| 1 |
<pre>Internet Engineering Task Force (IETF) S. Shepler, Ed. |
| 2 |
Request for Comments: 5661 Storspeed, Inc. |
| 3 |
Category: Standards Track M. Eisler, Ed. |
| 4 |
ISSN: 2070-1721 D. Noveck, Ed. |
| 5 |
NetApp |
| 6 |
January 2010 |
| 7 |
|
| 8 |
|
| 9 |
<span class="h1">Network File System (NFS) Version 4 Minor Version 1 Protocol</span> |
| 10 |
|
| 11 |
Abstract |
| 12 |
|
| 13 |
This document describes the Network File System (NFS) version 4 minor |
| 14 |
version 1, including features retained from the base protocol (NFS |
| 15 |
version 4 minor version 0, which is specified in <a href="./rfc3530">RFC 3530</a>) and |
| 16 |
protocol extensions made subsequently. Major extensions introduced |
| 17 |
in NFS version 4 minor version 1 include Sessions, Directory |
| 18 |
Delegations, and parallel NFS (pNFS). NFS version 4 minor version 1 |
| 19 |
has no dependencies on NFS version 4 minor version 0, and it is |
| 20 |
considered a separate protocol. Thus, this document neither updates |
| 21 |
nor obsoletes <a href="./rfc3530">RFC 3530</a>. NFS minor version 1 is deemed superior to |
| 22 |
NFS minor version 0 with no loss of functionality, and its use is |
| 23 |
preferred over version 0. Both NFS minor versions 0 and 1 can be |
| 24 |
used simultaneously on the same network, between the same client and |
| 25 |
server. |
| 26 |
|
| 27 |
Status of This Memo |
| 28 |
|
| 29 |
This is an Internet Standards Track document. |
| 30 |
|
| 31 |
This document is a product of the Internet Engineering Task Force |
| 32 |
(IETF). It represents the consensus of the IETF community. It has |
| 33 |
received public review and has been approved for publication by the |
| 34 |
Internet Engineering Steering Group (IESG). Further information on |
| 35 |
Internet Standards is available in <a href="./rfc5741#section-2">Section 2 of RFC 5741</a>. |
| 36 |
|
| 37 |
Information about the current status of this document, any errata, |
| 38 |
and how to provide feedback on it may be obtained at |
| 39 |
<a href="http://www.rfc-editor.org/info/rfc5661">http://www.rfc-editor.org/info/rfc5661</a>. |
| 40 |
|
| 41 |
|
| 42 |
|
| 43 |
|
| 44 |
|
| 45 |
|
| 46 |
|
| 47 |
|
| 48 |
|
| 49 |
|
| 50 |
|
| 51 |
|
| 52 |
<span class="grey">Shepler, et al. Standards Track [Page 1]</span></pre> |
| 53 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span> |
| 54 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 55 |
|
| 56 |
|
| 57 |
Copyright Notice |
| 58 |
|
| 59 |
Copyright (c) 2010 IETF Trust and the persons identified as the |
| 60 |
document authors. All rights reserved. |
| 61 |
|
| 62 |
This document is subject to <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and the IETF Trust's Legal |
| 63 |
Provisions Relating to IETF Documents |
| 64 |
(<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) in effect on the date of |
| 65 |
publication of this document. Please review these documents |
| 66 |
carefully, as they describe your rights and restrictions with respect |
| 67 |
to this document. Code Components extracted from this document must |
| 68 |
include Simplified BSD License text as described in Section 4.e of |
| 69 |
the Trust Legal Provisions and are provided without warranty as |
| 70 |
described in the Simplified BSD License. |
| 71 |
|
| 72 |
|
| 73 |
|
| 74 |
|
| 75 |
|
| 76 |
|
| 77 |
|
| 78 |
|
| 79 |
|
| 80 |
|
| 81 |
|
| 82 |
|
| 83 |
|
| 84 |
|
| 85 |
|
| 86 |
|
| 87 |
|
| 88 |
|
| 89 |
|
| 90 |
|
| 91 |
|
| 92 |
|
| 93 |
|
| 94 |
|
| 95 |
|
| 96 |
|
| 97 |
|
| 98 |
|
| 99 |
|
| 100 |
|
| 101 |
|
| 102 |
|
| 103 |
|
| 104 |
|
| 105 |
|
| 106 |
|
| 107 |
|
| 108 |
<span class="grey">Shepler, et al. Standards Track [Page 2]</span></pre> |
| 109 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span> |
| 110 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 111 |
|
| 112 |
|
| 113 |
Table of Contents |
| 114 |
|
| 115 |
<a href="#section-1">1</a>. Introduction ....................................................<a href="#page-9">9</a> |
| 116 |
<a href="#section-1.1">1.1</a>. The NFS Version 4 Minor Version 1 Protocol .................<a href="#page-9">9</a> |
| 117 |
<a href="#section-1.2">1.2</a>. Requirements Language ......................................<a href="#page-9">9</a> |
| 118 |
<a href="#section-1.3">1.3</a>. Scope of This Document .....................................<a href="#page-9">9</a> |
| 119 |
<a href="#section-1.4">1.4</a>. NFSv4 Goals ...............................................<a href="#page-10">10</a> |
| 120 |
<a href="#section-1.5">1.5</a>. NFSv4.1 Goals .............................................<a href="#page-10">10</a> |
| 121 |
<a href="#section-1.6">1.6</a>. General Definitions .......................................<a href="#page-11">11</a> |
| 122 |
<a href="#section-1.7">1.7</a>. Overview of NFSv4.1 Features ..............................<a href="#page-13">13</a> |
| 123 |
<a href="#section-1.8">1.8</a>. Differences from NFSv4.0 ..................................<a href="#page-17">17</a> |
| 124 |
<a href="#section-2">2</a>. Core Infrastructure ............................................<a href="#page-18">18</a> |
| 125 |
<a href="#section-2.1">2.1</a>. Introduction ..............................................<a href="#page-18">18</a> |
| 126 |
<a href="#section-2.2">2.2</a>. RPC and XDR ...............................................<a href="#page-19">19</a> |
| 127 |
<a href="#section-2.3">2.3</a>. COMPOUND and CB_COMPOUND ..................................<a href="#page-22">22</a> |
| 128 |
<a href="#section-2.4">2.4</a>. Client Identifiers and Client Owners ......................<a href="#page-23">23</a> |
| 129 |
<a href="#section-2.5">2.5</a>. Server Owners .............................................<a href="#page-28">28</a> |
| 130 |
<a href="#section-2.6">2.6</a>. Security Service Negotiation ..............................<a href="#page-29">29</a> |
| 131 |
<a href="#section-2.7">2.7</a>. Minor Versioning ..........................................<a href="#page-34">34</a> |
| 132 |
<a href="#section-2.8">2.8</a>. Non-RPC-Based Security Services ...........................<a href="#page-37">37</a> |
| 133 |
<a href="#section-2.9">2.9</a>. Transport Layers ..........................................<a href="#page-37">37</a> |
| 134 |
<a href="#section-2.10">2.10</a>. Session ..................................................<a href="#page-40">40</a> |
| 135 |
<a href="#section-3">3</a>. Protocol Constants and Data Types ..............................<a href="#page-86">86</a> |
| 136 |
<a href="#section-3.1">3.1</a>. Basic Constants ...........................................<a href="#page-86">86</a> |
| 137 |
<a href="#section-3.2">3.2</a>. Basic Data Types ..........................................<a href="#page-87">87</a> |
| 138 |
<a href="#section-3.3">3.3</a>. Structured Data Types .....................................<a href="#page-89">89</a> |
| 139 |
<a href="#section-4">4</a>. Filehandles ....................................................<a href="#page-97">97</a> |
| 140 |
<a href="#section-4.1">4.1</a>. Obtaining the First Filehandle ............................<a href="#page-98">98</a> |
| 141 |
<a href="#section-4.2">4.2</a>. Filehandle Types ..........................................<a href="#page-99">99</a> |
| 142 |
<a href="#section-4.3">4.3</a>. One Method of Constructing a Volatile Filehandle .........<a href="#page-101">101</a> |
| 143 |
<a href="#section-4.4">4.4</a>. Client Recovery from Filehandle Expiration ...............<a href="#page-102">102</a> |
| 144 |
<a href="#section-5">5</a>. File Attributes ...............................................<a href="#page-103">103</a> |
| 145 |
<a href="#section-5.1">5.1</a>. REQUIRED Attributes ......................................<a href="#page-104">104</a> |
| 146 |
<a href="#section-5.2">5.2</a>. RECOMMENDED Attributes ...................................<a href="#page-104">104</a> |
| 147 |
<a href="#section-5.3">5.3</a>. Named Attributes .........................................<a href="#page-105">105</a> |
| 148 |
<a href="#section-5.4">5.4</a>. Classification of Attributes .............................<a href="#page-106">106</a> |
| 149 |
<a href="#section-5.5">5.5</a>. Set-Only and Get-Only Attributes .........................<a href="#page-107">107</a> |
| 150 |
<a href="#section-5.6">5.6</a>. REQUIRED Attributes - List and Definition References .....<a href="#page-107">107</a> |
| 151 |
<a href="#section-5.7">5.7</a>. RECOMMENDED Attributes - List and Definition References ..108 |
| 152 |
<a href="#section-5.8">5.8</a>. Attribute Definitions ....................................<a href="#page-110">110</a> |
| 153 |
<a href="#section-5.9">5.9</a>. Interpreting owner and owner_group .......................<a href="#page-119">119</a> |
| 154 |
<a href="#section-5.10">5.10</a>. Character Case Attributes ...............................<a href="#page-121">121</a> |
| 155 |
<a href="#section-5.11">5.11</a>. Directory Notification Attributes .......................<a href="#page-121">121</a> |
| 156 |
<a href="#section-5.12">5.12</a>. pNFS Attribute Definitions ..............................<a href="#page-122">122</a> |
| 157 |
<a href="#section-5.13">5.13</a>. Retention Attributes ....................................<a href="#page-123">123</a> |
| 158 |
<a href="#section-6">6</a>. Access Control Attributes .....................................<a href="#page-126">126</a> |
| 159 |
<a href="#section-6.1">6.1</a>. Goals ....................................................<a href="#page-126">126</a> |
| 160 |
<a href="#section-6.2">6.2</a>. File Attributes Discussion ...............................<a href="#page-128">128</a> |
| 161 |
|
| 162 |
|
| 163 |
|
| 164 |
<span class="grey">Shepler, et al. Standards Track [Page 3]</span></pre> |
| 165 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span> |
| 166 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 167 |
|
| 168 |
|
| 169 |
<a href="#section-6.3">6.3</a>. Common Methods ...........................................<a href="#page-144">144</a> |
| 170 |
<a href="#section-6.4">6.4</a>. Requirements .............................................<a href="#page-147">147</a> |
| 171 |
<a href="#section-7">7</a>. Single-Server Namespace .......................................<a href="#page-153">153</a> |
| 172 |
<a href="#section-7.1">7.1</a>. Server Exports ...........................................<a href="#page-153">153</a> |
| 173 |
<a href="#section-7.2">7.2</a>. Browsing Exports .........................................<a href="#page-153">153</a> |
| 174 |
<a href="#section-7.3">7.3</a>. Server Pseudo File System ................................<a href="#page-154">154</a> |
| 175 |
<a href="#section-7.4">7.4</a>. Multiple Roots ...........................................<a href="#page-155">155</a> |
| 176 |
<a href="#section-7.5">7.5</a>. Filehandle Volatility ....................................<a href="#page-155">155</a> |
| 177 |
<a href="#section-7.6">7.6</a>. Exported Root ............................................<a href="#page-155">155</a> |
| 178 |
<a href="#section-7.7">7.7</a>. Mount Point Crossing .....................................<a href="#page-156">156</a> |
| 179 |
<a href="#section-7.8">7.8</a>. Security Policy and Namespace Presentation ...............<a href="#page-156">156</a> |
| 180 |
<a href="#section-8">8</a>. State Management ..............................................<a href="#page-157">157</a> |
| 181 |
<a href="#section-8.1">8.1</a>. Client and Session ID ....................................<a href="#page-158">158</a> |
| 182 |
<a href="#section-8.2">8.2</a>. Stateid Definition .......................................<a href="#page-158">158</a> |
| 183 |
<a href="#section-8.3">8.3</a>. Lease Renewal ............................................<a href="#page-167">167</a> |
| 184 |
<a href="#section-8.4">8.4</a>. Crash Recovery ...........................................<a href="#page-170">170</a> |
| 185 |
<a href="#section-8.5">8.5</a>. Server Revocation of Locks ...............................<a href="#page-181">181</a> |
| 186 |
<a href="#section-8.6">8.6</a>. Short and Long Leases ....................................<a href="#page-182">182</a> |
| 187 |
8.7. Clocks, Propagation Delay, and Calculating Lease |
| 188 |
Expiration ...............................................<a href="#page-182">182</a> |
| 189 |
<a href="#section-8.8">8.8</a>. Obsolete Locking Infrastructure from NFSv4.0 .............<a href="#page-183">183</a> |
| 190 |
<a href="#section-9">9</a>. File Locking and Share Reservations ...........................<a href="#page-184">184</a> |
| 191 |
<a href="#section-9.1">9.1</a>. Opens and Byte-Range Locks ...............................<a href="#page-184">184</a> |
| 192 |
<a href="#section-9.2">9.2</a>. Lock Ranges ..............................................<a href="#page-188">188</a> |
| 193 |
<a href="#section-9.3">9.3</a>. Upgrading and Downgrading Locks ..........................<a href="#page-188">188</a> |
| 194 |
<a href="#section-9.4">9.4</a>. Stateid Seqid Values and Byte-Range Locks ................<a href="#page-189">189</a> |
| 195 |
<a href="#section-9.5">9.5</a>. Issues with Multiple Open-Owners .........................<a href="#page-189">189</a> |
| 196 |
<a href="#section-9.6">9.6</a>. Blocking Locks ...........................................<a href="#page-190">190</a> |
| 197 |
<a href="#section-9.7">9.7</a>. Share Reservations .......................................<a href="#page-191">191</a> |
| 198 |
<a href="#section-9.8">9.8</a>. OPEN/CLOSE Operations ....................................<a href="#page-192">192</a> |
| 199 |
<a href="#section-9.9">9.9</a>. Open Upgrade and Downgrade ...............................<a href="#page-192">192</a> |
| 200 |
<a href="#section-9.10">9.10</a>. Parallel OPENs ..........................................<a href="#page-193">193</a> |
| 201 |
<a href="#section-9.11">9.11</a>. Reclaim of Open and Byte-Range Locks ....................<a href="#page-194">194</a> |
| 202 |
<a href="#section-10">10</a>. Client-Side Caching ..........................................<a href="#page-194">194</a> |
| 203 |
<a href="#section-10.1">10.1</a>. Performance Challenges for Client-Side Caching ..........<a href="#page-195">195</a> |
| 204 |
<a href="#section-10.2">10.2</a>. Delegation and Callbacks ................................<a href="#page-196">196</a> |
| 205 |
<a href="#section-10.3">10.3</a>. Data Caching ............................................<a href="#page-200">200</a> |
| 206 |
<a href="#section-10.4">10.4</a>. Open Delegation .........................................<a href="#page-205">205</a> |
| 207 |
<a href="#section-10.5">10.5</a>. Data Caching and Revocation .............................<a href="#page-216">216</a> |
| 208 |
<a href="#section-10.6">10.6</a>. Attribute Caching .......................................<a href="#page-218">218</a> |
| 209 |
<a href="#section-10.7">10.7</a>. Data and Metadata Caching and Memory Mapped Files .......<a href="#page-220">220</a> |
| 210 |
10.8. Name and Directory Caching without Directory |
| 211 |
Delegations .............................................<a href="#page-222">222</a> |
| 212 |
<a href="#section-10.9">10.9</a>. Directory Delegations ...................................<a href="#page-225">225</a> |
| 213 |
<a href="#section-11">11</a>. Multi-Server Namespace .......................................<a href="#page-228">228</a> |
| 214 |
<a href="#section-11.1">11.1</a>. Location Attributes .....................................<a href="#page-228">228</a> |
| 215 |
<a href="#section-11.2">11.2</a>. File System Presence or Absence .........................<a href="#page-229">229</a> |
| 216 |
<a href="#section-11.3">11.3</a>. Getting Attributes for an Absent File System ............<a href="#page-230">230</a> |
| 217 |
|
| 218 |
|
| 219 |
|
| 220 |
<span class="grey">Shepler, et al. Standards Track [Page 4]</span></pre> |
| 221 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span> |
| 222 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 223 |
|
| 224 |
|
| 225 |
<a href="#section-11.4">11.4</a>. Uses of Location Information ............................<a href="#page-232">232</a> |
| 226 |
<a href="#section-11.5">11.5</a>. Location Entries and Server Identity ....................<a href="#page-236">236</a> |
| 227 |
<a href="#section-11.6">11.6</a>. Additional Client-Side Considerations ...................<a href="#page-237">237</a> |
| 228 |
<a href="#section-11.7">11.7</a>. Effecting File System Transitions .......................<a href="#page-238">238</a> |
| 229 |
<a href="#section-11.8">11.8</a>. Effecting File System Referrals .........................<a href="#page-251">251</a> |
| 230 |
<a href="#section-11.9">11.9</a>. The Attribute fs_locations ..............................<a href="#page-258">258</a> |
| 231 |
<a href="#section-11.10">11.10</a>. The Attribute fs_locations_info ........................<a href="#page-261">261</a> |
| 232 |
<a href="#section-11.11">11.11</a>. The Attribute fs_status ................................<a href="#page-273">273</a> |
| 233 |
<a href="#section-12">12</a>. Parallel NFS (pNFS) ..........................................<a href="#page-277">277</a> |
| 234 |
<a href="#section-12.1">12.1</a>. Introduction ............................................<a href="#page-277">277</a> |
| 235 |
<a href="#section-12.2">12.2</a>. pNFS Definitions ........................................<a href="#page-278">278</a> |
| 236 |
<a href="#section-12.3">12.3</a>. pNFS Operations .........................................<a href="#page-284">284</a> |
| 237 |
<a href="#section-12.4">12.4</a>. pNFS Attributes .........................................<a href="#page-285">285</a> |
| 238 |
<a href="#section-12.5">12.5</a>. Layout Semantics ........................................<a href="#page-285">285</a> |
| 239 |
<a href="#section-12.6">12.6</a>. pNFS Mechanics ..........................................<a href="#page-300">300</a> |
| 240 |
<a href="#section-12.7">12.7</a>. Recovery ................................................<a href="#page-302">302</a> |
| 241 |
<a href="#section-12.8">12.8</a>. Metadata and Storage Device Roles .......................<a href="#page-307">307</a> |
| 242 |
<a href="#section-12.9">12.9</a>. Security Considerations for pNFS ........................<a href="#page-307">307</a> |
| 243 |
<a href="#section-13">13</a>. NFSv4.1 as a Storage Protocol in pNFS: the File Layout Type ..309 |
| 244 |
<a href="#section-13.1">13.1</a>. Client ID and Session Considerations ....................<a href="#page-309">309</a> |
| 245 |
<a href="#section-13.2">13.2</a>. File Layout Definitions .................................<a href="#page-312">312</a> |
| 246 |
<a href="#section-13.3">13.3</a>. File Layout Data Types ..................................<a href="#page-312">312</a> |
| 247 |
<a href="#section-13.4">13.4</a>. Interpreting the File Layout ............................<a href="#page-317">317</a> |
| 248 |
<a href="#section-13.5">13.5</a>. Data Server Multipathing ................................<a href="#page-324">324</a> |
| 249 |
<a href="#section-13.6">13.6</a>. Operations Sent to NFSv4.1 Data Servers .................<a href="#page-325">325</a> |
| 250 |
<a href="#section-13.7">13.7</a>. COMMIT through Metadata Server ..........................<a href="#page-327">327</a> |
| 251 |
<a href="#section-13.8">13.8</a>. The Layout Iomode .......................................<a href="#page-328">328</a> |
| 252 |
<a href="#section-13.9">13.9</a>. Metadata and Data Server State Coordination .............<a href="#page-329">329</a> |
| 253 |
<a href="#section-13.10">13.10</a>. Data Server Component File Size ........................<a href="#page-332">332</a> |
| 254 |
<a href="#section-13.11">13.11</a>. Layout Revocation and Fencing ..........................<a href="#page-333">333</a> |
| 255 |
<a href="#section-13.12">13.12</a>. Security Considerations for the File Layout Type .......<a href="#page-334">334</a> |
| 256 |
<a href="#section-14">14</a>. Internationalization .........................................<a href="#page-334">334</a> |
| 257 |
<a href="#section-14.1">14.1</a>. Stringprep profile for the utf8str_cs type ..............<a href="#page-336">336</a> |
| 258 |
<a href="#section-14.2">14.2</a>. Stringprep profile for the utf8str_cis type .............<a href="#page-337">337</a> |
| 259 |
<a href="#section-14.3">14.3</a>. Stringprep profile for the utf8str_mixed type ...........<a href="#page-338">338</a> |
| 260 |
<a href="#section-14.4">14.4</a>. UTF-8 Capabilities ......................................<a href="#page-340">340</a> |
| 261 |
<a href="#section-14.5">14.5</a>. UTF-8 Related Errors ....................................<a href="#page-340">340</a> |
| 262 |
<a href="#section-15">15</a>. Error Values .................................................<a href="#page-341">341</a> |
| 263 |
<a href="#section-15.1">15.1</a>. Error Definitions .......................................<a href="#page-341">341</a> |
| 264 |
<a href="#section-15.2">15.2</a>. Operations and Their Valid Errors .......................<a href="#page-361">361</a> |
| 265 |
<a href="#section-15.3">15.3</a>. Callback Operations and Their Valid Errors ..............<a href="#page-376">376</a> |
| 266 |
<a href="#section-15.4">15.4</a>. Errors and the Operations That Use Them .................<a href="#page-379">379</a> |
| 267 |
<a href="#section-16">16</a>. NFSv4.1 Procedures ...........................................<a href="#page-391">391</a> |
| 268 |
<a href="#section-16.1">16.1</a>. Procedure 0: NULL - No Operation ........................<a href="#page-392">392</a> |
| 269 |
<a href="#section-16.2">16.2</a>. Procedure 1: COMPOUND - Compound Operations .............<a href="#page-392">392</a> |
| 270 |
<a href="#section-17">17</a>. Operations: REQUIRED, RECOMMENDED, or OPTIONAL ...............<a href="#page-403">403</a> |
| 271 |
<a href="#section-18">18</a>. NFSv4.1 Operations ...........................................<a href="#page-407">407</a> |
| 272 |
<a href="#section-18.1">18.1</a>. Operation 3: ACCESS - Check Access Rights ...............<a href="#page-407">407</a> |
| 273 |
|
| 274 |
|
| 275 |
|
| 276 |
<span class="grey">Shepler, et al. Standards Track [Page 5]</span></pre> |
| 277 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-6" ></span> |
| 278 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 279 |
|
| 280 |
|
| 281 |
<a href="#section-18.2">18.2</a>. Operation 4: CLOSE - Close File .........................<a href="#page-413">413</a> |
| 282 |
<a href="#section-18.3">18.3</a>. Operation 5: COMMIT - Commit Cached Data ................<a href="#page-414">414</a> |
| 283 |
<a href="#section-18.4">18.4</a>. Operation 6: CREATE - Create a Non-Regular File Object ..417 |
| 284 |
18.5. Operation 7: DELEGPURGE - Purge Delegations |
| 285 |
Awaiting Recovery .......................................<a href="#page-419">419</a> |
| 286 |
<a href="#section-18.6">18.6</a>. Operation 8: DELEGRETURN - Return Delegation ............<a href="#page-420">420</a> |
| 287 |
<a href="#section-18.7">18.7</a>. Operation 9: GETATTR - Get Attributes ...................<a href="#page-421">421</a> |
| 288 |
<a href="#section-18.8">18.8</a>. Operation 10: GETFH - Get Current Filehandle ............<a href="#page-423">423</a> |
| 289 |
<a href="#section-18.9">18.9</a>. Operation 11: LINK - Create Link to a File ..............<a href="#page-424">424</a> |
| 290 |
<a href="#section-18.10">18.10</a>. Operation 12: LOCK - Create Lock .......................<a href="#page-426">426</a> |
| 291 |
<a href="#section-18.11">18.11</a>. Operation 13: LOCKT - Test for Lock ....................<a href="#page-430">430</a> |
| 292 |
<a href="#section-18.12">18.12</a>. Operation 14: LOCKU - Unlock File ......................<a href="#page-432">432</a> |
| 293 |
<a href="#section-18.13">18.13</a>. Operation 15: LOOKUP - Lookup Filename .................<a href="#page-433">433</a> |
| 294 |
<a href="#section-18.14">18.14</a>. Operation 16: LOOKUPP - Lookup Parent Directory ........<a href="#page-435">435</a> |
| 295 |
18.15. Operation 17: NVERIFY - Verify Difference in |
| 296 |
Attributes .............................................<a href="#page-436">436</a> |
| 297 |
<a href="#section-18.16">18.16</a>. Operation 18: OPEN - Open a Regular File ...............<a href="#page-437">437</a> |
| 298 |
18.17. Operation 19: OPENATTR - Open Named Attribute |
| 299 |
Directory ..............................................<a href="#page-458">458</a> |
| 300 |
18.18. Operation 21: OPEN_DOWNGRADE - Reduce Open File |
| 301 |
Access .................................................<a href="#page-459">459</a> |
| 302 |
<a href="#section-18.19">18.19</a>. Operation 22: PUTFH - Set Current Filehandle ...........<a href="#page-461">461</a> |
| 303 |
<a href="#section-18.20">18.20</a>. Operation 23: PUTPUBFH - Set Public Filehandle .........<a href="#page-461">461</a> |
| 304 |
<a href="#section-18.21">18.21</a>. Operation 24: PUTROOTFH - Set Root Filehandle ..........<a href="#page-463">463</a> |
| 305 |
<a href="#section-18.22">18.22</a>. Operation 25: READ - Read from File ....................<a href="#page-464">464</a> |
| 306 |
<a href="#section-18.23">18.23</a>. Operation 26: READDIR - Read Directory .................<a href="#page-466">466</a> |
| 307 |
<a href="#section-18.24">18.24</a>. Operation 27: READLINK - Read Symbolic Link ............<a href="#page-469">469</a> |
| 308 |
<a href="#section-18.25">18.25</a>. Operation 28: REMOVE - Remove File System Object .......<a href="#page-470">470</a> |
| 309 |
<a href="#section-18.26">18.26</a>. Operation 29: RENAME - Rename Directory Entry ..........<a href="#page-473">473</a> |
| 310 |
<a href="#section-18.27">18.27</a>. Operation 31: RESTOREFH - Restore Saved Filehandle .....<a href="#page-477">477</a> |
| 311 |
<a href="#section-18.28">18.28</a>. Operation 32: SAVEFH - Save Current Filehandle .........<a href="#page-478">478</a> |
| 312 |
<a href="#section-18.29">18.29</a>. Operation 33: SECINFO - Obtain Available Security ......<a href="#page-479">479</a> |
| 313 |
<a href="#section-18.30">18.30</a>. Operation 34: SETATTR - Set Attributes .................<a href="#page-482">482</a> |
| 314 |
<a href="#section-18.31">18.31</a>. Operation 37: VERIFY - Verify Same Attributes ..........<a href="#page-485">485</a> |
| 315 |
<a href="#section-18.32">18.32</a>. Operation 38: WRITE - Write to File ....................<a href="#page-486">486</a> |
| 316 |
<a href="#section-18.33">18.33</a>. Operation 40: BACKCHANNEL_CTL - Backchannel Control ....<a href="#page-491">491</a> |
| 317 |
18.34. Operation 41: BIND_CONN_TO_SESSION - Associate |
| 318 |
Connection with Session ................................<a href="#page-492">492</a> |
| 319 |
<a href="#section-18.35">18.35</a>. Operation 42: EXCHANGE_ID - Instantiate Client ID ......<a href="#page-495">495</a> |
| 320 |
18.36. Operation 43: CREATE_SESSION - Create New |
| 321 |
Session and Confirm Client ID ..........................<a href="#page-513">513</a> |
| 322 |
<a href="#section-18.37">18.37</a>. Operation 44: DESTROY_SESSION - Destroy a Session ......<a href="#page-523">523</a> |
| 323 |
18.38. Operation 45: FREE_STATEID - Free Stateid with |
| 324 |
No Locks ...............................................<a href="#page-525">525</a> |
| 325 |
18.39. Operation 46: GET_DIR_DELEGATION - Get a |
| 326 |
Directory Delegation ...................................<a href="#page-526">526</a> |
| 327 |
<a href="#section-18.40">18.40</a>. Operation 47: GETDEVICEINFO - Get Device Information ...<a href="#page-530">530</a> |
| 328 |
18.41. Operation 48: GETDEVICELIST - Get All Device |
| 329 |
|
| 330 |
|
| 331 |
|
| 332 |
<span class="grey">Shepler, et al. Standards Track [Page 6]</span></pre> |
| 333 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-7" ></span> |
| 334 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 335 |
|
| 336 |
|
| 337 |
Mappings for a File System .............................<a href="#page-533">533</a> |
| 338 |
18.42. Operation 49: LAYOUTCOMMIT - Commit Writes Made |
| 339 |
Using a Layout .........................................<a href="#page-534">534</a> |
| 340 |
<a href="#section-18.43">18.43</a>. Operation 50: LAYOUTGET - Get Layout Information .......<a href="#page-538">538</a> |
| 341 |
18.44. Operation 51: LAYOUTRETURN - Release Layout |
| 342 |
Information ............................................<a href="#page-547">547</a> |
| 343 |
18.45. Operation 52: SECINFO_NO_NAME - Get Security on |
| 344 |
Unnamed Object .........................................<a href="#page-552">552</a> |
| 345 |
18.46. Operation 53: SEQUENCE - Supply Per-Procedure |
| 346 |
Sequencing and Control .................................<a href="#page-553">553</a> |
| 347 |
<a href="#section-18.47">18.47</a>. Operation 54: SET_SSV - Update SSV for a Client ID .....<a href="#page-559">559</a> |
| 348 |
18.48. Operation 55: TEST_STATEID - Test Stateids for |
| 349 |
Validity ...............................................<a href="#page-561">561</a> |
| 350 |
<a href="#section-18.49">18.49</a>. Operation 56: WANT_DELEGATION - Request Delegation .....<a href="#page-563">563</a> |
| 351 |
<a href="#section-18.50">18.50</a>. Operation 57: DESTROY_CLIENTID - Destroy a Client ID ...<a href="#page-566">566</a> |
| 352 |
18.51. Operation 58: RECLAIM_COMPLETE - Indicates |
| 353 |
Reclaims Finished ......................................<a href="#page-567">567</a> |
| 354 |
<a href="#section-18.52">18.52</a>. Operation 10044: ILLEGAL - Illegal Operation ...........<a href="#page-569">569</a> |
| 355 |
<a href="#section-19">19</a>. NFSv4.1 Callback Procedures ..................................<a href="#page-570">570</a> |
| 356 |
<a href="#section-19.1">19.1</a>. Procedure 0: CB_NULL - No Operation .....................<a href="#page-570">570</a> |
| 357 |
<a href="#section-19.2">19.2</a>. Procedure 1: CB_COMPOUND - Compound Operations ..........<a href="#page-571">571</a> |
| 358 |
<a href="#section-20">20</a>. NFSv4.1 Callback Operations ..................................<a href="#page-574">574</a> |
| 359 |
<a href="#section-20.1">20.1</a>. Operation 3: CB_GETATTR - Get Attributes ................<a href="#page-574">574</a> |
| 360 |
<a href="#section-20.2">20.2</a>. Operation 4: CB_RECALL - Recall a Delegation ............<a href="#page-575">575</a> |
| 361 |
20.3. Operation 5: CB_LAYOUTRECALL - Recall Layout |
| 362 |
from Client .............................................<a href="#page-576">576</a> |
| 363 |
20.4. Operation 6: CB_NOTIFY - Notify Client of |
| 364 |
Directory Changes .......................................<a href="#page-580">580</a> |
| 365 |
20.5. Operation 7: CB_PUSH_DELEG - Offer Previously |
| 366 |
Requested Delegation to Client ..........................<a href="#page-583">583</a> |
| 367 |
20.6. Operation 8: CB_RECALL_ANY - Keep Any N |
| 368 |
Recallable Objects ......................................<a href="#page-584">584</a> |
| 369 |
20.7. Operation 9: CB_RECALLABLE_OBJ_AVAIL - Signal |
| 370 |
Resources for Recallable Objects ........................<a href="#page-588">588</a> |
| 371 |
20.8. Operation 10: CB_RECALL_SLOT - Change Flow |
| 372 |
Control Limits ..........................................<a href="#page-588">588</a> |
| 373 |
20.9. Operation 11: CB_SEQUENCE - Supply Backchannel |
| 374 |
Sequencing and Control ..................................<a href="#page-589">589</a> |
| 375 |
20.10. Operation 12: CB_WANTS_CANCELLED - Cancel |
| 376 |
Pending Delegation Wants ...............................<a href="#page-592">592</a> |
| 377 |
20.11. Operation 13: CB_NOTIFY_LOCK - Notify Client of |
| 378 |
Possible Lock Availability .............................<a href="#page-593">593</a> |
| 379 |
20.12. Operation 14: CB_NOTIFY_DEVICEID - Notify |
| 380 |
Client of Device ID Changes ............................<a href="#page-594">594</a> |
| 381 |
20.13. Operation 10044: CB_ILLEGAL - Illegal Callback |
| 382 |
Operation ..............................................<a href="#page-596">596</a> |
| 383 |
<a href="#section-21">21</a>. Security Considerations ......................................<a href="#page-597">597</a> |
| 384 |
<a href="#section-22">22</a>. IANA Considerations ..........................................<a href="#page-598">598</a> |
| 385 |
|
| 386 |
|
| 387 |
|
| 388 |
<span class="grey">Shepler, et al. Standards Track [Page 7]</span></pre> |
| 389 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-8" ></span> |
| 390 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 391 |
|
| 392 |
|
| 393 |
<a href="#section-22.1">22.1</a>. Named Attribute Definitions .............................<a href="#page-598">598</a> |
| 394 |
<a href="#section-22.2">22.2</a>. Device ID Notifications .................................<a href="#page-600">600</a> |
| 395 |
<a href="#section-22.3">22.3</a>. Object Recall Types .....................................<a href="#page-601">601</a> |
| 396 |
<a href="#section-22.4">22.4</a>. Layout Types ............................................<a href="#page-603">603</a> |
| 397 |
<a href="#section-22.5">22.5</a>. Path Variable Definitions ...............................<a href="#page-606">606</a> |
| 398 |
<a href="#section-23">23</a>. References ...................................................<a href="#page-609">609</a> |
| 399 |
<a href="#section-23.1">23.1</a>. Normative References ....................................<a href="#page-609">609</a> |
| 400 |
<a href="#section-23.2">23.2</a>. Informative References ..................................<a href="#page-612">612</a> |
| 401 |
<a href="#appendix-A">Appendix A</a>. Acknowledgments ....................................<a href="#page-615">615</a> |
| 402 |
|
| 403 |
|
| 404 |
|
| 405 |
|
| 406 |
|
| 407 |
|
| 408 |
|
| 409 |
|
| 410 |
|
| 411 |
|
| 412 |
|
| 413 |
|
| 414 |
|
| 415 |
|
| 416 |
|
| 417 |
|
| 418 |
|
| 419 |
|
| 420 |
|
| 421 |
|
| 422 |
|
| 423 |
|
| 424 |
|
| 425 |
|
| 426 |
|
| 427 |
|
| 428 |
|
| 429 |
|
| 430 |
|
| 431 |
|
| 432 |
|
| 433 |
|
| 434 |
|
| 435 |
|
| 436 |
|
| 437 |
|
| 438 |
|
| 439 |
|
| 440 |
|
| 441 |
|
| 442 |
|
| 443 |
|
| 444 |
<span class="grey">Shepler, et al. Standards Track [Page 8]</span></pre> |
| 445 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-9" ></span> |
| 446 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 447 |
|
| 448 |
|
| 449 |
<span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span> |
| 450 |
|
| 451 |
<span class="h3"><a class="selflink" id="section-1.1" href="#section-1.1">1.1</a>. The NFS Version 4 Minor Version 1 Protocol</span> |
| 452 |
|
| 453 |
The NFS version 4 minor version 1 (NFSv4.1) protocol is the second |
| 454 |
minor version of the NFS version 4 (NFSv4) protocol. The first minor |
| 455 |
version, NFSv4.0, is described in [<a href="#ref-30" title=""Network File System (NFS) version 4 Protocol"">30</a>]. It generally follows the |
| 456 |
guidelines for minor versioning that are listed in Section 10 of <a href="./rfc3530">RFC</a> |
| 457 |
<a href="./rfc3530">3530</a>. However, it diverges from guidelines 11 ("a client and server |
| 458 |
that support minor version X must support minor versions 0 through |
| 459 |
X-1") and 12 ("no new features may be introduced as mandatory in a |
| 460 |
minor version"). These divergences are due to the introduction of |
| 461 |
the sessions model for managing non-idempotent operations and the |
| 462 |
RECLAIM_COMPLETE operation. These two new features are |
| 463 |
infrastructural in nature and simplify implementation of existing and |
| 464 |
other new features. Making them anything but REQUIRED would add |
| 465 |
undue complexity to protocol definition and implementation. NFSv4.1 |
| 466 |
accordingly updates the minor versioning guidelines (<a href="#section-2.7">Section 2.7</a>). |
| 467 |
|
| 468 |
As a minor version, NFSv4.1 is consistent with the overall goals for |
| 469 |
NFSv4, but extends the protocol so as to better meet those goals, |
| 470 |
based on experiences with NFSv4.0. In addition, NFSv4.1 has adopted |
| 471 |
some additional goals, which motivate some of the major extensions in |
| 472 |
NFSv4.1. |
| 473 |
|
| 474 |
<span class="h3"><a class="selflink" id="section-1.2" href="#section-1.2">1.2</a>. Requirements Language</span> |
| 475 |
|
| 476 |
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |
| 477 |
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |
| 478 |
document are to be interpreted as described in <a href="./rfc2119">RFC 2119</a> [<a href="#ref-1" title=""Key words for use in RFCs to Indicate Requirement Levels"">1</a>]. |
| 479 |
|
| 480 |
<span class="h3"><a class="selflink" id="section-1.3" href="#section-1.3">1.3</a>. Scope of This Document</span> |
| 481 |
|
| 482 |
This document describes the NFSv4.1 protocol. With respect to |
| 483 |
NFSv4.0, this document does not: |
| 484 |
|
| 485 |
o describe the NFSv4.0 protocol, except where needed to contrast |
| 486 |
with NFSv4.1. |
| 487 |
|
| 488 |
o modify the specification of the NFSv4.0 protocol. |
| 489 |
|
| 490 |
o clarify the NFSv4.0 protocol. |
| 491 |
|
| 492 |
|
| 493 |
|
| 494 |
|
| 495 |
|
| 496 |
|
| 497 |
|
| 498 |
|
| 499 |
|
| 500 |
<span class="grey">Shepler, et al. Standards Track [Page 9]</span></pre> |
| 501 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-10" ></span> |
| 502 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 503 |
|
| 504 |
|
| 505 |
<span class="h3"><a class="selflink" id="section-1.4" href="#section-1.4">1.4</a>. NFSv4 Goals</span> |
| 506 |
|
| 507 |
The NFSv4 protocol is a further revision of the NFS protocol defined |
| 508 |
already by NFSv3 [<a href="#ref-31" title=""NFS Version 3 Protocol Specification"">31</a>]. It retains the essential characteristics of |
| 509 |
previous versions: easy recovery; independence of transport |
| 510 |
protocols, operating systems, and file systems; simplicity; and good |
| 511 |
performance. NFSv4 has the following goals: |
| 512 |
|
| 513 |
o Improved access and good performance on the Internet |
| 514 |
|
| 515 |
The protocol is designed to transit firewalls easily, perform well |
| 516 |
where latency is high and bandwidth is low, and scale to very |
| 517 |
large numbers of clients per server. |
| 518 |
|
| 519 |
o Strong security with negotiation built into the protocol |
| 520 |
|
| 521 |
The protocol builds on the work of the ONCRPC working group in |
| 522 |
supporting the RPCSEC_GSS protocol. Additionally, the NFSv4.1 |
| 523 |
protocol provides a mechanism to allow clients and servers the |
| 524 |
ability to negotiate security and require clients and servers to |
| 525 |
support a minimal set of security schemes. |
| 526 |
|
| 527 |
o Good cross-platform interoperability |
| 528 |
|
| 529 |
The protocol features a file system model that provides a useful, |
| 530 |
common set of features that does not unduly favor one file system |
| 531 |
or operating system over another. |
| 532 |
|
| 533 |
o Designed for protocol extensions |
| 534 |
|
| 535 |
The protocol is designed to accept standard extensions within a |
| 536 |
framework that enables and encourages backward compatibility. |
| 537 |
|
| 538 |
<span class="h3"><a class="selflink" id="section-1.5" href="#section-1.5">1.5</a>. NFSv4.1 Goals</span> |
| 539 |
|
| 540 |
NFSv4.1 has the following goals, within the framework established by |
| 541 |
the overall NFSv4 goals. |
| 542 |
|
| 543 |
o To correct significant structural weaknesses and oversights |
| 544 |
discovered in the base protocol. |
| 545 |
|
| 546 |
o To add clarity and specificity to areas left unaddressed or not |
| 547 |
addressed in sufficient detail in the base protocol. However, as |
| 548 |
stated in <a href="#section-1.3">Section 1.3</a>, it is not a goal to clarify the NFSv4.0 |
| 549 |
protocol in the NFSv4.1 specification. |
| 550 |
|
| 551 |
o To add specific features based on experience with the existing |
| 552 |
protocol and recent industry developments. |
| 553 |
|
| 554 |
|
| 555 |
|
| 556 |
<span class="grey">Shepler, et al. Standards Track [Page 10]</span></pre> |
| 557 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-11" ></span> |
| 558 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 559 |
|
| 560 |
|
| 561 |
o To provide protocol support to take advantage of clustered server |
| 562 |
deployments including the ability to provide scalable parallel |
| 563 |
access to files distributed among multiple servers. |
| 564 |
|
| 565 |
<span class="h3"><a class="selflink" id="section-1.6" href="#section-1.6">1.6</a>. General Definitions</span> |
| 566 |
|
| 567 |
The following definitions provide an appropriate context for the |
| 568 |
reader. |
| 569 |
|
| 570 |
Byte: In this document, a byte is an octet, i.e., a datum exactly 8 |
| 571 |
bits in length. |
| 572 |
|
| 573 |
Client: The client is the entity that accesses the NFS server's |
| 574 |
resources. The client may be an application that contains the |
| 575 |
logic to access the NFS server directly. The client may also be |
| 576 |
the traditional operating system client that provides remote file |
| 577 |
system services for a set of applications. |
| 578 |
|
| 579 |
A client is uniquely identified by a client owner. |
| 580 |
|
| 581 |
With reference to byte-range locking, the client is also the |
| 582 |
entity that maintains a set of locks on behalf of one or more |
| 583 |
applications. This client is responsible for crash or failure |
| 584 |
recovery for those locks it manages. |
| 585 |
|
| 586 |
Note that multiple clients may share the same transport and |
| 587 |
connection and multiple clients may exist on the same network |
| 588 |
node. |
| 589 |
|
| 590 |
Client ID: The client ID is a 64-bit quantity used as a unique, |
| 591 |
short-hand reference to a client-supplied verifier and client |
| 592 |
owner. The server is responsible for supplying the client ID. |
| 593 |
|
| 594 |
Client Owner: The client owner is a unique string, opaque to the |
| 595 |
server, that identifies a client. Multiple network connections |
| 596 |
and source network addresses originating from those connections |
| 597 |
may share a client owner. The server is expected to treat |
| 598 |
requests from connections with the same client owner as coming |
| 599 |
from the same client. |
| 600 |
|
| 601 |
File System: The file system is the collection of objects on a |
| 602 |
server (as identified by the major identifier of a server owner, |
| 603 |
which is defined later in this section) that share the same fsid |
| 604 |
attribute (see <a href="#section-5.8.1.9">Section 5.8.1.9</a>). |
| 605 |
|
| 606 |
|
| 607 |
|
| 608 |
|
| 609 |
|
| 610 |
|
| 611 |
|
| 612 |
<span class="grey">Shepler, et al. Standards Track [Page 11]</span></pre> |
| 613 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-12" ></span> |
| 614 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 615 |
|
| 616 |
|
| 617 |
Lease: A lease is an interval of time defined by the server for |
| 618 |
which the client is irrevocably granted locks. At the end of a |
| 619 |
lease period, locks may be revoked if the lease has not been |
| 620 |
extended. A lock must be revoked if a conflicting lock has been |
| 621 |
granted after the lease interval. |
| 622 |
|
| 623 |
A server grants a client a single lease for all state. |
| 624 |
|
| 625 |
Lock: The term "lock" is used to refer to byte-range (in UNIX |
| 626 |
environments, also known as record) locks, share reservations, |
| 627 |
delegations, or layouts unless specifically stated otherwise. |
| 628 |
|
| 629 |
Secret State Verifier (SSV): The SSV is a unique secret key shared |
| 630 |
between a client and server. The SSV serves as the secret key for |
| 631 |
an internal (that is, internal to NFSv4.1) Generic Security |
| 632 |
Services (GSS) mechanism (the SSV GSS mechanism; see |
| 633 |
<a href="#section-2.10.9">Section 2.10.9</a>). The SSV GSS mechanism uses the SSV to compute |
| 634 |
message integrity code (MIC) and Wrap tokens. See |
| 635 |
<a href="#section-2.10.8.3">Section 2.10.8.3</a> for more details on how NFSv4.1 uses the SSV and |
| 636 |
the SSV GSS mechanism. |
| 637 |
|
| 638 |
Server: The Server is the entity responsible for coordinating client |
| 639 |
access to a set of file systems and is identified by a server |
| 640 |
owner. A server can span multiple network addresses. |
| 641 |
|
| 642 |
Server Owner: The server owner identifies the server to the client. |
| 643 |
The server owner consists of a major identifier and a minor |
| 644 |
identifier. When the client has two connections each to a peer |
| 645 |
with the same major identifier, the client assumes that both peers |
| 646 |
are the same server (the server namespace is the same via each |
| 647 |
connection) and that lock state is sharable across both |
| 648 |
connections. When each peer has both the same major and minor |
| 649 |
identifiers, the client assumes that each connection might be |
| 650 |
associable with the same session. |
| 651 |
|
| 652 |
Stable Storage: Stable storage is storage from which data stored by |
| 653 |
an NFSv4.1 server can be recovered without data loss from multiple |
| 654 |
power failures (including cascading power failures, that is, |
| 655 |
several power failures in quick succession), operating system |
| 656 |
failures, and/or hardware failure of components other than the |
| 657 |
storage medium itself (such as disk, nonvolatile RAM, flash |
| 658 |
memory, etc.). |
| 659 |
|
| 660 |
Some examples of stable storage that are allowable for an NFS |
| 661 |
server include: |
| 662 |
|
| 663 |
|
| 664 |
|
| 665 |
|
| 666 |
|
| 667 |
|
| 668 |
<span class="grey">Shepler, et al. Standards Track [Page 12]</span></pre> |
| 669 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-13" ></span> |
| 670 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 671 |
|
| 672 |
|
| 673 |
1. Media commit of data; that is, the modified data has been |
| 674 |
successfully written to the disk media, for example, the disk |
| 675 |
platter. |
| 676 |
|
| 677 |
2. An immediate reply disk drive with battery-backed, on-drive |
| 678 |
intermediate storage or uninterruptible power system (UPS). |
| 679 |
|
| 680 |
3. Server commit of data with battery-backed intermediate storage |
| 681 |
and recovery software. |
| 682 |
|
| 683 |
4. Cache commit with uninterruptible power system (UPS) and |
| 684 |
recovery software. |
| 685 |
|
| 686 |
Stateid: A stateid is a 128-bit quantity returned by a server that |
| 687 |
uniquely defines the open and locking states provided by the |
| 688 |
server for a specific open-owner or lock-owner/open-owner pair for |
| 689 |
a specific file and type of lock. |
| 690 |
|
| 691 |
Verifier: A verifier is a 64-bit quantity generated by the client |
| 692 |
that the server can use to determine if the client has restarted |
| 693 |
and lost all previous lock state. |
| 694 |
|
| 695 |
<span class="h3"><a class="selflink" id="section-1.7" href="#section-1.7">1.7</a>. Overview of NFSv4.1 Features</span> |
| 696 |
|
| 697 |
The major features of the NFSv4.1 protocol will be reviewed in brief. |
| 698 |
This will be done to provide an appropriate context for both the |
| 699 |
reader who is familiar with the previous versions of the NFS protocol |
| 700 |
and the reader who is new to the NFS protocols. For the reader new |
| 701 |
to the NFS protocols, there is still a set of fundamental knowledge |
| 702 |
that is expected. The reader should be familiar with the External |
| 703 |
Data Representation (XDR) and Remote Procedure Call (RPC) protocols |
| 704 |
as described in [<a href="#ref-2" title=""XDR: External Data Representation Standard"">2</a>] and [<a href="#ref-3" title=""RPC: Remote Procedure Call Protocol Specification Version 2"">3</a>]. A basic knowledge of file systems and |
| 705 |
distributed file systems is expected as well. |
| 706 |
|
| 707 |
In general, this specification of NFSv4.1 will not distinguish those |
| 708 |
features added in minor version 1 from those present in the base |
| 709 |
protocol but will treat NFSv4.1 as a unified whole. See <a href="#section-1.8">Section 1.8</a> |
| 710 |
for a summary of the differences between NFSv4.0 and NFSv4.1. |
| 711 |
|
| 712 |
<span class="h4"><a class="selflink" id="section-1.7.1" href="#section-1.7.1">1.7.1</a>. RPC and Security</span> |
| 713 |
|
| 714 |
As with previous versions of NFS, the External Data Representation |
| 715 |
(XDR) and Remote Procedure Call (RPC) mechanisms used for the NFSv4.1 |
| 716 |
protocol are those defined in [<a href="#ref-2" title=""XDR: External Data Representation Standard"">2</a>] and [<a href="#ref-3" title=""RPC: Remote Procedure Call Protocol Specification Version 2"">3</a>]. To meet end-to-end |
| 717 |
security requirements, the RPCSEC_GSS framework [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>] is used to extend |
| 718 |
the basic RPC security. With the use of RPCSEC_GSS, various |
| 719 |
mechanisms can be provided to offer authentication, integrity, and |
| 720 |
|
| 721 |
|
| 722 |
|
| 723 |
|
| 724 |
<span class="grey">Shepler, et al. Standards Track [Page 13]</span></pre> |
| 725 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-14" ></span> |
| 726 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 727 |
|
| 728 |
|
| 729 |
privacy to the NFSv4 protocol. Kerberos V5 is used as described in |
| 730 |
[<a href="#ref-5" title=""The Kerberos Version 5 Generic Security Service Application Program Interface (GSS- API) Mechanism Version 2"">5</a>] to provide one security framework. With the use of RPCSEC_GSS, |
| 731 |
other mechanisms may also be specified and used for NFSv4.1 security. |
| 732 |
|
| 733 |
To enable in-band security negotiation, the NFSv4.1 protocol has |
| 734 |
operations that provide the client a method of querying the server |
| 735 |
about its policies regarding which security mechanisms must be used |
| 736 |
for access to the server's file system resources. With this, the |
| 737 |
client can securely match the security mechanism that meets the |
| 738 |
policies specified at both the client and server. |
| 739 |
|
| 740 |
NFSv4.1 introduces parallel access (see <a href="#section-1.7.2.2">Section 1.7.2.2</a>), which is |
| 741 |
called pNFS. The security framework described in this section is |
| 742 |
significantly modified by the introduction of pNFS (see |
| 743 |
<a href="#section-12.9">Section 12.9</a>), because data access is sometimes not over RPC. The |
| 744 |
level of significance varies with the storage protocol (see |
| 745 |
<a href="#section-12.2.5">Section 12.2.5</a>) and can be as low as zero impact (see <a href="#section-13.12">Section 13.12</a>). |
| 746 |
|
| 747 |
<span class="h4"><a class="selflink" id="section-1.7.2" href="#section-1.7.2">1.7.2</a>. Protocol Structure</span> |
| 748 |
|
| 749 |
<span class="h5"><a class="selflink" id="section-1.7.2.1" href="#section-1.7.2.1">1.7.2.1</a>. Core Protocol</span> |
| 750 |
|
| 751 |
Unlike NFSv3, which used a series of ancillary protocols (e.g., NLM, |
| 752 |
NSM (Network Status Monitor), MOUNT), within all minor versions of |
| 753 |
NFSv4 a single RPC protocol is used to make requests to the server. |
| 754 |
Facilities that had been separate protocols, such as locking, are now |
| 755 |
integrated within a single unified protocol. |
| 756 |
|
| 757 |
<span class="h5"><a class="selflink" id="section-1.7.2.2" href="#section-1.7.2.2">1.7.2.2</a>. Parallel Access</span> |
| 758 |
|
| 759 |
Minor version 1 supports high-performance data access to a clustered |
| 760 |
server implementation by enabling a separation of metadata access and |
| 761 |
data access, with the latter done to multiple servers in parallel. |
| 762 |
|
| 763 |
Such parallel data access is controlled by recallable objects known |
| 764 |
as "layouts", which are integrated into the protocol locking model. |
| 765 |
Clients direct requests for data access to a set of data servers |
| 766 |
specified by the layout via a data storage protocol which may be |
| 767 |
NFSv4.1 or may be another protocol. |
| 768 |
|
| 769 |
Because the protocols used for parallel data access are not |
| 770 |
necessarily RPC-based, the RPC-based security model (<a href="#section-1.7.1">Section 1.7.1</a>) |
| 771 |
is obviously impacted (see <a href="#section-12.9">Section 12.9</a>). The degree of impact |
| 772 |
varies with the storage protocol (see <a href="#section-12.2.5">Section 12.2.5</a>) used for data |
| 773 |
access, and can be as low as zero (see <a href="#section-13.12">Section 13.12</a>). |
| 774 |
|
| 775 |
|
| 776 |
|
| 777 |
|
| 778 |
|
| 779 |
|
| 780 |
<span class="grey">Shepler, et al. Standards Track [Page 14]</span></pre> |
| 781 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-15" ></span> |
| 782 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 783 |
|
| 784 |
|
| 785 |
<span class="h4"><a class="selflink" id="section-1.7.3" href="#section-1.7.3">1.7.3</a>. File System Model</span> |
| 786 |
|
| 787 |
The general file system model used for the NFSv4.1 protocol is the |
| 788 |
same as previous versions. The server file system is hierarchical |
| 789 |
with the regular files contained within being treated as opaque byte |
| 790 |
streams. In a slight departure, file and directory names are encoded |
| 791 |
with UTF-8 to deal with the basics of internationalization. |
| 792 |
|
| 793 |
The NFSv4.1 protocol does not require a separate protocol to provide |
| 794 |
for the initial mapping between path name and filehandle. All file |
| 795 |
systems exported by a server are presented as a tree so that all file |
| 796 |
systems are reachable from a special per-server global root |
| 797 |
filehandle. This allows LOOKUP operations to be used to perform |
| 798 |
functions previously provided by the MOUNT protocol. The server |
| 799 |
provides any necessary pseudo file systems to bridge any gaps that |
| 800 |
arise due to unexported gaps between exported file systems. |
| 801 |
|
| 802 |
<span class="h5"><a class="selflink" id="section-1.7.3.1" href="#section-1.7.3.1">1.7.3.1</a>. Filehandles</span> |
| 803 |
|
| 804 |
As in previous versions of the NFS protocol, opaque filehandles are |
| 805 |
used to identify individual files and directories. Lookup-type and |
| 806 |
create operations translate file and directory names to filehandles, |
| 807 |
which are then used to identify objects in subsequent operations. |
| 808 |
|
| 809 |
The NFSv4.1 protocol provides support for persistent filehandles, |
| 810 |
guaranteed to be valid for the lifetime of the file system object |
| 811 |
designated. In addition, it provides support to servers to provide |
| 812 |
filehandles with more limited validity guarantees, called volatile |
| 813 |
filehandles. |
| 814 |
|
| 815 |
<span class="h5"><a class="selflink" id="section-1.7.3.2" href="#section-1.7.3.2">1.7.3.2</a>. File Attributes</span> |
| 816 |
|
| 817 |
The NFSv4.1 protocol has a rich and extensible file object attribute |
| 818 |
structure, which is divided into REQUIRED, RECOMMENDED, and named |
| 819 |
attributes (see <a href="#section-5">Section 5</a>). |
| 820 |
|
| 821 |
Several (but not all) of the REQUIRED attributes are derived from the |
| 822 |
attributes of NFSv3 (see the definition of the fattr3 data type in |
| 823 |
[<a href="#ref-31" title=""NFS Version 3 Protocol Specification"">31</a>]). An example of a REQUIRED attribute is the file object's type |
| 824 |
(<a href="#section-5.8.1.2">Section 5.8.1.2</a>) so that regular files can be distinguished from |
| 825 |
directories (also known as folders in some operating environments) |
| 826 |
and other types of objects. REQUIRED attributes are discussed in |
| 827 |
<a href="#section-5.1">Section 5.1</a>. |
| 828 |
|
| 829 |
An example of three RECOMMENDED attributes are acl, sacl, and dacl. |
| 830 |
These attributes define an Access Control List (ACL) on a file object |
| 831 |
(<a href="#section-6">Section 6</a>). An ACL provides directory and file access control |
| 832 |
beyond the model used in NFSv3. The ACL definition allows for |
| 833 |
|
| 834 |
|
| 835 |
|
| 836 |
<span class="grey">Shepler, et al. Standards Track [Page 15]</span></pre> |
| 837 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-16" ></span> |
| 838 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 839 |
|
| 840 |
|
| 841 |
specification of specific sets of permissions for individual users |
| 842 |
and groups. In addition, ACL inheritance allows propagation of |
| 843 |
access permissions and restrictions down a directory tree as file |
| 844 |
system objects are created. RECOMMENDED attributes are discussed in |
| 845 |
<a href="#section-5.2">Section 5.2</a>. |
| 846 |
|
| 847 |
A named attribute is an opaque byte stream that is associated with a |
| 848 |
directory or file and referred to by a string name. Named attributes |
| 849 |
are meant to be used by client applications as a method to associate |
| 850 |
application-specific data with a regular file or directory. NFSv4.1 |
| 851 |
modifies named attributes relative to NFSv4.0 by tightening the |
| 852 |
allowed operations in order to prevent the development of non- |
| 853 |
interoperable implementations. Named attributes are discussed in |
| 854 |
<a href="#section-5.3">Section 5.3</a>. |
| 855 |
|
| 856 |
<span class="h5"><a class="selflink" id="section-1.7.3.3" href="#section-1.7.3.3">1.7.3.3</a>. Multi-Server Namespace</span> |
| 857 |
|
| 858 |
NFSv4.1 contains a number of features to allow implementation of |
| 859 |
namespaces that cross server boundaries and that allow and facilitate |
| 860 |
a non-disruptive transfer of support for individual file systems |
| 861 |
between servers. They are all based upon attributes that allow one |
| 862 |
file system to specify alternate or new locations for that file |
| 863 |
system. |
| 864 |
|
| 865 |
These attributes may be used together with the concept of absent file |
| 866 |
systems, which provide specifications for additional locations but no |
| 867 |
actual file system content. This allows a number of important |
| 868 |
facilities: |
| 869 |
|
| 870 |
o Location attributes may be used with absent file systems to |
| 871 |
implement referrals whereby one server may direct the client to a |
| 872 |
file system provided by another server. This allows extensive |
| 873 |
multi-server namespaces to be constructed. |
| 874 |
|
| 875 |
o Location attributes may be provided for present file systems to |
| 876 |
provide the locations of alternate file system instances or |
| 877 |
replicas to be used in the event that the current file system |
| 878 |
instance becomes unavailable. |
| 879 |
|
| 880 |
o Location attributes may be provided when a previously present file |
| 881 |
system becomes absent. This allows non-disruptive migration of |
| 882 |
file systems to alternate servers. |
| 883 |
|
| 884 |
<span class="h4"><a class="selflink" id="section-1.7.4" href="#section-1.7.4">1.7.4</a>. Locking Facilities</span> |
| 885 |
|
| 886 |
As mentioned previously, NFSv4.1 is a single protocol that includes |
| 887 |
locking facilities. These locking facilities include support for |
| 888 |
many types of locks including a number of sorts of recallable locks. |
| 889 |
|
| 890 |
|
| 891 |
|
| 892 |
<span class="grey">Shepler, et al. Standards Track [Page 16]</span></pre> |
| 893 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-17" ></span> |
| 894 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 895 |
|
| 896 |
|
| 897 |
Recallable locks such as delegations allow the client to be assured |
| 898 |
that certain events will not occur so long as that lock is held. |
| 899 |
When circumstances change, the lock is recalled via a callback |
| 900 |
request. The assurances provided by delegations allow more extensive |
| 901 |
caching to be done safely when circumstances allow it. |
| 902 |
|
| 903 |
The types of locks are: |
| 904 |
|
| 905 |
o Share reservations as established by OPEN operations. |
| 906 |
|
| 907 |
o Byte-range locks. |
| 908 |
|
| 909 |
o File delegations, which are recallable locks that assure the |
| 910 |
holder that inconsistent opens and file changes cannot occur so |
| 911 |
long as the delegation is held. |
| 912 |
|
| 913 |
o Directory delegations, which are recallable locks that assure the |
| 914 |
holder that inconsistent directory modifications cannot occur so |
| 915 |
long as the delegation is held. |
| 916 |
|
| 917 |
o Layouts, which are recallable objects that assure the holder that |
| 918 |
direct access to the file data may be performed directly by the |
| 919 |
client and that no change to the data's location that is |
| 920 |
inconsistent with that access may be made so long as the layout is |
| 921 |
held. |
| 922 |
|
| 923 |
All locks for a given client are tied together under a single client- |
| 924 |
wide lease. All requests made on sessions associated with the client |
| 925 |
renew that lease. When the client's lease is not promptly renewed, |
| 926 |
the client's locks are subject to revocation. In the event of server |
| 927 |
restart, clients have the opportunity to safely reclaim their locks |
| 928 |
within a special grace period. |
| 929 |
|
| 930 |
<span class="h3"><a class="selflink" id="section-1.8" href="#section-1.8">1.8</a>. Differences from NFSv4.0</span> |
| 931 |
|
| 932 |
The following summarizes the major differences between minor version |
| 933 |
1 and the base protocol: |
| 934 |
|
| 935 |
o Implementation of the sessions model (<a href="#section-2.10">Section 2.10</a>). |
| 936 |
|
| 937 |
o Parallel access to data (<a href="#section-12">Section 12</a>). |
| 938 |
|
| 939 |
o Addition of the RECLAIM_COMPLETE operation to better structure the |
| 940 |
lock reclamation process (<a href="#section-18.51">Section 18.51</a>). |
| 941 |
|
| 942 |
o Enhanced delegation support as follows. |
| 943 |
|
| 944 |
|
| 945 |
|
| 946 |
|
| 947 |
|
| 948 |
<span class="grey">Shepler, et al. Standards Track [Page 17]</span></pre> |
| 949 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-18" ></span> |
| 950 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 951 |
|
| 952 |
|
| 953 |
* Delegations on directories and other file types in addition to |
| 954 |
regular files (<a href="#section-18.39">Section 18.39</a>, <a href="#section-18.49">Section 18.49</a>). |
| 955 |
|
| 956 |
* Operations to optimize acquisition of recalled or denied |
| 957 |
delegations (<a href="#section-18.49">Section 18.49</a>, <a href="#section-20.5">Section 20.5</a>, <a href="#section-20.7">Section 20.7</a>). |
| 958 |
|
| 959 |
* Notifications of changes to files and directories |
| 960 |
(<a href="#section-18.39">Section 18.39</a>, <a href="#section-20.4">Section 20.4</a>). |
| 961 |
|
| 962 |
* A method to allow a server to indicate that it is recalling one |
| 963 |
or more delegations for resource management reasons, and thus a |
| 964 |
method to allow the client to pick which delegations to return |
| 965 |
(<a href="#section-20.6">Section 20.6</a>). |
| 966 |
|
| 967 |
o Attributes can be set atomically during exclusive file create via |
| 968 |
the OPEN operation (see the new EXCLUSIVE4_1 creation method in |
| 969 |
<a href="#section-18.16">Section 18.16</a>). |
| 970 |
|
| 971 |
o Open files can be preserved if removed and the hard link count |
| 972 |
("hard link" is defined in an Open Group [<a href="#ref-6" title="">6</a>] standard) goes to |
| 973 |
zero, thus obviating the need for clients to rename deleted files |
| 974 |
to partially hidden names -- colloquially called "silly rename" |
| 975 |
(see the new OPEN4_RESULT_PRESERVE_UNLINKED reply flag in |
| 976 |
<a href="#section-18.16">Section 18.16</a>). |
| 977 |
|
| 978 |
o Improved compatibility with Microsoft Windows for Access Control |
| 979 |
Lists (<a href="#section-6.2.3">Section 6.2.3</a>, <a href="#section-6.2.2">Section 6.2.2</a>, <a href="#section-6.4.3.2">Section 6.4.3.2</a>). |
| 980 |
|
| 981 |
o Data retention (<a href="#section-5.13">Section 5.13</a>). |
| 982 |
|
| 983 |
o Identification of the implementation of the NFS client and server |
| 984 |
(<a href="#section-18.35">Section 18.35</a>). |
| 985 |
|
| 986 |
o Support for notification of the availability of byte-range locks |
| 987 |
(see the new OPEN4_RESULT_MAY_NOTIFY_LOCK reply flag in |
| 988 |
<a href="#section-18.16">Section 18.16</a> and see <a href="#section-20.11">Section 20.11</a>). |
| 989 |
|
| 990 |
o In NFSv4.1, LIPKEY and SPKM-3 are not required security mechanisms |
| 991 |
[<a href="#ref-32" title=""LIPKEY - A Low Infrastructure Public Key Mechanism Using SPKM"">32</a>]. |
| 992 |
|
| 993 |
<span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. Core Infrastructure</span> |
| 994 |
|
| 995 |
<span class="h3"><a class="selflink" id="section-2.1" href="#section-2.1">2.1</a>. Introduction</span> |
| 996 |
|
| 997 |
NFSv4.1 relies on core infrastructure common to nearly every |
| 998 |
operation. This core infrastructure is described in the remainder of |
| 999 |
this section. |
| 1000 |
|
| 1001 |
|
| 1002 |
|
| 1003 |
|
| 1004 |
<span class="grey">Shepler, et al. Standards Track [Page 18]</span></pre> |
| 1005 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-19" ></span> |
| 1006 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1007 |
|
| 1008 |
|
| 1009 |
<span class="h3"><a class="selflink" id="section-2.2" href="#section-2.2">2.2</a>. RPC and XDR</span> |
| 1010 |
|
| 1011 |
The NFSv4.1 protocol is a Remote Procedure Call (RPC) application |
| 1012 |
that uses RPC version 2 and the corresponding eXternal Data |
| 1013 |
Representation (XDR) as defined in [<a href="#ref-3" title=""RPC: Remote Procedure Call Protocol Specification Version 2"">3</a>] and [<a href="#ref-2" title=""XDR: External Data Representation Standard"">2</a>]. |
| 1014 |
|
| 1015 |
<span class="h4"><a class="selflink" id="section-2.2.1" href="#section-2.2.1">2.2.1</a>. RPC-Based Security</span> |
| 1016 |
|
| 1017 |
Previous NFS versions have been thought of as having a host-based |
| 1018 |
authentication model, where the NFS server authenticates the NFS |
| 1019 |
client, and trusts the client to authenticate all users. Actually, |
| 1020 |
NFS has always depended on RPC for authentication. One of the first |
| 1021 |
forms of RPC authentication, AUTH_SYS, had no strong authentication |
| 1022 |
and required a host-based authentication approach. NFSv4.1 also |
| 1023 |
depends on RPC for basic security services and mandates RPC support |
| 1024 |
for a user-based authentication model. The user-based authentication |
| 1025 |
model has user principals authenticated by a server, and in turn the |
| 1026 |
server authenticated by user principals. RPC provides some basic |
| 1027 |
security services that are used by NFSv4.1. |
| 1028 |
|
| 1029 |
<span class="h5"><a class="selflink" id="section-2.2.1.1" href="#section-2.2.1.1">2.2.1.1</a>. RPC Security Flavors</span> |
| 1030 |
|
| 1031 |
As described in <a href="#section-7.2">Section 7.2</a> ("Authentication") of [<a href="#ref-3" title=""RPC: Remote Procedure Call Protocol Specification Version 2"">3</a>], RPC security |
| 1032 |
is encapsulated in the RPC header, via a security or authentication |
| 1033 |
flavor, and information specific to the specified security flavor. |
| 1034 |
Every RPC header conveys information used to identify and |
| 1035 |
authenticate a client and server. As discussed in <a href="#section-2.2.1.1.1">Section 2.2.1.1.1</a>, |
| 1036 |
some security flavors provide additional security services. |
| 1037 |
|
| 1038 |
NFSv4.1 clients and servers MUST implement RPCSEC_GSS. (This |
| 1039 |
requirement to implement is not a requirement to use.) Other |
| 1040 |
flavors, such as AUTH_NONE and AUTH_SYS, MAY be implemented as well. |
| 1041 |
|
| 1042 |
<span class="h6"><a class="selflink" id="section-2.2.1.1.1" href="#section-2.2.1.1.1">2.2.1.1.1</a>. RPCSEC_GSS and Security Services</span> |
| 1043 |
|
| 1044 |
RPCSEC_GSS [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>] uses the functionality of GSS-API [<a href="#ref-7" title=""Generic Security Service Application Program Interface Version 2, Update 1"">7</a>]. This allows |
| 1045 |
for the use of various security mechanisms by the RPC layer without |
| 1046 |
the additional implementation overhead of adding RPC security |
| 1047 |
flavors. |
| 1048 |
|
| 1049 |
<span class="h6"><a class="selflink" id="section-2.2.1.1.1.1" href="#section-2.2.1.1.1.1">2.2.1.1.1.1</a>. Identification, Authentication, Integrity, Privacy</span> |
| 1050 |
|
| 1051 |
Via the GSS-API, RPCSEC_GSS can be used to identify and authenticate |
| 1052 |
users on clients to servers, and servers to users. It can also |
| 1053 |
perform integrity checking on the entire RPC message, including the |
| 1054 |
RPC header, and on the arguments or results. Finally, privacy, |
| 1055 |
usually via encryption, is a service available with RPCSEC_GSS. |
| 1056 |
Privacy is performed on the arguments and results. Note that if |
| 1057 |
|
| 1058 |
|
| 1059 |
|
| 1060 |
<span class="grey">Shepler, et al. Standards Track [Page 19]</span></pre> |
| 1061 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-20" ></span> |
| 1062 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1063 |
|
| 1064 |
|
| 1065 |
privacy is selected, integrity, authentication, and identification |
| 1066 |
are enabled. If privacy is not selected, but integrity is selected, |
| 1067 |
authentication and identification are enabled. If integrity and |
| 1068 |
privacy are not selected, but authentication is enabled, |
| 1069 |
identification is enabled. RPCSEC_GSS does not provide |
| 1070 |
identification as a separate service. |
| 1071 |
|
| 1072 |
Although GSS-API has an authentication service distinct from its |
| 1073 |
privacy and integrity services, GSS-API's authentication service is |
| 1074 |
not used for RPCSEC_GSS's authentication service. Instead, each RPC |
| 1075 |
request and response header is integrity protected with the GSS-API |
| 1076 |
integrity service, and this allows RPCSEC_GSS to offer per-RPC |
| 1077 |
authentication and identity. See [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>] for more information. |
| 1078 |
|
| 1079 |
NFSv4.1 client and servers MUST support RPCSEC_GSS's integrity and |
| 1080 |
authentication service. NFSv4.1 servers MUST support RPCSEC_GSS's |
| 1081 |
privacy service. NFSv4.1 clients SHOULD support RPCSEC_GSS's privacy |
| 1082 |
service. |
| 1083 |
|
| 1084 |
<span class="h6"><a class="selflink" id="section-2.2.1.1.1.2" href="#section-2.2.1.1.1.2">2.2.1.1.1.2</a>. Security Mechanisms for NFSv4.1</span> |
| 1085 |
|
| 1086 |
RPCSEC_GSS, via GSS-API, normalizes access to mechanisms that provide |
| 1087 |
security services. Therefore, NFSv4.1 clients and servers MUST |
| 1088 |
support the Kerberos V5 security mechanism. |
| 1089 |
|
| 1090 |
The use of RPCSEC_GSS requires selection of mechanism, quality of |
| 1091 |
protection (QOP), and service (authentication, integrity, privacy). |
| 1092 |
For the mandated security mechanisms, NFSv4.1 specifies that a QOP of |
| 1093 |
zero is used, leaving it up to the mechanism or the mechanism's |
| 1094 |
configuration to map QOP zero to an appropriate level of protection. |
| 1095 |
Each mandated mechanism specifies a minimum set of cryptographic |
| 1096 |
algorithms for implementing integrity and privacy. NFSv4.1 clients |
| 1097 |
and servers MUST be implemented on operating environments that comply |
| 1098 |
with the REQUIRED cryptographic algorithms of each REQUIRED |
| 1099 |
mechanism. |
| 1100 |
|
| 1101 |
<span class="h6"><a class="selflink" id="section-2.2.1.1.1.2.1" href="#section-2.2.1.1.1.2.1">2.2.1.1.1.2.1</a>. Kerberos V5</span> |
| 1102 |
|
| 1103 |
The Kerberos V5 GSS-API mechanism as described in [<a href="#ref-5" title=""The Kerberos Version 5 Generic Security Service Application Program Interface (GSS- API) Mechanism Version 2"">5</a>] MUST be |
| 1104 |
implemented with the RPCSEC_GSS services as specified in the |
| 1105 |
following table: |
| 1106 |
|
| 1107 |
|
| 1108 |
|
| 1109 |
|
| 1110 |
|
| 1111 |
|
| 1112 |
|
| 1113 |
|
| 1114 |
|
| 1115 |
|
| 1116 |
<span class="grey">Shepler, et al. Standards Track [Page 20]</span></pre> |
| 1117 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-21" ></span> |
| 1118 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1119 |
|
| 1120 |
|
| 1121 |
column descriptions: |
| 1122 |
1 == number of pseudo flavor |
| 1123 |
2 == name of pseudo flavor |
| 1124 |
3 == mechanism's OID |
| 1125 |
4 == RPCSEC_GSS service |
| 1126 |
5 == NFSv4.1 clients MUST support |
| 1127 |
6 == NFSv4.1 servers MUST support |
| 1128 |
|
| 1129 |
1 2 3 4 5 6 |
| 1130 |
------------------------------------------------------------------ |
| 1131 |
390003 krb5 1.2.840.113554.1.2.2 rpc_gss_svc_none yes yes |
| 1132 |
390004 krb5i 1.2.840.113554.1.2.2 rpc_gss_svc_integrity yes yes |
| 1133 |
390005 krb5p 1.2.840.113554.1.2.2 rpc_gss_svc_privacy no yes |
| 1134 |
|
| 1135 |
Note that the number and name of the pseudo flavor are presented here |
| 1136 |
as a mapping aid to the implementor. Because the NFSv4.1 protocol |
| 1137 |
includes a method to negotiate security and it understands the GSS- |
| 1138 |
API mechanism, the pseudo flavor is not needed. The pseudo flavor is |
| 1139 |
needed for the NFSv3 since the security negotiation is done via the |
| 1140 |
MOUNT protocol as described in [<a href="#ref-33" title=""NFS Version 2 and Version 3 Security Issues and the NFS Protocol's Use of RPCSEC_GSS and Kerberos V5"">33</a>]. |
| 1141 |
|
| 1142 |
At the time NFSv4.1 was specified, the Advanced Encryption Standard |
| 1143 |
(AES) with HMAC-SHA1 was a REQUIRED algorithm set for Kerberos V5. |
| 1144 |
In contrast, when NFSv4.0 was specified, weaker algorithm sets were |
| 1145 |
REQUIRED for Kerberos V5, and were REQUIRED in the NFSv4.0 |
| 1146 |
specification, because the Kerberos V5 specification at the time did |
| 1147 |
not specify stronger algorithms. The NFSv4.1 specification does not |
| 1148 |
specify REQUIRED algorithms for Kerberos V5, and instead, the |
| 1149 |
implementor is expected to track the evolution of the Kerberos V5 |
| 1150 |
standard if and when stronger algorithms are specified. |
| 1151 |
|
| 1152 |
<span class="h6"><a class="selflink" id="section-2.2.1.1.1.2.1.1" href="#section-2.2.1.1.1.2.1.1">2.2.1.1.1.2.1.1</a>. Security Considerations for Cryptographic Algorithms</span> |
| 1153 |
<span class="h6"> in Kerberos V5</span> |
| 1154 |
|
| 1155 |
When deploying NFSv4.1, the strength of the security achieved depends |
| 1156 |
on the existing Kerberos V5 infrastructure. The algorithms of |
| 1157 |
Kerberos V5 are not directly exposed to or selectable by the client |
| 1158 |
or server, so there is some due diligence required by the user of |
| 1159 |
NFSv4.1 to ensure that security is acceptable where needed. |
| 1160 |
|
| 1161 |
<span class="h6"><a class="selflink" id="section-2.2.1.1.1.3" href="#section-2.2.1.1.1.3">2.2.1.1.1.3</a>. GSS Server Principal</span> |
| 1162 |
|
| 1163 |
Regardless of what security mechanism under RPCSEC_GSS is being used, |
| 1164 |
the NFS server MUST identify itself in GSS-API via a |
| 1165 |
GSS_C_NT_HOSTBASED_SERVICE name type. GSS_C_NT_HOSTBASED_SERVICE |
| 1166 |
names are of the form: |
| 1167 |
|
| 1168 |
service@hostname |
| 1169 |
|
| 1170 |
|
| 1171 |
|
| 1172 |
<span class="grey">Shepler, et al. Standards Track [Page 21]</span></pre> |
| 1173 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-22" ></span> |
| 1174 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1175 |
|
| 1176 |
|
| 1177 |
For NFS, the "service" element is |
| 1178 |
|
| 1179 |
nfs |
| 1180 |
|
| 1181 |
Implementations of security mechanisms will convert nfs@hostname to |
| 1182 |
various different forms. For Kerberos V5, the following form is |
| 1183 |
RECOMMENDED: |
| 1184 |
|
| 1185 |
nfs/hostname |
| 1186 |
|
| 1187 |
<span class="h3"><a class="selflink" id="section-2.3" href="#section-2.3">2.3</a>. COMPOUND and CB_COMPOUND</span> |
| 1188 |
|
| 1189 |
A significant departure from the versions of the NFS protocol before |
| 1190 |
NFSv4 is the introduction of the COMPOUND procedure. For the NFSv4 |
| 1191 |
protocol, in all minor versions, there are exactly two RPC |
| 1192 |
procedures, NULL and COMPOUND. The COMPOUND procedure is defined as |
| 1193 |
a series of individual operations and these operations perform the |
| 1194 |
sorts of functions performed by traditional NFS procedures. |
| 1195 |
|
| 1196 |
The operations combined within a COMPOUND request are evaluated in |
| 1197 |
order by the server, without any atomicity guarantees. A limited set |
| 1198 |
of facilities exist to pass results from one operation to another. |
| 1199 |
Once an operation returns a failing result, the evaluation ends and |
| 1200 |
the results of all evaluated operations are returned to the client. |
| 1201 |
|
| 1202 |
With the use of the COMPOUND procedure, the client is able to build |
| 1203 |
simple or complex requests. These COMPOUND requests allow for a |
| 1204 |
reduction in the number of RPCs needed for logical file system |
| 1205 |
operations. For example, multi-component look up requests can be |
| 1206 |
constructed by combining multiple LOOKUP operations. Those can be |
| 1207 |
further combined with operations such as GETATTR, READDIR, or OPEN |
| 1208 |
plus READ to do more complicated sets of operation without incurring |
| 1209 |
additional latency. |
| 1210 |
|
| 1211 |
NFSv4.1 also contains a considerable set of callback operations in |
| 1212 |
which the server makes an RPC directed at the client. Callback RPCs |
| 1213 |
have a similar structure to that of the normal server requests. In |
| 1214 |
all minor versions of the NFSv4 protocol, there are two callback RPC |
| 1215 |
procedures: CB_NULL and CB_COMPOUND. The CB_COMPOUND procedure is |
| 1216 |
defined in an analogous fashion to that of COMPOUND with its own set |
| 1217 |
of callback operations. |
| 1218 |
|
| 1219 |
The addition of new server and callback operations within the |
| 1220 |
COMPOUND and CB_COMPOUND request framework provides a means of |
| 1221 |
extending the protocol in subsequent minor versions. |
| 1222 |
|
| 1223 |
|
| 1224 |
|
| 1225 |
|
| 1226 |
|
| 1227 |
|
| 1228 |
<span class="grey">Shepler, et al. Standards Track [Page 22]</span></pre> |
| 1229 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-23" ></span> |
| 1230 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1231 |
|
| 1232 |
|
| 1233 |
Except for a small number of operations needed for session creation, |
| 1234 |
server requests and callback requests are performed within the |
| 1235 |
context of a session. Sessions provide a client context for every |
| 1236 |
request and support robust reply protection for non-idempotent |
| 1237 |
requests. |
| 1238 |
|
| 1239 |
<span class="h3"><a class="selflink" id="section-2.4" href="#section-2.4">2.4</a>. Client Identifiers and Client Owners</span> |
| 1240 |
|
| 1241 |
For each operation that obtains or depends on locking state, the |
| 1242 |
specific client needs to be identifiable by the server. |
| 1243 |
|
| 1244 |
Each distinct client instance is represented by a client ID. A |
| 1245 |
client ID is a 64-bit identifier representing a specific client at a |
| 1246 |
given time. The client ID is changed whenever the client re- |
| 1247 |
initializes, and may change when the server re-initializes. Client |
| 1248 |
IDs are used to support lock identification and crash recovery. |
| 1249 |
|
| 1250 |
During steady state operation, the client ID associated with each |
| 1251 |
operation is derived from the session (see <a href="#section-2.10">Section 2.10</a>) on which the |
| 1252 |
operation is sent. A session is associated with a client ID when the |
| 1253 |
session is created. |
| 1254 |
|
| 1255 |
Unlike NFSv4.0, the only NFSv4.1 operations possible before a client |
| 1256 |
ID is established are those needed to establish the client ID. |
| 1257 |
|
| 1258 |
A sequence of an EXCHANGE_ID operation followed by a CREATE_SESSION |
| 1259 |
operation using that client ID (eir_clientid as returned from |
| 1260 |
EXCHANGE_ID) is required to establish and confirm the client ID on |
| 1261 |
the server. Establishment of identification by a new incarnation of |
| 1262 |
the client also has the effect of immediately releasing any locking |
| 1263 |
state that a previous incarnation of that same client might have had |
| 1264 |
on the server. Such released state would include all byte-range |
| 1265 |
lock, share reservation, layout state, and -- where the server |
| 1266 |
supports neither the CLAIM_DELEGATE_PREV nor CLAIM_DELEG_CUR_FH claim |
| 1267 |
types -- all delegation state associated with the same client with |
| 1268 |
the same identity. For discussion of delegation state recovery, see |
| 1269 |
<a href="#section-10.2.1">Section 10.2.1</a>. For discussion of layout state recovery, see |
| 1270 |
<a href="#section-12.7.1">Section 12.7.1</a>. |
| 1271 |
|
| 1272 |
Releasing such state requires that the server be able to determine |
| 1273 |
that one client instance is the successor of another. Where this |
| 1274 |
cannot be done, for any of a number of reasons, the locking state |
| 1275 |
will remain for a time subject to lease expiration (see <a href="#section-8.3">Section 8.3</a>) |
| 1276 |
and the new client will need to wait for such state to be removed, if |
| 1277 |
it makes conflicting lock requests. |
| 1278 |
|
| 1279 |
Client identification is encapsulated in the following client owner |
| 1280 |
data type: |
| 1281 |
|
| 1282 |
|
| 1283 |
|
| 1284 |
<span class="grey">Shepler, et al. Standards Track [Page 23]</span></pre> |
| 1285 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-24" ></span> |
| 1286 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1287 |
|
| 1288 |
|
| 1289 |
struct client_owner4 { |
| 1290 |
verifier4 co_verifier; |
| 1291 |
opaque co_ownerid<NFS4_OPAQUE_LIMIT>; |
| 1292 |
}; |
| 1293 |
|
| 1294 |
The first field, co_verifier, is a client incarnation verifier. The |
| 1295 |
server will start the process of canceling the client's leased state |
| 1296 |
if co_verifier is different than what the server has previously |
| 1297 |
recorded for the identified client (as specified in the co_ownerid |
| 1298 |
field). |
| 1299 |
|
| 1300 |
The second field, co_ownerid, is a variable length string that |
| 1301 |
uniquely defines the client so that subsequent instances of the same |
| 1302 |
client bear the same co_ownerid with a different verifier. |
| 1303 |
|
| 1304 |
There are several considerations for how the client generates the |
| 1305 |
co_ownerid string: |
| 1306 |
|
| 1307 |
o The string should be unique so that multiple clients do not |
| 1308 |
present the same string. The consequences of two clients |
| 1309 |
presenting the same string range from one client getting an error |
| 1310 |
to one client having its leased state abruptly and unexpectedly |
| 1311 |
cancelled. |
| 1312 |
|
| 1313 |
o The string should be selected so that subsequent incarnations |
| 1314 |
(e.g., restarts) of the same client cause the client to present |
| 1315 |
the same string. The implementor is cautioned from an approach |
| 1316 |
that requires the string to be recorded in a local file because |
| 1317 |
this precludes the use of the implementation in an environment |
| 1318 |
where there is no local disk and all file access is from an |
| 1319 |
NFSv4.1 server. |
| 1320 |
|
| 1321 |
o The string should be the same for each server network address that |
| 1322 |
the client accesses. This way, if a server has multiple |
| 1323 |
interfaces, the client can trunk traffic over multiple network |
| 1324 |
paths as described in <a href="#section-2.10.5">Section 2.10.5</a>. (Note: the precise opposite |
| 1325 |
was advised in the NFSv4.0 specification [<a href="#ref-30" title=""Network File System (NFS) version 4 Protocol"">30</a>].) |
| 1326 |
|
| 1327 |
o The algorithm for generating the string should not assume that the |
| 1328 |
client's network address will not change, unless the client |
| 1329 |
implementation knows it is using statically assigned network |
| 1330 |
addresses. This includes changes between client incarnations and |
| 1331 |
even changes while the client is still running in its current |
| 1332 |
incarnation. Thus, with dynamic address assignment, if the client |
| 1333 |
includes just the client's network address in the co_ownerid |
| 1334 |
string, there is a real risk that after the client gives up the |
| 1335 |
|
| 1336 |
|
| 1337 |
|
| 1338 |
|
| 1339 |
|
| 1340 |
<span class="grey">Shepler, et al. Standards Track [Page 24]</span></pre> |
| 1341 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-25" ></span> |
| 1342 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1343 |
|
| 1344 |
|
| 1345 |
network address, another client, using a similar algorithm for |
| 1346 |
generating the co_ownerid string, would generate a conflicting |
| 1347 |
co_ownerid string. |
| 1348 |
|
| 1349 |
Given the above considerations, an example of a well-generated |
| 1350 |
co_ownerid string is one that includes: |
| 1351 |
|
| 1352 |
o If applicable, the client's statically assigned network address. |
| 1353 |
|
| 1354 |
o Additional information that tends to be unique, such as one or |
| 1355 |
more of: |
| 1356 |
|
| 1357 |
* The client machine's serial number (for privacy reasons, it is |
| 1358 |
best to perform some one-way function on the serial number). |
| 1359 |
|
| 1360 |
* A Media Access Control (MAC) address (again, a one-way function |
| 1361 |
should be performed). |
| 1362 |
|
| 1363 |
* The timestamp of when the NFSv4.1 software was first installed |
| 1364 |
on the client (though this is subject to the previously |
| 1365 |
mentioned caution about using information that is stored in a |
| 1366 |
file, because the file might only be accessible over NFSv4.1). |
| 1367 |
|
| 1368 |
* A true random number. However, since this number ought to be |
| 1369 |
the same between client incarnations, this shares the same |
| 1370 |
problem as that of using the timestamp of the software |
| 1371 |
installation. |
| 1372 |
|
| 1373 |
o For a user-level NFSv4.1 client, it should contain additional |
| 1374 |
information to distinguish the client from other user-level |
| 1375 |
clients running on the same host, such as a process identifier or |
| 1376 |
other unique sequence. |
| 1377 |
|
| 1378 |
The client ID is assigned by the server (the eir_clientid result from |
| 1379 |
EXCHANGE_ID) and should be chosen so that it will not conflict with a |
| 1380 |
client ID previously assigned by the server. This applies across |
| 1381 |
server restarts. |
| 1382 |
|
| 1383 |
In the event of a server restart, a client may find out that its |
| 1384 |
current client ID is no longer valid when it receives an |
| 1385 |
NFS4ERR_STALE_CLIENTID error. The precise circumstances depend on |
| 1386 |
the characteristics of the sessions involved, specifically whether |
| 1387 |
the session is persistent (see <a href="#section-2.10.6.5">Section 2.10.6.5</a>), but in each case |
| 1388 |
the client will receive this error when it attempts to establish a |
| 1389 |
new session with the existing client ID and receives the error |
| 1390 |
NFS4ERR_STALE_CLIENTID, indicating that a new client ID needs to be |
| 1391 |
obtained via EXCHANGE_ID and the new session established with that |
| 1392 |
client ID. |
| 1393 |
|
| 1394 |
|
| 1395 |
|
| 1396 |
<span class="grey">Shepler, et al. Standards Track [Page 25]</span></pre> |
| 1397 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-26" ></span> |
| 1398 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1399 |
|
| 1400 |
|
| 1401 |
When a session is not persistent, the client will find out that it |
| 1402 |
needs to create a new session as a result of getting an |
| 1403 |
NFS4ERR_BADSESSION, since the session in question was lost as part of |
| 1404 |
a server restart. When the existing client ID is presented to a |
| 1405 |
server as part of creating a session and that client ID is not |
| 1406 |
recognized, as would happen after a server restart, the server will |
| 1407 |
reject the request with the error NFS4ERR_STALE_CLIENTID. |
| 1408 |
|
| 1409 |
In the case of the session being persistent, the client will re- |
| 1410 |
establish communication using the existing session after the restart. |
| 1411 |
This session will be associated with the existing client ID but may |
| 1412 |
only be used to retransmit operations that the client previously |
| 1413 |
transmitted and did not see replies to. Replies to operations that |
| 1414 |
the server previously performed will come from the reply cache; |
| 1415 |
otherwise, NFS4ERR_DEADSESSION will be returned. Hence, such a |
| 1416 |
session is referred to as "dead". In this situation, in order to |
| 1417 |
perform new operations, the client needs to establish a new session. |
| 1418 |
If an attempt is made to establish this new session with the existing |
| 1419 |
client ID, the server will reject the request with |
| 1420 |
NFS4ERR_STALE_CLIENTID. |
| 1421 |
|
| 1422 |
When NFS4ERR_STALE_CLIENTID is received in either of these |
| 1423 |
situations, the client needs to obtain a new client ID by use of the |
| 1424 |
EXCHANGE_ID operation, then use that client ID as the basis of a new |
| 1425 |
session, and then proceed to any other necessary recovery for the |
| 1426 |
server restart case (see <a href="#section-8.4.2">Section 8.4.2</a>). |
| 1427 |
|
| 1428 |
See the descriptions of EXCHANGE_ID (<a href="#section-18.35">Section 18.35</a>) and |
| 1429 |
CREATE_SESSION (<a href="#section-18.36">Section 18.36</a>) for a complete specification of these |
| 1430 |
operations. |
| 1431 |
|
| 1432 |
<span class="h4"><a class="selflink" id="section-2.4.1" href="#section-2.4.1">2.4.1</a>. Upgrade from NFSv4.0 to NFSv4.1</span> |
| 1433 |
|
| 1434 |
To facilitate upgrade from NFSv4.0 to NFSv4.1, a server may compare a |
| 1435 |
value of data type client_owner4 in an EXCHANGE_ID with a value of |
| 1436 |
data type nfs_client_id4 that was established using the SETCLIENTID |
| 1437 |
operation of NFSv4.0. A server that does so will allow an upgraded |
| 1438 |
client to avoid waiting until the lease (i.e., the lease established |
| 1439 |
by the NFSv4.0 instance client) expires. This requires that the |
| 1440 |
value of data type client_owner4 be constructed the same way as the |
| 1441 |
value of data type nfs_client_id4. If the latter's contents included |
| 1442 |
the server's network address (per the recommendations of the NFSv4.0 |
| 1443 |
specification [<a href="#ref-30" title=""Network File System (NFS) version 4 Protocol"">30</a>]), and the NFSv4.1 client does not wish to use a |
| 1444 |
client ID that prevents trunking, it should send two EXCHANGE_ID |
| 1445 |
operations. The first EXCHANGE_ID will have a client_owner4 equal to |
| 1446 |
the nfs_client_id4. This will clear the state created by the NFSv4.0 |
| 1447 |
client. The second EXCHANGE_ID will not have the server's network |
| 1448 |
|
| 1449 |
|
| 1450 |
|
| 1451 |
|
| 1452 |
<span class="grey">Shepler, et al. Standards Track [Page 26]</span></pre> |
| 1453 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-27" ></span> |
| 1454 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1455 |
|
| 1456 |
|
| 1457 |
address. The state created for the second EXCHANGE_ID will not have |
| 1458 |
to wait for lease expiration, because there will be no state to |
| 1459 |
expire. |
| 1460 |
|
| 1461 |
<span class="h4"><a class="selflink" id="section-2.4.2" href="#section-2.4.2">2.4.2</a>. Server Release of Client ID</span> |
| 1462 |
|
| 1463 |
NFSv4.1 introduces a new operation called DESTROY_CLIENTID |
| 1464 |
(<a href="#section-18.50">Section 18.50</a>), which the client SHOULD use to destroy a client ID |
| 1465 |
it no longer needs. This permits graceful, bilateral release of a |
| 1466 |
client ID. The operation cannot be used if there are sessions |
| 1467 |
associated with the client ID, or state with an unexpired lease. |
| 1468 |
|
| 1469 |
If the server determines that the client holds no associated state |
| 1470 |
for its client ID (associated state includes unrevoked sessions, |
| 1471 |
opens, locks, delegations, layouts, and wants), the server MAY choose |
| 1472 |
to unilaterally release the client ID in order to conserve resources. |
| 1473 |
If the client contacts the server after this release, the server MUST |
| 1474 |
ensure that the client receives the appropriate error so that it will |
| 1475 |
use the EXCHANGE_ID/CREATE_SESSION sequence to establish a new client |
| 1476 |
ID. The server ought to be very hesitant to release a client ID |
| 1477 |
since the resulting work on the client to recover from such an event |
| 1478 |
will be the same burden as if the server had failed and restarted. |
| 1479 |
Typically, a server would not release a client ID unless there had |
| 1480 |
been no activity from that client for many minutes. As long as there |
| 1481 |
are sessions, opens, locks, delegations, layouts, or wants, the |
| 1482 |
server MUST NOT release the client ID. See <a href="#section-2.10.13.1.4">Section 2.10.13.1.4</a> for |
| 1483 |
discussion on releasing inactive sessions. |
| 1484 |
|
| 1485 |
<span class="h4"><a class="selflink" id="section-2.4.3" href="#section-2.4.3">2.4.3</a>. Resolving Client Owner Conflicts</span> |
| 1486 |
|
| 1487 |
When the server gets an EXCHANGE_ID for a client owner that currently |
| 1488 |
has no state, or that has state but the lease has expired, the server |
| 1489 |
MUST allow the EXCHANGE_ID and confirm the new client ID if followed |
| 1490 |
by the appropriate CREATE_SESSION. |
| 1491 |
|
| 1492 |
When the server gets an EXCHANGE_ID for a new incarnation of a client |
| 1493 |
owner that currently has an old incarnation with state and an |
| 1494 |
unexpired lease, the server is allowed to dispose of the state of the |
| 1495 |
previous incarnation of the client owner if one of the following is |
| 1496 |
true: |
| 1497 |
|
| 1498 |
o The principal that created the client ID for the client owner is |
| 1499 |
the same as the principal that is sending the EXCHANGE_ID |
| 1500 |
operation. Note that if the client ID was created with |
| 1501 |
SP4_MACH_CRED state protection (<a href="#section-18.35">Section 18.35</a>), the principal MUST |
| 1502 |
be based on RPCSEC_GSS authentication, the RPCSEC_GSS service used |
| 1503 |
|
| 1504 |
|
| 1505 |
|
| 1506 |
|
| 1507 |
|
| 1508 |
<span class="grey">Shepler, et al. Standards Track [Page 27]</span></pre> |
| 1509 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-28" ></span> |
| 1510 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1511 |
|
| 1512 |
|
| 1513 |
MUST be integrity or privacy, and the same GSS mechanism and |
| 1514 |
principal MUST be used as that used when the client ID was |
| 1515 |
created. |
| 1516 |
|
| 1517 |
o The client ID was established with SP4_SSV protection |
| 1518 |
(<a href="#section-18.35">Section 18.35</a>, <a href="#section-2.10.8.3">Section 2.10.8.3</a>) and the client sends the |
| 1519 |
EXCHANGE_ID with the security flavor set to RPCSEC_GSS using the |
| 1520 |
GSS SSV mechanism (<a href="#section-2.10.9">Section 2.10.9</a>). |
| 1521 |
|
| 1522 |
o The client ID was established with SP4_SSV protection, and under |
| 1523 |
the conditions described herein, the EXCHANGE_ID was sent with |
| 1524 |
SP4_MACH_CRED state protection. Because the SSV might not persist |
| 1525 |
across client and server restart, and because the first time a |
| 1526 |
client sends EXCHANGE_ID to a server it does not have an SSV, the |
| 1527 |
client MAY send the subsequent EXCHANGE_ID without an SSV |
| 1528 |
RPCSEC_GSS handle. Instead, as with SP4_MACH_CRED protection, the |
| 1529 |
principal MUST be based on RPCSEC_GSS authentication, the |
| 1530 |
RPCSEC_GSS service used MUST be integrity or privacy, and the same |
| 1531 |
GSS mechanism and principal MUST be used as that used when the |
| 1532 |
client ID was created. |
| 1533 |
|
| 1534 |
If none of the above situations apply, the server MUST return |
| 1535 |
NFS4ERR_CLID_INUSE. |
| 1536 |
|
| 1537 |
If the server accepts the principal and co_ownerid as matching that |
| 1538 |
which created the client ID, and the co_verifier in the EXCHANGE_ID |
| 1539 |
differs from the co_verifier used when the client ID was created, |
| 1540 |
then after the server receives a CREATE_SESSION that confirms the |
| 1541 |
client ID, the server deletes state. If the co_verifier values are |
| 1542 |
the same (e.g., the client either is updating properties of the |
| 1543 |
client ID (<a href="#section-18.35">Section 18.35</a>) or is attempting trunking (<a href="#section-2.10.5">Section 2.10.5</a>), |
| 1544 |
the server MUST NOT delete state. |
| 1545 |
|
| 1546 |
<span class="h3"><a class="selflink" id="section-2.5" href="#section-2.5">2.5</a>. Server Owners</span> |
| 1547 |
|
| 1548 |
The server owner is similar to a client owner (<a href="#section-2.4">Section 2.4</a>), but |
| 1549 |
unlike the client owner, there is no shorthand server ID. The server |
| 1550 |
owner is defined in the following data type: |
| 1551 |
|
| 1552 |
|
| 1553 |
struct server_owner4 { |
| 1554 |
uint64_t so_minor_id; |
| 1555 |
opaque so_major_id<NFS4_OPAQUE_LIMIT>; |
| 1556 |
}; |
| 1557 |
|
| 1558 |
The server owner is returned from EXCHANGE_ID. When the so_major_id |
| 1559 |
fields are the same in two EXCHANGE_ID results, the connections that |
| 1560 |
each EXCHANGE_ID were sent over can be assumed to address the same |
| 1561 |
|
| 1562 |
|
| 1563 |
|
| 1564 |
<span class="grey">Shepler, et al. Standards Track [Page 28]</span></pre> |
| 1565 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-29" ></span> |
| 1566 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1567 |
|
| 1568 |
|
| 1569 |
server (as defined in <a href="#section-1.6">Section 1.6</a>). If the so_minor_id fields are |
| 1570 |
also the same, then not only do both connections connect to the same |
| 1571 |
server, but the session can be shared across both connections. The |
| 1572 |
reader is cautioned that multiple servers may deliberately or |
| 1573 |
accidentally claim to have the same so_major_id or so_major_id/ |
| 1574 |
so_minor_id; the reader should examine Sections <a href="#section-2.10.5">2.10.5</a> and <a href="#section-18.35">18.35</a> in |
| 1575 |
order to avoid acting on falsely matching server owner values. |
| 1576 |
|
| 1577 |
The considerations for generating a so_major_id are similar to that |
| 1578 |
for generating a co_ownerid string (see <a href="#section-2.4">Section 2.4</a>). The |
| 1579 |
consequences of two servers generating conflicting so_major_id values |
| 1580 |
are less dire than they are for co_ownerid conflicts because the |
| 1581 |
client can use RPCSEC_GSS to compare the authenticity of each server |
| 1582 |
(see <a href="#section-2.10.5">Section 2.10.5</a>). |
| 1583 |
|
| 1584 |
<span class="h3"><a class="selflink" id="section-2.6" href="#section-2.6">2.6</a>. Security Service Negotiation</span> |
| 1585 |
|
| 1586 |
With the NFSv4.1 server potentially offering multiple security |
| 1587 |
mechanisms, the client needs a method to determine or negotiate which |
| 1588 |
mechanism is to be used for its communication with the server. The |
| 1589 |
NFS server may have multiple points within its file system namespace |
| 1590 |
that are available for use by NFS clients. These points can be |
| 1591 |
considered security policy boundaries, and, in some NFS |
| 1592 |
implementations, are tied to NFS export points. In turn, the NFS |
| 1593 |
server may be configured such that each of these security policy |
| 1594 |
boundaries may have different or multiple security mechanisms in use. |
| 1595 |
|
| 1596 |
The security negotiation between client and server SHOULD be done |
| 1597 |
with a secure channel to eliminate the possibility of a third party |
| 1598 |
intercepting the negotiation sequence and forcing the client and |
| 1599 |
server to choose a lower level of security than required or desired. |
| 1600 |
See <a href="#section-21">Section 21</a> for further discussion. |
| 1601 |
|
| 1602 |
<span class="h4"><a class="selflink" id="section-2.6.1" href="#section-2.6.1">2.6.1</a>. NFSv4.1 Security Tuples</span> |
| 1603 |
|
| 1604 |
An NFS server can assign one or more "security tuples" to each |
| 1605 |
security policy boundary in its namespace. Each security tuple |
| 1606 |
consists of a security flavor (see <a href="#section-2.2.1.1">Section 2.2.1.1</a>) and, if the |
| 1607 |
flavor is RPCSEC_GSS, a GSS-API mechanism Object Identifier (OID), a |
| 1608 |
GSS-API quality of protection, and an RPCSEC_GSS service. |
| 1609 |
|
| 1610 |
<span class="h4"><a class="selflink" id="section-2.6.2" href="#section-2.6.2">2.6.2</a>. SECINFO and SECINFO_NO_NAME</span> |
| 1611 |
|
| 1612 |
The SECINFO and SECINFO_NO_NAME operations allow the client to |
| 1613 |
determine, on a per-filehandle basis, what security tuple is to be |
| 1614 |
used for server access. In general, the client will not have to use |
| 1615 |
either operation except during initial communication with the server |
| 1616 |
or when the client crosses security policy boundaries at the server. |
| 1617 |
|
| 1618 |
|
| 1619 |
|
| 1620 |
<span class="grey">Shepler, et al. Standards Track [Page 29]</span></pre> |
| 1621 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-30" ></span> |
| 1622 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1623 |
|
| 1624 |
|
| 1625 |
However, the server's policies may also change at any time and force |
| 1626 |
the client to negotiate a new security tuple. |
| 1627 |
|
| 1628 |
Where the use of different security tuples would affect the type of |
| 1629 |
access that would be allowed if a request was sent over the same |
| 1630 |
connection used for the SECINFO or SECINFO_NO_NAME operation (e.g., |
| 1631 |
read-only vs. read-write) access, security tuples that allow greater |
| 1632 |
access should be presented first. Where the general level of access |
| 1633 |
is the same and different security flavors limit the range of |
| 1634 |
principals whose privileges are recognized (e.g., allowing or |
| 1635 |
disallowing root access), flavors supporting the greatest range of |
| 1636 |
principals should be listed first. |
| 1637 |
|
| 1638 |
<span class="h4"><a class="selflink" id="section-2.6.3" href="#section-2.6.3">2.6.3</a>. Security Error</span> |
| 1639 |
|
| 1640 |
Based on the assumption that each NFSv4.1 client and server MUST |
| 1641 |
support a minimum set of security (i.e., Kerberos V5 under |
| 1642 |
RPCSEC_GSS), the NFS client will initiate file access to the server |
| 1643 |
with one of the minimal security tuples. During communication with |
| 1644 |
the server, the client may receive an NFS error of NFS4ERR_WRONGSEC. |
| 1645 |
This error allows the server to notify the client that the security |
| 1646 |
tuple currently being used contravenes the server's security policy. |
| 1647 |
The client is then responsible for determining (see <a href="#section-2.6.3.1">Section 2.6.3.1</a>) |
| 1648 |
what security tuples are available at the server and choosing one |
| 1649 |
that is appropriate for the client. |
| 1650 |
|
| 1651 |
<span class="h5"><a class="selflink" id="section-2.6.3.1" href="#section-2.6.3.1">2.6.3.1</a>. Using NFS4ERR_WRONGSEC, SECINFO, and SECINFO_NO_NAME</span> |
| 1652 |
|
| 1653 |
This section explains the mechanics of NFSv4.1 security negotiation. |
| 1654 |
|
| 1655 |
<span class="h6"><a class="selflink" id="section-2.6.3.1.1" href="#section-2.6.3.1.1">2.6.3.1.1</a>. Put Filehandle Operations</span> |
| 1656 |
|
| 1657 |
The term "put filehandle operation" refers to PUTROOTFH, PUTPUBFH, |
| 1658 |
PUTFH, and RESTOREFH. Each of the subsections herein describes how |
| 1659 |
the server handles a subseries of operations that starts with a put |
| 1660 |
filehandle operation. |
| 1661 |
|
| 1662 |
<span class="h6"><a class="selflink" id="section-2.6.3.1.1.1" href="#section-2.6.3.1.1.1">2.6.3.1.1.1</a>. Put Filehandle Operation + SAVEFH</span> |
| 1663 |
|
| 1664 |
The client is saving a filehandle for a future RESTOREFH, LINK, or |
| 1665 |
RENAME. SAVEFH MUST NOT return NFS4ERR_WRONGSEC. To determine |
| 1666 |
whether or not the put filehandle operation returns NFS4ERR_WRONGSEC, |
| 1667 |
the server implementation pretends SAVEFH is not in the series of |
| 1668 |
operations and examines which of the situations described in the |
| 1669 |
other subsections of <a href="#section-2.6.3.1.1">Section 2.6.3.1.1</a> apply. |
| 1670 |
|
| 1671 |
|
| 1672 |
|
| 1673 |
|
| 1674 |
|
| 1675 |
|
| 1676 |
<span class="grey">Shepler, et al. Standards Track [Page 30]</span></pre> |
| 1677 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-31" ></span> |
| 1678 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1679 |
|
| 1680 |
|
| 1681 |
<span class="h6"><a class="selflink" id="section-2.6.3.1.1.2" href="#section-2.6.3.1.1.2">2.6.3.1.1.2</a>. Two or More Put Filehandle Operations</span> |
| 1682 |
|
| 1683 |
For a series of N put filehandle operations, the server MUST NOT |
| 1684 |
return NFS4ERR_WRONGSEC to the first N-1 put filehandle operations. |
| 1685 |
The Nth put filehandle operation is handled as if it is the first in |
| 1686 |
a subseries of operations. For example, if the server received a |
| 1687 |
COMPOUND request with this series of operations -- PUTFH, PUTROOTFH, |
| 1688 |
LOOKUP -- then the PUTFH operation is ignored for NFS4ERR_WRONGSEC |
| 1689 |
purposes, and the PUTROOTFH, LOOKUP subseries is processed as |
| 1690 |
according to <a href="#section-2.6.3.1.1.3">Section 2.6.3.1.1.3</a>. |
| 1691 |
|
| 1692 |
<span class="h6"><a class="selflink" id="section-2.6.3.1.1.3" href="#section-2.6.3.1.1.3">2.6.3.1.1.3</a>. Put Filehandle Operation + LOOKUP (or OPEN of an Existing</span> |
| 1693 |
<span class="h6"> Name)</span> |
| 1694 |
|
| 1695 |
This situation also applies to a put filehandle operation followed by |
| 1696 |
a LOOKUP or an OPEN operation that specifies an existing component |
| 1697 |
name. |
| 1698 |
|
| 1699 |
In this situation, the client is potentially crossing a security |
| 1700 |
policy boundary, and the set of security tuples the parent directory |
| 1701 |
supports may differ from those of the child. The server |
| 1702 |
implementation may decide whether to impose any restrictions on |
| 1703 |
security policy administration. There are at least three approaches |
| 1704 |
(sec_policy_child is the tuple set of the child export, |
| 1705 |
sec_policy_parent is that of the parent). |
| 1706 |
|
| 1707 |
(a) sec_policy_child <= sec_policy_parent (<= for subset). This |
| 1708 |
means that the set of security tuples specified on the security |
| 1709 |
policy of a child directory is always a subset of its parent |
| 1710 |
directory. |
| 1711 |
|
| 1712 |
(b) sec_policy_child ^ sec_policy_parent != {} (^ for intersection, |
| 1713 |
{} for the empty set). This means that the set of security |
| 1714 |
tuples specified on the security policy of a child directory |
| 1715 |
always has a non-empty intersection with that of the parent. |
| 1716 |
|
| 1717 |
(c) sec_policy_child ^ sec_policy_parent == {}. This means that the |
| 1718 |
set of security tuples specified on the security policy of a |
| 1719 |
child directory may not intersect with that of the parent. In |
| 1720 |
other words, there are no restrictions on how the system |
| 1721 |
administrator may set up these tuples. |
| 1722 |
|
| 1723 |
In order for a server to support approaches (b) (for the case when a |
| 1724 |
client chooses a flavor that is not a member of sec_policy_parent) |
| 1725 |
and (c), the put filehandle operation cannot return NFS4ERR_WRONGSEC |
| 1726 |
when there is a security tuple mismatch. Instead, it should be |
| 1727 |
returned from the LOOKUP (or OPEN by existing component name) that |
| 1728 |
follows. |
| 1729 |
|
| 1730 |
|
| 1731 |
|
| 1732 |
<span class="grey">Shepler, et al. Standards Track [Page 31]</span></pre> |
| 1733 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-32" ></span> |
| 1734 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1735 |
|
| 1736 |
|
| 1737 |
Since the above guideline does not contradict approach (a), it should |
| 1738 |
be followed in general. Even if approach (a) is implemented, it is |
| 1739 |
possible for the security tuple used to be acceptable for the target |
| 1740 |
of LOOKUP but not for the filehandles used in the put filehandle |
| 1741 |
operation. The put filehandle operation could be a PUTROOTFH or |
| 1742 |
PUTPUBFH, where the client cannot know the security tuples for the |
| 1743 |
root or public filehandle. Or the security policy for the filehandle |
| 1744 |
used by the put filehandle operation could have changed since the |
| 1745 |
time the filehandle was obtained. |
| 1746 |
|
| 1747 |
Therefore, an NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC in |
| 1748 |
response to the put filehandle operation if the operation is |
| 1749 |
immediately followed by a LOOKUP or an OPEN by component name. |
| 1750 |
|
| 1751 |
<span class="h6"><a class="selflink" id="section-2.6.3.1.1.4" href="#section-2.6.3.1.1.4">2.6.3.1.1.4</a>. Put Filehandle Operation + LOOKUPP</span> |
| 1752 |
|
| 1753 |
Since SECINFO only works its way down, there is no way LOOKUPP can |
| 1754 |
return NFS4ERR_WRONGSEC without SECINFO_NO_NAME. SECINFO_NO_NAME |
| 1755 |
solves this issue via style SECINFO_STYLE4_PARENT, which works in the |
| 1756 |
opposite direction as SECINFO. As with <a href="#section-2.6.3.1.1.3">Section 2.6.3.1.1.3</a>, a put |
| 1757 |
filehandle operation that is followed by a LOOKUPP MUST NOT return |
| 1758 |
NFS4ERR_WRONGSEC. If the server does not support SECINFO_NO_NAME, |
| 1759 |
the client's only recourse is to send the put filehandle operation, |
| 1760 |
LOOKUPP, GETFH sequence of operations with every security tuple it |
| 1761 |
supports. |
| 1762 |
|
| 1763 |
Regardless of whether SECINFO_NO_NAME is supported, an NFSv4.1 server |
| 1764 |
MUST NOT return NFS4ERR_WRONGSEC in response to a put filehandle |
| 1765 |
operation if the operation is immediately followed by a LOOKUPP. |
| 1766 |
|
| 1767 |
<span class="h6"><a class="selflink" id="section-2.6.3.1.1.5" href="#section-2.6.3.1.1.5">2.6.3.1.1.5</a>. Put Filehandle Operation + SECINFO/SECINFO_NO_NAME</span> |
| 1768 |
|
| 1769 |
A security-sensitive client is allowed to choose a strong security |
| 1770 |
tuple when querying a server to determine a file object's permitted |
| 1771 |
security tuples. The security tuple chosen by the client does not |
| 1772 |
have to be included in the tuple list of the security policy of |
| 1773 |
either the parent directory indicated in the put filehandle operation |
| 1774 |
or the child file object indicated in SECINFO (or any parent |
| 1775 |
directory indicated in SECINFO_NO_NAME). Of course, the server has |
| 1776 |
to be configured for whatever security tuple the client selects; |
| 1777 |
otherwise, the request will fail at the RPC layer with an appropriate |
| 1778 |
authentication error. |
| 1779 |
|
| 1780 |
In theory, there is no connection between the security flavor used by |
| 1781 |
SECINFO or SECINFO_NO_NAME and those supported by the security |
| 1782 |
policy. But in practice, the client may start looking for strong |
| 1783 |
flavors from those supported by the security policy, followed by |
| 1784 |
those in the REQUIRED set. |
| 1785 |
|
| 1786 |
|
| 1787 |
|
| 1788 |
<span class="grey">Shepler, et al. Standards Track [Page 32]</span></pre> |
| 1789 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-33" ></span> |
| 1790 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1791 |
|
| 1792 |
|
| 1793 |
The NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC to a put |
| 1794 |
filehandle operation that is immediately followed by SECINFO or |
| 1795 |
SECINFO_NO_NAME. The NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC |
| 1796 |
from SECINFO or SECINFO_NO_NAME. |
| 1797 |
|
| 1798 |
<span class="h6"><a class="selflink" id="section-2.6.3.1.1.6" href="#section-2.6.3.1.1.6">2.6.3.1.1.6</a>. Put Filehandle Operation + Nothing</span> |
| 1799 |
|
| 1800 |
The NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC. |
| 1801 |
|
| 1802 |
<span class="h6"><a class="selflink" id="section-2.6.3.1.1.7" href="#section-2.6.3.1.1.7">2.6.3.1.1.7</a>. Put Filehandle Operation + Anything Else</span> |
| 1803 |
|
| 1804 |
"Anything Else" includes OPEN by filehandle. |
| 1805 |
|
| 1806 |
The security policy enforcement applies to the filehandle specified |
| 1807 |
in the put filehandle operation. Therefore, the put filehandle |
| 1808 |
operation MUST return NFS4ERR_WRONGSEC when there is a security tuple |
| 1809 |
mismatch. This avoids the complexity of adding NFS4ERR_WRONGSEC as |
| 1810 |
an allowable error to every other operation. |
| 1811 |
|
| 1812 |
A COMPOUND containing the series put filehandle operation + |
| 1813 |
SECINFO_NO_NAME (style SECINFO_STYLE4_CURRENT_FH) is an efficient way |
| 1814 |
for the client to recover from NFS4ERR_WRONGSEC. |
| 1815 |
|
| 1816 |
The NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC to any operation |
| 1817 |
other than a put filehandle operation, LOOKUP, LOOKUPP, and OPEN (by |
| 1818 |
component name). |
| 1819 |
|
| 1820 |
<span class="h6"><a class="selflink" id="section-2.6.3.1.1.8" href="#section-2.6.3.1.1.8">2.6.3.1.1.8</a>. Operations after SECINFO and SECINFO_NO_NAME</span> |
| 1821 |
|
| 1822 |
Suppose a client sends a COMPOUND procedure containing the series |
| 1823 |
SEQUENCE, PUTFH, SECINFO_NONAME, READ, and suppose the security tuple |
| 1824 |
used does not match that required for the target file. By rule (see |
| 1825 |
<a href="#section-2.6.3.1.1.5">Section 2.6.3.1.1.5</a>), neither PUTFH nor SECINFO_NO_NAME can return |
| 1826 |
NFS4ERR_WRONGSEC. By rule (see <a href="#section-2.6.3.1.1.7">Section 2.6.3.1.1.7</a>), READ cannot |
| 1827 |
return NFS4ERR_WRONGSEC. The issue is resolved by the fact that |
| 1828 |
SECINFO and SECINFO_NO_NAME consume the current filehandle (note that |
| 1829 |
this is a change from NFSv4.0). This leaves no current filehandle |
| 1830 |
for READ to use, and READ returns NFS4ERR_NOFILEHANDLE. |
| 1831 |
|
| 1832 |
<span class="h6"><a class="selflink" id="section-2.6.3.1.2" href="#section-2.6.3.1.2">2.6.3.1.2</a>. LINK and RENAME</span> |
| 1833 |
|
| 1834 |
The LINK and RENAME operations use both the current and saved |
| 1835 |
filehandles. Technically, the server MAY return NFS4ERR_WRONGSEC |
| 1836 |
from LINK or RENAME if the security policy of the saved filehandle |
| 1837 |
rejects the security flavor used in the COMPOUND request's |
| 1838 |
credentials. If the server does so, then if there is no intersection |
| 1839 |
|
| 1840 |
|
| 1841 |
|
| 1842 |
|
| 1843 |
|
| 1844 |
<span class="grey">Shepler, et al. Standards Track [Page 33]</span></pre> |
| 1845 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-34" ></span> |
| 1846 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1847 |
|
| 1848 |
|
| 1849 |
between the security policies of saved and current filehandles, this |
| 1850 |
means that it will be impossible for the client to perform the |
| 1851 |
intended LINK or RENAME operation. |
| 1852 |
|
| 1853 |
For example, suppose the client sends this COMPOUND request: |
| 1854 |
SEQUENCE, PUTFH bFH, SAVEFH, PUTFH aFH, RENAME "c" "d", where |
| 1855 |
filehandles bFH and aFH refer to different directories. Suppose no |
| 1856 |
common security tuple exists between the security policies of aFH and |
| 1857 |
bFH. If the client sends the request using credentials acceptable to |
| 1858 |
bFH's security policy but not aFH's policy, then the PUTFH aFH |
| 1859 |
operation will fail with NFS4ERR_WRONGSEC. After a SECINFO_NO_NAME |
| 1860 |
request, the client sends SEQUENCE, PUTFH bFH, SAVEFH, PUTFH aFH, |
| 1861 |
RENAME "c" "d", using credentials acceptable to aFH's security policy |
| 1862 |
but not bFH's policy. The server returns NFS4ERR_WRONGSEC on the |
| 1863 |
RENAME operation. |
| 1864 |
|
| 1865 |
To prevent a client from an endless sequence of a request containing |
| 1866 |
LINK or RENAME, followed by a request containing SECINFO_NO_NAME or |
| 1867 |
SECINFO, the server MUST detect when the security policies of the |
| 1868 |
current and saved filehandles have no mutually acceptable security |
| 1869 |
tuple, and MUST NOT return NFS4ERR_WRONGSEC from LINK or RENAME in |
| 1870 |
that situation. Instead the server MUST do one of two things: |
| 1871 |
|
| 1872 |
o The server can return NFS4ERR_XDEV. |
| 1873 |
|
| 1874 |
o The server can allow the security policy of the current filehandle |
| 1875 |
to override that of the saved filehandle, and so return NFS4_OK. |
| 1876 |
|
| 1877 |
<span class="h3"><a class="selflink" id="section-2.7" href="#section-2.7">2.7</a>. Minor Versioning</span> |
| 1878 |
|
| 1879 |
To address the requirement of an NFS protocol that can evolve as the |
| 1880 |
need arises, the NFSv4.1 protocol contains the rules and framework to |
| 1881 |
allow for future minor changes or versioning. |
| 1882 |
|
| 1883 |
The base assumption with respect to minor versioning is that any |
| 1884 |
future accepted minor version will be documented in one or more |
| 1885 |
Standards Track RFCs. Minor version 0 of the NFSv4 protocol is |
| 1886 |
represented by [<a href="#ref-30" title=""Network File System (NFS) version 4 Protocol"">30</a>], and minor version 1 is represented by this RFC. |
| 1887 |
The COMPOUND and CB_COMPOUND procedures support the encoding of the |
| 1888 |
minor version being requested by the client. |
| 1889 |
|
| 1890 |
The following items represent the basic rules for the development of |
| 1891 |
minor versions. Note that a future minor version may modify or add |
| 1892 |
to the following rules as part of the minor version definition. |
| 1893 |
|
| 1894 |
|
| 1895 |
|
| 1896 |
|
| 1897 |
|
| 1898 |
|
| 1899 |
|
| 1900 |
<span class="grey">Shepler, et al. Standards Track [Page 34]</span></pre> |
| 1901 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-35" ></span> |
| 1902 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1903 |
|
| 1904 |
|
| 1905 |
1. Procedures are not added or deleted. |
| 1906 |
|
| 1907 |
To maintain the general RPC model, NFSv4 minor versions will not |
| 1908 |
add to or delete procedures from the NFS program. |
| 1909 |
|
| 1910 |
2. Minor versions may add operations to the COMPOUND and |
| 1911 |
CB_COMPOUND procedures. |
| 1912 |
|
| 1913 |
The addition of operations to the COMPOUND and CB_COMPOUND |
| 1914 |
procedures does not affect the RPC model. |
| 1915 |
|
| 1916 |
* Minor versions may append attributes to the bitmap4 that |
| 1917 |
represents sets of attributes and to the fattr4 that |
| 1918 |
represents sets of attribute values. |
| 1919 |
|
| 1920 |
This allows for the expansion of the attribute model to allow |
| 1921 |
for future growth or adaptation. |
| 1922 |
|
| 1923 |
* Minor version X must append any new attributes after the last |
| 1924 |
documented attribute. |
| 1925 |
|
| 1926 |
Since attribute results are specified as an opaque array of |
| 1927 |
per-attribute, XDR-encoded results, the complexity of adding |
| 1928 |
new attributes in the midst of the current definitions would |
| 1929 |
be too burdensome. |
| 1930 |
|
| 1931 |
3. Minor versions must not modify the structure of an existing |
| 1932 |
operation's arguments or results. |
| 1933 |
|
| 1934 |
Again, the complexity of handling multiple structure definitions |
| 1935 |
for a single operation is too burdensome. New operations should |
| 1936 |
be added instead of modifying existing structures for a minor |
| 1937 |
version. |
| 1938 |
|
| 1939 |
This rule does not preclude the following adaptations in a minor |
| 1940 |
version: |
| 1941 |
|
| 1942 |
* adding bits to flag fields, such as new attributes to |
| 1943 |
GETATTR's bitmap4 data type, and providing corresponding |
| 1944 |
variants of opaque arrays, such as a notify4 used together |
| 1945 |
with such bitmaps |
| 1946 |
|
| 1947 |
* adding bits to existing attributes like ACLs that have flag |
| 1948 |
words |
| 1949 |
|
| 1950 |
* extending enumerated types (including NFS4ERR_*) with new |
| 1951 |
values |
| 1952 |
|
| 1953 |
|
| 1954 |
|
| 1955 |
|
| 1956 |
<span class="grey">Shepler, et al. Standards Track [Page 35]</span></pre> |
| 1957 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-36" ></span> |
| 1958 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 1959 |
|
| 1960 |
|
| 1961 |
* adding cases to a switched union |
| 1962 |
|
| 1963 |
4. Minor versions must not modify the structure of existing |
| 1964 |
attributes. |
| 1965 |
|
| 1966 |
5. Minor versions must not delete operations. |
| 1967 |
|
| 1968 |
This prevents the potential reuse of a particular operation |
| 1969 |
"slot" in a future minor version. |
| 1970 |
|
| 1971 |
6. Minor versions must not delete attributes. |
| 1972 |
|
| 1973 |
7. Minor versions must not delete flag bits or enumeration values. |
| 1974 |
|
| 1975 |
8. Minor versions may declare an operation MUST NOT be implemented. |
| 1976 |
|
| 1977 |
Specifying that an operation MUST NOT be implemented is |
| 1978 |
equivalent to obsoleting an operation. For the client, it means |
| 1979 |
that the operation MUST NOT be sent to the server. For the |
| 1980 |
server, an NFS error can be returned as opposed to "dropping" |
| 1981 |
the request as an XDR decode error. This approach allows for |
| 1982 |
the obsolescence of an operation while maintaining its structure |
| 1983 |
so that a future minor version can reintroduce the operation. |
| 1984 |
|
| 1985 |
1. Minor versions may declare that an attribute MUST NOT be |
| 1986 |
implemented. |
| 1987 |
|
| 1988 |
2. Minor versions may declare that a flag bit or enumeration |
| 1989 |
value MUST NOT be implemented. |
| 1990 |
|
| 1991 |
9. Minor versions may downgrade features from REQUIRED to |
| 1992 |
RECOMMENDED, or RECOMMENDED to OPTIONAL. |
| 1993 |
|
| 1994 |
10. Minor versions may upgrade features from OPTIONAL to |
| 1995 |
RECOMMENDED, or RECOMMENDED to REQUIRED. |
| 1996 |
|
| 1997 |
11. A client and server that support minor version X SHOULD support |
| 1998 |
minor versions zero through X-1 as well. |
| 1999 |
|
| 2000 |
12. Except for infrastructural changes, a minor version must not |
| 2001 |
introduce REQUIRED new features. |
| 2002 |
|
| 2003 |
This rule allows for the introduction of new functionality and |
| 2004 |
forces the use of implementation experience before designating a |
| 2005 |
feature as REQUIRED. On the other hand, some classes of |
| 2006 |
features are infrastructural and have broad effects. Allowing |
| 2007 |
infrastructural features to be RECOMMENDED or OPTIONAL |
| 2008 |
complicates implementation of the minor version. |
| 2009 |
|
| 2010 |
|
| 2011 |
|
| 2012 |
<span class="grey">Shepler, et al. Standards Track [Page 36]</span></pre> |
| 2013 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-37" ></span> |
| 2014 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2015 |
|
| 2016 |
|
| 2017 |
13. A client MUST NOT attempt to use a stateid, filehandle, or |
| 2018 |
similar returned object from the COMPOUND procedure with minor |
| 2019 |
version X for another COMPOUND procedure with minor version Y, |
| 2020 |
where X != Y. |
| 2021 |
|
| 2022 |
<span class="h3"><a class="selflink" id="section-2.8" href="#section-2.8">2.8</a>. Non-RPC-Based Security Services</span> |
| 2023 |
|
| 2024 |
As described in <a href="#section-2.2.1.1.1.1">Section 2.2.1.1.1.1</a>, NFSv4.1 relies on RPC for |
| 2025 |
identification, authentication, integrity, and privacy. NFSv4.1 |
| 2026 |
itself provides or enables additional security services as described |
| 2027 |
in the next several subsections. |
| 2028 |
|
| 2029 |
<span class="h4"><a class="selflink" id="section-2.8.1" href="#section-2.8.1">2.8.1</a>. Authorization</span> |
| 2030 |
|
| 2031 |
Authorization to access a file object via an NFSv4.1 operation is |
| 2032 |
ultimately determined by the NFSv4.1 server. A client can |
| 2033 |
predetermine its access to a file object via the OPEN (<a href="#section-18.16">Section 18.16</a>) |
| 2034 |
and the ACCESS (<a href="#section-18.1">Section 18.1</a>) operations. |
| 2035 |
|
| 2036 |
Principals with appropriate access rights can modify the |
| 2037 |
authorization on a file object via the SETATTR (<a href="#section-18.30">Section 18.30</a>) |
| 2038 |
operation. Attributes that affect access rights include mode, owner, |
| 2039 |
owner_group, acl, dacl, and sacl. See <a href="#section-5">Section 5</a>. |
| 2040 |
|
| 2041 |
<span class="h4"><a class="selflink" id="section-2.8.2" href="#section-2.8.2">2.8.2</a>. Auditing</span> |
| 2042 |
|
| 2043 |
NFSv4.1 provides auditing on a per-file object basis, via the acl and |
| 2044 |
sacl attributes as described in <a href="#section-6">Section 6</a>. It is outside the scope |
| 2045 |
of this specification to specify audit log formats or management |
| 2046 |
policies. |
| 2047 |
|
| 2048 |
<span class="h4"><a class="selflink" id="section-2.8.3" href="#section-2.8.3">2.8.3</a>. Intrusion Detection</span> |
| 2049 |
|
| 2050 |
NFSv4.1 provides alarm control on a per-file object basis, via the |
| 2051 |
acl and sacl attributes as described in <a href="#section-6">Section 6</a>. Alarms may serve |
| 2052 |
as the basis for intrusion detection. It is outside the scope of |
| 2053 |
this specification to specify heuristics for detecting intrusion via |
| 2054 |
alarms. |
| 2055 |
|
| 2056 |
<span class="h3"><a class="selflink" id="section-2.9" href="#section-2.9">2.9</a>. Transport Layers</span> |
| 2057 |
|
| 2058 |
<span class="h4"><a class="selflink" id="section-2.9.1" href="#section-2.9.1">2.9.1</a>. REQUIRED and RECOMMENDED Properties of Transports</span> |
| 2059 |
|
| 2060 |
NFSv4.1 works over Remote Direct Memory Access (RDMA) and non-RDMA- |
| 2061 |
based transports with the following attributes: |
| 2062 |
|
| 2063 |
|
| 2064 |
|
| 2065 |
|
| 2066 |
|
| 2067 |
|
| 2068 |
<span class="grey">Shepler, et al. Standards Track [Page 37]</span></pre> |
| 2069 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-38" ></span> |
| 2070 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2071 |
|
| 2072 |
|
| 2073 |
o The transport supports reliable delivery of data, which NFSv4.1 |
| 2074 |
requires but neither NFSv4.1 nor RPC has facilities for ensuring |
| 2075 |
[<a href="#ref-34" title=""Improving the Performance and Correctness of an NFS Server"">34</a>]. |
| 2076 |
|
| 2077 |
o The transport delivers data in the order it was sent. Ordered |
| 2078 |
delivery simplifies detection of transmit errors, and simplifies |
| 2079 |
the sending of arbitrary sized requests and responses via the |
| 2080 |
record marking protocol [<a href="#ref-3" title=""RPC: Remote Procedure Call Protocol Specification Version 2"">3</a>]. |
| 2081 |
|
| 2082 |
Where an NFSv4.1 implementation supports operation over the IP |
| 2083 |
network protocol, any transport used between NFS and IP MUST be among |
| 2084 |
the IETF-approved congestion control transport protocols. At the |
| 2085 |
time this document was written, the only two transports that had the |
| 2086 |
above attributes were TCP and the Stream Control Transmission |
| 2087 |
Protocol (SCTP). To enhance the possibilities for interoperability, |
| 2088 |
an NFSv4.1 implementation MUST support operation over the TCP |
| 2089 |
transport protocol. |
| 2090 |
|
| 2091 |
Even if NFSv4.1 is used over a non-IP network protocol, it is |
| 2092 |
RECOMMENDED that the transport support congestion control. |
| 2093 |
|
| 2094 |
It is permissible for a connectionless transport to be used under |
| 2095 |
NFSv4.1; however, reliable and in-order delivery of data combined |
| 2096 |
with congestion control by the connectionless transport is REQUIRED. |
| 2097 |
As a consequence, UDP by itself MUST NOT be used as an NFSv4.1 |
| 2098 |
transport. NFSv4.1 assumes that a client transport address and |
| 2099 |
server transport address used to send data over a transport together |
| 2100 |
constitute a connection, even if the underlying transport eschews the |
| 2101 |
concept of a connection. |
| 2102 |
|
| 2103 |
<span class="h4"><a class="selflink" id="section-2.9.2" href="#section-2.9.2">2.9.2</a>. Client and Server Transport Behavior</span> |
| 2104 |
|
| 2105 |
If a connection-oriented transport (e.g., TCP) is used, the client |
| 2106 |
and server SHOULD use long-lived connections for at least three |
| 2107 |
reasons: |
| 2108 |
|
| 2109 |
1. This will prevent the weakening of the transport's congestion |
| 2110 |
control mechanisms via short-lived connections. |
| 2111 |
|
| 2112 |
2. This will improve performance for the WAN environment by |
| 2113 |
eliminating the need for connection setup handshakes. |
| 2114 |
|
| 2115 |
3. The NFSv4.1 callback model differs from NFSv4.0, and requires the |
| 2116 |
client and server to maintain a client-created backchannel (see |
| 2117 |
<a href="#section-2.10.3.1">Section 2.10.3.1</a>) for the server to use. |
| 2118 |
|
| 2119 |
In order to reduce congestion, if a connection-oriented transport is |
| 2120 |
used, and the request is not the NULL procedure: |
| 2121 |
|
| 2122 |
|
| 2123 |
|
| 2124 |
<span class="grey">Shepler, et al. Standards Track [Page 38]</span></pre> |
| 2125 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-39" ></span> |
| 2126 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2127 |
|
| 2128 |
|
| 2129 |
o A requester MUST NOT retry a request unless the connection the |
| 2130 |
request was sent over was lost before the reply was received. |
| 2131 |
|
| 2132 |
o A replier MUST NOT silently drop a request, even if the request is |
| 2133 |
a retry. (The silent drop behavior of RPCSEC_GSS [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>] does not |
| 2134 |
apply because this behavior happens at the RPCSEC_GSS layer, a |
| 2135 |
lower layer in the request processing.) Instead, the replier |
| 2136 |
SHOULD return an appropriate error (see <a href="#section-2.10.6.1">Section 2.10.6.1</a>), or it |
| 2137 |
MAY disconnect the connection. |
| 2138 |
|
| 2139 |
When sending a reply, the replier MUST send the reply to the same |
| 2140 |
full network address (e.g., if using an IP-based transport, the |
| 2141 |
source port of the requester is part of the full network address) |
| 2142 |
from which the requester sent the request. If using a connection- |
| 2143 |
oriented transport, replies MUST be sent on the same connection from |
| 2144 |
which the request was received. |
| 2145 |
|
| 2146 |
If a connection is dropped after the replier receives the request but |
| 2147 |
before the replier sends the reply, the replier might have a pending |
| 2148 |
reply. If a connection is established with the same source and |
| 2149 |
destination full network address as the dropped connection, then the |
| 2150 |
replier MUST NOT send the reply until the requester retries the |
| 2151 |
request. The reason for this prohibition is that the requester MAY |
| 2152 |
retry a request over a different connection (provided that connection |
| 2153 |
is associated with the original request's session). |
| 2154 |
|
| 2155 |
When using RDMA transports, there are other reasons for not |
| 2156 |
tolerating retries over the same connection: |
| 2157 |
|
| 2158 |
o RDMA transports use "credits" to enforce flow control, where a |
| 2159 |
credit is a right to a peer to transmit a message. If one peer |
| 2160 |
were to retransmit a request (or reply), it would consume an |
| 2161 |
additional credit. If the replier retransmitted a reply, it would |
| 2162 |
certainly result in an RDMA connection loss, since the requester |
| 2163 |
would typically only post a single receive buffer for each |
| 2164 |
request. If the requester retransmitted a request, the additional |
| 2165 |
credit consumed on the server might lead to RDMA connection |
| 2166 |
failure unless the client accounted for it and decreased its |
| 2167 |
available credit, leading to wasted resources. |
| 2168 |
|
| 2169 |
o RDMA credits present a new issue to the reply cache in NFSv4.1. |
| 2170 |
The reply cache may be used when a connection within a session is |
| 2171 |
lost, such as after the client reconnects. Credit information is |
| 2172 |
a dynamic property of the RDMA connection, and stale values must |
| 2173 |
not be replayed from the cache. This implies that the reply cache |
| 2174 |
contents must not be blindly used when replies are sent from it, |
| 2175 |
and credit information appropriate to the channel must be |
| 2176 |
refreshed by the RPC layer. |
| 2177 |
|
| 2178 |
|
| 2179 |
|
| 2180 |
<span class="grey">Shepler, et al. Standards Track [Page 39]</span></pre> |
| 2181 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-40" ></span> |
| 2182 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2183 |
|
| 2184 |
|
| 2185 |
In addition, as described in <a href="#section-2.10.6.2">Section 2.10.6.2</a>, while a session is |
| 2186 |
active, the NFSv4.1 requester MUST NOT stop waiting for a reply. |
| 2187 |
|
| 2188 |
<span class="h4"><a class="selflink" id="section-2.9.3" href="#section-2.9.3">2.9.3</a>. Ports</span> |
| 2189 |
|
| 2190 |
Historically, NFSv3 servers have listened over TCP port 2049. The |
| 2191 |
registered port 2049 [<a href="#ref-35" title=""Assigned Numbers: RFC 1700 is Replaced by an On-line Database"">35</a>] for the NFS protocol should be the default |
| 2192 |
configuration. NFSv4.1 clients SHOULD NOT use the RPC binding |
| 2193 |
protocols as described in [<a href="#ref-36" title=""Binding Protocols for ONC RPC Version 2"">36</a>]. |
| 2194 |
|
| 2195 |
<span class="h3"><a class="selflink" id="section-2.10" href="#section-2.10">2.10</a>. Session</span> |
| 2196 |
|
| 2197 |
NFSv4.1 clients and servers MUST support and MUST use the session |
| 2198 |
feature as described in this section. |
| 2199 |
|
| 2200 |
<span class="h4"><a class="selflink" id="section-2.10.1" href="#section-2.10.1">2.10.1</a>. Motivation and Overview</span> |
| 2201 |
|
| 2202 |
Previous versions and minor versions of NFS have suffered from the |
| 2203 |
following: |
| 2204 |
|
| 2205 |
o Lack of support for Exactly Once Semantics (EOS). This includes |
| 2206 |
lack of support for EOS through server failure and recovery. |
| 2207 |
|
| 2208 |
o Limited callback support, including no support for sending |
| 2209 |
callbacks through firewalls, and races between replies to normal |
| 2210 |
requests and callbacks. |
| 2211 |
|
| 2212 |
o Limited trunking over multiple network paths. |
| 2213 |
|
| 2214 |
o Requiring machine credentials for fully secure operation. |
| 2215 |
|
| 2216 |
Through the introduction of a session, NFSv4.1 addresses the above |
| 2217 |
shortfalls with practical solutions: |
| 2218 |
|
| 2219 |
o EOS is enabled by a reply cache with a bounded size, making it |
| 2220 |
feasible to keep the cache in persistent storage and enable EOS |
| 2221 |
through server failure and recovery. One reason that previous |
| 2222 |
revisions of NFS did not support EOS was because some EOS |
| 2223 |
approaches often limited parallelism. As will be explained in |
| 2224 |
<a href="#section-2.10.6">Section 2.10.6</a>, NFSv4.1 supports both EOS and unlimited |
| 2225 |
parallelism. |
| 2226 |
|
| 2227 |
o The NFSv4.1 client (defined in <a href="#section-1.6">Section 1.6</a>, Paragraph 2) creates |
| 2228 |
transport connections and provides them to the server to use for |
| 2229 |
sending callback requests, thus solving the firewall issue |
| 2230 |
(<a href="#section-18.34">Section 18.34</a>). Races between responses from client requests and |
| 2231 |
|
| 2232 |
|
| 2233 |
|
| 2234 |
|
| 2235 |
|
| 2236 |
<span class="grey">Shepler, et al. Standards Track [Page 40]</span></pre> |
| 2237 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-41" ></span> |
| 2238 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2239 |
|
| 2240 |
|
| 2241 |
callbacks caused by the requests are detected via the session's |
| 2242 |
sequencing properties that are a consequence of EOS |
| 2243 |
(<a href="#section-2.10.6.3">Section 2.10.6.3</a>). |
| 2244 |
|
| 2245 |
o The NFSv4.1 client can associate an arbitrary number of |
| 2246 |
connections with the session, and thus provide trunking |
| 2247 |
(<a href="#section-2.10.5">Section 2.10.5</a>). |
| 2248 |
|
| 2249 |
o The NFSv4.1 client and server produces a session key independent |
| 2250 |
of client and server machine credentials which can be used to |
| 2251 |
compute a digest for protecting critical session management |
| 2252 |
operations (<a href="#section-2.10.8.3">Section 2.10.8.3</a>). |
| 2253 |
|
| 2254 |
o The NFSv4.1 client can also create secure RPCSEC_GSS contexts for |
| 2255 |
use by the session's backchannel that do not require the server to |
| 2256 |
authenticate to a client machine principal (<a href="#section-2.10.8.2">Section 2.10.8.2</a>). |
| 2257 |
|
| 2258 |
A session is a dynamically created, long-lived server object created |
| 2259 |
by a client and used over time from one or more transport |
| 2260 |
connections. Its function is to maintain the server's state relative |
| 2261 |
to the connection(s) belonging to a client instance. This state is |
| 2262 |
entirely independent of the connection itself, and indeed the state |
| 2263 |
exists whether or not the connection exists. A client may have one |
| 2264 |
or more sessions associated with it so that client-associated state |
| 2265 |
may be accessed using any of the sessions associated with that |
| 2266 |
client's client ID, when connections are associated with those |
| 2267 |
sessions. When no connections are associated with any of a client |
| 2268 |
ID's sessions for an extended time, such objects as locks, opens, |
| 2269 |
delegations, layouts, etc. are subject to expiration. The session |
| 2270 |
serves as an object representing a means of access by a client to the |
| 2271 |
associated client state on the server, independent of the physical |
| 2272 |
means of access to that state. |
| 2273 |
|
| 2274 |
A single client may create multiple sessions. A single session MUST |
| 2275 |
NOT serve multiple clients. |
| 2276 |
|
| 2277 |
<span class="h4"><a class="selflink" id="section-2.10.2" href="#section-2.10.2">2.10.2</a>. NFSv4 Integration</span> |
| 2278 |
|
| 2279 |
Sessions are part of NFSv4.1 and not NFSv4.0. Normally, a major |
| 2280 |
infrastructure change such as sessions would require a new major |
| 2281 |
version number to an Open Network Computing (ONC) RPC program like |
| 2282 |
NFS. However, because NFSv4 encapsulates its functionality in a |
| 2283 |
single procedure, COMPOUND, and because COMPOUND can support an |
| 2284 |
arbitrary number of operations, sessions have been added to NFSv4.1 |
| 2285 |
with little difficulty. COMPOUND includes a minor version number |
| 2286 |
field, and for NFSv4.1 this minor version is set to 1. When the |
| 2287 |
NFSv4 server processes a COMPOUND with the minor version set to 1, it |
| 2288 |
expects a different set of operations than it does for NFSv4.0. |
| 2289 |
|
| 2290 |
|
| 2291 |
|
| 2292 |
<span class="grey">Shepler, et al. Standards Track [Page 41]</span></pre> |
| 2293 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-42" ></span> |
| 2294 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2295 |
|
| 2296 |
|
| 2297 |
NFSv4.1 defines the SEQUENCE operation, which is required for every |
| 2298 |
COMPOUND that operates over an established session, with the |
| 2299 |
exception of some session administration operations, such as |
| 2300 |
DESTROY_SESSION (<a href="#section-18.37">Section 18.37</a>). |
| 2301 |
|
| 2302 |
<span class="h5"><a class="selflink" id="section-2.10.2.1" href="#section-2.10.2.1">2.10.2.1</a>. SEQUENCE and CB_SEQUENCE</span> |
| 2303 |
|
| 2304 |
In NFSv4.1, when the SEQUENCE operation is present, it MUST be the |
| 2305 |
first operation in the COMPOUND procedure. The primary purpose of |
| 2306 |
SEQUENCE is to carry the session identifier. The session identifier |
| 2307 |
associates all other operations in the COMPOUND procedure with a |
| 2308 |
particular session. SEQUENCE also contains required information for |
| 2309 |
maintaining EOS (see <a href="#section-2.10.6">Section 2.10.6</a>). Session-enabled NFSv4.1 |
| 2310 |
COMPOUND requests thus have the form: |
| 2311 |
|
| 2312 |
+-----+--------------+-----------+------------+-----------+---- |
| 2313 |
| tag | minorversion | numops |SEQUENCE op | op + args | ... |
| 2314 |
| | (== 1) | (limited) | + args | | |
| 2315 |
+-----+--------------+-----------+------------+-----------+---- |
| 2316 |
|
| 2317 |
and the replies have the form: |
| 2318 |
|
| 2319 |
+------------+-----+--------+-------------------------------+--// |
| 2320 |
|last status | tag | numres |status + SEQUENCE op + results | // |
| 2321 |
+------------+-----+--------+-------------------------------+--// |
| 2322 |
//-----------------------+---- |
| 2323 |
// status + op + results | ... |
| 2324 |
//-----------------------+---- |
| 2325 |
|
| 2326 |
A CB_COMPOUND procedure request and reply has a similar form to |
| 2327 |
COMPOUND, but instead of a SEQUENCE operation, there is a CB_SEQUENCE |
| 2328 |
operation. CB_COMPOUND also has an additional field called |
| 2329 |
"callback_ident", which is superfluous in NFSv4.1 and MUST be ignored |
| 2330 |
by the client. CB_SEQUENCE has the same information as SEQUENCE, and |
| 2331 |
also includes other information needed to resolve callback races |
| 2332 |
(<a href="#section-2.10.6.3">Section 2.10.6.3</a>). |
| 2333 |
|
| 2334 |
<span class="h5"><a class="selflink" id="section-2.10.2.2" href="#section-2.10.2.2">2.10.2.2</a>. Client ID and Session Association</span> |
| 2335 |
|
| 2336 |
Each client ID (<a href="#section-2.4">Section 2.4</a>) can have zero or more active sessions. |
| 2337 |
A client ID and associated session are required to perform file |
| 2338 |
access in NFSv4.1. Each time a session is used (whether by a client |
| 2339 |
sending a request to the server or the client replying to a callback |
| 2340 |
request from the server), the state leased to its associated client |
| 2341 |
ID is automatically renewed. |
| 2342 |
|
| 2343 |
|
| 2344 |
|
| 2345 |
|
| 2346 |
|
| 2347 |
|
| 2348 |
<span class="grey">Shepler, et al. Standards Track [Page 42]</span></pre> |
| 2349 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-43" ></span> |
| 2350 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2351 |
|
| 2352 |
|
| 2353 |
State (which can consist of share reservations, locks, delegations, |
| 2354 |
and layouts (<a href="#section-1.7.4">Section 1.7.4</a>)) is tied to the client ID. Client state |
| 2355 |
is not tied to any individual session. Successive state changing |
| 2356 |
operations from a given state owner MAY go over different sessions, |
| 2357 |
provided the session is associated with the same client ID. A |
| 2358 |
callback MAY arrive over a different session than that of the request |
| 2359 |
that originally acquired the state pertaining to the callback. For |
| 2360 |
example, if session A is used to acquire a delegation, a request to |
| 2361 |
recall the delegation MAY arrive over session B if both sessions are |
| 2362 |
associated with the same client ID. Sections <a href="#section-2.10.8.1">2.10.8.1</a> and <a href="#section-2.10.8.2">2.10.8.2</a> |
| 2363 |
discuss the security considerations around callbacks. |
| 2364 |
|
| 2365 |
<span class="h4"><a class="selflink" id="section-2.10.3" href="#section-2.10.3">2.10.3</a>. Channels</span> |
| 2366 |
|
| 2367 |
A channel is not a connection. A channel represents the direction |
| 2368 |
ONC RPC requests are sent. |
| 2369 |
|
| 2370 |
Each session has one or two channels: the fore channel and the |
| 2371 |
backchannel. Because there are at most two channels per session, and |
| 2372 |
because each channel has a distinct purpose, channels are not |
| 2373 |
assigned identifiers. |
| 2374 |
|
| 2375 |
The fore channel is used for ordinary requests from the client to the |
| 2376 |
server, and carries COMPOUND requests and responses. A session |
| 2377 |
always has a fore channel. |
| 2378 |
|
| 2379 |
The backchannel is used for callback requests from server to client, |
| 2380 |
and carries CB_COMPOUND requests and responses. Whether or not there |
| 2381 |
is a backchannel is a decision made by the client; however, many |
| 2382 |
features of NFSv4.1 require a backchannel. NFSv4.1 servers MUST |
| 2383 |
support backchannels. |
| 2384 |
|
| 2385 |
Each session has resources for each channel, including separate reply |
| 2386 |
caches (see <a href="#section-2.10.6.1">Section 2.10.6.1</a>). Note that even the backchannel |
| 2387 |
requires a reply cache (or, at least, a slot table in order to detect |
| 2388 |
retries) because some callback operations are nonidempotent. |
| 2389 |
|
| 2390 |
<span class="h5"><a class="selflink" id="section-2.10.3.1" href="#section-2.10.3.1">2.10.3.1</a>. Association of Connections, Channels, and Sessions</span> |
| 2391 |
|
| 2392 |
Each channel is associated with zero or more transport connections |
| 2393 |
(whether of the same transport protocol or different transport |
| 2394 |
protocols). A connection can be associated with one channel or both |
| 2395 |
channels of a session; the client and server negotiate whether a |
| 2396 |
connection will carry traffic for one channel or both channels via |
| 2397 |
the CREATE_SESSION (<a href="#section-18.36">Section 18.36</a>) and the BIND_CONN_TO_SESSION |
| 2398 |
(<a href="#section-18.34">Section 18.34</a>) operations. When a session is created via |
| 2399 |
CREATE_SESSION, the connection that transported the CREATE_SESSION |
| 2400 |
request is automatically associated with the fore channel, and |
| 2401 |
|
| 2402 |
|
| 2403 |
|
| 2404 |
<span class="grey">Shepler, et al. Standards Track [Page 43]</span></pre> |
| 2405 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-44" ></span> |
| 2406 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2407 |
|
| 2408 |
|
| 2409 |
optionally the backchannel. If the client specifies no state |
| 2410 |
protection (<a href="#section-18.35">Section 18.35</a>) when the session is created, then when |
| 2411 |
SEQUENCE is transmitted on a different connection, the connection is |
| 2412 |
automatically associated with the fore channel of the session |
| 2413 |
specified in the SEQUENCE operation. |
| 2414 |
|
| 2415 |
A connection's association with a session is not exclusive. A |
| 2416 |
connection associated with the channel(s) of one session may be |
| 2417 |
simultaneously associated with the channel(s) of other sessions |
| 2418 |
including sessions associated with other client IDs. |
| 2419 |
|
| 2420 |
It is permissible for connections of multiple transport types to be |
| 2421 |
associated with the same channel. For example, both TCP and RDMA |
| 2422 |
connections can be associated with the fore channel. In the event an |
| 2423 |
RDMA and non-RDMA connection are associated with the same channel, |
| 2424 |
the maximum number of slots SHOULD be at least one more than the |
| 2425 |
total number of RDMA credits (<a href="#section-2.10.6.1">Section 2.10.6.1</a>). This way, if all |
| 2426 |
RDMA credits are used, the non-RDMA connection can have at least one |
| 2427 |
outstanding request. If a server supports multiple transport types, |
| 2428 |
it MUST allow a client to associate connections from each transport |
| 2429 |
to a channel. |
| 2430 |
|
| 2431 |
It is permissible for a connection of one type of transport to be |
| 2432 |
associated with the fore channel, and a connection of a different |
| 2433 |
type to be associated with the backchannel. |
| 2434 |
|
| 2435 |
<span class="h4"><a class="selflink" id="section-2.10.4" href="#section-2.10.4">2.10.4</a>. Server Scope</span> |
| 2436 |
|
| 2437 |
Servers each specify a server scope value in the form of an opaque |
| 2438 |
string eir_server_scope returned as part of the results of an |
| 2439 |
EXCHANGE_ID operation. The purpose of the server scope is to allow a |
| 2440 |
group of servers to indicate to clients that a set of servers sharing |
| 2441 |
the same server scope value has arranged to use compatible values of |
| 2442 |
otherwise opaque identifiers. Thus, the identifiers generated by one |
| 2443 |
server of that set may be presented to another of that same scope. |
| 2444 |
|
| 2445 |
The use of such compatible values does not imply that a value |
| 2446 |
generated by one server will always be accepted by another. In most |
| 2447 |
cases, it will not. However, a server will not accept a value |
| 2448 |
generated by another inadvertently. When it does accept it, it will |
| 2449 |
be because it is recognized as valid and carrying the same meaning as |
| 2450 |
on another server of the same scope. |
| 2451 |
|
| 2452 |
When servers are of the same server scope, this compatibility of |
| 2453 |
values applies to the follow identifiers: |
| 2454 |
|
| 2455 |
|
| 2456 |
|
| 2457 |
|
| 2458 |
|
| 2459 |
|
| 2460 |
<span class="grey">Shepler, et al. Standards Track [Page 44]</span></pre> |
| 2461 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-45" ></span> |
| 2462 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2463 |
|
| 2464 |
|
| 2465 |
o Filehandle values. A filehandle value accepted by two servers of |
| 2466 |
the same server scope denotes the same object. A WRITE operation |
| 2467 |
sent to one server is reflected immediately in a READ sent to the |
| 2468 |
other, and locks obtained on one server conflict with those |
| 2469 |
requested on the other. |
| 2470 |
|
| 2471 |
o Session ID values. A session ID value accepted by two servers of |
| 2472 |
the same server scope denotes the same session. |
| 2473 |
|
| 2474 |
o Client ID values. A client ID value accepted as valid by two |
| 2475 |
servers of the same server scope is associated with two clients |
| 2476 |
with the same client owner and verifier. |
| 2477 |
|
| 2478 |
o State ID values. A state ID value is recognized as valid when the |
| 2479 |
corresponding client ID is recognized as valid. If the same |
| 2480 |
stateid value is accepted as valid on two servers of the same |
| 2481 |
scope and the client IDs on the two servers represent the same |
| 2482 |
client owner and verifier, then the two stateid values designate |
| 2483 |
the same set of locks and are for the same file. |
| 2484 |
|
| 2485 |
o Server owner values. When the server scope values are the same, |
| 2486 |
server owner value may be validly compared. In cases where the |
| 2487 |
server scope values are different, server owner values are treated |
| 2488 |
as different even if they contain all identical bytes. |
| 2489 |
|
| 2490 |
The coordination among servers required to provide such compatibility |
| 2491 |
can be quite minimal, and limited to a simple partition of the ID |
| 2492 |
space. The recognition of common values requires additional |
| 2493 |
implementation, but this can be tailored to the specific situations |
| 2494 |
in which that recognition is desired. |
| 2495 |
|
| 2496 |
Clients will have occasion to compare the server scope values of |
| 2497 |
multiple servers under a number of circumstances, each of which will |
| 2498 |
be discussed under the appropriate functional section: |
| 2499 |
|
| 2500 |
o When server owner values received in response to EXCHANGE_ID |
| 2501 |
operations sent to multiple network addresses are compared for the |
| 2502 |
purpose of determining the validity of various forms of trunking, |
| 2503 |
as described in <a href="#section-2.10.5">Section 2.10.5</a>. |
| 2504 |
|
| 2505 |
o When network or server reconfiguration causes the same network |
| 2506 |
address to possibly be directed to different servers, with the |
| 2507 |
necessity for the client to determine when lock reclaim should be |
| 2508 |
attempted, as described in <a href="#section-8.4.2.1">Section 8.4.2.1</a>. |
| 2509 |
|
| 2510 |
o When file system migration causes the transfer of responsibility |
| 2511 |
for a file system between servers and the client needs to |
| 2512 |
determine whether state has been transferred with the file system |
| 2513 |
|
| 2514 |
|
| 2515 |
|
| 2516 |
<span class="grey">Shepler, et al. Standards Track [Page 45]</span></pre> |
| 2517 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-46" ></span> |
| 2518 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2519 |
|
| 2520 |
|
| 2521 |
(as described in <a href="#section-11.7.7">Section 11.7.7</a>) or whether the client needs to |
| 2522 |
reclaim state on a similar basis as in the case of server restart, |
| 2523 |
as described in <a href="#section-8.4.2">Section 8.4.2</a>. |
| 2524 |
|
| 2525 |
When two replies from EXCHANGE_ID, each from two different server |
| 2526 |
network addresses, have the same server scope, there are a number of |
| 2527 |
ways a client can validate that the common server scope is due to two |
| 2528 |
servers cooperating in a group. |
| 2529 |
|
| 2530 |
o If both EXCHANGE_ID requests were sent with RPCSEC_GSS |
| 2531 |
authentication and the server principal is the same for both |
| 2532 |
targets, the equality of server scope is validated. It is |
| 2533 |
RECOMMENDED that two servers intending to share the same server |
| 2534 |
scope also share the same principal name. |
| 2535 |
|
| 2536 |
o The client may accept the appearance of the second server in the |
| 2537 |
fs_locations or fs_locations_info attribute for a relevant file |
| 2538 |
system. For example, if there is a migration event for a |
| 2539 |
particular file system or there are locks to be reclaimed on a |
| 2540 |
particular file system, the attributes for that particular file |
| 2541 |
system may be used. The client sends the GETATTR request to the |
| 2542 |
first server for the fs_locations or fs_locations_info attribute |
| 2543 |
with RPCSEC_GSS authentication. It may need to do this in advance |
| 2544 |
of the need to verify the common server scope. If the client |
| 2545 |
successfully authenticates the reply to GETATTR, and the GETATTR |
| 2546 |
request and reply containing the fs_locations or fs_locations_info |
| 2547 |
attribute refers to the second server, then the equality of server |
| 2548 |
scope is supported. A client may choose to limit the use of this |
| 2549 |
form of support to information relevant to the specific file |
| 2550 |
system involved (e.g. a file system being migrated). |
| 2551 |
|
| 2552 |
<span class="h4"><a class="selflink" id="section-2.10.5" href="#section-2.10.5">2.10.5</a>. Trunking</span> |
| 2553 |
|
| 2554 |
Trunking is the use of multiple connections between a client and |
| 2555 |
server in order to increase the speed of data transfer. NFSv4.1 |
| 2556 |
supports two types of trunking: session trunking and client ID |
| 2557 |
trunking. |
| 2558 |
|
| 2559 |
NFSv4.1 servers MUST support both forms of trunking within the |
| 2560 |
context of a single server network address and MUST support both |
| 2561 |
forms within the context of the set of network addresses used to |
| 2562 |
access a single server. NFSv4.1 servers in a clustered configuration |
| 2563 |
MAY allow network addresses for different servers to use client ID |
| 2564 |
trunking. |
| 2565 |
|
| 2566 |
Clients may use either form of trunking as long as they do not, when |
| 2567 |
trunking between different server network addresses, violate the |
| 2568 |
servers' mandates as to the kinds of trunking to be allowed (see |
| 2569 |
|
| 2570 |
|
| 2571 |
|
| 2572 |
<span class="grey">Shepler, et al. Standards Track [Page 46]</span></pre> |
| 2573 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-47" ></span> |
| 2574 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2575 |
|
| 2576 |
|
| 2577 |
below). With regard to callback channels, the client MUST allow the |
| 2578 |
server to choose among all callback channels valid for a given client |
| 2579 |
ID and MUST support trunking when the connections supporting the |
| 2580 |
backchannel allow session or client ID trunking to be used for |
| 2581 |
callbacks. |
| 2582 |
|
| 2583 |
Session trunking is essentially the association of multiple |
| 2584 |
connections, each with potentially different target and/or source |
| 2585 |
network addresses, to the same session. When the target network |
| 2586 |
addresses (server addresses) of the two connections are the same, the |
| 2587 |
server MUST support such session trunking. When the target network |
| 2588 |
addresses are different, the server MAY indicate such support using |
| 2589 |
the data returned by the EXCHANGE_ID operation (see below). |
| 2590 |
|
| 2591 |
Client ID trunking is the association of multiple sessions to the |
| 2592 |
same client ID. Servers MUST support client ID trunking for two |
| 2593 |
target network addresses whenever they allow session trunking for |
| 2594 |
those same two network addresses. In addition, a server MAY, by |
| 2595 |
presenting the same major server owner ID (<a href="#section-2.5">Section 2.5</a>) and server |
| 2596 |
scope (<a href="#section-2.10.4">Section 2.10.4</a>), allow an additional case of client ID |
| 2597 |
trunking. When two servers return the same major server owner and |
| 2598 |
server scope, it means that the two servers are cooperating on |
| 2599 |
locking state management, which is a prerequisite for client ID |
| 2600 |
trunking. |
| 2601 |
|
| 2602 |
Distinguishing when the client is allowed to use session and client |
| 2603 |
ID trunking requires understanding how the results of the EXCHANGE_ID |
| 2604 |
(<a href="#section-18.35">Section 18.35</a>) operation identify a server. Suppose a client sends |
| 2605 |
EXCHANGE_IDs over two different connections, each with a possibly |
| 2606 |
different target network address, but each EXCHANGE_ID operation has |
| 2607 |
the same value in the eia_clientowner field. If the same NFSv4.1 |
| 2608 |
server is listening over each connection, then each EXCHANGE_ID |
| 2609 |
result MUST return the same values of eir_clientid, |
| 2610 |
eir_server_owner.so_major_id, and eir_server_scope. The client can |
| 2611 |
then treat each connection as referring to the same server (subject |
| 2612 |
to verification; see <a href="#section-2.10.5.1">Section 2.10.5.1</a> later in this section), and it |
| 2613 |
can use each connection to trunk requests and replies. The client's |
| 2614 |
choice is whether session trunking or client ID trunking applies. |
| 2615 |
|
| 2616 |
Session Trunking. If the eia_clientowner argument is the same in two |
| 2617 |
different EXCHANGE_ID requests, and the eir_clientid, |
| 2618 |
eir_server_owner.so_major_id, eir_server_owner.so_minor_id, and |
| 2619 |
eir_server_scope results match in both EXCHANGE_ID results, then |
| 2620 |
the client is permitted to perform session trunking. If the |
| 2621 |
client has no session mapping to the tuple of eir_clientid, |
| 2622 |
eir_server_owner.so_major_id, eir_server_scope, and |
| 2623 |
eir_server_owner.so_minor_id, then it creates the session via a |
| 2624 |
CREATE_SESSION operation over one of the connections, which |
| 2625 |
|
| 2626 |
|
| 2627 |
|
| 2628 |
<span class="grey">Shepler, et al. Standards Track [Page 47]</span></pre> |
| 2629 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-48" ></span> |
| 2630 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2631 |
|
| 2632 |
|
| 2633 |
associates the connection to the session. If there is a session |
| 2634 |
for the tuple, the client can send BIND_CONN_TO_SESSION to |
| 2635 |
associate the connection to the session. |
| 2636 |
|
| 2637 |
Of course, if the client does not desire to use session trunking, |
| 2638 |
it is not required to do so. It can invoke CREATE_SESSION on the |
| 2639 |
connection. This will result in client ID trunking as described |
| 2640 |
below. It can also decide to drop the connection if it does not |
| 2641 |
choose to use trunking. |
| 2642 |
|
| 2643 |
Client ID Trunking. If the eia_clientowner argument is the same in |
| 2644 |
two different EXCHANGE_ID requests, and the eir_clientid, |
| 2645 |
eir_server_owner.so_major_id, and eir_server_scope results match |
| 2646 |
in both EXCHANGE_ID results, then the client is permitted to |
| 2647 |
perform client ID trunking (regardless of whether the |
| 2648 |
eir_server_owner.so_minor_id results match). The client can |
| 2649 |
associate each connection with different sessions, where each |
| 2650 |
session is associated with the same server. |
| 2651 |
|
| 2652 |
The client completes the act of client ID trunking by invoking |
| 2653 |
CREATE_SESSION on each connection, using the same client ID that |
| 2654 |
was returned in eir_clientid. These invocations create two |
| 2655 |
sessions and also associate each connection with its respective |
| 2656 |
session. The client is free to decline to use client ID trunking |
| 2657 |
by simply dropping the connection at this point. |
| 2658 |
|
| 2659 |
When doing client ID trunking, locking state is shared across |
| 2660 |
sessions associated with that same client ID. This requires the |
| 2661 |
server to coordinate state across sessions. |
| 2662 |
|
| 2663 |
The client should be prepared for the possibility that |
| 2664 |
eir_server_owner values may be different on subsequent EXCHANGE_ID |
| 2665 |
requests made to the same network address, as a result of various |
| 2666 |
sorts of reconfiguration events. When this happens and the changes |
| 2667 |
result in the invalidation of previously valid forms of trunking, the |
| 2668 |
client should cease to use those forms, either by dropping |
| 2669 |
connections or by adding sessions. For a discussion of lock reclaim |
| 2670 |
as it relates to such reconfiguration events, see <a href="#section-8.4.2.1">Section 8.4.2.1</a>. |
| 2671 |
|
| 2672 |
<span class="h5"><a class="selflink" id="section-2.10.5.1" href="#section-2.10.5.1">2.10.5.1</a>. Verifying Claims of Matching Server Identity</span> |
| 2673 |
|
| 2674 |
When two servers over two connections claim matching or partially |
| 2675 |
matching eir_server_owner, eir_server_scope, and eir_clientid values, |
| 2676 |
the client does not have to trust the servers' claims. The client |
| 2677 |
may verify these claims before trunking traffic in the following |
| 2678 |
ways: |
| 2679 |
|
| 2680 |
|
| 2681 |
|
| 2682 |
|
| 2683 |
|
| 2684 |
<span class="grey">Shepler, et al. Standards Track [Page 48]</span></pre> |
| 2685 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-49" ></span> |
| 2686 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2687 |
|
| 2688 |
|
| 2689 |
o For session trunking, clients SHOULD reliably verify if |
| 2690 |
connections between different network paths are in fact associated |
| 2691 |
with the same NFSv4.1 server and usable on the same session, and |
| 2692 |
servers MUST allow clients to perform reliable verification. When |
| 2693 |
a client ID is created, the client SHOULD specify that |
| 2694 |
BIND_CONN_TO_SESSION is to be verified according to the SP4_SSV or |
| 2695 |
SP4_MACH_CRED (<a href="#section-18.35">Section 18.35</a>) state protection options. For |
| 2696 |
SP4_SSV, reliable verification depends on a shared secret (the |
| 2697 |
SSV) that is established via the SET_SSV (<a href="#section-18.47">Section 18.47</a>) |
| 2698 |
operation. |
| 2699 |
|
| 2700 |
When a new connection is associated with the session (via the |
| 2701 |
BIND_CONN_TO_SESSION operation, see <a href="#section-18.34">Section 18.34</a>), if the client |
| 2702 |
specified SP4_SSV state protection for the BIND_CONN_TO_SESSION |
| 2703 |
operation, the client MUST send the BIND_CONN_TO_SESSION with |
| 2704 |
RPCSEC_GSS protection, using integrity or privacy, and an |
| 2705 |
RPCSEC_GSS handle created with the GSS SSV mechanism |
| 2706 |
(<a href="#section-2.10.9">Section 2.10.9</a>). |
| 2707 |
|
| 2708 |
If the client mistakenly tries to associate a connection to a |
| 2709 |
session of a wrong server, the server will either reject the |
| 2710 |
attempt because it is not aware of the session identifier of the |
| 2711 |
BIND_CONN_TO_SESSION arguments, or it will reject the attempt |
| 2712 |
because the RPCSEC_GSS authentication fails. Even if the server |
| 2713 |
mistakenly or maliciously accepts the connection association |
| 2714 |
attempt, the RPCSEC_GSS verifier it computes in the response will |
| 2715 |
not be verified by the client, so the client will know it cannot |
| 2716 |
use the connection for trunking the specified session. |
| 2717 |
|
| 2718 |
If the client specified SP4_MACH_CRED state protection, the |
| 2719 |
BIND_CONN_TO_SESSION operation will use RPCSEC_GSS integrity or |
| 2720 |
privacy, using the same credential that was used when the client |
| 2721 |
ID was created. Mutual authentication via RPCSEC_GSS assures the |
| 2722 |
client that the connection is associated with the correct session |
| 2723 |
of the correct server. |
| 2724 |
|
| 2725 |
|
| 2726 |
o For client ID trunking, the client has at least two options for |
| 2727 |
verifying that the same client ID obtained from two different |
| 2728 |
EXCHANGE_ID operations came from the same server. The first |
| 2729 |
option is to use RPCSEC_GSS authentication when sending each |
| 2730 |
EXCHANGE_ID operation. Each time an EXCHANGE_ID is sent with |
| 2731 |
RPCSEC_GSS authentication, the client notes the principal name of |
| 2732 |
the GSS target. If the EXCHANGE_ID results indicate that client |
| 2733 |
ID trunking is possible, and the GSS targets' principal names are |
| 2734 |
the same, the servers are the same and client ID trunking is |
| 2735 |
allowed. |
| 2736 |
|
| 2737 |
|
| 2738 |
|
| 2739 |
|
| 2740 |
<span class="grey">Shepler, et al. Standards Track [Page 49]</span></pre> |
| 2741 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-50" ></span> |
| 2742 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2743 |
|
| 2744 |
|
| 2745 |
The second option for verification is to use SP4_SSV protection. |
| 2746 |
When the client sends EXCHANGE_ID, it specifies SP4_SSV |
| 2747 |
protection. The first EXCHANGE_ID the client sends always has to |
| 2748 |
be confirmed by a CREATE_SESSION call. The client then sends |
| 2749 |
SET_SSV. Later, the client sends EXCHANGE_ID to a second |
| 2750 |
destination network address different from the one the first |
| 2751 |
EXCHANGE_ID was sent to. The client checks that each EXCHANGE_ID |
| 2752 |
reply has the same eir_clientid, eir_server_owner.so_major_id, and |
| 2753 |
eir_server_scope. If so, the client verifies the claim by sending |
| 2754 |
a CREATE_SESSION operation to the second destination address, |
| 2755 |
protected with RPCSEC_GSS integrity using an RPCSEC_GSS handle |
| 2756 |
returned by the second EXCHANGE_ID. If the server accepts the |
| 2757 |
CREATE_SESSION request, and if the client verifies the RPCSEC_GSS |
| 2758 |
verifier and integrity codes, then the client has proof the second |
| 2759 |
server knows the SSV, and thus the two servers are cooperating for |
| 2760 |
the purposes of specifying server scope and client ID trunking. |
| 2761 |
|
| 2762 |
<span class="h4"><a class="selflink" id="section-2.10.6" href="#section-2.10.6">2.10.6</a>. Exactly Once Semantics</span> |
| 2763 |
|
| 2764 |
Via the session, NFSv4.1 offers exactly once semantics (EOS) for |
| 2765 |
requests sent over a channel. EOS is supported on both the fore |
| 2766 |
channel and backchannel. |
| 2767 |
|
| 2768 |
Each COMPOUND or CB_COMPOUND request that is sent with a leading |
| 2769 |
SEQUENCE or CB_SEQUENCE operation MUST be executed by the receiver |
| 2770 |
exactly once. This requirement holds regardless of whether the |
| 2771 |
request is sent with reply caching specified (see |
| 2772 |
<a href="#section-2.10.6.1.3">Section 2.10.6.1.3</a>). The requirement holds even if the requester is |
| 2773 |
sending the request over a session created between a pNFS data client |
| 2774 |
and pNFS data server. To understand the rationale for this |
| 2775 |
requirement, divide the requests into three classifications: |
| 2776 |
|
| 2777 |
o Non-idempotent requests. |
| 2778 |
|
| 2779 |
o Idempotent modifying requests. |
| 2780 |
|
| 2781 |
o Idempotent non-modifying requests. |
| 2782 |
|
| 2783 |
An example of a non-idempotent request is RENAME. Obviously, if a |
| 2784 |
replier executes the same RENAME request twice, and the first |
| 2785 |
execution succeeds, the re-execution will fail. If the replier |
| 2786 |
returns the result from the re-execution, this result is incorrect. |
| 2787 |
Therefore, EOS is required for non-idempotent requests. |
| 2788 |
|
| 2789 |
|
| 2790 |
|
| 2791 |
|
| 2792 |
|
| 2793 |
|
| 2794 |
|
| 2795 |
|
| 2796 |
<span class="grey">Shepler, et al. Standards Track [Page 50]</span></pre> |
| 2797 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-51" ></span> |
| 2798 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2799 |
|
| 2800 |
|
| 2801 |
An example of an idempotent modifying request is a COMPOUND request |
| 2802 |
containing a WRITE operation. Repeated execution of the same WRITE |
| 2803 |
has the same effect as execution of that WRITE a single time. |
| 2804 |
Nevertheless, enforcing EOS for WRITEs and other idempotent modifying |
| 2805 |
requests is necessary to avoid data corruption. |
| 2806 |
|
| 2807 |
Suppose a client sends WRITE A to a noncompliant server that does not |
| 2808 |
enforce EOS, and receives no response, perhaps due to a network |
| 2809 |
partition. The client reconnects to the server and re-sends WRITE A. |
| 2810 |
Now, the server has outstanding two instances of A. The server can |
| 2811 |
be in a situation in which it executes and replies to the retry of A, |
| 2812 |
while the first A is still waiting in the server's internal I/O |
| 2813 |
system for some resource. Upon receiving the reply to the second |
| 2814 |
attempt of WRITE A, the client believes its WRITE is done so it is |
| 2815 |
free to send WRITE B, which overlaps the byte-range of A. When the |
| 2816 |
original A is dispatched from the server's I/O system and executed |
| 2817 |
(thus the second time A will have been written), then what has been |
| 2818 |
written by B can be overwritten and thus corrupted. |
| 2819 |
|
| 2820 |
An example of an idempotent non-modifying request is a COMPOUND |
| 2821 |
containing SEQUENCE, PUTFH, READLINK, and nothing else. The re- |
| 2822 |
execution of such a request will not cause data corruption or produce |
| 2823 |
an incorrect result. Nonetheless, to keep the implementation simple, |
| 2824 |
the replier MUST enforce EOS for all requests, whether or not |
| 2825 |
idempotent and non-modifying. |
| 2826 |
|
| 2827 |
Note that true and complete EOS is not possible unless the server |
| 2828 |
persists the reply cache in stable storage, and unless the server is |
| 2829 |
somehow implemented to never require a restart (indeed, if such a |
| 2830 |
server exists, the distinction between a reply cache kept in stable |
| 2831 |
storage versus one that is not is one without meaning). See |
| 2832 |
<a href="#section-2.10.6.5">Section 2.10.6.5</a> for a discussion of persistence in the reply cache. |
| 2833 |
Regardless, even if the server does not persist the reply cache, EOS |
| 2834 |
improves robustness and correctness over previous versions of NFS |
| 2835 |
because the legacy duplicate request/reply caches were based on the |
| 2836 |
ONC RPC transaction identifier (XID). <a href="#section-2.10.6.1">Section 2.10.6.1</a> explains the |
| 2837 |
shortcomings of the XID as a basis for a reply cache and describes |
| 2838 |
how NFSv4.1 sessions improve upon the XID. |
| 2839 |
|
| 2840 |
<span class="h5"><a class="selflink" id="section-2.10.6.1" href="#section-2.10.6.1">2.10.6.1</a>. Slot Identifiers and Reply Cache</span> |
| 2841 |
|
| 2842 |
The RPC layer provides a transaction ID (XID), which, while required |
| 2843 |
to be unique, is not convenient for tracking requests for two |
| 2844 |
reasons. First, the XID is only meaningful to the requester; it |
| 2845 |
cannot be interpreted by the replier except to test for equality with |
| 2846 |
previously sent requests. When consulting an RPC-based duplicate |
| 2847 |
request cache, the opaqueness of the XID requires a computationally |
| 2848 |
expensive look up (often via a hash that includes XID and source |
| 2849 |
|
| 2850 |
|
| 2851 |
|
| 2852 |
<span class="grey">Shepler, et al. Standards Track [Page 51]</span></pre> |
| 2853 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-52" ></span> |
| 2854 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2855 |
|
| 2856 |
|
| 2857 |
address). NFSv4.1 requests use a non-opaque slot ID, which is an |
| 2858 |
index into a slot table, which is far more efficient. Second, |
| 2859 |
because RPC requests can be executed by the replier in any order, |
| 2860 |
there is no bound on the number of requests that may be outstanding |
| 2861 |
at any time. To achieve perfect EOS, using ONC RPC would require |
| 2862 |
storing all replies in the reply cache. XIDs are 32 bits; storing |
| 2863 |
over four billion (2^32) replies in the reply cache is not practical. |
| 2864 |
In practice, previous versions of NFS have chosen to store a fixed |
| 2865 |
number of replies in the cache, and to use a least recently used |
| 2866 |
(LRU) approach to replacing cache entries with new entries when the |
| 2867 |
cache is full. In NFSv4.1, the number of outstanding requests is |
| 2868 |
bounded by the size of the slot table, and a sequence ID per slot is |
| 2869 |
used to tell the replier when it is safe to delete a cached reply. |
| 2870 |
|
| 2871 |
In the NFSv4.1 reply cache, when the requester sends a new request, |
| 2872 |
it selects a slot ID in the range 0..N, where N is the replier's |
| 2873 |
current maximum slot ID granted to the requester on the session over |
| 2874 |
which the request is to be sent. The value of N starts out as equal |
| 2875 |
to ca_maxrequests - 1 (<a href="#section-18.36">Section 18.36</a>), but can be adjusted by the |
| 2876 |
response to SEQUENCE or CB_SEQUENCE as described later in this |
| 2877 |
section. The slot ID must be unused by any of the requests that the |
| 2878 |
requester has already active on the session. "Unused" here means the |
| 2879 |
requester has no outstanding request for that slot ID. |
| 2880 |
|
| 2881 |
A slot contains a sequence ID and the cached reply corresponding to |
| 2882 |
the request sent with that sequence ID. The sequence ID is a 32-bit |
| 2883 |
unsigned value, and is therefore in the range 0..0xFFFFFFFF (2^32 - |
| 2884 |
1). The first time a slot is used, the requester MUST specify a |
| 2885 |
sequence ID of one (<a href="#section-18.36">Section 18.36</a>). Each time a slot is reused, the |
| 2886 |
request MUST specify a sequence ID that is one greater than that of |
| 2887 |
the previous request on the slot. If the previous sequence ID was |
| 2888 |
0xFFFFFFFF, then the next request for the slot MUST have the sequence |
| 2889 |
ID set to zero (i.e., (2^32 - 1) + 1 mod 2^32). |
| 2890 |
|
| 2891 |
The sequence ID accompanies the slot ID in each request. It is for |
| 2892 |
the critical check at the replier: it used to efficiently determine |
| 2893 |
whether a request using a certain slot ID is a retransmit or a new, |
| 2894 |
never-before-seen request. It is not feasible for the requester to |
| 2895 |
assert that it is retransmitting to implement this, because for any |
| 2896 |
given request the requester cannot know whether the replier has seen |
| 2897 |
it unless the replier actually replies. Of course, if the requester |
| 2898 |
has seen the reply, the requester would not retransmit. |
| 2899 |
|
| 2900 |
The replier compares each received request's sequence ID with the |
| 2901 |
last one previously received for that slot ID, to see if the new |
| 2902 |
request is: |
| 2903 |
|
| 2904 |
|
| 2905 |
|
| 2906 |
|
| 2907 |
|
| 2908 |
<span class="grey">Shepler, et al. Standards Track [Page 52]</span></pre> |
| 2909 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-53" ></span> |
| 2910 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2911 |
|
| 2912 |
|
| 2913 |
o A new request, in which the sequence ID is one greater than that |
| 2914 |
previously seen in the slot (accounting for sequence wraparound). |
| 2915 |
The replier proceeds to execute the new request, and the replier |
| 2916 |
MUST increase the slot's sequence ID by one. |
| 2917 |
|
| 2918 |
o A retransmitted request, in which the sequence ID is equal to that |
| 2919 |
currently recorded in the slot. If the original request has |
| 2920 |
executed to completion, the replier returns the cached reply. See |
| 2921 |
<a href="#section-2.10.6.2">Section 2.10.6.2</a> for direction on how the replier deals with |
| 2922 |
retries of requests that are still in progress. |
| 2923 |
|
| 2924 |
o A misordered retry, in which the sequence ID is less than |
| 2925 |
(accounting for sequence wraparound) that previously seen in the |
| 2926 |
slot. The replier MUST return NFS4ERR_SEQ_MISORDERED (as the |
| 2927 |
result from SEQUENCE or CB_SEQUENCE). |
| 2928 |
|
| 2929 |
o A misordered new request, in which the sequence ID is two or more |
| 2930 |
than (accounting for sequence wraparound) that previously seen in |
| 2931 |
the slot. Note that because the sequence ID MUST wrap around to |
| 2932 |
zero once it reaches 0xFFFFFFFF, a misordered new request and a |
| 2933 |
misordered retry cannot be distinguished. Thus, the replier MUST |
| 2934 |
return NFS4ERR_SEQ_MISORDERED (as the result from SEQUENCE or |
| 2935 |
CB_SEQUENCE). |
| 2936 |
|
| 2937 |
Unlike the XID, the slot ID is always within a specific range; this |
| 2938 |
has two implications. The first implication is that for a given |
| 2939 |
session, the replier need only cache the results of a limited number |
| 2940 |
of COMPOUND requests. The second implication derives from the first, |
| 2941 |
which is that unlike XID-indexed reply caches (also known as |
| 2942 |
duplicate request caches - DRCs), the slot ID-based reply cache |
| 2943 |
cannot be overflowed. Through use of the sequence ID to identify |
| 2944 |
retransmitted requests, the replier does not need to actually cache |
| 2945 |
the request itself, reducing the storage requirements of the reply |
| 2946 |
cache further. These facilities make it practical to maintain all |
| 2947 |
the required entries for an effective reply cache. |
| 2948 |
|
| 2949 |
The slot ID, sequence ID, and session ID therefore take over the |
| 2950 |
traditional role of the XID and source network address in the |
| 2951 |
replier's reply cache implementation. This approach is considerably |
| 2952 |
more portable and completely robust -- it is not subject to the |
| 2953 |
reassignment of ports as clients reconnect over IP networks. In |
| 2954 |
addition, the RPC XID is not used in the reply cache, enhancing |
| 2955 |
robustness of the cache in the face of any rapid reuse of XIDs by the |
| 2956 |
requester. While the replier does not care about the XID for the |
| 2957 |
purposes of reply cache management (but the replier MUST return the |
| 2958 |
same XID that was in the request), nonetheless there are |
| 2959 |
considerations for the XID in NFSv4.1 that are the same as all other |
| 2960 |
|
| 2961 |
|
| 2962 |
|
| 2963 |
|
| 2964 |
<span class="grey">Shepler, et al. Standards Track [Page 53]</span></pre> |
| 2965 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-54" ></span> |
| 2966 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 2967 |
|
| 2968 |
|
| 2969 |
previous versions of NFS. The RPC XID remains in each message and |
| 2970 |
needs to be formulated in NFSv4.1 requests as in any other ONC RPC |
| 2971 |
request. The reasons include: |
| 2972 |
|
| 2973 |
o The RPC layer retains its existing semantics and implementation. |
| 2974 |
|
| 2975 |
o The requester and replier must be able to interoperate at the RPC |
| 2976 |
layer, prior to the NFSv4.1 decoding of the SEQUENCE or |
| 2977 |
CB_SEQUENCE operation. |
| 2978 |
|
| 2979 |
o If an operation is being used that does not start with SEQUENCE or |
| 2980 |
CB_SEQUENCE (e.g., BIND_CONN_TO_SESSION), then the RPC XID is |
| 2981 |
needed for correct operation to match the reply to the request. |
| 2982 |
|
| 2983 |
o The SEQUENCE or CB_SEQUENCE operation may generate an error. If |
| 2984 |
so, the embedded slot ID, sequence ID, and session ID (if present) |
| 2985 |
in the request will not be in the reply, and the requester has |
| 2986 |
only the XID to match the reply to the request. |
| 2987 |
|
| 2988 |
Given that well-formulated XIDs continue to be required, this begs |
| 2989 |
the question: why do SEQUENCE and CB_SEQUENCE replies have a session |
| 2990 |
ID, slot ID, and sequence ID? Having the session ID in the reply |
| 2991 |
means that the requester does not have to use the XID to look up the |
| 2992 |
session ID, which would be necessary if the connection were |
| 2993 |
associated with multiple sessions. Having the slot ID and sequence |
| 2994 |
ID in the reply means that the requester does not have to use the XID |
| 2995 |
to look up the slot ID and sequence ID. Furthermore, since the XID |
| 2996 |
is only 32 bits, it is too small to guarantee the re-association of a |
| 2997 |
reply with its request [<a href="#ref-37" title=""RPC XID Issues"">37</a>]; having session ID, slot ID, and sequence |
| 2998 |
ID in the reply allows the client to validate that the reply in fact |
| 2999 |
belongs to the matched request. |
| 3000 |
|
| 3001 |
The SEQUENCE (and CB_SEQUENCE) operation also carries a |
| 3002 |
"highest_slotid" value, which carries additional requester slot usage |
| 3003 |
information. The requester MUST always indicate the slot ID |
| 3004 |
representing the outstanding request with the highest-numbered slot |
| 3005 |
value. The requester should in all cases provide the most |
| 3006 |
conservative value possible, although it can be increased somewhat |
| 3007 |
above the actual instantaneous usage to maintain some minimum or |
| 3008 |
optimal level. This provides a way for the requester to yield unused |
| 3009 |
request slots back to the replier, which in turn can use the |
| 3010 |
information to reallocate resources. |
| 3011 |
|
| 3012 |
The replier responds with both a new target highest_slotid and an |
| 3013 |
enforced highest_slotid, described as follows: |
| 3014 |
|
| 3015 |
|
| 3016 |
|
| 3017 |
|
| 3018 |
|
| 3019 |
|
| 3020 |
<span class="grey">Shepler, et al. Standards Track [Page 54]</span></pre> |
| 3021 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-55" ></span> |
| 3022 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3023 |
|
| 3024 |
|
| 3025 |
o The target highest_slotid is an indication to the requester of the |
| 3026 |
highest_slotid the replier wishes the requester to be using. This |
| 3027 |
permits the replier to withdraw (or add) resources from a |
| 3028 |
requester that has been found to not be using them, in order to |
| 3029 |
more fairly share resources among a varying level of demand from |
| 3030 |
other requesters. The requester must always comply with the |
| 3031 |
replier's value updates, since they indicate newly established |
| 3032 |
hard limits on the requester's access to session resources. |
| 3033 |
However, because of request pipelining, the requester may have |
| 3034 |
active requests in flight reflecting prior values; therefore, the |
| 3035 |
replier must not immediately require the requester to comply. |
| 3036 |
|
| 3037 |
o The enforced highest_slotid indicates the highest slot ID the |
| 3038 |
requester is permitted to use on a subsequent SEQUENCE or |
| 3039 |
CB_SEQUENCE operation. The replier's enforced highest_slotid |
| 3040 |
SHOULD be no less than the highest_slotid the requester indicated |
| 3041 |
in the SEQUENCE or CB_SEQUENCE arguments. |
| 3042 |
|
| 3043 |
A requester can be intransigent with respect to lowering its |
| 3044 |
highest_slotid argument to a Sequence operation, i.e. the |
| 3045 |
requester continues to ignore the target highest_slotid in the |
| 3046 |
response to a Sequence operation, and continues to set its |
| 3047 |
highest_slotid argument to be higher than the target |
| 3048 |
highest_slotid. This can be considered particularly egregious |
| 3049 |
behavior when the replier knows there are no outstanding requests |
| 3050 |
with slot IDs higher than its target highest_slotid. When faced |
| 3051 |
with such intransigence, the replier is free to take more forceful |
| 3052 |
action, and MAY reply with a new enforced highest_slotid that is |
| 3053 |
less than its previous enforced highest_slotid. Thereafter, if |
| 3054 |
the requester continues to send requests with a highest_slotid |
| 3055 |
that is greater than the replier's new enforced highest_slotid, |
| 3056 |
the server MAY return NFS4ERR_BAD_HIGH_SLOT, unless the slot ID in |
| 3057 |
the request is greater than the new enforced highest_slotid and |
| 3058 |
the request is a retry. |
| 3059 |
|
| 3060 |
The replier SHOULD retain the slots it wants to retire until the |
| 3061 |
requester sends a request with a highest_slotid less than or equal |
| 3062 |
to the replier's new enforced highest_slotid. |
| 3063 |
|
| 3064 |
The requester can also be intransigent with respect to sending |
| 3065 |
non-retry requests that have a slot ID that exceeds the replier's |
| 3066 |
highest_slotid. Once the replier has forcibly lowered the |
| 3067 |
enforced highest_slotid, the requester is only allowed to send |
| 3068 |
retries on slots that exceed the replier's highest_slotid. If a |
| 3069 |
request is received with a slot ID that is higher than the new |
| 3070 |
enforced highest_slotid, and the sequence ID is one higher than |
| 3071 |
what is in the slot's reply cache, then the server can both retire |
| 3072 |
the slot and return NFS4ERR_BADSLOT (however, the server MUST NOT |
| 3073 |
|
| 3074 |
|
| 3075 |
|
| 3076 |
<span class="grey">Shepler, et al. Standards Track [Page 55]</span></pre> |
| 3077 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-56" ></span> |
| 3078 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3079 |
|
| 3080 |
|
| 3081 |
do one and not the other). The reason it is safe to retire the |
| 3082 |
slot is because by using the next sequence ID, the requester is |
| 3083 |
indicating it has received the previous reply for the slot. |
| 3084 |
|
| 3085 |
o The requester SHOULD use the lowest available slot when sending a |
| 3086 |
new request. This way, the replier may be able to retire slot |
| 3087 |
entries faster. However, where the replier is actively adjusting |
| 3088 |
its granted highest_slotid, it will not be able to use only the |
| 3089 |
receipt of the slot ID and highest_slotid in the request. Neither |
| 3090 |
the slot ID nor the highest_slotid used in a request may reflect |
| 3091 |
the replier's current idea of the requester's session limit, |
| 3092 |
because the request may have been sent from the requester before |
| 3093 |
the update was received. Therefore, in the downward adjustment |
| 3094 |
case, the replier may have to retain a number of reply cache |
| 3095 |
entries at least as large as the old value of maximum requests |
| 3096 |
outstanding, until it can infer that the requester has seen a |
| 3097 |
reply containing the new granted highest_slotid. The replier can |
| 3098 |
infer that the requester has seen such a reply when it receives a |
| 3099 |
new request with the same slot ID as the request replied to and |
| 3100 |
the next higher sequence ID. |
| 3101 |
|
| 3102 |
<span class="h6"><a class="selflink" id="section-2.10.6.1.1" href="#section-2.10.6.1.1">2.10.6.1.1</a>. Caching of SEQUENCE and CB_SEQUENCE Replies</span> |
| 3103 |
|
| 3104 |
When a SEQUENCE or CB_SEQUENCE operation is successfully executed, |
| 3105 |
its reply MUST always be cached. Specifically, session ID, sequence |
| 3106 |
ID, and slot ID MUST be cached in the reply cache. The reply from |
| 3107 |
SEQUENCE also includes the highest slot ID, target highest slot ID, |
| 3108 |
and status flags. Instead of caching these values, the server MAY |
| 3109 |
re-compute the values from the current state of the fore channel, |
| 3110 |
session, and/or client ID as appropriate. Similarly, the reply from |
| 3111 |
CB_SEQUENCE includes a highest slot ID and target highest slot ID. |
| 3112 |
The client MAY re-compute the values from the current state of the |
| 3113 |
session as appropriate. |
| 3114 |
|
| 3115 |
Regardless of whether or not a replier is re-computing highest slot |
| 3116 |
ID, target slot ID, and status on replies to retries, the requester |
| 3117 |
MUST NOT assume that the values are being re-computed whenever it |
| 3118 |
receives a reply after a retry is sent, since it has no way of |
| 3119 |
knowing whether the reply it has received was sent by the replier in |
| 3120 |
response to the retry or is a delayed response to the original |
| 3121 |
request. Therefore, it may be the case that highest slot ID, target |
| 3122 |
slot ID, or status bits may reflect the state of affairs when the |
| 3123 |
request was first executed. Although acting based on such delayed |
| 3124 |
information is valid, it may cause the receiver of the reply to do |
| 3125 |
unneeded work. Requesters MAY choose to send additional requests to |
| 3126 |
get the current state of affairs or use the state of affairs reported |
| 3127 |
by subsequent requests, in preference to acting immediately on data |
| 3128 |
that might be out of date. |
| 3129 |
|
| 3130 |
|
| 3131 |
|
| 3132 |
<span class="grey">Shepler, et al. Standards Track [Page 56]</span></pre> |
| 3133 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-57" ></span> |
| 3134 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3135 |
|
| 3136 |
|
| 3137 |
<span class="h6"><a class="selflink" id="section-2.10.6.1.2" href="#section-2.10.6.1.2">2.10.6.1.2</a>. Errors from SEQUENCE and CB_SEQUENCE</span> |
| 3138 |
|
| 3139 |
Any time SEQUENCE or CB_SEQUENCE returns an error, the sequence ID of |
| 3140 |
the slot MUST NOT change. The replier MUST NOT modify the reply |
| 3141 |
cache entry for the slot whenever an error is returned from SEQUENCE |
| 3142 |
or CB_SEQUENCE. |
| 3143 |
|
| 3144 |
<span class="h6"><a class="selflink" id="section-2.10.6.1.3" href="#section-2.10.6.1.3">2.10.6.1.3</a>. Optional Reply Caching</span> |
| 3145 |
|
| 3146 |
On a per-request basis, the requester can choose to direct the |
| 3147 |
replier to cache the reply to all operations after the first |
| 3148 |
operation (SEQUENCE or CB_SEQUENCE) via the sa_cachethis or |
| 3149 |
csa_cachethis fields of the arguments to SEQUENCE or CB_SEQUENCE. |
| 3150 |
The reason it would not direct the replier to cache the entire reply |
| 3151 |
is that the request is composed of all idempotent operations [<a href="#ref-34" title=""Improving the Performance and Correctness of an NFS Server"">34</a>]. |
| 3152 |
Caching the reply may offer little benefit. If the reply is too |
| 3153 |
large (see <a href="#section-2.10.6.4">Section 2.10.6.4</a>), it may not be cacheable anyway. Even |
| 3154 |
if the reply to idempotent request is small enough to cache, |
| 3155 |
unnecessarily caching the reply slows down the server and increases |
| 3156 |
RPC latency. |
| 3157 |
|
| 3158 |
Whether or not the requester requests the reply to be cached has no |
| 3159 |
effect on the slot processing. If the results of SEQUENCE or |
| 3160 |
CB_SEQUENCE are NFS4_OK, then the slot's sequence ID MUST be |
| 3161 |
incremented by one. If a requester does not direct the replier to |
| 3162 |
cache the reply, the replier MUST do one of following: |
| 3163 |
|
| 3164 |
o The replier can cache the entire original reply. Even though |
| 3165 |
sa_cachethis or csa_cachethis is FALSE, the replier is always free |
| 3166 |
to cache. It may choose this approach in order to simplify |
| 3167 |
implementation. |
| 3168 |
|
| 3169 |
o The replier enters into its reply cache a reply consisting of the |
| 3170 |
original results to the SEQUENCE or CB_SEQUENCE operation, and |
| 3171 |
with the next operation in COMPOUND or CB_COMPOUND having the |
| 3172 |
error NFS4ERR_RETRY_UNCACHED_REP. Thus, if the requester later |
| 3173 |
retries the request, it will get NFS4ERR_RETRY_UNCACHED_REP. If a |
| 3174 |
replier receives a retried Sequence operation where the reply to |
| 3175 |
the COMPOUND or CB_COMPOUND was not cached, then the replier, |
| 3176 |
|
| 3177 |
* MAY return NFS4ERR_RETRY_UNCACHED_REP in reply to a Sequence |
| 3178 |
operation if the Sequence operation is not the first operation |
| 3179 |
(granted, a requester that does so is in violation of the |
| 3180 |
NFSv4.1 protocol). |
| 3181 |
|
| 3182 |
* MUST NOT return NFS4ERR_RETRY_UNCACHED_REP in reply to a |
| 3183 |
Sequence operation if the Sequence operation is the first |
| 3184 |
operation. |
| 3185 |
|
| 3186 |
|
| 3187 |
|
| 3188 |
<span class="grey">Shepler, et al. Standards Track [Page 57]</span></pre> |
| 3189 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-58" ></span> |
| 3190 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3191 |
|
| 3192 |
|
| 3193 |
o If the second operation is an illegal operation, or an operation |
| 3194 |
that was legal in a previous minor version of NFSv4 and MUST NOT |
| 3195 |
be supported in the current minor version (e.g., SETCLIENTID), the |
| 3196 |
replier MUST NOT ever return NFS4ERR_RETRY_UNCACHED_REP. Instead |
| 3197 |
the replier MUST return NFS4ERR_OP_ILLEGAL or NFS4ERR_BADXDR or |
| 3198 |
NFS4ERR_NOTSUPP as appropriate. |
| 3199 |
|
| 3200 |
o If the second operation can result in another error status, the |
| 3201 |
replier MAY return a status other than NFS4ERR_RETRY_UNCACHED_REP, |
| 3202 |
provided the operation is not executed in such a way that the |
| 3203 |
state of the replier is changed. Examples of such an error status |
| 3204 |
include: NFS4ERR_NOTSUPP returned for an operation that is legal |
| 3205 |
but not REQUIRED in the current minor versions, and thus not |
| 3206 |
supported by the replier; NFS4ERR_SEQUENCE_POS; and |
| 3207 |
NFS4ERR_REQ_TOO_BIG. |
| 3208 |
|
| 3209 |
The discussion above assumes that the retried request matches the |
| 3210 |
original one. <a href="#section-2.10.6.1.3.1">Section 2.10.6.1.3.1</a> discusses what the replier might |
| 3211 |
do, and MUST do when original and retried requests do not match. |
| 3212 |
Since the replier may only cache a small amount of the information |
| 3213 |
that would be required to determine whether this is a case of a false |
| 3214 |
retry, the replier may send to the client any of the following |
| 3215 |
responses: |
| 3216 |
|
| 3217 |
o The cached reply to the original request (if the replier has |
| 3218 |
cached it in its entirety and the users of the original request |
| 3219 |
and retry match). |
| 3220 |
|
| 3221 |
o A reply that consists only of the Sequence operation with the |
| 3222 |
error NFS4ERR_FALSE_RETRY. |
| 3223 |
|
| 3224 |
o A reply consisting of the response to Sequence with the status |
| 3225 |
NFS4_OK, together with the second operation as it appeared in the |
| 3226 |
retried request with an error of NFS4ERR_RETRY_UNCACHED_REP or |
| 3227 |
other error as described above. |
| 3228 |
|
| 3229 |
o A reply that consists of the response to Sequence with the status |
| 3230 |
NFS4_OK, together with the second operation as it appeared in the |
| 3231 |
original request with an error of NFS4ERR_RETRY_UNCACHED_REP or |
| 3232 |
other error as described above. |
| 3233 |
|
| 3234 |
<span class="h6"><a class="selflink" id="section-2.10.6.1.3.1" href="#section-2.10.6.1.3.1">2.10.6.1.3.1</a>. False Retry</span> |
| 3235 |
|
| 3236 |
If a requester sent a Sequence operation with a slot ID and sequence |
| 3237 |
ID that are in the reply cache but the replier detected that the |
| 3238 |
retried request is not the same as the original request, including a |
| 3239 |
retry that has different operations or different arguments in the |
| 3240 |
operations from the original and a retry that uses a different |
| 3241 |
|
| 3242 |
|
| 3243 |
|
| 3244 |
<span class="grey">Shepler, et al. Standards Track [Page 58]</span></pre> |
| 3245 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-59" ></span> |
| 3246 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3247 |
|
| 3248 |
|
| 3249 |
principal in the RPC request's credential field that translates to a |
| 3250 |
different user, then this is a false retry. When the replier detects |
| 3251 |
a false retry, it is permitted (but not always obligated) to return |
| 3252 |
NFS4ERR_FALSE_RETRY in response to the Sequence operation when it |
| 3253 |
detects a false retry. |
| 3254 |
|
| 3255 |
Translations of particularly privileged user values to other users |
| 3256 |
due to the lack of appropriately secure credentials, as configured on |
| 3257 |
the replier, should be applied before determining whether the users |
| 3258 |
are the same or different. If the replier determines the users are |
| 3259 |
different between the original request and a retry, then the replier |
| 3260 |
MUST return NFS4ERR_FALSE_RETRY. |
| 3261 |
|
| 3262 |
If an operation of the retry is an illegal operation, or an operation |
| 3263 |
that was legal in a previous minor version of NFSv4 and MUST NOT be |
| 3264 |
supported in the current minor version (e.g., SETCLIENTID), the |
| 3265 |
replier MAY return NFS4ERR_FALSE_RETRY (and MUST do so if the users |
| 3266 |
of the original request and retry differ). Otherwise, the replier |
| 3267 |
MAY return NFS4ERR_OP_ILLEGAL or NFS4ERR_BADXDR or NFS4ERR_NOTSUPP as |
| 3268 |
appropriate. Note that the handling is in contrast for how the |
| 3269 |
replier deals with retries requests with no cached reply. The |
| 3270 |
difference is due to NFS4ERR_FALSE_RETRY being a valid error for only |
| 3271 |
Sequence operations, whereas NFS4ERR_RETRY_UNCACHED_REP is a valid |
| 3272 |
error for all operations except illegal operations and operations |
| 3273 |
that MUST NOT be supported in the current minor version of NFSv4. |
| 3274 |
|
| 3275 |
<span class="h5"><a class="selflink" id="section-2.10.6.2" href="#section-2.10.6.2">2.10.6.2</a>. Retry and Replay of Reply</span> |
| 3276 |
|
| 3277 |
A requester MUST NOT retry a request, unless the connection it used |
| 3278 |
to send the request disconnects. The requester can then reconnect |
| 3279 |
and re-send the request, or it can re-send the request over a |
| 3280 |
different connection that is associated with the same session. |
| 3281 |
|
| 3282 |
If the requester is a server wanting to re-send a callback operation |
| 3283 |
over the backchannel of a session, the requester of course cannot |
| 3284 |
reconnect because only the client can associate connections with the |
| 3285 |
backchannel. The server can re-send the request over another |
| 3286 |
connection that is bound to the same session's backchannel. If there |
| 3287 |
is no such connection, the server MUST indicate that the session has |
| 3288 |
no backchannel by setting the SEQ4_STATUS_CB_PATH_DOWN_SESSION flag |
| 3289 |
bit in the response to the next SEQUENCE operation from the client. |
| 3290 |
The client MUST then associate a connection with the session (or |
| 3291 |
destroy the session). |
| 3292 |
|
| 3293 |
Note that it is not fatal for a requester to retry without a |
| 3294 |
disconnect between the request and retry. However, the retry does |
| 3295 |
consume resources, especially with RDMA, where each request, retry or |
| 3296 |
not, consumes a credit. Retries for no reason, especially retries |
| 3297 |
|
| 3298 |
|
| 3299 |
|
| 3300 |
<span class="grey">Shepler, et al. Standards Track [Page 59]</span></pre> |
| 3301 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-60" ></span> |
| 3302 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3303 |
|
| 3304 |
|
| 3305 |
sent shortly after the previous attempt, are a poor use of network |
| 3306 |
bandwidth and defeat the purpose of a transport's inherent congestion |
| 3307 |
control system. |
| 3308 |
|
| 3309 |
A requester MUST wait for a reply to a request before using the slot |
| 3310 |
for another request. If it does not wait for a reply, then the |
| 3311 |
requester does not know what sequence ID to use for the slot on its |
| 3312 |
next request. For example, suppose a requester sends a request with |
| 3313 |
sequence ID 1, and does not wait for the response. The next time it |
| 3314 |
uses the slot, it sends the new request with sequence ID 2. If the |
| 3315 |
replier has not seen the request with sequence ID 1, then the replier |
| 3316 |
is not expecting sequence ID 2, and rejects the requester's new |
| 3317 |
request with NFS4ERR_SEQ_MISORDERED (as the result from SEQUENCE or |
| 3318 |
CB_SEQUENCE). |
| 3319 |
|
| 3320 |
RDMA fabrics do not guarantee that the memory handles (Steering Tags) |
| 3321 |
within each RPC/RDMA "chunk" [<a href="#ref-8" title=""Remote Direct Memory Access Transport for Remote Procedure Call"">8</a>] are valid on a scope outside that of |
| 3322 |
a single connection. Therefore, handles used by the direct |
| 3323 |
operations become invalid after connection loss. The server must |
| 3324 |
ensure that any RDMA operations that must be replayed from the reply |
| 3325 |
cache use the newly provided handle(s) from the most recent request. |
| 3326 |
|
| 3327 |
A retry might be sent while the original request is still in progress |
| 3328 |
on the replier. The replier SHOULD deal with the issue by returning |
| 3329 |
NFS4ERR_DELAY as the reply to SEQUENCE or CB_SEQUENCE operation, but |
| 3330 |
implementations MAY return NFS4ERR_MISORDERED. Since errors from |
| 3331 |
SEQUENCE and CB_SEQUENCE are never recorded in the reply cache, this |
| 3332 |
approach allows the results of the execution of the original request |
| 3333 |
to be properly recorded in the reply cache (assuming that the |
| 3334 |
requester specified the reply to be cached). |
| 3335 |
|
| 3336 |
<span class="h5"><a class="selflink" id="section-2.10.6.3" href="#section-2.10.6.3">2.10.6.3</a>. Resolving Server Callback Races</span> |
| 3337 |
|
| 3338 |
It is possible for server callbacks to arrive at the client before |
| 3339 |
the reply from related fore channel operations. For example, a |
| 3340 |
client may have been granted a delegation to a file it has opened, |
| 3341 |
but the reply to the OPEN (informing the client of the granting of |
| 3342 |
the delegation) may be delayed in the network. If a conflicting |
| 3343 |
operation arrives at the server, it will recall the delegation using |
| 3344 |
the backchannel, which may be on a different transport connection, |
| 3345 |
perhaps even a different network, or even a different session |
| 3346 |
associated with the same client ID. |
| 3347 |
|
| 3348 |
The presence of a session between the client and server alleviates |
| 3349 |
this issue. When a session is in place, each client request is |
| 3350 |
uniquely identified by its { session ID, slot ID, sequence ID } |
| 3351 |
triple. By the rules under which slot entries (reply cache entries) |
| 3352 |
are retired, the server has knowledge whether the client has "seen" |
| 3353 |
|
| 3354 |
|
| 3355 |
|
| 3356 |
<span class="grey">Shepler, et al. Standards Track [Page 60]</span></pre> |
| 3357 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-61" ></span> |
| 3358 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3359 |
|
| 3360 |
|
| 3361 |
each of the server's replies. The server can therefore provide |
| 3362 |
sufficient information to the client to allow it to disambiguate |
| 3363 |
between an erroneous or conflicting callback race condition. |
| 3364 |
|
| 3365 |
For each client operation that might result in some sort of server |
| 3366 |
callback, the server SHOULD "remember" the { session ID, slot ID, |
| 3367 |
sequence ID } triple of the client request until the slot ID |
| 3368 |
retirement rules allow the server to determine that the client has, |
| 3369 |
in fact, seen the server's reply. Until the time the { session ID, |
| 3370 |
slot ID, sequence ID } request triple can be retired, any recalls of |
| 3371 |
the associated object MUST carry an array of these referring |
| 3372 |
identifiers (in the CB_SEQUENCE operation's arguments), for the |
| 3373 |
benefit of the client. After this time, it is not necessary for the |
| 3374 |
server to provide this information in related callbacks, since it is |
| 3375 |
certain that a race condition can no longer occur. |
| 3376 |
|
| 3377 |
The CB_SEQUENCE operation that begins each server callback carries a |
| 3378 |
list of "referring" { session ID, slot ID, sequence ID } triples. If |
| 3379 |
the client finds the request corresponding to the referring session |
| 3380 |
ID, slot ID, and sequence ID to be currently outstanding (i.e., the |
| 3381 |
server's reply has not been seen by the client), it can determine |
| 3382 |
that the callback has raced the reply, and act accordingly. If the |
| 3383 |
client does not find the request corresponding to the referring |
| 3384 |
triple to be outstanding (including the case of a session ID |
| 3385 |
referring to a destroyed session), then there is no race with respect |
| 3386 |
to this triple. The server SHOULD limit the referring triples to |
| 3387 |
requests that refer to just those that apply to the objects referred |
| 3388 |
to in the CB_COMPOUND procedure. |
| 3389 |
|
| 3390 |
The client must not simply wait forever for the expected server reply |
| 3391 |
to arrive before responding to the CB_COMPOUND that won the race, |
| 3392 |
because it is possible that it will be delayed indefinitely. The |
| 3393 |
client should assume the likely case that the reply will arrive |
| 3394 |
within the average round-trip time for COMPOUND requests to the |
| 3395 |
server, and wait that period of time. If that period of time |
| 3396 |
expires, it can respond to the CB_COMPOUND with NFS4ERR_DELAY. There |
| 3397 |
are other scenarios under which callbacks may race replies. Among |
| 3398 |
them are pNFS layout recalls as described in <a href="#section-12.5.5.2">Section 12.5.5.2</a>. |
| 3399 |
|
| 3400 |
<span class="h5"><a class="selflink" id="section-2.10.6.4" href="#section-2.10.6.4">2.10.6.4</a>. COMPOUND and CB_COMPOUND Construction Issues</span> |
| 3401 |
|
| 3402 |
Very large requests and replies may pose both buffer management |
| 3403 |
issues (especially with RDMA) and reply cache issues. When the |
| 3404 |
session is created (<a href="#section-18.36">Section 18.36</a>), for each channel (fore and back), |
| 3405 |
the client and server negotiate the maximum-sized request they will |
| 3406 |
send or process (ca_maxrequestsize), the maximum-sized reply they |
| 3407 |
will return or process (ca_maxresponsesize), and the maximum-sized |
| 3408 |
reply they will store in the reply cache (ca_maxresponsesize_cached). |
| 3409 |
|
| 3410 |
|
| 3411 |
|
| 3412 |
<span class="grey">Shepler, et al. Standards Track [Page 61]</span></pre> |
| 3413 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-62" ></span> |
| 3414 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3415 |
|
| 3416 |
|
| 3417 |
If a request exceeds ca_maxrequestsize, the reply will have the |
| 3418 |
status NFS4ERR_REQ_TOO_BIG. A replier MAY return NFS4ERR_REQ_TOO_BIG |
| 3419 |
as the status for the first operation (SEQUENCE or CB_SEQUENCE) in |
| 3420 |
the request (which means that no operations in the request executed |
| 3421 |
and that the state of the slot in the reply cache is unchanged), or |
| 3422 |
it MAY opt to return it on a subsequent operation in the same |
| 3423 |
COMPOUND or CB_COMPOUND request (which means that at least one |
| 3424 |
operation did execute and that the state of the slot in the reply |
| 3425 |
cache does change). The replier SHOULD set NFS4ERR_REQ_TOO_BIG on |
| 3426 |
the operation that exceeds ca_maxrequestsize. |
| 3427 |
|
| 3428 |
If a reply exceeds ca_maxresponsesize, the reply will have the status |
| 3429 |
NFS4ERR_REP_TOO_BIG. A replier MAY return NFS4ERR_REP_TOO_BIG as the |
| 3430 |
status for the first operation (SEQUENCE or CB_SEQUENCE) in the |
| 3431 |
request, or it MAY opt to return it on a subsequent operation (in the |
| 3432 |
same COMPOUND or CB_COMPOUND reply). A replier MAY return |
| 3433 |
NFS4ERR_REP_TOO_BIG in the reply to SEQUENCE or CB_SEQUENCE, even if |
| 3434 |
the response would still exceed ca_maxresponsesize. |
| 3435 |
|
| 3436 |
If sa_cachethis or csa_cachethis is TRUE, then the replier MUST cache |
| 3437 |
a reply except if an error is returned by the SEQUENCE or CB_SEQUENCE |
| 3438 |
operation (see <a href="#section-2.10.6.1.2">Section 2.10.6.1.2</a>). If the reply exceeds |
| 3439 |
ca_maxresponsesize_cached (and sa_cachethis or csa_cachethis is |
| 3440 |
TRUE), then the server MUST return NFS4ERR_REP_TOO_BIG_TO_CACHE. |
| 3441 |
Even if NFS4ERR_REP_TOO_BIG_TO_CACHE (or any other error for that |
| 3442 |
matter) is returned on an operation other than the first operation |
| 3443 |
(SEQUENCE or CB_SEQUENCE), then the reply MUST be cached if |
| 3444 |
sa_cachethis or csa_cachethis is TRUE. For example, if a COMPOUND |
| 3445 |
has eleven operations, including SEQUENCE, the fifth operation is a |
| 3446 |
RENAME, and the tenth operation is a READ for one million bytes, the |
| 3447 |
server may return NFS4ERR_REP_TOO_BIG_TO_CACHE on the tenth |
| 3448 |
operation. Since the server executed several operations, especially |
| 3449 |
the non-idempotent RENAME, the client's request to cache the reply |
| 3450 |
needs to be honored in order for the correct operation of exactly |
| 3451 |
once semantics. If the client retries the request, the server will |
| 3452 |
have cached a reply that contains results for ten of the eleven |
| 3453 |
requested operations, with the tenth operation having a status of |
| 3454 |
NFS4ERR_REP_TOO_BIG_TO_CACHE. |
| 3455 |
|
| 3456 |
A client needs to take care that when sending operations that change |
| 3457 |
the current filehandle (except for PUTFH, PUTPUBFH, PUTROOTFH, and |
| 3458 |
RESTOREFH), it not exceed the maximum reply buffer before the GETFH |
| 3459 |
operation. Otherwise, the client will have to retry the operation |
| 3460 |
that changed the current filehandle, in order to obtain the desired |
| 3461 |
filehandle. For the OPEN operation (see <a href="#section-18.16">Section 18.16</a>), retry is not |
| 3462 |
always available as an option. The following guidelines for the |
| 3463 |
handling of filehandle-changing operations are advised: |
| 3464 |
|
| 3465 |
|
| 3466 |
|
| 3467 |
|
| 3468 |
<span class="grey">Shepler, et al. Standards Track [Page 62]</span></pre> |
| 3469 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-63" ></span> |
| 3470 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3471 |
|
| 3472 |
|
| 3473 |
o Within the same COMPOUND procedure, a client SHOULD send GETFH |
| 3474 |
immediately after a current filehandle-changing operation. A |
| 3475 |
client MUST send GETFH after a current filehandle-changing |
| 3476 |
operation that is also non-idempotent (e.g., the OPEN operation), |
| 3477 |
unless the operation is RESTOREFH. RESTOREFH is an exception, |
| 3478 |
because even though it is non-idempotent, the filehandle RESTOREFH |
| 3479 |
produced originated from an operation that is either idempotent |
| 3480 |
(e.g., PUTFH, LOOKUP), or non-idempotent (e.g., OPEN, CREATE). If |
| 3481 |
the origin is non-idempotent, then because the client MUST send |
| 3482 |
GETFH after the origin operation, the client can recover if |
| 3483 |
RESTOREFH returns an error. |
| 3484 |
|
| 3485 |
o A server MAY return NFS4ERR_REP_TOO_BIG or |
| 3486 |
NFS4ERR_REP_TOO_BIG_TO_CACHE (if sa_cachethis is TRUE) on a |
| 3487 |
filehandle-changing operation if the reply would be too large on |
| 3488 |
the next operation. |
| 3489 |
|
| 3490 |
o A server SHOULD return NFS4ERR_REP_TOO_BIG or |
| 3491 |
NFS4ERR_REP_TOO_BIG_TO_CACHE (if sa_cachethis is TRUE) on a |
| 3492 |
filehandle-changing, non-idempotent operation if the reply would |
| 3493 |
be too large on the next operation, especially if the operation is |
| 3494 |
OPEN. |
| 3495 |
|
| 3496 |
o A server MAY return NFS4ERR_UNSAFE_COMPOUND to a non-idempotent |
| 3497 |
current filehandle-changing operation, if it looks at the next |
| 3498 |
operation (in the same COMPOUND procedure) and finds it is not |
| 3499 |
GETFH. The server SHOULD do this if it is unable to determine in |
| 3500 |
advance whether the total response size would exceed |
| 3501 |
ca_maxresponsesize_cached or ca_maxresponsesize. |
| 3502 |
|
| 3503 |
<span class="h5"><a class="selflink" id="section-2.10.6.5" href="#section-2.10.6.5">2.10.6.5</a>. Persistence</span> |
| 3504 |
|
| 3505 |
Since the reply cache is bounded, it is practical for the reply cache |
| 3506 |
to persist across server restarts. The replier MUST persist the |
| 3507 |
following information if it agreed to persist the session (when the |
| 3508 |
session was created; see <a href="#section-18.36">Section 18.36</a>): |
| 3509 |
|
| 3510 |
o The session ID. |
| 3511 |
|
| 3512 |
o The slot table including the sequence ID and cached reply for each |
| 3513 |
slot. |
| 3514 |
|
| 3515 |
The above are sufficient for a replier to provide EOS semantics for |
| 3516 |
any requests that were sent and executed before the server restarted. |
| 3517 |
If the replier is a client, then there is no need for it to persist |
| 3518 |
any more information, unless the client will be persisting all other |
| 3519 |
state across client restart, in which case, the server will never see |
| 3520 |
any NFSv4.1-level protocol manifestation of a client restart. If the |
| 3521 |
|
| 3522 |
|
| 3523 |
|
| 3524 |
<span class="grey">Shepler, et al. Standards Track [Page 63]</span></pre> |
| 3525 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-64" ></span> |
| 3526 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3527 |
|
| 3528 |
|
| 3529 |
replier is a server, with just the slot table and session ID |
| 3530 |
persisting, any requests the client retries after the server restart |
| 3531 |
will return the results that are cached in the reply cache, and any |
| 3532 |
new requests (i.e., the sequence ID is one greater than the slot's |
| 3533 |
sequence ID) MUST be rejected with NFS4ERR_DEADSESSION (returned by |
| 3534 |
SEQUENCE). Such a session is considered dead. A server MAY re- |
| 3535 |
animate a session after a server restart so that the session will |
| 3536 |
accept new requests as well as retries. To re-animate a session, the |
| 3537 |
server needs to persist additional information through server |
| 3538 |
restart: |
| 3539 |
|
| 3540 |
o The client ID. This is a prerequisite to let the client create |
| 3541 |
more sessions associated with the same client ID as the re- |
| 3542 |
animated session. |
| 3543 |
|
| 3544 |
o The client ID's sequence ID that is used for creating sessions |
| 3545 |
(see Sections <a href="#section-18.35">18.35</a> and <a href="#section-18.36">18.36</a>). This is a prerequisite to let the |
| 3546 |
client create more sessions. |
| 3547 |
|
| 3548 |
o The principal that created the client ID. This allows the server |
| 3549 |
to authenticate the client when it sends EXCHANGE_ID. |
| 3550 |
|
| 3551 |
o The SSV, if SP4_SSV state protection was specified when the client |
| 3552 |
ID was created (see <a href="#section-18.35">Section 18.35</a>). This lets the client create |
| 3553 |
new sessions, and associate connections with the new and existing |
| 3554 |
sessions. |
| 3555 |
|
| 3556 |
o The properties of the client ID as defined in <a href="#section-18.35">Section 18.35</a>. |
| 3557 |
|
| 3558 |
A persistent reply cache places certain demands on the server. The |
| 3559 |
execution of the sequence of operations (starting with SEQUENCE) and |
| 3560 |
placement of its results in the persistent cache MUST be atomic. If |
| 3561 |
a client retries a sequence of operations that was previously |
| 3562 |
executed on the server, the only acceptable outcomes are either the |
| 3563 |
original cached reply or an indication that the client ID or session |
| 3564 |
has been lost (indicating a catastrophic loss of the reply cache or a |
| 3565 |
session that has been deleted because the client failed to use the |
| 3566 |
session for an extended period of time). |
| 3567 |
|
| 3568 |
A server could fail and restart in the middle of a COMPOUND procedure |
| 3569 |
that contains one or more non-idempotent or idempotent-but-modifying |
| 3570 |
operations. This creates an even higher challenge for atomic |
| 3571 |
execution and placement of results in the reply cache. One way to |
| 3572 |
view the problem is as a single transaction consisting of each |
| 3573 |
operation in the COMPOUND followed by storing the result in |
| 3574 |
persistent storage, then finally a transaction commit. If there is a |
| 3575 |
failure before the transaction is committed, then the server rolls |
| 3576 |
|
| 3577 |
|
| 3578 |
|
| 3579 |
|
| 3580 |
<span class="grey">Shepler, et al. Standards Track [Page 64]</span></pre> |
| 3581 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-65" ></span> |
| 3582 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3583 |
|
| 3584 |
|
| 3585 |
back the transaction. If the server itself fails, then when it |
| 3586 |
restarts, its recovery logic could roll back the transaction before |
| 3587 |
starting the NFSv4.1 server. |
| 3588 |
|
| 3589 |
While the description of the implementation for atomic execution of |
| 3590 |
the request and caching of the reply is beyond the scope of this |
| 3591 |
document, an example implementation for NFSv2 [<a href="#ref-38" title=""NFS: Network File System Protocol specification"">38</a>] is described in |
| 3592 |
[<a href="#ref-39" title=""A Highly Available Network Server"">39</a>]. |
| 3593 |
|
| 3594 |
<span class="h4"><a class="selflink" id="section-2.10.7" href="#section-2.10.7">2.10.7</a>. RDMA Considerations</span> |
| 3595 |
|
| 3596 |
A complete discussion of the operation of RPC-based protocols over |
| 3597 |
RDMA transports is in [<a href="#ref-8" title=""Remote Direct Memory Access Transport for Remote Procedure Call"">8</a>]. A discussion of the operation of NFSv4, |
| 3598 |
including NFSv4.1, over RDMA is in [<a href="#ref-9" title=""Network File System (NFS) Direct Data Placement"">9</a>]. Where RDMA is considered, |
| 3599 |
this specification assumes the use of such a layering; it addresses |
| 3600 |
only the upper-layer issues relevant to making best use of RPC/RDMA. |
| 3601 |
|
| 3602 |
<span class="h5"><a class="selflink" id="section-2.10.7.1" href="#section-2.10.7.1">2.10.7.1</a>. RDMA Connection Resources</span> |
| 3603 |
|
| 3604 |
RDMA requires its consumers to register memory and post buffers of a |
| 3605 |
specific size and number for receive operations. |
| 3606 |
|
| 3607 |
Registration of memory can be a relatively high-overhead operation, |
| 3608 |
since it requires pinning of buffers, assignment of attributes (e.g., |
| 3609 |
readable/writable), and initialization of hardware translation. |
| 3610 |
Preregistration is desirable to reduce overhead. These registrations |
| 3611 |
are specific to hardware interfaces and even to RDMA connection |
| 3612 |
endpoints; therefore, negotiation of their limits is desirable to |
| 3613 |
manage resources effectively. |
| 3614 |
|
| 3615 |
Following basic registration, these buffers must be posted by the RPC |
| 3616 |
layer to handle receives. These buffers remain in use by the RPC/ |
| 3617 |
NFSv4.1 implementation; the size and number of them must be known to |
| 3618 |
the remote peer in order to avoid RDMA errors that would cause a |
| 3619 |
fatal error on the RDMA connection. |
| 3620 |
|
| 3621 |
NFSv4.1 manages slots as resources on a per-session basis (see |
| 3622 |
<a href="#section-2.10">Section 2.10</a>), while RDMA connections manage credits on a per- |
| 3623 |
connection basis. This means that in order for a peer to send data |
| 3624 |
over RDMA to a remote buffer, it has to have both an NFSv4.1 slot and |
| 3625 |
an RDMA credit. If multiple RDMA connections are associated with a |
| 3626 |
session, then if the total number of credits across all RDMA |
| 3627 |
connections associated with the session is X, and the number of slots |
| 3628 |
in the session is Y, then the maximum number of outstanding requests |
| 3629 |
is the lesser of X and Y. |
| 3630 |
|
| 3631 |
|
| 3632 |
|
| 3633 |
|
| 3634 |
|
| 3635 |
|
| 3636 |
<span class="grey">Shepler, et al. Standards Track [Page 65]</span></pre> |
| 3637 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-66" ></span> |
| 3638 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3639 |
|
| 3640 |
|
| 3641 |
<span class="h5"><a class="selflink" id="section-2.10.7.2" href="#section-2.10.7.2">2.10.7.2</a>. Flow Control</span> |
| 3642 |
|
| 3643 |
Previous versions of NFS do not provide flow control; instead, they |
| 3644 |
rely on the windowing provided by transports like TCP to throttle |
| 3645 |
requests. This does not work with RDMA, which provides no operation |
| 3646 |
flow control and will terminate a connection in error when limits are |
| 3647 |
exceeded. Limits such as maximum number of requests outstanding are |
| 3648 |
therefore negotiated when a session is created (see the |
| 3649 |
ca_maxrequests field in <a href="#section-18.36">Section 18.36</a>). These limits then provide |
| 3650 |
the maxima within which each connection associated with the session's |
| 3651 |
channel(s) must remain. RDMA connections are managed within these |
| 3652 |
limits as described in Section 3.3 of [<a href="#ref-8" title=""Remote Direct Memory Access Transport for Remote Procedure Call"">8</a>]; if there are multiple RDMA |
| 3653 |
connections, then the maximum number of requests for a channel will |
| 3654 |
be divided among the RDMA connections. Put a different way, the onus |
| 3655 |
is on the replier to ensure that the total number of RDMA credits |
| 3656 |
across all connections associated with the replier's channel does |
| 3657 |
exceed the channel's maximum number of outstanding requests. |
| 3658 |
|
| 3659 |
The limits may also be modified dynamically at the replier's choosing |
| 3660 |
by manipulating certain parameters present in each NFSv4.1 reply. In |
| 3661 |
addition, the CB_RECALL_SLOT callback operation (see <a href="#section-20.8">Section 20.8</a>) |
| 3662 |
can be sent by a server to a client to return RDMA credits to the |
| 3663 |
server, thereby lowering the maximum number of requests a client can |
| 3664 |
have outstanding to the server. |
| 3665 |
|
| 3666 |
<span class="h5"><a class="selflink" id="section-2.10.7.3" href="#section-2.10.7.3">2.10.7.3</a>. Padding</span> |
| 3667 |
|
| 3668 |
Header padding is requested by each peer at session initiation (see |
| 3669 |
the ca_headerpadsize argument to CREATE_SESSION in <a href="#section-18.36">Section 18.36</a>), |
| 3670 |
and subsequently used by the RPC RDMA layer, as described in [<a href="#ref-8" title=""Remote Direct Memory Access Transport for Remote Procedure Call"">8</a>]. |
| 3671 |
Zero padding is permitted. |
| 3672 |
|
| 3673 |
Padding leverages the useful property that RDMA preserve alignment of |
| 3674 |
data, even when they are placed into anonymous (untagged) buffers. |
| 3675 |
If requested, client inline writes will insert appropriate pad bytes |
| 3676 |
within the request header to align the data payload on the specified |
| 3677 |
boundary. The client is encouraged to add sufficient padding (up to |
| 3678 |
the negotiated size) so that the "data" field of the WRITE operation |
| 3679 |
is aligned. Most servers can make good use of such padding, which |
| 3680 |
allows them to chain receive buffers in such a way that any data |
| 3681 |
carried by client requests will be placed into appropriate buffers at |
| 3682 |
the server, ready for file system processing. The receiver's RPC |
| 3683 |
layer encounters no overhead from skipping over pad bytes, and the |
| 3684 |
RDMA layer's high performance makes the insertion and transmission of |
| 3685 |
padding on the sender a significant optimization. In this way, the |
| 3686 |
need for servers to perform RDMA Read to satisfy all but the largest |
| 3687 |
|
| 3688 |
|
| 3689 |
|
| 3690 |
|
| 3691 |
|
| 3692 |
<span class="grey">Shepler, et al. Standards Track [Page 66]</span></pre> |
| 3693 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-67" ></span> |
| 3694 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3695 |
|
| 3696 |
|
| 3697 |
client writes is obviated. An added benefit is the reduction of |
| 3698 |
message round trips on the network -- a potentially good trade, where |
| 3699 |
latency is present. |
| 3700 |
|
| 3701 |
The value to choose for padding is subject to a number of criteria. |
| 3702 |
A primary source of variable-length data in the RPC header is the |
| 3703 |
authentication information, the form of which is client-determined, |
| 3704 |
possibly in response to server specification. The contents of |
| 3705 |
COMPOUNDs, sizes of strings such as those passed to RENAME, etc. all |
| 3706 |
go into the determination of a maximal NFSv4.1 request size and |
| 3707 |
therefore minimal buffer size. The client must select its offered |
| 3708 |
value carefully, so as to avoid overburdening the server, and vice |
| 3709 |
versa. The benefit of an appropriate padding value is higher |
| 3710 |
performance. |
| 3711 |
|
| 3712 |
Sender gather: |
| 3713 |
|RPC Request|Pad bytes|Length| -> |User data...| |
| 3714 |
\------+----------------------/ \ |
| 3715 |
\ \ |
| 3716 |
\ Receiver scatter: \-----------+- ... |
| 3717 |
/-----+----------------\ \ \ |
| 3718 |
|RPC Request|Pad|Length| -> |FS buffer|->|FS buffer|->... |
| 3719 |
|
| 3720 |
In the above case, the server may recycle unused buffers to the next |
| 3721 |
posted receive if unused by the actual received request, or may pass |
| 3722 |
the now-complete buffers by reference for normal write processing. |
| 3723 |
For a server that can make use of it, this removes any need for data |
| 3724 |
copies of incoming data, without resorting to complicated end-to-end |
| 3725 |
buffer advertisement and management. This includes most kernel-based |
| 3726 |
and integrated server designs, among many others. The client may |
| 3727 |
perform similar optimizations, if desired. |
| 3728 |
|
| 3729 |
<span class="h5"><a class="selflink" id="section-2.10.7.4" href="#section-2.10.7.4">2.10.7.4</a>. Dual RDMA and Non-RDMA Transports</span> |
| 3730 |
|
| 3731 |
Some RDMA transports (e.g., <a href="./rfc5040">RFC 5040</a> [<a href="#ref-10" title=""A Remote Direct Memory Access Protocol Specification"">10</a>]) permit a "streaming" (non- |
| 3732 |
RDMA) phase, where ordinary traffic might flow before "stepping up" |
| 3733 |
to RDMA mode, commencing RDMA traffic. Some RDMA transports start |
| 3734 |
connections always in RDMA mode. NFSv4.1 allows, but does not |
| 3735 |
assume, a streaming phase before RDMA mode. When a connection is |
| 3736 |
associated with a session, the client and server negotiate whether |
| 3737 |
the connection is used in RDMA or non-RDMA mode (see Sections <a href="#section-18.36">18.36</a> |
| 3738 |
and 18.34). |
| 3739 |
|
| 3740 |
|
| 3741 |
|
| 3742 |
|
| 3743 |
|
| 3744 |
|
| 3745 |
|
| 3746 |
|
| 3747 |
|
| 3748 |
<span class="grey">Shepler, et al. Standards Track [Page 67]</span></pre> |
| 3749 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-68" ></span> |
| 3750 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3751 |
|
| 3752 |
|
| 3753 |
<span class="h4"><a class="selflink" id="section-2.10.8" href="#section-2.10.8">2.10.8</a>. Session Security</span> |
| 3754 |
|
| 3755 |
<span class="h5"><a class="selflink" id="section-2.10.8.1" href="#section-2.10.8.1">2.10.8.1</a>. Session Callback Security</span> |
| 3756 |
|
| 3757 |
Via session/connection association, NFSv4.1 improves security over |
| 3758 |
that provided by NFSv4.0 for the backchannel. The connection is |
| 3759 |
client-initiated (see <a href="#section-18.34">Section 18.34</a>) and subject to the same firewall |
| 3760 |
and routing checks as the fore channel. At the client's option (see |
| 3761 |
<a href="#section-18.35">Section 18.35</a>), connection association is fully authenticated before |
| 3762 |
being activated (see <a href="#section-18.34">Section 18.34</a>). Traffic from the server over |
| 3763 |
the backchannel is authenticated exactly as the client specifies (see |
| 3764 |
<a href="#section-2.10.8.2">Section 2.10.8.2</a>). |
| 3765 |
|
| 3766 |
<span class="h5"><a class="selflink" id="section-2.10.8.2" href="#section-2.10.8.2">2.10.8.2</a>. Backchannel RPC Security</span> |
| 3767 |
|
| 3768 |
When the NFSv4.1 client establishes the backchannel, it informs the |
| 3769 |
server of the security flavors and principals to use when sending |
| 3770 |
requests. If the security flavor is RPCSEC_GSS, the client expresses |
| 3771 |
the principal in the form of an established RPCSEC_GSS context. The |
| 3772 |
server is free to use any of the flavor/principal combinations the |
| 3773 |
client offers, but it MUST NOT use unoffered combinations. This way, |
| 3774 |
the client need not provide a target GSS principal for the |
| 3775 |
backchannel as it did with NFSv4.0, nor does the server have to |
| 3776 |
implement an RPCSEC_GSS initiator as it did with NFSv4.0 [<a href="#ref-30" title=""Network File System (NFS) version 4 Protocol"">30</a>]. |
| 3777 |
|
| 3778 |
The CREATE_SESSION (<a href="#section-18.36">Section 18.36</a>) and BACKCHANNEL_CTL |
| 3779 |
(<a href="#section-18.33">Section 18.33</a>) operations allow the client to specify flavor/ |
| 3780 |
principal combinations. |
| 3781 |
|
| 3782 |
Also note that the SP4_SSV state protection mode (see Sections <a href="#section-18.35">18.35</a> |
| 3783 |
and 2.10.8.3) has the side benefit of providing SSV-derived |
| 3784 |
RPCSEC_GSS contexts (<a href="#section-2.10.9">Section 2.10.9</a>). |
| 3785 |
|
| 3786 |
<span class="h5"><a class="selflink" id="section-2.10.8.3" href="#section-2.10.8.3">2.10.8.3</a>. Protection from Unauthorized State Changes</span> |
| 3787 |
|
| 3788 |
As described to this point in the specification, the state model of |
| 3789 |
NFSv4.1 is vulnerable to an attacker that sends a SEQUENCE operation |
| 3790 |
with a forged session ID and with a slot ID that it expects the |
| 3791 |
legitimate client to use next. When the legitimate client uses the |
| 3792 |
slot ID with the same sequence number, the server returns the |
| 3793 |
attacker's result from the reply cache, which disrupts the legitimate |
| 3794 |
client and thus denies service to it. Similarly, an attacker could |
| 3795 |
send a CREATE_SESSION with a forged client ID to create a new session |
| 3796 |
associated with the client ID. The attacker could send requests |
| 3797 |
using the new session that change locking state, such as LOCKU |
| 3798 |
operations to release locks the legitimate client has acquired. |
| 3799 |
Setting a security policy on the file that requires RPCSEC_GSS |
| 3800 |
credentials when manipulating the file's state is one potential work |
| 3801 |
|
| 3802 |
|
| 3803 |
|
| 3804 |
<span class="grey">Shepler, et al. Standards Track [Page 68]</span></pre> |
| 3805 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-69" ></span> |
| 3806 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3807 |
|
| 3808 |
|
| 3809 |
around, but has the disadvantage of preventing a legitimate client |
| 3810 |
from releasing state when RPCSEC_GSS is required to do so, but a GSS |
| 3811 |
context cannot be obtained (possibly because the user has logged off |
| 3812 |
the client). |
| 3813 |
|
| 3814 |
NFSv4.1 provides three options to a client for state protection, |
| 3815 |
which are specified when a client creates a client ID via EXCHANGE_ID |
| 3816 |
(<a href="#section-18.35">Section 18.35</a>). |
| 3817 |
|
| 3818 |
The first (SP4_NONE) is to simply waive state protection. |
| 3819 |
|
| 3820 |
The other two options (SP4_MACH_CRED and SP4_SSV) share several |
| 3821 |
traits: |
| 3822 |
|
| 3823 |
o An RPCSEC_GSS-based credential is used to authenticate client ID |
| 3824 |
and session maintenance operations, including creating and |
| 3825 |
destroying a session, associating a connection with the session, |
| 3826 |
and destroying the client ID. |
| 3827 |
|
| 3828 |
o Because RPCSEC_GSS is used to authenticate client ID and session |
| 3829 |
maintenance, the attacker cannot associate a rogue connection with |
| 3830 |
a legitimate session, or associate a rogue session with a |
| 3831 |
legitimate client ID in order to maliciously alter the client ID's |
| 3832 |
lock state via CLOSE, LOCKU, DELEGRETURN, LAYOUTRETURN, etc. |
| 3833 |
|
| 3834 |
o In cases where the server's security policies on a portion of its |
| 3835 |
namespace require RPCSEC_GSS authentication, a client may have to |
| 3836 |
use an RPCSEC_GSS credential to remove per-file state (e.g., |
| 3837 |
LOCKU, CLOSE, etc.). The server may require that the principal |
| 3838 |
that removes the state match certain criteria (e.g., the principal |
| 3839 |
might have to be the same as the one that acquired the state). |
| 3840 |
However, the client might not have an RPCSEC_GSS context for such |
| 3841 |
a principal, and might not be able to create such a context |
| 3842 |
(perhaps because the user has logged off). When the client |
| 3843 |
establishes SP4_MACH_CRED or SP4_SSV protection, it can specify a |
| 3844 |
list of operations that the server MUST allow using the machine |
| 3845 |
credential (if SP4_MACH_CRED is used) or the SSV credential (if |
| 3846 |
SP4_SSV is used). |
| 3847 |
|
| 3848 |
The SP4_MACH_CRED state protection option uses a machine credential |
| 3849 |
where the principal that creates the client ID MUST also be the |
| 3850 |
principal that performs client ID and session maintenance operations. |
| 3851 |
The security of the machine credential state protection approach |
| 3852 |
depends entirely on safe guarding the per-machine credential. |
| 3853 |
Assuming a proper safeguard using the per-machine credential for |
| 3854 |
operations like CREATE_SESSION, BIND_CONN_TO_SESSION, |
| 3855 |
|
| 3856 |
|
| 3857 |
|
| 3858 |
|
| 3859 |
|
| 3860 |
<span class="grey">Shepler, et al. Standards Track [Page 69]</span></pre> |
| 3861 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-70" ></span> |
| 3862 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3863 |
|
| 3864 |
|
| 3865 |
DESTROY_SESSION, and DESTROY_CLIENTID will prevent an attacker from |
| 3866 |
associating a rogue connection with a session, or associating a rogue |
| 3867 |
session with a client ID. |
| 3868 |
|
| 3869 |
There are at least three scenarios for the SP4_MACH_CRED option: |
| 3870 |
|
| 3871 |
1. The system administrator configures a unique, permanent per- |
| 3872 |
machine credential for one of the mandated GSS mechanisms (e.g., |
| 3873 |
if Kerberos V5 is used, a "keytab" containing a principal derived |
| 3874 |
from a client host name could be used). |
| 3875 |
|
| 3876 |
2. The client is used by a single user, and so the client ID and its |
| 3877 |
sessions are used by just that user. If the user's credential |
| 3878 |
expires, then session and client ID maintenance cannot occur, but |
| 3879 |
since the client has a single user, only that user is |
| 3880 |
inconvenienced. |
| 3881 |
|
| 3882 |
3. The physical client has multiple users, but the client |
| 3883 |
implementation has a unique client ID for each user. This is |
| 3884 |
effectively the same as the second scenario, but a disadvantage |
| 3885 |
is that each user needs to be allocated at least one session |
| 3886 |
each, so the approach suffers from lack of economy. |
| 3887 |
|
| 3888 |
The SP4_SSV protection option uses the SSV (<a href="#section-1.6">Section 1.6</a>), via |
| 3889 |
RPCSEC_GSS and the SSV GSS mechanism (<a href="#section-2.10.9">Section 2.10.9</a>), to protect |
| 3890 |
state from attack. The SP4_SSV protection option is intended for the |
| 3891 |
situation comprised of a client that has multiple active users and a |
| 3892 |
system administrator who wants to avoid the burden of installing a |
| 3893 |
permanent machine credential on each client. The SSV is established |
| 3894 |
and updated on the server via SET_SSV (see <a href="#section-18.47">Section 18.47</a>). To |
| 3895 |
prevent eavesdropping, a client SHOULD send SET_SSV via RPCSEC_GSS |
| 3896 |
with the privacy service. Several aspects of the SSV make it |
| 3897 |
intractable for an attacker to guess the SSV, and thus associate |
| 3898 |
rogue connections with a session, and rogue sessions with a client |
| 3899 |
ID: |
| 3900 |
|
| 3901 |
o The arguments to and results of SET_SSV include digests of the old |
| 3902 |
and new SSV, respectively. |
| 3903 |
|
| 3904 |
o Because the initial value of the SSV is zero, therefore known, the |
| 3905 |
client that opts for SP4_SSV protection and opts to apply SP4_SSV |
| 3906 |
protection to BIND_CONN_TO_SESSION and CREATE_SESSION MUST send at |
| 3907 |
least one SET_SSV operation before the first BIND_CONN_TO_SESSION |
| 3908 |
operation or before the second CREATE_SESSION operation on a |
| 3909 |
client ID. If it does not, the SSV mechanism will not generate |
| 3910 |
tokens (<a href="#section-2.10.9">Section 2.10.9</a>). A client SHOULD send SET_SSV as soon as |
| 3911 |
a session is created. |
| 3912 |
|
| 3913 |
|
| 3914 |
|
| 3915 |
|
| 3916 |
<span class="grey">Shepler, et al. Standards Track [Page 70]</span></pre> |
| 3917 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-71" ></span> |
| 3918 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3919 |
|
| 3920 |
|
| 3921 |
o A SET_SSV request does not replace the SSV with the argument to |
| 3922 |
SET_SSV. Instead, the current SSV on the server is logically |
| 3923 |
exclusive ORed (XORed) with the argument to SET_SSV. Each time a |
| 3924 |
new principal uses a client ID for the first time, the client |
| 3925 |
SHOULD send a SET_SSV with that principal's RPCSEC_GSS |
| 3926 |
credentials, with RPCSEC_GSS service set to RPC_GSS_SVC_PRIVACY. |
| 3927 |
|
| 3928 |
Here are the types of attacks that can be attempted by an attacker |
| 3929 |
named Eve on a victim named Bob, and how SP4_SSV protection foils |
| 3930 |
each attack: |
| 3931 |
|
| 3932 |
o Suppose Eve is the first user to log into a legitimate client. |
| 3933 |
Eve's use of an NFSv4.1 file system will cause the legitimate |
| 3934 |
client to create a client ID with SP4_SSV protection, specifying |
| 3935 |
that the BIND_CONN_TO_SESSION operation MUST use the SSV |
| 3936 |
credential. Eve's use of the file system also causes an SSV to be |
| 3937 |
created. The SET_SSV operation that creates the SSV will be |
| 3938 |
protected by the RPCSEC_GSS context created by the legitimate |
| 3939 |
client, which uses Eve's GSS principal and credentials. Eve can |
| 3940 |
eavesdrop on the network while her RPCSEC_GSS context is created |
| 3941 |
and the SET_SSV using her context is sent. Even if the legitimate |
| 3942 |
client sends the SET_SSV with RPC_GSS_SVC_PRIVACY, because Eve |
| 3943 |
knows her own credentials, she can decrypt the SSV. Eve can |
| 3944 |
compute an RPCSEC_GSS credential that BIND_CONN_TO_SESSION will |
| 3945 |
accept, and so associate a new connection with the legitimate |
| 3946 |
session. Eve can change the slot ID and sequence state of a |
| 3947 |
legitimate session, and/or the SSV state, in such a way that when |
| 3948 |
Bob accesses the server via the same legitimate client, the |
| 3949 |
legitimate client will be unable to use the session. |
| 3950 |
|
| 3951 |
The client's only recourse is to create a new client ID for Bob to |
| 3952 |
use, and establish a new SSV for the client ID. The client will |
| 3953 |
be unable to delete the old client ID, and will let the lease on |
| 3954 |
the old client ID expire. |
| 3955 |
|
| 3956 |
Once the legitimate client establishes an SSV over the new session |
| 3957 |
using Bob's RPCSEC_GSS context, Eve can use the new session via |
| 3958 |
the legitimate client, but she cannot disrupt Bob. Moreover, |
| 3959 |
because the client SHOULD have modified the SSV due to Eve using |
| 3960 |
the new session, Bob cannot get revenge on Eve by associating a |
| 3961 |
rogue connection with the session. |
| 3962 |
|
| 3963 |
The question is how did the legitimate client detect that Eve has |
| 3964 |
hijacked the old session? When the client detects that a new |
| 3965 |
principal, Bob, wants to use the session, it SHOULD have sent a |
| 3966 |
SET_SSV, which leads to the following sub-scenarios: |
| 3967 |
|
| 3968 |
|
| 3969 |
|
| 3970 |
|
| 3971 |
|
| 3972 |
<span class="grey">Shepler, et al. Standards Track [Page 71]</span></pre> |
| 3973 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-72" ></span> |
| 3974 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 3975 |
|
| 3976 |
|
| 3977 |
* Let us suppose that from the rogue connection, Eve sent a |
| 3978 |
SET_SSV with the same slot ID and sequence ID that the |
| 3979 |
legitimate client later uses. The server will assume the |
| 3980 |
SET_SSV sent with Bob's credentials is a retry, and return to |
| 3981 |
the legitimate client the reply it sent Eve. However, unless |
| 3982 |
Eve can correctly guess the SSV the legitimate client will use, |
| 3983 |
the digest verification checks in the SET_SSV response will |
| 3984 |
fail. That is an indication to the client that the session has |
| 3985 |
apparently been hijacked. |
| 3986 |
|
| 3987 |
* Alternatively, Eve sent a SET_SSV with a different slot ID than |
| 3988 |
the legitimate client uses for its SET_SSV. Then the digest |
| 3989 |
verification of the SET_SSV sent with Bob's credentials fails |
| 3990 |
on the server, and the error returned to the client makes it |
| 3991 |
apparent that the session has been hijacked. |
| 3992 |
|
| 3993 |
* Alternatively, Eve sent an operation other than SET_SSV, but |
| 3994 |
with the same slot ID and sequence that the legitimate client |
| 3995 |
uses for its SET_SSV. The server returns to the legitimate |
| 3996 |
client the response it sent Eve. The client sees that the |
| 3997 |
response is not at all what it expects. The client assumes |
| 3998 |
either session hijacking or a server bug, and either way |
| 3999 |
destroys the old session. |
| 4000 |
|
| 4001 |
o Eve associates a rogue connection with the session as above, and |
| 4002 |
then destroys the session. Again, Bob goes to use the server from |
| 4003 |
the legitimate client, which sends a SET_SSV using Bob's |
| 4004 |
credentials. The client receives an error that indicates that the |
| 4005 |
session does not exist. When the client tries to create a new |
| 4006 |
session, this will fail because the SSV it has does not match that |
| 4007 |
which the server has, and now the client knows the session was |
| 4008 |
hijacked. The legitimate client establishes a new client ID. |
| 4009 |
|
| 4010 |
o If Eve creates a connection before the legitimate client |
| 4011 |
establishes an SSV, because the initial value of the SSV is zero |
| 4012 |
and therefore known, Eve can send a SET_SSV that will pass the |
| 4013 |
digest verification check. However, because the new connection |
| 4014 |
has not been associated with the session, the SET_SSV is rejected |
| 4015 |
for that reason. |
| 4016 |
|
| 4017 |
In summary, an attacker's disruption of state when SP4_SSV protection |
| 4018 |
is in use is limited to the formative period of a client ID, its |
| 4019 |
first session, and the establishment of the SSV. Once a non- |
| 4020 |
malicious user uses the client ID, the client quickly detects any |
| 4021 |
hijack and rectifies the situation. Once a non-malicious user |
| 4022 |
successfully modifies the SSV, the attacker cannot use NFSv4.1 |
| 4023 |
operations to disrupt the non-malicious user. |
| 4024 |
|
| 4025 |
|
| 4026 |
|
| 4027 |
|
| 4028 |
<span class="grey">Shepler, et al. Standards Track [Page 72]</span></pre> |
| 4029 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-73" ></span> |
| 4030 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4031 |
|
| 4032 |
|
| 4033 |
Note that neither the SP4_MACH_CRED nor SP4_SSV protection approaches |
| 4034 |
prevent hijacking of a transport connection that has previously been |
| 4035 |
associated with a session. If the goal of a counter-threat strategy |
| 4036 |
is to prevent connection hijacking, the use of IPsec is RECOMMENDED. |
| 4037 |
|
| 4038 |
If a connection hijack occurs, the hijacker could in theory change |
| 4039 |
locking state and negatively impact the service to legitimate |
| 4040 |
clients. However, if the server is configured to require the use of |
| 4041 |
RPCSEC_GSS with integrity or privacy on the affected file objects, |
| 4042 |
and if EXCHGID4_FLAG_BIND_PRINC_STATEID capability (<a href="#section-18.35">Section 18.35</a>) is |
| 4043 |
in force, this will thwart unauthorized attempts to change locking |
| 4044 |
state. |
| 4045 |
|
| 4046 |
<span class="h4"><a class="selflink" id="section-2.10.9" href="#section-2.10.9">2.10.9</a>. The Secret State Verifier (SSV) GSS Mechanism</span> |
| 4047 |
|
| 4048 |
The SSV provides the secret key for a GSS mechanism internal to |
| 4049 |
NFSv4.1 that NFSv4.1 uses for state protection. Contexts for this |
| 4050 |
mechanism are not established via the RPCSEC_GSS protocol. Instead, |
| 4051 |
the contexts are automatically created when EXCHANGE_ID specifies |
| 4052 |
SP4_SSV protection. The only tokens defined are the PerMsgToken |
| 4053 |
(emitted by GSS_GetMIC) and the SealedMessage token (emitted by |
| 4054 |
GSS_Wrap). |
| 4055 |
|
| 4056 |
The mechanism OID for the SSV mechanism is |
| 4057 |
iso.org.dod.internet.private.enterprise.Michael Eisler.nfs.ssv_mech |
| 4058 |
(1.3.6.1.4.1.28882.1.1). While the SSV mechanism does not define any |
| 4059 |
initial context tokens, the OID can be used to let servers indicate |
| 4060 |
that the SSV mechanism is acceptable whenever the client sends a |
| 4061 |
SECINFO or SECINFO_NO_NAME operation (see <a href="#section-2.6">Section 2.6</a>). |
| 4062 |
|
| 4063 |
The SSV mechanism defines four subkeys derived from the SSV value. |
| 4064 |
Each time SET_SSV is invoked, the subkeys are recalculated by the |
| 4065 |
client and server. The calculation of each of the four subkeys |
| 4066 |
depends on each of the four respective ssv_subkey4 enumerated values. |
| 4067 |
The calculation uses the HMAC [<a href="#ref-11" title=""HMAC: Keyed-Hashing for Message Authentication"">11</a>] algorithm, using the current SSV |
| 4068 |
as the key, the one-way hash algorithm as negotiated by EXCHANGE_ID, |
| 4069 |
and the input text as represented by the XDR encoded enumeration |
| 4070 |
value for that subkey of data type ssv_subkey4. If the length of the |
| 4071 |
output of the HMAC algorithm exceeds the length of key of the |
| 4072 |
encryption algorithm (which is also negotiated by EXCHANGE_ID), then |
| 4073 |
the subkey MUST be truncated from the HMAC output, i.e., if the |
| 4074 |
subkey is of N bytes long, then the first N bytes of the HMAC output |
| 4075 |
MUST be used for the subkey. The specification of EXCHANGE_ID states |
| 4076 |
that the length of the output of the HMAC algorithm MUST NOT be less |
| 4077 |
than the length of subkey needed for the encryption algorithm (see |
| 4078 |
<a href="#section-18.35">Section 18.35</a>). |
| 4079 |
|
| 4080 |
|
| 4081 |
|
| 4082 |
|
| 4083 |
|
| 4084 |
<span class="grey">Shepler, et al. Standards Track [Page 73]</span></pre> |
| 4085 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-74" ></span> |
| 4086 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4087 |
|
| 4088 |
|
| 4089 |
/* Input for computing subkeys */ |
| 4090 |
enum ssv_subkey4 { |
| 4091 |
SSV4_SUBKEY_MIC_I2T = 1, |
| 4092 |
SSV4_SUBKEY_MIC_T2I = 2, |
| 4093 |
SSV4_SUBKEY_SEAL_I2T = 3, |
| 4094 |
SSV4_SUBKEY_SEAL_T2I = 4 |
| 4095 |
}; |
| 4096 |
|
| 4097 |
The subkey derived from SSV4_SUBKEY_MIC_I2T is used for calculating |
| 4098 |
message integrity codes (MICs) that originate from the NFSv4.1 |
| 4099 |
client, whether as part of a request over the fore channel or a |
| 4100 |
response over the backchannel. The subkey derived from |
| 4101 |
SSV4_SUBKEY_MIC_T2I is used for MICs originating from the NFSv4.1 |
| 4102 |
server. The subkey derived from SSV4_SUBKEY_SEAL_I2T is used for |
| 4103 |
encryption text originating from the NFSv4.1 client, and the subkey |
| 4104 |
derived from SSV4_SUBKEY_SEAL_T2I is used for encryption text |
| 4105 |
originating from the NFSv4.1 server. |
| 4106 |
|
| 4107 |
The PerMsgToken description is based on an XDR definition: |
| 4108 |
|
| 4109 |
/* Input for computing smt_hmac */ |
| 4110 |
struct ssv_mic_plain_tkn4 { |
| 4111 |
uint32_t smpt_ssv_seq; |
| 4112 |
opaque smpt_orig_plain<>; |
| 4113 |
}; |
| 4114 |
|
| 4115 |
|
| 4116 |
/* SSV GSS PerMsgToken token */ |
| 4117 |
struct ssv_mic_tkn4 { |
| 4118 |
uint32_t smt_ssv_seq; |
| 4119 |
opaque smt_hmac<>; |
| 4120 |
}; |
| 4121 |
|
| 4122 |
The field smt_hmac is an HMAC calculated by using the subkey derived |
| 4123 |
from SSV4_SUBKEY_MIC_I2T or SSV4_SUBKEY_MIC_T2I as the key, the one- |
| 4124 |
way hash algorithm as negotiated by EXCHANGE_ID, and the input text |
| 4125 |
as represented by data of type ssv_mic_plain_tkn4. The field |
| 4126 |
smpt_ssv_seq is the same as smt_ssv_seq. The field smpt_orig_plain |
| 4127 |
is the "message" input passed to GSS_GetMIC() (see Section 2.3.1 of |
| 4128 |
[<a href="#ref-7" title=""Generic Security Service Application Program Interface Version 2, Update 1"">7</a>]). The caller of GSS_GetMIC() provides a pointer to a buffer |
| 4129 |
containing the plain text. The SSV mechanism's entry point for |
| 4130 |
GSS_GetMIC() encodes this into an opaque array, and the encoding will |
| 4131 |
include an initial four-byte length, plus any necessary padding. |
| 4132 |
Prepended to this will be the XDR encoded value of smpt_ssv_seq, thus |
| 4133 |
making up an XDR encoding of a value of data type ssv_mic_plain_tkn4, |
| 4134 |
which in turn is the input into the HMAC. |
| 4135 |
|
| 4136 |
|
| 4137 |
|
| 4138 |
|
| 4139 |
|
| 4140 |
<span class="grey">Shepler, et al. Standards Track [Page 74]</span></pre> |
| 4141 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-75" ></span> |
| 4142 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4143 |
|
| 4144 |
|
| 4145 |
The token emitted by GSS_GetMIC() is XDR encoded and of XDR data type |
| 4146 |
ssv_mic_tkn4. The field smt_ssv_seq comes from the SSV sequence |
| 4147 |
number, which is equal to one after SET_SSV (<a href="#section-18.47">Section 18.47</a>) is called |
| 4148 |
the first time on a client ID. Thereafter, the SSV sequence number |
| 4149 |
is incremented on each SET_SSV. Thus, smt_ssv_seq represents the |
| 4150 |
version of the SSV at the time GSS_GetMIC() was called. As noted in |
| 4151 |
<a href="#section-18.35">Section 18.35</a>, the client and server can maintain multiple concurrent |
| 4152 |
versions of the SSV. This allows the SSV to be changed without |
| 4153 |
serializing all RPC calls that use the SSV mechanism with SET_SSV |
| 4154 |
operations. Once the HMAC is calculated, it is XDR encoded into |
| 4155 |
smt_hmac, which will include an initial four-byte length, and any |
| 4156 |
necessary padding. Prepended to this will be the XDR encoded value |
| 4157 |
of smt_ssv_seq. |
| 4158 |
|
| 4159 |
The SealedMessage description is based on an XDR definition: |
| 4160 |
|
| 4161 |
/* Input for computing ssct_encr_data and ssct_hmac */ |
| 4162 |
struct ssv_seal_plain_tkn4 { |
| 4163 |
opaque sspt_confounder<>; |
| 4164 |
uint32_t sspt_ssv_seq; |
| 4165 |
opaque sspt_orig_plain<>; |
| 4166 |
opaque sspt_pad<>; |
| 4167 |
}; |
| 4168 |
|
| 4169 |
|
| 4170 |
/* SSV GSS SealedMessage token */ |
| 4171 |
struct ssv_seal_cipher_tkn4 { |
| 4172 |
uint32_t ssct_ssv_seq; |
| 4173 |
opaque ssct_iv<>; |
| 4174 |
opaque ssct_encr_data<>; |
| 4175 |
opaque ssct_hmac<>; |
| 4176 |
}; |
| 4177 |
|
| 4178 |
The token emitted by GSS_Wrap() is XDR encoded and of XDR data type |
| 4179 |
ssv_seal_cipher_tkn4. |
| 4180 |
|
| 4181 |
The ssct_ssv_seq field has the same meaning as smt_ssv_seq. |
| 4182 |
|
| 4183 |
The ssct_encr_data field is the result of encrypting a value of the |
| 4184 |
XDR encoded data type ssv_seal_plain_tkn4. The encryption key is the |
| 4185 |
subkey derived from SSV4_SUBKEY_SEAL_I2T or SSV4_SUBKEY_SEAL_T2I, and |
| 4186 |
the encryption algorithm is that negotiated by EXCHANGE_ID. |
| 4187 |
|
| 4188 |
The ssct_iv field is the initialization vector (IV) for the |
| 4189 |
encryption algorithm (if applicable) and is sent in clear text. The |
| 4190 |
content and size of the IV MUST comply with the specification of the |
| 4191 |
encryption algorithm. For example, the id-aes256-CBC algorithm MUST |
| 4192 |
|
| 4193 |
|
| 4194 |
|
| 4195 |
|
| 4196 |
<span class="grey">Shepler, et al. Standards Track [Page 75]</span></pre> |
| 4197 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-76" ></span> |
| 4198 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4199 |
|
| 4200 |
|
| 4201 |
use a 16-byte initialization vector (IV), which MUST be unpredictable |
| 4202 |
for each instance of a value of data type ssv_seal_plain_tkn4 that is |
| 4203 |
encrypted with a particular SSV key. |
| 4204 |
|
| 4205 |
The ssct_hmac field is the result of computing an HMAC using the |
| 4206 |
value of the XDR encoded data type ssv_seal_plain_tkn4 as the input |
| 4207 |
text. The key is the subkey derived from SSV4_SUBKEY_MIC_I2T or |
| 4208 |
SSV4_SUBKEY_MIC_T2I, and the one-way hash algorithm is that |
| 4209 |
negotiated by EXCHANGE_ID. |
| 4210 |
|
| 4211 |
The sspt_confounder field is a random value. |
| 4212 |
|
| 4213 |
The sspt_ssv_seq field is the same as ssvt_ssv_seq. |
| 4214 |
|
| 4215 |
The field sspt_orig_plain field is the original plaintext and is the |
| 4216 |
"input_message" input passed to GSS_Wrap() (see Section 2.3.3 of |
| 4217 |
[<a href="#ref-7" title=""Generic Security Service Application Program Interface Version 2, Update 1"">7</a>]). As with the handling of the plaintext by the SSV mechanism's |
| 4218 |
GSS_GetMIC() entry point, the entry point for GSS_Wrap() expects a |
| 4219 |
pointer to the plaintext, and will XDR encode an opaque array into |
| 4220 |
sspt_orig_plain representing the plain text, along with the other |
| 4221 |
fields of an instance of data type ssv_seal_plain_tkn4. |
| 4222 |
|
| 4223 |
The sspt_pad field is present to support encryption algorithms that |
| 4224 |
require inputs to be in fixed-sized blocks. The content of sspt_pad |
| 4225 |
is zero filled except for the length. Beware that the XDR encoding |
| 4226 |
of ssv_seal_plain_tkn4 contains three variable-length arrays, and so |
| 4227 |
each array consumes four bytes for an array length, and each array |
| 4228 |
that follows the length is always padded to a multiple of four bytes |
| 4229 |
per the XDR standard. |
| 4230 |
|
| 4231 |
For example, suppose the encryption algorithm uses 16-byte blocks, |
| 4232 |
and the sspt_confounder is three bytes long, and the sspt_orig_plain |
| 4233 |
field is 15 bytes long. The XDR encoding of sspt_confounder uses |
| 4234 |
eight bytes (4 + 3 + 1 byte pad), the XDR encoding of sspt_ssv_seq |
| 4235 |
uses four bytes, the XDR encoding of sspt_orig_plain uses 20 bytes (4 |
| 4236 |
+ 15 + 1 byte pad), and the smallest XDR encoding of the sspt_pad |
| 4237 |
field is four bytes. This totals 36 bytes. The next multiple of 16 |
| 4238 |
is 48; thus, the length field of sspt_pad needs to be set to 12 |
| 4239 |
bytes, or a total encoding of 16 bytes. The total number of XDR |
| 4240 |
encoded bytes is thus 8 + 4 + 20 + 16 = 48. |
| 4241 |
|
| 4242 |
GSS_Wrap() emits a token that is an XDR encoding of a value of data |
| 4243 |
type ssv_seal_cipher_tkn4. Note that regardless of whether or not |
| 4244 |
the caller of GSS_Wrap() requests confidentiality, the token always |
| 4245 |
has confidentiality. This is because the SSV mechanism is for |
| 4246 |
RPCSEC_GSS, and RPCSEC_GSS never produces GSS_wrap() tokens without |
| 4247 |
confidentiality. |
| 4248 |
|
| 4249 |
|
| 4250 |
|
| 4251 |
|
| 4252 |
<span class="grey">Shepler, et al. Standards Track [Page 76]</span></pre> |
| 4253 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-77" ></span> |
| 4254 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4255 |
|
| 4256 |
|
| 4257 |
There is one SSV per client ID. There is a single GSS context for a |
| 4258 |
client ID / SSV pair. All SSV mechanism RPCSEC_GSS handles of a |
| 4259 |
client ID / SSV pair share the same GSS context. SSV GSS contexts do |
| 4260 |
not expire except when the SSV is destroyed (causes would include the |
| 4261 |
client ID being destroyed or a server restart). Since one purpose of |
| 4262 |
context expiration is to replace keys that have been in use for "too |
| 4263 |
long", hence vulnerable to compromise by brute force or accident, the |
| 4264 |
client can replace the SSV key by sending periodic SET_SSV |
| 4265 |
operations, which is done by cycling through different users' |
| 4266 |
RPCSEC_GSS credentials. This way, the SSV is replaced without |
| 4267 |
destroying the SSV's GSS contexts. |
| 4268 |
|
| 4269 |
SSV RPCSEC_GSS handles can be expired or deleted by the server at any |
| 4270 |
time, and the EXCHANGE_ID operation can be used to create more SSV |
| 4271 |
RPCSEC_GSS handles. Expiration of SSV RPCSEC_GSS handles does not |
| 4272 |
imply that the SSV or its GSS context has expired. |
| 4273 |
|
| 4274 |
The client MUST establish an SSV via SET_SSV before the SSV GSS |
| 4275 |
context can be used to emit tokens from GSS_Wrap() and GSS_GetMIC(). |
| 4276 |
If SET_SSV has not been successfully called, attempts to emit tokens |
| 4277 |
MUST fail. |
| 4278 |
|
| 4279 |
The SSV mechanism does not support replay detection and sequencing in |
| 4280 |
its tokens because RPCSEC_GSS does not use those features (See |
| 4281 |
<a href="#section-5.2.2">Section 5.2.2</a>, "Context Creation Requests", in [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>]). However, |
| 4282 |
<a href="#section-2.10.10">Section 2.10.10</a> discusses special considerations for the SSV |
| 4283 |
mechanism when used with RPCSEC_GSS. |
| 4284 |
|
| 4285 |
<span class="h4"><a class="selflink" id="section-2.10.10" href="#section-2.10.10">2.10.10</a>. Security Considerations for RPCSEC_GSS When Using the SSV</span> |
| 4286 |
<span class="h4"> Mechanism</span> |
| 4287 |
|
| 4288 |
When a client ID is created with SP4_SSV state protection (see |
| 4289 |
<a href="#section-18.35">Section 18.35</a>), the client is permitted to associate multiple |
| 4290 |
RPCSEC_GSS handles with the single SSV GSS context (see |
| 4291 |
<a href="#section-2.10.9">Section 2.10.9</a>). Because of the way RPCSEC_GSS (both version 1 and |
| 4292 |
version 2, see [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>] and [<a href="#ref-12" title=""RPCSEC_GSS Version 2"">12</a>]) calculate the verifier of the reply, |
| 4293 |
special care must be taken by the implementation of the NFSv4.1 |
| 4294 |
client to prevent attacks by a man-in-the-middle. The verifier of an |
| 4295 |
RPCSEC_GSS reply is the output of GSS_GetMIC() applied to the input |
| 4296 |
value of the seq_num field of the RPCSEC_GSS credential (data type |
| 4297 |
rpc_gss_cred_ver_1_t) (see Section 5.3.3.2 of [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>]). If multiple |
| 4298 |
RPCSEC_GSS handles share the same GSS context, then if one handle is |
| 4299 |
used to send a request with the same seq_num value as another handle, |
| 4300 |
an attacker could block the reply, and replace it with the verifier |
| 4301 |
used for the other handle. |
| 4302 |
|
| 4303 |
There are multiple ways to prevent the attack on the SSV RPCSEC_GSS |
| 4304 |
verifier in the reply. The simplest is believed to be as follows. |
| 4305 |
|
| 4306 |
|
| 4307 |
|
| 4308 |
<span class="grey">Shepler, et al. Standards Track [Page 77]</span></pre> |
| 4309 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-78" ></span> |
| 4310 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4311 |
|
| 4312 |
|
| 4313 |
o Each time one or more new SSV RPCSEC_GSS handles are created via |
| 4314 |
EXCHANGE_ID, the client SHOULD send a SET_SSV operation to modify |
| 4315 |
the SSV. By changing the SSV, the new handles will not result in |
| 4316 |
the re-use of an SSV RPCSEC_GSS verifier in a reply. |
| 4317 |
|
| 4318 |
o When a requester decides to use N SSV RPCSEC_GSS handles, it |
| 4319 |
SHOULD assign a unique and non-overlapping range of seq_nums to |
| 4320 |
each SSV RPCSEC_GSS handle. The size of each range SHOULD be |
| 4321 |
equal to MAXSEQ / N (see Section 5 of [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>] for the definition of |
| 4322 |
MAXSEQ). When an SSV RPCSEC_GSS handle reaches its maximum, it |
| 4323 |
SHOULD force the replier to destroy the handle by sending a NULL |
| 4324 |
RPC request with seq_num set to MAXSEQ + 1 (see Section 5.3.3.3 of |
| 4325 |
[<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>]). |
| 4326 |
|
| 4327 |
o When the requester wants to increase or decrease N, it SHOULD |
| 4328 |
force the replier to destroy all N handles by sending a NULL RPC |
| 4329 |
request on each handle with seq_num set to MAXSEQ + 1. If the |
| 4330 |
requester is the client, it SHOULD send a SET_SSV operation before |
| 4331 |
using new handles. If the requester is the server, then the |
| 4332 |
client SHOULD send a SET_SSV operation when it detects that the |
| 4333 |
server has forced it to destroy a backchannel's SSV RPCSEC_GSS |
| 4334 |
handle. By sending a SET_SSV operation, the SSV will change, and |
| 4335 |
so the attacker will be unavailable to successfully replay a |
| 4336 |
previous verifier in a reply to the requester. |
| 4337 |
|
| 4338 |
Note that if the replier carefully creates the SSV RPCSEC_GSS |
| 4339 |
handles, the related risk of a man-in-the-middle splicing a forged |
| 4340 |
SSV RPCSEC_GSS credential with a verifier for another handle does not |
| 4341 |
exist. This is because the verifier in an RPCSEC_GSS request is |
| 4342 |
computed from input that includes both the RPCSEC_GSS handle and |
| 4343 |
seq_num (see Section 5.3.1 of [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>]). Provided the replier takes care |
| 4344 |
to avoid re-using the value of an RPCSEC_GSS handle that it creates, |
| 4345 |
such as by including a generation number in the handle, the man-in- |
| 4346 |
the-middle will not be able to successfully replay a previous |
| 4347 |
verifier in the request to a replier. |
| 4348 |
|
| 4349 |
<span class="h4"><a class="selflink" id="section-2.10.11" href="#section-2.10.11">2.10.11</a>. Session Mechanics - Steady State</span> |
| 4350 |
|
| 4351 |
<span class="h5"><a class="selflink" id="section-2.10.11.1" href="#section-2.10.11.1">2.10.11.1</a>. Obligations of the Server</span> |
| 4352 |
|
| 4353 |
The server has the primary obligation to monitor the state of |
| 4354 |
backchannel resources that the client has created for the server |
| 4355 |
(RPCSEC_GSS contexts and backchannel connections). If these |
| 4356 |
resources vanish, the server takes action as specified in |
| 4357 |
<a href="#section-2.10.13.2">Section 2.10.13.2</a>. |
| 4358 |
|
| 4359 |
|
| 4360 |
|
| 4361 |
|
| 4362 |
|
| 4363 |
|
| 4364 |
<span class="grey">Shepler, et al. Standards Track [Page 78]</span></pre> |
| 4365 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-79" ></span> |
| 4366 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4367 |
|
| 4368 |
|
| 4369 |
<span class="h5"><a class="selflink" id="section-2.10.11.2" href="#section-2.10.11.2">2.10.11.2</a>. Obligations of the Client</span> |
| 4370 |
|
| 4371 |
The client SHOULD honor the following obligations in order to utilize |
| 4372 |
the session: |
| 4373 |
|
| 4374 |
o Keep a necessary session from going idle on the server. A client |
| 4375 |
that requires a session but nonetheless is not sending operations |
| 4376 |
risks having the session be destroyed by the server. This is |
| 4377 |
because sessions consume resources, and resource limitations may |
| 4378 |
force the server to cull an inactive session. A server MAY |
| 4379 |
consider a session to be inactive if the client has not used the |
| 4380 |
session before the session inactivity timer (<a href="#section-2.10.12">Section 2.10.12</a>) has |
| 4381 |
expired. |
| 4382 |
|
| 4383 |
o Destroy the session when not needed. If a client has multiple |
| 4384 |
sessions, one of which has no requests waiting for replies, and |
| 4385 |
has been idle for some period of time, it SHOULD destroy the |
| 4386 |
session. |
| 4387 |
|
| 4388 |
o Maintain GSS contexts and RPCSEC_GSS handles for the backchannel. |
| 4389 |
If the client requires the server to use the RPCSEC_GSS security |
| 4390 |
flavor for callbacks, then it needs to be sure the RPCSEC_GSS |
| 4391 |
handles and/or their GSS contexts that are handed to the server |
| 4392 |
via BACKCHANNEL_CTL or CREATE_SESSION are unexpired. |
| 4393 |
|
| 4394 |
o Preserve a connection for a backchannel. The server requires a |
| 4395 |
backchannel in order to gracefully recall recallable state or |
| 4396 |
notify the client of certain events. Note that if the connection |
| 4397 |
is not being used for the fore channel, there is no way for the |
| 4398 |
client to tell if the connection is still alive (e.g., the server |
| 4399 |
restarted without sending a disconnect). The onus is on the |
| 4400 |
server, not the client, to determine if the backchannel's |
| 4401 |
connection is alive, and to indicate in the response to a SEQUENCE |
| 4402 |
operation when the last connection associated with a session's |
| 4403 |
backchannel has disconnected. |
| 4404 |
|
| 4405 |
<span class="h5"><a class="selflink" id="section-2.10.11.3" href="#section-2.10.11.3">2.10.11.3</a>. Steps the Client Takes to Establish a Session</span> |
| 4406 |
|
| 4407 |
If the client does not have a client ID, the client sends EXCHANGE_ID |
| 4408 |
to establish a client ID. If it opts for SP4_MACH_CRED or SP4_SSV |
| 4409 |
protection, in the spo_must_enforce list of operations, it SHOULD at |
| 4410 |
minimum specify CREATE_SESSION, DESTROY_SESSION, |
| 4411 |
BIND_CONN_TO_SESSION, BACKCHANNEL_CTL, and DESTROY_CLIENTID. If it |
| 4412 |
opts for SP4_SSV protection, the client needs to ask for SSV-based |
| 4413 |
RPCSEC_GSS handles. |
| 4414 |
|
| 4415 |
|
| 4416 |
|
| 4417 |
|
| 4418 |
|
| 4419 |
|
| 4420 |
<span class="grey">Shepler, et al. Standards Track [Page 79]</span></pre> |
| 4421 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-80" ></span> |
| 4422 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4423 |
|
| 4424 |
|
| 4425 |
The client uses the client ID to send a CREATE_SESSION on a |
| 4426 |
connection to the server. The results of CREATE_SESSION indicate |
| 4427 |
whether or not the server will persist the session reply cache |
| 4428 |
through a server that has restarted, and the client notes this for |
| 4429 |
future reference. |
| 4430 |
|
| 4431 |
If the client specified SP4_SSV state protection when the client ID |
| 4432 |
was created, then it SHOULD send SET_SSV in the first COMPOUND after |
| 4433 |
the session is created. Each time a new principal goes to use the |
| 4434 |
client ID, it SHOULD send a SET_SSV again. |
| 4435 |
|
| 4436 |
If the client wants to use delegations, layouts, directory |
| 4437 |
notifications, or any other state that requires a backchannel, then |
| 4438 |
it needs to add a connection to the backchannel if CREATE_SESSION did |
| 4439 |
not already do so. The client creates a connection, and calls |
| 4440 |
BIND_CONN_TO_SESSION to associate the connection with the session and |
| 4441 |
the session's backchannel. If CREATE_SESSION did not already do so, |
| 4442 |
the client MUST tell the server what security is required in order |
| 4443 |
for the client to accept callbacks. The client does this via |
| 4444 |
BACKCHANNEL_CTL. If the client selected SP4_MACH_CRED or SP4_SSV |
| 4445 |
protection when it called EXCHANGE_ID, then the client SHOULD specify |
| 4446 |
that the backchannel use RPCSEC_GSS contexts for security. |
| 4447 |
|
| 4448 |
If the client wants to use additional connections for the |
| 4449 |
backchannel, then it needs to call BIND_CONN_TO_SESSION on each |
| 4450 |
connection it wants to use with the session. If the client wants to |
| 4451 |
use additional connections for the fore channel, then it needs to |
| 4452 |
call BIND_CONN_TO_SESSION if it specified SP4_SSV or SP4_MACH_CRED |
| 4453 |
state protection when the client ID was created. |
| 4454 |
|
| 4455 |
At this point, the session has reached steady state. |
| 4456 |
|
| 4457 |
<span class="h4"><a class="selflink" id="section-2.10.12" href="#section-2.10.12">2.10.12</a>. Session Inactivity Timer</span> |
| 4458 |
|
| 4459 |
The server MAY maintain a session inactivity timer for each session. |
| 4460 |
If the session inactivity timer expires, then the server MAY destroy |
| 4461 |
the session. To avoid losing a session due to inactivity, the client |
| 4462 |
MUST renew the session inactivity timer. The length of session |
| 4463 |
inactivity timer MUST NOT be less than the lease_time attribute |
| 4464 |
(<a href="#section-5.8.1.11">Section 5.8.1.11</a>). As with lease renewal (<a href="#section-8.3">Section 8.3</a>), when the |
| 4465 |
server receives a SEQUENCE operation, it resets the session |
| 4466 |
inactivity timer, and MUST NOT allow the timer to expire while the |
| 4467 |
rest of the operations in the COMPOUND procedure's request are still |
| 4468 |
executing. Once the last operation has finished, the server MUST set |
| 4469 |
the session inactivity timer to expire no sooner than the sum of the |
| 4470 |
current time and the value of the lease_time attribute. |
| 4471 |
|
| 4472 |
|
| 4473 |
|
| 4474 |
|
| 4475 |
|
| 4476 |
<span class="grey">Shepler, et al. Standards Track [Page 80]</span></pre> |
| 4477 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-81" ></span> |
| 4478 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4479 |
|
| 4480 |
|
| 4481 |
<span class="h4"><a class="selflink" id="section-2.10.13" href="#section-2.10.13">2.10.13</a>. Session Mechanics - Recovery</span> |
| 4482 |
|
| 4483 |
<span class="h5"><a class="selflink" id="section-2.10.13.1" href="#section-2.10.13.1">2.10.13.1</a>. Events Requiring Client Action</span> |
| 4484 |
|
| 4485 |
The following events require client action to recover. |
| 4486 |
|
| 4487 |
<span class="h6"><a class="selflink" id="section-2.10.13.1.1" href="#section-2.10.13.1.1">2.10.13.1.1</a>. RPCSEC_GSS Context Loss by Callback Path</span> |
| 4488 |
|
| 4489 |
If all RPCSEC_GSS handles granted by the client to the server for |
| 4490 |
callback use have expired, the client MUST establish a new handle via |
| 4491 |
BACKCHANNEL_CTL. The sr_status_flags field of the SEQUENCE results |
| 4492 |
indicates when callback handles are nearly expired, or fully expired |
| 4493 |
(see <a href="#section-18.46.3">Section 18.46.3</a>). |
| 4494 |
|
| 4495 |
<span class="h6"><a class="selflink" id="section-2.10.13.1.2" href="#section-2.10.13.1.2">2.10.13.1.2</a>. Connection Loss</span> |
| 4496 |
|
| 4497 |
If the client loses the last connection of the session and wants to |
| 4498 |
retain the session, then it needs to create a new connection, and if, |
| 4499 |
when the client ID was created, BIND_CONN_TO_SESSION was specified in |
| 4500 |
the spo_must_enforce list, the client MUST use BIND_CONN_TO_SESSION |
| 4501 |
to associate the connection with the session. |
| 4502 |
|
| 4503 |
If there was a request outstanding at the time of connection loss, |
| 4504 |
then if the client wants to continue to use the session, it MUST |
| 4505 |
retry the request, as described in <a href="#section-2.10.6.2">Section 2.10.6.2</a>. Note that it is |
| 4506 |
not necessary to retry requests over a connection with the same |
| 4507 |
source network address or the same destination network address as the |
| 4508 |
lost connection. As long as the session ID, slot ID, and sequence ID |
| 4509 |
in the retry match that of the original request, the server will |
| 4510 |
recognize the request as a retry if it executed the request prior to |
| 4511 |
disconnect. |
| 4512 |
|
| 4513 |
If the connection that was lost was the last one associated with the |
| 4514 |
backchannel, and the client wants to retain the backchannel and/or |
| 4515 |
prevent revocation of recallable state, the client needs to |
| 4516 |
reconnect, and if it does, it MUST associate the connection to the |
| 4517 |
session and backchannel via BIND_CONN_TO_SESSION. The server SHOULD |
| 4518 |
indicate when it has no callback connection via the sr_status_flags |
| 4519 |
result from SEQUENCE. |
| 4520 |
|
| 4521 |
<span class="h6"><a class="selflink" id="section-2.10.13.1.3" href="#section-2.10.13.1.3">2.10.13.1.3</a>. Backchannel GSS Context Loss</span> |
| 4522 |
|
| 4523 |
Via the sr_status_flags result of the SEQUENCE operation or other |
| 4524 |
means, the client will learn if some or all of the RPCSEC_GSS |
| 4525 |
contexts it assigned to the backchannel have been lost. If the |
| 4526 |
client wants to retain the backchannel and/or not put recallable |
| 4527 |
state subject to revocation, the client needs to use BACKCHANNEL_CTL |
| 4528 |
to assign new contexts. |
| 4529 |
|
| 4530 |
|
| 4531 |
|
| 4532 |
<span class="grey">Shepler, et al. Standards Track [Page 81]</span></pre> |
| 4533 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-82" ></span> |
| 4534 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4535 |
|
| 4536 |
|
| 4537 |
<span class="h6"><a class="selflink" id="section-2.10.13.1.4" href="#section-2.10.13.1.4">2.10.13.1.4</a>. Loss of Session</span> |
| 4538 |
|
| 4539 |
The replier might lose a record of the session. Causes include: |
| 4540 |
|
| 4541 |
o Replier failure and restart. |
| 4542 |
|
| 4543 |
o A catastrophe that causes the reply cache to be corrupted or lost |
| 4544 |
on the media on which it was stored. This applies even if the |
| 4545 |
replier indicated in the CREATE_SESSION results that it would |
| 4546 |
persist the cache. |
| 4547 |
|
| 4548 |
o The server purges the session of a client that has been inactive |
| 4549 |
for a very extended period of time. |
| 4550 |
|
| 4551 |
o As a result of configuration changes among a set of clustered |
| 4552 |
servers, a network address previously connected to one server |
| 4553 |
becomes connected to a different server that has no knowledge of |
| 4554 |
the session in question. Such a configuration change will |
| 4555 |
generally only happen when the original server ceases to function |
| 4556 |
for a time. |
| 4557 |
|
| 4558 |
Loss of reply cache is equivalent to loss of session. The replier |
| 4559 |
indicates loss of session to the requester by returning |
| 4560 |
NFS4ERR_BADSESSION on the next operation that uses the session ID |
| 4561 |
that refers to the lost session. |
| 4562 |
|
| 4563 |
After an event like a server restart, the client may have lost its |
| 4564 |
connections. The client assumes for the moment that the session has |
| 4565 |
not been lost. It reconnects, and if it specified connection |
| 4566 |
association enforcement when the session was created, it invokes |
| 4567 |
BIND_CONN_TO_SESSION using the session ID. Otherwise, it invokes |
| 4568 |
SEQUENCE. If BIND_CONN_TO_SESSION or SEQUENCE returns |
| 4569 |
NFS4ERR_BADSESSION, the client knows the session is not available to |
| 4570 |
it when communicating with that network address. If the connection |
| 4571 |
survives session loss, then the next SEQUENCE operation the client |
| 4572 |
sends over the connection will get back NFS4ERR_BADSESSION. The |
| 4573 |
client again knows the session was lost. |
| 4574 |
|
| 4575 |
Here is one suggested algorithm for the client when it gets |
| 4576 |
NFS4ERR_BADSESSION. It is not obligatory in that, if a client does |
| 4577 |
not want to take advantage of such features as trunking, it may omit |
| 4578 |
parts of it. However, it is a useful example that draws attention to |
| 4579 |
various possible recovery issues: |
| 4580 |
|
| 4581 |
1. If the client has other connections to other server network |
| 4582 |
addresses associated with the same session, attempt a COMPOUND |
| 4583 |
with a single operation, SEQUENCE, on each of the other |
| 4584 |
connections. |
| 4585 |
|
| 4586 |
|
| 4587 |
|
| 4588 |
<span class="grey">Shepler, et al. Standards Track [Page 82]</span></pre> |
| 4589 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-83" ></span> |
| 4590 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4591 |
|
| 4592 |
|
| 4593 |
2. If the attempts succeed, the session is still alive, and this is |
| 4594 |
a strong indicator that the server's network address has moved. |
| 4595 |
The client might send an EXCHANGE_ID on the connection that |
| 4596 |
returned NFS4ERR_BADSESSION to see if there are opportunities for |
| 4597 |
client ID trunking (i.e., the same client ID and so_major are |
| 4598 |
returned). The client might use DNS to see if the moved network |
| 4599 |
address was replaced with another, so that the performance and |
| 4600 |
availability benefits of session trunking can continue. |
| 4601 |
|
| 4602 |
3. If the SEQUENCE requests fail with NFS4ERR_BADSESSION, then the |
| 4603 |
session no longer exists on any of the server network addresses |
| 4604 |
for which the client has connections associated with that session |
| 4605 |
ID. It is possible the session is still alive and available on |
| 4606 |
other network addresses. The client sends an EXCHANGE_ID on all |
| 4607 |
the connections to see if the server owner is still listening on |
| 4608 |
those network addresses. If the same server owner is returned |
| 4609 |
but a new client ID is returned, this is a strong indicator of a |
| 4610 |
server restart. If both the same server owner and same client ID |
| 4611 |
are returned, then this is a strong indication that the server |
| 4612 |
did delete the session, and the client will need to send a |
| 4613 |
CREATE_SESSION if it has no other sessions for that client ID. |
| 4614 |
If a different server owner is returned, the client can use DNS |
| 4615 |
to find other network addresses. If it does not, or if DNS does |
| 4616 |
not find any other addresses for the server, then the client will |
| 4617 |
be unable to provide NFSv4.1 service, and fatal errors should be |
| 4618 |
returned to processes that were using the server. If the client |
| 4619 |
is using a "mount" paradigm, unmounting the server is advised. |
| 4620 |
|
| 4621 |
4. If the client knows of no other connections associated with the |
| 4622 |
session ID and server network addresses that are, or have been, |
| 4623 |
associated with the session ID, then the client can use DNS to |
| 4624 |
find other network addresses. If it does not, or if DNS does not |
| 4625 |
find any other addresses for the server, then the client will be |
| 4626 |
unable to provide NFSv4.1 service, and fatal errors should be |
| 4627 |
returned to processes that were using the server. If the client |
| 4628 |
is using a "mount" paradigm, unmounting the server is advised. |
| 4629 |
|
| 4630 |
If there is a reconfiguration event that results in the same network |
| 4631 |
address being assigned to servers where the eir_server_scope value is |
| 4632 |
different, it cannot be guaranteed that a session ID generated by the |
| 4633 |
first will be recognized as invalid by the first. Therefore, in |
| 4634 |
managing server reconfigurations among servers with different server |
| 4635 |
scope values, it is necessary to make sure that all clients have |
| 4636 |
disconnected from the first server before effecting the |
| 4637 |
reconfiguration. Nonetheless, clients should not assume that servers |
| 4638 |
will always adhere to this requirement; clients MUST be prepared to |
| 4639 |
deal with unexpected effects of server reconfigurations. Even where |
| 4640 |
a session ID is inappropriately recognized as valid, it is likely |
| 4641 |
|
| 4642 |
|
| 4643 |
|
| 4644 |
<span class="grey">Shepler, et al. Standards Track [Page 83]</span></pre> |
| 4645 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-84" ></span> |
| 4646 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4647 |
|
| 4648 |
|
| 4649 |
either that the connection will not be recognized as valid or that a |
| 4650 |
sequence value for a slot will not be correct. Therefore, when a |
| 4651 |
client receives results indicating such unexpected errors, the use of |
| 4652 |
EXCHANGE_ID to determine the current server configuration is |
| 4653 |
RECOMMENDED. |
| 4654 |
|
| 4655 |
A variation on the above is that after a server's network address |
| 4656 |
moves, there is no NFSv4.1 server listening, e.g., no listener on |
| 4657 |
port 2049. In this example, one of the following occur: the NFSv4 |
| 4658 |
server returns NFS4ERR_MINOR_VERS_MISMATCH, the NFS server returns a |
| 4659 |
PROG_MISMATCH error, the RPC listener on 2049 returns PROG_UNVAIL, or |
| 4660 |
attempts to reconnect to the network address timeout. These SHOULD |
| 4661 |
be treated as equivalent to SEQUENCE returning NFS4ERR_BADSESSION for |
| 4662 |
these purposes. |
| 4663 |
|
| 4664 |
When the client detects session loss, it needs to call CREATE_SESSION |
| 4665 |
to recover. Any non-idempotent operations that were in progress |
| 4666 |
might have been performed on the server at the time of session loss. |
| 4667 |
The client has no general way to recover from this. |
| 4668 |
|
| 4669 |
Note that loss of session does not imply loss of byte-range lock, |
| 4670 |
open, delegation, or layout state because locks, opens, delegations, |
| 4671 |
and layouts are tied to the client ID and depend on the client ID, |
| 4672 |
not the session. Nor does loss of byte-range lock, open, delegation, |
| 4673 |
or layout state imply loss of session state, because the session |
| 4674 |
depends on the client ID; loss of client ID however does imply loss |
| 4675 |
of session, byte-range lock, open, delegation, and layout state. See |
| 4676 |
<a href="#section-8.4.2">Section 8.4.2</a>. A session can survive a server restart, but lock |
| 4677 |
recovery may still be needed. |
| 4678 |
|
| 4679 |
It is possible that CREATE_SESSION will fail with |
| 4680 |
NFS4ERR_STALE_CLIENTID (e.g., the server restarts and does not |
| 4681 |
preserve client ID state). If so, the client needs to call |
| 4682 |
EXCHANGE_ID, followed by CREATE_SESSION. |
| 4683 |
|
| 4684 |
<span class="h5"><a class="selflink" id="section-2.10.13.2" href="#section-2.10.13.2">2.10.13.2</a>. Events Requiring Server Action</span> |
| 4685 |
|
| 4686 |
The following events require server action to recover. |
| 4687 |
|
| 4688 |
<span class="h6"><a class="selflink" id="section-2.10.13.2.1" href="#section-2.10.13.2.1">2.10.13.2.1</a>. Client Crash and Restart</span> |
| 4689 |
|
| 4690 |
As described in <a href="#section-18.35">Section 18.35</a>, a restarted client sends EXCHANGE_ID |
| 4691 |
in such a way that it causes the server to delete any sessions it |
| 4692 |
had. |
| 4693 |
|
| 4694 |
|
| 4695 |
|
| 4696 |
|
| 4697 |
|
| 4698 |
|
| 4699 |
|
| 4700 |
<span class="grey">Shepler, et al. Standards Track [Page 84]</span></pre> |
| 4701 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-85" ></span> |
| 4702 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4703 |
|
| 4704 |
|
| 4705 |
<span class="h6"><a class="selflink" id="section-2.10.13.2.2" href="#section-2.10.13.2.2">2.10.13.2.2</a>. Client Crash with No Restart</span> |
| 4706 |
|
| 4707 |
If a client crashes and never comes back, it will never send |
| 4708 |
EXCHANGE_ID with its old client owner. Thus, the server has session |
| 4709 |
state that will never be used again. After an extended period of |
| 4710 |
time, and if the server has resource constraints, it MAY destroy the |
| 4711 |
old session as well as locking state. |
| 4712 |
|
| 4713 |
<span class="h6"><a class="selflink" id="section-2.10.13.2.3" href="#section-2.10.13.2.3">2.10.13.2.3</a>. Extended Network Partition</span> |
| 4714 |
|
| 4715 |
To the server, the extended network partition may be no different |
| 4716 |
from a client crash with no restart (see <a href="#section-2.10.13.2.2">Section 2.10.13.2.2</a>). |
| 4717 |
Unless the server can discern that there is a network partition, it |
| 4718 |
is free to treat the situation as if the client has crashed |
| 4719 |
permanently. |
| 4720 |
|
| 4721 |
<span class="h6"><a class="selflink" id="section-2.10.13.2.4" href="#section-2.10.13.2.4">2.10.13.2.4</a>. Backchannel Connection Loss</span> |
| 4722 |
|
| 4723 |
If there were callback requests outstanding at the time of a |
| 4724 |
connection loss, then the server MUST retry the requests, as |
| 4725 |
described in <a href="#section-2.10.6.2">Section 2.10.6.2</a>. Note that it is not necessary to |
| 4726 |
retry requests over a connection with the same source network address |
| 4727 |
or the same destination network address as the lost connection. As |
| 4728 |
long as the session ID, slot ID, and sequence ID in the retry match |
| 4729 |
that of the original request, the callback target will recognize the |
| 4730 |
request as a retry even if it did see the request prior to |
| 4731 |
disconnect. |
| 4732 |
|
| 4733 |
If the connection lost is the last one associated with the |
| 4734 |
backchannel, then the server MUST indicate that in the |
| 4735 |
sr_status_flags field of every SEQUENCE reply until the backchannel |
| 4736 |
is re-established. There are two situations, each of which uses |
| 4737 |
different status flags: no connectivity for the session's backchannel |
| 4738 |
and no connectivity for any session backchannel of the client. See |
| 4739 |
<a href="#section-18.46">Section 18.46</a> for a description of the appropriate flags in |
| 4740 |
sr_status_flags. |
| 4741 |
|
| 4742 |
<span class="h6"><a class="selflink" id="section-2.10.13.2.5" href="#section-2.10.13.2.5">2.10.13.2.5</a>. GSS Context Loss</span> |
| 4743 |
|
| 4744 |
The server SHOULD monitor when the number of RPCSEC_GSS handles |
| 4745 |
assigned to the backchannel reaches one, and when that one handle is |
| 4746 |
near expiry (i.e., between one and two periods of lease time), and |
| 4747 |
indicate so in the sr_status_flags field of all SEQUENCE replies. |
| 4748 |
The server MUST indicate when all of the backchannel's assigned |
| 4749 |
RPCSEC_GSS handles have expired via the sr_status_flags field of all |
| 4750 |
SEQUENCE replies. |
| 4751 |
|
| 4752 |
|
| 4753 |
|
| 4754 |
|
| 4755 |
|
| 4756 |
<span class="grey">Shepler, et al. Standards Track [Page 85]</span></pre> |
| 4757 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-86" ></span> |
| 4758 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4759 |
|
| 4760 |
|
| 4761 |
<span class="h4"><a class="selflink" id="section-2.10.14" href="#section-2.10.14">2.10.14</a>. Parallel NFS and Sessions</span> |
| 4762 |
|
| 4763 |
A client and server can potentially be a non-pNFS implementation, a |
| 4764 |
metadata server implementation, a data server implementation, or two |
| 4765 |
or three types of implementations. The EXCHGID4_FLAG_USE_NON_PNFS, |
| 4766 |
EXCHGID4_FLAG_USE_PNFS_MDS, and EXCHGID4_FLAG_USE_PNFS_DS flags (not |
| 4767 |
mutually exclusive) are passed in the EXCHANGE_ID arguments and |
| 4768 |
results to allow the client to indicate how it wants to use sessions |
| 4769 |
created under the client ID, and to allow the server to indicate how |
| 4770 |
it will allow the sessions to be used. See <a href="#section-13.1">Section 13.1</a> for pNFS |
| 4771 |
sessions considerations. |
| 4772 |
|
| 4773 |
<span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. Protocol Constants and Data Types</span> |
| 4774 |
|
| 4775 |
The syntax and semantics to describe the data types of the NFSv4.1 |
| 4776 |
protocol are defined in the XDR <a href="./rfc4506">RFC 4506</a> [<a href="#ref-2" title=""XDR: External Data Representation Standard"">2</a>] and RPC <a href="./rfc5531">RFC 5531</a> [<a href="#ref-3" title=""RPC: Remote Procedure Call Protocol Specification Version 2"">3</a>] |
| 4777 |
documents. The next sections build upon the XDR data types to define |
| 4778 |
constants, types, and structures specific to this protocol. The full |
| 4779 |
list of XDR data types is in [<a href="#ref-13" title=""Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description"">13</a>]. |
| 4780 |
|
| 4781 |
<span class="h3"><a class="selflink" id="section-3.1" href="#section-3.1">3.1</a>. Basic Constants</span> |
| 4782 |
|
| 4783 |
const NFS4_FHSIZE = 128; |
| 4784 |
const NFS4_VERIFIER_SIZE = 8; |
| 4785 |
const NFS4_OPAQUE_LIMIT = 1024; |
| 4786 |
const NFS4_SESSIONID_SIZE = 16; |
| 4787 |
|
| 4788 |
const NFS4_INT64_MAX = 0x7fffffffffffffff; |
| 4789 |
const NFS4_UINT64_MAX = 0xffffffffffffffff; |
| 4790 |
const NFS4_INT32_MAX = 0x7fffffff; |
| 4791 |
const NFS4_UINT32_MAX = 0xffffffff; |
| 4792 |
|
| 4793 |
const NFS4_MAXFILELEN = 0xffffffffffffffff; |
| 4794 |
const NFS4_MAXFILEOFF = 0xfffffffffffffffe; |
| 4795 |
|
| 4796 |
Except where noted, all these constants are defined in bytes. |
| 4797 |
|
| 4798 |
o NFS4_FHSIZE is the maximum size of a filehandle. |
| 4799 |
|
| 4800 |
o NFS4_VERIFIER_SIZE is the fixed size of a verifier. |
| 4801 |
|
| 4802 |
o NFS4_OPAQUE_LIMIT is the maximum size of certain opaque |
| 4803 |
information. |
| 4804 |
|
| 4805 |
o NFS4_SESSIONID_SIZE is the fixed size of a session identifier. |
| 4806 |
|
| 4807 |
o NFS4_INT64_MAX is the maximum value of a signed 64-bit integer. |
| 4808 |
|
| 4809 |
|
| 4810 |
|
| 4811 |
|
| 4812 |
<span class="grey">Shepler, et al. Standards Track [Page 86]</span></pre> |
| 4813 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-87" ></span> |
| 4814 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4815 |
|
| 4816 |
|
| 4817 |
o NFS4_UINT64_MAX is the maximum value of an unsigned 64-bit |
| 4818 |
integer. |
| 4819 |
|
| 4820 |
o NFS4_INT32_MAX is the maximum value of a signed 32-bit integer. |
| 4821 |
|
| 4822 |
o NFS4_UINT32_MAX is the maximum value of an unsigned 32-bit |
| 4823 |
integer. |
| 4824 |
|
| 4825 |
o NFS4_MAXFILELEN is the maximum length of a regular file. |
| 4826 |
|
| 4827 |
o NFS4_MAXFILEOFF is the maximum offset into a regular file. |
| 4828 |
|
| 4829 |
<span class="h3"><a class="selflink" id="section-3.2" href="#section-3.2">3.2</a>. Basic Data Types</span> |
| 4830 |
|
| 4831 |
These are the base NFSv4.1 data types. |
| 4832 |
|
| 4833 |
+---------------+---------------------------------------------------+ |
| 4834 |
| Data Type | Definition | |
| 4835 |
+---------------+---------------------------------------------------+ |
| 4836 |
| int32_t | typedef int int32_t; | |
| 4837 |
| uint32_t | typedef unsigned int uint32_t; | |
| 4838 |
| int64_t | typedef hyper int64_t; | |
| 4839 |
| uint64_t | typedef unsigned hyper uint64_t; | |
| 4840 |
| attrlist4 | typedef opaque attrlist4<>; | |
| 4841 |
| | Used for file/directory attributes. | |
| 4842 |
| bitmap4 | typedef uint32_t bitmap4<>; | |
| 4843 |
| | Used in attribute array encoding. | |
| 4844 |
| changeid4 | typedef uint64_t changeid4; | |
| 4845 |
| | Used in the definition of change_info4. | |
| 4846 |
| clientid4 | typedef uint64_t clientid4; | |
| 4847 |
| | Shorthand reference to client identification. | |
| 4848 |
| count4 | typedef uint32_t count4; | |
| 4849 |
| | Various count parameters (READ, WRITE, COMMIT). | |
| 4850 |
| length4 | typedef uint64_t length4; | |
| 4851 |
| | The length of a byte-range within a file. | |
| 4852 |
| mode4 | typedef uint32_t mode4; | |
| 4853 |
| | Mode attribute data type. | |
| 4854 |
| nfs_cookie4 | typedef uint64_t nfs_cookie4; | |
| 4855 |
| | Opaque cookie value for READDIR. | |
| 4856 |
| nfs_fh4 | typedef opaque nfs_fh4<NFS4_FHSIZE>; | |
| 4857 |
| | Filehandle definition. | |
| 4858 |
| nfs_ftype4 | enum nfs_ftype4; | |
| 4859 |
| | Various defined file types. | |
| 4860 |
| nfsstat4 | enum nfsstat4; | |
| 4861 |
| | Return value for operations. | |
| 4862 |
| offset4 | typedef uint64_t offset4; | |
| 4863 |
| | Various offset designations (READ, WRITE, LOCK, | |
| 4864 |
| | COMMIT). | |
| 4865 |
|
| 4866 |
|
| 4867 |
|
| 4868 |
<span class="grey">Shepler, et al. Standards Track [Page 87]</span></pre> |
| 4869 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-88" ></span> |
| 4870 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4871 |
|
| 4872 |
|
| 4873 |
| qop4 | typedef uint32_t qop4; | |
| 4874 |
| | Quality of protection designation in SECINFO. | |
| 4875 |
| sec_oid4 | typedef opaque sec_oid4<>; | |
| 4876 |
| | Security Object Identifier. The sec_oid4 data | |
| 4877 |
| | type is not really opaque. Instead, it contains | |
| 4878 |
| | an ASN.1 OBJECT IDENTIFIER as used by GSS-API in | |
| 4879 |
| | the mech_type argument to GSS_Init_sec_context. | |
| 4880 |
| | See [<a href="#ref-7" title=""Generic Security Service Application Program Interface Version 2, Update 1"">7</a>] for details. | |
| 4881 |
| sequenceid4 | typedef uint32_t sequenceid4; | |
| 4882 |
| | Sequence number used for various session | |
| 4883 |
| | operations (EXCHANGE_ID, CREATE_SESSION, | |
| 4884 |
| | SEQUENCE, CB_SEQUENCE). | |
| 4885 |
| seqid4 | typedef uint32_t seqid4; | |
| 4886 |
| | Sequence identifier used for locking. | |
| 4887 |
| sessionid4 | typedef opaque sessionid4[NFS4_SESSIONID_SIZE]; | |
| 4888 |
| | Session identifier. | |
| 4889 |
| slotid4 | typedef uint32_t slotid4; | |
| 4890 |
| | Sequencing artifact for various session | |
| 4891 |
| | operations (SEQUENCE, CB_SEQUENCE). | |
| 4892 |
| utf8string | typedef opaque utf8string<>; | |
| 4893 |
| | UTF-8 encoding for strings. | |
| 4894 |
| utf8str_cis | typedef utf8string utf8str_cis; | |
| 4895 |
| | Case-insensitive UTF-8 string. | |
| 4896 |
| utf8str_cs | typedef utf8string utf8str_cs; | |
| 4897 |
| | Case-sensitive UTF-8 string. | |
| 4898 |
| utf8str_mixed | typedef utf8string utf8str_mixed; | |
| 4899 |
| | UTF-8 strings with a case-sensitive prefix and a | |
| 4900 |
| | case-insensitive suffix. | |
| 4901 |
| component4 | typedef utf8str_cs component4; | |
| 4902 |
| | Represents pathname components. | |
| 4903 |
| linktext4 | typedef utf8str_cs linktext4; | |
| 4904 |
| | Symbolic link contents ("symbolic link" is | |
| 4905 |
| | defined in an Open Group [<a href="#ref-14" title="">14</a>] standard). | |
| 4906 |
| pathname4 | typedef component4 pathname4<>; | |
| 4907 |
| | Represents pathname for fs_locations. | |
| 4908 |
| verifier4 | typedef opaque verifier4[NFS4_VERIFIER_SIZE]; | |
| 4909 |
| | Verifier used for various operations (COMMIT, | |
| 4910 |
| | CREATE, EXCHANGE_ID, OPEN, READDIR, WRITE) | |
| 4911 |
| | NFS4_VERIFIER_SIZE is defined as 8. | |
| 4912 |
+---------------+---------------------------------------------------+ |
| 4913 |
|
| 4914 |
End of Base Data Types |
| 4915 |
|
| 4916 |
Table 1 |
| 4917 |
|
| 4918 |
|
| 4919 |
|
| 4920 |
|
| 4921 |
|
| 4922 |
|
| 4923 |
|
| 4924 |
<span class="grey">Shepler, et al. Standards Track [Page 88]</span></pre> |
| 4925 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-89" ></span> |
| 4926 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4927 |
|
| 4928 |
|
| 4929 |
<span class="h3"><a class="selflink" id="section-3.3" href="#section-3.3">3.3</a>. Structured Data Types</span> |
| 4930 |
|
| 4931 |
<span class="h4"><a class="selflink" id="section-3.3.1" href="#section-3.3.1">3.3.1</a>. nfstime4</span> |
| 4932 |
|
| 4933 |
struct nfstime4 { |
| 4934 |
int64_t seconds; |
| 4935 |
uint32_t nseconds; |
| 4936 |
}; |
| 4937 |
|
| 4938 |
The nfstime4 data type gives the number of seconds and nanoseconds |
| 4939 |
since midnight or zero hour January 1, 1970 Coordinated Universal |
| 4940 |
Time (UTC). Values greater than zero for the seconds field denote |
| 4941 |
dates after the zero hour January 1, 1970. Values less than zero for |
| 4942 |
the seconds field denote dates before the zero hour January 1, 1970. |
| 4943 |
In both cases, the nseconds field is to be added to the seconds field |
| 4944 |
for the final time representation. For example, if the time to be |
| 4945 |
represented is one-half second before zero hour January 1, 1970, the |
| 4946 |
seconds field would have a value of negative one (-1) and the |
| 4947 |
nseconds field would have a value of one-half second (500000000). |
| 4948 |
Values greater than 999,999,999 for nseconds are invalid. |
| 4949 |
|
| 4950 |
This data type is used to pass time and date information. A server |
| 4951 |
converts to and from its local representation of time when processing |
| 4952 |
time values, preserving as much accuracy as possible. If the |
| 4953 |
precision of timestamps stored for a file system object is less than |
| 4954 |
defined, loss of precision can occur. An adjunct time maintenance |
| 4955 |
protocol is RECOMMENDED to reduce client and server time skew. |
| 4956 |
|
| 4957 |
<span class="h4"><a class="selflink" id="section-3.3.2" href="#section-3.3.2">3.3.2</a>. time_how4</span> |
| 4958 |
|
| 4959 |
enum time_how4 { |
| 4960 |
SET_TO_SERVER_TIME4 = 0, |
| 4961 |
SET_TO_CLIENT_TIME4 = 1 |
| 4962 |
}; |
| 4963 |
|
| 4964 |
<span class="h4"><a class="selflink" id="section-3.3.3" href="#section-3.3.3">3.3.3</a>. settime4</span> |
| 4965 |
|
| 4966 |
union settime4 switch (time_how4 set_it) { |
| 4967 |
case SET_TO_CLIENT_TIME4: |
| 4968 |
nfstime4 time; |
| 4969 |
default: |
| 4970 |
void; |
| 4971 |
}; |
| 4972 |
|
| 4973 |
The time_how4 and settime4 data types are used for setting timestamps |
| 4974 |
in file object attributes. If set_it is SET_TO_SERVER_TIME4, then |
| 4975 |
the server uses its local representation of time for the time value. |
| 4976 |
|
| 4977 |
|
| 4978 |
|
| 4979 |
|
| 4980 |
<span class="grey">Shepler, et al. Standards Track [Page 89]</span></pre> |
| 4981 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-90" ></span> |
| 4982 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 4983 |
|
| 4984 |
|
| 4985 |
<span class="h4"><a class="selflink" id="section-3.3.4" href="#section-3.3.4">3.3.4</a>. specdata4</span> |
| 4986 |
|
| 4987 |
struct specdata4 { |
| 4988 |
uint32_t specdata1; /* major device number */ |
| 4989 |
uint32_t specdata2; /* minor device number */ |
| 4990 |
}; |
| 4991 |
|
| 4992 |
This data type represents the device numbers for the device file |
| 4993 |
types NF4CHR and NF4BLK. |
| 4994 |
|
| 4995 |
<span class="h4"><a class="selflink" id="section-3.3.5" href="#section-3.3.5">3.3.5</a>. fsid4</span> |
| 4996 |
|
| 4997 |
struct fsid4 { |
| 4998 |
uint64_t major; |
| 4999 |
uint64_t minor; |
| 5000 |
}; |
| 5001 |
|
| 5002 |
<span class="h4"><a class="selflink" id="section-3.3.6" href="#section-3.3.6">3.3.6</a>. change_policy4</span> |
| 5003 |
|
| 5004 |
struct change_policy4 { |
| 5005 |
uint64_t cp_major; |
| 5006 |
uint64_t cp_minor; |
| 5007 |
}; |
| 5008 |
|
| 5009 |
The change_policy4 data type is used for the change_policy |
| 5010 |
RECOMMENDED attribute. It provides change sequencing indication |
| 5011 |
analogous to the change attribute. To enable the server to present a |
| 5012 |
value valid across server re-initialization without requiring |
| 5013 |
persistent storage, two 64-bit quantities are used, allowing one to |
| 5014 |
be a server instance ID and the second to be incremented non- |
| 5015 |
persistently, within a given server instance. |
| 5016 |
|
| 5017 |
<span class="h4"><a class="selflink" id="section-3.3.7" href="#section-3.3.7">3.3.7</a>. fattr4</span> |
| 5018 |
|
| 5019 |
struct fattr4 { |
| 5020 |
bitmap4 attrmask; |
| 5021 |
attrlist4 attr_vals; |
| 5022 |
}; |
| 5023 |
|
| 5024 |
The fattr4 data type is used to represent file and directory |
| 5025 |
attributes. |
| 5026 |
|
| 5027 |
The bitmap is a counted array of 32-bit integers used to contain bit |
| 5028 |
values. The position of the integer in the array that contains bit n |
| 5029 |
can be computed from the expression (n / 32), and its bit within that |
| 5030 |
integer is (n mod 32). |
| 5031 |
|
| 5032 |
|
| 5033 |
|
| 5034 |
|
| 5035 |
|
| 5036 |
<span class="grey">Shepler, et al. Standards Track [Page 90]</span></pre> |
| 5037 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-91" ></span> |
| 5038 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5039 |
|
| 5040 |
|
| 5041 |
0 1 |
| 5042 |
+-----------+-----------+-----------+-- |
| 5043 |
| count | 31 .. 0 | 63 .. 32 | |
| 5044 |
+-----------+-----------+-----------+-- |
| 5045 |
|
| 5046 |
<span class="h4"><a class="selflink" id="section-3.3.8" href="#section-3.3.8">3.3.8</a>. change_info4</span> |
| 5047 |
|
| 5048 |
struct change_info4 { |
| 5049 |
bool atomic; |
| 5050 |
changeid4 before; |
| 5051 |
changeid4 after; |
| 5052 |
}; |
| 5053 |
|
| 5054 |
This data type is used with the CREATE, LINK, OPEN, REMOVE, and |
| 5055 |
RENAME operations to let the client know the value of the change |
| 5056 |
attribute for the directory in which the target file system object |
| 5057 |
resides. |
| 5058 |
|
| 5059 |
<span class="h4"><a class="selflink" id="section-3.3.9" href="#section-3.3.9">3.3.9</a>. netaddr4</span> |
| 5060 |
|
| 5061 |
struct netaddr4 { |
| 5062 |
/* see struct rpcb in <a href="./rfc1833">RFC 1833</a> */ |
| 5063 |
string na_r_netid<>; /* network id */ |
| 5064 |
string na_r_addr<>; /* universal address */ |
| 5065 |
}; |
| 5066 |
|
| 5067 |
The netaddr4 data type is used to identify network transport |
| 5068 |
endpoints. The r_netid and r_addr fields respectively contain a |
| 5069 |
netid and uaddr. The netid and uaddr concepts are defined in [<a href="#ref-15" title=""IANA Considerations for Remote Procedure Call (RPC) Network Identifiers and Universal Address Formats"">15</a>]. |
| 5070 |
The netid and uaddr formats for TCP over IPv4 and TCP over IPv6 are |
| 5071 |
defined in [<a href="#ref-15" title=""IANA Considerations for Remote Procedure Call (RPC) Network Identifiers and Universal Address Formats"">15</a>], specifically Tables 2 and 3 and Sections <a href="#section-5.2.3.3">5.2.3.3</a> and |
| 5072 |
5.2.3.4. |
| 5073 |
|
| 5074 |
<span class="h4"><a class="selflink" id="section-3.3.10" href="#section-3.3.10">3.3.10</a>. state_owner4</span> |
| 5075 |
|
| 5076 |
struct state_owner4 { |
| 5077 |
clientid4 clientid; |
| 5078 |
opaque owner<NFS4_OPAQUE_LIMIT>; |
| 5079 |
}; |
| 5080 |
|
| 5081 |
typedef state_owner4 open_owner4; |
| 5082 |
typedef state_owner4 lock_owner4; |
| 5083 |
|
| 5084 |
The state_owner4 data type is the base type for the open_owner4 |
| 5085 |
(<a href="#section-3.3.10.1">Section 3.3.10.1</a>) and lock_owner4 (<a href="#section-3.3.10.2">Section 3.3.10.2</a>). |
| 5086 |
|
| 5087 |
|
| 5088 |
|
| 5089 |
|
| 5090 |
|
| 5091 |
|
| 5092 |
<span class="grey">Shepler, et al. Standards Track [Page 91]</span></pre> |
| 5093 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-92" ></span> |
| 5094 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5095 |
|
| 5096 |
|
| 5097 |
<span class="h5"><a class="selflink" id="section-3.3.10.1" href="#section-3.3.10.1">3.3.10.1</a>. open_owner4</span> |
| 5098 |
|
| 5099 |
This data type is used to identify the owner of OPEN state. |
| 5100 |
|
| 5101 |
<span class="h5"><a class="selflink" id="section-3.3.10.2" href="#section-3.3.10.2">3.3.10.2</a>. lock_owner4</span> |
| 5102 |
|
| 5103 |
This structure is used to identify the owner of byte-range locking |
| 5104 |
state. |
| 5105 |
|
| 5106 |
<span class="h4"><a class="selflink" id="section-3.3.11" href="#section-3.3.11">3.3.11</a>. open_to_lock_owner4</span> |
| 5107 |
|
| 5108 |
struct open_to_lock_owner4 { |
| 5109 |
seqid4 open_seqid; |
| 5110 |
stateid4 open_stateid; |
| 5111 |
seqid4 lock_seqid; |
| 5112 |
lock_owner4 lock_owner; |
| 5113 |
}; |
| 5114 |
|
| 5115 |
This data type is used for the first LOCK operation done for an |
| 5116 |
open_owner4. It provides both the open_stateid and lock_owner, such |
| 5117 |
that the transition is made from a valid open_stateid sequence to |
| 5118 |
that of the new lock_stateid sequence. Using this mechanism avoids |
| 5119 |
the confirmation of the lock_owner/lock_seqid pair since it is tied |
| 5120 |
to established state in the form of the open_stateid/open_seqid. |
| 5121 |
|
| 5122 |
<span class="h4"><a class="selflink" id="section-3.3.12" href="#section-3.3.12">3.3.12</a>. stateid4</span> |
| 5123 |
|
| 5124 |
struct stateid4 { |
| 5125 |
uint32_t seqid; |
| 5126 |
opaque other[12]; |
| 5127 |
}; |
| 5128 |
|
| 5129 |
This data type is used for the various state sharing mechanisms |
| 5130 |
between the client and server. The client never modifies a value of |
| 5131 |
data type stateid. The starting value of the "seqid" field is |
| 5132 |
undefined. The server is required to increment the "seqid" field by |
| 5133 |
one at each transition of the stateid. This is important since the |
| 5134 |
client will inspect the seqid in OPEN stateids to determine the order |
| 5135 |
of OPEN processing done by the server. |
| 5136 |
|
| 5137 |
<span class="h4"><a class="selflink" id="section-3.3.13" href="#section-3.3.13">3.3.13</a>. layouttype4</span> |
| 5138 |
|
| 5139 |
enum layouttype4 { |
| 5140 |
LAYOUT4_NFSV4_1_FILES = 0x1, |
| 5141 |
LAYOUT4_OSD2_OBJECTS = 0x2, |
| 5142 |
LAYOUT4_BLOCK_VOLUME = 0x3 |
| 5143 |
}; |
| 5144 |
|
| 5145 |
|
| 5146 |
|
| 5147 |
|
| 5148 |
<span class="grey">Shepler, et al. Standards Track [Page 92]</span></pre> |
| 5149 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-93" ></span> |
| 5150 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5151 |
|
| 5152 |
|
| 5153 |
This data type indicates what type of layout is being used. The file |
| 5154 |
server advertises the layout types it supports through the |
| 5155 |
fs_layout_type file system attribute (<a href="#section-5.12.1">Section 5.12.1</a>). A client asks |
| 5156 |
for layouts of a particular type in LAYOUTGET, and processes those |
| 5157 |
layouts in its layout-type-specific logic. |
| 5158 |
|
| 5159 |
The layouttype4 data type is 32 bits in length. The range |
| 5160 |
represented by the layout type is split into three parts. Type 0x0 |
| 5161 |
is reserved. Types within the range 0x00000001-0x7FFFFFFF are |
| 5162 |
globally unique and are assigned according to the description in |
| 5163 |
<a href="#section-22.4">Section 22.4</a>; they are maintained by IANA. Types within the range |
| 5164 |
0x80000000-0xFFFFFFFF are site specific and for private use only. |
| 5165 |
|
| 5166 |
The LAYOUT4_NFSV4_1_FILES enumeration specifies that the NFSv4.1 file |
| 5167 |
layout type, as defined in <a href="#section-13">Section 13</a>, is to be used. The |
| 5168 |
LAYOUT4_OSD2_OBJECTS enumeration specifies that the object layout, as |
| 5169 |
defined in [<a href="#ref-40" title=""Object-Based Parallel NFS (pNFS) Operations"">40</a>], is to be used. Similarly, the LAYOUT4_BLOCK_VOLUME |
| 5170 |
enumeration specifies that the block/volume layout, as defined in |
| 5171 |
[<a href="#ref-41" title=""Parallel NFS (pNFS) Block/Volume Layout"">41</a>], is to be used. |
| 5172 |
|
| 5173 |
<span class="h4"><a class="selflink" id="section-3.3.14" href="#section-3.3.14">3.3.14</a>. deviceid4</span> |
| 5174 |
|
| 5175 |
const NFS4_DEVICEID4_SIZE = 16; |
| 5176 |
|
| 5177 |
typedef opaque deviceid4[NFS4_DEVICEID4_SIZE]; |
| 5178 |
|
| 5179 |
Layout information includes device IDs that specify a storage device |
| 5180 |
through a compact handle. Addressing and type information is |
| 5181 |
obtained with the GETDEVICEINFO operation. Device IDs are not |
| 5182 |
guaranteed to be valid across metadata server restarts. A device ID |
| 5183 |
is unique per client ID and layout type. See <a href="#section-12.2.10">Section 12.2.10</a> for |
| 5184 |
more details. |
| 5185 |
|
| 5186 |
<span class="h4"><a class="selflink" id="section-3.3.15" href="#section-3.3.15">3.3.15</a>. device_addr4</span> |
| 5187 |
|
| 5188 |
struct device_addr4 { |
| 5189 |
layouttype4 da_layout_type; |
| 5190 |
opaque da_addr_body<>; |
| 5191 |
}; |
| 5192 |
|
| 5193 |
The device address is used to set up a communication channel with the |
| 5194 |
storage device. Different layout types will require different data |
| 5195 |
types to define how they communicate with storage devices. The |
| 5196 |
opaque da_addr_body field is interpreted based on the specified |
| 5197 |
da_layout_type field. |
| 5198 |
|
| 5199 |
|
| 5200 |
|
| 5201 |
|
| 5202 |
|
| 5203 |
|
| 5204 |
<span class="grey">Shepler, et al. Standards Track [Page 93]</span></pre> |
| 5205 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-94" ></span> |
| 5206 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5207 |
|
| 5208 |
|
| 5209 |
This document defines the device address for the NFSv4.1 file layout |
| 5210 |
(see <a href="#section-13.3">Section 13.3</a>), which identifies a storage device by network IP |
| 5211 |
address and port number. This is sufficient for the clients to |
| 5212 |
communicate with the NFSv4.1 storage devices, and may be sufficient |
| 5213 |
for other layout types as well. Device types for object-based |
| 5214 |
storage devices and block storage devices (e.g., Small Computer |
| 5215 |
System Interface (SCSI) volume labels) are defined by their |
| 5216 |
respective layout specifications. |
| 5217 |
|
| 5218 |
<span class="h4"><a class="selflink" id="section-3.3.16" href="#section-3.3.16">3.3.16</a>. layout_content4</span> |
| 5219 |
|
| 5220 |
struct layout_content4 { |
| 5221 |
layouttype4 loc_type; |
| 5222 |
opaque loc_body<>; |
| 5223 |
}; |
| 5224 |
|
| 5225 |
The loc_body field is interpreted based on the layout type |
| 5226 |
(loc_type). This document defines the loc_body for the NFSv4.1 file |
| 5227 |
layout type; see <a href="#section-13.3">Section 13.3</a> for its definition. |
| 5228 |
|
| 5229 |
<span class="h4"><a class="selflink" id="section-3.3.17" href="#section-3.3.17">3.3.17</a>. layout4</span> |
| 5230 |
|
| 5231 |
struct layout4 { |
| 5232 |
offset4 lo_offset; |
| 5233 |
length4 lo_length; |
| 5234 |
layoutiomode4 lo_iomode; |
| 5235 |
layout_content4 lo_content; |
| 5236 |
}; |
| 5237 |
|
| 5238 |
The layout4 data type defines a layout for a file. The layout type |
| 5239 |
specific data is opaque within lo_content. Since layouts are sub- |
| 5240 |
dividable, the offset and length together with the file's filehandle, |
| 5241 |
the client ID, iomode, and layout type identify the layout. |
| 5242 |
|
| 5243 |
<span class="h4"><a class="selflink" id="section-3.3.18" href="#section-3.3.18">3.3.18</a>. layoutupdate4</span> |
| 5244 |
|
| 5245 |
struct layoutupdate4 { |
| 5246 |
layouttype4 lou_type; |
| 5247 |
opaque lou_body<>; |
| 5248 |
}; |
| 5249 |
|
| 5250 |
The layoutupdate4 data type is used by the client to return updated |
| 5251 |
layout information to the metadata server via the LAYOUTCOMMIT |
| 5252 |
(<a href="#section-18.42">Section 18.42</a>) operation. This data type provides a channel to pass |
| 5253 |
layout type specific information (in field lou_body) back to the |
| 5254 |
metadata server. For example, for the block/volume layout type, this |
| 5255 |
could include the list of reserved blocks that were written. The |
| 5256 |
contents of the opaque lou_body argument are determined by the layout |
| 5257 |
|
| 5258 |
|
| 5259 |
|
| 5260 |
<span class="grey">Shepler, et al. Standards Track [Page 94]</span></pre> |
| 5261 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-95" ></span> |
| 5262 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5263 |
|
| 5264 |
|
| 5265 |
type. The NFSv4.1 file-based layout does not use this data type; if |
| 5266 |
lou_type is LAYOUT4_NFSV4_1_FILES, the lou_body field MUST have a |
| 5267 |
zero length. |
| 5268 |
|
| 5269 |
<span class="h4"><a class="selflink" id="section-3.3.19" href="#section-3.3.19">3.3.19</a>. layouthint4</span> |
| 5270 |
|
| 5271 |
struct layouthint4 { |
| 5272 |
layouttype4 loh_type; |
| 5273 |
opaque loh_body<>; |
| 5274 |
}; |
| 5275 |
|
| 5276 |
The layouthint4 data type is used by the client to pass in a hint |
| 5277 |
about the type of layout it would like created for a particular file. |
| 5278 |
It is the data type specified by the layout_hint attribute described |
| 5279 |
in <a href="#section-5.12.4">Section 5.12.4</a>. The metadata server may ignore the hint or may |
| 5280 |
selectively ignore fields within the hint. This hint should be |
| 5281 |
provided at create time as part of the initial attributes within |
| 5282 |
OPEN. The loh_body field is specific to the type of layout |
| 5283 |
(loh_type). The NFSv4.1 file-based layout uses the |
| 5284 |
nfsv4_1_file_layouthint4 data type as defined in <a href="#section-13.3">Section 13.3</a>. |
| 5285 |
|
| 5286 |
<span class="h4"><a class="selflink" id="section-3.3.20" href="#section-3.3.20">3.3.20</a>. layoutiomode4</span> |
| 5287 |
|
| 5288 |
enum layoutiomode4 { |
| 5289 |
LAYOUTIOMODE4_READ = 1, |
| 5290 |
LAYOUTIOMODE4_RW = 2, |
| 5291 |
LAYOUTIOMODE4_ANY = 3 |
| 5292 |
}; |
| 5293 |
|
| 5294 |
The iomode specifies whether the client intends to just read or both |
| 5295 |
read and write the data represented by the layout. While the |
| 5296 |
LAYOUTIOMODE4_ANY iomode MUST NOT be used in the arguments to the |
| 5297 |
LAYOUTGET operation, it MAY be used in the arguments to the |
| 5298 |
LAYOUTRETURN and CB_LAYOUTRECALL operations. The LAYOUTIOMODE4_ANY |
| 5299 |
iomode specifies that layouts pertaining to both LAYOUTIOMODE4_READ |
| 5300 |
and LAYOUTIOMODE4_RW iomodes are being returned or recalled, |
| 5301 |
respectively. The metadata server's use of the iomode may depend on |
| 5302 |
the layout type being used. The storage devices MAY validate I/O |
| 5303 |
accesses against the iomode and reject invalid accesses. |
| 5304 |
|
| 5305 |
<span class="h4"><a class="selflink" id="section-3.3.21" href="#section-3.3.21">3.3.21</a>. nfs_impl_id4</span> |
| 5306 |
|
| 5307 |
struct nfs_impl_id4 { |
| 5308 |
utf8str_cis nii_domain; |
| 5309 |
utf8str_cs nii_name; |
| 5310 |
nfstime4 nii_date; |
| 5311 |
}; |
| 5312 |
|
| 5313 |
|
| 5314 |
|
| 5315 |
|
| 5316 |
<span class="grey">Shepler, et al. Standards Track [Page 95]</span></pre> |
| 5317 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-96" ></span> |
| 5318 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5319 |
|
| 5320 |
|
| 5321 |
This data type is used to identify client and server implementation |
| 5322 |
details. The nii_domain field is the DNS domain name with which the |
| 5323 |
implementor is associated. The nii_name field is the product name of |
| 5324 |
the implementation and is completely free form. It is RECOMMENDED |
| 5325 |
that the nii_name be used to distinguish machine architecture, |
| 5326 |
machine platforms, revisions, versions, and patch levels. The |
| 5327 |
nii_date field is the timestamp of when the software instance was |
| 5328 |
published or built. |
| 5329 |
|
| 5330 |
<span class="h4"><a class="selflink" id="section-3.3.22" href="#section-3.3.22">3.3.22</a>. threshold_item4</span> |
| 5331 |
|
| 5332 |
struct threshold_item4 { |
| 5333 |
layouttype4 thi_layout_type; |
| 5334 |
bitmap4 thi_hintset; |
| 5335 |
opaque thi_hintlist<>; |
| 5336 |
}; |
| 5337 |
|
| 5338 |
This data type contains a list of hints specific to a layout type for |
| 5339 |
helping the client determine when it should send I/O directly through |
| 5340 |
the metadata server versus the storage devices. The data type |
| 5341 |
consists of the layout type (thi_layout_type), a bitmap (thi_hintset) |
| 5342 |
describing the set of hints supported by the server (they may differ |
| 5343 |
based on the layout type), and a list of hints (thi_hintlist) whose |
| 5344 |
content is determined by the hintset bitmap. See the mdsthreshold |
| 5345 |
attribute for more details. |
| 5346 |
|
| 5347 |
The thi_hintset field is a bitmap of the following values: |
| 5348 |
|
| 5349 |
|
| 5350 |
|
| 5351 |
|
| 5352 |
|
| 5353 |
|
| 5354 |
|
| 5355 |
|
| 5356 |
|
| 5357 |
|
| 5358 |
|
| 5359 |
|
| 5360 |
|
| 5361 |
|
| 5362 |
|
| 5363 |
|
| 5364 |
|
| 5365 |
|
| 5366 |
|
| 5367 |
|
| 5368 |
|
| 5369 |
|
| 5370 |
|
| 5371 |
|
| 5372 |
<span class="grey">Shepler, et al. Standards Track [Page 96]</span></pre> |
| 5373 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-97" ></span> |
| 5374 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5375 |
|
| 5376 |
|
| 5377 |
+-------------------------+---+---------+---------------------------+ |
| 5378 |
| name | # | Data | Description | |
| 5379 |
| | | Type | | |
| 5380 |
+-------------------------+---+---------+---------------------------+ |
| 5381 |
| threshold4_read_size | 0 | length4 | If a file's length is | |
| 5382 |
| | | | less than the value of | |
| 5383 |
| | | | threshold4_read_size, | |
| 5384 |
| | | | then it is RECOMMENDED | |
| 5385 |
| | | | that the client read from | |
| 5386 |
| | | | the file via the MDS and | |
| 5387 |
| | | | not a storage device. | |
| 5388 |
| threshold4_write_size | 1 | length4 | If a file's length is | |
| 5389 |
| | | | less than the value of | |
| 5390 |
| | | | threshold4_write_size, | |
| 5391 |
| | | | then it is RECOMMENDED | |
| 5392 |
| | | | that the client write to | |
| 5393 |
| | | | the file via the MDS and | |
| 5394 |
| | | | not a storage device. | |
| 5395 |
| threshold4_read_iosize | 2 | length4 | For read I/O sizes below | |
| 5396 |
| | | | this threshold, it is | |
| 5397 |
| | | | RECOMMENDED to read data | |
| 5398 |
| | | | through the MDS. | |
| 5399 |
| threshold4_write_iosize | 3 | length4 | For write I/O sizes below | |
| 5400 |
| | | | this threshold, it is | |
| 5401 |
| | | | RECOMMENDED to write data | |
| 5402 |
| | | | through the MDS. | |
| 5403 |
+-------------------------+---+---------+---------------------------+ |
| 5404 |
|
| 5405 |
<span class="h4"><a class="selflink" id="section-3.3.23" href="#section-3.3.23">3.3.23</a>. mdsthreshold4</span> |
| 5406 |
|
| 5407 |
struct mdsthreshold4 { |
| 5408 |
threshold_item4 mth_hints<>; |
| 5409 |
}; |
| 5410 |
|
| 5411 |
This data type holds an array of elements of data type |
| 5412 |
threshold_item4, each of which is valid for a particular layout type. |
| 5413 |
An array is necessary because a server can support multiple layout |
| 5414 |
types for a single file. |
| 5415 |
|
| 5416 |
<span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. Filehandles</span> |
| 5417 |
|
| 5418 |
The filehandle in the NFS protocol is a per-server unique identifier |
| 5419 |
for a file system object. The contents of the filehandle are opaque |
| 5420 |
to the client. Therefore, the server is responsible for translating |
| 5421 |
the filehandle to an internal representation of the file system |
| 5422 |
object. |
| 5423 |
|
| 5424 |
|
| 5425 |
|
| 5426 |
|
| 5427 |
|
| 5428 |
<span class="grey">Shepler, et al. Standards Track [Page 97]</span></pre> |
| 5429 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-98" ></span> |
| 5430 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5431 |
|
| 5432 |
|
| 5433 |
<span class="h3"><a class="selflink" id="section-4.1" href="#section-4.1">4.1</a>. Obtaining the First Filehandle</span> |
| 5434 |
|
| 5435 |
The operations of the NFS protocol are defined in terms of one or |
| 5436 |
more filehandles. Therefore, the client needs a filehandle to |
| 5437 |
initiate communication with the server. With the NFSv3 protocol (<a href="./rfc1813">RFC</a> |
| 5438 |
<a href="./rfc1813">1813</a> [<a href="#ref-31" title=""NFS Version 3 Protocol Specification"">31</a>]), there exists an ancillary protocol to obtain this first |
| 5439 |
filehandle. The MOUNT protocol, RPC program number 100005, provides |
| 5440 |
the mechanism of translating a string-based file system pathname to a |
| 5441 |
filehandle, which can then be used by the NFS protocols. |
| 5442 |
|
| 5443 |
The MOUNT protocol has deficiencies in the area of security and use |
| 5444 |
via firewalls. This is one reason that the use of the public |
| 5445 |
filehandle was introduced in <a href="./rfc2054">RFC 2054</a> [<a href="#ref-42" title=""WebNFS Client Specification"">42</a>] and <a href="./rfc2055">RFC 2055</a> [<a href="#ref-43" title=""WebNFS Server Specification"">43</a>]. With |
| 5446 |
the use of the public filehandle in combination with the LOOKUP |
| 5447 |
operation in the NFSv3 protocol, it has been demonstrated that the |
| 5448 |
MOUNT protocol is unnecessary for viable interaction between NFS |
| 5449 |
client and server. |
| 5450 |
|
| 5451 |
Therefore, the NFSv4.1 protocol will not use an ancillary protocol |
| 5452 |
for translation from string-based pathnames to a filehandle. Two |
| 5453 |
special filehandles will be used as starting points for the NFS |
| 5454 |
client. |
| 5455 |
|
| 5456 |
<span class="h4"><a class="selflink" id="section-4.1.1" href="#section-4.1.1">4.1.1</a>. Root Filehandle</span> |
| 5457 |
|
| 5458 |
The first of the special filehandles is the ROOT filehandle. The |
| 5459 |
ROOT filehandle is the "conceptual" root of the file system namespace |
| 5460 |
at the NFS server. The client uses or starts with the ROOT |
| 5461 |
filehandle by employing the PUTROOTFH operation. The PUTROOTFH |
| 5462 |
operation instructs the server to set the "current" filehandle to the |
| 5463 |
ROOT of the server's file tree. Once this PUTROOTFH operation is |
| 5464 |
used, the client can then traverse the entirety of the server's file |
| 5465 |
tree with the LOOKUP operation. A complete discussion of the server |
| 5466 |
namespace is in <a href="#section-7">Section 7</a>. |
| 5467 |
|
| 5468 |
<span class="h4"><a class="selflink" id="section-4.1.2" href="#section-4.1.2">4.1.2</a>. Public Filehandle</span> |
| 5469 |
|
| 5470 |
The second special filehandle is the PUBLIC filehandle. Unlike the |
| 5471 |
ROOT filehandle, the PUBLIC filehandle may be bound or represent an |
| 5472 |
arbitrary file system object at the server. The server is |
| 5473 |
responsible for this binding. It may be that the PUBLIC filehandle |
| 5474 |
and the ROOT filehandle refer to the same file system object. |
| 5475 |
However, it is up to the administrative software at the server and |
| 5476 |
the policies of the server administrator to define the binding of the |
| 5477 |
PUBLIC filehandle and server file system object. The client may not |
| 5478 |
make any assumptions about this binding. The client uses the PUBLIC |
| 5479 |
filehandle via the PUTPUBFH operation. |
| 5480 |
|
| 5481 |
|
| 5482 |
|
| 5483 |
|
| 5484 |
<span class="grey">Shepler, et al. Standards Track [Page 98]</span></pre> |
| 5485 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-99" ></span> |
| 5486 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5487 |
|
| 5488 |
|
| 5489 |
<span class="h3"><a class="selflink" id="section-4.2" href="#section-4.2">4.2</a>. Filehandle Types</span> |
| 5490 |
|
| 5491 |
In the NFSv3 protocol, there was one type of filehandle with a single |
| 5492 |
set of semantics. This type of filehandle is termed "persistent" in |
| 5493 |
NFSv4.1. The semantics of a persistent filehandle remain the same as |
| 5494 |
before. A new type of filehandle introduced in NFSv4.1 is the |
| 5495 |
"volatile" filehandle, which attempts to accommodate certain server |
| 5496 |
environments. |
| 5497 |
|
| 5498 |
The volatile filehandle type was introduced to address server |
| 5499 |
functionality or implementation issues that make correct |
| 5500 |
implementation of a persistent filehandle infeasible. Some server |
| 5501 |
environments do not provide a file-system-level invariant that can be |
| 5502 |
used to construct a persistent filehandle. The underlying server |
| 5503 |
file system may not provide the invariant or the server's file system |
| 5504 |
programming interfaces may not provide access to the needed |
| 5505 |
invariant. Volatile filehandles may ease the implementation of |
| 5506 |
server functionality such as hierarchical storage management or file |
| 5507 |
system reorganization or migration. However, the volatile filehandle |
| 5508 |
increases the implementation burden for the client. |
| 5509 |
|
| 5510 |
Since the client will need to handle persistent and volatile |
| 5511 |
filehandles differently, a file attribute is defined that may be used |
| 5512 |
by the client to determine the filehandle types being returned by the |
| 5513 |
server. |
| 5514 |
|
| 5515 |
<span class="h4"><a class="selflink" id="section-4.2.1" href="#section-4.2.1">4.2.1</a>. General Properties of a Filehandle</span> |
| 5516 |
|
| 5517 |
The filehandle contains all the information the server needs to |
| 5518 |
distinguish an individual file. To the client, the filehandle is |
| 5519 |
opaque. The client stores filehandles for use in a later request and |
| 5520 |
can compare two filehandles from the same server for equality by |
| 5521 |
doing a byte-by-byte comparison. However, the client MUST NOT |
| 5522 |
otherwise interpret the contents of filehandles. If two filehandles |
| 5523 |
from the same server are equal, they MUST refer to the same file. |
| 5524 |
Servers SHOULD try to maintain a one-to-one correspondence between |
| 5525 |
filehandles and files, but this is not required. Clients MUST use |
| 5526 |
filehandle comparisons only to improve performance, not for correct |
| 5527 |
behavior. All clients need to be prepared for situations in which it |
| 5528 |
cannot be determined whether two filehandles denote the same object |
| 5529 |
and in such cases, avoid making invalid assumptions that might cause |
| 5530 |
incorrect behavior. Further discussion of filehandle and attribute |
| 5531 |
comparison in the context of data caching is presented in |
| 5532 |
<a href="#section-10.3.4">Section 10.3.4</a>. |
| 5533 |
|
| 5534 |
As an example, in the case that two different pathnames when |
| 5535 |
traversed at the server terminate at the same file system object, the |
| 5536 |
server SHOULD return the same filehandle for each path. This can |
| 5537 |
|
| 5538 |
|
| 5539 |
|
| 5540 |
<span class="grey">Shepler, et al. Standards Track [Page 99]</span></pre> |
| 5541 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-100" ></span> |
| 5542 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5543 |
|
| 5544 |
|
| 5545 |
occur if a hard link (see [<a href="#ref-6" title="">6</a>]) is used to create two file names that |
| 5546 |
refer to the same underlying file object and associated data. For |
| 5547 |
example, if paths /a/b/c and /a/d/c refer to the same file, the |
| 5548 |
server SHOULD return the same filehandle for both pathnames' |
| 5549 |
traversals. |
| 5550 |
|
| 5551 |
<span class="h4"><a class="selflink" id="section-4.2.2" href="#section-4.2.2">4.2.2</a>. Persistent Filehandle</span> |
| 5552 |
|
| 5553 |
A persistent filehandle is defined as having a fixed value for the |
| 5554 |
lifetime of the file system object to which it refers. Once the |
| 5555 |
server creates the filehandle for a file system object, the server |
| 5556 |
MUST accept the same filehandle for the object for the lifetime of |
| 5557 |
the object. If the server restarts, the NFS server MUST honor the |
| 5558 |
same filehandle value as it did in the server's previous |
| 5559 |
instantiation. Similarly, if the file system is migrated, the new |
| 5560 |
NFS server MUST honor the same filehandle as the old NFS server. |
| 5561 |
|
| 5562 |
The persistent filehandle will be become stale or invalid when the |
| 5563 |
file system object is removed. When the server is presented with a |
| 5564 |
persistent filehandle that refers to a deleted object, it MUST return |
| 5565 |
an error of NFS4ERR_STALE. A filehandle may become stale when the |
| 5566 |
file system containing the object is no longer available. The file |
| 5567 |
system may become unavailable if it exists on removable media and the |
| 5568 |
media is no longer available at the server or the file system in |
| 5569 |
whole has been destroyed or the file system has simply been removed |
| 5570 |
from the server's namespace (i.e., unmounted in a UNIX environment). |
| 5571 |
|
| 5572 |
<span class="h4"><a class="selflink" id="section-4.2.3" href="#section-4.2.3">4.2.3</a>. Volatile Filehandle</span> |
| 5573 |
|
| 5574 |
A volatile filehandle does not share the same longevity |
| 5575 |
characteristics of a persistent filehandle. The server may determine |
| 5576 |
that a volatile filehandle is no longer valid at many different |
| 5577 |
points in time. If the server can definitively determine that a |
| 5578 |
volatile filehandle refers to an object that has been removed, the |
| 5579 |
server should return NFS4ERR_STALE to the client (as is the case for |
| 5580 |
persistent filehandles). In all other cases where the server |
| 5581 |
determines that a volatile filehandle can no longer be used, it |
| 5582 |
should return an error of NFS4ERR_FHEXPIRED. |
| 5583 |
|
| 5584 |
The REQUIRED attribute "fh_expire_type" is used by the client to |
| 5585 |
determine what type of filehandle the server is providing for a |
| 5586 |
particular file system. This attribute is a bitmask with the |
| 5587 |
following values: |
| 5588 |
|
| 5589 |
|
| 5590 |
|
| 5591 |
|
| 5592 |
|
| 5593 |
|
| 5594 |
|
| 5595 |
|
| 5596 |
<span class="grey">Shepler, et al. Standards Track [Page 100]</span></pre> |
| 5597 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-101" ></span> |
| 5598 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5599 |
|
| 5600 |
|
| 5601 |
FH4_PERSISTENT The value of FH4_PERSISTENT is used to indicate a |
| 5602 |
persistent filehandle, which is valid until the object is removed |
| 5603 |
from the file system. The server will not return |
| 5604 |
NFS4ERR_FHEXPIRED for this filehandle. FH4_PERSISTENT is defined |
| 5605 |
as a value in which none of the bits specified below are set. |
| 5606 |
|
| 5607 |
FH4_VOLATILE_ANY The filehandle may expire at any time, except as |
| 5608 |
specifically excluded (i.e., FH4_NO_EXPIRE_WITH_OPEN). |
| 5609 |
|
| 5610 |
FH4_NOEXPIRE_WITH_OPEN May only be set when FH4_VOLATILE_ANY is set. |
| 5611 |
If this bit is set, then the meaning of FH4_VOLATILE_ANY is |
| 5612 |
qualified to exclude any expiration of the filehandle when it is |
| 5613 |
open. |
| 5614 |
|
| 5615 |
FH4_VOL_MIGRATION The filehandle will expire as a result of a file |
| 5616 |
system transition (migration or replication), in those cases in |
| 5617 |
which the continuity of filehandle use is not specified by handle |
| 5618 |
class information within the fs_locations_info attribute. When |
| 5619 |
this bit is set, clients without access to fs_locations_info |
| 5620 |
information should assume that filehandles will expire on file |
| 5621 |
system transitions. |
| 5622 |
|
| 5623 |
FH4_VOL_RENAME The filehandle will expire during rename. This |
| 5624 |
includes a rename by the requesting client or a rename by any |
| 5625 |
other client. If FH4_VOL_ANY is set, FH4_VOL_RENAME is redundant. |
| 5626 |
|
| 5627 |
Servers that provide volatile filehandles that can expire while open |
| 5628 |
require special care as regards handling of RENAMEs and REMOVEs. |
| 5629 |
This situation can arise if FH4_VOL_MIGRATION or FH4_VOL_RENAME is |
| 5630 |
set, if FH4_VOLATILE_ANY is set and FH4_NOEXPIRE_WITH_OPEN is not |
| 5631 |
set, or if a non-read-only file system has a transition target in a |
| 5632 |
different handle class. In these cases, the server should deny a |
| 5633 |
RENAME or REMOVE that would affect an OPEN file of any of the |
| 5634 |
components leading to the OPEN file. In addition, the server should |
| 5635 |
deny all RENAME or REMOVE requests during the grace period, in order |
| 5636 |
to make sure that reclaims of files where filehandles may have |
| 5637 |
expired do not do a reclaim for the wrong file. |
| 5638 |
|
| 5639 |
Volatile filehandles are especially suitable for implementation of |
| 5640 |
the pseudo file systems used to bridge exports. See <a href="#section-7.5">Section 7.5</a> for |
| 5641 |
a discussion of this. |
| 5642 |
|
| 5643 |
<span class="h3"><a class="selflink" id="section-4.3" href="#section-4.3">4.3</a>. One Method of Constructing a Volatile Filehandle</span> |
| 5644 |
|
| 5645 |
A volatile filehandle, while opaque to the client, could contain: |
| 5646 |
|
| 5647 |
[volatile bit = 1 | server boot time | slot | generation number] |
| 5648 |
|
| 5649 |
|
| 5650 |
|
| 5651 |
|
| 5652 |
<span class="grey">Shepler, et al. Standards Track [Page 101]</span></pre> |
| 5653 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-102" ></span> |
| 5654 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5655 |
|
| 5656 |
|
| 5657 |
o slot is an index in the server volatile filehandle table |
| 5658 |
|
| 5659 |
o generation number is the generation number for the table entry/ |
| 5660 |
slot |
| 5661 |
|
| 5662 |
When the client presents a volatile filehandle, the server makes the |
| 5663 |
following checks, which assume that the check for the volatile bit |
| 5664 |
has passed. If the server boot time is less than the current server |
| 5665 |
boot time, return NFS4ERR_FHEXPIRED. If slot is out of range, return |
| 5666 |
NFS4ERR_BADHANDLE. If the generation number does not match, return |
| 5667 |
NFS4ERR_FHEXPIRED. |
| 5668 |
|
| 5669 |
When the server restarts, the table is gone (it is volatile). |
| 5670 |
|
| 5671 |
If the volatile bit is 0, then it is a persistent filehandle with a |
| 5672 |
different structure following it. |
| 5673 |
|
| 5674 |
<span class="h3"><a class="selflink" id="section-4.4" href="#section-4.4">4.4</a>. Client Recovery from Filehandle Expiration</span> |
| 5675 |
|
| 5676 |
If possible, the client SHOULD recover from the receipt of an |
| 5677 |
NFS4ERR_FHEXPIRED error. The client must take on additional |
| 5678 |
responsibility so that it may prepare itself to recover from the |
| 5679 |
expiration of a volatile filehandle. If the server returns |
| 5680 |
persistent filehandles, the client does not need these additional |
| 5681 |
steps. |
| 5682 |
|
| 5683 |
For volatile filehandles, most commonly the client will need to store |
| 5684 |
the component names leading up to and including the file system |
| 5685 |
object in question. With these names, the client should be able to |
| 5686 |
recover by finding a filehandle in the namespace that is still |
| 5687 |
available or by starting at the root of the server's file system |
| 5688 |
namespace. |
| 5689 |
|
| 5690 |
If the expired filehandle refers to an object that has been removed |
| 5691 |
from the file system, obviously the client will not be able to |
| 5692 |
recover from the expired filehandle. |
| 5693 |
|
| 5694 |
It is also possible that the expired filehandle refers to a file that |
| 5695 |
has been renamed. If the file was renamed by another client, again |
| 5696 |
it is possible that the original client will not be able to recover. |
| 5697 |
However, in the case that the client itself is renaming the file and |
| 5698 |
the file is open, it is possible that the client may be able to |
| 5699 |
recover. The client can determine the new pathname based on the |
| 5700 |
processing of the rename request. The client can then regenerate the |
| 5701 |
new filehandle based on the new pathname. The client could also use |
| 5702 |
the COMPOUND procedure to construct a series of operations like: |
| 5703 |
|
| 5704 |
|
| 5705 |
|
| 5706 |
|
| 5707 |
|
| 5708 |
<span class="grey">Shepler, et al. Standards Track [Page 102]</span></pre> |
| 5709 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-103" ></span> |
| 5710 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5711 |
|
| 5712 |
|
| 5713 |
RENAME A B |
| 5714 |
LOOKUP B |
| 5715 |
GETFH |
| 5716 |
|
| 5717 |
Note that the COMPOUND procedure does not provide atomicity. This |
| 5718 |
example only reduces the overhead of recovering from an expired |
| 5719 |
filehandle. |
| 5720 |
|
| 5721 |
<span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. File Attributes</span> |
| 5722 |
|
| 5723 |
To meet the requirements of extensibility and increased |
| 5724 |
interoperability with non-UNIX platforms, attributes need to be |
| 5725 |
handled in a flexible manner. The NFSv3 fattr3 structure contains a |
| 5726 |
fixed list of attributes that not all clients and servers are able to |
| 5727 |
support or care about. The fattr3 structure cannot be extended as |
| 5728 |
new needs arise and it provides no way to indicate non-support. With |
| 5729 |
the NFSv4.1 protocol, the client is able to query what attributes the |
| 5730 |
server supports and construct requests with only those supported |
| 5731 |
attributes (or a subset thereof). |
| 5732 |
|
| 5733 |
To this end, attributes are divided into three groups: REQUIRED, |
| 5734 |
RECOMMENDED, and named. Both REQUIRED and RECOMMENDED attributes are |
| 5735 |
supported in the NFSv4.1 protocol by a specific and well-defined |
| 5736 |
encoding and are identified by number. They are requested by setting |
| 5737 |
a bit in the bit vector sent in the GETATTR request; the server |
| 5738 |
response includes a bit vector to list what attributes were returned |
| 5739 |
in the response. New REQUIRED or RECOMMENDED attributes may be added |
| 5740 |
to the NFSv4 protocol as part of a new minor version by publishing a |
| 5741 |
Standards Track RFC that allocates a new attribute number value and |
| 5742 |
defines the encoding for the attribute. See <a href="#section-2.7">Section 2.7</a> for further |
| 5743 |
discussion. |
| 5744 |
|
| 5745 |
Named attributes are accessed by the new OPENATTR operation, which |
| 5746 |
accesses a hidden directory of attributes associated with a file |
| 5747 |
system object. OPENATTR takes a filehandle for the object and |
| 5748 |
returns the filehandle for the attribute hierarchy. The filehandle |
| 5749 |
for the named attributes is a directory object accessible by LOOKUP |
| 5750 |
or READDIR and contains files whose names represent the named |
| 5751 |
attributes and whose data bytes are the value of the attribute. For |
| 5752 |
example: |
| 5753 |
|
| 5754 |
+----------+-----------+---------------------------------+ |
| 5755 |
| LOOKUP | "foo" | ; look up file | |
| 5756 |
| GETATTR | attrbits | | |
| 5757 |
| OPENATTR | | ; access foo's named attributes | |
| 5758 |
| LOOKUP | "x11icon" | ; look up specific attribute | |
| 5759 |
| READ | 0,4096 | ; read stream of bytes | |
| 5760 |
+----------+-----------+---------------------------------+ |
| 5761 |
|
| 5762 |
|
| 5763 |
|
| 5764 |
<span class="grey">Shepler, et al. Standards Track [Page 103]</span></pre> |
| 5765 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-104" ></span> |
| 5766 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5767 |
|
| 5768 |
|
| 5769 |
Named attributes are intended for data needed by applications rather |
| 5770 |
than by an NFS client implementation. NFS implementors are strongly |
| 5771 |
encouraged to define their new attributes as RECOMMENDED attributes |
| 5772 |
by bringing them to the IETF Standards Track process. |
| 5773 |
|
| 5774 |
The set of attributes that are classified as REQUIRED is deliberately |
| 5775 |
small since servers need to do whatever it takes to support them. A |
| 5776 |
server should support as many of the RECOMMENDED attributes as |
| 5777 |
possible but, by their definition, the server is not required to |
| 5778 |
support all of them. Attributes are deemed REQUIRED if the data is |
| 5779 |
both needed by a large number of clients and is not otherwise |
| 5780 |
reasonably computable by the client when support is not provided on |
| 5781 |
the server. |
| 5782 |
|
| 5783 |
Note that the hidden directory returned by OPENATTR is a convenience |
| 5784 |
for protocol processing. The client should not make any assumptions |
| 5785 |
about the server's implementation of named attributes and whether or |
| 5786 |
not the underlying file system at the server has a named attribute |
| 5787 |
directory. Therefore, operations such as SETATTR and GETATTR on the |
| 5788 |
named attribute directory are undefined. |
| 5789 |
|
| 5790 |
<span class="h3"><a class="selflink" id="section-5.1" href="#section-5.1">5.1</a>. REQUIRED Attributes</span> |
| 5791 |
|
| 5792 |
These MUST be supported by every NFSv4.1 client and server in order |
| 5793 |
to ensure a minimum level of interoperability. The server MUST store |
| 5794 |
and return these attributes, and the client MUST be able to function |
| 5795 |
with an attribute set limited to these attributes. With just the |
| 5796 |
REQUIRED attributes some client functionality may be impaired or |
| 5797 |
limited in some ways. A client may ask for any of these attributes |
| 5798 |
to be returned by setting a bit in the GETATTR request, and the |
| 5799 |
server MUST return their value. |
| 5800 |
|
| 5801 |
<span class="h3"><a class="selflink" id="section-5.2" href="#section-5.2">5.2</a>. RECOMMENDED Attributes</span> |
| 5802 |
|
| 5803 |
These attributes are understood well enough to warrant support in the |
| 5804 |
NFSv4.1 protocol. However, they may not be supported on all clients |
| 5805 |
and servers. A client may ask for any of these attributes to be |
| 5806 |
returned by setting a bit in the GETATTR request but must handle the |
| 5807 |
case where the server does not return them. A client MAY ask for the |
| 5808 |
set of attributes the server supports and SHOULD NOT request |
| 5809 |
attributes the server does not support. A server should be tolerant |
| 5810 |
of requests for unsupported attributes and simply not return them |
| 5811 |
rather than considering the request an error. It is expected that |
| 5812 |
servers will support all attributes they comfortably can and only |
| 5813 |
fail to support attributes that are difficult to support in their |
| 5814 |
operating environments. A server should provide attributes whenever |
| 5815 |
they don't have to "tell lies" to the client. For example, a file |
| 5816 |
modification time should be either an accurate time or should not be |
| 5817 |
|
| 5818 |
|
| 5819 |
|
| 5820 |
<span class="grey">Shepler, et al. Standards Track [Page 104]</span></pre> |
| 5821 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-105" ></span> |
| 5822 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5823 |
|
| 5824 |
|
| 5825 |
supported by the server. At times this will be difficult for |
| 5826 |
clients, but a client is better positioned to decide whether and how |
| 5827 |
to fabricate or construct an attribute or whether to do without the |
| 5828 |
attribute. |
| 5829 |
|
| 5830 |
<span class="h3"><a class="selflink" id="section-5.3" href="#section-5.3">5.3</a>. Named Attributes</span> |
| 5831 |
|
| 5832 |
These attributes are not supported by direct encoding in the NFSv4 |
| 5833 |
protocol but are accessed by string names rather than numbers and |
| 5834 |
correspond to an uninterpreted stream of bytes that are stored with |
| 5835 |
the file system object. The namespace for these attributes may be |
| 5836 |
accessed by using the OPENATTR operation. The OPENATTR operation |
| 5837 |
returns a filehandle for a virtual "named attribute directory", and |
| 5838 |
further perusal and modification of the namespace may be done using |
| 5839 |
operations that work on more typical directories. In particular, |
| 5840 |
READDIR may be used to get a list of such named attributes, and |
| 5841 |
LOOKUP and OPEN may select a particular attribute. Creation of a new |
| 5842 |
named attribute may be the result of an OPEN specifying file |
| 5843 |
creation. |
| 5844 |
|
| 5845 |
Once an OPEN is done, named attributes may be examined and changed by |
| 5846 |
normal READ and WRITE operations using the filehandles and stateids |
| 5847 |
returned by OPEN. |
| 5848 |
|
| 5849 |
Named attributes and the named attribute directory may have their own |
| 5850 |
(non-named) attributes. Each of these objects MUST have all of the |
| 5851 |
REQUIRED attributes and may have additional RECOMMENDED attributes. |
| 5852 |
However, the set of attributes for named attributes and the named |
| 5853 |
attribute directory need not be, and typically will not be, as large |
| 5854 |
as that for other objects in that file system. |
| 5855 |
|
| 5856 |
Named attributes and the named attribute directory might be the |
| 5857 |
target of delegations (in the case of the named attribute directory, |
| 5858 |
these will be directory delegations). However, since granting |
| 5859 |
delegations is at the server's discretion, a server need not support |
| 5860 |
delegations on named attributes or the named attribute directory. |
| 5861 |
|
| 5862 |
It is RECOMMENDED that servers support arbitrary named attributes. A |
| 5863 |
client should not depend on the ability to store any named attributes |
| 5864 |
in the server's file system. If a server does support named |
| 5865 |
attributes, a client that is also able to handle them should be able |
| 5866 |
to copy a file's data and metadata with complete transparency from |
| 5867 |
one location to another; this would imply that names allowed for |
| 5868 |
regular directory entries are valid for named attribute names as |
| 5869 |
well. |
| 5870 |
|
| 5871 |
|
| 5872 |
|
| 5873 |
|
| 5874 |
|
| 5875 |
|
| 5876 |
<span class="grey">Shepler, et al. Standards Track [Page 105]</span></pre> |
| 5877 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-106" ></span> |
| 5878 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5879 |
|
| 5880 |
|
| 5881 |
In NFSv4.1, the structure of named attribute directories is |
| 5882 |
restricted in a number of ways, in order to prevent the development |
| 5883 |
of non-interoperable implementations in which some servers support a |
| 5884 |
fully general hierarchical directory structure for named attributes |
| 5885 |
while others support a limited but adequate structure for named |
| 5886 |
attributes. In such an environment, clients or applications might |
| 5887 |
come to depend on non-portable extensions. The restrictions are: |
| 5888 |
|
| 5889 |
o CREATE is not allowed in a named attribute directory. Thus, such |
| 5890 |
objects as symbolic links and special files are not allowed to be |
| 5891 |
named attributes. Further, directories may not be created in a |
| 5892 |
named attribute directory, so no hierarchical structure of named |
| 5893 |
attributes for a single object is allowed. |
| 5894 |
|
| 5895 |
o If OPENATTR is done on a named attribute directory or on a named |
| 5896 |
attribute, the server MUST return NFS4ERR_WRONG_TYPE. |
| 5897 |
|
| 5898 |
o Doing a RENAME of a named attribute to a different named attribute |
| 5899 |
directory or to an ordinary (i.e., non-named-attribute) directory |
| 5900 |
is not allowed. |
| 5901 |
|
| 5902 |
o Creating hard links between named attribute directories or between |
| 5903 |
named attribute directories and ordinary directories is not |
| 5904 |
allowed. |
| 5905 |
|
| 5906 |
Names of attributes will not be controlled by this document or other |
| 5907 |
IETF Standards Track documents. See <a href="#section-22.1">Section 22.1</a> for further |
| 5908 |
discussion. |
| 5909 |
|
| 5910 |
<span class="h3"><a class="selflink" id="section-5.4" href="#section-5.4">5.4</a>. Classification of Attributes</span> |
| 5911 |
|
| 5912 |
Each of the REQUIRED and RECOMMENDED attributes can be classified in |
| 5913 |
one of three categories: per server (i.e., the value of the attribute |
| 5914 |
will be the same for all file objects that share the same server |
| 5915 |
owner; see <a href="#section-2.5">Section 2.5</a> for a definition of server owner), per file |
| 5916 |
system (i.e., the value of the attribute will be the same for some or |
| 5917 |
all file objects that share the same fsid attribute (<a href="#section-5.8.1.9">Section 5.8.1.9</a>) |
| 5918 |
and server owner), or per file system object. Note that it is |
| 5919 |
possible that some per file system attributes may vary within the |
| 5920 |
file system, depending on the value of the "homogeneous" |
| 5921 |
(<a href="#section-5.8.2.16">Section 5.8.2.16</a>) attribute. Note that the attributes |
| 5922 |
time_access_set and time_modify_set are not listed in this section |
| 5923 |
because they are write-only attributes corresponding to time_access |
| 5924 |
and time_modify, and are used in a special instance of SETATTR. |
| 5925 |
|
| 5926 |
o The per-server attribute is: |
| 5927 |
|
| 5928 |
lease_time |
| 5929 |
|
| 5930 |
|
| 5931 |
|
| 5932 |
<span class="grey">Shepler, et al. Standards Track [Page 106]</span></pre> |
| 5933 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-107" ></span> |
| 5934 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5935 |
|
| 5936 |
|
| 5937 |
o The per-file system attributes are: |
| 5938 |
|
| 5939 |
supported_attrs, suppattr_exclcreat, fh_expire_type, |
| 5940 |
link_support, symlink_support, unique_handles, aclsupport, |
| 5941 |
cansettime, case_insensitive, case_preserving, |
| 5942 |
chown_restricted, files_avail, files_free, files_total, |
| 5943 |
fs_locations, homogeneous, maxfilesize, maxname, maxread, |
| 5944 |
maxwrite, no_trunc, space_avail, space_free, space_total, |
| 5945 |
time_delta, change_policy, fs_status, fs_layout_type, |
| 5946 |
fs_locations_info, fs_charset_cap |
| 5947 |
|
| 5948 |
o The per-file system object attributes are: |
| 5949 |
|
| 5950 |
type, change, size, named_attr, fsid, rdattr_error, filehandle, |
| 5951 |
acl, archive, fileid, hidden, maxlink, mimetype, mode, |
| 5952 |
numlinks, owner, owner_group, rawdev, space_used, system, |
| 5953 |
time_access, time_backup, time_create, time_metadata, |
| 5954 |
time_modify, mounted_on_fileid, dir_notif_delay, |
| 5955 |
dirent_notif_delay, dacl, sacl, layout_type, layout_hint, |
| 5956 |
layout_blksize, layout_alignment, mdsthreshold, retention_get, |
| 5957 |
retention_set, retentevt_get, retentevt_set, retention_hold, |
| 5958 |
mode_set_masked |
| 5959 |
|
| 5960 |
For quota_avail_hard, quota_avail_soft, and quota_used, see their |
| 5961 |
definitions below for the appropriate classification. |
| 5962 |
|
| 5963 |
<span class="h3"><a class="selflink" id="section-5.5" href="#section-5.5">5.5</a>. Set-Only and Get-Only Attributes</span> |
| 5964 |
|
| 5965 |
Some REQUIRED and RECOMMENDED attributes are set-only; i.e., they can |
| 5966 |
be set via SETATTR but not retrieved via GETATTR. Similarly, some |
| 5967 |
REQUIRED and RECOMMENDED attributes are get-only; i.e., they can be |
| 5968 |
retrieved via GETATTR but not set via SETATTR. If a client attempts |
| 5969 |
to set a get-only attribute or get a set-only attributes, the server |
| 5970 |
MUST return NFS4ERR_INVAL. |
| 5971 |
|
| 5972 |
<span class="h3"><a class="selflink" id="section-5.6" href="#section-5.6">5.6</a>. REQUIRED Attributes - List and Definition References</span> |
| 5973 |
|
| 5974 |
The list of REQUIRED attributes appears in Table 2. The meaning of |
| 5975 |
the columns of the table are: |
| 5976 |
|
| 5977 |
o Name: The name of the attribute. |
| 5978 |
|
| 5979 |
o Id: The number assigned to the attribute. In the event of |
| 5980 |
conflicts between the assigned number and [<a href="#ref-13" title=""Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description"">13</a>], the latter is |
| 5981 |
likely authoritative, but should be resolved with Errata to this |
| 5982 |
document and/or [<a href="#ref-13" title=""Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description"">13</a>]. See [<a href="#ref-44" title=""IESG Processing of RFC Errata for the IETF Stream"">44</a>] for the Errata process. |
| 5983 |
|
| 5984 |
o Data Type: The XDR data type of the attribute. |
| 5985 |
|
| 5986 |
|
| 5987 |
|
| 5988 |
<span class="grey">Shepler, et al. Standards Track [Page 107]</span></pre> |
| 5989 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-108" ></span> |
| 5990 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 5991 |
|
| 5992 |
|
| 5993 |
o Acc: Access allowed to the attribute. R means read-only (GETATTR |
| 5994 |
may retrieve, SETATTR may not set). W means write-only (SETATTR |
| 5995 |
may set, GETATTR may not retrieve). R W means read/write (GETATTR |
| 5996 |
may retrieve, SETATTR may set). |
| 5997 |
|
| 5998 |
o Defined in: The section of this specification that describes the |
| 5999 |
attribute. |
| 6000 |
|
| 6001 |
+--------------------+----+------------+-----+------------------+ |
| 6002 |
| Name | Id | Data Type | Acc | Defined in: | |
| 6003 |
+--------------------+----+------------+-----+------------------+ |
| 6004 |
| supported_attrs | 0 | bitmap4 | R | <a href="#section-5.8.1.1">Section 5.8.1.1</a> | |
| 6005 |
| type | 1 | nfs_ftype4 | R | <a href="#section-5.8.1.2">Section 5.8.1.2</a> | |
| 6006 |
| fh_expire_type | 2 | uint32_t | R | <a href="#section-5.8.1.3">Section 5.8.1.3</a> | |
| 6007 |
| change | 3 | uint64_t | R | <a href="#section-5.8.1.4">Section 5.8.1.4</a> | |
| 6008 |
| size | 4 | uint64_t | R W | <a href="#section-5.8.1.5">Section 5.8.1.5</a> | |
| 6009 |
| link_support | 5 | bool | R | <a href="#section-5.8.1.6">Section 5.8.1.6</a> | |
| 6010 |
| symlink_support | 6 | bool | R | <a href="#section-5.8.1.7">Section 5.8.1.7</a> | |
| 6011 |
| named_attr | 7 | bool | R | <a href="#section-5.8.1.8">Section 5.8.1.8</a> | |
| 6012 |
| fsid | 8 | fsid4 | R | <a href="#section-5.8.1.9">Section 5.8.1.9</a> | |
| 6013 |
| unique_handles | 9 | bool | R | <a href="#section-5.8.1.10">Section 5.8.1.10</a> | |
| 6014 |
| lease_time | 10 | nfs_lease4 | R | <a href="#section-5.8.1.11">Section 5.8.1.11</a> | |
| 6015 |
| rdattr_error | 11 | enum | R | <a href="#section-5.8.1.12">Section 5.8.1.12</a> | |
| 6016 |
| filehandle | 19 | nfs_fh4 | R | <a href="#section-5.8.1.13">Section 5.8.1.13</a> | |
| 6017 |
| suppattr_exclcreat | 75 | bitmap4 | R | <a href="#section-5.8.1.14">Section 5.8.1.14</a> | |
| 6018 |
+--------------------+----+------------+-----+------------------+ |
| 6019 |
|
| 6020 |
Table 2 |
| 6021 |
|
| 6022 |
<span class="h3"><a class="selflink" id="section-5.7" href="#section-5.7">5.7</a>. RECOMMENDED Attributes - List and Definition References</span> |
| 6023 |
|
| 6024 |
The RECOMMENDED attributes are defined in Table 3. The meanings of |
| 6025 |
the column headers are the same as Table 2; see <a href="#section-5.6">Section 5.6</a> for the |
| 6026 |
meanings. |
| 6027 |
|
| 6028 |
|
| 6029 |
|
| 6030 |
|
| 6031 |
|
| 6032 |
|
| 6033 |
|
| 6034 |
|
| 6035 |
|
| 6036 |
|
| 6037 |
|
| 6038 |
|
| 6039 |
|
| 6040 |
|
| 6041 |
|
| 6042 |
|
| 6043 |
|
| 6044 |
<span class="grey">Shepler, et al. Standards Track [Page 108]</span></pre> |
| 6045 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-109" ></span> |
| 6046 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6047 |
|
| 6048 |
|
| 6049 |
+--------------------+----+----------------+-----+------------------+ |
| 6050 |
| Name | Id | Data Type | Acc | Defined in: | |
| 6051 |
+--------------------+----+----------------+-----+------------------+ |
| 6052 |
| acl | 12 | nfsace4<> | R W | <a href="#section-6.2.1">Section 6.2.1</a> | |
| 6053 |
| aclsupport | 13 | uint32_t | R | <a href="#section-6.2.1.2">Section 6.2.1.2</a> | |
| 6054 |
| archive | 14 | bool | R W | <a href="#section-5.8.2.1">Section 5.8.2.1</a> | |
| 6055 |
| cansettime | 15 | bool | R | <a href="#section-5.8.2.2">Section 5.8.2.2</a> | |
| 6056 |
| case_insensitive | 16 | bool | R | <a href="#section-5.8.2.3">Section 5.8.2.3</a> | |
| 6057 |
| case_preserving | 17 | bool | R | <a href="#section-5.8.2.4">Section 5.8.2.4</a> | |
| 6058 |
| change_policy | 60 | chg_policy4 | R | <a href="#section-5.8.2.5">Section 5.8.2.5</a> | |
| 6059 |
| chown_restricted | 18 | bool | R | <a href="#section-5.8.2.6">Section 5.8.2.6</a> | |
| 6060 |
| dacl | 58 | nfsacl41 | R W | <a href="#section-6.2.2">Section 6.2.2</a> | |
| 6061 |
| dir_notif_delay | 56 | nfstime4 | R | <a href="#section-5.11.1">Section 5.11.1</a> | |
| 6062 |
| dirent_notif_delay | 57 | nfstime4 | R | <a href="#section-5.11.2">Section 5.11.2</a> | |
| 6063 |
| fileid | 20 | uint64_t | R | <a href="#section-5.8.2.7">Section 5.8.2.7</a> | |
| 6064 |
| files_avail | 21 | uint64_t | R | <a href="#section-5.8.2.8">Section 5.8.2.8</a> | |
| 6065 |
| files_free | 22 | uint64_t | R | <a href="#section-5.8.2.9">Section 5.8.2.9</a> | |
| 6066 |
| files_total | 23 | uint64_t | R | <a href="#section-5.8.2.10">Section 5.8.2.10</a> | |
| 6067 |
| fs_charset_cap | 76 | uint32_t | R | <a href="#section-5.8.2.11">Section 5.8.2.11</a> | |
| 6068 |
| fs_layout_type | 62 | layouttype4<> | R | <a href="#section-5.12.1">Section 5.12.1</a> | |
| 6069 |
| fs_locations | 24 | fs_locations | R | <a href="#section-5.8.2.12">Section 5.8.2.12</a> | |
| 6070 |
| fs_locations_info | 67 | * | R | <a href="#section-5.8.2.13">Section 5.8.2.13</a> | |
| 6071 |
| fs_status | 61 | fs4_status | R | <a href="#section-5.8.2.14">Section 5.8.2.14</a> | |
| 6072 |
| hidden | 25 | bool | R W | <a href="#section-5.8.2.15">Section 5.8.2.15</a> | |
| 6073 |
| homogeneous | 26 | bool | R | <a href="#section-5.8.2.16">Section 5.8.2.16</a> | |
| 6074 |
| layout_alignment | 66 | uint32_t | R | <a href="#section-5.12.2">Section 5.12.2</a> | |
| 6075 |
| layout_blksize | 65 | uint32_t | R | <a href="#section-5.12.3">Section 5.12.3</a> | |
| 6076 |
| layout_hint | 63 | layouthint4 | W | <a href="#section-5.12.4">Section 5.12.4</a> | |
| 6077 |
| layout_type | 64 | layouttype4<> | R | <a href="#section-5.12.5">Section 5.12.5</a> | |
| 6078 |
| maxfilesize | 27 | uint64_t | R | <a href="#section-5.8.2.17">Section 5.8.2.17</a> | |
| 6079 |
| maxlink | 28 | uint32_t | R | <a href="#section-5.8.2.18">Section 5.8.2.18</a> | |
| 6080 |
| maxname | 29 | uint32_t | R | <a href="#section-5.8.2.19">Section 5.8.2.19</a> | |
| 6081 |
| maxread | 30 | uint64_t | R | <a href="#section-5.8.2.20">Section 5.8.2.20</a> | |
| 6082 |
| maxwrite | 31 | uint64_t | R | <a href="#section-5.8.2.21">Section 5.8.2.21</a> | |
| 6083 |
| mdsthreshold | 68 | mdsthreshold4 | R | <a href="#section-5.12.6">Section 5.12.6</a> | |
| 6084 |
| mimetype | 32 | utf8str_cs | R W | <a href="#section-5.8.2.22">Section 5.8.2.22</a> | |
| 6085 |
| mode | 33 | mode4 | R W | <a href="#section-6.2.4">Section 6.2.4</a> | |
| 6086 |
| mode_set_masked | 74 | mode_masked4 | W | <a href="#section-6.2.5">Section 6.2.5</a> | |
| 6087 |
| mounted_on_fileid | 55 | uint64_t | R | <a href="#section-5.8.2.23">Section 5.8.2.23</a> | |
| 6088 |
| no_trunc | 34 | bool | R | <a href="#section-5.8.2.24">Section 5.8.2.24</a> | |
| 6089 |
| numlinks | 35 | uint32_t | R | <a href="#section-5.8.2.25">Section 5.8.2.25</a> | |
| 6090 |
| owner | 36 | utf8str_mixed | R W | <a href="#section-5.8.2.26">Section 5.8.2.26</a> | |
| 6091 |
| owner_group | 37 | utf8str_mixed | R W | <a href="#section-5.8.2.27">Section 5.8.2.27</a> | |
| 6092 |
| quota_avail_hard | 38 | uint64_t | R | <a href="#section-5.8.2.28">Section 5.8.2.28</a> | |
| 6093 |
| quota_avail_soft | 39 | uint64_t | R | <a href="#section-5.8.2.29">Section 5.8.2.29</a> | |
| 6094 |
| quota_used | 40 | uint64_t | R | <a href="#section-5.8.2.30">Section 5.8.2.30</a> | |
| 6095 |
| rawdev | 41 | specdata4 | R | <a href="#section-5.8.2.31">Section 5.8.2.31</a> | |
| 6096 |
| retentevt_get | 71 | retention_get4 | R | <a href="#section-5.13.3">Section 5.13.3</a> | |
| 6097 |
|
| 6098 |
|
| 6099 |
|
| 6100 |
<span class="grey">Shepler, et al. Standards Track [Page 109]</span></pre> |
| 6101 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-110" ></span> |
| 6102 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6103 |
|
| 6104 |
|
| 6105 |
| retentevt_set | 72 | retention_set4 | W | <a href="#section-5.13.4">Section 5.13.4</a> | |
| 6106 |
| retention_get | 69 | retention_get4 | R | <a href="#section-5.13.1">Section 5.13.1</a> | |
| 6107 |
| retention_hold | 73 | uint64_t | R W | <a href="#section-5.13.5">Section 5.13.5</a> | |
| 6108 |
| retention_set | 70 | retention_set4 | W | <a href="#section-5.13.2">Section 5.13.2</a> | |
| 6109 |
| sacl | 59 | nfsacl41 | R W | <a href="#section-6.2.3">Section 6.2.3</a> | |
| 6110 |
| space_avail | 42 | uint64_t | R | <a href="#section-5.8.2.32">Section 5.8.2.32</a> | |
| 6111 |
| space_free | 43 | uint64_t | R | <a href="#section-5.8.2.33">Section 5.8.2.33</a> | |
| 6112 |
| space_total | 44 | uint64_t | R | <a href="#section-5.8.2.34">Section 5.8.2.34</a> | |
| 6113 |
| space_used | 45 | uint64_t | R | <a href="#section-5.8.2.35">Section 5.8.2.35</a> | |
| 6114 |
| system | 46 | bool | R W | <a href="#section-5.8.2.36">Section 5.8.2.36</a> | |
| 6115 |
| time_access | 47 | nfstime4 | R | <a href="#section-5.8.2.37">Section 5.8.2.37</a> | |
| 6116 |
| time_access_set | 48 | settime4 | W | <a href="#section-5.8.2.38">Section 5.8.2.38</a> | |
| 6117 |
| time_backup | 49 | nfstime4 | R W | <a href="#section-5.8.2.39">Section 5.8.2.39</a> | |
| 6118 |
| time_create | 50 | nfstime4 | R W | <a href="#section-5.8.2.40">Section 5.8.2.40</a> | |
| 6119 |
| time_delta | 51 | nfstime4 | R | <a href="#section-5.8.2.41">Section 5.8.2.41</a> | |
| 6120 |
| time_metadata | 52 | nfstime4 | R | <a href="#section-5.8.2.42">Section 5.8.2.42</a> | |
| 6121 |
| time_modify | 53 | nfstime4 | R | <a href="#section-5.8.2.43">Section 5.8.2.43</a> | |
| 6122 |
| time_modify_set | 54 | settime4 | W | <a href="#section-5.8.2.44">Section 5.8.2.44</a> | |
| 6123 |
+--------------------+----+----------------+-----+------------------+ |
| 6124 |
|
| 6125 |
Table 3 |
| 6126 |
|
| 6127 |
* fs_locations_info4 |
| 6128 |
|
| 6129 |
<span class="h3"><a class="selflink" id="section-5.8" href="#section-5.8">5.8</a>. Attribute Definitions</span> |
| 6130 |
|
| 6131 |
<span class="h4"><a class="selflink" id="section-5.8.1" href="#section-5.8.1">5.8.1</a>. Definitions of REQUIRED Attributes</span> |
| 6132 |
|
| 6133 |
<span class="h5"><a class="selflink" id="section-5.8.1.1" href="#section-5.8.1.1">5.8.1.1</a>. Attribute 0: supported_attrs</span> |
| 6134 |
|
| 6135 |
The bit vector that would retrieve all REQUIRED and RECOMMENDED |
| 6136 |
attributes that are supported for this object. The scope of this |
| 6137 |
attribute applies to all objects with a matching fsid. |
| 6138 |
|
| 6139 |
<span class="h5"><a class="selflink" id="section-5.8.1.2" href="#section-5.8.1.2">5.8.1.2</a>. Attribute 1: type</span> |
| 6140 |
|
| 6141 |
Designates the type of an object in terms of one of a number of |
| 6142 |
special constants: |
| 6143 |
|
| 6144 |
o NF4REG designates a regular file. |
| 6145 |
|
| 6146 |
o NF4DIR designates a directory. |
| 6147 |
|
| 6148 |
o NF4BLK designates a block device special file. |
| 6149 |
|
| 6150 |
o NF4CHR designates a character device special file. |
| 6151 |
|
| 6152 |
o NF4LNK designates a symbolic link. |
| 6153 |
|
| 6154 |
|
| 6155 |
|
| 6156 |
<span class="grey">Shepler, et al. Standards Track [Page 110]</span></pre> |
| 6157 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-111" ></span> |
| 6158 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6159 |
|
| 6160 |
|
| 6161 |
o NF4SOCK designates a named socket special file. |
| 6162 |
|
| 6163 |
o NF4FIFO designates a fifo special file. |
| 6164 |
|
| 6165 |
o NF4ATTRDIR designates a named attribute directory. |
| 6166 |
|
| 6167 |
o NF4NAMEDATTR designates a named attribute. |
| 6168 |
|
| 6169 |
Within the explanatory text and operation descriptions, the following |
| 6170 |
phrases will be used with the meanings given below: |
| 6171 |
|
| 6172 |
o The phrase "is a directory" means that the object's type attribute |
| 6173 |
is NF4DIR or NF4ATTRDIR. |
| 6174 |
|
| 6175 |
o The phrase "is a special file" means that the object's type |
| 6176 |
attribute is NF4BLK, NF4CHR, NF4SOCK, or NF4FIFO. |
| 6177 |
|
| 6178 |
o The phrases "is an ordinary file" and "is a regular file" mean |
| 6179 |
that the object's type attribute is NF4REG or NF4NAMEDATTR. |
| 6180 |
|
| 6181 |
<span class="h5"><a class="selflink" id="section-5.8.1.3" href="#section-5.8.1.3">5.8.1.3</a>. Attribute 2: fh_expire_type</span> |
| 6182 |
|
| 6183 |
Server uses this to specify filehandle expiration behavior to the |
| 6184 |
client. See <a href="#section-4">Section 4</a> for additional description. |
| 6185 |
|
| 6186 |
<span class="h5"><a class="selflink" id="section-5.8.1.4" href="#section-5.8.1.4">5.8.1.4</a>. Attribute 3: change</span> |
| 6187 |
|
| 6188 |
A value created by the server that the client can use to determine if |
| 6189 |
file data, directory contents, or attributes of the object have been |
| 6190 |
modified. The server may return the object's time_metadata attribute |
| 6191 |
for this attribute's value, but only if the file system object cannot |
| 6192 |
be updated more frequently than the resolution of time_metadata. |
| 6193 |
|
| 6194 |
<span class="h5"><a class="selflink" id="section-5.8.1.5" href="#section-5.8.1.5">5.8.1.5</a>. Attribute 4: size</span> |
| 6195 |
|
| 6196 |
The size of the object in bytes. |
| 6197 |
|
| 6198 |
<span class="h5"><a class="selflink" id="section-5.8.1.6" href="#section-5.8.1.6">5.8.1.6</a>. Attribute 5: link_support</span> |
| 6199 |
|
| 6200 |
TRUE, if the object's file system supports hard links. |
| 6201 |
|
| 6202 |
<span class="h5"><a class="selflink" id="section-5.8.1.7" href="#section-5.8.1.7">5.8.1.7</a>. Attribute 6: symlink_support</span> |
| 6203 |
|
| 6204 |
TRUE, if the object's file system supports symbolic links. |
| 6205 |
|
| 6206 |
|
| 6207 |
|
| 6208 |
|
| 6209 |
|
| 6210 |
|
| 6211 |
|
| 6212 |
<span class="grey">Shepler, et al. Standards Track [Page 111]</span></pre> |
| 6213 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-112" ></span> |
| 6214 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6215 |
|
| 6216 |
|
| 6217 |
<span class="h5"><a class="selflink" id="section-5.8.1.8" href="#section-5.8.1.8">5.8.1.8</a>. Attribute 7: named_attr</span> |
| 6218 |
|
| 6219 |
TRUE, if this object has named attributes. In other words, object |
| 6220 |
has a non-empty named attribute directory. |
| 6221 |
|
| 6222 |
<span class="h5"><a class="selflink" id="section-5.8.1.9" href="#section-5.8.1.9">5.8.1.9</a>. Attribute 8: fsid</span> |
| 6223 |
|
| 6224 |
Unique file system identifier for the file system holding this |
| 6225 |
object. The fsid attribute has major and minor components, each of |
| 6226 |
which are of data type uint64_t. |
| 6227 |
|
| 6228 |
<span class="h5"><a class="selflink" id="section-5.8.1.10" href="#section-5.8.1.10">5.8.1.10</a>. Attribute 9: unique_handles</span> |
| 6229 |
|
| 6230 |
TRUE, if two distinct filehandles are guaranteed to refer to two |
| 6231 |
different file system objects. |
| 6232 |
|
| 6233 |
<span class="h5"><a class="selflink" id="section-5.8.1.11" href="#section-5.8.1.11">5.8.1.11</a>. Attribute 10: lease_time</span> |
| 6234 |
|
| 6235 |
Duration of the lease at server in seconds. |
| 6236 |
|
| 6237 |
<span class="h5"><a class="selflink" id="section-5.8.1.12" href="#section-5.8.1.12">5.8.1.12</a>. Attribute 11: rdattr_error</span> |
| 6238 |
|
| 6239 |
Error returned from an attempt to retrieve attributes during a |
| 6240 |
READDIR operation. |
| 6241 |
|
| 6242 |
<span class="h5"><a class="selflink" id="section-5.8.1.13" href="#section-5.8.1.13">5.8.1.13</a>. Attribute 19: filehandle</span> |
| 6243 |
|
| 6244 |
The filehandle of this object (primarily for READDIR requests). |
| 6245 |
|
| 6246 |
<span class="h5"><a class="selflink" id="section-5.8.1.14" href="#section-5.8.1.14">5.8.1.14</a>. Attribute 75: suppattr_exclcreat</span> |
| 6247 |
|
| 6248 |
The bit vector that would set all REQUIRED and RECOMMENDED attributes |
| 6249 |
that are supported by the EXCLUSIVE4_1 method of file creation via |
| 6250 |
the OPEN operation. The scope of this attribute applies to all |
| 6251 |
objects with a matching fsid. |
| 6252 |
|
| 6253 |
<span class="h4"><a class="selflink" id="section-5.8.2" href="#section-5.8.2">5.8.2</a>. Definitions of Uncategorized RECOMMENDED Attributes</span> |
| 6254 |
|
| 6255 |
The definitions of most of the RECOMMENDED attributes follow. |
| 6256 |
Collections that share a common category are defined in other |
| 6257 |
sections. |
| 6258 |
|
| 6259 |
<span class="h5"><a class="selflink" id="section-5.8.2.1" href="#section-5.8.2.1">5.8.2.1</a>. Attribute 14: archive</span> |
| 6260 |
|
| 6261 |
TRUE, if this file has been archived since the time of last |
| 6262 |
modification (deprecated in favor of time_backup). |
| 6263 |
|
| 6264 |
|
| 6265 |
|
| 6266 |
|
| 6267 |
|
| 6268 |
<span class="grey">Shepler, et al. Standards Track [Page 112]</span></pre> |
| 6269 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-113" ></span> |
| 6270 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6271 |
|
| 6272 |
|
| 6273 |
<span class="h5"><a class="selflink" id="section-5.8.2.2" href="#section-5.8.2.2">5.8.2.2</a>. Attribute 15: cansettime</span> |
| 6274 |
|
| 6275 |
TRUE, if the server is able to change the times for a file system |
| 6276 |
object as specified in a SETATTR operation. |
| 6277 |
|
| 6278 |
<span class="h5"><a class="selflink" id="section-5.8.2.3" href="#section-5.8.2.3">5.8.2.3</a>. Attribute 16: case_insensitive</span> |
| 6279 |
|
| 6280 |
TRUE, if file name comparisons on this file system are case |
| 6281 |
insensitive. |
| 6282 |
|
| 6283 |
<span class="h5"><a class="selflink" id="section-5.8.2.4" href="#section-5.8.2.4">5.8.2.4</a>. Attribute 17: case_preserving</span> |
| 6284 |
|
| 6285 |
TRUE, if file name case on this file system is preserved. |
| 6286 |
|
| 6287 |
<span class="h5"><a class="selflink" id="section-5.8.2.5" href="#section-5.8.2.5">5.8.2.5</a>. Attribute 60: change_policy</span> |
| 6288 |
|
| 6289 |
A value created by the server that the client can use to determine if |
| 6290 |
some server policy related to the current file system has been |
| 6291 |
subject to change. If the value remains the same, then the client |
| 6292 |
can be sure that the values of the attributes related to fs location |
| 6293 |
and the fss_type field of the fs_status attribute have not changed. |
| 6294 |
On the other hand, a change in this value does necessarily imply a |
| 6295 |
change in policy. It is up to the client to interrogate the server |
| 6296 |
to determine if some policy relevant to it has changed. See |
| 6297 |
<a href="#section-3.3.6">Section 3.3.6</a> for details. |
| 6298 |
|
| 6299 |
This attribute MUST change when the value returned by the |
| 6300 |
fs_locations or fs_locations_info attribute changes, when a file |
| 6301 |
system goes from read-only to writable or vice versa, or when the |
| 6302 |
allowable set of security flavors for the file system or any part |
| 6303 |
thereof is changed. |
| 6304 |
|
| 6305 |
<span class="h5"><a class="selflink" id="section-5.8.2.6" href="#section-5.8.2.6">5.8.2.6</a>. Attribute 18: chown_restricted</span> |
| 6306 |
|
| 6307 |
If TRUE, the server will reject any request to change either the |
| 6308 |
owner or the group associated with a file if the caller is not a |
| 6309 |
privileged user (for example, "root" in UNIX operating environments |
| 6310 |
or, in Windows 2000, the "Take Ownership" privilege). |
| 6311 |
|
| 6312 |
<span class="h5"><a class="selflink" id="section-5.8.2.7" href="#section-5.8.2.7">5.8.2.7</a>. Attribute 20: fileid</span> |
| 6313 |
|
| 6314 |
A number uniquely identifying the file within the file system. |
| 6315 |
|
| 6316 |
<span class="h5"><a class="selflink" id="section-5.8.2.8" href="#section-5.8.2.8">5.8.2.8</a>. Attribute 21: files_avail</span> |
| 6317 |
|
| 6318 |
File slots available to this user on the file system containing this |
| 6319 |
object -- this should be the smallest relevant limit. |
| 6320 |
|
| 6321 |
|
| 6322 |
|
| 6323 |
|
| 6324 |
<span class="grey">Shepler, et al. Standards Track [Page 113]</span></pre> |
| 6325 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-114" ></span> |
| 6326 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6327 |
|
| 6328 |
|
| 6329 |
<span class="h5"><a class="selflink" id="section-5.8.2.9" href="#section-5.8.2.9">5.8.2.9</a>. Attribute 22: files_free</span> |
| 6330 |
|
| 6331 |
Free file slots on the file system containing this object -- this |
| 6332 |
should be the smallest relevant limit. |
| 6333 |
|
| 6334 |
<span class="h5"><a class="selflink" id="section-5.8.2.10" href="#section-5.8.2.10">5.8.2.10</a>. Attribute 23: files_total</span> |
| 6335 |
|
| 6336 |
Total file slots on the file system containing this object. |
| 6337 |
|
| 6338 |
<span class="h5"><a class="selflink" id="section-5.8.2.11" href="#section-5.8.2.11">5.8.2.11</a>. Attribute 76: fs_charset_cap</span> |
| 6339 |
|
| 6340 |
Character set capabilities for this file system. See <a href="#section-14.4">Section 14.4</a>. |
| 6341 |
|
| 6342 |
<span class="h5"><a class="selflink" id="section-5.8.2.12" href="#section-5.8.2.12">5.8.2.12</a>. Attribute 24: fs_locations</span> |
| 6343 |
|
| 6344 |
Locations where this file system may be found. If the server returns |
| 6345 |
NFS4ERR_MOVED as an error, this attribute MUST be supported. See |
| 6346 |
<a href="#section-11.9">Section 11.9</a> for more details. |
| 6347 |
|
| 6348 |
<span class="h5"><a class="selflink" id="section-5.8.2.13" href="#section-5.8.2.13">5.8.2.13</a>. Attribute 67: fs_locations_info</span> |
| 6349 |
|
| 6350 |
Full function file system location. See <a href="#section-11.10">Section 11.10</a> for more |
| 6351 |
details. |
| 6352 |
|
| 6353 |
<span class="h5"><a class="selflink" id="section-5.8.2.14" href="#section-5.8.2.14">5.8.2.14</a>. Attribute 61: fs_status</span> |
| 6354 |
|
| 6355 |
Generic file system type information. See <a href="#section-11.11">Section 11.11</a> for more |
| 6356 |
details. |
| 6357 |
|
| 6358 |
<span class="h5"><a class="selflink" id="section-5.8.2.15" href="#section-5.8.2.15">5.8.2.15</a>. Attribute 25: hidden</span> |
| 6359 |
|
| 6360 |
TRUE, if the file is considered hidden with respect to the Windows |
| 6361 |
API. |
| 6362 |
|
| 6363 |
<span class="h5"><a class="selflink" id="section-5.8.2.16" href="#section-5.8.2.16">5.8.2.16</a>. Attribute 26: homogeneous</span> |
| 6364 |
|
| 6365 |
TRUE, if this object's file system is homogeneous; i.e., all objects |
| 6366 |
in the file system (all objects on the server with the same fsid) |
| 6367 |
have common values for all per-file-system attributes. |
| 6368 |
|
| 6369 |
<span class="h5"><a class="selflink" id="section-5.8.2.17" href="#section-5.8.2.17">5.8.2.17</a>. Attribute 27: maxfilesize</span> |
| 6370 |
|
| 6371 |
Maximum supported file size for the file system of this object. |
| 6372 |
|
| 6373 |
<span class="h5"><a class="selflink" id="section-5.8.2.18" href="#section-5.8.2.18">5.8.2.18</a>. Attribute 28: maxlink</span> |
| 6374 |
|
| 6375 |
Maximum number of links for this object. |
| 6376 |
|
| 6377 |
|
| 6378 |
|
| 6379 |
|
| 6380 |
<span class="grey">Shepler, et al. Standards Track [Page 114]</span></pre> |
| 6381 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-115" ></span> |
| 6382 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6383 |
|
| 6384 |
|
| 6385 |
<span class="h5"><a class="selflink" id="section-5.8.2.19" href="#section-5.8.2.19">5.8.2.19</a>. Attribute 29: maxname</span> |
| 6386 |
|
| 6387 |
Maximum file name size supported for this object. |
| 6388 |
|
| 6389 |
<span class="h5"><a class="selflink" id="section-5.8.2.20" href="#section-5.8.2.20">5.8.2.20</a>. Attribute 30: maxread</span> |
| 6390 |
|
| 6391 |
Maximum amount of data the READ operation will return for this |
| 6392 |
object. |
| 6393 |
|
| 6394 |
<span class="h5"><a class="selflink" id="section-5.8.2.21" href="#section-5.8.2.21">5.8.2.21</a>. Attribute 31: maxwrite</span> |
| 6395 |
|
| 6396 |
Maximum amount of data the WRITE operation will accept for this |
| 6397 |
object. This attribute SHOULD be supported if the file is writable. |
| 6398 |
Lack of this attribute can lead to the client either wasting |
| 6399 |
bandwidth or not receiving the best performance. |
| 6400 |
|
| 6401 |
<span class="h5"><a class="selflink" id="section-5.8.2.22" href="#section-5.8.2.22">5.8.2.22</a>. Attribute 32: mimetype</span> |
| 6402 |
|
| 6403 |
MIME body type/subtype of this object. |
| 6404 |
|
| 6405 |
<span class="h5"><a class="selflink" id="section-5.8.2.23" href="#section-5.8.2.23">5.8.2.23</a>. Attribute 55: mounted_on_fileid</span> |
| 6406 |
|
| 6407 |
Like fileid, but if the target filehandle is the root of a file |
| 6408 |
system, this attribute represents the fileid of the underlying |
| 6409 |
directory. |
| 6410 |
|
| 6411 |
UNIX-based operating environments connect a file system into the |
| 6412 |
namespace by connecting (mounting) the file system onto the existing |
| 6413 |
file object (the mount point, usually a directory) of an existing |
| 6414 |
file system. When the mount point's parent directory is read via an |
| 6415 |
API like readdir(), the return results are directory entries, each |
| 6416 |
with a component name and a fileid. The fileid of the mount point's |
| 6417 |
directory entry will be different from the fileid that the stat() |
| 6418 |
system call returns. The stat() system call is returning the fileid |
| 6419 |
of the root of the mounted file system, whereas readdir() is |
| 6420 |
returning the fileid that stat() would have returned before any file |
| 6421 |
systems were mounted on the mount point. |
| 6422 |
|
| 6423 |
Unlike NFSv3, NFSv4.1 allows a client's LOOKUP request to cross other |
| 6424 |
file systems. The client detects the file system crossing whenever |
| 6425 |
the filehandle argument of LOOKUP has an fsid attribute different |
| 6426 |
from that of the filehandle returned by LOOKUP. A UNIX-based client |
| 6427 |
will consider this a "mount point crossing". UNIX has a legacy |
| 6428 |
scheme for allowing a process to determine its current working |
| 6429 |
directory. This relies on readdir() of a mount point's parent and |
| 6430 |
stat() of the mount point returning fileids as previously described. |
| 6431 |
The mounted_on_fileid attribute corresponds to the fileid that |
| 6432 |
readdir() would have returned as described previously. |
| 6433 |
|
| 6434 |
|
| 6435 |
|
| 6436 |
<span class="grey">Shepler, et al. Standards Track [Page 115]</span></pre> |
| 6437 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-116" ></span> |
| 6438 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6439 |
|
| 6440 |
|
| 6441 |
While the NFSv4.1 client could simply fabricate a fileid |
| 6442 |
corresponding to what mounted_on_fileid provides (and if the server |
| 6443 |
does not support mounted_on_fileid, the client has no choice), there |
| 6444 |
is a risk that the client will generate a fileid that conflicts with |
| 6445 |
one that is already assigned to another object in the file system. |
| 6446 |
Instead, if the server can provide the mounted_on_fileid, the |
| 6447 |
potential for client operational problems in this area is eliminated. |
| 6448 |
|
| 6449 |
If the server detects that there is no mounted point at the target |
| 6450 |
file object, then the value for mounted_on_fileid that it returns is |
| 6451 |
the same as that of the fileid attribute. |
| 6452 |
|
| 6453 |
The mounted_on_fileid attribute is RECOMMENDED, so the server SHOULD |
| 6454 |
provide it if possible, and for a UNIX-based server, this is |
| 6455 |
straightforward. Usually, mounted_on_fileid will be requested during |
| 6456 |
a READDIR operation, in which case it is trivial (at least for UNIX- |
| 6457 |
based servers) to return mounted_on_fileid since it is equal to the |
| 6458 |
fileid of a directory entry returned by readdir(). If |
| 6459 |
mounted_on_fileid is requested in a GETATTR operation, the server |
| 6460 |
should obey an invariant that has it returning a value that is equal |
| 6461 |
to the file object's entry in the object's parent directory, i.e., |
| 6462 |
what readdir() would have returned. Some operating environments |
| 6463 |
allow a series of two or more file systems to be mounted onto a |
| 6464 |
single mount point. In this case, for the server to obey the |
| 6465 |
aforementioned invariant, it will need to find the base mount point, |
| 6466 |
and not the intermediate mount points. |
| 6467 |
|
| 6468 |
<span class="h5"><a class="selflink" id="section-5.8.2.24" href="#section-5.8.2.24">5.8.2.24</a>. Attribute 34: no_trunc</span> |
| 6469 |
|
| 6470 |
If this attribute is TRUE, then if the client uses a file name longer |
| 6471 |
than name_max, an error will be returned instead of the name being |
| 6472 |
truncated. |
| 6473 |
|
| 6474 |
<span class="h5"><a class="selflink" id="section-5.8.2.25" href="#section-5.8.2.25">5.8.2.25</a>. Attribute 35: numlinks</span> |
| 6475 |
|
| 6476 |
Number of hard links to this object. |
| 6477 |
|
| 6478 |
<span class="h5"><a class="selflink" id="section-5.8.2.26" href="#section-5.8.2.26">5.8.2.26</a>. Attribute 36: owner</span> |
| 6479 |
|
| 6480 |
The string name of the owner of this object. |
| 6481 |
|
| 6482 |
<span class="h5"><a class="selflink" id="section-5.8.2.27" href="#section-5.8.2.27">5.8.2.27</a>. Attribute 37: owner_group</span> |
| 6483 |
|
| 6484 |
The string name of the group ownership of this object. |
| 6485 |
|
| 6486 |
|
| 6487 |
|
| 6488 |
|
| 6489 |
|
| 6490 |
|
| 6491 |
|
| 6492 |
<span class="grey">Shepler, et al. Standards Track [Page 116]</span></pre> |
| 6493 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-117" ></span> |
| 6494 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6495 |
|
| 6496 |
|
| 6497 |
<span class="h5"><a class="selflink" id="section-5.8.2.28" href="#section-5.8.2.28">5.8.2.28</a>. Attribute 38: quota_avail_hard</span> |
| 6498 |
|
| 6499 |
The value in bytes that represents the amount of additional disk |
| 6500 |
space beyond the current allocation that can be allocated to this |
| 6501 |
file or directory before further allocations will be refused. It is |
| 6502 |
understood that this space may be consumed by allocations to other |
| 6503 |
files or directories. |
| 6504 |
|
| 6505 |
<span class="h5"><a class="selflink" id="section-5.8.2.29" href="#section-5.8.2.29">5.8.2.29</a>. Attribute 39: quota_avail_soft</span> |
| 6506 |
|
| 6507 |
The value in bytes that represents the amount of additional disk |
| 6508 |
space that can be allocated to this file or directory before the user |
| 6509 |
may reasonably be warned. It is understood that this space may be |
| 6510 |
consumed by allocations to other files or directories though there is |
| 6511 |
a rule as to which other files or directories. |
| 6512 |
|
| 6513 |
<span class="h5"><a class="selflink" id="section-5.8.2.30" href="#section-5.8.2.30">5.8.2.30</a>. Attribute 40: quota_used</span> |
| 6514 |
|
| 6515 |
The value in bytes that represents the amount of disk space used by |
| 6516 |
this file or directory and possibly a number of other similar files |
| 6517 |
or directories, where the set of "similar" meets at least the |
| 6518 |
criterion that allocating space to any file or directory in the set |
| 6519 |
will reduce the "quota_avail_hard" of every other file or directory |
| 6520 |
in the set. |
| 6521 |
|
| 6522 |
Note that there may be a number of distinct but overlapping sets of |
| 6523 |
files or directories for which a quota_used value is maintained, |
| 6524 |
e.g., "all files with a given owner", "all files with a given group |
| 6525 |
owner", etc. The server is at liberty to choose any of those sets |
| 6526 |
when providing the content of the quota_used attribute, but should do |
| 6527 |
so in a repeatable way. The rule may be configured per file system |
| 6528 |
or may be "choose the set with the smallest quota". |
| 6529 |
|
| 6530 |
<span class="h5"><a class="selflink" id="section-5.8.2.31" href="#section-5.8.2.31">5.8.2.31</a>. Attribute 41: rawdev</span> |
| 6531 |
|
| 6532 |
Raw device number of file of type NF4BLK or NF4CHR. The device |
| 6533 |
number is split into major and minor numbers. If the file's type |
| 6534 |
attribute is not NF4BLK or NF4CHR, the value returned SHOULD NOT be |
| 6535 |
considered useful. |
| 6536 |
|
| 6537 |
<span class="h5"><a class="selflink" id="section-5.8.2.32" href="#section-5.8.2.32">5.8.2.32</a>. Attribute 42: space_avail</span> |
| 6538 |
|
| 6539 |
Disk space in bytes available to this user on the file system |
| 6540 |
containing this object -- this should be the smallest relevant limit. |
| 6541 |
|
| 6542 |
|
| 6543 |
|
| 6544 |
|
| 6545 |
|
| 6546 |
|
| 6547 |
|
| 6548 |
<span class="grey">Shepler, et al. Standards Track [Page 117]</span></pre> |
| 6549 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-118" ></span> |
| 6550 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6551 |
|
| 6552 |
|
| 6553 |
<span class="h5"><a class="selflink" id="section-5.8.2.33" href="#section-5.8.2.33">5.8.2.33</a>. Attribute 43: space_free</span> |
| 6554 |
|
| 6555 |
Free disk space in bytes on the file system containing this object -- |
| 6556 |
this should be the smallest relevant limit. |
| 6557 |
|
| 6558 |
<span class="h5"><a class="selflink" id="section-5.8.2.34" href="#section-5.8.2.34">5.8.2.34</a>. Attribute 44: space_total</span> |
| 6559 |
|
| 6560 |
Total disk space in bytes on the file system containing this object. |
| 6561 |
|
| 6562 |
<span class="h5"><a class="selflink" id="section-5.8.2.35" href="#section-5.8.2.35">5.8.2.35</a>. Attribute 45: space_used</span> |
| 6563 |
|
| 6564 |
Number of file system bytes allocated to this object. |
| 6565 |
|
| 6566 |
<span class="h5"><a class="selflink" id="section-5.8.2.36" href="#section-5.8.2.36">5.8.2.36</a>. Attribute 46: system</span> |
| 6567 |
|
| 6568 |
This attribute is TRUE if this file is a "system" file with respect |
| 6569 |
to the Windows operating environment. |
| 6570 |
|
| 6571 |
<span class="h5"><a class="selflink" id="section-5.8.2.37" href="#section-5.8.2.37">5.8.2.37</a>. Attribute 47: time_access</span> |
| 6572 |
|
| 6573 |
The time_access attribute represents the time of last access to the |
| 6574 |
object by a READ operation sent to the server. The notion of what is |
| 6575 |
an "access" depends on the server's operating environment and/or the |
| 6576 |
server's file system semantics. For example, for servers obeying |
| 6577 |
Portable Operating System Interface (POSIX) semantics, time_access |
| 6578 |
would be updated only by the READ and READDIR operations and not any |
| 6579 |
of the operations that modify the content of the object [<a href="#ref-16" title="">16</a>], [<a href="#ref-17" title="">17</a>], |
| 6580 |
[<a href="#ref-18" title="">18</a>]. Of course, setting the corresponding time_access_set attribute |
| 6581 |
is another way to modify the time_access attribute. |
| 6582 |
|
| 6583 |
Whenever the file object resides on a writable file system, the |
| 6584 |
server should make its best efforts to record time_access into stable |
| 6585 |
storage. However, to mitigate the performance effects of doing so, |
| 6586 |
and most especially whenever the server is satisfying the read of the |
| 6587 |
object's content from its cache, the server MAY cache access time |
| 6588 |
updates and lazily write them to stable storage. It is also |
| 6589 |
acceptable to give administrators of the server the option to disable |
| 6590 |
time_access updates. |
| 6591 |
|
| 6592 |
<span class="h5"><a class="selflink" id="section-5.8.2.38" href="#section-5.8.2.38">5.8.2.38</a>. Attribute 48: time_access_set</span> |
| 6593 |
|
| 6594 |
Sets the time of last access to the object. SETATTR use only. |
| 6595 |
|
| 6596 |
<span class="h5"><a class="selflink" id="section-5.8.2.39" href="#section-5.8.2.39">5.8.2.39</a>. Attribute 49: time_backup</span> |
| 6597 |
|
| 6598 |
The time of last backup of the object. |
| 6599 |
|
| 6600 |
|
| 6601 |
|
| 6602 |
|
| 6603 |
|
| 6604 |
<span class="grey">Shepler, et al. Standards Track [Page 118]</span></pre> |
| 6605 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-119" ></span> |
| 6606 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6607 |
|
| 6608 |
|
| 6609 |
<span class="h5"><a class="selflink" id="section-5.8.2.40" href="#section-5.8.2.40">5.8.2.40</a>. Attribute 50: time_create</span> |
| 6610 |
|
| 6611 |
The time of creation of the object. This attribute does not have any |
| 6612 |
relation to the traditional UNIX file attribute "ctime" or "change |
| 6613 |
time". |
| 6614 |
|
| 6615 |
<span class="h5"><a class="selflink" id="section-5.8.2.41" href="#section-5.8.2.41">5.8.2.41</a>. Attribute 51: time_delta</span> |
| 6616 |
|
| 6617 |
Smallest useful server time granularity. |
| 6618 |
|
| 6619 |
<span class="h5"><a class="selflink" id="section-5.8.2.42" href="#section-5.8.2.42">5.8.2.42</a>. Attribute 52: time_metadata</span> |
| 6620 |
|
| 6621 |
The time of last metadata modification of the object. |
| 6622 |
|
| 6623 |
<span class="h5"><a class="selflink" id="section-5.8.2.43" href="#section-5.8.2.43">5.8.2.43</a>. Attribute 53: time_modify</span> |
| 6624 |
|
| 6625 |
The time of last modification to the object. |
| 6626 |
|
| 6627 |
<span class="h5"><a class="selflink" id="section-5.8.2.44" href="#section-5.8.2.44">5.8.2.44</a>. Attribute 54: time_modify_set</span> |
| 6628 |
|
| 6629 |
Sets the time of last modification to the object. SETATTR use only. |
| 6630 |
|
| 6631 |
<span class="h3"><a class="selflink" id="section-5.9" href="#section-5.9">5.9</a>. Interpreting owner and owner_group</span> |
| 6632 |
|
| 6633 |
The RECOMMENDED attributes "owner" and "owner_group" (and also users |
| 6634 |
and groups within the "acl" attribute) are represented in terms of a |
| 6635 |
UTF-8 string. To avoid a representation that is tied to a particular |
| 6636 |
underlying implementation at the client or server, the use of the |
| 6637 |
UTF-8 string has been chosen. Note that <a href="./rfc2624#section-6.1">Section 6.1 of RFC 2624</a> [<a href="#ref-45" title=""NFS Version 4 Design Considerations"">45</a>] |
| 6638 |
provides additional rationale. It is expected that the client and |
| 6639 |
server will have their own local representation of owner and |
| 6640 |
owner_group that is used for local storage or presentation to the end |
| 6641 |
user. Therefore, it is expected that when these attributes are |
| 6642 |
transferred between the client and server, the local representation |
| 6643 |
is translated to a syntax of the form "user@dns_domain". This will |
| 6644 |
allow for a client and server that do not use the same local |
| 6645 |
representation the ability to translate to a common syntax that can |
| 6646 |
be interpreted by both. |
| 6647 |
|
| 6648 |
Similarly, security principals may be represented in different ways |
| 6649 |
by different security mechanisms. Servers normally translate these |
| 6650 |
representations into a common format, generally that used by local |
| 6651 |
storage, to serve as a means of identifying the users corresponding |
| 6652 |
to these security principals. When these local identifiers are |
| 6653 |
translated to the form of the owner attribute, associated with files |
| 6654 |
created by such principals, they identify, in a common format, the |
| 6655 |
users associated with each corresponding set of security principals. |
| 6656 |
|
| 6657 |
|
| 6658 |
|
| 6659 |
|
| 6660 |
<span class="grey">Shepler, et al. Standards Track [Page 119]</span></pre> |
| 6661 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-120" ></span> |
| 6662 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6663 |
|
| 6664 |
|
| 6665 |
The translation used to interpret owner and group strings is not |
| 6666 |
specified as part of the protocol. This allows various solutions to |
| 6667 |
be employed. For example, a local translation table may be consulted |
| 6668 |
that maps a numeric identifier to the user@dns_domain syntax. A name |
| 6669 |
service may also be used to accomplish the translation. A server may |
| 6670 |
provide a more general service, not limited by any particular |
| 6671 |
translation (which would only translate a limited set of possible |
| 6672 |
strings) by storing the owner and owner_group attributes in local |
| 6673 |
storage without any translation or it may augment a translation |
| 6674 |
method by storing the entire string for attributes for which no |
| 6675 |
translation is available while using the local representation for |
| 6676 |
those cases in which a translation is available. |
| 6677 |
|
| 6678 |
Servers that do not provide support for all possible values of the |
| 6679 |
owner and owner_group attributes SHOULD return an error |
| 6680 |
(NFS4ERR_BADOWNER) when a string is presented that has no |
| 6681 |
translation, as the value to be set for a SETATTR of the owner, |
| 6682 |
owner_group, or acl attributes. When a server does accept an owner |
| 6683 |
or owner_group value as valid on a SETATTR (and similarly for the |
| 6684 |
owner and group strings in an acl), it is promising to return that |
| 6685 |
same string when a corresponding GETATTR is done. Configuration |
| 6686 |
changes (including changes from the mapping of the string to the |
| 6687 |
local representation) and ill-constructed name translations (those |
| 6688 |
that contain aliasing) may make that promise impossible to honor. |
| 6689 |
Servers should make appropriate efforts to avoid a situation in which |
| 6690 |
these attributes have their values changed when no real change to |
| 6691 |
ownership has occurred. |
| 6692 |
|
| 6693 |
The "dns_domain" portion of the owner string is meant to be a DNS |
| 6694 |
domain name, for example, [email protected]. Servers should accept as |
| 6695 |
valid a set of users for at least one domain. A server may treat |
| 6696 |
other domains as having no valid translations. A more general |
| 6697 |
service is provided when a server is capable of accepting users for |
| 6698 |
multiple domains, or for all domains, subject to security |
| 6699 |
constraints. |
| 6700 |
|
| 6701 |
In the case where there is no translation available to the client or |
| 6702 |
server, the attribute value will be constructed without the "@". |
| 6703 |
Therefore, the absence of the @ from the owner or owner_group |
| 6704 |
attribute signifies that no translation was available at the sender |
| 6705 |
and that the receiver of the attribute should not use that string as |
| 6706 |
a basis for translation into its own internal format. Even though |
| 6707 |
the attribute value cannot be translated, it may still be useful. In |
| 6708 |
the case of a client, the attribute string may be used for local |
| 6709 |
display of ownership. |
| 6710 |
|
| 6711 |
|
| 6712 |
|
| 6713 |
|
| 6714 |
|
| 6715 |
|
| 6716 |
<span class="grey">Shepler, et al. Standards Track [Page 120]</span></pre> |
| 6717 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-121" ></span> |
| 6718 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6719 |
|
| 6720 |
|
| 6721 |
To provide a greater degree of compatibility with NFSv3, which |
| 6722 |
identified users and groups by 32-bit unsigned user identifiers and |
| 6723 |
group identifiers, owner and group strings that consist of decimal |
| 6724 |
numeric values with no leading zeros can be given a special |
| 6725 |
interpretation by clients and servers that choose to provide such |
| 6726 |
support. The receiver may treat such a user or group string as |
| 6727 |
representing the same user as would be represented by an NFSv3 uid or |
| 6728 |
gid having the corresponding numeric value. A server is not |
| 6729 |
obligated to accept such a string, but may return an NFS4ERR_BADOWNER |
| 6730 |
instead. To avoid this mechanism being used to subvert user and |
| 6731 |
group translation, so that a client might pass all of the owners and |
| 6732 |
groups in numeric form, a server SHOULD return an NFS4ERR_BADOWNER |
| 6733 |
error when there is a valid translation for the user or owner |
| 6734 |
designated in this way. In that case, the client must use the |
| 6735 |
appropriate name@domain string and not the special form for |
| 6736 |
compatibility. |
| 6737 |
|
| 6738 |
The owner string "nobody" may be used to designate an anonymous user, |
| 6739 |
which will be associated with a file created by a security principal |
| 6740 |
that cannot be mapped through normal means to the owner attribute. |
| 6741 |
Users and implementations of NFSv4.1 SHOULD NOT use "nobody" to |
| 6742 |
designate a real user whose access is not anonymous. |
| 6743 |
|
| 6744 |
<span class="h3"><a class="selflink" id="section-5.10" href="#section-5.10">5.10</a>. Character Case Attributes</span> |
| 6745 |
|
| 6746 |
With respect to the case_insensitive and case_preserving attributes, |
| 6747 |
each UCS-4 character (which UTF-8 encodes) can be mapped according to |
| 6748 |
<a href="./rfc3454#appendix-B.2">Appendix B.2 of RFC 3454</a> [<a href="#ref-19" title=""Preparation of Internationalized Strings ("">19</a>]. For general character handling and |
| 6749 |
internationalization issues, see <a href="#section-14">Section 14</a>. |
| 6750 |
|
| 6751 |
<span class="h3"><a class="selflink" id="section-5.11" href="#section-5.11">5.11</a>. Directory Notification Attributes</span> |
| 6752 |
|
| 6753 |
As described in <a href="#section-18.39">Section 18.39</a>, the client can request a minimum delay |
| 6754 |
for notifications of changes to attributes, but the server is free to |
| 6755 |
ignore what the client requests. The client can determine in advance |
| 6756 |
what notification delays the server will accept by sending a GETATTR |
| 6757 |
operation for either or both of two directory notification |
| 6758 |
attributes. When the client calls the GET_DIR_DELEGATION operation |
| 6759 |
and asks for attribute change notifications, it should request |
| 6760 |
notification delays that are no less than the values in the server- |
| 6761 |
provided attributes. |
| 6762 |
|
| 6763 |
<span class="h4"><a class="selflink" id="section-5.11.1" href="#section-5.11.1">5.11.1</a>. Attribute 56: dir_notif_delay</span> |
| 6764 |
|
| 6765 |
The dir_notif_delay attribute is the minimum number of seconds the |
| 6766 |
server will delay before notifying the client of a change to the |
| 6767 |
directory's attributes. |
| 6768 |
|
| 6769 |
|
| 6770 |
|
| 6771 |
|
| 6772 |
<span class="grey">Shepler, et al. Standards Track [Page 121]</span></pre> |
| 6773 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-122" ></span> |
| 6774 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6775 |
|
| 6776 |
|
| 6777 |
<span class="h4"><a class="selflink" id="section-5.11.2" href="#section-5.11.2">5.11.2</a>. Attribute 57: dirent_notif_delay</span> |
| 6778 |
|
| 6779 |
The dirent_notif_delay attribute is the minimum number of seconds the |
| 6780 |
server will delay before notifying the client of a change to a file |
| 6781 |
object that has an entry in the directory. |
| 6782 |
|
| 6783 |
<span class="h3"><a class="selflink" id="section-5.12" href="#section-5.12">5.12</a>. pNFS Attribute Definitions</span> |
| 6784 |
|
| 6785 |
<span class="h4"><a class="selflink" id="section-5.12.1" href="#section-5.12.1">5.12.1</a>. Attribute 62: fs_layout_type</span> |
| 6786 |
|
| 6787 |
The fs_layout_type attribute (see <a href="#section-3.3.13">Section 3.3.13</a>) applies to a file |
| 6788 |
system and indicates what layout types are supported by the file |
| 6789 |
system. When the client encounters a new fsid, the client SHOULD |
| 6790 |
obtain the value for the fs_layout_type attribute associated with the |
| 6791 |
new file system. This attribute is used by the client to determine |
| 6792 |
if the layout types supported by the server match any of the client's |
| 6793 |
supported layout types. |
| 6794 |
|
| 6795 |
<span class="h4"><a class="selflink" id="section-5.12.2" href="#section-5.12.2">5.12.2</a>. Attribute 66: layout_alignment</span> |
| 6796 |
|
| 6797 |
When a client holds layouts on files of a file system, the |
| 6798 |
layout_alignment attribute indicates the preferred alignment for I/O |
| 6799 |
to files on that file system. Where possible, the client should send |
| 6800 |
READ and WRITE operations with offsets that are whole multiples of |
| 6801 |
the layout_alignment attribute. |
| 6802 |
|
| 6803 |
<span class="h4"><a class="selflink" id="section-5.12.3" href="#section-5.12.3">5.12.3</a>. Attribute 65: layout_blksize</span> |
| 6804 |
|
| 6805 |
When a client holds layouts on files of a file system, the |
| 6806 |
layout_blksize attribute indicates the preferred block size for I/O |
| 6807 |
to files on that file system. Where possible, the client should send |
| 6808 |
READ operations with a count argument that is a whole multiple of |
| 6809 |
layout_blksize, and WRITE operations with a data argument of size |
| 6810 |
that is a whole multiple of layout_blksize. |
| 6811 |
|
| 6812 |
<span class="h4"><a class="selflink" id="section-5.12.4" href="#section-5.12.4">5.12.4</a>. Attribute 63: layout_hint</span> |
| 6813 |
|
| 6814 |
The layout_hint attribute (see <a href="#section-3.3.19">Section 3.3.19</a>) may be set on newly |
| 6815 |
created files to influence the metadata server's choice for the |
| 6816 |
file's layout. If possible, this attribute is one of those set in |
| 6817 |
the initial attributes within the OPEN operation. The metadata |
| 6818 |
server may choose to ignore this attribute. The layout_hint |
| 6819 |
attribute is a subset of the layout structure returned by LAYOUTGET. |
| 6820 |
For example, instead of specifying particular devices, this would be |
| 6821 |
used to suggest the stripe width of a file. The server |
| 6822 |
implementation determines which fields within the layout will be |
| 6823 |
used. |
| 6824 |
|
| 6825 |
|
| 6826 |
|
| 6827 |
|
| 6828 |
<span class="grey">Shepler, et al. Standards Track [Page 122]</span></pre> |
| 6829 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-123" ></span> |
| 6830 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6831 |
|
| 6832 |
|
| 6833 |
<span class="h4"><a class="selflink" id="section-5.12.5" href="#section-5.12.5">5.12.5</a>. Attribute 64: layout_type</span> |
| 6834 |
|
| 6835 |
This attribute lists the layout type(s) available for a file. The |
| 6836 |
value returned by the server is for informational purposes only. The |
| 6837 |
client will use the LAYOUTGET operation to obtain the information |
| 6838 |
needed in order to perform I/O, for example, the specific device |
| 6839 |
information for the file and its layout. |
| 6840 |
|
| 6841 |
<span class="h4"><a class="selflink" id="section-5.12.6" href="#section-5.12.6">5.12.6</a>. Attribute 68: mdsthreshold</span> |
| 6842 |
|
| 6843 |
This attribute is a server-provided hint used to communicate to the |
| 6844 |
client when it is more efficient to send READ and WRITE operations to |
| 6845 |
the metadata server or the data server. The two types of thresholds |
| 6846 |
described are file size thresholds and I/O size thresholds. If a |
| 6847 |
file's size is smaller than the file size threshold, data accesses |
| 6848 |
SHOULD be sent to the metadata server. If an I/O request has a |
| 6849 |
length that is below the I/O size threshold, the I/O SHOULD be sent |
| 6850 |
to the metadata server. Each threshold type is specified separately |
| 6851 |
for read and write. |
| 6852 |
|
| 6853 |
The server MAY provide both types of thresholds for a file. If both |
| 6854 |
file size and I/O size are provided, the client SHOULD reach or |
| 6855 |
exceed both thresholds before sending its read or write requests to |
| 6856 |
the data server. Alternatively, if only one of the specified |
| 6857 |
thresholds is reached or exceeded, the I/O requests are sent to the |
| 6858 |
metadata server. |
| 6859 |
|
| 6860 |
For each threshold type, a value of zero indicates no READ or WRITE |
| 6861 |
should be sent to the metadata server, while a value of all ones |
| 6862 |
indicates that all READs or WRITEs should be sent to the metadata |
| 6863 |
server. |
| 6864 |
|
| 6865 |
The attribute is available on a per-filehandle basis. If the current |
| 6866 |
filehandle refers to a non-pNFS file or directory, the metadata |
| 6867 |
server should return an attribute that is representative of the |
| 6868 |
filehandle's file system. It is suggested that this attribute is |
| 6869 |
queried as part of the OPEN operation. Due to dynamic system |
| 6870 |
changes, the client should not assume that the attribute will remain |
| 6871 |
constant for any specific time period; thus, it should be |
| 6872 |
periodically refreshed. |
| 6873 |
|
| 6874 |
<span class="h3"><a class="selflink" id="section-5.13" href="#section-5.13">5.13</a>. Retention Attributes</span> |
| 6875 |
|
| 6876 |
Retention is a concept whereby a file object can be placed in an |
| 6877 |
immutable, undeletable, unrenamable state for a fixed or infinite |
| 6878 |
duration of time. Once in this "retained" state, the file cannot be |
| 6879 |
moved out of the state until the duration of retention has been |
| 6880 |
reached. |
| 6881 |
|
| 6882 |
|
| 6883 |
|
| 6884 |
<span class="grey">Shepler, et al. Standards Track [Page 123]</span></pre> |
| 6885 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-124" ></span> |
| 6886 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6887 |
|
| 6888 |
|
| 6889 |
When retention is enabled, retention MUST extend to the data of the |
| 6890 |
file, and the name of file. The server MAY extend retention to any |
| 6891 |
other property of the file, including any subset of REQUIRED, |
| 6892 |
RECOMMENDED, and named attributes, with the exceptions noted in this |
| 6893 |
section. |
| 6894 |
|
| 6895 |
Servers MAY support or not support retention on any file object type. |
| 6896 |
|
| 6897 |
The five retention attributes are explained in the next subsections. |
| 6898 |
|
| 6899 |
<span class="h4"><a class="selflink" id="section-5.13.1" href="#section-5.13.1">5.13.1</a>. Attribute 69: retention_get</span> |
| 6900 |
|
| 6901 |
If retention is enabled for the associated file, this attribute's |
| 6902 |
value represents the retention begin time of the file object. This |
| 6903 |
attribute's value is only readable with the GETATTR operation and |
| 6904 |
MUST NOT be modified by the SETATTR operation (<a href="#section-5.5">Section 5.5</a>). The |
| 6905 |
value of the attribute consists of: |
| 6906 |
|
| 6907 |
const RET4_DURATION_INFINITE = 0xffffffffffffffff; |
| 6908 |
struct retention_get4 { |
| 6909 |
uint64_t rg_duration; |
| 6910 |
nfstime4 rg_begin_time<1>; |
| 6911 |
}; |
| 6912 |
|
| 6913 |
The field rg_duration is the duration in seconds indicating how long |
| 6914 |
the file will be retained once retention is enabled. The field |
| 6915 |
rg_begin_time is an array of up to one absolute time value. If the |
| 6916 |
array is zero length, no beginning retention time has been |
| 6917 |
established, and retention is not enabled. If rg_duration is equal |
| 6918 |
to RET4_DURATION_INFINITE, the file, once retention is enabled, will |
| 6919 |
be retained for an infinite duration. |
| 6920 |
|
| 6921 |
If (as soon as) rg_duration is zero, then rg_begin_time will be of |
| 6922 |
zero length, and again, retention is not (no longer) enabled. |
| 6923 |
|
| 6924 |
<span class="h4"><a class="selflink" id="section-5.13.2" href="#section-5.13.2">5.13.2</a>. Attribute 70: retention_set</span> |
| 6925 |
|
| 6926 |
This attribute is used to set the retention duration and optionally |
| 6927 |
enable retention for the associated file object. This attribute is |
| 6928 |
only modifiable via the SETATTR operation and MUST NOT be retrieved |
| 6929 |
by the GETATTR operation (<a href="#section-5.5">Section 5.5</a>). This attribute corresponds |
| 6930 |
to retention_get. The value of the attribute consists of: |
| 6931 |
|
| 6932 |
struct retention_set4 { |
| 6933 |
bool rs_enable; |
| 6934 |
uint64_t rs_duration<1>; |
| 6935 |
}; |
| 6936 |
|
| 6937 |
|
| 6938 |
|
| 6939 |
|
| 6940 |
<span class="grey">Shepler, et al. Standards Track [Page 124]</span></pre> |
| 6941 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-125" ></span> |
| 6942 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6943 |
|
| 6944 |
|
| 6945 |
If the client sets rs_enable to TRUE, then it is enabling retention |
| 6946 |
on the file object with the begin time of retention starting from the |
| 6947 |
server's current time and date. The duration of the retention can |
| 6948 |
also be provided if the rs_duration array is of length one. The |
| 6949 |
duration is the time in seconds from the begin time of retention, and |
| 6950 |
if set to RET4_DURATION_INFINITE, the file is to be retained forever. |
| 6951 |
If retention is enabled, with no duration specified in either this |
| 6952 |
SETATTR or a previous SETATTR, the duration defaults to zero seconds. |
| 6953 |
The server MAY restrict the enabling of retention or the duration of |
| 6954 |
retention on the basis of the ACE4_WRITE_RETENTION ACL permission. |
| 6955 |
|
| 6956 |
The enabling of retention MUST NOT prevent the enabling of event- |
| 6957 |
based retention or the modification of the retention_hold attribute. |
| 6958 |
|
| 6959 |
The following rules apply to both the retention_set and retentevt_set |
| 6960 |
attributes. |
| 6961 |
|
| 6962 |
o As long as retention is not enabled, the client is permitted to |
| 6963 |
decrease the duration. |
| 6964 |
|
| 6965 |
o The duration can always be set to an equal or higher value, even |
| 6966 |
if retention is enabled. Note that once retention is enabled, the |
| 6967 |
actual duration (as returned by the retention_get or retentevt_get |
| 6968 |
attributes; see <a href="#section-5.13.1">Section 5.13.1</a> or <a href="#section-5.13.3">Section 5.13.3</a>) is constantly |
| 6969 |
counting down to zero (one unit per second), unless the duration |
| 6970 |
was set to RET4_DURATION_INFINITE. Thus, it will not be possible |
| 6971 |
for the client to precisely extend the duration on a file that has |
| 6972 |
retention enabled. |
| 6973 |
|
| 6974 |
o While retention is enabled, attempts to disable retention or |
| 6975 |
decrease the retention's duration MUST fail with the error |
| 6976 |
NFS4ERR_INVAL. |
| 6977 |
|
| 6978 |
o If the principal attempting to change retention_set or |
| 6979 |
retentevt_set does not have ACE4_WRITE_RETENTION permissions, the |
| 6980 |
attempt MUST fail with NFS4ERR_ACCESS. |
| 6981 |
|
| 6982 |
<span class="h4"><a class="selflink" id="section-5.13.3" href="#section-5.13.3">5.13.3</a>. Attribute 71: retentevt_get</span> |
| 6983 |
|
| 6984 |
Gets the event-based retention duration, and if enabled, the event- |
| 6985 |
based retention begin time of the file object. This attribute is |
| 6986 |
like retention_get, but refers to event-based retention. The event |
| 6987 |
that triggers event-based retention is not defined by the NFSv4.1 |
| 6988 |
specification. |
| 6989 |
|
| 6990 |
|
| 6991 |
|
| 6992 |
|
| 6993 |
|
| 6994 |
|
| 6995 |
|
| 6996 |
<span class="grey">Shepler, et al. Standards Track [Page 125]</span></pre> |
| 6997 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-126" ></span> |
| 6998 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 6999 |
|
| 7000 |
|
| 7001 |
<span class="h4"><a class="selflink" id="section-5.13.4" href="#section-5.13.4">5.13.4</a>. Attribute 72: retentevt_set</span> |
| 7002 |
|
| 7003 |
Sets the event-based retention duration, and optionally enables |
| 7004 |
event-based retention on the file object. This attribute corresponds |
| 7005 |
to retentevt_get and is like retention_set, but refers to event-based |
| 7006 |
retention. When event-based retention is set, the file MUST be |
| 7007 |
retained even if non-event-based retention has been set, and the |
| 7008 |
duration of non-event-based retention has been reached. Conversely, |
| 7009 |
when non-event-based retention has been set, the file MUST be |
| 7010 |
retained even if event-based retention has been set, and the duration |
| 7011 |
of event-based retention has been reached. The server MAY restrict |
| 7012 |
the enabling of event-based retention or the duration of event-based |
| 7013 |
retention on the basis of the ACE4_WRITE_RETENTION ACL permission. |
| 7014 |
The enabling of event-based retention MUST NOT prevent the enabling |
| 7015 |
of non-event-based retention or the modification of the |
| 7016 |
retention_hold attribute. |
| 7017 |
|
| 7018 |
<span class="h4"><a class="selflink" id="section-5.13.5" href="#section-5.13.5">5.13.5</a>. Attribute 73: retention_hold</span> |
| 7019 |
|
| 7020 |
Gets or sets administrative retention holds, one hold per bit |
| 7021 |
position. |
| 7022 |
|
| 7023 |
This attribute allows one to 64 administrative holds, one hold per |
| 7024 |
bit on the attribute. If retention_hold is not zero, then the file |
| 7025 |
MUST NOT be deleted, renamed, or modified, even if the duration on |
| 7026 |
enabled event or non-event-based retention has been reached. The |
| 7027 |
server MAY restrict the modification of retention_hold on the basis |
| 7028 |
of the ACE4_WRITE_RETENTION_HOLD ACL permission. The enabling of |
| 7029 |
administration retention holds does not prevent the enabling of |
| 7030 |
event-based or non-event-based retention. |
| 7031 |
|
| 7032 |
If the principal attempting to change retention_hold does not have |
| 7033 |
ACE4_WRITE_RETENTION_HOLD permissions, the attempt MUST fail with |
| 7034 |
NFS4ERR_ACCESS. |
| 7035 |
|
| 7036 |
<span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. Access Control Attributes</span> |
| 7037 |
|
| 7038 |
Access Control Lists (ACLs) are file attributes that specify fine- |
| 7039 |
grained access control. This section covers the "acl", "dacl", |
| 7040 |
"sacl", "aclsupport", "mode", and "mode_set_masked" file attributes |
| 7041 |
and their interactions. Note that file attributes may apply to any |
| 7042 |
file system object. |
| 7043 |
|
| 7044 |
<span class="h3"><a class="selflink" id="section-6.1" href="#section-6.1">6.1</a>. Goals</span> |
| 7045 |
|
| 7046 |
ACLs and modes represent two well-established models for specifying |
| 7047 |
permissions. This section specifies requirements that attempt to |
| 7048 |
meet the following goals: |
| 7049 |
|
| 7050 |
|
| 7051 |
|
| 7052 |
<span class="grey">Shepler, et al. Standards Track [Page 126]</span></pre> |
| 7053 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-127" ></span> |
| 7054 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7055 |
|
| 7056 |
|
| 7057 |
o If a server supports the mode attribute, it should provide |
| 7058 |
reasonable semantics to clients that only set and retrieve the |
| 7059 |
mode attribute. |
| 7060 |
|
| 7061 |
o If a server supports ACL attributes, it should provide reasonable |
| 7062 |
semantics to clients that only set and retrieve those attributes. |
| 7063 |
|
| 7064 |
o On servers that support the mode attribute, if ACL attributes have |
| 7065 |
never been set on an object, via inheritance or explicitly, the |
| 7066 |
behavior should be traditional UNIX-like behavior. |
| 7067 |
|
| 7068 |
o On servers that support the mode attribute, if the ACL attributes |
| 7069 |
have been previously set on an object, either explicitly or via |
| 7070 |
inheritance: |
| 7071 |
|
| 7072 |
* Setting only the mode attribute should effectively control the |
| 7073 |
traditional UNIX-like permissions of read, write, and execute |
| 7074 |
on owner, owner_group, and other. |
| 7075 |
|
| 7076 |
* Setting only the mode attribute should provide reasonable |
| 7077 |
security. For example, setting a mode of 000 should be enough |
| 7078 |
to ensure that future OPEN operations for |
| 7079 |
OPEN4_SHARE_ACCESS_READ or OPEN4_SHARE_ACCESS_WRITE by any |
| 7080 |
principal fail, regardless of a previously existing or |
| 7081 |
inherited ACL. |
| 7082 |
|
| 7083 |
o NFSv4.1 may introduce different semantics relating to the mode and |
| 7084 |
ACL attributes, but it does not render invalid any previously |
| 7085 |
existing implementations. Additionally, this section provides |
| 7086 |
clarifications based on previous implementations and discussions |
| 7087 |
around them. |
| 7088 |
|
| 7089 |
o On servers that support both the mode and the acl or dacl |
| 7090 |
attributes, the server must keep the two consistent with each |
| 7091 |
other. The value of the mode attribute (with the exception of the |
| 7092 |
three high-order bits described in <a href="#section-6.2.4">Section 6.2.4</a>) must be |
| 7093 |
determined entirely by the value of the ACL, so that use of the |
| 7094 |
mode is never required for anything other than setting the three |
| 7095 |
high-order bits. See <a href="#section-6.4.1">Section 6.4.1</a> for exact requirements. |
| 7096 |
|
| 7097 |
o When a mode attribute is set on an object, the ACL attributes may |
| 7098 |
need to be modified in order to not conflict with the new mode. |
| 7099 |
In such cases, it is desirable that the ACL keep as much |
| 7100 |
information as possible. This includes information about |
| 7101 |
inheritance, AUDIT and ALARM ACEs, and permissions granted and |
| 7102 |
denied that do not conflict with the new mode. |
| 7103 |
|
| 7104 |
|
| 7105 |
|
| 7106 |
|
| 7107 |
|
| 7108 |
<span class="grey">Shepler, et al. Standards Track [Page 127]</span></pre> |
| 7109 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-128" ></span> |
| 7110 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7111 |
|
| 7112 |
|
| 7113 |
<span class="h3"><a class="selflink" id="section-6.2" href="#section-6.2">6.2</a>. File Attributes Discussion</span> |
| 7114 |
|
| 7115 |
<span class="h4"><a class="selflink" id="section-6.2.1" href="#section-6.2.1">6.2.1</a>. Attribute 12: acl</span> |
| 7116 |
|
| 7117 |
The NFSv4.1 ACL attribute contains an array of Access Control Entries |
| 7118 |
(ACEs) that are associated with the file system object. Although the |
| 7119 |
client can set and get the acl attribute, the server is responsible |
| 7120 |
for using the ACL to perform access control. The client can use the |
| 7121 |
OPEN or ACCESS operations to check access without modifying or |
| 7122 |
reading data or metadata. |
| 7123 |
|
| 7124 |
The NFS ACE structure is defined as follows: |
| 7125 |
|
| 7126 |
typedef uint32_t acetype4; |
| 7127 |
|
| 7128 |
typedef uint32_t aceflag4; |
| 7129 |
|
| 7130 |
|
| 7131 |
typedef uint32_t acemask4; |
| 7132 |
|
| 7133 |
|
| 7134 |
struct nfsace4 { |
| 7135 |
acetype4 type; |
| 7136 |
aceflag4 flag; |
| 7137 |
acemask4 access_mask; |
| 7138 |
utf8str_mixed who; |
| 7139 |
}; |
| 7140 |
|
| 7141 |
To determine if a request succeeds, the server processes each nfsace4 |
| 7142 |
entry in order. Only ACEs that have a "who" that matches the |
| 7143 |
requester are considered. Each ACE is processed until all of the |
| 7144 |
bits of the requester's access have been ALLOWED. Once a bit (see |
| 7145 |
below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it is no longer |
| 7146 |
considered in the processing of later ACEs. If an ACCESS_DENIED_ACE |
| 7147 |
is encountered where the requester's access still has unALLOWED bits |
| 7148 |
in common with the "access_mask" of the ACE, the request is denied. |
| 7149 |
When the ACL is fully processed, if there are bits in the requester's |
| 7150 |
mask that have not been ALLOWED or DENIED, access is denied. |
| 7151 |
|
| 7152 |
Unlike the ALLOW and DENY ACE types, the ALARM and AUDIT ACE types do |
| 7153 |
not affect a requester's access, and instead are for triggering |
| 7154 |
events as a result of a requester's access attempt. Therefore, AUDIT |
| 7155 |
and ALARM ACEs are processed only after processing ALLOW and DENY |
| 7156 |
ACEs. |
| 7157 |
|
| 7158 |
The NFSv4.1 ACL model is quite rich. Some server platforms may |
| 7159 |
provide access-control functionality that goes beyond the UNIX-style |
| 7160 |
mode attribute, but that is not as rich as the NFS ACL model. So |
| 7161 |
|
| 7162 |
|
| 7163 |
|
| 7164 |
<span class="grey">Shepler, et al. Standards Track [Page 128]</span></pre> |
| 7165 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-129" ></span> |
| 7166 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7167 |
|
| 7168 |
|
| 7169 |
that users can take advantage of this more limited functionality, the |
| 7170 |
server may support the acl attributes by mapping between its ACL |
| 7171 |
model and the NFSv4.1 ACL model. Servers must ensure that the ACL |
| 7172 |
they actually store or enforce is at least as strict as the NFSv4 ACL |
| 7173 |
that was set. It is tempting to accomplish this by rejecting any ACL |
| 7174 |
that falls outside the small set that can be represented accurately. |
| 7175 |
However, such an approach can render ACLs unusable without special |
| 7176 |
client-side knowledge of the server's mapping, which defeats the |
| 7177 |
purpose of having a common NFSv4 ACL protocol. Therefore, servers |
| 7178 |
should accept every ACL that they can without compromising security. |
| 7179 |
To help accomplish this, servers may make a special exception, in the |
| 7180 |
case of unsupported permission bits, to the rule that bits not |
| 7181 |
ALLOWED or DENIED by an ACL must be denied. For example, a UNIX- |
| 7182 |
style server might choose to silently allow read attribute |
| 7183 |
permissions even though an ACL does not explicitly allow those |
| 7184 |
permissions. (An ACL that explicitly denies permission to read |
| 7185 |
attributes should still be rejected.) |
| 7186 |
|
| 7187 |
The situation is complicated by the fact that a server may have |
| 7188 |
multiple modules that enforce ACLs. For example, the enforcement for |
| 7189 |
NFSv4.1 access may be different from, but not weaker than, the |
| 7190 |
enforcement for local access, and both may be different from the |
| 7191 |
enforcement for access through other protocols such as SMB (Server |
| 7192 |
Message Block). So it may be useful for a server to accept an ACL |
| 7193 |
even if not all of its modules are able to support it. |
| 7194 |
|
| 7195 |
The guiding principle with regard to NFSv4 access is that the server |
| 7196 |
must not accept ACLs that appear to make access to the file more |
| 7197 |
restrictive than it really is. |
| 7198 |
|
| 7199 |
<span class="h5"><a class="selflink" id="section-6.2.1.1" href="#section-6.2.1.1">6.2.1.1</a>. ACE Type</span> |
| 7200 |
|
| 7201 |
The constants used for the type field (acetype4) are as follows: |
| 7202 |
|
| 7203 |
const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; |
| 7204 |
const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; |
| 7205 |
const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; |
| 7206 |
const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; |
| 7207 |
|
| 7208 |
Only the ALLOWED and DENIED bits may be used in the dacl attribute, |
| 7209 |
and only the AUDIT and ALARM bits may be used in the sacl attribute. |
| 7210 |
All four are permitted in the acl attribute. |
| 7211 |
|
| 7212 |
|
| 7213 |
|
| 7214 |
|
| 7215 |
|
| 7216 |
|
| 7217 |
|
| 7218 |
|
| 7219 |
|
| 7220 |
<span class="grey">Shepler, et al. Standards Track [Page 129]</span></pre> |
| 7221 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-130" ></span> |
| 7222 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7223 |
|
| 7224 |
|
| 7225 |
+------------------------------+--------------+---------------------+ |
| 7226 |
| Value | Abbreviation | Description | |
| 7227 |
+------------------------------+--------------+---------------------+ |
| 7228 |
| ACE4_ACCESS_ALLOWED_ACE_TYPE | ALLOW | Explicitly grants | |
| 7229 |
| | | the access defined | |
| 7230 |
| | | in acemask4 to the | |
| 7231 |
| | | file or directory. | |
| 7232 |
| ACE4_ACCESS_DENIED_ACE_TYPE | DENY | Explicitly denies | |
| 7233 |
| | | the access defined | |
| 7234 |
| | | in acemask4 to the | |
| 7235 |
| | | file or directory. | |
| 7236 |
| ACE4_SYSTEM_AUDIT_ACE_TYPE | AUDIT | Log (in a | |
| 7237 |
| | | system-dependent | |
| 7238 |
| | | way) any access | |
| 7239 |
| | | attempt to a file | |
| 7240 |
| | | or directory that | |
| 7241 |
| | | uses any of the | |
| 7242 |
| | | access methods | |
| 7243 |
| | | specified in | |
| 7244 |
| | | acemask4. | |
| 7245 |
| ACE4_SYSTEM_ALARM_ACE_TYPE | ALARM | Generate an alarm | |
| 7246 |
| | | (in a | |
| 7247 |
| | | system-dependent | |
| 7248 |
| | | way) when any | |
| 7249 |
| | | access attempt is | |
| 7250 |
| | | made to a file or | |
| 7251 |
| | | directory for the | |
| 7252 |
| | | access methods | |
| 7253 |
| | | specified in | |
| 7254 |
| | | acemask4. | |
| 7255 |
+------------------------------+--------------+---------------------+ |
| 7256 |
|
| 7257 |
The "Abbreviation" column denotes how the types will be referred to |
| 7258 |
throughout the rest of this section. |
| 7259 |
|
| 7260 |
<span class="h5"><a class="selflink" id="section-6.2.1.2" href="#section-6.2.1.2">6.2.1.2</a>. Attribute 13: aclsupport</span> |
| 7261 |
|
| 7262 |
A server need not support all of the above ACE types. This attribute |
| 7263 |
indicates which ACE types are supported for the current file system. |
| 7264 |
The bitmask constants used to represent the above definitions within |
| 7265 |
the aclsupport attribute are as follows: |
| 7266 |
|
| 7267 |
const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; |
| 7268 |
const ACL4_SUPPORT_DENY_ACL = 0x00000002; |
| 7269 |
const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; |
| 7270 |
const ACL4_SUPPORT_ALARM_ACL = 0x00000008; |
| 7271 |
|
| 7272 |
|
| 7273 |
|
| 7274 |
|
| 7275 |
|
| 7276 |
<span class="grey">Shepler, et al. Standards Track [Page 130]</span></pre> |
| 7277 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-131" ></span> |
| 7278 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7279 |
|
| 7280 |
|
| 7281 |
Servers that support either the ALLOW or DENY ACE type SHOULD support |
| 7282 |
both ALLOW and DENY ACE types. |
| 7283 |
|
| 7284 |
Clients should not attempt to set an ACE unless the server claims |
| 7285 |
support for that ACE type. If the server receives a request to set |
| 7286 |
an ACE that it cannot store, it MUST reject the request with |
| 7287 |
NFS4ERR_ATTRNOTSUPP. If the server receives a request to set an ACE |
| 7288 |
that it can store but cannot enforce, the server SHOULD reject the |
| 7289 |
request with NFS4ERR_ATTRNOTSUPP. |
| 7290 |
|
| 7291 |
Support for any of the ACL attributes is optional (albeit |
| 7292 |
RECOMMENDED). However, a server that supports either of the new ACL |
| 7293 |
attributes (dacl or sacl) MUST allow use of the new ACL attributes to |
| 7294 |
access all of the ACE types that it supports. In other words, if |
| 7295 |
such a server supports ALLOW or DENY ACEs, then it MUST support the |
| 7296 |
dacl attribute, and if it supports AUDIT or ALARM ACEs, then it MUST |
| 7297 |
support the sacl attribute. |
| 7298 |
|
| 7299 |
<span class="h5"><a class="selflink" id="section-6.2.1.3" href="#section-6.2.1.3">6.2.1.3</a>. ACE Access Mask</span> |
| 7300 |
|
| 7301 |
The bitmask constants used for the access mask field are as follows: |
| 7302 |
|
| 7303 |
const ACE4_READ_DATA = 0x00000001; |
| 7304 |
const ACE4_LIST_DIRECTORY = 0x00000001; |
| 7305 |
const ACE4_WRITE_DATA = 0x00000002; |
| 7306 |
const ACE4_ADD_FILE = 0x00000002; |
| 7307 |
const ACE4_APPEND_DATA = 0x00000004; |
| 7308 |
const ACE4_ADD_SUBDIRECTORY = 0x00000004; |
| 7309 |
const ACE4_READ_NAMED_ATTRS = 0x00000008; |
| 7310 |
const ACE4_WRITE_NAMED_ATTRS = 0x00000010; |
| 7311 |
const ACE4_EXECUTE = 0x00000020; |
| 7312 |
const ACE4_DELETE_CHILD = 0x00000040; |
| 7313 |
const ACE4_READ_ATTRIBUTES = 0x00000080; |
| 7314 |
const ACE4_WRITE_ATTRIBUTES = 0x00000100; |
| 7315 |
const ACE4_WRITE_RETENTION = 0x00000200; |
| 7316 |
const ACE4_WRITE_RETENTION_HOLD = 0x00000400; |
| 7317 |
|
| 7318 |
const ACE4_DELETE = 0x00010000; |
| 7319 |
const ACE4_READ_ACL = 0x00020000; |
| 7320 |
const ACE4_WRITE_ACL = 0x00040000; |
| 7321 |
const ACE4_WRITE_OWNER = 0x00080000; |
| 7322 |
const ACE4_SYNCHRONIZE = 0x00100000; |
| 7323 |
|
| 7324 |
Note that some masks have coincident values, for example, |
| 7325 |
ACE4_READ_DATA and ACE4_LIST_DIRECTORY. The mask entries |
| 7326 |
ACE4_LIST_DIRECTORY, ACE4_ADD_FILE, and ACE4_ADD_SUBDIRECTORY are |
| 7327 |
|
| 7328 |
|
| 7329 |
|
| 7330 |
|
| 7331 |
|
| 7332 |
<span class="grey">Shepler, et al. Standards Track [Page 131]</span></pre> |
| 7333 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-132" ></span> |
| 7334 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7335 |
|
| 7336 |
|
| 7337 |
intended to be used with directory objects, while ACE4_READ_DATA, |
| 7338 |
ACE4_WRITE_DATA, and ACE4_APPEND_DATA are intended to be used with |
| 7339 |
non-directory objects. |
| 7340 |
|
| 7341 |
<span class="h6"><a class="selflink" id="section-6.2.1.3.1" href="#section-6.2.1.3.1">6.2.1.3.1</a>. Discussion of Mask Attributes</span> |
| 7342 |
|
| 7343 |
ACE4_READ_DATA |
| 7344 |
|
| 7345 |
Operation(s) affected: |
| 7346 |
|
| 7347 |
READ |
| 7348 |
|
| 7349 |
OPEN |
| 7350 |
|
| 7351 |
Discussion: |
| 7352 |
|
| 7353 |
Permission to read the data of the file. |
| 7354 |
|
| 7355 |
Servers SHOULD allow a user the ability to read the data of the |
| 7356 |
file when only the ACE4_EXECUTE access mask bit is allowed. |
| 7357 |
|
| 7358 |
ACE4_LIST_DIRECTORY |
| 7359 |
|
| 7360 |
Operation(s) affected: |
| 7361 |
|
| 7362 |
READDIR |
| 7363 |
|
| 7364 |
Discussion: |
| 7365 |
|
| 7366 |
Permission to list the contents of a directory. |
| 7367 |
|
| 7368 |
ACE4_WRITE_DATA |
| 7369 |
|
| 7370 |
Operation(s) affected: |
| 7371 |
|
| 7372 |
WRITE |
| 7373 |
|
| 7374 |
OPEN |
| 7375 |
|
| 7376 |
SETATTR of size |
| 7377 |
|
| 7378 |
Discussion: |
| 7379 |
|
| 7380 |
Permission to modify a file's data. |
| 7381 |
|
| 7382 |
ACE4_ADD_FILE |
| 7383 |
|
| 7384 |
|
| 7385 |
|
| 7386 |
|
| 7387 |
|
| 7388 |
<span class="grey">Shepler, et al. Standards Track [Page 132]</span></pre> |
| 7389 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-133" ></span> |
| 7390 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7391 |
|
| 7392 |
|
| 7393 |
Operation(s) affected: |
| 7394 |
|
| 7395 |
CREATE |
| 7396 |
|
| 7397 |
LINK |
| 7398 |
|
| 7399 |
OPEN |
| 7400 |
|
| 7401 |
RENAME |
| 7402 |
|
| 7403 |
Discussion: |
| 7404 |
|
| 7405 |
Permission to add a new file in a directory. The CREATE |
| 7406 |
operation is affected when nfs_ftype4 is NF4LNK, NF4BLK, |
| 7407 |
NF4CHR, NF4SOCK, or NF4FIFO. (NF4DIR is not listed because it |
| 7408 |
is covered by ACE4_ADD_SUBDIRECTORY.) OPEN is affected when |
| 7409 |
used to create a regular file. LINK and RENAME are always |
| 7410 |
affected. |
| 7411 |
|
| 7412 |
|
| 7413 |
ACE4_APPEND_DATA |
| 7414 |
|
| 7415 |
Operation(s) affected: |
| 7416 |
|
| 7417 |
WRITE |
| 7418 |
|
| 7419 |
OPEN |
| 7420 |
|
| 7421 |
SETATTR of size |
| 7422 |
|
| 7423 |
Discussion: |
| 7424 |
|
| 7425 |
The ability to modify a file's data, but only starting at EOF. |
| 7426 |
This allows for the notion of append-only files, by allowing |
| 7427 |
ACE4_APPEND_DATA and denying ACE4_WRITE_DATA to the same user |
| 7428 |
or group. If a file has an ACL such as the one described above |
| 7429 |
and a WRITE request is made for somewhere other than EOF, the |
| 7430 |
server SHOULD return NFS4ERR_ACCESS. |
| 7431 |
|
| 7432 |
ACE4_ADD_SUBDIRECTORY |
| 7433 |
|
| 7434 |
Operation(s) affected: |
| 7435 |
|
| 7436 |
CREATE |
| 7437 |
|
| 7438 |
RENAME |
| 7439 |
|
| 7440 |
|
| 7441 |
|
| 7442 |
|
| 7443 |
|
| 7444 |
<span class="grey">Shepler, et al. Standards Track [Page 133]</span></pre> |
| 7445 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-134" ></span> |
| 7446 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7447 |
|
| 7448 |
|
| 7449 |
Discussion: |
| 7450 |
|
| 7451 |
Permission to create a subdirectory in a directory. The CREATE |
| 7452 |
operation is affected when nfs_ftype4 is NF4DIR. The RENAME |
| 7453 |
operation is always affected. |
| 7454 |
|
| 7455 |
ACE4_READ_NAMED_ATTRS |
| 7456 |
|
| 7457 |
Operation(s) affected: |
| 7458 |
|
| 7459 |
OPENATTR |
| 7460 |
|
| 7461 |
Discussion: |
| 7462 |
|
| 7463 |
Permission to read the named attributes of a file or to look up |
| 7464 |
the named attribute directory. OPENATTR is affected when it is |
| 7465 |
not used to create a named attribute directory. This is when |
| 7466 |
1) createdir is TRUE, but a named attribute directory already |
| 7467 |
exists, or 2) createdir is FALSE. |
| 7468 |
|
| 7469 |
ACE4_WRITE_NAMED_ATTRS |
| 7470 |
|
| 7471 |
Operation(s) affected: |
| 7472 |
|
| 7473 |
OPENATTR |
| 7474 |
|
| 7475 |
Discussion: |
| 7476 |
|
| 7477 |
Permission to write the named attributes of a file or to create |
| 7478 |
a named attribute directory. OPENATTR is affected when it is |
| 7479 |
used to create a named attribute directory. This is when |
| 7480 |
createdir is TRUE and no named attribute directory exists. The |
| 7481 |
ability to check whether or not a named attribute directory |
| 7482 |
exists depends on the ability to look it up; therefore, users |
| 7483 |
also need the ACE4_READ_NAMED_ATTRS permission in order to |
| 7484 |
create a named attribute directory. |
| 7485 |
|
| 7486 |
ACE4_EXECUTE |
| 7487 |
|
| 7488 |
Operation(s) affected: |
| 7489 |
|
| 7490 |
READ |
| 7491 |
|
| 7492 |
OPEN |
| 7493 |
|
| 7494 |
REMOVE |
| 7495 |
|
| 7496 |
RENAME |
| 7497 |
|
| 7498 |
|
| 7499 |
|
| 7500 |
<span class="grey">Shepler, et al. Standards Track [Page 134]</span></pre> |
| 7501 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-135" ></span> |
| 7502 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7503 |
|
| 7504 |
|
| 7505 |
LINK |
| 7506 |
|
| 7507 |
CREATE |
| 7508 |
|
| 7509 |
Discussion: |
| 7510 |
|
| 7511 |
Permission to execute a file. |
| 7512 |
|
| 7513 |
Servers SHOULD allow a user the ability to read the data of the |
| 7514 |
file when only the ACE4_EXECUTE access mask bit is allowed. |
| 7515 |
This is because there is no way to execute a file without |
| 7516 |
reading the contents. Though a server may treat ACE4_EXECUTE |
| 7517 |
and ACE4_READ_DATA bits identically when deciding to permit a |
| 7518 |
READ operation, it SHOULD still allow the two bits to be set |
| 7519 |
independently in ACLs, and MUST distinguish between them when |
| 7520 |
replying to ACCESS operations. In particular, servers SHOULD |
| 7521 |
NOT silently turn on one of the two bits when the other is set, |
| 7522 |
as that would make it impossible for the client to correctly |
| 7523 |
enforce the distinction between read and execute permissions. |
| 7524 |
|
| 7525 |
As an example, following a SETATTR of the following ACL: |
| 7526 |
|
| 7527 |
nfsuser:ACE4_EXECUTE:ALLOW |
| 7528 |
|
| 7529 |
A subsequent GETATTR of ACL for that file SHOULD return: |
| 7530 |
|
| 7531 |
nfsuser:ACE4_EXECUTE:ALLOW |
| 7532 |
|
| 7533 |
Rather than: |
| 7534 |
|
| 7535 |
nfsuser:ACE4_EXECUTE/ACE4_READ_DATA:ALLOW |
| 7536 |
|
| 7537 |
ACE4_EXECUTE |
| 7538 |
|
| 7539 |
Operation(s) affected: |
| 7540 |
|
| 7541 |
LOOKUP |
| 7542 |
|
| 7543 |
Discussion: |
| 7544 |
|
| 7545 |
Permission to traverse/search a directory. |
| 7546 |
|
| 7547 |
ACE4_DELETE_CHILD |
| 7548 |
|
| 7549 |
Operation(s) affected: |
| 7550 |
|
| 7551 |
REMOVE |
| 7552 |
|
| 7553 |
|
| 7554 |
|
| 7555 |
|
| 7556 |
<span class="grey">Shepler, et al. Standards Track [Page 135]</span></pre> |
| 7557 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-136" ></span> |
| 7558 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7559 |
|
| 7560 |
|
| 7561 |
RENAME |
| 7562 |
|
| 7563 |
Discussion: |
| 7564 |
|
| 7565 |
Permission to delete a file or directory within a directory. |
| 7566 |
See <a href="#section-6.2.1.3.2">Section 6.2.1.3.2</a> for information on ACE4_DELETE and |
| 7567 |
ACE4_DELETE_CHILD interact. |
| 7568 |
|
| 7569 |
ACE4_READ_ATTRIBUTES |
| 7570 |
|
| 7571 |
Operation(s) affected: |
| 7572 |
|
| 7573 |
GETATTR of file system object attributes |
| 7574 |
|
| 7575 |
VERIFY |
| 7576 |
|
| 7577 |
NVERIFY |
| 7578 |
|
| 7579 |
READDIR |
| 7580 |
|
| 7581 |
Discussion: |
| 7582 |
|
| 7583 |
The ability to read basic attributes (non-ACLs) of a file. On |
| 7584 |
a UNIX system, basic attributes can be thought of as the stat- |
| 7585 |
level attributes. Allowing this access mask bit would mean |
| 7586 |
that the entity can execute "ls -l" and stat. If a READDIR |
| 7587 |
operation requests attributes, this mask must be allowed for |
| 7588 |
the READDIR to succeed. |
| 7589 |
|
| 7590 |
ACE4_WRITE_ATTRIBUTES |
| 7591 |
|
| 7592 |
Operation(s) affected: |
| 7593 |
|
| 7594 |
SETATTR of time_access_set, time_backup, |
| 7595 |
|
| 7596 |
time_create, time_modify_set, mimetype, hidden, system |
| 7597 |
|
| 7598 |
Discussion: |
| 7599 |
|
| 7600 |
Permission to change the times associated with a file or |
| 7601 |
directory to an arbitrary value. Also permission to change the |
| 7602 |
mimetype, hidden, and system attributes. A user having |
| 7603 |
ACE4_WRITE_DATA or ACE4_WRITE_ATTRIBUTES will be allowed to set |
| 7604 |
the times associated with a file to the current server time. |
| 7605 |
|
| 7606 |
|
| 7607 |
|
| 7608 |
|
| 7609 |
|
| 7610 |
|
| 7611 |
|
| 7612 |
<span class="grey">Shepler, et al. Standards Track [Page 136]</span></pre> |
| 7613 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-137" ></span> |
| 7614 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7615 |
|
| 7616 |
|
| 7617 |
ACE4_WRITE_RETENTION |
| 7618 |
|
| 7619 |
Operation(s) affected: |
| 7620 |
|
| 7621 |
SETATTR of retention_set, retentevt_set. |
| 7622 |
|
| 7623 |
Discussion: |
| 7624 |
|
| 7625 |
Permission to modify the durations of event and non-event-based |
| 7626 |
retention. Also permission to enable event and non-event-based |
| 7627 |
retention. A server MAY behave such that setting |
| 7628 |
ACE4_WRITE_ATTRIBUTES allows ACE4_WRITE_RETENTION. |
| 7629 |
|
| 7630 |
ACE4_WRITE_RETENTION_HOLD |
| 7631 |
|
| 7632 |
Operation(s) affected: |
| 7633 |
|
| 7634 |
SETATTR of retention_hold. |
| 7635 |
|
| 7636 |
Discussion: |
| 7637 |
|
| 7638 |
Permission to modify the administration retention holds. A |
| 7639 |
server MAY map ACE4_WRITE_ATTRIBUTES to |
| 7640 |
ACE_WRITE_RETENTION_HOLD. |
| 7641 |
|
| 7642 |
ACE4_DELETE |
| 7643 |
|
| 7644 |
Operation(s) affected: |
| 7645 |
|
| 7646 |
REMOVE |
| 7647 |
|
| 7648 |
Discussion: |
| 7649 |
|
| 7650 |
Permission to delete the file or directory. See |
| 7651 |
<a href="#section-6.2.1.3.2">Section 6.2.1.3.2</a> for information on ACE4_DELETE and |
| 7652 |
ACE4_DELETE_CHILD interact. |
| 7653 |
|
| 7654 |
ACE4_READ_ACL |
| 7655 |
|
| 7656 |
Operation(s) affected: |
| 7657 |
|
| 7658 |
GETATTR of acl, dacl, or sacl |
| 7659 |
|
| 7660 |
NVERIFY |
| 7661 |
|
| 7662 |
VERIFY |
| 7663 |
|
| 7664 |
|
| 7665 |
|
| 7666 |
|
| 7667 |
|
| 7668 |
<span class="grey">Shepler, et al. Standards Track [Page 137]</span></pre> |
| 7669 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-138" ></span> |
| 7670 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7671 |
|
| 7672 |
|
| 7673 |
Discussion: |
| 7674 |
|
| 7675 |
Permission to read the ACL. |
| 7676 |
|
| 7677 |
ACE4_WRITE_ACL |
| 7678 |
|
| 7679 |
Operation(s) affected: |
| 7680 |
|
| 7681 |
SETATTR of acl and mode |
| 7682 |
|
| 7683 |
Discussion: |
| 7684 |
|
| 7685 |
Permission to write the acl and mode attributes. |
| 7686 |
|
| 7687 |
ACE4_WRITE_OWNER |
| 7688 |
|
| 7689 |
Operation(s) affected: |
| 7690 |
|
| 7691 |
SETATTR of owner and owner_group |
| 7692 |
|
| 7693 |
Discussion: |
| 7694 |
|
| 7695 |
Permission to write the owner and owner_group attributes. On |
| 7696 |
UNIX systems, this is the ability to execute chown() and |
| 7697 |
chgrp(). |
| 7698 |
|
| 7699 |
ACE4_SYNCHRONIZE |
| 7700 |
|
| 7701 |
Operation(s) affected: |
| 7702 |
|
| 7703 |
NONE |
| 7704 |
|
| 7705 |
Discussion: |
| 7706 |
|
| 7707 |
Permission to use the file object as a synchronization |
| 7708 |
primitive for interprocess communication. This permission is |
| 7709 |
not enforced or interpreted by the NFSv4.1 server on behalf of |
| 7710 |
the client. |
| 7711 |
|
| 7712 |
Typically, the ACE4_SYNCHRONIZE permission is only meaningful |
| 7713 |
on local file systems, i.e., file systems not accessed via |
| 7714 |
NFSv4.1. The reason that the permission bit exists is that |
| 7715 |
some operating environments, such as Windows, use |
| 7716 |
ACE4_SYNCHRONIZE. |
| 7717 |
|
| 7718 |
For example, if a client copies a file that has |
| 7719 |
ACE4_SYNCHRONIZE set from a local file system to an NFSv4.1 |
| 7720 |
server, and then later copies the file from the NFSv4.1 server |
| 7721 |
|
| 7722 |
|
| 7723 |
|
| 7724 |
<span class="grey">Shepler, et al. Standards Track [Page 138]</span></pre> |
| 7725 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-139" ></span> |
| 7726 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7727 |
|
| 7728 |
|
| 7729 |
to a local file system, it is likely that if ACE4_SYNCHRONIZE |
| 7730 |
was set in the original file, the client will want it set in |
| 7731 |
the second copy. The first copy will not have the permission |
| 7732 |
set unless the NFSv4.1 server has the means to set the |
| 7733 |
ACE4_SYNCHRONIZE bit. The second copy will not have the |
| 7734 |
permission set unless the NFSv4.1 server has the means to |
| 7735 |
retrieve the ACE4_SYNCHRONIZE bit. |
| 7736 |
|
| 7737 |
Server implementations need not provide the granularity of control |
| 7738 |
that is implied by this list of masks. For example, POSIX-based |
| 7739 |
systems might not distinguish ACE4_APPEND_DATA (the ability to append |
| 7740 |
to a file) from ACE4_WRITE_DATA (the ability to modify existing |
| 7741 |
contents); both masks would be tied to a single "write" permission |
| 7742 |
[<a href="#ref-20" title="">20</a>]. When such a server returns attributes to the client, it would |
| 7743 |
show both ACE4_APPEND_DATA and ACE4_WRITE_DATA if and only if the |
| 7744 |
write permission is enabled. |
| 7745 |
|
| 7746 |
If a server receives a SETATTR request that it cannot accurately |
| 7747 |
implement, it should err in the direction of more restricted access, |
| 7748 |
except in the previously discussed cases of execute and read. For |
| 7749 |
example, suppose a server cannot distinguish overwriting data from |
| 7750 |
appending new data, as described in the previous paragraph. If a |
| 7751 |
client submits an ALLOW ACE where ACE4_APPEND_DATA is set but |
| 7752 |
ACE4_WRITE_DATA is not (or vice versa), the server should either turn |
| 7753 |
off ACE4_APPEND_DATA or reject the request with NFS4ERR_ATTRNOTSUPP. |
| 7754 |
|
| 7755 |
<span class="h6"><a class="selflink" id="section-6.2.1.3.2" href="#section-6.2.1.3.2">6.2.1.3.2</a>. ACE4_DELETE vs. ACE4_DELETE_CHILD</span> |
| 7756 |
|
| 7757 |
Two access mask bits govern the ability to delete a directory entry: |
| 7758 |
ACE4_DELETE on the object itself (the "target") and ACE4_DELETE_CHILD |
| 7759 |
on the containing directory (the "parent"). |
| 7760 |
|
| 7761 |
Many systems also take the "sticky bit" (MODE4_SVTX) on a directory |
| 7762 |
to allow unlink only to a user that owns either the target or the |
| 7763 |
parent; on some such systems the decision also depends on whether the |
| 7764 |
target is writable. |
| 7765 |
|
| 7766 |
Servers SHOULD allow unlink if either ACE4_DELETE is permitted on the |
| 7767 |
target, or ACE4_DELETE_CHILD is permitted on the parent. (Note that |
| 7768 |
this is true even if the parent or target explicitly denies one of |
| 7769 |
these permissions.) |
| 7770 |
|
| 7771 |
If the ACLs in question neither explicitly ALLOW nor DENY either of |
| 7772 |
the above, and if MODE4_SVTX is not set on the parent, then the |
| 7773 |
server SHOULD allow the removal if and only if ACE4_ADD_FILE is |
| 7774 |
permitted. In the case where MODE4_SVTX is set, the server may also |
| 7775 |
require the remover to own either the parent or the target, or may |
| 7776 |
require the target to be writable. |
| 7777 |
|
| 7778 |
|
| 7779 |
|
| 7780 |
<span class="grey">Shepler, et al. Standards Track [Page 139]</span></pre> |
| 7781 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-140" ></span> |
| 7782 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7783 |
|
| 7784 |
|
| 7785 |
This allows servers to support something close to traditional UNIX- |
| 7786 |
like semantics, with ACE4_ADD_FILE taking the place of the write bit. |
| 7787 |
|
| 7788 |
<span class="h5"><a class="selflink" id="section-6.2.1.4" href="#section-6.2.1.4">6.2.1.4</a>. ACE flag</span> |
| 7789 |
|
| 7790 |
The bitmask constants used for the flag field are as follows: |
| 7791 |
|
| 7792 |
const ACE4_FILE_INHERIT_ACE = 0x00000001; |
| 7793 |
const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; |
| 7794 |
const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; |
| 7795 |
const ACE4_INHERIT_ONLY_ACE = 0x00000008; |
| 7796 |
const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; |
| 7797 |
const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; |
| 7798 |
const ACE4_IDENTIFIER_GROUP = 0x00000040; |
| 7799 |
const ACE4_INHERITED_ACE = 0x00000080; |
| 7800 |
|
| 7801 |
A server need not support any of these flags. If the server supports |
| 7802 |
flags that are similar to, but not exactly the same as, these flags, |
| 7803 |
the implementation may define a mapping between the protocol-defined |
| 7804 |
flags and the implementation-defined flags. |
| 7805 |
|
| 7806 |
For example, suppose a client tries to set an ACE with |
| 7807 |
ACE4_FILE_INHERIT_ACE set but not ACE4_DIRECTORY_INHERIT_ACE. If the |
| 7808 |
server does not support any form of ACL inheritance, the server |
| 7809 |
should reject the request with NFS4ERR_ATTRNOTSUPP. If the server |
| 7810 |
supports a single "inherit ACE" flag that applies to both files and |
| 7811 |
directories, the server may reject the request (i.e., requiring the |
| 7812 |
client to set both the file and directory inheritance flags). The |
| 7813 |
server may also accept the request and silently turn on the |
| 7814 |
ACE4_DIRECTORY_INHERIT_ACE flag. |
| 7815 |
|
| 7816 |
<span class="h6"><a class="selflink" id="section-6.2.1.4.1" href="#section-6.2.1.4.1">6.2.1.4.1</a>. Discussion of Flag Bits</span> |
| 7817 |
|
| 7818 |
ACE4_FILE_INHERIT_ACE |
| 7819 |
Any non-directory file in any sub-directory will get this ACE |
| 7820 |
inherited. |
| 7821 |
|
| 7822 |
ACE4_DIRECTORY_INHERIT_ACE |
| 7823 |
Can be placed on a directory and indicates that this ACE should be |
| 7824 |
added to each new directory created. |
| 7825 |
If this flag is set in an ACE in an ACL attribute to be set on a |
| 7826 |
non-directory file system object, the operation attempting to set |
| 7827 |
the ACL SHOULD fail with NFS4ERR_ATTRNOTSUPP. |
| 7828 |
|
| 7829 |
ACE4_NO_PROPAGATE_INHERIT_ACE |
| 7830 |
Can be placed on a directory. This flag tells the server that |
| 7831 |
inheritance of this ACE should stop at newly created child |
| 7832 |
directories. |
| 7833 |
|
| 7834 |
|
| 7835 |
|
| 7836 |
<span class="grey">Shepler, et al. Standards Track [Page 140]</span></pre> |
| 7837 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-141" ></span> |
| 7838 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7839 |
|
| 7840 |
|
| 7841 |
ACE4_INHERIT_ONLY_ACE |
| 7842 |
Can be placed on a directory but does not apply to the directory; |
| 7843 |
ALLOW and DENY ACEs with this bit set do not affect access to the |
| 7844 |
directory, and AUDIT and ALARM ACEs with this bit set do not |
| 7845 |
trigger log or alarm events. Such ACEs only take effect once they |
| 7846 |
are applied (with this bit cleared) to newly created files and |
| 7847 |
directories as specified by the ACE4_FILE_INHERIT_ACE and |
| 7848 |
ACE4_DIRECTORY_INHERIT_ACE flags. |
| 7849 |
|
| 7850 |
If this flag is present on an ACE, but neither |
| 7851 |
ACE4_DIRECTORY_INHERIT_ACE nor ACE4_FILE_INHERIT_ACE is present, |
| 7852 |
then an operation attempting to set such an attribute SHOULD fail |
| 7853 |
with NFS4ERR_ATTRNOTSUPP. |
| 7854 |
|
| 7855 |
ACE4_SUCCESSFUL_ACCESS_ACE_FLAG |
| 7856 |
|
| 7857 |
ACE4_FAILED_ACCESS_ACE_FLAG |
| 7858 |
The ACE4_SUCCESSFUL_ACCESS_ACE_FLAG (SUCCESS) and |
| 7859 |
ACE4_FAILED_ACCESS_ACE_FLAG (FAILED) flag bits may be set only on |
| 7860 |
ACE4_SYSTEM_AUDIT_ACE_TYPE (AUDIT) and ACE4_SYSTEM_ALARM_ACE_TYPE |
| 7861 |
(ALARM) ACE types. If during the processing of the file's ACL, |
| 7862 |
the server encounters an AUDIT or ALARM ACE that matches the |
| 7863 |
principal attempting the OPEN, the server notes that fact, and the |
| 7864 |
presence, if any, of the SUCCESS and FAILED flags encountered in |
| 7865 |
the AUDIT or ALARM ACE. Once the server completes the ACL |
| 7866 |
processing, it then notes if the operation succeeded or failed. |
| 7867 |
If the operation succeeded, and if the SUCCESS flag was set for a |
| 7868 |
matching AUDIT or ALARM ACE, then the appropriate AUDIT or ALARM |
| 7869 |
event occurs. If the operation failed, and if the FAILED flag was |
| 7870 |
set for the matching AUDIT or ALARM ACE, then the appropriate |
| 7871 |
AUDIT or ALARM event occurs. Either or both of the SUCCESS or |
| 7872 |
FAILED can be set, but if neither is set, the AUDIT or ALARM ACE |
| 7873 |
is not useful. |
| 7874 |
|
| 7875 |
The previously described processing applies to ACCESS operations |
| 7876 |
even when they return NFS4_OK. For the purposes of AUDIT and |
| 7877 |
ALARM, we consider an ACCESS operation to be a "failure" if it |
| 7878 |
fails to return a bit that was requested and supported. |
| 7879 |
|
| 7880 |
ACE4_IDENTIFIER_GROUP |
| 7881 |
Indicates that the "who" refers to a GROUP as defined under UNIX |
| 7882 |
or a GROUP ACCOUNT as defined under Windows. Clients and servers |
| 7883 |
MUST ignore the ACE4_IDENTIFIER_GROUP flag on ACEs with a who |
| 7884 |
value equal to one of the special identifiers outlined in |
| 7885 |
<a href="#section-6.2.1.5">Section 6.2.1.5</a>. |
| 7886 |
|
| 7887 |
|
| 7888 |
|
| 7889 |
|
| 7890 |
|
| 7891 |
|
| 7892 |
<span class="grey">Shepler, et al. Standards Track [Page 141]</span></pre> |
| 7893 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-142" ></span> |
| 7894 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7895 |
|
| 7896 |
|
| 7897 |
ACE4_INHERITED_ACE |
| 7898 |
Indicates that this ACE is inherited from a parent directory. A |
| 7899 |
server that supports automatic inheritance will place this flag on |
| 7900 |
any ACEs inherited from the parent directory when creating a new |
| 7901 |
object. Client applications will use this to perform automatic |
| 7902 |
inheritance. Clients and servers MUST clear this bit in the acl |
| 7903 |
attribute; it may only be used in the dacl and sacl attributes. |
| 7904 |
|
| 7905 |
<span class="h5"><a class="selflink" id="section-6.2.1.5" href="#section-6.2.1.5">6.2.1.5</a>. ACE Who</span> |
| 7906 |
|
| 7907 |
The "who" field of an ACE is an identifier that specifies the |
| 7908 |
principal or principals to whom the ACE applies. It may refer to a |
| 7909 |
user or a group, with the flag bit ACE4_IDENTIFIER_GROUP specifying |
| 7910 |
which. |
| 7911 |
|
| 7912 |
There are several special identifiers that need to be understood |
| 7913 |
universally, rather than in the context of a particular DNS domain. |
| 7914 |
Some of these identifiers cannot be understood when an NFS client |
| 7915 |
accesses the server, but have meaning when a local process accesses |
| 7916 |
the file. The ability to display and modify these permissions is |
| 7917 |
permitted over NFS, even if none of the access methods on the server |
| 7918 |
understands the identifiers. |
| 7919 |
|
| 7920 |
+---------------+--------------------------------------------------+ |
| 7921 |
| Who | Description | |
| 7922 |
+---------------+--------------------------------------------------+ |
| 7923 |
| OWNER | The owner of the file. | |
| 7924 |
| GROUP | The group associated with the file. | |
| 7925 |
| EVERYONE | The world, including the owner and owning group. | |
| 7926 |
| INTERACTIVE | Accessed from an interactive terminal. | |
| 7927 |
| NETWORK | Accessed via the network. | |
| 7928 |
| DIALUP | Accessed as a dialup user to the server. | |
| 7929 |
| BATCH | Accessed from a batch job. | |
| 7930 |
| ANONYMOUS | Accessed without any authentication. | |
| 7931 |
| AUTHENTICATED | Any authenticated user (opposite of ANONYMOUS). | |
| 7932 |
| SERVICE | Access from a system service. | |
| 7933 |
+---------------+--------------------------------------------------+ |
| 7934 |
|
| 7935 |
Table 4 |
| 7936 |
|
| 7937 |
To avoid conflict, these special identifiers are distinguished by an |
| 7938 |
appended "@" and should appear in the form "xxxx@" (with no domain |
| 7939 |
name after the "@"), for example, ANONYMOUS@. |
| 7940 |
|
| 7941 |
The ACE4_IDENTIFIER_GROUP flag MUST be ignored on entries with these |
| 7942 |
special identifiers. When encoding entries with these special |
| 7943 |
identifiers, the ACE4_IDENTIFIER_GROUP flag SHOULD be set to zero. |
| 7944 |
|
| 7945 |
|
| 7946 |
|
| 7947 |
|
| 7948 |
<span class="grey">Shepler, et al. Standards Track [Page 142]</span></pre> |
| 7949 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-143" ></span> |
| 7950 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 7951 |
|
| 7952 |
|
| 7953 |
<span class="h6"><a class="selflink" id="section-6.2.1.5.1" href="#section-6.2.1.5.1">6.2.1.5.1</a>. Discussion of EVERYONE@</span> |
| 7954 |
|
| 7955 |
It is important to note that "EVERYONE@" is not equivalent to the |
| 7956 |
UNIX "other" entity. This is because, by definition, UNIX "other" |
| 7957 |
does not include the owner or owning group of a file. "EVERYONE@" |
| 7958 |
means literally everyone, including the owner or owning group. |
| 7959 |
|
| 7960 |
<span class="h4"><a class="selflink" id="section-6.2.2" href="#section-6.2.2">6.2.2</a>. Attribute 58: dacl</span> |
| 7961 |
|
| 7962 |
The dacl attribute is like the acl attribute, but dacl allows just |
| 7963 |
ALLOW and DENY ACEs. The dacl attribute supports automatic |
| 7964 |
inheritance (see <a href="#section-6.4.3.2">Section 6.4.3.2</a>). |
| 7965 |
|
| 7966 |
<span class="h4"><a class="selflink" id="section-6.2.3" href="#section-6.2.3">6.2.3</a>. Attribute 59: sacl</span> |
| 7967 |
|
| 7968 |
The sacl attribute is like the acl attribute, but sacl allows just |
| 7969 |
AUDIT and ALARM ACEs. The sacl attribute supports automatic |
| 7970 |
inheritance (see <a href="#section-6.4.3.2">Section 6.4.3.2</a>). |
| 7971 |
|
| 7972 |
<span class="h4"><a class="selflink" id="section-6.2.4" href="#section-6.2.4">6.2.4</a>. Attribute 33: mode</span> |
| 7973 |
|
| 7974 |
The NFSv4.1 mode attribute is based on the UNIX mode bits. The |
| 7975 |
following bits are defined: |
| 7976 |
|
| 7977 |
const MODE4_SUID = 0x800; /* set user id on execution */ |
| 7978 |
const MODE4_SGID = 0x400; /* set group id on execution */ |
| 7979 |
const MODE4_SVTX = 0x200; /* save text even after use */ |
| 7980 |
const MODE4_RUSR = 0x100; /* read permission: owner */ |
| 7981 |
const MODE4_WUSR = 0x080; /* write permission: owner */ |
| 7982 |
const MODE4_XUSR = 0x040; /* execute permission: owner */ |
| 7983 |
const MODE4_RGRP = 0x020; /* read permission: group */ |
| 7984 |
const MODE4_WGRP = 0x010; /* write permission: group */ |
| 7985 |
const MODE4_XGRP = 0x008; /* execute permission: group */ |
| 7986 |
const MODE4_ROTH = 0x004; /* read permission: other */ |
| 7987 |
const MODE4_WOTH = 0x002; /* write permission: other */ |
| 7988 |
const MODE4_XOTH = 0x001; /* execute permission: other */ |
| 7989 |
|
| 7990 |
Bits MODE4_RUSR, MODE4_WUSR, and MODE4_XUSR apply to the principal |
| 7991 |
identified in the owner attribute. Bits MODE4_RGRP, MODE4_WGRP, and |
| 7992 |
MODE4_XGRP apply to principals identified in the owner_group |
| 7993 |
attribute but who are not identified in the owner attribute. Bits |
| 7994 |
MODE4_ROTH, MODE4_WOTH, and MODE4_XOTH apply to any principal that |
| 7995 |
does not match that in the owner attribute and does not have a group |
| 7996 |
matching that of the owner_group attribute. |
| 7997 |
|
| 7998 |
|
| 7999 |
|
| 8000 |
|
| 8001 |
|
| 8002 |
|
| 8003 |
|
| 8004 |
<span class="grey">Shepler, et al. Standards Track [Page 143]</span></pre> |
| 8005 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-144" ></span> |
| 8006 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8007 |
|
| 8008 |
|
| 8009 |
Bits within a mode other than those specified above are not defined |
| 8010 |
by this protocol. A server MUST NOT return bits other than those |
| 8011 |
defined above in a GETATTR or READDIR operation, and it MUST return |
| 8012 |
NFS4ERR_INVAL if bits other than those defined above are set in a |
| 8013 |
SETATTR, CREATE, OPEN, VERIFY, or NVERIFY operation. |
| 8014 |
|
| 8015 |
<span class="h4"><a class="selflink" id="section-6.2.5" href="#section-6.2.5">6.2.5</a>. Attribute 74: mode_set_masked</span> |
| 8016 |
|
| 8017 |
The mode_set_masked attribute is a write-only attribute that allows |
| 8018 |
individual bits in the mode attribute to be set or reset, without |
| 8019 |
changing others. It allows, for example, the bits MODE4_SUID, |
| 8020 |
MODE4_SGID, and MODE4_SVTX to be modified while leaving unmodified |
| 8021 |
any of the nine low-order mode bits devoted to permissions. |
| 8022 |
|
| 8023 |
In such instances that the nine low-order bits are left unmodified, |
| 8024 |
then neither the acl nor the dacl attribute should be automatically |
| 8025 |
modified as discussed in <a href="#section-6.4.1">Section 6.4.1</a>. |
| 8026 |
|
| 8027 |
The mode_set_masked attribute consists of two words, each in the form |
| 8028 |
of a mode4. The first consists of the value to be applied to the |
| 8029 |
current mode value and the second is a mask. Only bits set to one in |
| 8030 |
the mask word are changed (set or reset) in the file's mode. All |
| 8031 |
other bits in the mode remain unchanged. Bits in the first word that |
| 8032 |
correspond to bits that are zero in the mask are ignored, except that |
| 8033 |
undefined bits are checked for validity and can result in |
| 8034 |
NFS4ERR_INVAL as described below. |
| 8035 |
|
| 8036 |
The mode_set_masked attribute is only valid in a SETATTR operation. |
| 8037 |
If it is used in a CREATE or OPEN operation, the server MUST return |
| 8038 |
NFS4ERR_INVAL. |
| 8039 |
|
| 8040 |
Bits not defined as valid in the mode attribute are not valid in |
| 8041 |
either word of the mode_set_masked attribute. The server MUST return |
| 8042 |
NFS4ERR_INVAL if any such bits are set to one in a SETATTR. If the |
| 8043 |
mode and mode_set_masked attributes are both specified in the same |
| 8044 |
SETATTR, the server MUST also return NFS4ERR_INVAL. |
| 8045 |
|
| 8046 |
<span class="h3"><a class="selflink" id="section-6.3" href="#section-6.3">6.3</a>. Common Methods</span> |
| 8047 |
|
| 8048 |
The requirements in this section will be referred to in future |
| 8049 |
sections, especially <a href="#section-6.4">Section 6.4</a>. |
| 8050 |
|
| 8051 |
|
| 8052 |
|
| 8053 |
|
| 8054 |
|
| 8055 |
|
| 8056 |
|
| 8057 |
|
| 8058 |
|
| 8059 |
|
| 8060 |
<span class="grey">Shepler, et al. Standards Track [Page 144]</span></pre> |
| 8061 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-145" ></span> |
| 8062 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8063 |
|
| 8064 |
|
| 8065 |
<span class="h4"><a class="selflink" id="section-6.3.1" href="#section-6.3.1">6.3.1</a>. Interpreting an ACL</span> |
| 8066 |
|
| 8067 |
<span class="h5"><a class="selflink" id="section-6.3.1.1" href="#section-6.3.1.1">6.3.1.1</a>. Server Considerations</span> |
| 8068 |
|
| 8069 |
The server uses the algorithm described in <a href="#section-6.2.1">Section 6.2.1</a> to determine |
| 8070 |
whether an ACL allows access to an object. However, the ACL might |
| 8071 |
not be the sole determiner of access. For example: |
| 8072 |
|
| 8073 |
o In the case of a file system exported as read-only, the server may |
| 8074 |
deny write access even though an object's ACL grants it. |
| 8075 |
|
| 8076 |
o Server implementations MAY grant ACE4_WRITE_ACL and ACE4_READ_ACL |
| 8077 |
permissions to prevent a situation from arising in which there is |
| 8078 |
no valid way to ever modify the ACL. |
| 8079 |
|
| 8080 |
o All servers will allow a user the ability to read the data of the |
| 8081 |
file when only the execute permission is granted (i.e., if the ACL |
| 8082 |
denies the user the ACE4_READ_DATA access and allows the user |
| 8083 |
ACE4_EXECUTE, the server will allow the user to read the data of |
| 8084 |
the file). |
| 8085 |
|
| 8086 |
o Many servers have the notion of owner-override in which the owner |
| 8087 |
of the object is allowed to override accesses that are denied by |
| 8088 |
the ACL. This may be helpful, for example, to allow users |
| 8089 |
continued access to open files on which the permissions have |
| 8090 |
changed. |
| 8091 |
|
| 8092 |
o Many servers have the notion of a "superuser" that has privileges |
| 8093 |
beyond an ordinary user. The superuser may be able to read or |
| 8094 |
write data or metadata in ways that would not be permitted by the |
| 8095 |
ACL. |
| 8096 |
|
| 8097 |
o A retention attribute might also block access otherwise allowed by |
| 8098 |
ACLs (see <a href="#section-5.13">Section 5.13</a>). |
| 8099 |
|
| 8100 |
<span class="h5"><a class="selflink" id="section-6.3.1.2" href="#section-6.3.1.2">6.3.1.2</a>. Client Considerations</span> |
| 8101 |
|
| 8102 |
Clients SHOULD NOT do their own access checks based on their |
| 8103 |
interpretation of the ACL, but rather use the OPEN and ACCESS |
| 8104 |
operations to do access checks. This allows the client to act on the |
| 8105 |
results of having the server determine whether or not access should |
| 8106 |
be granted based on its interpretation of the ACL. |
| 8107 |
|
| 8108 |
Clients must be aware of situations in which an object's ACL will |
| 8109 |
define a certain access even though the server will not enforce it. |
| 8110 |
In general, but especially in these situations, the client needs to |
| 8111 |
do its part in the enforcement of access as defined by the ACL. To |
| 8112 |
do this, the client MAY send the appropriate ACCESS operation prior |
| 8113 |
|
| 8114 |
|
| 8115 |
|
| 8116 |
<span class="grey">Shepler, et al. Standards Track [Page 145]</span></pre> |
| 8117 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-146" ></span> |
| 8118 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8119 |
|
| 8120 |
|
| 8121 |
to servicing the request of the user or application in order to |
| 8122 |
determine whether the user or application should be granted the |
| 8123 |
access requested. For examples in which the ACL may define accesses |
| 8124 |
that the server doesn't enforce, see <a href="#section-6.3.1.1">Section 6.3.1.1</a>. |
| 8125 |
|
| 8126 |
<span class="h4"><a class="selflink" id="section-6.3.2" href="#section-6.3.2">6.3.2</a>. Computing a Mode Attribute from an ACL</span> |
| 8127 |
|
| 8128 |
The following method can be used to calculate the MODE4_R*, MODE4_W*, |
| 8129 |
and MODE4_X* bits of a mode attribute, based upon an ACL. |
| 8130 |
|
| 8131 |
First, for each of the special identifiers OWNER@, GROUP@, and |
| 8132 |
EVERYONE@, evaluate the ACL in order, considering only ALLOW and DENY |
| 8133 |
ACEs for the identifier EVERYONE@ and for the identifier under |
| 8134 |
consideration. The result of the evaluation will be an NFSv4 ACL |
| 8135 |
mask showing exactly which bits are permitted to that identifier. |
| 8136 |
|
| 8137 |
Then translate the calculated mask for OWNER@, GROUP@, and EVERYONE@ |
| 8138 |
into mode bits for, respectively, the user, group, and other, as |
| 8139 |
follows: |
| 8140 |
|
| 8141 |
1. Set the read bit (MODE4_RUSR, MODE4_RGRP, or MODE4_ROTH) if and |
| 8142 |
only if ACE4_READ_DATA is set in the corresponding mask. |
| 8143 |
|
| 8144 |
2. Set the write bit (MODE4_WUSR, MODE4_WGRP, or MODE4_WOTH) if and |
| 8145 |
only if ACE4_WRITE_DATA and ACE4_APPEND_DATA are both set in the |
| 8146 |
corresponding mask. |
| 8147 |
|
| 8148 |
3. Set the execute bit (MODE4_XUSR, MODE4_XGRP, or MODE4_XOTH), if |
| 8149 |
and only if ACE4_EXECUTE is set in the corresponding mask. |
| 8150 |
|
| 8151 |
<span class="h5"><a class="selflink" id="section-6.3.2.1" href="#section-6.3.2.1">6.3.2.1</a>. Discussion</span> |
| 8152 |
|
| 8153 |
Some server implementations also add bits permitted to named users |
| 8154 |
and groups to the group bits (MODE4_RGRP, MODE4_WGRP, and |
| 8155 |
MODE4_XGRP). |
| 8156 |
|
| 8157 |
Implementations are discouraged from doing this, because it has been |
| 8158 |
found to cause confusion for users who see members of a file's group |
| 8159 |
denied access that the mode bits appear to allow. (The presence of |
| 8160 |
DENY ACEs may also lead to such behavior, but DENY ACEs are expected |
| 8161 |
to be more rarely used.) |
| 8162 |
|
| 8163 |
The same user confusion seen when fetching the mode also results if |
| 8164 |
setting the mode does not effectively control permissions for the |
| 8165 |
owner, group, and other users; this motivates some of the |
| 8166 |
requirements that follow. |
| 8167 |
|
| 8168 |
|
| 8169 |
|
| 8170 |
|
| 8171 |
|
| 8172 |
<span class="grey">Shepler, et al. Standards Track [Page 146]</span></pre> |
| 8173 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-147" ></span> |
| 8174 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8175 |
|
| 8176 |
|
| 8177 |
<span class="h3"><a class="selflink" id="section-6.4" href="#section-6.4">6.4</a>. Requirements</span> |
| 8178 |
|
| 8179 |
The server that supports both mode and ACL must take care to |
| 8180 |
synchronize the MODE4_*USR, MODE4_*GRP, and MODE4_*OTH bits with the |
| 8181 |
ACEs that have respective who fields of "OWNER@", "GROUP@", and |
| 8182 |
"EVERYONE@". This way, the client can see if semantically equivalent |
| 8183 |
access permissions exist whether the client asks for the owner, |
| 8184 |
owner_group, and mode attributes or for just the ACL. |
| 8185 |
|
| 8186 |
In this section, much is made of the methods in <a href="#section-6.3.2">Section 6.3.2</a>. Many |
| 8187 |
requirements refer to this section. But note that the methods have |
| 8188 |
behaviors specified with "SHOULD". This is intentional, to avoid |
| 8189 |
invalidating existing implementations that compute the mode according |
| 8190 |
to the withdrawn POSIX ACL draft (1003.1e draft 17), rather than by |
| 8191 |
actual permissions on owner, group, and other. |
| 8192 |
|
| 8193 |
<span class="h4"><a class="selflink" id="section-6.4.1" href="#section-6.4.1">6.4.1</a>. Setting the Mode and/or ACL Attributes</span> |
| 8194 |
|
| 8195 |
In the case where a server supports the sacl or dacl attribute, in |
| 8196 |
addition to the acl attribute, the server MUST fail a request to set |
| 8197 |
the acl attribute simultaneously with a dacl or sacl attribute. The |
| 8198 |
error to be given is NFS4ERR_ATTRNOTSUPP. |
| 8199 |
|
| 8200 |
<span class="h5"><a class="selflink" id="section-6.4.1.1" href="#section-6.4.1.1">6.4.1.1</a>. Setting Mode and not ACL</span> |
| 8201 |
|
| 8202 |
When any of the nine low-order mode bits are subject to change, |
| 8203 |
either because the mode attribute was set or because the |
| 8204 |
mode_set_masked attribute was set and the mask included one or more |
| 8205 |
bits from the nine low-order mode bits, and no ACL attribute is |
| 8206 |
explicitly set, the acl and dacl attributes must be modified in |
| 8207 |
accordance with the updated value of those bits. This must happen |
| 8208 |
even if the value of the low-order bits is the same after the mode is |
| 8209 |
set as before. |
| 8210 |
|
| 8211 |
Note that any AUDIT or ALARM ACEs (hence any ACEs in the sacl |
| 8212 |
attribute) are unaffected by changes to the mode. |
| 8213 |
|
| 8214 |
In cases in which the permissions bits are subject to change, the acl |
| 8215 |
and dacl attributes MUST be modified such that the mode computed via |
| 8216 |
the method in <a href="#section-6.3.2">Section 6.3.2</a> yields the low-order nine bits (MODE4_R*, |
| 8217 |
MODE4_W*, MODE4_X*) of the mode attribute as modified by the |
| 8218 |
attribute change. The ACL attributes SHOULD also be modified such |
| 8219 |
that: |
| 8220 |
|
| 8221 |
1. If MODE4_RGRP is not set, entities explicitly listed in the ACL |
| 8222 |
other than OWNER@ and EVERYONE@ SHOULD NOT be granted |
| 8223 |
ACE4_READ_DATA. |
| 8224 |
|
| 8225 |
|
| 8226 |
|
| 8227 |
|
| 8228 |
<span class="grey">Shepler, et al. Standards Track [Page 147]</span></pre> |
| 8229 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-148" ></span> |
| 8230 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8231 |
|
| 8232 |
|
| 8233 |
2. If MODE4_WGRP is not set, entities explicitly listed in the ACL |
| 8234 |
other than OWNER@ and EVERYONE@ SHOULD NOT be granted |
| 8235 |
ACE4_WRITE_DATA or ACE4_APPEND_DATA. |
| 8236 |
|
| 8237 |
3. If MODE4_XGRP is not set, entities explicitly listed in the ACL |
| 8238 |
other than OWNER@ and EVERYONE@ SHOULD NOT be granted |
| 8239 |
ACE4_EXECUTE. |
| 8240 |
|
| 8241 |
Access mask bits other than those listed above, appearing in ALLOW |
| 8242 |
ACEs, MAY also be disabled. |
| 8243 |
|
| 8244 |
Note that ACEs with the flag ACE4_INHERIT_ONLY_ACE set do not affect |
| 8245 |
the permissions of the ACL itself, nor do ACEs of the type AUDIT and |
| 8246 |
ALARM. As such, it is desirable to leave these ACEs unmodified when |
| 8247 |
modifying the ACL attributes. |
| 8248 |
|
| 8249 |
Also note that the requirement may be met by discarding the acl and |
| 8250 |
dacl, in favor of an ACL that represents the mode and only the mode. |
| 8251 |
This is permitted, but it is preferable for a server to preserve as |
| 8252 |
much of the ACL as possible without violating the above requirements. |
| 8253 |
Discarding the ACL makes it effectively impossible for a file created |
| 8254 |
with a mode attribute to inherit an ACL (see <a href="#section-6.4.3">Section 6.4.3</a>). |
| 8255 |
|
| 8256 |
<span class="h5"><a class="selflink" id="section-6.4.1.2" href="#section-6.4.1.2">6.4.1.2</a>. Setting ACL and Not Mode</span> |
| 8257 |
|
| 8258 |
When setting the acl or dacl and not setting the mode or |
| 8259 |
mode_set_masked attributes, the permission bits of the mode need to |
| 8260 |
be derived from the ACL. In this case, the ACL attribute SHOULD be |
| 8261 |
set as given. The nine low-order bits of the mode attribute |
| 8262 |
(MODE4_R*, MODE4_W*, MODE4_X*) MUST be modified to match the result |
| 8263 |
of the method in <a href="#section-6.3.2">Section 6.3.2</a>. The three high-order bits of the |
| 8264 |
mode (MODE4_SUID, MODE4_SGID, MODE4_SVTX) SHOULD remain unchanged. |
| 8265 |
|
| 8266 |
<span class="h5"><a class="selflink" id="section-6.4.1.3" href="#section-6.4.1.3">6.4.1.3</a>. Setting Both ACL and Mode</span> |
| 8267 |
|
| 8268 |
When setting both the mode (includes use of either the mode attribute |
| 8269 |
or the mode_set_masked attribute) and the acl or dacl attributes in |
| 8270 |
the same operation, the attributes MUST be applied in this order: |
| 8271 |
mode (or mode_set_masked), then ACL. The mode-related attribute is |
| 8272 |
set as given, then the ACL attribute is set as given, possibly |
| 8273 |
changing the final mode, as described above in <a href="#section-6.4.1.2">Section 6.4.1.2</a>. |
| 8274 |
|
| 8275 |
<span class="h4"><a class="selflink" id="section-6.4.2" href="#section-6.4.2">6.4.2</a>. Retrieving the Mode and/or ACL Attributes</span> |
| 8276 |
|
| 8277 |
This section applies only to servers that support both the mode and |
| 8278 |
ACL attributes. |
| 8279 |
|
| 8280 |
|
| 8281 |
|
| 8282 |
|
| 8283 |
|
| 8284 |
<span class="grey">Shepler, et al. Standards Track [Page 148]</span></pre> |
| 8285 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-149" ></span> |
| 8286 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8287 |
|
| 8288 |
|
| 8289 |
Some server implementations may have a concept of "objects without |
| 8290 |
ACLs", meaning that all permissions are granted and denied according |
| 8291 |
to the mode attribute and that no ACL attribute is stored for that |
| 8292 |
object. If an ACL attribute is requested of such a server, the |
| 8293 |
server SHOULD return an ACL that does not conflict with the mode; |
| 8294 |
that is to say, the ACL returned SHOULD represent the nine low-order |
| 8295 |
bits of the mode attribute (MODE4_R*, MODE4_W*, MODE4_X*) as |
| 8296 |
described in <a href="#section-6.3.2">Section 6.3.2</a>. |
| 8297 |
|
| 8298 |
For other server implementations, the ACL attribute is always present |
| 8299 |
for every object. Such servers SHOULD store at least the three high- |
| 8300 |
order bits of the mode attribute (MODE4_SUID, MODE4_SGID, |
| 8301 |
MODE4_SVTX). The server SHOULD return a mode attribute if one is |
| 8302 |
requested, and the low-order nine bits of the mode (MODE4_R*, |
| 8303 |
MODE4_W*, MODE4_X*) MUST match the result of applying the method in |
| 8304 |
<a href="#section-6.3.2">Section 6.3.2</a> to the ACL attribute. |
| 8305 |
|
| 8306 |
<span class="h4"><a class="selflink" id="section-6.4.3" href="#section-6.4.3">6.4.3</a>. Creating New Objects</span> |
| 8307 |
|
| 8308 |
If a server supports any ACL attributes, it may use the ACL |
| 8309 |
attributes on the parent directory to compute an initial ACL |
| 8310 |
attribute for a newly created object. This will be referred to as |
| 8311 |
the inherited ACL within this section. The act of adding one or more |
| 8312 |
ACEs to the inherited ACL that are based upon ACEs in the parent |
| 8313 |
directory's ACL will be referred to as inheriting an ACE within this |
| 8314 |
section. |
| 8315 |
|
| 8316 |
Implementors should standardize what the behavior of CREATE and OPEN |
| 8317 |
must be depending on the presence or absence of the mode and ACL |
| 8318 |
attributes. |
| 8319 |
|
| 8320 |
1. If just the mode is given in the call: |
| 8321 |
|
| 8322 |
In this case, inheritance SHOULD take place, but the mode MUST be |
| 8323 |
applied to the inherited ACL as described in <a href="#section-6.4.1.1">Section 6.4.1.1</a>, |
| 8324 |
thereby modifying the ACL. |
| 8325 |
|
| 8326 |
2. If just the ACL is given in the call: |
| 8327 |
|
| 8328 |
In this case, inheritance SHOULD NOT take place, and the ACL as |
| 8329 |
defined in the CREATE or OPEN will be set without modification, |
| 8330 |
and the mode modified as in <a href="#section-6.4.1.2">Section 6.4.1.2</a>. |
| 8331 |
|
| 8332 |
3. If both mode and ACL are given in the call: |
| 8333 |
|
| 8334 |
In this case, inheritance SHOULD NOT take place, and both |
| 8335 |
attributes will be set as described in <a href="#section-6.4.1.3">Section 6.4.1.3</a>. |
| 8336 |
|
| 8337 |
|
| 8338 |
|
| 8339 |
|
| 8340 |
<span class="grey">Shepler, et al. Standards Track [Page 149]</span></pre> |
| 8341 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-150" ></span> |
| 8342 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8343 |
|
| 8344 |
|
| 8345 |
4. If neither mode nor ACL is given in the call: |
| 8346 |
|
| 8347 |
In the case where an object is being created without any initial |
| 8348 |
attributes at all, e.g., an OPEN operation with an opentype4 of |
| 8349 |
OPEN4_CREATE and a createmode4 of EXCLUSIVE4, inheritance SHOULD |
| 8350 |
NOT take place (note that EXCLUSIVE4_1 is a better choice of |
| 8351 |
createmode4, since it does permit initial attributes). Instead, |
| 8352 |
the server SHOULD set permissions to deny all access to the newly |
| 8353 |
created object. It is expected that the appropriate client will |
| 8354 |
set the desired attributes in a subsequent SETATTR operation, and |
| 8355 |
the server SHOULD allow that operation to succeed, regardless of |
| 8356 |
what permissions the object is created with. For example, an |
| 8357 |
empty ACL denies all permissions, but the server should allow the |
| 8358 |
owner's SETATTR to succeed even though WRITE_ACL is implicitly |
| 8359 |
denied. |
| 8360 |
|
| 8361 |
In other cases, inheritance SHOULD take place, and no |
| 8362 |
modifications to the ACL will happen. The mode attribute, if |
| 8363 |
supported, MUST be as computed in <a href="#section-6.3.2">Section 6.3.2</a>, with the |
| 8364 |
MODE4_SUID, MODE4_SGID, and MODE4_SVTX bits clear. If no |
| 8365 |
inheritable ACEs exist on the parent directory, the rules for |
| 8366 |
creating acl, dacl, or sacl attributes are implementation |
| 8367 |
defined. If either the dacl or sacl attribute is supported, then |
| 8368 |
the ACL4_DEFAULTED flag SHOULD be set on the newly created |
| 8369 |
attributes. |
| 8370 |
|
| 8371 |
|
| 8372 |
<span class="h5"><a class="selflink" id="section-6.4.3.1" href="#section-6.4.3.1">6.4.3.1</a>. The Inherited ACL</span> |
| 8373 |
|
| 8374 |
If the object being created is not a directory, the inherited ACL |
| 8375 |
SHOULD NOT inherit ACEs from the parent directory ACL unless the |
| 8376 |
ACE4_FILE_INHERIT_FLAG is set. |
| 8377 |
|
| 8378 |
If the object being created is a directory, the inherited ACL should |
| 8379 |
inherit all inheritable ACEs from the parent directory, that is, |
| 8380 |
those that have the ACE4_FILE_INHERIT_ACE or |
| 8381 |
ACE4_DIRECTORY_INHERIT_ACE flag set. If the inheritable ACE has |
| 8382 |
ACE4_FILE_INHERIT_ACE set but ACE4_DIRECTORY_INHERIT_ACE is clear, |
| 8383 |
the inherited ACE on the newly created directory MUST have the |
| 8384 |
ACE4_INHERIT_ONLY_ACE flag set to prevent the directory from being |
| 8385 |
affected by ACEs meant for non-directories. |
| 8386 |
|
| 8387 |
When a new directory is created, the server MAY split any inherited |
| 8388 |
ACE that is both inheritable and effective (in other words, that has |
| 8389 |
neither ACE4_INHERIT_ONLY_ACE nor ACE4_NO_PROPAGATE_INHERIT_ACE set), |
| 8390 |
into two ACEs, one with no inheritance flags and one with |
| 8391 |
ACE4_INHERIT_ONLY_ACE set. (In the case of a dacl or sacl attribute, |
| 8392 |
both of those ACEs SHOULD also have the ACE4_INHERITED_ACE flag set.) |
| 8393 |
|
| 8394 |
|
| 8395 |
|
| 8396 |
<span class="grey">Shepler, et al. Standards Track [Page 150]</span></pre> |
| 8397 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-151" ></span> |
| 8398 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8399 |
|
| 8400 |
|
| 8401 |
This makes it simpler to modify the effective permissions on the |
| 8402 |
directory without modifying the ACE that is to be inherited to the |
| 8403 |
new directory's children. |
| 8404 |
|
| 8405 |
<span class="h5"><a class="selflink" id="section-6.4.3.2" href="#section-6.4.3.2">6.4.3.2</a>. Automatic Inheritance</span> |
| 8406 |
|
| 8407 |
The acl attribute consists only of an array of ACEs, but the sacl |
| 8408 |
(<a href="#section-6.2.3">Section 6.2.3</a>) and dacl (<a href="#section-6.2.2">Section 6.2.2</a>) attributes also include an |
| 8409 |
additional flag field. |
| 8410 |
|
| 8411 |
struct nfsacl41 { |
| 8412 |
aclflag4 na41_flag; |
| 8413 |
nfsace4 na41_aces<>; |
| 8414 |
}; |
| 8415 |
|
| 8416 |
The flag field applies to the entire sacl or dacl; three flag values |
| 8417 |
are defined: |
| 8418 |
|
| 8419 |
const ACL4_AUTO_INHERIT = 0x00000001; |
| 8420 |
const ACL4_PROTECTED = 0x00000002; |
| 8421 |
const ACL4_DEFAULTED = 0x00000004; |
| 8422 |
|
| 8423 |
and all other bits must be cleared. The ACE4_INHERITED_ACE flag may |
| 8424 |
be set in the ACEs of the sacl or dacl (whereas it must always be |
| 8425 |
cleared in the acl). |
| 8426 |
|
| 8427 |
Together these features allow a server to support automatic |
| 8428 |
inheritance, which we now explain in more detail. |
| 8429 |
|
| 8430 |
Inheritable ACEs are normally inherited by child objects only at the |
| 8431 |
time that the child objects are created; later modifications to |
| 8432 |
inheritable ACEs do not result in modifications to inherited ACEs on |
| 8433 |
descendants. |
| 8434 |
|
| 8435 |
However, the dacl and sacl provide an OPTIONAL mechanism that allows |
| 8436 |
a client application to propagate changes to inheritable ACEs to an |
| 8437 |
entire directory hierarchy. |
| 8438 |
|
| 8439 |
A server that supports this performs inheritance at object creation |
| 8440 |
time in the normal way, and SHOULD set the ACE4_INHERITED_ACE flag on |
| 8441 |
any inherited ACEs as they are added to the new object. |
| 8442 |
|
| 8443 |
A client application such as an ACL editor may then propagate changes |
| 8444 |
to inheritable ACEs on a directory by recursively traversing that |
| 8445 |
directory's descendants and modifying each ACL encountered to remove |
| 8446 |
any ACEs with the ACE4_INHERITED_ACE flag and to replace them by the |
| 8447 |
new inheritable ACEs (also with the ACE4_INHERITED_ACE flag set). It |
| 8448 |
uses the existing ACE inheritance flags in the obvious way to decide |
| 8449 |
|
| 8450 |
|
| 8451 |
|
| 8452 |
<span class="grey">Shepler, et al. Standards Track [Page 151]</span></pre> |
| 8453 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-152" ></span> |
| 8454 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8455 |
|
| 8456 |
|
| 8457 |
which ACEs to propagate. (Note that it may encounter further |
| 8458 |
inheritable ACEs when descending the directory hierarchy and that |
| 8459 |
those will also need to be taken into account when propagating |
| 8460 |
inheritable ACEs to further descendants.) |
| 8461 |
|
| 8462 |
The reach of this propagation may be limited in two ways: first, |
| 8463 |
automatic inheritance is not performed from any directory ACL that |
| 8464 |
has the ACL4_AUTO_INHERIT flag cleared; and second, automatic |
| 8465 |
inheritance stops wherever an ACL with the ACL4_PROTECTED flag is |
| 8466 |
set, preventing modification of that ACL and also (if the ACL is set |
| 8467 |
on a directory) of the ACL on any of the object's descendants. |
| 8468 |
|
| 8469 |
This propagation is performed independently for the sacl and the dacl |
| 8470 |
attributes; thus, the ACL4_AUTO_INHERIT and ACL4_PROTECTED flags may |
| 8471 |
be independently set for the sacl and the dacl, and propagation of |
| 8472 |
one type of acl may continue down a hierarchy even where propagation |
| 8473 |
of the other acl has stopped. |
| 8474 |
|
| 8475 |
New objects should be created with a dacl and a sacl that both have |
| 8476 |
the ACL4_PROTECTED flag cleared and the ACL4_AUTO_INHERIT flag set to |
| 8477 |
the same value as that on, respectively, the sacl or dacl of the |
| 8478 |
parent object. |
| 8479 |
|
| 8480 |
Both the dacl and sacl attributes are RECOMMENDED, and a server may |
| 8481 |
support one without supporting the other. |
| 8482 |
|
| 8483 |
A server that supports both the old acl attribute and one or both of |
| 8484 |
the new dacl or sacl attributes must do so in such a way as to keep |
| 8485 |
all three attributes consistent with each other. Thus, the ACEs |
| 8486 |
reported in the acl attribute should be the union of the ACEs |
| 8487 |
reported in the dacl and sacl attributes, except that the |
| 8488 |
ACE4_INHERITED_ACE flag must be cleared from the ACEs in the acl. |
| 8489 |
And of course a client that queries only the acl will be unable to |
| 8490 |
determine the values of the sacl or dacl flag fields. |
| 8491 |
|
| 8492 |
When a client performs a SETATTR for the acl attribute, the server |
| 8493 |
SHOULD set the ACL4_PROTECTED flag to true on both the sacl and the |
| 8494 |
dacl. By using the acl attribute, as opposed to the dacl or sacl |
| 8495 |
attributes, the client signals that it may not understand automatic |
| 8496 |
inheritance, and thus cannot be trusted to set an ACL for which |
| 8497 |
automatic inheritance would make sense. |
| 8498 |
|
| 8499 |
When a client application queries an ACL, modifies it, and sets it |
| 8500 |
again, it should leave any ACEs marked with ACE4_INHERITED_ACE |
| 8501 |
unchanged, in their original order, at the end of the ACL. If the |
| 8502 |
application is unable to do this, it should set the ACL4_PROTECTED |
| 8503 |
|
| 8504 |
|
| 8505 |
|
| 8506 |
|
| 8507 |
|
| 8508 |
<span class="grey">Shepler, et al. Standards Track [Page 152]</span></pre> |
| 8509 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-153" ></span> |
| 8510 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8511 |
|
| 8512 |
|
| 8513 |
flag. This behavior is not enforced by servers, but violations of |
| 8514 |
this rule may lead to unexpected results when applications perform |
| 8515 |
automatic inheritance. |
| 8516 |
|
| 8517 |
If a server also supports the mode attribute, it SHOULD set the mode |
| 8518 |
in such a way that leaves inherited ACEs unchanged, in their original |
| 8519 |
order, at the end of the ACL. If it is unable to do so, it SHOULD |
| 8520 |
set the ACL4_PROTECTED flag on the file's dacl. |
| 8521 |
|
| 8522 |
Finally, in the case where the request that creates a new file or |
| 8523 |
directory does not also set permissions for that file or directory, |
| 8524 |
and there are also no ACEs to inherit from the parent's directory, |
| 8525 |
then the server's choice of ACL for the new object is implementation- |
| 8526 |
dependent. In this case, the server SHOULD set the ACL4_DEFAULTED |
| 8527 |
flag on the ACL it chooses for the new object. An application |
| 8528 |
performing automatic inheritance takes the ACL4_DEFAULTED flag as a |
| 8529 |
sign that the ACL should be completely replaced by one generated |
| 8530 |
using the automatic inheritance rules. |
| 8531 |
|
| 8532 |
<span class="h2"><a class="selflink" id="section-7" href="#section-7">7</a>. Single-Server Namespace</span> |
| 8533 |
|
| 8534 |
This section describes the NFSv4 single-server namespace. Single- |
| 8535 |
server namespaces may be presented directly to clients, or they may |
| 8536 |
be used as a basis to form larger multi-server namespaces (e.g., |
| 8537 |
site-wide or organization-wide) to be presented to clients, as |
| 8538 |
described in <a href="#section-11">Section 11</a>. |
| 8539 |
|
| 8540 |
<span class="h3"><a class="selflink" id="section-7.1" href="#section-7.1">7.1</a>. Server Exports</span> |
| 8541 |
|
| 8542 |
On a UNIX server, the namespace describes all the files reachable by |
| 8543 |
pathnames under the root directory or "/". On a Windows server, the |
| 8544 |
namespace constitutes all the files on disks named by mapped disk |
| 8545 |
letters. NFS server administrators rarely make the entire server's |
| 8546 |
file system namespace available to NFS clients. More often, portions |
| 8547 |
of the namespace are made available via an "export" feature. In |
| 8548 |
previous versions of the NFS protocol, the root filehandle for each |
| 8549 |
export is obtained through the MOUNT protocol; the client sent a |
| 8550 |
string that identified the export name within the namespace and the |
| 8551 |
server returned the root filehandle for that export. The MOUNT |
| 8552 |
protocol also provided an EXPORTS procedure that enumerated the |
| 8553 |
server's exports. |
| 8554 |
|
| 8555 |
<span class="h3"><a class="selflink" id="section-7.2" href="#section-7.2">7.2</a>. Browsing Exports</span> |
| 8556 |
|
| 8557 |
The NFSv4.1 protocol provides a root filehandle that clients can use |
| 8558 |
to obtain filehandles for the exports of a particular server, via a |
| 8559 |
series of LOOKUP operations within a COMPOUND, to traverse a path. A |
| 8560 |
common user experience is to use a graphical user interface (perhaps |
| 8561 |
|
| 8562 |
|
| 8563 |
|
| 8564 |
<span class="grey">Shepler, et al. Standards Track [Page 153]</span></pre> |
| 8565 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-154" ></span> |
| 8566 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8567 |
|
| 8568 |
|
| 8569 |
a file "Open" dialog window) to find a file via progressive browsing |
| 8570 |
through a directory tree. The client must be able to move from one |
| 8571 |
export to another export via single-component, progressive LOOKUP |
| 8572 |
operations. |
| 8573 |
|
| 8574 |
This style of browsing is not well supported by the NFSv3 protocol. |
| 8575 |
In NFSv3, the client expects all LOOKUP operations to remain within a |
| 8576 |
single server file system. For example, the device attribute will |
| 8577 |
not change. This prevents a client from taking namespace paths that |
| 8578 |
span exports. |
| 8579 |
|
| 8580 |
In the case of NFSv3, an automounter on the client can obtain a |
| 8581 |
snapshot of the server's namespace using the EXPORTS procedure of the |
| 8582 |
MOUNT protocol. If it understands the server's pathname syntax, it |
| 8583 |
can create an image of the server's namespace on the client. The |
| 8584 |
parts of the namespace that are not exported by the server are filled |
| 8585 |
in with directories that might be constructed similarly to an NFSv4.1 |
| 8586 |
"pseudo file system" (see <a href="#section-7.3">Section 7.3</a>) that allows the user to browse |
| 8587 |
from one mounted file system to another. There is a drawback to this |
| 8588 |
representation of the server's namespace on the client: it is static. |
| 8589 |
If the server administrator adds a new export, the client will be |
| 8590 |
unaware of it. |
| 8591 |
|
| 8592 |
<span class="h3"><a class="selflink" id="section-7.3" href="#section-7.3">7.3</a>. Server Pseudo File System</span> |
| 8593 |
|
| 8594 |
NFSv4.1 servers avoid this namespace inconsistency by presenting all |
| 8595 |
the exports for a given server within the framework of a single |
| 8596 |
namespace for that server. An NFSv4.1 client uses LOOKUP and READDIR |
| 8597 |
operations to browse seamlessly from one export to another. |
| 8598 |
|
| 8599 |
Where there are portions of the server namespace that are not |
| 8600 |
exported, clients require some way of traversing those portions to |
| 8601 |
reach actual exported file systems. A technique that servers may use |
| 8602 |
to provide for this is to bridge the unexported portion of the |
| 8603 |
namespace via a "pseudo file system" that provides a view of exported |
| 8604 |
directories only. A pseudo file system has a unique fsid and behaves |
| 8605 |
like a normal, read-only file system. |
| 8606 |
|
| 8607 |
Based on the construction of the server's namespace, it is possible |
| 8608 |
that multiple pseudo file systems may exist. For example, |
| 8609 |
|
| 8610 |
/a pseudo file system |
| 8611 |
/a/b real file system |
| 8612 |
/a/b/c pseudo file system |
| 8613 |
/a/b/c/d real file system |
| 8614 |
|
| 8615 |
|
| 8616 |
|
| 8617 |
|
| 8618 |
|
| 8619 |
|
| 8620 |
<span class="grey">Shepler, et al. Standards Track [Page 154]</span></pre> |
| 8621 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-155" ></span> |
| 8622 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8623 |
|
| 8624 |
|
| 8625 |
Each of the pseudo file systems is considered a separate entity and |
| 8626 |
therefore MUST have its own fsid, unique among all the fsids for that |
| 8627 |
server. |
| 8628 |
|
| 8629 |
<span class="h3"><a class="selflink" id="section-7.4" href="#section-7.4">7.4</a>. Multiple Roots</span> |
| 8630 |
|
| 8631 |
Certain operating environments are sometimes described as having |
| 8632 |
"multiple roots". In such environments, individual file systems are |
| 8633 |
commonly represented by disk or volume names. NFSv4 servers for |
| 8634 |
these platforms can construct a pseudo file system above these root |
| 8635 |
names so that disk letters or volume names are simply directory names |
| 8636 |
in the pseudo root. |
| 8637 |
|
| 8638 |
<span class="h3"><a class="selflink" id="section-7.5" href="#section-7.5">7.5</a>. Filehandle Volatility</span> |
| 8639 |
|
| 8640 |
The nature of the server's pseudo file system is that it is a logical |
| 8641 |
representation of file system(s) available from the server. |
| 8642 |
Therefore, the pseudo file system is most likely constructed |
| 8643 |
dynamically when the server is first instantiated. It is expected |
| 8644 |
that the pseudo file system may not have an on-disk counterpart from |
| 8645 |
which persistent filehandles could be constructed. Even though it is |
| 8646 |
preferable that the server provide persistent filehandles for the |
| 8647 |
pseudo file system, the NFS client should expect that pseudo file |
| 8648 |
system filehandles are volatile. This can be confirmed by checking |
| 8649 |
the associated "fh_expire_type" attribute for those filehandles in |
| 8650 |
question. If the filehandles are volatile, the NFS client must be |
| 8651 |
prepared to recover a filehandle value (e.g., with a series of LOOKUP |
| 8652 |
operations) when receiving an error of NFS4ERR_FHEXPIRED. |
| 8653 |
|
| 8654 |
Because it is quite likely that servers will implement pseudo file |
| 8655 |
systems using volatile filehandles, clients need to be prepared for |
| 8656 |
them, rather than assuming that all filehandles will be persistent. |
| 8657 |
|
| 8658 |
<span class="h3"><a class="selflink" id="section-7.6" href="#section-7.6">7.6</a>. Exported Root</span> |
| 8659 |
|
| 8660 |
If the server's root file system is exported, one might conclude that |
| 8661 |
a pseudo file system is unneeded. This is not necessarily so. |
| 8662 |
Assume the following file systems on a server: |
| 8663 |
|
| 8664 |
/ fs1 (exported) |
| 8665 |
/a fs2 (not exported) |
| 8666 |
/a/b fs3 (exported) |
| 8667 |
|
| 8668 |
Because fs2 is not exported, fs3 cannot be reached with simple |
| 8669 |
LOOKUPs. The server must bridge the gap with a pseudo file system. |
| 8670 |
|
| 8671 |
|
| 8672 |
|
| 8673 |
|
| 8674 |
|
| 8675 |
|
| 8676 |
<span class="grey">Shepler, et al. Standards Track [Page 155]</span></pre> |
| 8677 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-156" ></span> |
| 8678 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8679 |
|
| 8680 |
|
| 8681 |
<span class="h3"><a class="selflink" id="section-7.7" href="#section-7.7">7.7</a>. Mount Point Crossing</span> |
| 8682 |
|
| 8683 |
The server file system environment may be constructed in such a way |
| 8684 |
that one file system contains a directory that is 'covered' or |
| 8685 |
mounted upon by a second file system. For example: |
| 8686 |
|
| 8687 |
/a/b (file system 1) |
| 8688 |
/a/b/c/d (file system 2) |
| 8689 |
|
| 8690 |
The pseudo file system for this server may be constructed to look |
| 8691 |
like: |
| 8692 |
|
| 8693 |
/ (place holder/not exported) |
| 8694 |
/a/b (file system 1) |
| 8695 |
/a/b/c/d (file system 2) |
| 8696 |
|
| 8697 |
It is the server's responsibility to present the pseudo file system |
| 8698 |
that is complete to the client. If the client sends a LOOKUP request |
| 8699 |
for the path /a/b/c/d, the server's response is the filehandle of the |
| 8700 |
root of the file system /a/b/c/d. In previous versions of the NFS |
| 8701 |
protocol, the server would respond with the filehandle of directory |
| 8702 |
/a/b/c/d within the file system /a/b. |
| 8703 |
|
| 8704 |
The NFS client will be able to determine if it crosses a server mount |
| 8705 |
point by a change in the value of the "fsid" attribute. |
| 8706 |
|
| 8707 |
<span class="h3"><a class="selflink" id="section-7.8" href="#section-7.8">7.8</a>. Security Policy and Namespace Presentation</span> |
| 8708 |
|
| 8709 |
Because NFSv4 clients possess the ability to change the security |
| 8710 |
mechanisms used, after determining what is allowed, by using SECINFO |
| 8711 |
and SECINFO_NONAME, the server SHOULD NOT present a different view of |
| 8712 |
the namespace based on the security mechanism being used by a client. |
| 8713 |
Instead, it should present a consistent view and return |
| 8714 |
NFS4ERR_WRONGSEC if an attempt is made to access data with an |
| 8715 |
inappropriate security mechanism. |
| 8716 |
|
| 8717 |
If security considerations make it necessary to hide the existence of |
| 8718 |
a particular file system, as opposed to all of the data within it, |
| 8719 |
the server can apply the security policy of a shared resource in the |
| 8720 |
server's namespace to components of the resource's ancestors. For |
| 8721 |
example: |
| 8722 |
|
| 8723 |
/ (place holder/not exported) |
| 8724 |
/a/b (file system 1) |
| 8725 |
/a/b/MySecretProject (file system 2) |
| 8726 |
|
| 8727 |
|
| 8728 |
|
| 8729 |
|
| 8730 |
|
| 8731 |
|
| 8732 |
<span class="grey">Shepler, et al. Standards Track [Page 156]</span></pre> |
| 8733 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-157" ></span> |
| 8734 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8735 |
|
| 8736 |
|
| 8737 |
The /a/b/MySecretProject directory is a real file system and is the |
| 8738 |
shared resource. Suppose the security policy for /a/b/ |
| 8739 |
MySecretProject is Kerberos with integrity and it is desired to limit |
| 8740 |
knowledge of the existence of this file system. In this case, the |
| 8741 |
server should apply the same security policy to /a/b. This allows |
| 8742 |
for knowledge of the existence of a file system to be secured when |
| 8743 |
desirable. |
| 8744 |
|
| 8745 |
For the case of the use of multiple, disjoint security mechanisms in |
| 8746 |
the server's resources, applying that sort of policy would result in |
| 8747 |
the higher-level file system not being accessible using any security |
| 8748 |
flavor. Therefore, that sort of configuration is not compatible with |
| 8749 |
hiding the existence (as opposed to the contents) from clients using |
| 8750 |
multiple disjoint sets of security flavors. |
| 8751 |
|
| 8752 |
In other circumstances, a desirable policy is for the security of a |
| 8753 |
particular object in the server's namespace to include the union of |
| 8754 |
all security mechanisms of all direct descendants. A common and |
| 8755 |
convenient practice, unless strong security requirements dictate |
| 8756 |
otherwise, is to make the entire the pseudo file system accessible by |
| 8757 |
all of the valid security mechanisms. |
| 8758 |
|
| 8759 |
Where there is concern about the security of data on the network, |
| 8760 |
clients should use strong security mechanisms to access the pseudo |
| 8761 |
file system in order to prevent man-in-the-middle attacks. |
| 8762 |
|
| 8763 |
<span class="h2"><a class="selflink" id="section-8" href="#section-8">8</a>. State Management</span> |
| 8764 |
|
| 8765 |
Integrating locking into the NFS protocol necessarily causes it to be |
| 8766 |
stateful. With the inclusion of such features as share reservations, |
| 8767 |
file and directory delegations, recallable layouts, and support for |
| 8768 |
mandatory byte-range locking, the protocol becomes substantially more |
| 8769 |
dependent on proper management of state than the traditional |
| 8770 |
combination of NFS and NLM (Network Lock Manager) [<a href="#ref-46" title=""Protocols for Interworking: XNFS, Version 3W, ISBN 1-85912-184-5"">46</a>]. These |
| 8771 |
features include expanded locking facilities, which provide some |
| 8772 |
measure of inter-client exclusion, but the state also offers features |
| 8773 |
not readily providable using a stateless model. There are three |
| 8774 |
components to making this state manageable: |
| 8775 |
|
| 8776 |
o clear division between client and server |
| 8777 |
|
| 8778 |
o ability to reliably detect inconsistency in state between client |
| 8779 |
and server |
| 8780 |
|
| 8781 |
o simple and robust recovery mechanisms |
| 8782 |
|
| 8783 |
|
| 8784 |
|
| 8785 |
|
| 8786 |
|
| 8787 |
|
| 8788 |
<span class="grey">Shepler, et al. Standards Track [Page 157]</span></pre> |
| 8789 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-158" ></span> |
| 8790 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8791 |
|
| 8792 |
|
| 8793 |
In this model, the server owns the state information. The client |
| 8794 |
requests changes in locks and the server responds with the changes |
| 8795 |
made. Non-client-initiated changes in locking state are infrequent. |
| 8796 |
The client receives prompt notification of such changes and can |
| 8797 |
adjust its view of the locking state to reflect the server's changes. |
| 8798 |
|
| 8799 |
Individual pieces of state created by the server and passed to the |
| 8800 |
client at its request are represented by 128-bit stateids. These |
| 8801 |
stateids may represent a particular open file, a set of byte-range |
| 8802 |
locks held by a particular owner, or a recallable delegation of |
| 8803 |
privileges to access a file in particular ways or at a particular |
| 8804 |
location. |
| 8805 |
|
| 8806 |
In all cases, there is a transition from the most general information |
| 8807 |
that represents a client as a whole to the eventual lightweight |
| 8808 |
stateid used for most client and server locking interactions. The |
| 8809 |
details of this transition will vary with the type of object but it |
| 8810 |
always starts with a client ID. |
| 8811 |
|
| 8812 |
<span class="h3"><a class="selflink" id="section-8.1" href="#section-8.1">8.1</a>. Client and Session ID</span> |
| 8813 |
|
| 8814 |
A client must establish a client ID (see <a href="#section-2.4">Section 2.4</a>) and then one or |
| 8815 |
more sessionids (see <a href="#section-2.10">Section 2.10</a>) before performing any operations |
| 8816 |
to open, byte-range lock, delegate, or obtain a layout for a file |
| 8817 |
object. Each session ID is associated with a specific client ID, and |
| 8818 |
thus serves as a shorthand reference to an NFSv4.1 client. |
| 8819 |
|
| 8820 |
For some types of locking interactions, the client will represent |
| 8821 |
some number of internal locking entities called "owners", which |
| 8822 |
normally correspond to processes internal to the client. For other |
| 8823 |
types of locking-related objects, such as delegations and layouts, no |
| 8824 |
such intermediate entities are provided for, and the locking-related |
| 8825 |
objects are considered to be transferred directly between the server |
| 8826 |
and a unitary client. |
| 8827 |
|
| 8828 |
<span class="h3"><a class="selflink" id="section-8.2" href="#section-8.2">8.2</a>. Stateid Definition</span> |
| 8829 |
|
| 8830 |
When the server grants a lock of any type (including opens, byte- |
| 8831 |
range locks, delegations, and layouts), it responds with a unique |
| 8832 |
stateid that represents a set of locks (often a single lock) for the |
| 8833 |
same file, of the same type, and sharing the same ownership |
| 8834 |
characteristics. Thus, opens of the same file by different open- |
| 8835 |
owners each have an identifying stateid. Similarly, each set of |
| 8836 |
byte-range locks on a file owned by a specific lock-owner has its own |
| 8837 |
identifying stateid. Delegations and layouts also have associated |
| 8838 |
stateids by which they may be referenced. The stateid is used as a |
| 8839 |
shorthand reference to a lock or set of locks, and given a stateid, |
| 8840 |
the server can determine the associated state-owner or state-owners |
| 8841 |
|
| 8842 |
|
| 8843 |
|
| 8844 |
<span class="grey">Shepler, et al. Standards Track [Page 158]</span></pre> |
| 8845 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-159" ></span> |
| 8846 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8847 |
|
| 8848 |
|
| 8849 |
(in the case of an open-owner/lock-owner pair) and the associated |
| 8850 |
filehandle. When stateids are used, the current filehandle must be |
| 8851 |
the one associated with that stateid. |
| 8852 |
|
| 8853 |
All stateids associated with a given client ID are associated with a |
| 8854 |
common lease that represents the claim of those stateids and the |
| 8855 |
objects they represent to be maintained by the server. See |
| 8856 |
<a href="#section-8.3">Section 8.3</a> for a discussion of the lease. |
| 8857 |
|
| 8858 |
The server may assign stateids independently for different clients. |
| 8859 |
A stateid with the same bit pattern for one client may designate an |
| 8860 |
entirely different set of locks for a different client. The stateid |
| 8861 |
is always interpreted with respect to the client ID associated with |
| 8862 |
the current session. Stateids apply to all sessions associated with |
| 8863 |
the given client ID, and the client may use a stateid obtained from |
| 8864 |
one session on another session associated with the same client ID. |
| 8865 |
|
| 8866 |
<span class="h4"><a class="selflink" id="section-8.2.1" href="#section-8.2.1">8.2.1</a>. Stateid Types</span> |
| 8867 |
|
| 8868 |
With the exception of special stateids (see <a href="#section-8.2.3">Section 8.2.3</a>), each |
| 8869 |
stateid represents locking objects of one of a set of types defined |
| 8870 |
by the NFSv4.1 protocol. Note that in all these cases, where we |
| 8871 |
speak of guarantee, it is understood there are situations such as a |
| 8872 |
client restart, or lock revocation, that allow the guarantee to be |
| 8873 |
voided. |
| 8874 |
|
| 8875 |
o Stateids may represent opens of files. |
| 8876 |
|
| 8877 |
Each stateid in this case represents the OPEN state for a given |
| 8878 |
client ID/open-owner/filehandle triple. Such stateids are subject |
| 8879 |
to change (with consequent incrementing of the stateid's seqid) in |
| 8880 |
response to OPENs that result in upgrade and OPEN_DOWNGRADE |
| 8881 |
operations. |
| 8882 |
|
| 8883 |
o Stateids may represent sets of byte-range locks. |
| 8884 |
|
| 8885 |
All locks held on a particular file by a particular owner and |
| 8886 |
gotten under the aegis of a particular open file are associated |
| 8887 |
with a single stateid with the seqid being incremented whenever |
| 8888 |
LOCK and LOCKU operations affect that set of locks. |
| 8889 |
|
| 8890 |
o Stateids may represent file delegations, which are recallable |
| 8891 |
guarantees by the server to the client that other clients will not |
| 8892 |
reference or modify a particular file, until the delegation is |
| 8893 |
returned. In NFSv4.1, file delegations may be obtained on both |
| 8894 |
regular and non-regular files. |
| 8895 |
|
| 8896 |
|
| 8897 |
|
| 8898 |
|
| 8899 |
|
| 8900 |
<span class="grey">Shepler, et al. Standards Track [Page 159]</span></pre> |
| 8901 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-160" ></span> |
| 8902 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8903 |
|
| 8904 |
|
| 8905 |
A stateid represents a single delegation held by a client for a |
| 8906 |
particular filehandle. |
| 8907 |
|
| 8908 |
o Stateids may represent directory delegations, which are recallable |
| 8909 |
guarantees by the server to the client that other clients will not |
| 8910 |
modify the directory, until the delegation is returned. |
| 8911 |
|
| 8912 |
A stateid represents a single delegation held by a client for a |
| 8913 |
particular directory filehandle. |
| 8914 |
|
| 8915 |
o Stateids may represent layouts, which are recallable guarantees by |
| 8916 |
the server to the client that particular files may be accessed via |
| 8917 |
an alternate data access protocol at specific locations. Such |
| 8918 |
access is limited to particular sets of byte-ranges and may |
| 8919 |
proceed until those byte-ranges are reduced or the layout is |
| 8920 |
returned. |
| 8921 |
|
| 8922 |
A stateid represents the set of all layouts held by a particular |
| 8923 |
client for a particular filehandle with a given layout type. The |
| 8924 |
seqid is updated as the layouts of that set of byte-ranges change, |
| 8925 |
via layout stateid changing operations such as LAYOUTGET and |
| 8926 |
LAYOUTRETURN. |
| 8927 |
|
| 8928 |
<span class="h4"><a class="selflink" id="section-8.2.2" href="#section-8.2.2">8.2.2</a>. Stateid Structure</span> |
| 8929 |
|
| 8930 |
Stateids are divided into two fields, a 96-bit "other" field |
| 8931 |
identifying the specific set of locks and a 32-bit "seqid" sequence |
| 8932 |
value. Except in the case of special stateids (see <a href="#section-8.2.3">Section 8.2.3</a>), a |
| 8933 |
particular value of the "other" field denotes a set of locks of the |
| 8934 |
same type (for example, byte-range locks, opens, delegations, or |
| 8935 |
layouts), for a specific file or directory, and sharing the same |
| 8936 |
ownership characteristics. The seqid designates a specific instance |
| 8937 |
of such a set of locks, and is incremented to indicate changes in |
| 8938 |
such a set of locks, either by the addition or deletion of locks from |
| 8939 |
the set, a change in the byte-range they apply to, or an upgrade or |
| 8940 |
downgrade in the type of one or more locks. |
| 8941 |
|
| 8942 |
When such a set of locks is first created, the server returns a |
| 8943 |
stateid with seqid value of one. On subsequent operations that |
| 8944 |
modify the set of locks, the server is required to increment the |
| 8945 |
"seqid" field by one whenever it returns a stateid for the same |
| 8946 |
state-owner/file/type combination and there is some change in the set |
| 8947 |
of locks actually designated. In this case, the server will return a |
| 8948 |
stateid with an "other" field the same as previously used for that |
| 8949 |
state-owner/file/type combination, with an incremented "seqid" field. |
| 8950 |
This pattern continues until the seqid is incremented past |
| 8951 |
NFS4_UINT32_MAX, and one (not zero) is the next seqid value. |
| 8952 |
|
| 8953 |
|
| 8954 |
|
| 8955 |
|
| 8956 |
<span class="grey">Shepler, et al. Standards Track [Page 160]</span></pre> |
| 8957 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-161" ></span> |
| 8958 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 8959 |
|
| 8960 |
|
| 8961 |
The purpose of the incrementing of the seqid is to allow the server |
| 8962 |
to communicate to the client the order in which operations that |
| 8963 |
modified locking state associated with a stateid have been processed |
| 8964 |
and to make it possible for the client to send requests that are |
| 8965 |
conditional on the set of locks not having changed since the stateid |
| 8966 |
in question was returned. |
| 8967 |
|
| 8968 |
Except for layout stateids (<a href="#section-12.5.3">Section 12.5.3</a>), when a client sends a |
| 8969 |
stateid to the server, it has two choices with regard to the seqid |
| 8970 |
sent. It may set the seqid to zero to indicate to the server that it |
| 8971 |
wishes the most up-to-date seqid for that stateid's "other" field to |
| 8972 |
be used. This would be the common choice in the case of a stateid |
| 8973 |
sent with a READ or WRITE operation. It also may set a non-zero |
| 8974 |
value, in which case the server checks if that seqid is the correct |
| 8975 |
one. In that case, the server is required to return |
| 8976 |
NFS4ERR_OLD_STATEID if the seqid is lower than the most current value |
| 8977 |
and NFS4ERR_BAD_STATEID if the seqid is greater than the most current |
| 8978 |
value. This would be the common choice in the case of stateids sent |
| 8979 |
with a CLOSE or OPEN_DOWNGRADE. Because OPENs may be sent in |
| 8980 |
parallel for the same owner, a client might close a file without |
| 8981 |
knowing that an OPEN upgrade had been done by the server, changing |
| 8982 |
the lock in question. If CLOSE were sent with a zero seqid, the OPEN |
| 8983 |
upgrade would be cancelled before the client even received an |
| 8984 |
indication that an upgrade had happened. |
| 8985 |
|
| 8986 |
When a stateid is sent by the server to the client as part of a |
| 8987 |
callback operation, it is not subject to checking for a current seqid |
| 8988 |
and returning NFS4ERR_OLD_STATEID. This is because the client is not |
| 8989 |
in a position to know the most up-to-date seqid and thus cannot |
| 8990 |
verify it. Unless specially noted, the seqid value for a stateid |
| 8991 |
sent by the server to the client as part of a callback is required to |
| 8992 |
be zero with NFS4ERR_BAD_STATEID returned if it is not. |
| 8993 |
|
| 8994 |
In making comparisons between seqids, both by the client in |
| 8995 |
determining the order of operations and by the server in determining |
| 8996 |
whether the NFS4ERR_OLD_STATEID is to be returned, the possibility of |
| 8997 |
the seqid being swapped around past the NFS4_UINT32_MAX value needs |
| 8998 |
to be taken into account. When two seqid values are being compared, |
| 8999 |
the total count of slots for all sessions associated with the current |
| 9000 |
client is used to do this. When one seqid value is less than this |
| 9001 |
total slot count and another seqid value is greater than |
| 9002 |
NFS4_UINT32_MAX minus the total slot count, the former is to be |
| 9003 |
treated as lower than the latter, despite the fact that it is |
| 9004 |
numerically greater. |
| 9005 |
|
| 9006 |
|
| 9007 |
|
| 9008 |
|
| 9009 |
|
| 9010 |
|
| 9011 |
|
| 9012 |
<span class="grey">Shepler, et al. Standards Track [Page 161]</span></pre> |
| 9013 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-162" ></span> |
| 9014 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9015 |
|
| 9016 |
|
| 9017 |
<span class="h4"><a class="selflink" id="section-8.2.3" href="#section-8.2.3">8.2.3</a>. Special Stateids</span> |
| 9018 |
|
| 9019 |
Stateid values whose "other" field is either all zeros or all ones |
| 9020 |
are reserved. They may not be assigned by the server but have |
| 9021 |
special meanings defined by the protocol. The particular meaning |
| 9022 |
depends on whether the "other" field is all zeros or all ones and the |
| 9023 |
specific value of the "seqid" field. |
| 9024 |
|
| 9025 |
The following combinations of "other" and "seqid" are defined in |
| 9026 |
NFSv4.1: |
| 9027 |
|
| 9028 |
o When "other" and "seqid" are both zero, the stateid is treated as |
| 9029 |
a special anonymous stateid, which can be used in READ, WRITE, and |
| 9030 |
SETATTR requests to indicate the absence of any OPEN state |
| 9031 |
associated with the request. When an anonymous stateid value is |
| 9032 |
used and an existing open denies the form of access requested, |
| 9033 |
then access will be denied to the request. This stateid MUST NOT |
| 9034 |
be used on operations to data servers (<a href="#section-13.6">Section 13.6</a>). |
| 9035 |
|
| 9036 |
o When "other" and "seqid" are both all ones, the stateid is a |
| 9037 |
special READ bypass stateid. When this value is used in WRITE or |
| 9038 |
SETATTR, it is treated like the anonymous value. When used in |
| 9039 |
READ, the server MAY grant access, even if access would normally |
| 9040 |
be denied to READ operations. This stateid MUST NOT be used on |
| 9041 |
operations to data servers. |
| 9042 |
|
| 9043 |
o When "other" is zero and "seqid" is one, the stateid represents |
| 9044 |
the current stateid, which is whatever value is the last stateid |
| 9045 |
returned by an operation within the COMPOUND. In the case of an |
| 9046 |
OPEN, the stateid returned for the open file and not the |
| 9047 |
delegation is used. The stateid passed to the operation in place |
| 9048 |
of the special value has its "seqid" value set to zero, except |
| 9049 |
when the current stateid is used by the operation CLOSE or |
| 9050 |
OPEN_DOWNGRADE. If there is no operation in the COMPOUND that has |
| 9051 |
returned a stateid value, the server MUST return the error |
| 9052 |
NFS4ERR_BAD_STATEID. As illustrated in Figure 6, if the value of |
| 9053 |
a current stateid is a special stateid and the stateid of an |
| 9054 |
operation's arguments has "other" set to zero and "seqid" set to |
| 9055 |
one, then the server MUST return the error NFS4ERR_BAD_STATEID. |
| 9056 |
|
| 9057 |
o When "other" is zero and "seqid" is NFS4_UINT32_MAX, the stateid |
| 9058 |
represents a reserved stateid value defined to be invalid. When |
| 9059 |
this stateid is used, the server MUST return the error |
| 9060 |
NFS4ERR_BAD_STATEID. |
| 9061 |
|
| 9062 |
If a stateid value is used that has all zeros or all ones in the |
| 9063 |
"other" field but does not match one of the cases above, the server |
| 9064 |
MUST return the error NFS4ERR_BAD_STATEID. |
| 9065 |
|
| 9066 |
|
| 9067 |
|
| 9068 |
<span class="grey">Shepler, et al. Standards Track [Page 162]</span></pre> |
| 9069 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-163" ></span> |
| 9070 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9071 |
|
| 9072 |
|
| 9073 |
Special stateids, unlike other stateids, are not associated with |
| 9074 |
individual client IDs or filehandles and can be used with all valid |
| 9075 |
client IDs and filehandles. In the case of a special stateid |
| 9076 |
designating the current stateid, the current stateid value |
| 9077 |
substituted for the special stateid is associated with a particular |
| 9078 |
client ID and filehandle, and so, if it is used where the current |
| 9079 |
filehandle does not match that associated with the current stateid, |
| 9080 |
the operation to which the stateid is passed will return |
| 9081 |
NFS4ERR_BAD_STATEID. |
| 9082 |
|
| 9083 |
<span class="h4"><a class="selflink" id="section-8.2.4" href="#section-8.2.4">8.2.4</a>. Stateid Lifetime and Validation</span> |
| 9084 |
|
| 9085 |
Stateids must remain valid until either a client restart or a server |
| 9086 |
restart or until the client returns all of the locks associated with |
| 9087 |
the stateid by means of an operation such as CLOSE or DELEGRETURN. |
| 9088 |
If the locks are lost due to revocation, as long as the client ID is |
| 9089 |
valid, the stateid remains a valid designation of that revoked state |
| 9090 |
until the client frees it by using FREE_STATEID. Stateids associated |
| 9091 |
with byte-range locks are an exception. They remain valid even if a |
| 9092 |
LOCKU frees all remaining locks, so long as the open file with which |
| 9093 |
they are associated remains open, unless the client frees the |
| 9094 |
stateids via the FREE_STATEID operation. |
| 9095 |
|
| 9096 |
It should be noted that there are situations in which the client's |
| 9097 |
locks become invalid, without the client requesting they be returned. |
| 9098 |
These include lease expiration and a number of forms of lock |
| 9099 |
revocation within the lease period. It is important to note that in |
| 9100 |
these situations, the stateid remains valid and the client can use it |
| 9101 |
to determine the disposition of the associated lost locks. |
| 9102 |
|
| 9103 |
An "other" value must never be reused for a different purpose (i.e., |
| 9104 |
different filehandle, owner, or type of locks) within the context of |
| 9105 |
a single client ID. A server may retain the "other" value for the |
| 9106 |
same purpose beyond the point where it may otherwise be freed, but if |
| 9107 |
it does so, it must maintain "seqid" continuity with previous values. |
| 9108 |
|
| 9109 |
One mechanism that may be used to satisfy the requirement that the |
| 9110 |
server recognize invalid and out-of-date stateids is for the server |
| 9111 |
to divide the "other" field of the stateid into two fields. |
| 9112 |
|
| 9113 |
o an index into a table of locking-state structures. |
| 9114 |
|
| 9115 |
o a generation number that is incremented on each allocation of a |
| 9116 |
table entry for a particular use. |
| 9117 |
|
| 9118 |
And then store in each table entry, |
| 9119 |
|
| 9120 |
o the client ID with which the stateid is associated. |
| 9121 |
|
| 9122 |
|
| 9123 |
|
| 9124 |
<span class="grey">Shepler, et al. Standards Track [Page 163]</span></pre> |
| 9125 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-164" ></span> |
| 9126 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9127 |
|
| 9128 |
|
| 9129 |
o the current generation number for the (at most one) valid stateid |
| 9130 |
sharing this index value. |
| 9131 |
|
| 9132 |
o the filehandle of the file on which the locks are taken. |
| 9133 |
|
| 9134 |
o an indication of the type of stateid (open, byte-range lock, file |
| 9135 |
delegation, directory delegation, layout). |
| 9136 |
|
| 9137 |
o the last "seqid" value returned corresponding to the current |
| 9138 |
"other" value. |
| 9139 |
|
| 9140 |
o an indication of the current status of the locks associated with |
| 9141 |
this stateid, in particular, whether these have been revoked and |
| 9142 |
if so, for what reason. |
| 9143 |
|
| 9144 |
With this information, an incoming stateid can be validated and the |
| 9145 |
appropriate error returned when necessary. Special and non-special |
| 9146 |
stateids are handled separately. (See <a href="#section-8.2.3">Section 8.2.3</a> for a discussion |
| 9147 |
of special stateids.) |
| 9148 |
|
| 9149 |
Note that stateids are implicitly qualified by the current client ID, |
| 9150 |
as derived from the client ID associated with the current session. |
| 9151 |
Note, however, that the semantics of the session will prevent |
| 9152 |
stateids associated with a previous client or server instance from |
| 9153 |
being analyzed by this procedure. |
| 9154 |
|
| 9155 |
If server restart has resulted in an invalid client ID or a session |
| 9156 |
ID that is invalid, SEQUENCE will return an error and the operation |
| 9157 |
that takes a stateid as an argument will never be processed. |
| 9158 |
|
| 9159 |
If there has been a server restart where there is a persistent |
| 9160 |
session and all leased state has been lost, then the session in |
| 9161 |
question will, although valid, be marked as dead, and any operation |
| 9162 |
not satisfied by means of the reply cache will receive the error |
| 9163 |
NFS4ERR_DEADSESSION, and thus not be processed as indicated below. |
| 9164 |
|
| 9165 |
When a stateid is being tested and the "other" field is all zeros or |
| 9166 |
all ones, a check that the "other" and "seqid" fields match a defined |
| 9167 |
combination for a special stateid is done and the results determined |
| 9168 |
as follows: |
| 9169 |
|
| 9170 |
o If the "other" and "seqid" fields do not match a defined |
| 9171 |
combination associated with a special stateid, the error |
| 9172 |
NFS4ERR_BAD_STATEID is returned. |
| 9173 |
|
| 9174 |
|
| 9175 |
|
| 9176 |
|
| 9177 |
|
| 9178 |
|
| 9179 |
|
| 9180 |
<span class="grey">Shepler, et al. Standards Track [Page 164]</span></pre> |
| 9181 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-165" ></span> |
| 9182 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9183 |
|
| 9184 |
|
| 9185 |
o If the special stateid is one designating the current stateid and |
| 9186 |
there is a current stateid, then the current stateid is |
| 9187 |
substituted for the special stateid and the checks appropriate to |
| 9188 |
non-special stateids are performed. |
| 9189 |
|
| 9190 |
o If the combination is valid in general but is not appropriate to |
| 9191 |
the context in which the stateid is used (e.g., an all-zero |
| 9192 |
stateid is used when an OPEN stateid is required in a LOCK |
| 9193 |
operation), the error NFS4ERR_BAD_STATEID is also returned. |
| 9194 |
|
| 9195 |
o Otherwise, the check is completed and the special stateid is |
| 9196 |
accepted as valid. |
| 9197 |
|
| 9198 |
When a stateid is being tested, and the "other" field is neither all |
| 9199 |
zeros nor all ones, the following procedure could be used to validate |
| 9200 |
an incoming stateid and return an appropriate error, when necessary, |
| 9201 |
assuming that the "other" field would be divided into a table index |
| 9202 |
and an entry generation. |
| 9203 |
|
| 9204 |
o If the table index field is outside the range of the associated |
| 9205 |
table, return NFS4ERR_BAD_STATEID. |
| 9206 |
|
| 9207 |
o If the selected table entry is of a different generation than that |
| 9208 |
specified in the incoming stateid, return NFS4ERR_BAD_STATEID. |
| 9209 |
|
| 9210 |
o If the selected table entry does not match the current filehandle, |
| 9211 |
return NFS4ERR_BAD_STATEID. |
| 9212 |
|
| 9213 |
o If the client ID in the table entry does not match the client ID |
| 9214 |
associated with the current session, return NFS4ERR_BAD_STATEID. |
| 9215 |
|
| 9216 |
o If the stateid represents revoked state, then return |
| 9217 |
NFS4ERR_EXPIRED, NFS4ERR_ADMIN_REVOKED, or NFS4ERR_DELEG_REVOKED, |
| 9218 |
as appropriate. |
| 9219 |
|
| 9220 |
o If the stateid type is not valid for the context in which the |
| 9221 |
stateid appears, return NFS4ERR_BAD_STATEID. Note that a stateid |
| 9222 |
may be valid in general, as would be reported by the TEST_STATEID |
| 9223 |
operation, but be invalid for a particular operation, as, for |
| 9224 |
example, when a stateid that doesn't represent byte-range locks is |
| 9225 |
passed to the non-from_open case of LOCK or to LOCKU, or when a |
| 9226 |
stateid that does not represent an open is passed to CLOSE or |
| 9227 |
OPEN_DOWNGRADE. In such cases, the server MUST return |
| 9228 |
NFS4ERR_BAD_STATEID. |
| 9229 |
|
| 9230 |
o If the "seqid" field is not zero and it is greater than the |
| 9231 |
current sequence value corresponding to the current "other" field, |
| 9232 |
return NFS4ERR_BAD_STATEID. |
| 9233 |
|
| 9234 |
|
| 9235 |
|
| 9236 |
<span class="grey">Shepler, et al. Standards Track [Page 165]</span></pre> |
| 9237 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-166" ></span> |
| 9238 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9239 |
|
| 9240 |
|
| 9241 |
o If the "seqid" field is not zero and it is less than the current |
| 9242 |
sequence value corresponding to the current "other" field, return |
| 9243 |
NFS4ERR_OLD_STATEID. |
| 9244 |
|
| 9245 |
o Otherwise, the stateid is valid and the table entry should contain |
| 9246 |
any additional information about the type of stateid and |
| 9247 |
information associated with that particular type of stateid, such |
| 9248 |
as the associated set of locks, e.g., open-owner and lock-owner |
| 9249 |
information, as well as information on the specific locks, e.g., |
| 9250 |
open modes and byte-ranges. |
| 9251 |
|
| 9252 |
<span class="h4"><a class="selflink" id="section-8.2.5" href="#section-8.2.5">8.2.5</a>. Stateid Use for I/O Operations</span> |
| 9253 |
|
| 9254 |
Clients performing I/O operations need to select an appropriate |
| 9255 |
stateid based on the locks (including opens and delegations) held by |
| 9256 |
the client and the various types of state-owners sending the I/O |
| 9257 |
requests. SETATTR operations that change the file size are treated |
| 9258 |
like I/O operations in this regard. |
| 9259 |
|
| 9260 |
The following rules, applied in order of decreasing priority, govern |
| 9261 |
the selection of the appropriate stateid. In following these rules, |
| 9262 |
the client will only consider locks of which it has actually received |
| 9263 |
notification by an appropriate operation response or callback. Note |
| 9264 |
that the rules are slightly different in the case of I/O to data |
| 9265 |
servers when file layouts are being used (see <a href="#section-13.9.1">Section 13.9.1</a>). |
| 9266 |
|
| 9267 |
o If the client holds a delegation for the file in question, the |
| 9268 |
delegation stateid SHOULD be used. |
| 9269 |
|
| 9270 |
o Otherwise, if the entity corresponding to the lock-owner (e.g., a |
| 9271 |
process) sending the I/O has a byte-range lock stateid for the |
| 9272 |
associated open file, then the byte-range lock stateid for that |
| 9273 |
lock-owner and open file SHOULD be used. |
| 9274 |
|
| 9275 |
o If there is no byte-range lock stateid, then the OPEN stateid for |
| 9276 |
the open file in question SHOULD be used. |
| 9277 |
|
| 9278 |
o Finally, if none of the above apply, then a special stateid SHOULD |
| 9279 |
be used. |
| 9280 |
|
| 9281 |
Ignoring these rules may result in situations in which the server |
| 9282 |
does not have information necessary to properly process the request. |
| 9283 |
For example, when mandatory byte-range locks are in effect, if the |
| 9284 |
stateid does not indicate the proper lock-owner, via a lock stateid, |
| 9285 |
a request might be avoidably rejected. |
| 9286 |
|
| 9287 |
|
| 9288 |
|
| 9289 |
|
| 9290 |
|
| 9291 |
|
| 9292 |
<span class="grey">Shepler, et al. Standards Track [Page 166]</span></pre> |
| 9293 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-167" ></span> |
| 9294 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9295 |
|
| 9296 |
|
| 9297 |
The server however should not try to enforce these ordering rules and |
| 9298 |
should use whatever information is available to properly process I/O |
| 9299 |
requests. In particular, when a client has a delegation for a given |
| 9300 |
file, it SHOULD take note of this fact in processing a request, even |
| 9301 |
if it is sent with a special stateid. |
| 9302 |
|
| 9303 |
<span class="h4"><a class="selflink" id="section-8.2.6" href="#section-8.2.6">8.2.6</a>. Stateid Use for SETATTR Operations</span> |
| 9304 |
|
| 9305 |
Because each operation is associated with a session ID and from that |
| 9306 |
the clientid can be determined, operations do not need to include a |
| 9307 |
stateid for the server to be able to determine whether they should |
| 9308 |
cause a delegation to be recalled or are to be treated as done within |
| 9309 |
the scope of the delegation. |
| 9310 |
|
| 9311 |
In the case of SETATTR operations, a stateid is present. In cases |
| 9312 |
other than those that set the file size, the client may send either a |
| 9313 |
special stateid or, when a delegation is held for the file in |
| 9314 |
question, a delegation stateid. While the server SHOULD validate the |
| 9315 |
stateid and may use the stateid to optimize the determination as to |
| 9316 |
whether a delegation is held, it SHOULD note the presence of a |
| 9317 |
delegation even when a special stateid is sent, and MUST accept a |
| 9318 |
valid delegation stateid when sent. |
| 9319 |
|
| 9320 |
<span class="h3"><a class="selflink" id="section-8.3" href="#section-8.3">8.3</a>. Lease Renewal</span> |
| 9321 |
|
| 9322 |
Each client/server pair, as represented by a client ID, has a single |
| 9323 |
lease. The purpose of the lease is to allow the client to indicate |
| 9324 |
to the server, in a low-overhead way, that it is active, and thus |
| 9325 |
that the server is to retain the client's locks. This arrangement |
| 9326 |
allows the server to remove stale locking-related objects that are |
| 9327 |
held by a client that has crashed or is otherwise unreachable, once |
| 9328 |
the relevant lease expires. This in turn allows other clients to |
| 9329 |
obtain conflicting locks without being delayed indefinitely by |
| 9330 |
inactive or unreachable clients. It is not a mechanism for cache |
| 9331 |
consistency and lease renewals may not be denied if the lease |
| 9332 |
interval has not expired. |
| 9333 |
|
| 9334 |
Since each session is associated with a specific client (identified |
| 9335 |
by the client's client ID), any operation sent on that session is an |
| 9336 |
indication that the associated client is reachable. When a request |
| 9337 |
is sent for a given session, successful execution of a SEQUENCE |
| 9338 |
operation (or successful retrieval of the result of SEQUENCE from the |
| 9339 |
reply cache) on an unexpired lease will result in the lease being |
| 9340 |
implicitly renewed, for the standard renewal period (equal to the |
| 9341 |
lease_time attribute). |
| 9342 |
|
| 9343 |
|
| 9344 |
|
| 9345 |
|
| 9346 |
|
| 9347 |
|
| 9348 |
<span class="grey">Shepler, et al. Standards Track [Page 167]</span></pre> |
| 9349 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-168" ></span> |
| 9350 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9351 |
|
| 9352 |
|
| 9353 |
If the client ID's lease has not expired when the server receives a |
| 9354 |
SEQUENCE operation, then the server MUST renew the lease. If the |
| 9355 |
client ID's lease has expired when the server receives a SEQUENCE |
| 9356 |
operation, the server MAY renew the lease; this depends on whether |
| 9357 |
any state was revoked as a result of the client's failure to renew |
| 9358 |
the lease before expiration. |
| 9359 |
|
| 9360 |
Absent other activity that would renew the lease, a COMPOUND |
| 9361 |
consisting of a single SEQUENCE operation will suffice. The client |
| 9362 |
should also take communication-related delays into account and take |
| 9363 |
steps to ensure that the renewal messages actually reach the server |
| 9364 |
in good time. For example: |
| 9365 |
|
| 9366 |
o When trunking is in effect, the client should consider sending |
| 9367 |
multiple requests on different connections, in order to ensure |
| 9368 |
that renewal occurs, even in the event of blockage in the path |
| 9369 |
used for one of those connections. |
| 9370 |
|
| 9371 |
o Transport retransmission delays might become so large as to |
| 9372 |
approach or exceed the length of the lease period. This may be |
| 9373 |
particularly likely when the server is unresponsive due to a |
| 9374 |
restart; see <a href="#section-8.4.2.1">Section 8.4.2.1</a>. If the client implementation is not |
| 9375 |
careful, transport retransmission delays can result in the client |
| 9376 |
failing to detect a server restart before the grace period ends. |
| 9377 |
The scenario is that the client is using a transport with |
| 9378 |
exponential backoff, such that the maximum retransmission timeout |
| 9379 |
exceeds both the grace period and the lease_time attribute. A |
| 9380 |
network partition causes the client's connection's retransmission |
| 9381 |
interval to back off, and even after the partition heals, the next |
| 9382 |
transport-level retransmission is sent after the server has |
| 9383 |
restarted and its grace period ends. |
| 9384 |
|
| 9385 |
The client MUST either recover from the ensuing NFS4ERR_NO_GRACE |
| 9386 |
errors or it MUST ensure that, despite transport-level |
| 9387 |
retransmission intervals that exceed the lease_time, a SEQUENCE |
| 9388 |
operation is sent that renews the lease before expiration. The |
| 9389 |
client can achieve this by associating a new connection with the |
| 9390 |
session, and sending a SEQUENCE operation on it. However, if the |
| 9391 |
attempt to establish a new connection is delayed for some reason |
| 9392 |
(e.g., exponential backoff of the connection establishment |
| 9393 |
packets), the client will have to abort the connection |
| 9394 |
establishment attempt before the lease expires, and attempt to |
| 9395 |
reconnect. |
| 9396 |
|
| 9397 |
If the server renews the lease upon receiving a SEQUENCE operation, |
| 9398 |
the server MUST NOT allow the lease to expire while the rest of the |
| 9399 |
operations in the COMPOUND procedure's request are still executing. |
| 9400 |
|
| 9401 |
|
| 9402 |
|
| 9403 |
|
| 9404 |
<span class="grey">Shepler, et al. Standards Track [Page 168]</span></pre> |
| 9405 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-169" ></span> |
| 9406 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9407 |
|
| 9408 |
|
| 9409 |
Once the last operation has finished, and the response to COMPOUND |
| 9410 |
has been sent, the server MUST set the lease to expire no sooner than |
| 9411 |
the sum of current time and the value of the lease_time attribute. |
| 9412 |
|
| 9413 |
A client ID's lease can expire when it has been at least the lease |
| 9414 |
interval (lease_time) since the last lease-renewing SEQUENCE |
| 9415 |
operation was sent on any of the client ID's sessions and there are |
| 9416 |
no active COMPOUND operations on any such sessions. |
| 9417 |
|
| 9418 |
Because the SEQUENCE operation is the basic mechanism to renew a |
| 9419 |
lease, and because it must be done at least once for each lease |
| 9420 |
period, it is the natural mechanism whereby the server will inform |
| 9421 |
the client of changes in the lease status that the client needs to be |
| 9422 |
informed of. The client should inspect the status flags |
| 9423 |
(sr_status_flags) returned by sequence and take the appropriate |
| 9424 |
action (see <a href="#section-18.46.3">Section 18.46.3</a> for details). |
| 9425 |
|
| 9426 |
o The status bits SEQ4_STATUS_CB_PATH_DOWN and |
| 9427 |
SEQ4_STATUS_CB_PATH_DOWN_SESSION indicate problems with the |
| 9428 |
backchannel that the client may need to address in order to |
| 9429 |
receive callback requests. |
| 9430 |
|
| 9431 |
o The status bits SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRING and |
| 9432 |
SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRED indicate problems with GSS |
| 9433 |
contexts or RPCSEC_GSS handles for the backchannel that the client |
| 9434 |
might have to address in order to allow callback requests to be |
| 9435 |
sent. |
| 9436 |
|
| 9437 |
o The status bits SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED, |
| 9438 |
SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED, |
| 9439 |
SEQ4_STATUS_ADMIN_STATE_REVOKED, and |
| 9440 |
SEQ4_STATUS_RECALLABLE_STATE_REVOKED notify the client of lock |
| 9441 |
revocation events. When these bits are set, the client should use |
| 9442 |
TEST_STATEID to find what stateids have been revoked and use |
| 9443 |
FREE_STATEID to acknowledge loss of the associated state. |
| 9444 |
|
| 9445 |
o The status bit SEQ4_STATUS_LEASE_MOVE indicates that |
| 9446 |
responsibility for lease renewal has been transferred to one or |
| 9447 |
more new servers. |
| 9448 |
|
| 9449 |
o The status bit SEQ4_STATUS_RESTART_RECLAIM_NEEDED indicates that |
| 9450 |
due to server restart the client must reclaim locking state. |
| 9451 |
|
| 9452 |
o The status bit SEQ4_STATUS_BACKCHANNEL_FAULT indicates that the |
| 9453 |
server has encountered an unrecoverable fault with the backchannel |
| 9454 |
(e.g., it has lost track of a sequence ID for a slot in the |
| 9455 |
backchannel). |
| 9456 |
|
| 9457 |
|
| 9458 |
|
| 9459 |
|
| 9460 |
<span class="grey">Shepler, et al. Standards Track [Page 169]</span></pre> |
| 9461 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-170" ></span> |
| 9462 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9463 |
|
| 9464 |
|
| 9465 |
<span class="h3"><a class="selflink" id="section-8.4" href="#section-8.4">8.4</a>. Crash Recovery</span> |
| 9466 |
|
| 9467 |
A critical requirement in crash recovery is that both the client and |
| 9468 |
the server know when the other has failed. Additionally, it is |
| 9469 |
required that a client sees a consistent view of data across server |
| 9470 |
restarts. All READ and WRITE operations that may have been queued |
| 9471 |
within the client or network buffers must wait until the client has |
| 9472 |
successfully recovered the locks protecting the READ and WRITE |
| 9473 |
operations. Any that reach the server before the server can safely |
| 9474 |
determine that the client has recovered enough locking state to be |
| 9475 |
sure that such operations can be safely processed must be rejected. |
| 9476 |
This will happen because either: |
| 9477 |
|
| 9478 |
o The state presented is no longer valid since it is associated with |
| 9479 |
a now invalid client ID. In this case, the client will receive |
| 9480 |
either an NFS4ERR_BADSESSION or NFS4ERR_DEADSESSION error, and any |
| 9481 |
attempt to attach a new session to that invalid client ID will |
| 9482 |
result in an NFS4ERR_STALE_CLIENTID error. |
| 9483 |
|
| 9484 |
o Subsequent recovery of locks may make execution of the operation |
| 9485 |
inappropriate (NFS4ERR_GRACE). |
| 9486 |
|
| 9487 |
<span class="h4"><a class="selflink" id="section-8.4.1" href="#section-8.4.1">8.4.1</a>. Client Failure and Recovery</span> |
| 9488 |
|
| 9489 |
In the event that a client fails, the server may release the client's |
| 9490 |
locks when the associated lease has expired. Conflicting locks from |
| 9491 |
another client may only be granted after this lease expiration. As |
| 9492 |
discussed in <a href="#section-8.3">Section 8.3</a>, when a client has not failed and re- |
| 9493 |
establishes its lease before expiration occurs, requests for |
| 9494 |
conflicting locks will not be granted. |
| 9495 |
|
| 9496 |
To minimize client delay upon restart, lock requests are associated |
| 9497 |
with an instance of the client by a client-supplied verifier. This |
| 9498 |
verifier is part of the client_owner4 sent in the initial EXCHANGE_ID |
| 9499 |
call made by the client. The server returns a client ID as a result |
| 9500 |
of the EXCHANGE_ID operation. The client then confirms the use of |
| 9501 |
the client ID by establishing a session associated with that client |
| 9502 |
ID (see <a href="#section-18.36.3">Section 18.36.3</a> for a description of how this is done). All |
| 9503 |
locks, including opens, byte-range locks, delegations, and layouts |
| 9504 |
obtained by sessions using that client ID, are associated with that |
| 9505 |
client ID. |
| 9506 |
|
| 9507 |
Since the verifier will be changed by the client upon each |
| 9508 |
initialization, the server can compare a new verifier to the verifier |
| 9509 |
associated with currently held locks and determine that they do not |
| 9510 |
match. This signifies the client's new instantiation and subsequent |
| 9511 |
loss (upon confirmation of the new client ID) of locking state. As a |
| 9512 |
result, the server is free to release all locks held that are |
| 9513 |
|
| 9514 |
|
| 9515 |
|
| 9516 |
<span class="grey">Shepler, et al. Standards Track [Page 170]</span></pre> |
| 9517 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-171" ></span> |
| 9518 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9519 |
|
| 9520 |
|
| 9521 |
associated with the old client ID that was derived from the old |
| 9522 |
verifier. At this point, conflicting locks from other clients, kept |
| 9523 |
waiting while the lease had not yet expired, can be granted. In |
| 9524 |
addition, all stateids associated with the old client ID can also be |
| 9525 |
freed, as they are no longer reference-able. |
| 9526 |
|
| 9527 |
Note that the verifier must have the same uniqueness properties as |
| 9528 |
the verifier for the COMMIT operation. |
| 9529 |
|
| 9530 |
<span class="h4"><a class="selflink" id="section-8.4.2" href="#section-8.4.2">8.4.2</a>. Server Failure and Recovery</span> |
| 9531 |
|
| 9532 |
If the server loses locking state (usually as a result of a restart), |
| 9533 |
it must allow clients time to discover this fact and re-establish the |
| 9534 |
lost locking state. The client must be able to re-establish the |
| 9535 |
locking state without having the server deny valid requests because |
| 9536 |
the server has granted conflicting access to another client. |
| 9537 |
Likewise, if there is a possibility that clients have not yet re- |
| 9538 |
established their locking state for a file and that such locking |
| 9539 |
state might make it invalid to perform READ or WRITE operations. For |
| 9540 |
example, if mandatory locks are a possibility, the server must |
| 9541 |
disallow READ and WRITE operations for that file. |
| 9542 |
|
| 9543 |
A client can determine that loss of locking state has occurred via |
| 9544 |
several methods. |
| 9545 |
|
| 9546 |
1. When a SEQUENCE (most common) or other operation returns |
| 9547 |
NFS4ERR_BADSESSION, this may mean that the session has been |
| 9548 |
destroyed but the client ID is still valid. The client sends a |
| 9549 |
CREATE_SESSION request with the client ID to re-establish the |
| 9550 |
session. If CREATE_SESSION fails with NFS4ERR_STALE_CLIENTID, |
| 9551 |
the client must establish a new client ID (see <a href="#section-8.1">Section 8.1</a>) and |
| 9552 |
re-establish its lock state with the new client ID, after the |
| 9553 |
CREATE_SESSION operation succeeds (see <a href="#section-8.4.2.1">Section 8.4.2.1</a>). |
| 9554 |
|
| 9555 |
2. When a SEQUENCE (most common) or other operation on a persistent |
| 9556 |
session returns NFS4ERR_DEADSESSION, this indicates that a |
| 9557 |
session is no longer usable for new, i.e., not satisfied from the |
| 9558 |
reply cache, operations. Once all pending operations are |
| 9559 |
determined to be either performed before the retry or not |
| 9560 |
performed, the client sends a CREATE_SESSION request with the |
| 9561 |
client ID to re-establish the session. If CREATE_SESSION fails |
| 9562 |
with NFS4ERR_STALE_CLIENTID, the client must establish a new |
| 9563 |
client ID (see <a href="#section-8.1">Section 8.1</a>) and re-establish its lock state after |
| 9564 |
the CREATE_SESSION, with the new client ID, succeeds |
| 9565 |
(<a href="#section-8.4.2.1">Section 8.4.2.1</a>). |
| 9566 |
|
| 9567 |
|
| 9568 |
|
| 9569 |
|
| 9570 |
|
| 9571 |
|
| 9572 |
<span class="grey">Shepler, et al. Standards Track [Page 171]</span></pre> |
| 9573 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-172" ></span> |
| 9574 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9575 |
|
| 9576 |
|
| 9577 |
3. When an operation, neither SEQUENCE nor preceded by SEQUENCE (for |
| 9578 |
example, CREATE_SESSION, DESTROY_SESSION), returns |
| 9579 |
NFS4ERR_STALE_CLIENTID, the client MUST establish a new client ID |
| 9580 |
(<a href="#section-8.1">Section 8.1</a>) and re-establish its lock state (<a href="#section-8.4.2.1">Section 8.4.2.1</a>). |
| 9581 |
|
| 9582 |
<span class="h5"><a class="selflink" id="section-8.4.2.1" href="#section-8.4.2.1">8.4.2.1</a>. State Reclaim</span> |
| 9583 |
|
| 9584 |
When state information and the associated locks are lost as a result |
| 9585 |
of a server restart, the protocol must provide a way to cause that |
| 9586 |
state to be re-established. The approach used is to define, for most |
| 9587 |
types of locking state (layouts are an exception), a request whose |
| 9588 |
function is to allow the client to re-establish on the server a lock |
| 9589 |
first obtained from a previous instance. Generally, these requests |
| 9590 |
are variants of the requests normally used to create locks of that |
| 9591 |
type and are referred to as "reclaim-type" requests, and the process |
| 9592 |
of re-establishing such locks is referred to as "reclaiming" them. |
| 9593 |
|
| 9594 |
Because each client must have an opportunity to reclaim all of the |
| 9595 |
locks that it has without the possibility that some other client will |
| 9596 |
be granted a conflicting lock, a "grace period" is devoted to the |
| 9597 |
reclaim process. During this period, requests creating client IDs |
| 9598 |
and sessions are handled normally, but locking requests are subject |
| 9599 |
to special restrictions. Only reclaim-type locking requests are |
| 9600 |
allowed, unless the server can reliably determine (through state |
| 9601 |
persistently maintained across restart instances) that granting any |
| 9602 |
such lock cannot possibly conflict with a subsequent reclaim. When a |
| 9603 |
request is made to obtain a new lock (i.e., not a reclaim-type |
| 9604 |
request) during the grace period and such a determination cannot be |
| 9605 |
made, the server must return the error NFS4ERR_GRACE. |
| 9606 |
|
| 9607 |
Once a session is established using the new client ID, the client |
| 9608 |
will use reclaim-type locking requests (e.g., LOCK operations with |
| 9609 |
reclaim set to TRUE and OPEN operations with a claim type of |
| 9610 |
CLAIM_PREVIOUS; see <a href="#section-9.11">Section 9.11</a>) to re-establish its locking state. |
| 9611 |
Once this is done, or if there is no such locking state to reclaim, |
| 9612 |
the client sends a global RECLAIM_COMPLETE operation, i.e., one with |
| 9613 |
the rca_one_fs argument set to FALSE, to indicate that it has |
| 9614 |
reclaimed all of the locking state that it will reclaim. Once a |
| 9615 |
client sends such a RECLAIM_COMPLETE operation, it may attempt non- |
| 9616 |
reclaim locking operations, although it might get an NFS4ERR_GRACE |
| 9617 |
status result from each such operation until the period of special |
| 9618 |
handling is over. See <a href="#section-11.7.7">Section 11.7.7</a> for a discussion of the |
| 9619 |
analogous handling lock reclamation in the case of file systems |
| 9620 |
transitioning from server to server. |
| 9621 |
|
| 9622 |
|
| 9623 |
|
| 9624 |
|
| 9625 |
|
| 9626 |
|
| 9627 |
|
| 9628 |
<span class="grey">Shepler, et al. Standards Track [Page 172]</span></pre> |
| 9629 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-173" ></span> |
| 9630 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9631 |
|
| 9632 |
|
| 9633 |
During the grace period, the server must reject READ and WRITE |
| 9634 |
operations and non-reclaim locking requests (i.e., other LOCK and |
| 9635 |
OPEN operations) with an error of NFS4ERR_GRACE, unless it can |
| 9636 |
guarantee that these may be done safely, as described below. |
| 9637 |
|
| 9638 |
The grace period may last until all clients that are known to |
| 9639 |
possibly have had locks have done a global RECLAIM_COMPLETE |
| 9640 |
operation, indicating that they have finished reclaiming the locks |
| 9641 |
they held before the server restart. This means that a client that |
| 9642 |
has done a RECLAIM_COMPLETE must be prepared to receive an |
| 9643 |
NFS4ERR_GRACE when attempting to acquire new locks. In order for the |
| 9644 |
server to know that all clients with possible prior lock state have |
| 9645 |
done a RECLAIM_COMPLETE, the server must maintain in stable storage a |
| 9646 |
list clients that may have such locks. The server may also terminate |
| 9647 |
the grace period before all clients have done a global |
| 9648 |
RECLAIM_COMPLETE. The server SHOULD NOT terminate the grace period |
| 9649 |
before a time equal to the lease period in order to give clients an |
| 9650 |
opportunity to find out about the server restart, as a result of |
| 9651 |
sending requests on associated sessions with a frequency governed by |
| 9652 |
the lease time. Note that when a client does not send such requests |
| 9653 |
(or they are sent by the client but not received by the server), it |
| 9654 |
is possible for the grace period to expire before the client finds |
| 9655 |
out that the server restart has occurred. |
| 9656 |
|
| 9657 |
Some additional time in order to allow a client to establish a new |
| 9658 |
client ID and session and to effect lock reclaims may be added to the |
| 9659 |
lease time. Note that analogous rules apply to file system-specific |
| 9660 |
grace periods discussed in <a href="#section-11.7.7">Section 11.7.7</a>. |
| 9661 |
|
| 9662 |
If the server can reliably determine that granting a non-reclaim |
| 9663 |
request will not conflict with reclamation of locks by other clients, |
| 9664 |
the NFS4ERR_GRACE error does not have to be returned even within the |
| 9665 |
grace period, although NFS4ERR_GRACE must always be returned to |
| 9666 |
clients attempting a non-reclaim lock request before doing their own |
| 9667 |
global RECLAIM_COMPLETE. For the server to be able to service READ |
| 9668 |
and WRITE operations during the grace period, it must again be able |
| 9669 |
to guarantee that no possible conflict could arise between a |
| 9670 |
potential reclaim locking request and the READ or WRITE operation. |
| 9671 |
If the server is unable to offer that guarantee, the NFS4ERR_GRACE |
| 9672 |
error must be returned to the client. |
| 9673 |
|
| 9674 |
For a server to provide simple, valid handling during the grace |
| 9675 |
period, the easiest method is to simply reject all non-reclaim |
| 9676 |
locking requests and READ and WRITE operations by returning the |
| 9677 |
NFS4ERR_GRACE error. However, a server may keep information about |
| 9678 |
granted locks in stable storage. With this information, the server |
| 9679 |
could determine if a locking, READ or WRITE operation can be safely |
| 9680 |
processed. |
| 9681 |
|
| 9682 |
|
| 9683 |
|
| 9684 |
<span class="grey">Shepler, et al. Standards Track [Page 173]</span></pre> |
| 9685 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-174" ></span> |
| 9686 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9687 |
|
| 9688 |
|
| 9689 |
For example, if the server maintained on stable storage summary |
| 9690 |
information on whether mandatory locks exist, either mandatory byte- |
| 9691 |
range locks, or share reservations specifying deny modes, many |
| 9692 |
requests could be allowed during the grace period. If it is known |
| 9693 |
that no such share reservations exist, OPEN request that do not |
| 9694 |
specify deny modes may be safely granted. If, in addition, it is |
| 9695 |
known that no mandatory byte-range locks exist, either through |
| 9696 |
information stored on stable storage or simply because the server |
| 9697 |
does not support such locks, READ and WRITE operations may be safely |
| 9698 |
processed during the grace period. Another important case is where |
| 9699 |
it is known that no mandatory byte-range locks exist, either because |
| 9700 |
the server does not provide support for them or because their absence |
| 9701 |
is known from persistently recorded data. In this case, READ and |
| 9702 |
WRITE operations specifying stateids derived from reclaim-type |
| 9703 |
operations may be validly processed during the grace period because |
| 9704 |
of the fact that the valid reclaim ensures that no lock subsequently |
| 9705 |
granted can prevent the I/O. |
| 9706 |
|
| 9707 |
To reiterate, for a server that allows non-reclaim lock and I/O |
| 9708 |
requests to be processed during the grace period, it MUST determine |
| 9709 |
that no lock subsequently reclaimed will be rejected and that no lock |
| 9710 |
subsequently reclaimed would have prevented any I/O operation |
| 9711 |
processed during the grace period. |
| 9712 |
|
| 9713 |
Clients should be prepared for the return of NFS4ERR_GRACE errors for |
| 9714 |
non-reclaim lock and I/O requests. In this case, the client should |
| 9715 |
employ a retry mechanism for the request. A delay (on the order of |
| 9716 |
several seconds) between retries should be used to avoid overwhelming |
| 9717 |
the server. Further discussion of the general issue is included in |
| 9718 |
[<a href="#ref-47" title=""The Synchronization of Periodic Routing Messages"">47</a>]. The client must account for the server that can perform I/O |
| 9719 |
and non-reclaim locking requests within the grace period as well as |
| 9720 |
those that cannot do so. |
| 9721 |
|
| 9722 |
A reclaim-type locking request outside the server's grace period can |
| 9723 |
only succeed if the server can guarantee that no conflicting lock or |
| 9724 |
I/O request has been granted since restart. |
| 9725 |
|
| 9726 |
A server may, upon restart, establish a new value for the lease |
| 9727 |
period. Therefore, clients should, once a new client ID is |
| 9728 |
established, refetch the lease_time attribute and use it as the basis |
| 9729 |
for lease renewal for the lease associated with that server. |
| 9730 |
However, the server must establish, for this restart event, a grace |
| 9731 |
period at least as long as the lease period for the previous server |
| 9732 |
instantiation. This allows the client state obtained during the |
| 9733 |
previous server instance to be reliably re-established. |
| 9734 |
|
| 9735 |
|
| 9736 |
|
| 9737 |
|
| 9738 |
|
| 9739 |
|
| 9740 |
<span class="grey">Shepler, et al. Standards Track [Page 174]</span></pre> |
| 9741 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-175" ></span> |
| 9742 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9743 |
|
| 9744 |
|
| 9745 |
The possibility exists that, because of server configuration events, |
| 9746 |
the client will be communicating with a server different than the one |
| 9747 |
on which the locks were obtained, as shown by the combination of |
| 9748 |
eir_server_scope and eir_server_owner. This leads to the issue of if |
| 9749 |
and when the client should attempt to reclaim locks previously |
| 9750 |
obtained on what is being reported as a different server. The rules |
| 9751 |
to resolve this question are as follows: |
| 9752 |
|
| 9753 |
o If the server scope is different, the client should not attempt to |
| 9754 |
reclaim locks. In this situation, no lock reclaim is possible. |
| 9755 |
Any attempt to re-obtain the locks with non-reclaim operations is |
| 9756 |
problematic since there is no guarantee that the existing |
| 9757 |
filehandles will be recognized by the new server, or that if |
| 9758 |
recognized, they denote the same objects. It is best to treat the |
| 9759 |
locks as having been revoked by the reconfiguration event. |
| 9760 |
|
| 9761 |
o If the server scope is the same, the client should attempt to |
| 9762 |
reclaim locks, even if the eir_server_owner value is different. |
| 9763 |
In this situation, it is the responsibility of the server to |
| 9764 |
return NFS4ERR_NO_GRACE if it cannot provide correct support for |
| 9765 |
lock reclaim operations, including the prevention of edge |
| 9766 |
conditions. |
| 9767 |
|
| 9768 |
The eir_server_owner field is not used in making this determination. |
| 9769 |
Its function is to specify trunking possibilities for the client (see |
| 9770 |
<a href="#section-2.10.5">Section 2.10.5</a>) and not to control lock reclaim. |
| 9771 |
|
| 9772 |
<span class="h6"><a class="selflink" id="section-8.4.2.1.1" href="#section-8.4.2.1.1">8.4.2.1.1</a>. Security Considerations for State Reclaim</span> |
| 9773 |
|
| 9774 |
During the grace period, a client can reclaim state that it believes |
| 9775 |
or asserts it had before the server restarted. Unless the server |
| 9776 |
maintained a complete record of all the state the client had, the |
| 9777 |
server has little choice but to trust the client. (Of course, if the |
| 9778 |
server maintained a complete record, then it would not have to force |
| 9779 |
the client to reclaim state after server restart.) While the server |
| 9780 |
has to trust the client to tell the truth, such trust does not have |
| 9781 |
any negative consequences for security. The fundamental rule for the |
| 9782 |
server when processing reclaim requests is that it MUST NOT grant the |
| 9783 |
reclaim if an equivalent non-reclaim request would not be granted |
| 9784 |
during steady state due to access control or access conflict issues. |
| 9785 |
For example, an OPEN request during a reclaim will be refused with |
| 9786 |
NFS4ERR_ACCESS if the principal making the request does not have |
| 9787 |
access to open the file according to the discretionary ACL |
| 9788 |
(<a href="#section-6.2.2">Section 6.2.2</a>) on the file. |
| 9789 |
|
| 9790 |
Nonetheless, it is possible that a client operating in error or |
| 9791 |
maliciously could, during reclaim, prevent another client from |
| 9792 |
reclaiming access to state. For example, an attacker could send an |
| 9793 |
|
| 9794 |
|
| 9795 |
|
| 9796 |
<span class="grey">Shepler, et al. Standards Track [Page 175]</span></pre> |
| 9797 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-176" ></span> |
| 9798 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9799 |
|
| 9800 |
|
| 9801 |
OPEN reclaim operation with a deny mode that prevents another client |
| 9802 |
from reclaiming the OPEN state it had before the server restarted. |
| 9803 |
The attacker could perform the same denial of service during steady |
| 9804 |
state prior to server restart, as long as the attacker had |
| 9805 |
permissions. Given that the attack vectors are equivalent, the grace |
| 9806 |
period does not offer any additional opportunity for denial of |
| 9807 |
service, and any concerns about this attack vector, whether during |
| 9808 |
grace or steady state, are addressed the same way: use RPCSEC_GSS for |
| 9809 |
authentication and limit access to the file only to principals that |
| 9810 |
the owner of the file trusts. |
| 9811 |
|
| 9812 |
Note that if prior to restart the server had client IDs with the |
| 9813 |
EXCHGID4_FLAG_BIND_PRINC_STATEID (<a href="#section-18.35">Section 18.35</a>) capability set, then |
| 9814 |
the server SHOULD record in stable storage the client owner and the |
| 9815 |
principal that established the client ID via EXCHANGE_ID. If the |
| 9816 |
server does not, then there is a risk a client will be unable to |
| 9817 |
reclaim state if it does not have a credential for a principal that |
| 9818 |
was originally authorized to establish the state. |
| 9819 |
|
| 9820 |
<span class="h4"><a class="selflink" id="section-8.4.3" href="#section-8.4.3">8.4.3</a>. Network Partitions and Recovery</span> |
| 9821 |
|
| 9822 |
If the duration of a network partition is greater than the lease |
| 9823 |
period provided by the server, the server will not have received a |
| 9824 |
lease renewal from the client. If this occurs, the server may free |
| 9825 |
all locks held for the client or it may allow the lock state to |
| 9826 |
remain for a considerable period, subject to the constraint that if a |
| 9827 |
request for a conflicting lock is made, locks associated with an |
| 9828 |
expired lease do not prevent such a conflicting lock from being |
| 9829 |
granted but MUST be revoked as necessary so as to avoid interfering |
| 9830 |
with such conflicting requests. |
| 9831 |
|
| 9832 |
If the server chooses to delay freeing of lock state until there is a |
| 9833 |
conflict, it may either free all of the client's locks once there is |
| 9834 |
a conflict or it may only revoke the minimum set of locks necessary |
| 9835 |
to allow conflicting requests. When it adopts the finer-grained |
| 9836 |
approach, it must revoke all locks associated with a given stateid, |
| 9837 |
even if the conflict is with only a subset of locks. |
| 9838 |
|
| 9839 |
When the server chooses to free all of a client's lock state, either |
| 9840 |
immediately upon lease expiration or as a result of the first attempt |
| 9841 |
to obtain a conflicting a lock, the server may report the loss of |
| 9842 |
lock state in a number of ways. |
| 9843 |
|
| 9844 |
The server may choose to invalidate the session and the associated |
| 9845 |
client ID. In this case, once the client can communicate with the |
| 9846 |
server, it will receive an NFS4ERR_BADSESSION error. Upon attempting |
| 9847 |
to create a new session, it would get an NFS4ERR_STALE_CLIENTID. |
| 9848 |
Upon creating the new client ID and new session, the client will |
| 9849 |
|
| 9850 |
|
| 9851 |
|
| 9852 |
<span class="grey">Shepler, et al. Standards Track [Page 176]</span></pre> |
| 9853 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-177" ></span> |
| 9854 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9855 |
|
| 9856 |
|
| 9857 |
attempt to reclaim locks. Normally, the server will not allow the |
| 9858 |
client to reclaim locks, because the server will not be in its |
| 9859 |
recovery grace period. |
| 9860 |
|
| 9861 |
Another possibility is for the server to maintain the session and |
| 9862 |
client ID but for all stateids held by the client to become invalid |
| 9863 |
or stale. Once the client can reach the server after such a network |
| 9864 |
partition, the status returned by the SEQUENCE operation will |
| 9865 |
indicate a loss of locking state; i.e., the flag |
| 9866 |
SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED will be set in sr_status_flags. |
| 9867 |
In addition, all I/O submitted by the client with the now invalid |
| 9868 |
stateids will fail with the server returning the error |
| 9869 |
NFS4ERR_EXPIRED. Once the client learns of the loss of locking |
| 9870 |
state, it will suitably notify the applications that held the |
| 9871 |
invalidated locks. The client should then take action to free |
| 9872 |
invalidated stateids, either by establishing a new client ID using a |
| 9873 |
new verifier or by doing a FREE_STATEID operation to release each of |
| 9874 |
the invalidated stateids. |
| 9875 |
|
| 9876 |
When the server adopts a finer-grained approach to revocation of |
| 9877 |
locks when a client's lease has expired, only a subset of stateids |
| 9878 |
will normally become invalid during a network partition. When the |
| 9879 |
client can communicate with the server after such a network partition |
| 9880 |
heals, the status returned by the SEQUENCE operation will indicate a |
| 9881 |
partial loss of locking state |
| 9882 |
(SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED). In addition, operations, |
| 9883 |
including I/O submitted by the client, with the now invalid stateids |
| 9884 |
will fail with the server returning the error NFS4ERR_EXPIRED. Once |
| 9885 |
the client learns of the loss of locking state, it will use the |
| 9886 |
TEST_STATEID operation on all of its stateids to determine which |
| 9887 |
locks have been lost and then suitably notify the applications that |
| 9888 |
held the invalidated locks. The client can then release the |
| 9889 |
invalidated locking state and acknowledge the revocation of the |
| 9890 |
associated locks by doing a FREE_STATEID operation on each of the |
| 9891 |
invalidated stateids. |
| 9892 |
|
| 9893 |
When a network partition is combined with a server restart, there are |
| 9894 |
edge conditions that place requirements on the server in order to |
| 9895 |
avoid silent data corruption following the server restart. Two of |
| 9896 |
these edge conditions are known, and are discussed below. |
| 9897 |
|
| 9898 |
The first edge condition arises as a result of the scenarios such as |
| 9899 |
the following: |
| 9900 |
|
| 9901 |
|
| 9902 |
|
| 9903 |
|
| 9904 |
|
| 9905 |
|
| 9906 |
|
| 9907 |
|
| 9908 |
<span class="grey">Shepler, et al. Standards Track [Page 177]</span></pre> |
| 9909 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-178" ></span> |
| 9910 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9911 |
|
| 9912 |
|
| 9913 |
1. Client A acquires a lock. |
| 9914 |
|
| 9915 |
2. Client A and server experience mutual network partition, such |
| 9916 |
that client A is unable to renew its lease. |
| 9917 |
|
| 9918 |
3. Client A's lease expires, and the server releases the lock. |
| 9919 |
|
| 9920 |
4. Client B acquires a lock that would have conflicted with that of |
| 9921 |
client A. |
| 9922 |
|
| 9923 |
5. Client B releases its lock. |
| 9924 |
|
| 9925 |
6. Server restarts. |
| 9926 |
|
| 9927 |
7. Network partition between client A and server heals. |
| 9928 |
|
| 9929 |
8. Client A connects to a new server instance and finds out about |
| 9930 |
server restart. |
| 9931 |
|
| 9932 |
9. Client A reclaims its lock within the server's grace period. |
| 9933 |
|
| 9934 |
Thus, at the final step, the server has erroneously granted client |
| 9935 |
A's lock reclaim. If client B modified the object the lock was |
| 9936 |
protecting, client A will experience object corruption. |
| 9937 |
|
| 9938 |
The second known edge condition arises in situations such as the |
| 9939 |
following: |
| 9940 |
|
| 9941 |
1. Client A acquires one or more locks. |
| 9942 |
|
| 9943 |
2. Server restarts. |
| 9944 |
|
| 9945 |
3. Client A and server experience mutual network partition, such |
| 9946 |
that client A is unable to reclaim all of its locks within the |
| 9947 |
grace period. |
| 9948 |
|
| 9949 |
4. Server's reclaim grace period ends. Client A has either no |
| 9950 |
locks or an incomplete set of locks known to the server. |
| 9951 |
|
| 9952 |
5. Client B acquires a lock that would have conflicted with a lock |
| 9953 |
of client A that was not reclaimed. |
| 9954 |
|
| 9955 |
6. Client B releases the lock. |
| 9956 |
|
| 9957 |
7. Server restarts a second time. |
| 9958 |
|
| 9959 |
8. Network partition between client A and server heals. |
| 9960 |
|
| 9961 |
|
| 9962 |
|
| 9963 |
|
| 9964 |
<span class="grey">Shepler, et al. Standards Track [Page 178]</span></pre> |
| 9965 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-179" ></span> |
| 9966 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 9967 |
|
| 9968 |
|
| 9969 |
9. Client A connects to new server instance and finds out about |
| 9970 |
server restart. |
| 9971 |
|
| 9972 |
10. Client A reclaims its lock within the server's grace period. |
| 9973 |
|
| 9974 |
As with the first edge condition, the final step of the scenario of |
| 9975 |
the second edge condition has the server erroneously granting client |
| 9976 |
A's lock reclaim. |
| 9977 |
|
| 9978 |
Solving the first and second edge conditions requires either that the |
| 9979 |
server always assumes after it restarts that some edge condition |
| 9980 |
occurs, and thus returns NFS4ERR_NO_GRACE for all reclaim attempts, |
| 9981 |
or that the server record some information in stable storage. The |
| 9982 |
amount of information the server records in stable storage is in |
| 9983 |
inverse proportion to how harsh the server intends to be whenever |
| 9984 |
edge conditions arise. The server that is completely tolerant of all |
| 9985 |
edge conditions will record in stable storage every lock that is |
| 9986 |
acquired, removing the lock record from stable storage only when the |
| 9987 |
lock is released. For the two edge conditions discussed above, the |
| 9988 |
harshest a server can be, and still support a grace period for |
| 9989 |
reclaims, requires that the server record in stable storage some |
| 9990 |
minimal information. For example, a server implementation could, for |
| 9991 |
each client, save in stable storage a record containing: |
| 9992 |
|
| 9993 |
o the co_ownerid field from the client_owner4 presented in the |
| 9994 |
EXCHANGE_ID operation. |
| 9995 |
|
| 9996 |
o a boolean that indicates if the client's lease expired or if there |
| 9997 |
was administrative intervention (see <a href="#section-8.5">Section 8.5</a>) to revoke a |
| 9998 |
byte-range lock, share reservation, or delegation and there has |
| 9999 |
been no acknowledgment, via FREE_STATEID, of such revocation. |
| 10000 |
|
| 10001 |
o a boolean that indicates whether the client may have locks that it |
| 10002 |
believes to be reclaimable in situations in which the grace period |
| 10003 |
was terminated, making the server's view of lock reclaimability |
| 10004 |
suspect. The server will set this for any client record in stable |
| 10005 |
storage where the client has not done a suitable RECLAIM_COMPLETE |
| 10006 |
(global or file system-specific depending on the target of the |
| 10007 |
lock request) before it grants any new (i.e., not reclaimed) lock |
| 10008 |
to any client. |
| 10009 |
|
| 10010 |
Assuming the above record keeping, for the first edge condition, |
| 10011 |
after the server restarts, the record that client A's lease expired |
| 10012 |
means that another client could have acquired a conflicting byte- |
| 10013 |
range lock, share reservation, or delegation. Hence, the server must |
| 10014 |
reject a reclaim from client A with the error NFS4ERR_NO_GRACE. |
| 10015 |
|
| 10016 |
|
| 10017 |
|
| 10018 |
|
| 10019 |
|
| 10020 |
<span class="grey">Shepler, et al. Standards Track [Page 179]</span></pre> |
| 10021 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-180" ></span> |
| 10022 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10023 |
|
| 10024 |
|
| 10025 |
For the second edge condition, after the server restarts for a second |
| 10026 |
time, the indication that the client had not completed its reclaims |
| 10027 |
at the time at which the grace period ended means that the server |
| 10028 |
must reject a reclaim from client A with the error NFS4ERR_NO_GRACE. |
| 10029 |
|
| 10030 |
When either edge condition occurs, the client's attempt to reclaim |
| 10031 |
locks will result in the error NFS4ERR_NO_GRACE. When this is |
| 10032 |
received, or after the client restarts with no lock state, the client |
| 10033 |
will send a global RECLAIM_COMPLETE. When the RECLAIM_COMPLETE is |
| 10034 |
received, the server and client are again in agreement regarding |
| 10035 |
reclaimable locks and both booleans in persistent storage can be |
| 10036 |
reset, to be set again only when there is a subsequent event that |
| 10037 |
causes lock reclaim operations to be questionable. |
| 10038 |
|
| 10039 |
Regardless of the level and approach to record keeping, the server |
| 10040 |
MUST implement one of the following strategies (which apply to |
| 10041 |
reclaims of share reservations, byte-range locks, and delegations): |
| 10042 |
|
| 10043 |
1. Reject all reclaims with NFS4ERR_NO_GRACE. This is extremely |
| 10044 |
unforgiving, but necessary if the server does not record lock |
| 10045 |
state in stable storage. |
| 10046 |
|
| 10047 |
2. Record sufficient state in stable storage such that all known |
| 10048 |
edge conditions involving server restart, including the two noted |
| 10049 |
in this section, are detected. It is acceptable to erroneously |
| 10050 |
recognize an edge condition and not allow a reclaim, when, with |
| 10051 |
sufficient knowledge, it would be allowed. The error the server |
| 10052 |
would return in this case is NFS4ERR_NO_GRACE. Note that it is |
| 10053 |
not known if there are other edge conditions. |
| 10054 |
|
| 10055 |
In the event that, after a server restart, the server determines |
| 10056 |
there is unrecoverable damage or corruption to the information in |
| 10057 |
stable storage, then for all clients and/or locks that may be |
| 10058 |
affected, the server MUST return NFS4ERR_NO_GRACE. |
| 10059 |
|
| 10060 |
A mandate for the client's handling of the NFS4ERR_NO_GRACE error is |
| 10061 |
outside the scope of this specification, since the strategies for |
| 10062 |
such handling are very dependent on the client's operating |
| 10063 |
environment. However, one potential approach is described below. |
| 10064 |
|
| 10065 |
When the client receives NFS4ERR_NO_GRACE, it could examine the |
| 10066 |
change attribute of the objects for which the client is trying to |
| 10067 |
reclaim state, and use that to determine whether to re-establish the |
| 10068 |
state via normal OPEN or LOCK operations. This is acceptable |
| 10069 |
provided that the client's operating environment allows it. In other |
| 10070 |
words, the client implementor is advised to document for his users |
| 10071 |
the behavior. The client could also inform the application that its |
| 10072 |
byte-range lock or share reservations (whether or not they were |
| 10073 |
|
| 10074 |
|
| 10075 |
|
| 10076 |
<span class="grey">Shepler, et al. Standards Track [Page 180]</span></pre> |
| 10077 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-181" ></span> |
| 10078 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10079 |
|
| 10080 |
|
| 10081 |
delegated) have been lost, such as via a UNIX signal, a Graphical |
| 10082 |
User Interface (GUI) pop-up window, etc. See <a href="#section-10.5">Section 10.5</a> for a |
| 10083 |
discussion of what the client should do for dealing with unreclaimed |
| 10084 |
delegations on client state. |
| 10085 |
|
| 10086 |
For further discussion of revocation of locks, see <a href="#section-8.5">Section 8.5</a>. |
| 10087 |
|
| 10088 |
<span class="h3"><a class="selflink" id="section-8.5" href="#section-8.5">8.5</a>. Server Revocation of Locks</span> |
| 10089 |
|
| 10090 |
At any point, the server can revoke locks held by a client, and the |
| 10091 |
client must be prepared for this event. When the client detects that |
| 10092 |
its locks have been or may have been revoked, the client is |
| 10093 |
responsible for validating the state information between itself and |
| 10094 |
the server. Validating locking state for the client means that it |
| 10095 |
must verify or reclaim state for each lock currently held. |
| 10096 |
|
| 10097 |
The first occasion of lock revocation is upon server restart. Note |
| 10098 |
that this includes situations in which sessions are persistent and |
| 10099 |
locking state is lost. In this class of instances, the client will |
| 10100 |
receive an error (NFS4ERR_STALE_CLIENTID) on an operation that takes |
| 10101 |
client ID, usually as part of recovery in response to a problem with |
| 10102 |
the current session), and the client will proceed with normal crash |
| 10103 |
recovery as described in the <a href="#section-8.4.2.1">Section 8.4.2.1</a>. |
| 10104 |
|
| 10105 |
The second occasion of lock revocation is the inability to renew the |
| 10106 |
lease before expiration, as discussed in <a href="#section-8.4.3">Section 8.4.3</a>. While this |
| 10107 |
is considered a rare or unusual event, the client must be prepared to |
| 10108 |
recover. The server is responsible for determining the precise |
| 10109 |
consequences of the lease expiration, informing the client of the |
| 10110 |
scope of the lock revocation decided upon. The client then uses the |
| 10111 |
status information provided by the server in the SEQUENCE results |
| 10112 |
(field sr_status_flags, see <a href="#section-18.46.3">Section 18.46.3</a>) to synchronize its |
| 10113 |
locking state with that of the server, in order to recover. |
| 10114 |
|
| 10115 |
The third occasion of lock revocation can occur as a result of |
| 10116 |
revocation of locks within the lease period, either because of |
| 10117 |
administrative intervention or because a recallable lock (a |
| 10118 |
delegation or layout) was not returned within the lease period after |
| 10119 |
having been recalled. While these are considered rare events, they |
| 10120 |
are possible, and the client must be prepared to deal with them. |
| 10121 |
When either of these events occurs, the client finds out about the |
| 10122 |
situation through the status returned by the SEQUENCE operation. Any |
| 10123 |
use of stateids associated with locks revoked during the lease period |
| 10124 |
will receive the error NFS4ERR_ADMIN_REVOKED or |
| 10125 |
NFS4ERR_DELEG_REVOKED, as appropriate. |
| 10126 |
|
| 10127 |
|
| 10128 |
|
| 10129 |
|
| 10130 |
|
| 10131 |
|
| 10132 |
<span class="grey">Shepler, et al. Standards Track [Page 181]</span></pre> |
| 10133 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-182" ></span> |
| 10134 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10135 |
|
| 10136 |
|
| 10137 |
In all situations in which a subset of locking state may have been |
| 10138 |
revoked, which include all cases in which locking state is revoked |
| 10139 |
within the lease period, it is up to the client to determine which |
| 10140 |
locks have been revoked and which have not. It does this by using |
| 10141 |
the TEST_STATEID operation on the appropriate set of stateids. Once |
| 10142 |
the set of revoked locks has been determined, the applications can be |
| 10143 |
notified, and the invalidated stateids can be freed and lock |
| 10144 |
revocation acknowledged by using FREE_STATEID. |
| 10145 |
|
| 10146 |
<span class="h3"><a class="selflink" id="section-8.6" href="#section-8.6">8.6</a>. Short and Long Leases</span> |
| 10147 |
|
| 10148 |
When determining the time period for the server lease, the usual |
| 10149 |
lease tradeoffs apply. A short lease is good for fast server |
| 10150 |
recovery at a cost of increased operations to effect lease renewal |
| 10151 |
(when there are no other operations during the period to effect lease |
| 10152 |
renewal as a side effect). A long lease is certainly kinder and |
| 10153 |
gentler to servers trying to handle very large numbers of clients. |
| 10154 |
The number of extra requests to effect lock renewal drops in inverse |
| 10155 |
proportion to the lease time. The disadvantages of a long lease |
| 10156 |
include the possibility of slower recovery after certain failures. |
| 10157 |
After server failure, a longer grace period may be required when some |
| 10158 |
clients do not promptly reclaim their locks and do a global |
| 10159 |
RECLAIM_COMPLETE. In the event of client failure, the longer period |
| 10160 |
for a lease to expire will force conflicting requests to wait longer. |
| 10161 |
|
| 10162 |
A long lease is practical if the server can store lease state in |
| 10163 |
stable storage. Upon recovery, the server can reconstruct the lease |
| 10164 |
state from its stable storage and continue operation with its |
| 10165 |
clients. |
| 10166 |
|
| 10167 |
<span class="h3"><a class="selflink" id="section-8.7" href="#section-8.7">8.7</a>. Clocks, Propagation Delay, and Calculating Lease Expiration</span> |
| 10168 |
|
| 10169 |
To avoid the need for synchronized clocks, lease times are granted by |
| 10170 |
the server as a time delta. However, there is a requirement that the |
| 10171 |
client and server clocks do not drift excessively over the duration |
| 10172 |
of the lease. There is also the issue of propagation delay across |
| 10173 |
the network, which could easily be several hundred milliseconds, as |
| 10174 |
well as the possibility that requests will be lost and need to be |
| 10175 |
retransmitted. |
| 10176 |
|
| 10177 |
To take propagation delay into account, the client should subtract it |
| 10178 |
from lease times (e.g., if the client estimates the one-way |
| 10179 |
propagation delay as 200 milliseconds, then it can assume that the |
| 10180 |
lease is already 200 milliseconds old when it gets it). In addition, |
| 10181 |
it will take another 200 milliseconds to get a response back to the |
| 10182 |
server. So the client must send a lease renewal or write data back |
| 10183 |
to the server at least 400 milliseconds before the lease would |
| 10184 |
expire. If the propagation delay varies over the life of the lease |
| 10185 |
|
| 10186 |
|
| 10187 |
|
| 10188 |
<span class="grey">Shepler, et al. Standards Track [Page 182]</span></pre> |
| 10189 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-183" ></span> |
| 10190 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10191 |
|
| 10192 |
|
| 10193 |
(e.g., the client is on a mobile host), the client will need to |
| 10194 |
continuously subtract the increase in propagation delay from the |
| 10195 |
lease times. |
| 10196 |
|
| 10197 |
The server's lease period configuration should take into account the |
| 10198 |
network distance of the clients that will be accessing the server's |
| 10199 |
resources. It is expected that the lease period will take into |
| 10200 |
account the network propagation delays and other network delay |
| 10201 |
factors for the client population. Since the protocol does not allow |
| 10202 |
for an automatic method to determine an appropriate lease period, the |
| 10203 |
server's administrator may have to tune the lease period. |
| 10204 |
|
| 10205 |
<span class="h3"><a class="selflink" id="section-8.8" href="#section-8.8">8.8</a>. Obsolete Locking Infrastructure from NFSv4.0</span> |
| 10206 |
|
| 10207 |
There are a number of operations and fields within existing |
| 10208 |
operations that no longer have a function in NFSv4.1. In one way or |
| 10209 |
another, these changes are all due to the implementation of sessions |
| 10210 |
that provide client context and exactly once semantics as a base |
| 10211 |
feature of the protocol, separate from locking itself. |
| 10212 |
|
| 10213 |
The following NFSv4.0 operations MUST NOT be implemented in NFSv4.1. |
| 10214 |
The server MUST return NFS4ERR_NOTSUPP if these operations are found |
| 10215 |
in an NFSv4.1 COMPOUND. |
| 10216 |
|
| 10217 |
o SETCLIENTID since its function has been replaced by EXCHANGE_ID. |
| 10218 |
|
| 10219 |
o SETCLIENTID_CONFIRM since client ID confirmation now happens by |
| 10220 |
means of CREATE_SESSION. |
| 10221 |
|
| 10222 |
o OPEN_CONFIRM because state-owner-based seqids have been replaced |
| 10223 |
by the sequence ID in the SEQUENCE operation. |
| 10224 |
|
| 10225 |
o RELEASE_LOCKOWNER because lock-owners with no associated locks do |
| 10226 |
not have any sequence-related state and so can be deleted by the |
| 10227 |
server at will. |
| 10228 |
|
| 10229 |
o RENEW because every SEQUENCE operation for a session causes lease |
| 10230 |
renewal, making a separate operation superfluous. |
| 10231 |
|
| 10232 |
Also, there are a number of fields, present in existing operations, |
| 10233 |
related to locking that have no use in minor version 1. They were |
| 10234 |
used in minor version 0 to perform functions now provided in a |
| 10235 |
different fashion. |
| 10236 |
|
| 10237 |
o Sequence ids used to sequence requests for a given state-owner and |
| 10238 |
to provide retry protection, now provided via sessions. |
| 10239 |
|
| 10240 |
|
| 10241 |
|
| 10242 |
|
| 10243 |
|
| 10244 |
<span class="grey">Shepler, et al. Standards Track [Page 183]</span></pre> |
| 10245 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-184" ></span> |
| 10246 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10247 |
|
| 10248 |
|
| 10249 |
o Client IDs used to identify the client associated with a given |
| 10250 |
request. Client identification is now available using the client |
| 10251 |
ID associated with the current session, without needing an |
| 10252 |
explicit client ID field. |
| 10253 |
|
| 10254 |
Such vestigial fields in existing operations have no function in |
| 10255 |
NFSv4.1 and are ignored by the server. Note that client IDs in |
| 10256 |
operations new to NFSv4.1 (such as CREATE_SESSION and |
| 10257 |
DESTROY_CLIENTID) are not ignored. |
| 10258 |
|
| 10259 |
<span class="h2"><a class="selflink" id="section-9" href="#section-9">9</a>. File Locking and Share Reservations</span> |
| 10260 |
|
| 10261 |
To support Win32 share reservations, it is necessary to provide |
| 10262 |
operations that atomically open or create files. Having a separate |
| 10263 |
share/unshare operation would not allow correct implementation of the |
| 10264 |
Win32 OpenFile API. In order to correctly implement share semantics, |
| 10265 |
the previous NFS protocol mechanisms used when a file is opened or |
| 10266 |
created (LOOKUP, CREATE, ACCESS) need to be replaced. The NFSv4.1 |
| 10267 |
protocol defines an OPEN operation that is capable of atomically |
| 10268 |
looking up, creating, and locking a file on the server. |
| 10269 |
|
| 10270 |
<span class="h3"><a class="selflink" id="section-9.1" href="#section-9.1">9.1</a>. Opens and Byte-Range Locks</span> |
| 10271 |
|
| 10272 |
It is assumed that manipulating a byte-range lock is rare when |
| 10273 |
compared to READ and WRITE operations. It is also assumed that |
| 10274 |
server restarts and network partitions are relatively rare. |
| 10275 |
Therefore, it is important that the READ and WRITE operations have a |
| 10276 |
lightweight mechanism to indicate if they possess a held lock. A |
| 10277 |
LOCK operation contains the heavyweight information required to |
| 10278 |
establish a byte-range lock and uniquely define the owner of the |
| 10279 |
lock. |
| 10280 |
|
| 10281 |
<span class="h4"><a class="selflink" id="section-9.1.1" href="#section-9.1.1">9.1.1</a>. State-Owner Definition</span> |
| 10282 |
|
| 10283 |
When opening a file or requesting a byte-range lock, the client must |
| 10284 |
specify an identifier that represents the owner of the requested |
| 10285 |
lock. This identifier is in the form of a state-owner, represented |
| 10286 |
in the protocol by a state_owner4, a variable-length opaque array |
| 10287 |
that, when concatenated with the current client ID, uniquely defines |
| 10288 |
the owner of a lock managed by the client. This may be a thread ID, |
| 10289 |
process ID, or other unique value. |
| 10290 |
|
| 10291 |
Owners of opens and owners of byte-range locks are separate entities |
| 10292 |
and remain separate even if the same opaque arrays are used to |
| 10293 |
designate owners of each. The protocol distinguishes between open- |
| 10294 |
owners (represented by open_owner4 structures) and lock-owners |
| 10295 |
(represented by lock_owner4 structures). |
| 10296 |
|
| 10297 |
|
| 10298 |
|
| 10299 |
|
| 10300 |
<span class="grey">Shepler, et al. Standards Track [Page 184]</span></pre> |
| 10301 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-185" ></span> |
| 10302 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10303 |
|
| 10304 |
|
| 10305 |
Each open is associated with a specific open-owner while each byte- |
| 10306 |
range lock is associated with a lock-owner and an open-owner, the |
| 10307 |
latter being the open-owner associated with the open file under which |
| 10308 |
the LOCK operation was done. Delegations and layouts, on the other |
| 10309 |
hand, are not associated with a specific owner but are associated |
| 10310 |
with the client as a whole (identified by a client ID). |
| 10311 |
|
| 10312 |
<span class="h4"><a class="selflink" id="section-9.1.2" href="#section-9.1.2">9.1.2</a>. Use of the Stateid and Locking</span> |
| 10313 |
|
| 10314 |
All READ, WRITE, and SETATTR operations contain a stateid. For the |
| 10315 |
purposes of this section, SETATTR operations that change the size |
| 10316 |
attribute of a file are treated as if they are writing the area |
| 10317 |
between the old and new sizes (i.e., the byte-range truncated or |
| 10318 |
added to the file by means of the SETATTR), even where SETATTR is not |
| 10319 |
explicitly mentioned in the text. The stateid passed to one of these |
| 10320 |
operations must be one that represents an open, a set of byte-range |
| 10321 |
locks, or a delegation, or it may be a special stateid representing |
| 10322 |
anonymous access or the special bypass stateid. |
| 10323 |
|
| 10324 |
If the state-owner performs a READ or WRITE operation in a situation |
| 10325 |
in which it has established a byte-range lock or share reservation on |
| 10326 |
the server (any OPEN constitutes a share reservation), the stateid |
| 10327 |
(previously returned by the server) must be used to indicate what |
| 10328 |
locks, including both byte-range locks and share reservations, are |
| 10329 |
held by the state-owner. If no state is established by the client, |
| 10330 |
either a byte-range lock or a share reservation, a special stateid |
| 10331 |
for anonymous state (zero as the value for "other" and "seqid") is |
| 10332 |
used. (See <a href="#section-8.2.3">Section 8.2.3</a> for a description of 'special' stateids in |
| 10333 |
general.) Regardless of whether a stateid for anonymous state or a |
| 10334 |
stateid returned by the server is used, if there is a conflicting |
| 10335 |
share reservation or mandatory byte-range lock held on the file, the |
| 10336 |
server MUST refuse to service the READ or WRITE operation. |
| 10337 |
|
| 10338 |
Share reservations are established by OPEN operations and by their |
| 10339 |
nature are mandatory in that when the OPEN denies READ or WRITE |
| 10340 |
operations, that denial results in such operations being rejected |
| 10341 |
with error NFS4ERR_LOCKED. Byte-range locks may be implemented by |
| 10342 |
the server as either mandatory or advisory, or the choice of |
| 10343 |
mandatory or advisory behavior may be determined by the server on the |
| 10344 |
basis of the file being accessed (for example, some UNIX-based |
| 10345 |
servers support a "mandatory lock bit" on the mode attribute such |
| 10346 |
that if set, byte-range locks are required on the file before I/O is |
| 10347 |
possible). When byte-range locks are advisory, they only prevent the |
| 10348 |
granting of conflicting lock requests and have no effect on READs or |
| 10349 |
WRITEs. Mandatory byte-range locks, however, prevent conflicting I/O |
| 10350 |
operations. When they are attempted, they are rejected with |
| 10351 |
NFS4ERR_LOCKED. When the client gets NFS4ERR_LOCKED on a file for |
| 10352 |
which it knows it has the proper share reservation, it will need to |
| 10353 |
|
| 10354 |
|
| 10355 |
|
| 10356 |
<span class="grey">Shepler, et al. Standards Track [Page 185]</span></pre> |
| 10357 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-186" ></span> |
| 10358 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10359 |
|
| 10360 |
|
| 10361 |
send a LOCK operation on the byte-range of the file that includes the |
| 10362 |
byte-range the I/O was to be performed on, with an appropriate |
| 10363 |
locktype field of the LOCK operation's arguments (i.e., READ*_LT for |
| 10364 |
a READ operation, WRITE*_LT for a WRITE operation). |
| 10365 |
|
| 10366 |
Note that for UNIX environments that support mandatory byte-range |
| 10367 |
locking, the distinction between advisory and mandatory locking is |
| 10368 |
subtle. In fact, advisory and mandatory byte-range locks are exactly |
| 10369 |
the same as far as the APIs and requirements on implementation. If |
| 10370 |
the mandatory lock attribute is set on the file, the server checks to |
| 10371 |
see if the lock-owner has an appropriate shared (READ_LT) or |
| 10372 |
exclusive (WRITE_LT) byte-range lock on the byte-range it wishes to |
| 10373 |
READ from or WRITE to. If there is no appropriate lock, the server |
| 10374 |
checks if there is a conflicting lock (which can be done by |
| 10375 |
attempting to acquire the conflicting lock on behalf of the lock- |
| 10376 |
owner, and if successful, release the lock after the READ or WRITE |
| 10377 |
operation is done), and if there is, the server returns |
| 10378 |
NFS4ERR_LOCKED. |
| 10379 |
|
| 10380 |
For Windows environments, byte-range locks are always mandatory, so |
| 10381 |
the server always checks for byte-range locks during I/O requests. |
| 10382 |
|
| 10383 |
Thus, the LOCK operation does not need to distinguish between |
| 10384 |
advisory and mandatory byte-range locks. It is the server's |
| 10385 |
processing of the READ and WRITE operations that introduces the |
| 10386 |
distinction. |
| 10387 |
|
| 10388 |
Every stateid that is validly passed to READ, WRITE, or SETATTR, with |
| 10389 |
the exception of special stateid values, defines an access mode for |
| 10390 |
the file (i.e., OPEN4_SHARE_ACCESS_READ, OPEN4_SHARE_ACCESS_WRITE, or |
| 10391 |
OPEN4_SHARE_ACCESS_BOTH). |
| 10392 |
|
| 10393 |
o For stateids associated with opens, this is the mode defined by |
| 10394 |
the original OPEN that caused the allocation of the OPEN stateid |
| 10395 |
and as modified by subsequent OPENs and OPEN_DOWNGRADEs for the |
| 10396 |
same open-owner/file pair. |
| 10397 |
|
| 10398 |
o For stateids returned by byte-range LOCK operations, the |
| 10399 |
appropriate mode is the access mode for the OPEN stateid |
| 10400 |
associated with the lock set represented by the stateid. |
| 10401 |
|
| 10402 |
o For delegation stateids, the access mode is based on the type of |
| 10403 |
delegation. |
| 10404 |
|
| 10405 |
When a READ, WRITE, or SETATTR (that specifies the size attribute) |
| 10406 |
operation is done, the operation is subject to checking against the |
| 10407 |
access mode to verify that the operation is appropriate given the |
| 10408 |
stateid with which the operation is associated. |
| 10409 |
|
| 10410 |
|
| 10411 |
|
| 10412 |
<span class="grey">Shepler, et al. Standards Track [Page 186]</span></pre> |
| 10413 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-187" ></span> |
| 10414 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10415 |
|
| 10416 |
|
| 10417 |
In the case of WRITE-type operations (i.e., WRITEs and SETATTRs that |
| 10418 |
set size), the server MUST verify that the access mode allows writing |
| 10419 |
and MUST return an NFS4ERR_OPENMODE error if it does not. In the |
| 10420 |
case of READ, the server may perform the corresponding check on the |
| 10421 |
access mode, or it may choose to allow READ on OPENs for |
| 10422 |
OPEN4_SHARE_ACCESS_WRITE, to accommodate clients whose WRITE |
| 10423 |
implementation may unavoidably do reads (e.g., due to buffer cache |
| 10424 |
constraints). However, even if READs are allowed in these |
| 10425 |
circumstances, the server MUST still check for locks that conflict |
| 10426 |
with the READ (e.g., another OPEN specified OPEN4_SHARE_DENY_READ or |
| 10427 |
OPEN4_SHARE_DENY_BOTH). Note that a server that does enforce the |
| 10428 |
access mode check on READs need not explicitly check for conflicting |
| 10429 |
share reservations since the existence of OPEN for |
| 10430 |
OPEN4_SHARE_ACCESS_READ guarantees that no conflicting share |
| 10431 |
reservation can exist. |
| 10432 |
|
| 10433 |
The READ bypass special stateid (all bits of "other" and "seqid" set |
| 10434 |
to one) indicates a desire to bypass locking checks. The server MAY |
| 10435 |
allow READ operations to bypass locking checks at the server, when |
| 10436 |
this special stateid is used. However, WRITE operations with this |
| 10437 |
special stateid value MUST NOT bypass locking checks and are treated |
| 10438 |
exactly the same as if a special stateid for anonymous state were |
| 10439 |
used. |
| 10440 |
|
| 10441 |
A lock may not be granted while a READ or WRITE operation using one |
| 10442 |
of the special stateids is being performed and the scope of the lock |
| 10443 |
to be granted would conflict with the READ or WRITE operation. This |
| 10444 |
can occur when: |
| 10445 |
|
| 10446 |
o A mandatory byte-range lock is requested with a byte-range that |
| 10447 |
conflicts with the byte-range of the READ or WRITE operation. For |
| 10448 |
the purposes of this paragraph, a conflict occurs when a shared |
| 10449 |
lock is requested and a WRITE operation is being performed, or an |
| 10450 |
exclusive lock is requested and either a READ or a WRITE operation |
| 10451 |
is being performed. |
| 10452 |
|
| 10453 |
o A share reservation is requested that denies reading and/or |
| 10454 |
writing and the corresponding operation is being performed. |
| 10455 |
|
| 10456 |
o A delegation is to be granted and the delegation type would |
| 10457 |
prevent the I/O operation, i.e., READ and WRITE conflict with an |
| 10458 |
OPEN_DELEGATE_WRITE delegation and WRITE conflicts with an |
| 10459 |
OPEN_DELEGATE_READ delegation. |
| 10460 |
|
| 10461 |
When a client holds a delegation, it needs to ensure that the stateid |
| 10462 |
sent conveys the association of operation with the delegation, to |
| 10463 |
avoid the delegation from being avoidably recalled. When the |
| 10464 |
delegation stateid, a stateid open associated with that delegation, |
| 10465 |
|
| 10466 |
|
| 10467 |
|
| 10468 |
<span class="grey">Shepler, et al. Standards Track [Page 187]</span></pre> |
| 10469 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-188" ></span> |
| 10470 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10471 |
|
| 10472 |
|
| 10473 |
or a stateid representing byte-range locks derived from such an open |
| 10474 |
is used, the server knows that the READ, WRITE, or SETATTR does not |
| 10475 |
conflict with the delegation but is sent under the aegis of the |
| 10476 |
delegation. Even though it is possible for the server to determine |
| 10477 |
from the client ID (via the session ID) that the client does in fact |
| 10478 |
have a delegation, the server is not obliged to check this, so using |
| 10479 |
a special stateid can result in avoidable recall of the delegation. |
| 10480 |
|
| 10481 |
<span class="h3"><a class="selflink" id="section-9.2" href="#section-9.2">9.2</a>. Lock Ranges</span> |
| 10482 |
|
| 10483 |
The protocol allows a lock-owner to request a lock with a byte-range |
| 10484 |
and then either upgrade, downgrade, or unlock a sub-range of the |
| 10485 |
initial lock, or a byte-range that overlaps -- fully or partially -- |
| 10486 |
either with that initial lock or a combination of a set of existing |
| 10487 |
locks for the same lock-owner. It is expected that this will be an |
| 10488 |
uncommon type of request. In any case, servers or server file |
| 10489 |
systems may not be able to support sub-range lock semantics. In the |
| 10490 |
event that a server receives a locking request that represents a sub- |
| 10491 |
range of current locking state for the lock-owner, the server is |
| 10492 |
allowed to return the error NFS4ERR_LOCK_RANGE to signify that it |
| 10493 |
does not support sub-range lock operations. Therefore, the client |
| 10494 |
should be prepared to receive this error and, if appropriate, report |
| 10495 |
the error to the requesting application. |
| 10496 |
|
| 10497 |
The client is discouraged from combining multiple independent locking |
| 10498 |
ranges that happen to be adjacent into a single request since the |
| 10499 |
server may not support sub-range requests for reasons related to the |
| 10500 |
recovery of byte-range locking state in the event of server failure. |
| 10501 |
As discussed in <a href="#section-8.4.2">Section 8.4.2</a>, the server may employ certain |
| 10502 |
optimizations during recovery that work effectively only when the |
| 10503 |
client's behavior during lock recovery is similar to the client's |
| 10504 |
locking behavior prior to server failure. |
| 10505 |
|
| 10506 |
<span class="h3"><a class="selflink" id="section-9.3" href="#section-9.3">9.3</a>. Upgrading and Downgrading Locks</span> |
| 10507 |
|
| 10508 |
If a client has a WRITE_LT lock on a byte-range, it can request an |
| 10509 |
atomic downgrade of the lock to a READ_LT lock via the LOCK |
| 10510 |
operation, by setting the type to READ_LT. If the server supports |
| 10511 |
atomic downgrade, the request will succeed. If not, it will return |
| 10512 |
NFS4ERR_LOCK_NOTSUPP. The client should be prepared to receive this |
| 10513 |
error and, if appropriate, report the error to the requesting |
| 10514 |
application. |
| 10515 |
|
| 10516 |
If a client has a READ_LT lock on a byte-range, it can request an |
| 10517 |
atomic upgrade of the lock to a WRITE_LT lock via the LOCK operation |
| 10518 |
by setting the type to WRITE_LT or WRITEW_LT. If the server does not |
| 10519 |
support atomic upgrade, it will return NFS4ERR_LOCK_NOTSUPP. If the |
| 10520 |
upgrade can be achieved without an existing conflict, the request |
| 10521 |
|
| 10522 |
|
| 10523 |
|
| 10524 |
<span class="grey">Shepler, et al. Standards Track [Page 188]</span></pre> |
| 10525 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-189" ></span> |
| 10526 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10527 |
|
| 10528 |
|
| 10529 |
will succeed. Otherwise, the server will return either |
| 10530 |
NFS4ERR_DENIED or NFS4ERR_DEADLOCK. The error NFS4ERR_DEADLOCK is |
| 10531 |
returned if the client sent the LOCK operation with the type set to |
| 10532 |
WRITEW_LT and the server has detected a deadlock. The client should |
| 10533 |
be prepared to receive such errors and, if appropriate, report the |
| 10534 |
error to the requesting application. |
| 10535 |
|
| 10536 |
<span class="h3"><a class="selflink" id="section-9.4" href="#section-9.4">9.4</a>. Stateid Seqid Values and Byte-Range Locks</span> |
| 10537 |
|
| 10538 |
When a LOCK or LOCKU operation is performed, the stateid returned has |
| 10539 |
the same "other" value as the argument's stateid, and a "seqid" value |
| 10540 |
that is incremented (relative to the argument's stateid) to reflect |
| 10541 |
the occurrence of the LOCK or LOCKU operation. The server MUST |
| 10542 |
increment the value of the "seqid" field whenever there is any change |
| 10543 |
to the locking status of any byte offset as described by any of the |
| 10544 |
locks covered by the stateid. A change in locking status includes a |
| 10545 |
change from locked to unlocked or the reverse or a change from being |
| 10546 |
locked for READ_LT to being locked for WRITE_LT or the reverse. |
| 10547 |
|
| 10548 |
When there is no such change, as, for example, when a range already |
| 10549 |
locked for WRITE_LT is locked again for WRITE_LT, the server MAY |
| 10550 |
increment the "seqid" value. |
| 10551 |
|
| 10552 |
<span class="h3"><a class="selflink" id="section-9.5" href="#section-9.5">9.5</a>. Issues with Multiple Open-Owners</span> |
| 10553 |
|
| 10554 |
When the same file is opened by multiple open-owners, a client will |
| 10555 |
have multiple OPEN stateids for that file, each associated with a |
| 10556 |
different open-owner. In that case, there can be multiple LOCK and |
| 10557 |
LOCKU requests for the same lock-owner sent using the different OPEN |
| 10558 |
stateids, and so a situation may arise in which there are multiple |
| 10559 |
stateids, each representing byte-range locks on the same file and |
| 10560 |
held by the same lock-owner but each associated with a different |
| 10561 |
open-owner. |
| 10562 |
|
| 10563 |
In such a situation, the locking status of each byte (i.e., whether |
| 10564 |
it is locked, the READ_LT or WRITE_LT type of the lock, and the lock- |
| 10565 |
owner holding the lock) MUST reflect the last LOCK or LOCKU operation |
| 10566 |
done for the lock-owner in question, independent of the stateid |
| 10567 |
through which the request was sent. |
| 10568 |
|
| 10569 |
When a byte is locked by the lock-owner in question, the open-owner |
| 10570 |
to which that byte-range lock is assigned SHOULD be that of the open- |
| 10571 |
owner associated with the stateid through which the last LOCK of that |
| 10572 |
byte was done. When there is a change in the open-owner associated |
| 10573 |
with locks for the stateid through which a LOCK or LOCKU was done, |
| 10574 |
the "seqid" field of the stateid MUST be incremented, even if the |
| 10575 |
locking, in terms of lock-owners has not changed. When there is a |
| 10576 |
|
| 10577 |
|
| 10578 |
|
| 10579 |
|
| 10580 |
<span class="grey">Shepler, et al. Standards Track [Page 189]</span></pre> |
| 10581 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-190" ></span> |
| 10582 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10583 |
|
| 10584 |
|
| 10585 |
change to the set of locked bytes associated with a different stateid |
| 10586 |
for the same lock-owner, i.e., associated with a different open- |
| 10587 |
owner, the "seqid" value for that stateid MUST NOT be incremented. |
| 10588 |
|
| 10589 |
<span class="h3"><a class="selflink" id="section-9.6" href="#section-9.6">9.6</a>. Blocking Locks</span> |
| 10590 |
|
| 10591 |
Some clients require the support of blocking locks. While NFSv4.1 |
| 10592 |
provides a callback when a previously unavailable lock becomes |
| 10593 |
available, this is an OPTIONAL feature and clients cannot depend on |
| 10594 |
its presence. Clients need to be prepared to continually poll for |
| 10595 |
the lock. This presents a fairness problem. Two of the lock types, |
| 10596 |
READW_LT and WRITEW_LT, are used to indicate to the server that the |
| 10597 |
client is requesting a blocking lock. When the callback is not used, |
| 10598 |
the server should maintain an ordered list of pending blocking locks. |
| 10599 |
When the conflicting lock is released, the server may wait for the |
| 10600 |
period of time equal to lease_time for the first waiting client to |
| 10601 |
re-request the lock. After the lease period expires, the next |
| 10602 |
waiting client request is allowed the lock. Clients are required to |
| 10603 |
poll at an interval sufficiently small that it is likely to acquire |
| 10604 |
the lock in a timely manner. The server is not required to maintain |
| 10605 |
a list of pending blocked locks as it is used to increase fairness |
| 10606 |
and not correct operation. Because of the unordered nature of crash |
| 10607 |
recovery, storing of lock state to stable storage would be required |
| 10608 |
to guarantee ordered granting of blocking locks. |
| 10609 |
|
| 10610 |
Servers may also note the lock types and delay returning denial of |
| 10611 |
the request to allow extra time for a conflicting lock to be |
| 10612 |
released, allowing a successful return. In this way, clients can |
| 10613 |
avoid the burden of needless frequent polling for blocking locks. |
| 10614 |
The server should take care in the length of delay in the event the |
| 10615 |
client retransmits the request. |
| 10616 |
|
| 10617 |
If a server receives a blocking LOCK operation, denies it, and then |
| 10618 |
later receives a nonblocking request for the same lock, which is also |
| 10619 |
denied, then it should remove the lock in question from its list of |
| 10620 |
pending blocking locks. Clients should use such a nonblocking |
| 10621 |
request to indicate to the server that this is the last time they |
| 10622 |
intend to poll for the lock, as may happen when the process |
| 10623 |
requesting the lock is interrupted. This is a courtesy to the |
| 10624 |
server, to prevent it from unnecessarily waiting a lease period |
| 10625 |
before granting other LOCK operations. However, clients are not |
| 10626 |
required to perform this courtesy, and servers must not depend on |
| 10627 |
them doing so. Also, clients must be prepared for the possibility |
| 10628 |
that this final locking request will be accepted. |
| 10629 |
|
| 10630 |
When a server indicates, via the flag OPEN4_RESULT_MAY_NOTIFY_LOCK, |
| 10631 |
that CB_NOTIFY_LOCK callbacks might be done for the current open |
| 10632 |
file, the client should take notice of this, but, since this is a |
| 10633 |
|
| 10634 |
|
| 10635 |
|
| 10636 |
<span class="grey">Shepler, et al. Standards Track [Page 190]</span></pre> |
| 10637 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-191" ></span> |
| 10638 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10639 |
|
| 10640 |
|
| 10641 |
hint, cannot rely on a CB_NOTIFY_LOCK always being done. A client |
| 10642 |
may reasonably reduce the frequency with which it polls for a denied |
| 10643 |
lock, since the greater latency that might occur is likely to be |
| 10644 |
eliminated given a prompt callback, but it still needs to poll. When |
| 10645 |
it receives a CB_NOTIFY_LOCK, it should promptly try to obtain the |
| 10646 |
lock, but it should be aware that other clients may be polling and |
| 10647 |
that the server is under no obligation to reserve the lock for that |
| 10648 |
particular client. |
| 10649 |
|
| 10650 |
<span class="h3"><a class="selflink" id="section-9.7" href="#section-9.7">9.7</a>. Share Reservations</span> |
| 10651 |
|
| 10652 |
A share reservation is a mechanism to control access to a file. It |
| 10653 |
is a separate and independent mechanism from byte-range locking. |
| 10654 |
When a client opens a file, it sends an OPEN operation to the server |
| 10655 |
specifying the type of access required (READ, WRITE, or BOTH) and the |
| 10656 |
type of access to deny others (OPEN4_SHARE_DENY_NONE, |
| 10657 |
OPEN4_SHARE_DENY_READ, OPEN4_SHARE_DENY_WRITE, or |
| 10658 |
OPEN4_SHARE_DENY_BOTH). If the OPEN fails, the client will fail the |
| 10659 |
application's open request. |
| 10660 |
|
| 10661 |
Pseudo-code definition of the semantics: |
| 10662 |
|
| 10663 |
if (request.access == 0) { |
| 10664 |
return (NFS4ERR_INVAL) |
| 10665 |
} else { |
| 10666 |
if ((request.access & file_state.deny)) || |
| 10667 |
(request.deny & file_state.access)) { |
| 10668 |
return (NFS4ERR_SHARE_DENIED) |
| 10669 |
} |
| 10670 |
return (NFS4ERR_OK); |
| 10671 |
|
| 10672 |
When doing this checking of share reservations on OPEN, the current |
| 10673 |
file_state used in the algorithm includes bits that reflect all |
| 10674 |
current opens, including those for the open-owner making the new OPEN |
| 10675 |
request. |
| 10676 |
|
| 10677 |
The constants used for the OPEN and OPEN_DOWNGRADE operations for the |
| 10678 |
access and deny fields are as follows: |
| 10679 |
|
| 10680 |
const OPEN4_SHARE_ACCESS_READ = 0x00000001; |
| 10681 |
const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; |
| 10682 |
const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; |
| 10683 |
|
| 10684 |
const OPEN4_SHARE_DENY_NONE = 0x00000000; |
| 10685 |
const OPEN4_SHARE_DENY_READ = 0x00000001; |
| 10686 |
const OPEN4_SHARE_DENY_WRITE = 0x00000002; |
| 10687 |
const OPEN4_SHARE_DENY_BOTH = 0x00000003; |
| 10688 |
|
| 10689 |
|
| 10690 |
|
| 10691 |
|
| 10692 |
<span class="grey">Shepler, et al. Standards Track [Page 191]</span></pre> |
| 10693 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-192" ></span> |
| 10694 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10695 |
|
| 10696 |
|
| 10697 |
<span class="h3"><a class="selflink" id="section-9.8" href="#section-9.8">9.8</a>. OPEN/CLOSE Operations</span> |
| 10698 |
|
| 10699 |
To provide correct share semantics, a client MUST use the OPEN |
| 10700 |
operation to obtain the initial filehandle and indicate the desired |
| 10701 |
access and what access, if any, to deny. Even if the client intends |
| 10702 |
to use a special stateid for anonymous state or READ bypass, it must |
| 10703 |
still obtain the filehandle for the regular file with the OPEN |
| 10704 |
operation so the appropriate share semantics can be applied. Clients |
| 10705 |
that do not have a deny mode built into their programming interfaces |
| 10706 |
for opening a file should request a deny mode of |
| 10707 |
OPEN4_SHARE_DENY_NONE. |
| 10708 |
|
| 10709 |
The OPEN operation with the CREATE flag also subsumes the CREATE |
| 10710 |
operation for regular files as used in previous versions of the NFS |
| 10711 |
protocol. This allows a create with a share to be done atomically. |
| 10712 |
|
| 10713 |
The CLOSE operation removes all share reservations held by the open- |
| 10714 |
owner on that file. If byte-range locks are held, the client SHOULD |
| 10715 |
release all locks before sending a CLOSE operation. The server MAY |
| 10716 |
free all outstanding locks on CLOSE, but some servers may not support |
| 10717 |
the CLOSE of a file that still has byte-range locks held. The server |
| 10718 |
MUST return failure, NFS4ERR_LOCKS_HELD, if any locks would exist |
| 10719 |
after the CLOSE. |
| 10720 |
|
| 10721 |
The LOOKUP operation will return a filehandle without establishing |
| 10722 |
any lock state on the server. Without a valid stateid, the server |
| 10723 |
will assume that the client has the least access. For example, if |
| 10724 |
one client opened a file with OPEN4_SHARE_DENY_BOTH and another |
| 10725 |
client accesses the file via a filehandle obtained through LOOKUP, |
| 10726 |
the second client could only read the file using the special read |
| 10727 |
bypass stateid. The second client could not WRITE the file at all |
| 10728 |
because it would not have a valid stateid from OPEN and the special |
| 10729 |
anonymous stateid would not be allowed access. |
| 10730 |
|
| 10731 |
<span class="h3"><a class="selflink" id="section-9.9" href="#section-9.9">9.9</a>. Open Upgrade and Downgrade</span> |
| 10732 |
|
| 10733 |
When an OPEN is done for a file and the open-owner for which the OPEN |
| 10734 |
is being done already has the file open, the result is to upgrade the |
| 10735 |
open file status maintained on the server to include the access and |
| 10736 |
deny bits specified by the new OPEN as well as those for the existing |
| 10737 |
OPEN. The result is that there is one open file, as far as the |
| 10738 |
protocol is concerned, and it includes the union of the access and |
| 10739 |
deny bits for all of the OPEN requests completed. The OPEN is |
| 10740 |
represented by a single stateid whose "other" value matches that of |
| 10741 |
the original open, and whose "seqid" value is incremented to reflect |
| 10742 |
the occurrence of the upgrade. The increment is required in cases in |
| 10743 |
which the "upgrade" results in no change to the open mode (e.g., an |
| 10744 |
OPEN is done for read when the existing open file is opened for |
| 10745 |
|
| 10746 |
|
| 10747 |
|
| 10748 |
<span class="grey">Shepler, et al. Standards Track [Page 192]</span></pre> |
| 10749 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-193" ></span> |
| 10750 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10751 |
|
| 10752 |
|
| 10753 |
OPEN4_SHARE_ACCESS_BOTH). Only a single CLOSE will be done to reset |
| 10754 |
the effects of both OPENs. The client may use the stateid returned |
| 10755 |
by the OPEN effecting the upgrade or with a stateid sharing the same |
| 10756 |
"other" field and a seqid of zero, although care needs to be taken as |
| 10757 |
far as upgrades that happen while the CLOSE is pending. Note that |
| 10758 |
the client, when sending the OPEN, may not know that the same file is |
| 10759 |
in fact being opened. The above only applies if both OPENs result in |
| 10760 |
the OPENed object being designated by the same filehandle. |
| 10761 |
|
| 10762 |
When the server chooses to export multiple filehandles corresponding |
| 10763 |
to the same file object and returns different filehandles on two |
| 10764 |
different OPENs of the same file object, the server MUST NOT "OR" |
| 10765 |
together the access and deny bits and coalesce the two open files. |
| 10766 |
Instead, the server must maintain separate OPENs with separate |
| 10767 |
stateids and will require separate CLOSEs to free them. |
| 10768 |
|
| 10769 |
When multiple open files on the client are merged into a single OPEN |
| 10770 |
file object on the server, the close of one of the open files (on the |
| 10771 |
client) may necessitate change of the access and deny status of the |
| 10772 |
open file on the server. This is because the union of the access and |
| 10773 |
deny bits for the remaining opens may be smaller (i.e., a proper |
| 10774 |
subset) than previously. The OPEN_DOWNGRADE operation is used to |
| 10775 |
make the necessary change and the client should use it to update the |
| 10776 |
server so that share reservation requests by other clients are |
| 10777 |
handled properly. The stateid returned has the same "other" field as |
| 10778 |
that passed to the server. The "seqid" value in the returned stateid |
| 10779 |
MUST be incremented, even in situations in which there is no change |
| 10780 |
to the access and deny bits for the file. |
| 10781 |
|
| 10782 |
<span class="h3"><a class="selflink" id="section-9.10" href="#section-9.10">9.10</a>. Parallel OPENs</span> |
| 10783 |
|
| 10784 |
Unlike the case of NFSv4.0, in which OPEN operations for the same |
| 10785 |
open-owner are inherently serialized because of the owner-based |
| 10786 |
seqid, multiple OPENs for the same open-owner may be done in |
| 10787 |
parallel. When clients do this, they may encounter situations in |
| 10788 |
which, because of the existence of hard links, two OPEN operations |
| 10789 |
may turn out to open the same file, with a later OPEN performed being |
| 10790 |
an upgrade of the first, with this fact only visible to the client |
| 10791 |
once the operations complete. |
| 10792 |
|
| 10793 |
In this situation, clients may determine the order in which the OPENs |
| 10794 |
were performed by examining the stateids returned by the OPENs. |
| 10795 |
Stateids that share a common value of the "other" field can be |
| 10796 |
recognized as having opened the same file, with the order of the |
| 10797 |
operations determinable from the order of the "seqid" fields, mod any |
| 10798 |
possible wraparound of the 32-bit field. |
| 10799 |
|
| 10800 |
|
| 10801 |
|
| 10802 |
|
| 10803 |
|
| 10804 |
<span class="grey">Shepler, et al. Standards Track [Page 193]</span></pre> |
| 10805 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-194" ></span> |
| 10806 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10807 |
|
| 10808 |
|
| 10809 |
When the possibility exists that the client will send multiple OPENs |
| 10810 |
for the same open-owner in parallel, it may be the case that an open |
| 10811 |
upgrade may happen without the client knowing beforehand that this |
| 10812 |
could happen. Because of this possibility, CLOSEs and |
| 10813 |
OPEN_DOWNGRADEs should generally be sent with a non-zero seqid in the |
| 10814 |
stateid, to avoid the possibility that the status change associated |
| 10815 |
with an open upgrade is not inadvertently lost. |
| 10816 |
|
| 10817 |
<span class="h3"><a class="selflink" id="section-9.11" href="#section-9.11">9.11</a>. Reclaim of Open and Byte-Range Locks</span> |
| 10818 |
|
| 10819 |
Special forms of the LOCK and OPEN operations are provided when it is |
| 10820 |
necessary to re-establish byte-range locks or opens after a server |
| 10821 |
failure. |
| 10822 |
|
| 10823 |
o To reclaim existing opens, an OPEN operation is performed using a |
| 10824 |
CLAIM_PREVIOUS. Because the client, in this type of situation, |
| 10825 |
will have already opened the file and have the filehandle of the |
| 10826 |
target file, this operation requires that the current filehandle |
| 10827 |
be the target file, rather than a directory, and no file name is |
| 10828 |
specified. |
| 10829 |
|
| 10830 |
o To reclaim byte-range locks, a LOCK operation with the reclaim |
| 10831 |
parameter set to true is used. |
| 10832 |
|
| 10833 |
Reclaims of opens associated with delegations are discussed in |
| 10834 |
<a href="#section-10.2.1">Section 10.2.1</a>. |
| 10835 |
|
| 10836 |
<span class="h2"><a class="selflink" id="section-10" href="#section-10">10</a>. Client-Side Caching</span> |
| 10837 |
|
| 10838 |
Client-side caching of data, of file attributes, and of file names is |
| 10839 |
essential to providing good performance with the NFS protocol. |
| 10840 |
Providing distributed cache coherence is a difficult problem, and |
| 10841 |
previous versions of the NFS protocol have not attempted it. |
| 10842 |
Instead, several NFS client implementation techniques have been used |
| 10843 |
to reduce the problems that a lack of coherence poses for users. |
| 10844 |
These techniques have not been clearly defined by earlier protocol |
| 10845 |
specifications, and it is often unclear what is valid or invalid |
| 10846 |
client behavior. |
| 10847 |
|
| 10848 |
The NFSv4.1 protocol uses many techniques similar to those that have |
| 10849 |
been used in previous protocol versions. The NFSv4.1 protocol does |
| 10850 |
not provide distributed cache coherence. However, it defines a more |
| 10851 |
limited set of caching guarantees to allow locks and share |
| 10852 |
reservations to be used without destructive interference from client- |
| 10853 |
side caching. |
| 10854 |
|
| 10855 |
|
| 10856 |
|
| 10857 |
|
| 10858 |
|
| 10859 |
|
| 10860 |
<span class="grey">Shepler, et al. Standards Track [Page 194]</span></pre> |
| 10861 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-195" ></span> |
| 10862 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10863 |
|
| 10864 |
|
| 10865 |
In addition, the NFSv4.1 protocol introduces a delegation mechanism, |
| 10866 |
which allows many decisions normally made by the server to be made |
| 10867 |
locally by clients. This mechanism provides efficient support of the |
| 10868 |
common cases where sharing is infrequent or where sharing is read- |
| 10869 |
only. |
| 10870 |
|
| 10871 |
<span class="h3"><a class="selflink" id="section-10.1" href="#section-10.1">10.1</a>. Performance Challenges for Client-Side Caching</span> |
| 10872 |
|
| 10873 |
Caching techniques used in previous versions of the NFS protocol have |
| 10874 |
been successful in providing good performance. However, several |
| 10875 |
scalability challenges can arise when those techniques are used with |
| 10876 |
very large numbers of clients. This is particularly true when |
| 10877 |
clients are geographically distributed, which classically increases |
| 10878 |
the latency for cache revalidation requests. |
| 10879 |
|
| 10880 |
The previous versions of the NFS protocol repeat their file data |
| 10881 |
cache validation requests at the time the file is opened. This |
| 10882 |
behavior can have serious performance drawbacks. A common case is |
| 10883 |
one in which a file is only accessed by a single client. Therefore, |
| 10884 |
sharing is infrequent. |
| 10885 |
|
| 10886 |
In this case, repeated references to the server to find that no |
| 10887 |
conflicts exist are expensive. A better option with regards to |
| 10888 |
performance is to allow a client that repeatedly opens a file to do |
| 10889 |
so without reference to the server. This is done until potentially |
| 10890 |
conflicting operations from another client actually occur. |
| 10891 |
|
| 10892 |
A similar situation arises in connection with byte-range locking. |
| 10893 |
Sending LOCK and LOCKU operations as well as the READ and WRITE |
| 10894 |
operations necessary to make data caching consistent with the locking |
| 10895 |
semantics (see <a href="#section-10.3.2">Section 10.3.2</a>) can severely limit performance. When |
| 10896 |
locking is used to provide protection against infrequent conflicts, a |
| 10897 |
large penalty is incurred. This penalty may discourage the use of |
| 10898 |
byte-range locking by applications. |
| 10899 |
|
| 10900 |
The NFSv4.1 protocol provides more aggressive caching strategies with |
| 10901 |
the following design goals: |
| 10902 |
|
| 10903 |
o Compatibility with a large range of server semantics. |
| 10904 |
|
| 10905 |
o Providing the same caching benefits as previous versions of the |
| 10906 |
NFS protocol when unable to support the more aggressive model. |
| 10907 |
|
| 10908 |
o Requirements for aggressive caching are organized so that a large |
| 10909 |
portion of the benefit can be obtained even when not all of the |
| 10910 |
requirements can be met. |
| 10911 |
|
| 10912 |
|
| 10913 |
|
| 10914 |
|
| 10915 |
|
| 10916 |
<span class="grey">Shepler, et al. Standards Track [Page 195]</span></pre> |
| 10917 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-196" ></span> |
| 10918 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10919 |
|
| 10920 |
|
| 10921 |
The appropriate requirements for the server are discussed in later |
| 10922 |
sections in which specific forms of caching are covered (see |
| 10923 |
<a href="#section-10.4">Section 10.4</a>). |
| 10924 |
|
| 10925 |
<span class="h3"><a class="selflink" id="section-10.2" href="#section-10.2">10.2</a>. Delegation and Callbacks</span> |
| 10926 |
|
| 10927 |
Recallable delegation of server responsibilities for a file to a |
| 10928 |
client improves performance by avoiding repeated requests to the |
| 10929 |
server in the absence of inter-client conflict. With the use of a |
| 10930 |
"callback" RPC from server to client, a server recalls delegated |
| 10931 |
responsibilities when another client engages in sharing of a |
| 10932 |
delegated file. |
| 10933 |
|
| 10934 |
A delegation is passed from the server to the client, specifying the |
| 10935 |
object of the delegation and the type of delegation. There are |
| 10936 |
different types of delegations, but each type contains a stateid to |
| 10937 |
be used to represent the delegation when performing operations that |
| 10938 |
depend on the delegation. This stateid is similar to those |
| 10939 |
associated with locks and share reservations but differs in that the |
| 10940 |
stateid for a delegation is associated with a client ID and may be |
| 10941 |
used on behalf of all the open-owners for the given client. A |
| 10942 |
delegation is made to the client as a whole and not to any specific |
| 10943 |
process or thread of control within it. |
| 10944 |
|
| 10945 |
The backchannel is established by CREATE_SESSION and |
| 10946 |
BIND_CONN_TO_SESSION, and the client is required to maintain it. |
| 10947 |
Because the backchannel may be down, even temporarily, correct |
| 10948 |
protocol operation does not depend on them. Preliminary testing of |
| 10949 |
backchannel functionality by means of a CB_COMPOUND procedure with a |
| 10950 |
single operation, CB_SEQUENCE, can be used to check the continuity of |
| 10951 |
the backchannel. A server avoids delegating responsibilities until |
| 10952 |
it has determined that the backchannel exists. Because the granting |
| 10953 |
of a delegation is always conditional upon the absence of conflicting |
| 10954 |
access, clients MUST NOT assume that a delegation will be granted and |
| 10955 |
they MUST always be prepared for OPENs, WANT_DELEGATIONs, and |
| 10956 |
GET_DIR_DELEGATIONs to be processed without any delegations being |
| 10957 |
granted. |
| 10958 |
|
| 10959 |
Unlike locks, an operation by a second client to a delegated file |
| 10960 |
will cause the server to recall a delegation through a callback. For |
| 10961 |
individual operations, we will describe, under IMPLEMENTATION, when |
| 10962 |
such operations are required to effect a recall. A number of points |
| 10963 |
should be noted, however. |
| 10964 |
|
| 10965 |
o The server is free to recall a delegation whenever it feels it is |
| 10966 |
desirable and may do so even if no operations requiring recall are |
| 10967 |
being done. |
| 10968 |
|
| 10969 |
|
| 10970 |
|
| 10971 |
|
| 10972 |
<span class="grey">Shepler, et al. Standards Track [Page 196]</span></pre> |
| 10973 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-197" ></span> |
| 10974 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 10975 |
|
| 10976 |
|
| 10977 |
o Operations done outside the NFSv4.1 protocol, due to, for example, |
| 10978 |
access by other protocols, or by local access, also need to result |
| 10979 |
in delegation recall when they make analogous changes to file |
| 10980 |
system data. What is crucial is if the change would invalidate |
| 10981 |
the guarantees provided by the delegation. When this is possible, |
| 10982 |
the delegation needs to be recalled and MUST be returned or |
| 10983 |
revoked before allowing the operation to proceed. |
| 10984 |
|
| 10985 |
o The semantics of the file system are crucial in defining when |
| 10986 |
delegation recall is required. If a particular change within a |
| 10987 |
specific implementation causes change to a file attribute, then |
| 10988 |
delegation recall is required, whether that operation has been |
| 10989 |
specifically listed as requiring delegation recall. Again, what |
| 10990 |
is critical is whether the guarantees provided by the delegation |
| 10991 |
are being invalidated. |
| 10992 |
|
| 10993 |
Despite those caveats, the implementation sections for a number of |
| 10994 |
operations describe situations in which delegation recall would be |
| 10995 |
required under some common circumstances: |
| 10996 |
|
| 10997 |
o For GETATTR, see <a href="#section-18.7.4">Section 18.7.4</a>. |
| 10998 |
|
| 10999 |
o For OPEN, see <a href="#section-18.16.4">Section 18.16.4</a>. |
| 11000 |
|
| 11001 |
o For READ, see <a href="#section-18.22.4">Section 18.22.4</a>. |
| 11002 |
|
| 11003 |
o For REMOVE, see <a href="#section-18.25.4">Section 18.25.4</a>. |
| 11004 |
|
| 11005 |
o For RENAME, see <a href="#section-18.26.4">Section 18.26.4</a>. |
| 11006 |
|
| 11007 |
o For SETATTR, see <a href="#section-18.30.4">Section 18.30.4</a>. |
| 11008 |
|
| 11009 |
o For WRITE, see <a href="#section-18.32.4">Section 18.32.4</a>. |
| 11010 |
|
| 11011 |
On recall, the client holding the delegation needs to flush modified |
| 11012 |
state (such as modified data) to the server and return the |
| 11013 |
delegation. The conflicting request will not be acted on until the |
| 11014 |
recall is complete. The recall is considered complete when the |
| 11015 |
client returns the delegation or the server times its wait for the |
| 11016 |
delegation to be returned and revokes the delegation as a result of |
| 11017 |
the timeout. In the interim, the server will either delay responding |
| 11018 |
to conflicting requests or respond to them with NFS4ERR_DELAY. |
| 11019 |
Following the resolution of the recall, the server has the |
| 11020 |
information necessary to grant or deny the second client's request. |
| 11021 |
|
| 11022 |
At the time the client receives a delegation recall, it may have |
| 11023 |
substantial state that needs to be flushed to the server. Therefore, |
| 11024 |
the server should allow sufficient time for the delegation to be |
| 11025 |
|
| 11026 |
|
| 11027 |
|
| 11028 |
<span class="grey">Shepler, et al. Standards Track [Page 197]</span></pre> |
| 11029 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-198" ></span> |
| 11030 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11031 |
|
| 11032 |
|
| 11033 |
returned since it may involve numerous RPCs to the server. If the |
| 11034 |
server is able to determine that the client is diligently flushing |
| 11035 |
state to the server as a result of the recall, the server may extend |
| 11036 |
the usual time allowed for a recall. However, the time allowed for |
| 11037 |
recall completion should not be unbounded. |
| 11038 |
|
| 11039 |
An example of this is when responsibility to mediate opens on a given |
| 11040 |
file is delegated to a client (see <a href="#section-10.4">Section 10.4</a>). The server will |
| 11041 |
not know what opens are in effect on the client. Without this |
| 11042 |
knowledge, the server will be unable to determine if the access and |
| 11043 |
deny states for the file allow any particular open until the |
| 11044 |
delegation for the file has been returned. |
| 11045 |
|
| 11046 |
A client failure or a network partition can result in failure to |
| 11047 |
respond to a recall callback. In this case, the server will revoke |
| 11048 |
the delegation, which in turn will render useless any modified state |
| 11049 |
still on the client. |
| 11050 |
|
| 11051 |
<span class="h4"><a class="selflink" id="section-10.2.1" href="#section-10.2.1">10.2.1</a>. Delegation Recovery</span> |
| 11052 |
|
| 11053 |
There are three situations that delegation recovery needs to deal |
| 11054 |
with: |
| 11055 |
|
| 11056 |
o client restart |
| 11057 |
|
| 11058 |
o server restart |
| 11059 |
|
| 11060 |
o network partition (full or backchannel-only) |
| 11061 |
|
| 11062 |
In the event the client restarts, the failure to renew the lease will |
| 11063 |
result in the revocation of byte-range locks and share reservations. |
| 11064 |
Delegations, however, may be treated a bit differently. |
| 11065 |
|
| 11066 |
There will be situations in which delegations will need to be re- |
| 11067 |
established after a client restarts. The reason for this is that the |
| 11068 |
client may have file data stored locally and this data was associated |
| 11069 |
with the previously held delegations. The client will need to re- |
| 11070 |
establish the appropriate file state on the server. |
| 11071 |
|
| 11072 |
To allow for this type of client recovery, the server MAY extend the |
| 11073 |
period for delegation recovery beyond the typical lease expiration |
| 11074 |
period. This implies that requests from other clients that conflict |
| 11075 |
with these delegations will need to wait. Because the normal recall |
| 11076 |
process may require significant time for the client to flush changed |
| 11077 |
state to the server, other clients need be prepared for delays that |
| 11078 |
occur because of a conflicting delegation. This longer interval |
| 11079 |
would increase the window for clients to restart and consult stable |
| 11080 |
storage so that the delegations can be reclaimed. For OPEN |
| 11081 |
|
| 11082 |
|
| 11083 |
|
| 11084 |
<span class="grey">Shepler, et al. Standards Track [Page 198]</span></pre> |
| 11085 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-199" ></span> |
| 11086 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11087 |
|
| 11088 |
|
| 11089 |
delegations, such delegations are reclaimed using OPEN with a claim |
| 11090 |
type of CLAIM_DELEGATE_PREV or CLAIM_DELEG_PREV_FH (see Sections <a href="#section-10.5">10.5</a> |
| 11091 |
and 18.16 for discussion of OPEN delegation and the details of OPEN, |
| 11092 |
respectively). |
| 11093 |
|
| 11094 |
A server MAY support claim types of CLAIM_DELEGATE_PREV and |
| 11095 |
CLAIM_DELEG_PREV_FH, and if it does, it MUST NOT remove delegations |
| 11096 |
upon a CREATE_SESSION that confirm a client ID created by |
| 11097 |
EXCHANGE_ID. Instead, the server MUST, for a period of time no less |
| 11098 |
than that of the value of the lease_time attribute, maintain the |
| 11099 |
client's delegations to allow time for the client to send |
| 11100 |
CLAIM_DELEGATE_PREV and/or CLAIM_DELEG_PREV_FH requests. The server |
| 11101 |
that supports CLAIM_DELEGATE_PREV and/or CLAIM_DELEG_PREV_FH MUST |
| 11102 |
support the DELEGPURGE operation. |
| 11103 |
|
| 11104 |
When the server restarts, delegations are reclaimed (using the OPEN |
| 11105 |
operation with CLAIM_PREVIOUS) in a similar fashion to byte-range |
| 11106 |
locks and share reservations. However, there is a slight semantic |
| 11107 |
difference. In the normal case, if the server decides that a |
| 11108 |
delegation should not be granted, it performs the requested action |
| 11109 |
(e.g., OPEN) without granting any delegation. For reclaim, the |
| 11110 |
server grants the delegation but a special designation is applied so |
| 11111 |
that the client treats the delegation as having been granted but |
| 11112 |
recalled by the server. Because of this, the client has the duty to |
| 11113 |
write all modified state to the server and then return the |
| 11114 |
delegation. This process of handling delegation reclaim reconciles |
| 11115 |
three principles of the NFSv4.1 protocol: |
| 11116 |
|
| 11117 |
o Upon reclaim, a client reporting resources assigned to it by an |
| 11118 |
earlier server instance must be granted those resources. |
| 11119 |
|
| 11120 |
o The server has unquestionable authority to determine whether |
| 11121 |
delegations are to be granted and, once granted, whether they are |
| 11122 |
to be continued. |
| 11123 |
|
| 11124 |
o The use of callbacks should not be depended upon until the client |
| 11125 |
has proven its ability to receive them. |
| 11126 |
|
| 11127 |
When a client needs to reclaim a delegation and there is no |
| 11128 |
associated open, the client may use the CLAIM_PREVIOUS variant of the |
| 11129 |
WANT_DELEGATION operation. However, since the server is not required |
| 11130 |
to support this operation, an alternative is to reclaim via a dummy |
| 11131 |
OPEN together with the delegation using an OPEN of type |
| 11132 |
CLAIM_PREVIOUS. The dummy open file can be released using a CLOSE to |
| 11133 |
re-establish the original state to be reclaimed, a delegation without |
| 11134 |
an associated open. |
| 11135 |
|
| 11136 |
|
| 11137 |
|
| 11138 |
|
| 11139 |
|
| 11140 |
<span class="grey">Shepler, et al. Standards Track [Page 199]</span></pre> |
| 11141 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-200" ></span> |
| 11142 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11143 |
|
| 11144 |
|
| 11145 |
When a client has more than a single open associated with a |
| 11146 |
delegation, state for those additional opens can be established using |
| 11147 |
OPEN operations of type CLAIM_DELEGATE_CUR. When these are used to |
| 11148 |
establish opens associated with reclaimed delegations, the server |
| 11149 |
MUST allow them when made within the grace period. |
| 11150 |
|
| 11151 |
When a network partition occurs, delegations are subject to freeing |
| 11152 |
by the server when the lease renewal period expires. This is similar |
| 11153 |
to the behavior for locks and share reservations. For delegations, |
| 11154 |
however, the server may extend the period in which conflicting |
| 11155 |
requests are held off. Eventually, the occurrence of a conflicting |
| 11156 |
request from another client will cause revocation of the delegation. |
| 11157 |
A loss of the backchannel (e.g., by later network configuration |
| 11158 |
change) will have the same effect. A recall request will fail and |
| 11159 |
revocation of the delegation will result. |
| 11160 |
|
| 11161 |
A client normally finds out about revocation of a delegation when it |
| 11162 |
uses a stateid associated with a delegation and receives one of the |
| 11163 |
errors NFS4ERR_EXPIRED, NFS4ERR_ADMIN_REVOKED, or |
| 11164 |
NFS4ERR_DELEG_REVOKED. It also may find out about delegation |
| 11165 |
revocation after a client restart when it attempts to reclaim a |
| 11166 |
delegation and receives that same error. Note that in the case of a |
| 11167 |
revoked OPEN_DELEGATE_WRITE delegation, there are issues because data |
| 11168 |
may have been modified by the client whose delegation is revoked and |
| 11169 |
separately by other clients. See <a href="#section-10.5.1">Section 10.5.1</a> for a discussion of |
| 11170 |
such issues. Note also that when delegations are revoked, |
| 11171 |
information about the revoked delegation will be written by the |
| 11172 |
server to stable storage (as described in <a href="#section-8.4.3">Section 8.4.3</a>). This is |
| 11173 |
done to deal with the case in which a server restarts after revoking |
| 11174 |
a delegation but before the client holding the revoked delegation is |
| 11175 |
notified about the revocation. |
| 11176 |
|
| 11177 |
<span class="h3"><a class="selflink" id="section-10.3" href="#section-10.3">10.3</a>. Data Caching</span> |
| 11178 |
|
| 11179 |
When applications share access to a set of files, they need to be |
| 11180 |
implemented so as to take account of the possibility of conflicting |
| 11181 |
access by another application. This is true whether the applications |
| 11182 |
in question execute on different clients or reside on the same |
| 11183 |
client. |
| 11184 |
|
| 11185 |
Share reservations and byte-range locks are the facilities the |
| 11186 |
NFSv4.1 protocol provides to allow applications to coordinate access |
| 11187 |
by using mutual exclusion facilities. The NFSv4.1 protocol's data |
| 11188 |
caching must be implemented such that it does not invalidate the |
| 11189 |
assumptions on which those using these facilities depend. |
| 11190 |
|
| 11191 |
|
| 11192 |
|
| 11193 |
|
| 11194 |
|
| 11195 |
|
| 11196 |
<span class="grey">Shepler, et al. Standards Track [Page 200]</span></pre> |
| 11197 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-201" ></span> |
| 11198 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11199 |
|
| 11200 |
|
| 11201 |
<span class="h4"><a class="selflink" id="section-10.3.1" href="#section-10.3.1">10.3.1</a>. Data Caching and OPENs</span> |
| 11202 |
|
| 11203 |
In order to avoid invalidating the sharing assumptions on which |
| 11204 |
applications rely, NFSv4.1 clients should not provide cached data to |
| 11205 |
applications or modify it on behalf of an application when it would |
| 11206 |
not be valid to obtain or modify that same data via a READ or WRITE |
| 11207 |
operation. |
| 11208 |
|
| 11209 |
Furthermore, in the absence of an OPEN delegation (see <a href="#section-10.4">Section 10.4</a>), |
| 11210 |
two additional rules apply. Note that these rules are obeyed in |
| 11211 |
practice by many NFSv3 clients. |
| 11212 |
|
| 11213 |
o First, cached data present on a client must be revalidated after |
| 11214 |
doing an OPEN. Revalidating means that the client fetches the |
| 11215 |
change attribute from the server, compares it with the cached |
| 11216 |
change attribute, and if different, declares the cached data (as |
| 11217 |
well as the cached attributes) as invalid. This is to ensure that |
| 11218 |
the data for the OPENed file is still correctly reflected in the |
| 11219 |
client's cache. This validation must be done at least when the |
| 11220 |
client's OPEN operation includes a deny of OPEN4_SHARE_DENY_WRITE |
| 11221 |
or OPEN4_SHARE_DENY_BOTH, thus terminating a period in which other |
| 11222 |
clients may have had the opportunity to open the file with |
| 11223 |
OPEN4_SHARE_ACCESS_WRITE/OPEN4_SHARE_ACCESS_BOTH access. Clients |
| 11224 |
may choose to do the revalidation more often (i.e., at OPENs |
| 11225 |
specifying a deny mode of OPEN4_SHARE_DENY_NONE) to parallel the |
| 11226 |
NFSv3 protocol's practice for the benefit of users assuming this |
| 11227 |
degree of cache revalidation. |
| 11228 |
|
| 11229 |
Since the change attribute is updated for data and metadata |
| 11230 |
modifications, some client implementors may be tempted to use the |
| 11231 |
time_modify attribute and not the change attribute to validate |
| 11232 |
cached data, so that metadata changes do not spuriously invalidate |
| 11233 |
clean data. The implementor is cautioned in this approach. The |
| 11234 |
change attribute is guaranteed to change for each update to the |
| 11235 |
file, whereas time_modify is guaranteed to change only at the |
| 11236 |
granularity of the time_delta attribute. Use by the client's data |
| 11237 |
cache validation logic of time_modify and not change runs the risk |
| 11238 |
of the client incorrectly marking stale data as valid. Thus, any |
| 11239 |
cache validation approach by the client MUST include the use of |
| 11240 |
the change attribute. |
| 11241 |
|
| 11242 |
o Second, modified data must be flushed to the server before closing |
| 11243 |
a file OPENed for OPEN4_SHARE_ACCESS_WRITE. This is complementary |
| 11244 |
to the first rule. If the data is not flushed at CLOSE, the |
| 11245 |
revalidation done after the client OPENs a file is unable to |
| 11246 |
achieve its purpose. The other aspect to flushing the data before |
| 11247 |
close is that the data must be committed to stable storage, at the |
| 11248 |
server, before the CLOSE operation is requested by the client. In |
| 11249 |
|
| 11250 |
|
| 11251 |
|
| 11252 |
<span class="grey">Shepler, et al. Standards Track [Page 201]</span></pre> |
| 11253 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-202" ></span> |
| 11254 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11255 |
|
| 11256 |
|
| 11257 |
the case of a server restart and a CLOSEd file, it may not be |
| 11258 |
possible to retransmit the data to be written to the file, hence, |
| 11259 |
this requirement. |
| 11260 |
|
| 11261 |
<span class="h4"><a class="selflink" id="section-10.3.2" href="#section-10.3.2">10.3.2</a>. Data Caching and File Locking</span> |
| 11262 |
|
| 11263 |
For those applications that choose to use byte-range locking instead |
| 11264 |
of share reservations to exclude inconsistent file access, there is |
| 11265 |
an analogous set of constraints that apply to client-side data |
| 11266 |
caching. These rules are effective only if the byte-range locking is |
| 11267 |
used in a way that matches in an equivalent way the actual READ and |
| 11268 |
WRITE operations executed. This is as opposed to byte-range locking |
| 11269 |
that is based on pure convention. For example, it is possible to |
| 11270 |
manipulate a two-megabyte file by dividing the file into two one- |
| 11271 |
megabyte ranges and protecting access to the two byte-ranges by byte- |
| 11272 |
range locks on bytes zero and one. A WRITE_LT lock on byte zero of |
| 11273 |
the file would represent the right to perform READ and WRITE |
| 11274 |
operations on the first byte-range. A WRITE_LT lock on byte one of |
| 11275 |
the file would represent the right to perform READ and WRITE |
| 11276 |
operations on the second byte-range. As long as all applications |
| 11277 |
manipulating the file obey this convention, they will work on a local |
| 11278 |
file system. However, they may not work with the NFSv4.1 protocol |
| 11279 |
unless clients refrain from data caching. |
| 11280 |
|
| 11281 |
The rules for data caching in the byte-range locking environment are: |
| 11282 |
|
| 11283 |
o First, when a client obtains a byte-range lock for a particular |
| 11284 |
byte-range, the data cache corresponding to that byte-range (if |
| 11285 |
any cache data exists) must be revalidated. If the change |
| 11286 |
attribute indicates that the file may have been updated since the |
| 11287 |
cached data was obtained, the client must flush or invalidate the |
| 11288 |
cached data for the newly locked byte-range. A client might |
| 11289 |
choose to invalidate all of the non-modified cached data that it |
| 11290 |
has for the file, but the only requirement for correct operation |
| 11291 |
is to invalidate all of the data in the newly locked byte-range. |
| 11292 |
|
| 11293 |
o Second, before releasing a WRITE_LT lock for a byte-range, all |
| 11294 |
modified data for that byte-range must be flushed to the server. |
| 11295 |
The modified data must also be written to stable storage. |
| 11296 |
|
| 11297 |
Note that flushing data to the server and the invalidation of cached |
| 11298 |
data must reflect the actual byte-ranges locked or unlocked. |
| 11299 |
Rounding these up or down to reflect client cache block boundaries |
| 11300 |
will cause problems if not carefully done. For example, writing a |
| 11301 |
modified block when only half of that block is within an area being |
| 11302 |
unlocked may cause invalid modification to the byte-range outside the |
| 11303 |
unlocked area. This, in turn, may be part of a byte-range locked by |
| 11304 |
another client. Clients can avoid this situation by synchronously |
| 11305 |
|
| 11306 |
|
| 11307 |
|
| 11308 |
<span class="grey">Shepler, et al. Standards Track [Page 202]</span></pre> |
| 11309 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-203" ></span> |
| 11310 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11311 |
|
| 11312 |
|
| 11313 |
performing portions of WRITE operations that overlap that portion |
| 11314 |
(initial or final) that is not a full block. Similarly, invalidating |
| 11315 |
a locked area that is not an integral number of full buffer blocks |
| 11316 |
would require the client to read one or two partial blocks from the |
| 11317 |
server if the revalidation procedure shows that the data that the |
| 11318 |
client possesses may not be valid. |
| 11319 |
|
| 11320 |
The data that is written to the server as a prerequisite to the |
| 11321 |
unlocking of a byte-range must be written, at the server, to stable |
| 11322 |
storage. The client may accomplish this either with synchronous |
| 11323 |
writes or by following asynchronous writes with a COMMIT operation. |
| 11324 |
This is required because retransmission of the modified data after a |
| 11325 |
server restart might conflict with a lock held by another client. |
| 11326 |
|
| 11327 |
A client implementation may choose to accommodate applications that |
| 11328 |
use byte-range locking in non-standard ways (e.g., using a byte-range |
| 11329 |
lock as a global semaphore) by flushing to the server more data upon |
| 11330 |
a LOCKU than is covered by the locked range. This may include |
| 11331 |
modified data within files other than the one for which the unlocks |
| 11332 |
are being done. In such cases, the client must not interfere with |
| 11333 |
applications whose READs and WRITEs are being done only within the |
| 11334 |
bounds of byte-range locks that the application holds. For example, |
| 11335 |
an application locks a single byte of a file and proceeds to write |
| 11336 |
that single byte. A client that chose to handle a LOCKU by flushing |
| 11337 |
all modified data to the server could validly write that single byte |
| 11338 |
in response to an unrelated LOCKU operation. However, it would not |
| 11339 |
be valid to write the entire block in which that single written byte |
| 11340 |
was located since it includes an area that is not locked and might be |
| 11341 |
locked by another client. Client implementations can avoid this |
| 11342 |
problem by dividing files with modified data into those for which all |
| 11343 |
modifications are done to areas covered by an appropriate byte-range |
| 11344 |
lock and those for which there are modifications not covered by a |
| 11345 |
byte-range lock. Any writes done for the former class of files must |
| 11346 |
not include areas not locked and thus not modified on the client. |
| 11347 |
|
| 11348 |
<span class="h4"><a class="selflink" id="section-10.3.3" href="#section-10.3.3">10.3.3</a>. Data Caching and Mandatory File Locking</span> |
| 11349 |
|
| 11350 |
Client-side data caching needs to respect mandatory byte-range |
| 11351 |
locking when it is in effect. The presence of mandatory byte-range |
| 11352 |
locking for a given file is indicated when the client gets back |
| 11353 |
NFS4ERR_LOCKED from a READ or WRITE operation on a file for which it |
| 11354 |
has an appropriate share reservation. When mandatory locking is in |
| 11355 |
effect for a file, the client must check for an appropriate byte- |
| 11356 |
range lock for data being read or written. If a byte-range lock |
| 11357 |
exists for the range being read or written, the client may satisfy |
| 11358 |
the request using the client's validated cache. If an appropriate |
| 11359 |
byte-range lock is not held for the range of the read or write, the |
| 11360 |
read or write request must not be satisfied by the client's cache and |
| 11361 |
|
| 11362 |
|
| 11363 |
|
| 11364 |
<span class="grey">Shepler, et al. Standards Track [Page 203]</span></pre> |
| 11365 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-204" ></span> |
| 11366 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11367 |
|
| 11368 |
|
| 11369 |
the request must be sent to the server for processing. When a read |
| 11370 |
or write request partially overlaps a locked byte-range, the request |
| 11371 |
should be subdivided into multiple pieces with each byte-range |
| 11372 |
(locked or not) treated appropriately. |
| 11373 |
|
| 11374 |
<span class="h4"><a class="selflink" id="section-10.3.4" href="#section-10.3.4">10.3.4</a>. Data Caching and File Identity</span> |
| 11375 |
|
| 11376 |
When clients cache data, the file data needs to be organized |
| 11377 |
according to the file system object to which the data belongs. For |
| 11378 |
NFSv3 clients, the typical practice has been to assume for the |
| 11379 |
purpose of caching that distinct filehandles represent distinct file |
| 11380 |
system objects. The client then has the choice to organize and |
| 11381 |
maintain the data cache on this basis. |
| 11382 |
|
| 11383 |
In the NFSv4.1 protocol, there is now the possibility to have |
| 11384 |
significant deviations from a "one filehandle per object" model |
| 11385 |
because a filehandle may be constructed on the basis of the object's |
| 11386 |
pathname. Therefore, clients need a reliable method to determine if |
| 11387 |
two filehandles designate the same file system object. If clients |
| 11388 |
were simply to assume that all distinct filehandles denote distinct |
| 11389 |
objects and proceed to do data caching on this basis, caching |
| 11390 |
inconsistencies would arise between the distinct client-side objects |
| 11391 |
that mapped to the same server-side object. |
| 11392 |
|
| 11393 |
By providing a method to differentiate filehandles, the NFSv4.1 |
| 11394 |
protocol alleviates a potential functional regression in comparison |
| 11395 |
with the NFSv3 protocol. Without this method, caching |
| 11396 |
inconsistencies within the same client could occur, and this has not |
| 11397 |
been present in previous versions of the NFS protocol. Note that it |
| 11398 |
is possible to have such inconsistencies with applications executing |
| 11399 |
on multiple clients, but that is not the issue being addressed here. |
| 11400 |
|
| 11401 |
For the purposes of data caching, the following steps allow an |
| 11402 |
NFSv4.1 client to determine whether two distinct filehandles denote |
| 11403 |
the same server-side object: |
| 11404 |
|
| 11405 |
o If GETATTR directed to two filehandles returns different values of |
| 11406 |
the fsid attribute, then the filehandles represent distinct |
| 11407 |
objects. |
| 11408 |
|
| 11409 |
o If GETATTR for any file with an fsid that matches the fsid of the |
| 11410 |
two filehandles in question returns a unique_handles attribute |
| 11411 |
with a value of TRUE, then the two objects are distinct. |
| 11412 |
|
| 11413 |
o If GETATTR directed to the two filehandles does not return the |
| 11414 |
fileid attribute for both of the handles, then it cannot be |
| 11415 |
determined whether the two objects are the same. Therefore, |
| 11416 |
operations that depend on that knowledge (e.g., client-side data |
| 11417 |
|
| 11418 |
|
| 11419 |
|
| 11420 |
<span class="grey">Shepler, et al. Standards Track [Page 204]</span></pre> |
| 11421 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-205" ></span> |
| 11422 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11423 |
|
| 11424 |
|
| 11425 |
caching) cannot be done reliably. Note that if GETATTR does not |
| 11426 |
return the fileid attribute for both filehandles, it will return |
| 11427 |
it for neither of the filehandles, since the fsid for both |
| 11428 |
filehandles is the same. |
| 11429 |
|
| 11430 |
o If GETATTR directed to the two filehandles returns different |
| 11431 |
values for the fileid attribute, then they are distinct objects. |
| 11432 |
|
| 11433 |
o Otherwise, they are the same object. |
| 11434 |
|
| 11435 |
<span class="h3"><a class="selflink" id="section-10.4" href="#section-10.4">10.4</a>. Open Delegation</span> |
| 11436 |
|
| 11437 |
When a file is being OPENed, the server may delegate further handling |
| 11438 |
of opens and closes for that file to the opening client. Any such |
| 11439 |
delegation is recallable since the circumstances that allowed for the |
| 11440 |
delegation are subject to change. In particular, if the server |
| 11441 |
receives a conflicting OPEN from another client, the server must |
| 11442 |
recall the delegation before deciding whether the OPEN from the other |
| 11443 |
client may be granted. Making a delegation is up to the server, and |
| 11444 |
clients should not assume that any particular OPEN either will or |
| 11445 |
will not result in an OPEN delegation. The following is a typical |
| 11446 |
set of conditions that servers might use in deciding whether an OPEN |
| 11447 |
should be delegated: |
| 11448 |
|
| 11449 |
o The client must be able to respond to the server's callback |
| 11450 |
requests. If a backchannel has been established, the server will |
| 11451 |
send a CB_COMPOUND request, containing a single operation, |
| 11452 |
CB_SEQUENCE, for a test of backchannel availability. |
| 11453 |
|
| 11454 |
o The client must have responded properly to previous recalls. |
| 11455 |
|
| 11456 |
o There must be no current OPEN conflicting with the requested |
| 11457 |
delegation. |
| 11458 |
|
| 11459 |
o There should be no current delegation that conflicts with the |
| 11460 |
delegation being requested. |
| 11461 |
|
| 11462 |
o The probability of future conflicting open requests should be low |
| 11463 |
based on the recent history of the file. |
| 11464 |
|
| 11465 |
o The existence of any server-specific semantics of OPEN/CLOSE that |
| 11466 |
would make the required handling incompatible with the prescribed |
| 11467 |
handling that the delegated client would apply (see below). |
| 11468 |
|
| 11469 |
There are two types of OPEN delegations: OPEN_DELEGATE_READ and |
| 11470 |
OPEN_DELEGATE_WRITE. An OPEN_DELEGATE_READ delegation allows a |
| 11471 |
client to handle, on its own, requests to open a file for reading |
| 11472 |
that do not deny OPEN4_SHARE_ACCESS_READ access to others. Multiple |
| 11473 |
|
| 11474 |
|
| 11475 |
|
| 11476 |
<span class="grey">Shepler, et al. Standards Track [Page 205]</span></pre> |
| 11477 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-206" ></span> |
| 11478 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11479 |
|
| 11480 |
|
| 11481 |
OPEN_DELEGATE_READ delegations may be outstanding simultaneously and |
| 11482 |
do not conflict. An OPEN_DELEGATE_WRITE delegation allows the client |
| 11483 |
to handle, on its own, all opens. Only OPEN_DELEGATE_WRITE |
| 11484 |
delegation may exist for a given file at a given time, and it is |
| 11485 |
inconsistent with any OPEN_DELEGATE_READ delegations. |
| 11486 |
|
| 11487 |
When a client has an OPEN_DELEGATE_READ delegation, it is assured |
| 11488 |
that neither the contents, the attributes (with the exception of |
| 11489 |
time_access), nor the names of any links to the file will change |
| 11490 |
without its knowledge, so long as the delegation is held. When a |
| 11491 |
client has an OPEN_DELEGATE_WRITE delegation, it may modify the file |
| 11492 |
data locally since no other client will be accessing the file's data. |
| 11493 |
The client holding an OPEN_DELEGATE_WRITE delegation may only locally |
| 11494 |
affect file attributes that are intimately connected with the file |
| 11495 |
data: size, change, time_access, time_metadata, and time_modify. All |
| 11496 |
other attributes must be reflected on the server. |
| 11497 |
|
| 11498 |
When a client has an OPEN delegation, it does not need to send OPENs |
| 11499 |
or CLOSEs to the server. Instead, the client may update the |
| 11500 |
appropriate status internally. For an OPEN_DELEGATE_READ delegation, |
| 11501 |
opens that cannot be handled locally (opens that are for |
| 11502 |
OPEN4_SHARE_ACCESS_WRITE/OPEN4_SHARE_ACCESS_BOTH or that deny |
| 11503 |
OPEN4_SHARE_ACCESS_READ access) must be sent to the server. |
| 11504 |
|
| 11505 |
When an OPEN delegation is made, the reply to the OPEN contains an |
| 11506 |
OPEN delegation structure that specifies the following: |
| 11507 |
|
| 11508 |
o the type of delegation (OPEN_DELEGATE_READ or |
| 11509 |
OPEN_DELEGATE_WRITE). |
| 11510 |
|
| 11511 |
o space limitation information to control flushing of data on close |
| 11512 |
(OPEN_DELEGATE_WRITE delegation only; see <a href="#section-10.4.1">Section 10.4.1</a>) |
| 11513 |
|
| 11514 |
o an nfsace4 specifying read and write permissions |
| 11515 |
|
| 11516 |
o a stateid to represent the delegation |
| 11517 |
|
| 11518 |
The delegation stateid is separate and distinct from the stateid for |
| 11519 |
the OPEN proper. The standard stateid, unlike the delegation |
| 11520 |
stateid, is associated with a particular lock-owner and will continue |
| 11521 |
to be valid after the delegation is recalled and the file remains |
| 11522 |
open. |
| 11523 |
|
| 11524 |
|
| 11525 |
|
| 11526 |
|
| 11527 |
|
| 11528 |
|
| 11529 |
|
| 11530 |
|
| 11531 |
|
| 11532 |
<span class="grey">Shepler, et al. Standards Track [Page 206]</span></pre> |
| 11533 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-207" ></span> |
| 11534 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11535 |
|
| 11536 |
|
| 11537 |
When a request internal to the client is made to open a file and an |
| 11538 |
OPEN delegation is in effect, it will be accepted or rejected solely |
| 11539 |
on the basis of the following conditions. Any requirement for other |
| 11540 |
checks to be made by the delegate should result in the OPEN |
| 11541 |
delegation being denied so that the checks can be made by the server |
| 11542 |
itself. |
| 11543 |
|
| 11544 |
o The access and deny bits for the request and the file as described |
| 11545 |
in <a href="#section-9.7">Section 9.7</a>. |
| 11546 |
|
| 11547 |
o The read and write permissions as determined below. |
| 11548 |
|
| 11549 |
The nfsace4 passed with delegation can be used to avoid frequent |
| 11550 |
ACCESS calls. The permission check should be as follows: |
| 11551 |
|
| 11552 |
o If the nfsace4 indicates that the open may be done, then it should |
| 11553 |
be granted without reference to the server. |
| 11554 |
|
| 11555 |
o If the nfsace4 indicates that the open may not be done, then an |
| 11556 |
ACCESS request must be sent to the server to obtain the definitive |
| 11557 |
answer. |
| 11558 |
|
| 11559 |
The server may return an nfsace4 that is more restrictive than the |
| 11560 |
actual ACL of the file. This includes an nfsace4 that specifies |
| 11561 |
denial of all access. Note that some common practices such as |
| 11562 |
mapping the traditional user "root" to the user "nobody" (see |
| 11563 |
<a href="#section-5.9">Section 5.9</a>) may make it incorrect to return the actual ACL of the |
| 11564 |
file in the delegation response. |
| 11565 |
|
| 11566 |
The use of a delegation together with various other forms of caching |
| 11567 |
creates the possibility that no server authentication and |
| 11568 |
authorization will ever be performed for a given user since all of |
| 11569 |
the user's requests might be satisfied locally. Where the client is |
| 11570 |
depending on the server for authentication and authorization, the |
| 11571 |
client should be sure authentication and authorization occurs for |
| 11572 |
each user by use of the ACCESS operation. This should be the case |
| 11573 |
even if an ACCESS operation would not be required otherwise. As |
| 11574 |
mentioned before, the server may enforce frequent authentication by |
| 11575 |
returning an nfsace4 denying all access with every OPEN delegation. |
| 11576 |
|
| 11577 |
<span class="h4"><a class="selflink" id="section-10.4.1" href="#section-10.4.1">10.4.1</a>. Open Delegation and Data Caching</span> |
| 11578 |
|
| 11579 |
An OPEN delegation allows much of the message overhead associated |
| 11580 |
with the opening and closing files to be eliminated. An open when an |
| 11581 |
OPEN delegation is in effect does not require that a validation |
| 11582 |
message be sent to the server. The continued endurance of the |
| 11583 |
"OPEN_DELEGATE_READ delegation" provides a guarantee that no OPEN for |
| 11584 |
OPEN4_SHARE_ACCESS_WRITE/OPEN4_SHARE_ACCESS_BOTH, and thus no write, |
| 11585 |
|
| 11586 |
|
| 11587 |
|
| 11588 |
<span class="grey">Shepler, et al. Standards Track [Page 207]</span></pre> |
| 11589 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-208" ></span> |
| 11590 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11591 |
|
| 11592 |
|
| 11593 |
has occurred. Similarly, when closing a file opened for |
| 11594 |
OPEN4_SHARE_ACCESS_WRITE/OPEN4_SHARE_ACCESS_BOTH and if an |
| 11595 |
OPEN_DELEGATE_WRITE delegation is in effect, the data written does |
| 11596 |
not have to be written to the server until the OPEN delegation is |
| 11597 |
recalled. The continued endurance of the OPEN delegation provides a |
| 11598 |
guarantee that no open, and thus no READ or WRITE, has been done by |
| 11599 |
another client. |
| 11600 |
|
| 11601 |
For the purposes of OPEN delegation, READs and WRITEs done without an |
| 11602 |
OPEN are treated as the functional equivalents of a corresponding |
| 11603 |
type of OPEN. Although a client SHOULD NOT use special stateids when |
| 11604 |
an open exists, delegation handling on the server can use the client |
| 11605 |
ID associated with the current session to determine if the operation |
| 11606 |
has been done by the holder of the delegation (in which case, no |
| 11607 |
recall is necessary) or by another client (in which case, the |
| 11608 |
delegation must be recalled and I/O not proceed until the delegation |
| 11609 |
is recalled or revoked). |
| 11610 |
|
| 11611 |
With delegations, a client is able to avoid writing data to the |
| 11612 |
server when the CLOSE of a file is serviced. The file close system |
| 11613 |
call is the usual point at which the client is notified of a lack of |
| 11614 |
stable storage for the modified file data generated by the |
| 11615 |
application. At the close, file data is written to the server and, |
| 11616 |
through normal accounting, the server is able to determine if the |
| 11617 |
available file system space for the data has been exceeded (i.e., the |
| 11618 |
server returns NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting |
| 11619 |
includes quotas. The introduction of delegations requires that an |
| 11620 |
alternative method be in place for the same type of communication to |
| 11621 |
occur between client and server. |
| 11622 |
|
| 11623 |
In the delegation response, the server provides either the limit of |
| 11624 |
the size of the file or the number of modified blocks and associated |
| 11625 |
block size. The server must ensure that the client will be able to |
| 11626 |
write modified data to the server of a size equal to that provided in |
| 11627 |
the original delegation. The server must make this assurance for all |
| 11628 |
outstanding delegations. Therefore, the server must be careful in |
| 11629 |
its management of available space for new or modified data, taking |
| 11630 |
into account available file system space and any applicable quotas. |
| 11631 |
The server can recall delegations as a result of managing the |
| 11632 |
available file system space. The client should abide by the server's |
| 11633 |
state space limits for delegations. If the client exceeds the stated |
| 11634 |
limits for the delegation, the server's behavior is undefined. |
| 11635 |
|
| 11636 |
Based on server conditions, quotas, or available file system space, |
| 11637 |
the server may grant OPEN_DELEGATE_WRITE delegations with very |
| 11638 |
restrictive space limitations. The limitations may be defined in a |
| 11639 |
way that will always force modified data to be flushed to the server |
| 11640 |
on close. |
| 11641 |
|
| 11642 |
|
| 11643 |
|
| 11644 |
<span class="grey">Shepler, et al. Standards Track [Page 208]</span></pre> |
| 11645 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-209" ></span> |
| 11646 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11647 |
|
| 11648 |
|
| 11649 |
With respect to authentication, flushing modified data to the server |
| 11650 |
after a CLOSE has occurred may be problematic. For example, the user |
| 11651 |
of the application may have logged off the client, and unexpired |
| 11652 |
authentication credentials may not be present. In this case, the |
| 11653 |
client may need to take special care to ensure that local unexpired |
| 11654 |
credentials will in fact be available. This may be accomplished by |
| 11655 |
tracking the expiration time of credentials and flushing data well in |
| 11656 |
advance of their expiration or by making private copies of |
| 11657 |
credentials to assure their availability when needed. |
| 11658 |
|
| 11659 |
<span class="h4"><a class="selflink" id="section-10.4.2" href="#section-10.4.2">10.4.2</a>. Open Delegation and File Locks</span> |
| 11660 |
|
| 11661 |
When a client holds an OPEN_DELEGATE_WRITE delegation, lock |
| 11662 |
operations are performed locally. This includes those required for |
| 11663 |
mandatory byte-range locking. This can be done since the delegation |
| 11664 |
implies that there can be no conflicting locks. Similarly, all of |
| 11665 |
the revalidations that would normally be associated with obtaining |
| 11666 |
locks and the flushing of data associated with the releasing of locks |
| 11667 |
need not be done. |
| 11668 |
|
| 11669 |
When a client holds an OPEN_DELEGATE_READ delegation, lock operations |
| 11670 |
are not performed locally. All lock operations, including those |
| 11671 |
requesting non-exclusive locks, are sent to the server for |
| 11672 |
resolution. |
| 11673 |
|
| 11674 |
<span class="h4"><a class="selflink" id="section-10.4.3" href="#section-10.4.3">10.4.3</a>. Handling of CB_GETATTR</span> |
| 11675 |
|
| 11676 |
The server needs to employ special handling for a GETATTR where the |
| 11677 |
target is a file that has an OPEN_DELEGATE_WRITE delegation in |
| 11678 |
effect. The reason for this is that the client holding the |
| 11679 |
OPEN_DELEGATE_WRITE delegation may have modified the data, and the |
| 11680 |
server needs to reflect this change to the second client that |
| 11681 |
submitted the GETATTR. Therefore, the client holding the |
| 11682 |
OPEN_DELEGATE_WRITE delegation needs to be interrogated. The server |
| 11683 |
will use the CB_GETATTR operation. The only attributes that the |
| 11684 |
server can reliably query via CB_GETATTR are size and change. |
| 11685 |
|
| 11686 |
Since CB_GETATTR is being used to satisfy another client's GETATTR |
| 11687 |
request, the server only needs to know if the client holding the |
| 11688 |
delegation has a modified version of the file. If the client's copy |
| 11689 |
of the delegated file is not modified (data or size), the server can |
| 11690 |
satisfy the second client's GETATTR request from the attributes |
| 11691 |
stored locally at the server. If the file is modified, the server |
| 11692 |
only needs to know about this modified state. If the server |
| 11693 |
determines that the file is currently modified, it will respond to |
| 11694 |
the second client's GETATTR as if the file had been modified locally |
| 11695 |
at the server. |
| 11696 |
|
| 11697 |
|
| 11698 |
|
| 11699 |
|
| 11700 |
<span class="grey">Shepler, et al. Standards Track [Page 209]</span></pre> |
| 11701 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-210" ></span> |
| 11702 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11703 |
|
| 11704 |
|
| 11705 |
Since the form of the change attribute is determined by the server |
| 11706 |
and is opaque to the client, the client and server need to agree on a |
| 11707 |
method of communicating the modified state of the file. For the size |
| 11708 |
attribute, the client will report its current view of the file size. |
| 11709 |
For the change attribute, the handling is more involved. |
| 11710 |
|
| 11711 |
For the client, the following steps will be taken when receiving an |
| 11712 |
OPEN_DELEGATE_WRITE delegation: |
| 11713 |
|
| 11714 |
o The value of the change attribute will be obtained from the server |
| 11715 |
and cached. Let this value be represented by c. |
| 11716 |
|
| 11717 |
o The client will create a value greater than c that will be used |
| 11718 |
for communicating that modified data is held at the client. Let |
| 11719 |
this value be represented by d. |
| 11720 |
|
| 11721 |
o When the client is queried via CB_GETATTR for the change |
| 11722 |
attribute, it checks to see if it holds modified data. If the |
| 11723 |
file is modified, the value d is returned for the change attribute |
| 11724 |
value. If this file is not currently modified, the client returns |
| 11725 |
the value c for the change attribute. |
| 11726 |
|
| 11727 |
For simplicity of implementation, the client MAY for each CB_GETATTR |
| 11728 |
return the same value d. This is true even if, between successive |
| 11729 |
CB_GETATTR operations, the client again modifies the file's data or |
| 11730 |
metadata in its cache. The client can return the same value because |
| 11731 |
the only requirement is that the client be able to indicate to the |
| 11732 |
server that the client holds modified data. Therefore, the value of |
| 11733 |
d may always be c + 1. |
| 11734 |
|
| 11735 |
While the change attribute is opaque to the client in the sense that |
| 11736 |
it has no idea what units of time, if any, the server is counting |
| 11737 |
change with, it is not opaque in that the client has to treat it as |
| 11738 |
an unsigned integer, and the server has to be able to see the results |
| 11739 |
of the client's changes to that integer. Therefore, the server MUST |
| 11740 |
encode the change attribute in network order when sending it to the |
| 11741 |
client. The client MUST decode it from network order to its native |
| 11742 |
order when receiving it, and the client MUST encode it in network |
| 11743 |
order when sending it to the server. For this reason, change is |
| 11744 |
defined as an unsigned integer rather than an opaque array of bytes. |
| 11745 |
|
| 11746 |
For the server, the following steps will be taken when providing an |
| 11747 |
OPEN_DELEGATE_WRITE delegation: |
| 11748 |
|
| 11749 |
o Upon providing an OPEN_DELEGATE_WRITE delegation, the server will |
| 11750 |
cache a copy of the change attribute in the data structure it uses |
| 11751 |
to record the delegation. Let this value be represented by sc. |
| 11752 |
|
| 11753 |
|
| 11754 |
|
| 11755 |
|
| 11756 |
<span class="grey">Shepler, et al. Standards Track [Page 210]</span></pre> |
| 11757 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-211" ></span> |
| 11758 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11759 |
|
| 11760 |
|
| 11761 |
o When a second client sends a GETATTR operation on the same file to |
| 11762 |
the server, the server obtains the change attribute from the first |
| 11763 |
client. Let this value be cc. |
| 11764 |
|
| 11765 |
o If the value cc is equal to sc, the file is not modified and the |
| 11766 |
server returns the current values for change, time_metadata, and |
| 11767 |
time_modify (for example) to the second client. |
| 11768 |
|
| 11769 |
o If the value cc is NOT equal to sc, the file is currently modified |
| 11770 |
at the first client and most likely will be modified at the server |
| 11771 |
at a future time. The server then uses its current time to |
| 11772 |
construct attribute values for time_metadata and time_modify. A |
| 11773 |
new value of sc, which we will call nsc, is computed by the |
| 11774 |
server, such that nsc >= sc + 1. The server then returns the |
| 11775 |
constructed time_metadata, time_modify, and nsc values to the |
| 11776 |
requester. The server replaces sc in the delegation record with |
| 11777 |
nsc. To prevent the possibility of time_modify, time_metadata, |
| 11778 |
and change from appearing to go backward (which would happen if |
| 11779 |
the client holding the delegation fails to write its modified data |
| 11780 |
to the server before the delegation is revoked or returned), the |
| 11781 |
server SHOULD update the file's metadata record with the |
| 11782 |
constructed attribute values. For reasons of reasonable |
| 11783 |
performance, committing the constructed attribute values to stable |
| 11784 |
storage is OPTIONAL. |
| 11785 |
|
| 11786 |
As discussed earlier in this section, the client MAY return the same |
| 11787 |
cc value on subsequent CB_GETATTR calls, even if the file was |
| 11788 |
modified in the client's cache yet again between successive |
| 11789 |
CB_GETATTR calls. Therefore, the server must assume that the file |
| 11790 |
has been modified yet again, and MUST take care to ensure that the |
| 11791 |
new nsc it constructs and returns is greater than the previous nsc it |
| 11792 |
returned. An example implementation's delegation record would |
| 11793 |
satisfy this mandate by including a boolean field (let us call it |
| 11794 |
"modified") that is set to FALSE when the delegation is granted, and |
| 11795 |
an sc value set at the time of grant to the change attribute value. |
| 11796 |
The modified field would be set to TRUE the first time cc != sc, and |
| 11797 |
would stay TRUE until the delegation is returned or revoked. The |
| 11798 |
processing for constructing nsc, time_modify, and time_metadata would |
| 11799 |
use this pseudo code: |
| 11800 |
|
| 11801 |
|
| 11802 |
|
| 11803 |
|
| 11804 |
|
| 11805 |
|
| 11806 |
|
| 11807 |
|
| 11808 |
|
| 11809 |
|
| 11810 |
|
| 11811 |
|
| 11812 |
<span class="grey">Shepler, et al. Standards Track [Page 211]</span></pre> |
| 11813 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-212" ></span> |
| 11814 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11815 |
|
| 11816 |
|
| 11817 |
if (!modified) { |
| 11818 |
do CB_GETATTR for change and size; |
| 11819 |
|
| 11820 |
if (cc != sc) |
| 11821 |
modified = TRUE; |
| 11822 |
} else { |
| 11823 |
do CB_GETATTR for size; |
| 11824 |
} |
| 11825 |
|
| 11826 |
if (modified) { |
| 11827 |
sc = sc + 1; |
| 11828 |
time_modify = time_metadata = current_time; |
| 11829 |
update sc, time_modify, time_metadata into file's metadata; |
| 11830 |
} |
| 11831 |
|
| 11832 |
This would return to the client (that sent GETATTR) the attributes it |
| 11833 |
requested, but make sure size comes from what CB_GETATTR returned. |
| 11834 |
The server would not update the file's metadata with the client's |
| 11835 |
modified size. |
| 11836 |
|
| 11837 |
In the case that the file attribute size is different than the |
| 11838 |
server's current value, the server treats this as a modification |
| 11839 |
regardless of the value of the change attribute retrieved via |
| 11840 |
CB_GETATTR and responds to the second client as in the last step. |
| 11841 |
|
| 11842 |
This methodology resolves issues of clock differences between client |
| 11843 |
and server and other scenarios where the use of CB_GETATTR break |
| 11844 |
down. |
| 11845 |
|
| 11846 |
It should be noted that the server is under no obligation to use |
| 11847 |
CB_GETATTR, and therefore the server MAY simply recall the delegation |
| 11848 |
to avoid its use. |
| 11849 |
|
| 11850 |
<span class="h4"><a class="selflink" id="section-10.4.4" href="#section-10.4.4">10.4.4</a>. Recall of Open Delegation</span> |
| 11851 |
|
| 11852 |
The following events necessitate recall of an OPEN delegation: |
| 11853 |
|
| 11854 |
o potentially conflicting OPEN request (or a READ or WRITE operation |
| 11855 |
done with a special stateid) |
| 11856 |
|
| 11857 |
o SETATTR sent by another client |
| 11858 |
|
| 11859 |
o REMOVE request for the file |
| 11860 |
|
| 11861 |
o RENAME request for the file as either the source or target of the |
| 11862 |
RENAME |
| 11863 |
|
| 11864 |
|
| 11865 |
|
| 11866 |
|
| 11867 |
|
| 11868 |
<span class="grey">Shepler, et al. Standards Track [Page 212]</span></pre> |
| 11869 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-213" ></span> |
| 11870 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11871 |
|
| 11872 |
|
| 11873 |
Whether a RENAME of a directory in the path leading to the file |
| 11874 |
results in recall of an OPEN delegation depends on the semantics of |
| 11875 |
the server's file system. If that file system denies such RENAMEs |
| 11876 |
when a file is open, the recall must be performed to determine |
| 11877 |
whether the file in question is, in fact, open. |
| 11878 |
|
| 11879 |
In addition to the situations above, the server may choose to recall |
| 11880 |
OPEN delegations at any time if resource constraints make it |
| 11881 |
advisable to do so. Clients should always be prepared for the |
| 11882 |
possibility of recall. |
| 11883 |
|
| 11884 |
When a client receives a recall for an OPEN delegation, it needs to |
| 11885 |
update state on the server before returning the delegation. These |
| 11886 |
same updates must be done whenever a client chooses to return a |
| 11887 |
delegation voluntarily. The following items of state need to be |
| 11888 |
dealt with: |
| 11889 |
|
| 11890 |
o If the file associated with the delegation is no longer open and |
| 11891 |
no previous CLOSE operation has been sent to the server, a CLOSE |
| 11892 |
operation must be sent to the server. |
| 11893 |
|
| 11894 |
o If a file has other open references at the client, then OPEN |
| 11895 |
operations must be sent to the server. The appropriate stateids |
| 11896 |
will be provided by the server for subsequent use by the client |
| 11897 |
since the delegation stateid will no longer be valid. These OPEN |
| 11898 |
requests are done with the claim type of CLAIM_DELEGATE_CUR. This |
| 11899 |
will allow the presentation of the delegation stateid so that the |
| 11900 |
client can establish the appropriate rights to perform the OPEN. |
| 11901 |
(see <a href="#section-18.16">Section 18.16</a>, which describes the OPEN operation, for |
| 11902 |
details.) |
| 11903 |
|
| 11904 |
o If there are granted byte-range locks, the corresponding LOCK |
| 11905 |
operations need to be performed. This applies to the |
| 11906 |
OPEN_DELEGATE_WRITE delegation case only. |
| 11907 |
|
| 11908 |
o For an OPEN_DELEGATE_WRITE delegation, if at the time of recall |
| 11909 |
the file is not open for OPEN4_SHARE_ACCESS_WRITE/ |
| 11910 |
OPEN4_SHARE_ACCESS_BOTH, all modified data for the file must be |
| 11911 |
flushed to the server. If the delegation had not existed, the |
| 11912 |
client would have done this data flush before the CLOSE operation. |
| 11913 |
|
| 11914 |
o For an OPEN_DELEGATE_WRITE delegation when a file is still open at |
| 11915 |
the time of recall, any modified data for the file needs to be |
| 11916 |
flushed to the server. |
| 11917 |
|
| 11918 |
o With the OPEN_DELEGATE_WRITE delegation in place, it is possible |
| 11919 |
that the file was truncated during the duration of the delegation. |
| 11920 |
For example, the truncation could have occurred as a result of an |
| 11921 |
|
| 11922 |
|
| 11923 |
|
| 11924 |
<span class="grey">Shepler, et al. Standards Track [Page 213]</span></pre> |
| 11925 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-214" ></span> |
| 11926 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11927 |
|
| 11928 |
|
| 11929 |
OPEN UNCHECKED with a size attribute value of zero. Therefore, if |
| 11930 |
a truncation of the file has occurred and this operation has not |
| 11931 |
been propagated to the server, the truncation must occur before |
| 11932 |
any modified data is written to the server. |
| 11933 |
|
| 11934 |
In the case of OPEN_DELEGATE_WRITE delegation, byte-range locking |
| 11935 |
imposes some additional requirements. To precisely maintain the |
| 11936 |
associated invariant, it is required to flush any modified data in |
| 11937 |
any byte-range for which a WRITE_LT lock was released while the |
| 11938 |
OPEN_DELEGATE_WRITE delegation was in effect. However, because the |
| 11939 |
OPEN_DELEGATE_WRITE delegation implies no other locking by other |
| 11940 |
clients, a simpler implementation is to flush all modified data for |
| 11941 |
the file (as described just above) if any WRITE_LT lock has been |
| 11942 |
released while the OPEN_DELEGATE_WRITE delegation was in effect. |
| 11943 |
|
| 11944 |
An implementation need not wait until delegation recall (or the |
| 11945 |
decision to voluntarily return a delegation) to perform any of the |
| 11946 |
above actions, if implementation considerations (e.g., resource |
| 11947 |
availability constraints) make that desirable. Generally, however, |
| 11948 |
the fact that the actual OPEN state of the file may continue to |
| 11949 |
change makes it not worthwhile to send information about opens and |
| 11950 |
closes to the server, except as part of delegation return. An |
| 11951 |
exception is when the client has no more internal opens of the file. |
| 11952 |
In this case, sending a CLOSE is useful because it reduces resource |
| 11953 |
utilization on the client and server. Regardless of the client's |
| 11954 |
choices on scheduling these actions, all must be performed before the |
| 11955 |
delegation is returned, including (when applicable) the close that |
| 11956 |
corresponds to the OPEN that resulted in the delegation. These |
| 11957 |
actions can be performed either in previous requests or in previous |
| 11958 |
operations in the same COMPOUND request. |
| 11959 |
|
| 11960 |
<span class="h4"><a class="selflink" id="section-10.4.5" href="#section-10.4.5">10.4.5</a>. Clients That Fail to Honor Delegation Recalls</span> |
| 11961 |
|
| 11962 |
A client may fail to respond to a recall for various reasons, such as |
| 11963 |
a failure of the backchannel from server to the client. The client |
| 11964 |
may be unaware of a failure in the backchannel. This lack of |
| 11965 |
awareness could result in the client finding out long after the |
| 11966 |
failure that its delegation has been revoked, and another client has |
| 11967 |
modified the data for which the client had a delegation. This is |
| 11968 |
especially a problem for the client that held an OPEN_DELEGATE_WRITE |
| 11969 |
delegation. |
| 11970 |
|
| 11971 |
Status bits returned by SEQUENCE operations help to provide an |
| 11972 |
alternate way of informing the client of issues regarding the status |
| 11973 |
of the backchannel and of recalled delegations. When the backchannel |
| 11974 |
is not available, the server returns the status bit |
| 11975 |
SEQ4_STATUS_CB_PATH_DOWN on SEQUENCE operations. The client can |
| 11976 |
|
| 11977 |
|
| 11978 |
|
| 11979 |
|
| 11980 |
<span class="grey">Shepler, et al. Standards Track [Page 214]</span></pre> |
| 11981 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-215" ></span> |
| 11982 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 11983 |
|
| 11984 |
|
| 11985 |
react by attempting to re-establish the backchannel and by returning |
| 11986 |
recallable objects if a backchannel cannot be successfully re- |
| 11987 |
established. |
| 11988 |
|
| 11989 |
Whether the backchannel is functioning or not, it may be that the |
| 11990 |
recalled delegation is not returned. Note that the client's lease |
| 11991 |
might still be renewed, even though the recalled delegation is not |
| 11992 |
returned. In this situation, servers SHOULD revoke delegations that |
| 11993 |
are not returned in a period of time equal to the lease period. This |
| 11994 |
period of time should allow the client time to note the backchannel- |
| 11995 |
down status and re-establish the backchannel. |
| 11996 |
|
| 11997 |
When delegations are revoked, the server will return with the |
| 11998 |
SEQ4_STATUS_RECALLABLE_STATE_REVOKED status bit set on subsequent |
| 11999 |
SEQUENCE operations. The client should note this and then use |
| 12000 |
TEST_STATEID to find which delegations have been revoked. |
| 12001 |
|
| 12002 |
<span class="h4"><a class="selflink" id="section-10.4.6" href="#section-10.4.6">10.4.6</a>. Delegation Revocation</span> |
| 12003 |
|
| 12004 |
At the point a delegation is revoked, if there are associated opens |
| 12005 |
on the client, these opens may or may not be revoked. If no byte- |
| 12006 |
range lock or open is granted that is inconsistent with the existing |
| 12007 |
open, the stateid for the open may remain valid and be disconnected |
| 12008 |
from the revoked delegation, just as would be the case if the |
| 12009 |
delegation were returned. |
| 12010 |
|
| 12011 |
For example, if an OPEN for OPEN4_SHARE_ACCESS_BOTH with a deny of |
| 12012 |
OPEN4_SHARE_DENY_NONE is associated with the delegation, granting of |
| 12013 |
another such OPEN to a different client will revoke the delegation |
| 12014 |
but need not revoke the OPEN, since the two OPENs are consistent with |
| 12015 |
each other. On the other hand, if an OPEN denying write access is |
| 12016 |
granted, then the existing OPEN must be revoked. |
| 12017 |
|
| 12018 |
When opens and/or locks are revoked, the applications holding these |
| 12019 |
opens or locks need to be notified. This notification usually occurs |
| 12020 |
by returning errors for READ/WRITE operations or when a close is |
| 12021 |
attempted for the open file. |
| 12022 |
|
| 12023 |
If no opens exist for the file at the point the delegation is |
| 12024 |
revoked, then notification of the revocation is unnecessary. |
| 12025 |
However, if there is modified data present at the client for the |
| 12026 |
file, the user of the application should be notified. Unfortunately, |
| 12027 |
it may not be possible to notify the user since active applications |
| 12028 |
may not be present at the client. See <a href="#section-10.5.1">Section 10.5.1</a> for additional |
| 12029 |
details. |
| 12030 |
|
| 12031 |
|
| 12032 |
|
| 12033 |
|
| 12034 |
|
| 12035 |
|
| 12036 |
<span class="grey">Shepler, et al. Standards Track [Page 215]</span></pre> |
| 12037 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-216" ></span> |
| 12038 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12039 |
|
| 12040 |
|
| 12041 |
<span class="h4"><a class="selflink" id="section-10.4.7" href="#section-10.4.7">10.4.7</a>. Delegations via WANT_DELEGATION</span> |
| 12042 |
|
| 12043 |
In addition to providing delegations as part of the reply to OPEN |
| 12044 |
operations, servers MAY provide delegations separate from open, via |
| 12045 |
the OPTIONAL WANT_DELEGATION operation. This allows delegations to |
| 12046 |
be obtained in advance of an OPEN that might benefit from them, for |
| 12047 |
objects that are not a valid target of OPEN, or to deal with cases in |
| 12048 |
which a delegation has been recalled and the client wants to make an |
| 12049 |
attempt to re-establish it if the absence of use by other clients |
| 12050 |
allows that. |
| 12051 |
|
| 12052 |
The WANT_DELEGATION operation may be performed on any type of file |
| 12053 |
object other than a directory. |
| 12054 |
|
| 12055 |
When a delegation is obtained using WANT_DELEGATION, any open files |
| 12056 |
for the same filehandle held by that client are to be treated as |
| 12057 |
subordinate to the delegation, just as if they had been created using |
| 12058 |
an OPEN of type CLAIM_DELEGATE_CUR. They are otherwise unchanged as |
| 12059 |
to seqid, access and deny modes, and the relationship with byte-range |
| 12060 |
locks. Similarly, because existing byte-range locks are subordinate |
| 12061 |
to an open, those byte-range locks also become indirectly subordinate |
| 12062 |
to that new delegation. |
| 12063 |
|
| 12064 |
The WANT_DELEGATION operation provides for delivery of delegations |
| 12065 |
via callbacks, when the delegations are not immediately available. |
| 12066 |
When a requested delegation is available, it is delivered to the |
| 12067 |
client via a CB_PUSH_DELEG operation. When this happens, open files |
| 12068 |
for the same filehandle become subordinate to the new delegation at |
| 12069 |
the point at which the delegation is delivered, just as if they had |
| 12070 |
been created using an OPEN of type CLAIM_DELEGATE_CUR. Similarly, |
| 12071 |
this occurs for existing byte-range locks subordinate to an open. |
| 12072 |
|
| 12073 |
<span class="h3"><a class="selflink" id="section-10.5" href="#section-10.5">10.5</a>. Data Caching and Revocation</span> |
| 12074 |
|
| 12075 |
When locks and delegations are revoked, the assumptions upon which |
| 12076 |
successful caching depends are no longer guaranteed. For any locks |
| 12077 |
or share reservations that have been revoked, the corresponding |
| 12078 |
state-owner needs to be notified. This notification includes |
| 12079 |
applications with a file open that has a corresponding delegation |
| 12080 |
that has been revoked. Cached data associated with the revocation |
| 12081 |
must be removed from the client. In the case of modified data |
| 12082 |
existing in the client's cache, that data must be removed from the |
| 12083 |
client without being written to the server. As mentioned, the |
| 12084 |
assumptions made by the client are no longer valid at the point when |
| 12085 |
a lock or delegation has been revoked. For example, another client |
| 12086 |
may have been granted a conflicting byte-range lock after the |
| 12087 |
revocation of the byte-range lock at the first client. Therefore, |
| 12088 |
|
| 12089 |
|
| 12090 |
|
| 12091 |
|
| 12092 |
<span class="grey">Shepler, et al. Standards Track [Page 216]</span></pre> |
| 12093 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-217" ></span> |
| 12094 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12095 |
|
| 12096 |
|
| 12097 |
the data within the lock range may have been modified by the other |
| 12098 |
client. Obviously, the first client is unable to guarantee to the |
| 12099 |
application what has occurred to the file in the case of revocation. |
| 12100 |
|
| 12101 |
Notification to a state-owner will in many cases consist of simply |
| 12102 |
returning an error on the next and all subsequent READs/WRITEs to the |
| 12103 |
open file or on the close. Where the methods available to a client |
| 12104 |
make such notification impossible because errors for certain |
| 12105 |
operations may not be returned, more drastic action such as signals |
| 12106 |
or process termination may be appropriate. The justification here is |
| 12107 |
that an invariant on which an application depends may be violated. |
| 12108 |
Depending on how errors are typically treated for the client- |
| 12109 |
operating environment, further levels of notification including |
| 12110 |
logging, console messages, and GUI pop-ups may be appropriate. |
| 12111 |
|
| 12112 |
<span class="h4"><a class="selflink" id="section-10.5.1" href="#section-10.5.1">10.5.1</a>. Revocation Recovery for Write Open Delegation</span> |
| 12113 |
|
| 12114 |
Revocation recovery for an OPEN_DELEGATE_WRITE delegation poses the |
| 12115 |
special issue of modified data in the client cache while the file is |
| 12116 |
not open. In this situation, any client that does not flush modified |
| 12117 |
data to the server on each close must ensure that the user receives |
| 12118 |
appropriate notification of the failure as a result of the |
| 12119 |
revocation. Since such situations may require human action to |
| 12120 |
correct problems, notification schemes in which the appropriate user |
| 12121 |
or administrator is notified may be necessary. Logging and console |
| 12122 |
messages are typical examples. |
| 12123 |
|
| 12124 |
If there is modified data on the client, it must not be flushed |
| 12125 |
normally to the server. A client may attempt to provide a copy of |
| 12126 |
the file data as modified during the delegation under a different |
| 12127 |
name in the file system namespace to ease recovery. Note that when |
| 12128 |
the client can determine that the file has not been modified by any |
| 12129 |
other client, or when the client has a complete cached copy of the |
| 12130 |
file in question, such a saved copy of the client's view of the file |
| 12131 |
may be of particular value for recovery. In another case, recovery |
| 12132 |
using a copy of the file based partially on the client's cached data |
| 12133 |
and partially on the server's copy as modified by other clients will |
| 12134 |
be anything but straightforward, so clients may avoid saving file |
| 12135 |
contents in these situations or specially mark the results to warn |
| 12136 |
users of possible problems. |
| 12137 |
|
| 12138 |
Saving of such modified data in delegation revocation situations may |
| 12139 |
be limited to files of a certain size or might be used only when |
| 12140 |
sufficient disk space is available within the target file system. |
| 12141 |
Such saving may also be restricted to situations when the client has |
| 12142 |
sufficient buffering resources to keep the cached copy available |
| 12143 |
until it is properly stored to the target file system. |
| 12144 |
|
| 12145 |
|
| 12146 |
|
| 12147 |
|
| 12148 |
<span class="grey">Shepler, et al. Standards Track [Page 217]</span></pre> |
| 12149 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-218" ></span> |
| 12150 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12151 |
|
| 12152 |
|
| 12153 |
<span class="h3"><a class="selflink" id="section-10.6" href="#section-10.6">10.6</a>. Attribute Caching</span> |
| 12154 |
|
| 12155 |
This section pertains to the caching of a file's attributes on a |
| 12156 |
client when that client does not hold a delegation on the file. |
| 12157 |
|
| 12158 |
The attributes discussed in this section do not include named |
| 12159 |
attributes. Individual named attributes are analogous to files, and |
| 12160 |
caching of the data for these needs to be handled just as data |
| 12161 |
caching is for ordinary files. Similarly, LOOKUP results from an |
| 12162 |
OPENATTR directory (as well as the directory's contents) are to be |
| 12163 |
cached on the same basis as any other pathnames. |
| 12164 |
|
| 12165 |
Clients may cache file attributes obtained from the server and use |
| 12166 |
them to avoid subsequent GETATTR requests. Such caching is write |
| 12167 |
through in that modification to file attributes is always done by |
| 12168 |
means of requests to the server and should not be done locally and |
| 12169 |
should not be cached. The exception to this are modifications to |
| 12170 |
attributes that are intimately connected with data caching. |
| 12171 |
Therefore, extending a file by writing data to the local data cache |
| 12172 |
is reflected immediately in the size as seen on the client without |
| 12173 |
this change being immediately reflected on the server. Normally, |
| 12174 |
such changes are not propagated directly to the server, but when the |
| 12175 |
modified data is flushed to the server, analogous attribute changes |
| 12176 |
are made on the server. When OPEN delegation is in effect, the |
| 12177 |
modified attributes may be returned to the server in reaction to a |
| 12178 |
CB_RECALL call. |
| 12179 |
|
| 12180 |
The result of local caching of attributes is that the attribute |
| 12181 |
caches maintained on individual clients will not be coherent. |
| 12182 |
Changes made in one order on the server may be seen in a different |
| 12183 |
order on one client and in a third order on another client. |
| 12184 |
|
| 12185 |
The typical file system application programming interfaces do not |
| 12186 |
provide means to atomically modify or interrogate attributes for |
| 12187 |
multiple files at the same time. The following rules provide an |
| 12188 |
environment where the potential incoherencies mentioned above can be |
| 12189 |
reasonably managed. These rules are derived from the practice of |
| 12190 |
previous NFS protocols. |
| 12191 |
|
| 12192 |
o All attributes for a given file (per-fsid attributes excepted) are |
| 12193 |
cached as a unit at the client so that no non-serializability can |
| 12194 |
arise within the context of a single file. |
| 12195 |
|
| 12196 |
o An upper time boundary is maintained on how long a client cache |
| 12197 |
entry can be kept without being refreshed from the server. |
| 12198 |
|
| 12199 |
|
| 12200 |
|
| 12201 |
|
| 12202 |
|
| 12203 |
|
| 12204 |
<span class="grey">Shepler, et al. Standards Track [Page 218]</span></pre> |
| 12205 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-219" ></span> |
| 12206 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12207 |
|
| 12208 |
|
| 12209 |
o When operations are performed that change attributes at the |
| 12210 |
server, the updated attribute set is requested as part of the |
| 12211 |
containing RPC. This includes directory operations that update |
| 12212 |
attributes indirectly. This is accomplished by following the |
| 12213 |
modifying operation with a GETATTR operation and then using the |
| 12214 |
results of the GETATTR to update the client's cached attributes. |
| 12215 |
|
| 12216 |
Note that if the full set of attributes to be cached is requested by |
| 12217 |
READDIR, the results can be cached by the client on the same basis as |
| 12218 |
attributes obtained via GETATTR. |
| 12219 |
|
| 12220 |
A client may validate its cached version of attributes for a file by |
| 12221 |
fetching both the change and time_access attributes and assuming that |
| 12222 |
if the change attribute has the same value as it did when the |
| 12223 |
attributes were cached, then no attributes other than time_access |
| 12224 |
have changed. The reason why time_access is also fetched is because |
| 12225 |
many servers operate in environments where the operation that updates |
| 12226 |
change does not update time_access. For example, POSIX file |
| 12227 |
semantics do not update access time when a file is modified by the |
| 12228 |
write system call [<a href="#ref-18" title="">18</a>]. Therefore, the client that wants a current |
| 12229 |
time_access value should fetch it with change during the attribute |
| 12230 |
cache validation processing and update its cached time_access. |
| 12231 |
|
| 12232 |
The client may maintain a cache of modified attributes for those |
| 12233 |
attributes intimately connected with data of modified regular files |
| 12234 |
(size, time_modify, and change). Other than those three attributes, |
| 12235 |
the client MUST NOT maintain a cache of modified attributes. |
| 12236 |
Instead, attribute changes are immediately sent to the server. |
| 12237 |
|
| 12238 |
In some operating environments, the equivalent to time_access is |
| 12239 |
expected to be implicitly updated by each read of the content of the |
| 12240 |
file object. If an NFS client is caching the content of a file |
| 12241 |
object, whether it is a regular file, directory, or symbolic link, |
| 12242 |
the client SHOULD NOT update the time_access attribute (via SETATTR |
| 12243 |
or a small READ or READDIR request) on the server with each read that |
| 12244 |
is satisfied from cache. The reason is that this can defeat the |
| 12245 |
performance benefits of caching content, especially since an explicit |
| 12246 |
SETATTR of time_access may alter the change attribute on the server. |
| 12247 |
If the change attribute changes, clients that are caching the content |
| 12248 |
will think the content has changed, and will re-read unmodified data |
| 12249 |
from the server. Nor is the client encouraged to maintain a modified |
| 12250 |
version of time_access in its cache, since the client either would |
| 12251 |
eventually have to write the access time to the server with bad |
| 12252 |
performance effects or never update the server's time_access, thereby |
| 12253 |
resulting in a situation where an application that caches access time |
| 12254 |
between a close and open of the same file observes the access time |
| 12255 |
oscillating between the past and present. The time_access attribute |
| 12256 |
|
| 12257 |
|
| 12258 |
|
| 12259 |
|
| 12260 |
<span class="grey">Shepler, et al. Standards Track [Page 219]</span></pre> |
| 12261 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-220" ></span> |
| 12262 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12263 |
|
| 12264 |
|
| 12265 |
always means the time of last access to a file by a read that was |
| 12266 |
satisfied by the server. This way clients will tend to see only |
| 12267 |
time_access changes that go forward in time. |
| 12268 |
|
| 12269 |
<span class="h3"><a class="selflink" id="section-10.7" href="#section-10.7">10.7</a>. Data and Metadata Caching and Memory Mapped Files</span> |
| 12270 |
|
| 12271 |
Some operating environments include the capability for an application |
| 12272 |
to map a file's content into the application's address space. Each |
| 12273 |
time the application accesses a memory location that corresponds to a |
| 12274 |
block that has not been loaded into the address space, a page fault |
| 12275 |
occurs and the file is read (or if the block does not exist in the |
| 12276 |
file, the block is allocated and then instantiated in the |
| 12277 |
application's address space). |
| 12278 |
|
| 12279 |
As long as each memory-mapped access to the file requires a page |
| 12280 |
fault, the relevant attributes of the file that are used to detect |
| 12281 |
access and modification (time_access, time_metadata, time_modify, and |
| 12282 |
change) will be updated. However, in many operating environments, |
| 12283 |
when page faults are not required, these attributes will not be |
| 12284 |
updated on reads or updates to the file via memory access (regardless |
| 12285 |
of whether the file is local or is accessed remotely). A client or |
| 12286 |
server MAY fail to update attributes of a file that is being accessed |
| 12287 |
via memory-mapped I/O. This has several implications: |
| 12288 |
|
| 12289 |
o If there is an application on the server that has memory mapped a |
| 12290 |
file that a client is also accessing, the client may not be able |
| 12291 |
to get a consistent value of the change attribute to determine |
| 12292 |
whether or not its cache is stale. A server that knows that the |
| 12293 |
file is memory-mapped could always pessimistically return updated |
| 12294 |
values for change so as to force the application to always get the |
| 12295 |
most up-to-date data and metadata for the file. However, due to |
| 12296 |
the negative performance implications of this, such behavior is |
| 12297 |
OPTIONAL. |
| 12298 |
|
| 12299 |
o If the memory-mapped file is not being modified on the server, and |
| 12300 |
instead is just being read by an application via the memory-mapped |
| 12301 |
interface, the client will not see an updated time_access |
| 12302 |
attribute. However, in many operating environments, neither will |
| 12303 |
any process running on the server. Thus, NFS clients are at no |
| 12304 |
disadvantage with respect to local processes. |
| 12305 |
|
| 12306 |
o If there is another client that is memory mapping the file, and if |
| 12307 |
that client is holding an OPEN_DELEGATE_WRITE delegation, the same |
| 12308 |
set of issues as discussed in the previous two bullet points |
| 12309 |
apply. So, when a server does a CB_GETATTR to a file that the |
| 12310 |
client has modified in its cache, the reply from CB_GETATTR will |
| 12311 |
not necessarily be accurate. As discussed earlier, the client's |
| 12312 |
obligation is to report that the file has been modified since the |
| 12313 |
|
| 12314 |
|
| 12315 |
|
| 12316 |
<span class="grey">Shepler, et al. Standards Track [Page 220]</span></pre> |
| 12317 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-221" ></span> |
| 12318 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12319 |
|
| 12320 |
|
| 12321 |
delegation was granted, not whether it has been modified again |
| 12322 |
between successive CB_GETATTR calls, and the server MUST assume |
| 12323 |
that any file the client has modified in cache has been modified |
| 12324 |
again between successive CB_GETATTR calls. Depending on the |
| 12325 |
nature of the client's memory management system, this weak |
| 12326 |
obligation may not be possible. A client MAY return stale |
| 12327 |
information in CB_GETATTR whenever the file is memory-mapped. |
| 12328 |
|
| 12329 |
o The mixture of memory mapping and byte-range locking on the same |
| 12330 |
file is problematic. Consider the following scenario, where a |
| 12331 |
page size on each client is 8192 bytes. |
| 12332 |
|
| 12333 |
* Client A memory maps the first page (8192 bytes) of file X. |
| 12334 |
|
| 12335 |
* Client B memory maps the first page (8192 bytes) of file X. |
| 12336 |
|
| 12337 |
* Client A WRITE_LT locks the first 4096 bytes. |
| 12338 |
|
| 12339 |
* Client B WRITE_LT locks the second 4096 bytes. |
| 12340 |
|
| 12341 |
* Client A, via a STORE instruction, modifies part of its locked |
| 12342 |
byte-range. |
| 12343 |
|
| 12344 |
* Simultaneous to client A, client B executes a STORE on part of |
| 12345 |
its locked byte-range. |
| 12346 |
|
| 12347 |
Here the challenge is for each client to resynchronize to get a |
| 12348 |
correct view of the first page. In many operating environments, the |
| 12349 |
virtual memory management systems on each client only know a page is |
| 12350 |
modified, not that a subset of the page corresponding to the |
| 12351 |
respective lock byte-ranges has been modified. So it is not possible |
| 12352 |
for each client to do the right thing, which is to write to the |
| 12353 |
server only that portion of the page that is locked. For example, if |
| 12354 |
client A simply writes out the page, and then client B writes out the |
| 12355 |
page, client A's data is lost. |
| 12356 |
|
| 12357 |
Moreover, if mandatory locking is enabled on the file, then we have a |
| 12358 |
different problem. When clients A and B execute the STORE |
| 12359 |
instructions, the resulting page faults require a byte-range lock on |
| 12360 |
the entire page. Each client then tries to extend their locked range |
| 12361 |
to the entire page, which results in a deadlock. Communicating the |
| 12362 |
NFS4ERR_DEADLOCK error to a STORE instruction is difficult at best. |
| 12363 |
|
| 12364 |
If a client is locking the entire memory-mapped file, there is no |
| 12365 |
problem with advisory or mandatory byte-range locking, at least until |
| 12366 |
the client unlocks a byte-range in the middle of the file. |
| 12367 |
|
| 12368 |
|
| 12369 |
|
| 12370 |
|
| 12371 |
|
| 12372 |
<span class="grey">Shepler, et al. Standards Track [Page 221]</span></pre> |
| 12373 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-222" ></span> |
| 12374 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12375 |
|
| 12376 |
|
| 12377 |
Given the above issues, the following are permitted: |
| 12378 |
|
| 12379 |
o Clients and servers MAY deny memory mapping a file for which they |
| 12380 |
know there are byte-range locks. |
| 12381 |
|
| 12382 |
o Clients and servers MAY deny a byte-range lock on a file they know |
| 12383 |
is memory-mapped. |
| 12384 |
|
| 12385 |
o A client MAY deny memory mapping a file that it knows requires |
| 12386 |
mandatory locking for I/O. If mandatory locking is enabled after |
| 12387 |
the file is opened and mapped, the client MAY deny the application |
| 12388 |
further access to its mapped file. |
| 12389 |
|
| 12390 |
<span class="h3"><a class="selflink" id="section-10.8" href="#section-10.8">10.8</a>. Name and Directory Caching without Directory Delegations</span> |
| 12391 |
|
| 12392 |
The NFSv4.1 directory delegation facility (described in <a href="#section-10.9">Section 10.9</a> |
| 12393 |
below) is OPTIONAL for servers to implement. Even where it is |
| 12394 |
implemented, it may not always be functional because of resource |
| 12395 |
availability issues or other constraints. Thus, it is important to |
| 12396 |
understand how name and directory caching are done in the absence of |
| 12397 |
directory delegations. These topics are discussed in the next two |
| 12398 |
subsections. |
| 12399 |
|
| 12400 |
<span class="h4"><a class="selflink" id="section-10.8.1" href="#section-10.8.1">10.8.1</a>. Name Caching</span> |
| 12401 |
|
| 12402 |
The results of LOOKUP and READDIR operations may be cached to avoid |
| 12403 |
the cost of subsequent LOOKUP operations. Just as in the case of |
| 12404 |
attribute caching, inconsistencies may arise among the various client |
| 12405 |
caches. To mitigate the effects of these inconsistencies and given |
| 12406 |
the context of typical file system APIs, an upper time boundary is |
| 12407 |
maintained for how long a client name cache entry can be kept without |
| 12408 |
verifying that the entry has not been made invalid by a directory |
| 12409 |
change operation performed by another client. |
| 12410 |
|
| 12411 |
When a client is not making changes to a directory for which there |
| 12412 |
exist name cache entries, the client needs to periodically fetch |
| 12413 |
attributes for that directory to ensure that it is not being |
| 12414 |
modified. After determining that no modification has occurred, the |
| 12415 |
expiration time for the associated name cache entries may be updated |
| 12416 |
to be the current time plus the name cache staleness bound. |
| 12417 |
|
| 12418 |
When a client is making changes to a given directory, it needs to |
| 12419 |
determine whether there have been changes made to the directory by |
| 12420 |
other clients. It does this by using the change attribute as |
| 12421 |
reported before and after the directory operation in the associated |
| 12422 |
change_info4 value returned for the operation. The server is able to |
| 12423 |
communicate to the client whether the change_info4 data is provided |
| 12424 |
atomically with respect to the directory operation. If the change |
| 12425 |
|
| 12426 |
|
| 12427 |
|
| 12428 |
<span class="grey">Shepler, et al. Standards Track [Page 222]</span></pre> |
| 12429 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-223" ></span> |
| 12430 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12431 |
|
| 12432 |
|
| 12433 |
values are provided atomically, the client has a basis for |
| 12434 |
determining, given proper care, whether other clients are modifying |
| 12435 |
the directory in question. |
| 12436 |
|
| 12437 |
The simplest way to enable the client to make this determination is |
| 12438 |
for the client to serialize all changes made to a specific directory. |
| 12439 |
When this is done, and the server provides before and after values of |
| 12440 |
the change attribute atomically, the client can simply compare the |
| 12441 |
after value of the change attribute from one operation on a directory |
| 12442 |
with the before value on the subsequent operation modifying that |
| 12443 |
directory. When these are equal, the client is assured that no other |
| 12444 |
client is modifying the directory in question. |
| 12445 |
|
| 12446 |
When such serialization is not used, and there may be multiple |
| 12447 |
simultaneous outstanding operations modifying a single directory sent |
| 12448 |
from a single client, making this sort of determination can be more |
| 12449 |
complicated. If two such operations complete in a different order |
| 12450 |
than they were actually performed, that might give an appearance |
| 12451 |
consistent with modification being made by another client. Where |
| 12452 |
this appears to happen, the client needs to await the completion of |
| 12453 |
all such modifications that were started previously, to see if the |
| 12454 |
outstanding before and after change numbers can be sorted into a |
| 12455 |
chain such that the before value of one change number matches the |
| 12456 |
after value of a previous one, in a chain consistent with this client |
| 12457 |
being the only one modifying the directory. |
| 12458 |
|
| 12459 |
In either of these cases, the client is able to determine whether the |
| 12460 |
directory is being modified by another client. If the comparison |
| 12461 |
indicates that the directory was updated by another client, the name |
| 12462 |
cache associated with the modified directory is purged from the |
| 12463 |
client. If the comparison indicates no modification, the name cache |
| 12464 |
can be updated on the client to reflect the directory operation and |
| 12465 |
the associated timeout can be extended. The post-operation change |
| 12466 |
value needs to be saved as the basis for future change_info4 |
| 12467 |
comparisons. |
| 12468 |
|
| 12469 |
As demonstrated by the scenario above, name caching requires that the |
| 12470 |
client revalidate name cache data by inspecting the change attribute |
| 12471 |
of a directory at the point when the name cache item was cached. |
| 12472 |
This requires that the server update the change attribute for |
| 12473 |
directories when the contents of the corresponding directory is |
| 12474 |
modified. For a client to use the change_info4 information |
| 12475 |
appropriately and correctly, the server must report the pre- and |
| 12476 |
post-operation change attribute values atomically. When the server |
| 12477 |
is unable to report the before and after values atomically with |
| 12478 |
respect to the directory operation, the server must indicate that |
| 12479 |
|
| 12480 |
|
| 12481 |
|
| 12482 |
|
| 12483 |
|
| 12484 |
<span class="grey">Shepler, et al. Standards Track [Page 223]</span></pre> |
| 12485 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-224" ></span> |
| 12486 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12487 |
|
| 12488 |
|
| 12489 |
fact in the change_info4 return value. When the information is not |
| 12490 |
atomically reported, the client should not assume that other clients |
| 12491 |
have not changed the directory. |
| 12492 |
|
| 12493 |
<span class="h4"><a class="selflink" id="section-10.8.2" href="#section-10.8.2">10.8.2</a>. Directory Caching</span> |
| 12494 |
|
| 12495 |
The results of READDIR operations may be used to avoid subsequent |
| 12496 |
READDIR operations. Just as in the cases of attribute and name |
| 12497 |
caching, inconsistencies may arise among the various client caches. |
| 12498 |
To mitigate the effects of these inconsistencies, and given the |
| 12499 |
context of typical file system APIs, the following rules should be |
| 12500 |
followed: |
| 12501 |
|
| 12502 |
o Cached READDIR information for a directory that is not obtained in |
| 12503 |
a single READDIR operation must always be a consistent snapshot of |
| 12504 |
directory contents. This is determined by using a GETATTR before |
| 12505 |
the first READDIR and after the last READDIR that contributes to |
| 12506 |
the cache. |
| 12507 |
|
| 12508 |
o An upper time boundary is maintained to indicate the length of |
| 12509 |
time a directory cache entry is considered valid before the client |
| 12510 |
must revalidate the cached information. |
| 12511 |
|
| 12512 |
The revalidation technique parallels that discussed in the case of |
| 12513 |
name caching. When the client is not changing the directory in |
| 12514 |
question, checking the change attribute of the directory with GETATTR |
| 12515 |
is adequate. The lifetime of the cache entry can be extended at |
| 12516 |
these checkpoints. When a client is modifying the directory, the |
| 12517 |
client needs to use the change_info4 data to determine whether there |
| 12518 |
are other clients modifying the directory. If it is determined that |
| 12519 |
no other client modifications are occurring, the client may update |
| 12520 |
its directory cache to reflect its own changes. |
| 12521 |
|
| 12522 |
As demonstrated previously, directory caching requires that the |
| 12523 |
client revalidate directory cache data by inspecting the change |
| 12524 |
attribute of a directory at the point when the directory was cached. |
| 12525 |
This requires that the server update the change attribute for |
| 12526 |
directories when the contents of the corresponding directory is |
| 12527 |
modified. For a client to use the change_info4 information |
| 12528 |
appropriately and correctly, the server must report the pre- and |
| 12529 |
post-operation change attribute values atomically. When the server |
| 12530 |
is unable to report the before and after values atomically with |
| 12531 |
respect to the directory operation, the server must indicate that |
| 12532 |
fact in the change_info4 return value. When the information is not |
| 12533 |
atomically reported, the client should not assume that other clients |
| 12534 |
have not changed the directory. |
| 12535 |
|
| 12536 |
|
| 12537 |
|
| 12538 |
|
| 12539 |
|
| 12540 |
<span class="grey">Shepler, et al. Standards Track [Page 224]</span></pre> |
| 12541 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-225" ></span> |
| 12542 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12543 |
|
| 12544 |
|
| 12545 |
<span class="h3"><a class="selflink" id="section-10.9" href="#section-10.9">10.9</a>. Directory Delegations</span> |
| 12546 |
|
| 12547 |
<span class="h4"><a class="selflink" id="section-10.9.1" href="#section-10.9.1">10.9.1</a>. Introduction to Directory Delegations</span> |
| 12548 |
|
| 12549 |
Directory caching for the NFSv4.1 protocol, as previously described, |
| 12550 |
is similar to file caching in previous versions. Clients typically |
| 12551 |
cache directory information for a duration determined by the client. |
| 12552 |
At the end of a predefined timeout, the client will query the server |
| 12553 |
to see if the directory has been updated. By caching attributes, |
| 12554 |
clients reduce the number of GETATTR calls made to the server to |
| 12555 |
validate attributes. Furthermore, frequently accessed files and |
| 12556 |
directories, such as the current working directory, have their |
| 12557 |
attributes cached on the client so that some NFS operations can be |
| 12558 |
performed without having to make an RPC call. By caching name and |
| 12559 |
inode information about most recently looked up entries in a |
| 12560 |
Directory Name Lookup Cache (DNLC), clients do not need to send |
| 12561 |
LOOKUP calls to the server every time these files are accessed. |
| 12562 |
|
| 12563 |
This caching approach works reasonably well at reducing network |
| 12564 |
traffic in many environments. However, it does not address |
| 12565 |
environments where there are numerous queries for files that do not |
| 12566 |
exist. In these cases of "misses", the client sends requests to the |
| 12567 |
server in order to provide reasonable application semantics and |
| 12568 |
promptly detect the creation of new directory entries. Examples of |
| 12569 |
high miss activity are compilation in software development |
| 12570 |
environments. The current behavior of NFS limits its potential |
| 12571 |
scalability and wide-area sharing effectiveness in these types of |
| 12572 |
environments. Other distributed stateful file system architectures |
| 12573 |
such as AFS and DFS have proven that adding state around directory |
| 12574 |
contents can greatly reduce network traffic in high-miss |
| 12575 |
environments. |
| 12576 |
|
| 12577 |
Delegation of directory contents is an OPTIONAL feature of NFSv4.1. |
| 12578 |
Directory delegations provide similar traffic reduction benefits as |
| 12579 |
with file delegations. By allowing clients to cache directory |
| 12580 |
contents (in a read-only fashion) while being notified of changes, |
| 12581 |
the client can avoid making frequent requests to interrogate the |
| 12582 |
contents of slowly-changing directories, reducing network traffic and |
| 12583 |
improving client performance. It can also simplify the task of |
| 12584 |
determining whether other clients are making changes to the directory |
| 12585 |
when the client itself is making many changes to the directory and |
| 12586 |
changes are not serialized. |
| 12587 |
|
| 12588 |
Directory delegations allow improved namespace cache consistency to |
| 12589 |
be achieved through delegations and synchronous recalls, in the |
| 12590 |
absence of notifications. In addition, if time-based consistency is |
| 12591 |
|
| 12592 |
|
| 12593 |
|
| 12594 |
|
| 12595 |
|
| 12596 |
<span class="grey">Shepler, et al. Standards Track [Page 225]</span></pre> |
| 12597 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-226" ></span> |
| 12598 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12599 |
|
| 12600 |
|
| 12601 |
sufficient, asynchronous notifications can provide performance |
| 12602 |
benefits for the client, and possibly the server, under some common |
| 12603 |
operating conditions such as slowly-changing and/or very large |
| 12604 |
directories. |
| 12605 |
|
| 12606 |
<span class="h4"><a class="selflink" id="section-10.9.2" href="#section-10.9.2">10.9.2</a>. Directory Delegation Design</span> |
| 12607 |
|
| 12608 |
NFSv4.1 introduces the GET_DIR_DELEGATION (<a href="#section-18.39">Section 18.39</a>) operation |
| 12609 |
to allow the client to ask for a directory delegation. The |
| 12610 |
delegation covers directory attributes and all entries in the |
| 12611 |
directory. If either of these change, the delegation will be |
| 12612 |
recalled synchronously. The operation causing the recall will have |
| 12613 |
to wait before the recall is complete. Any changes to directory |
| 12614 |
entry attributes will not cause the delegation to be recalled. |
| 12615 |
|
| 12616 |
In addition to asking for delegations, a client can also ask for |
| 12617 |
notifications for certain events. These events include changes to |
| 12618 |
the directory's attributes and/or its contents. If a client asks for |
| 12619 |
notification for a certain event, the server will notify the client |
| 12620 |
when that event occurs. This will not result in the delegation being |
| 12621 |
recalled for that client. The notifications are asynchronous and |
| 12622 |
provide a way of avoiding recalls in situations where a directory is |
| 12623 |
changing enough that the pure recall model may not be effective while |
| 12624 |
trying to allow the client to get substantial benefit. In the |
| 12625 |
absence of notifications, once the delegation is recalled the client |
| 12626 |
has to refresh its directory cache; this might not be very efficient |
| 12627 |
for very large directories. |
| 12628 |
|
| 12629 |
The delegation is read-only and the client may not make changes to |
| 12630 |
the directory other than by performing NFSv4.1 operations that modify |
| 12631 |
the directory or the associated file attributes so that the server |
| 12632 |
has knowledge of these changes. In order to keep the client's |
| 12633 |
namespace synchronized with the server, the server will notify the |
| 12634 |
delegation-holding client (assuming it has requested notifications) |
| 12635 |
of the changes made as a result of that client's directory-modifying |
| 12636 |
operations. This is to avoid any need for that client to send |
| 12637 |
subsequent GETATTR or READDIR operations to the server. If a single |
| 12638 |
client is holding the delegation and that client makes any changes to |
| 12639 |
the directory (i.e., the changes are made via operations sent on a |
| 12640 |
session associated with the client ID holding the delegation), the |
| 12641 |
delegation will not be recalled. Multiple clients may hold a |
| 12642 |
delegation on the same directory, but if any such client modifies the |
| 12643 |
directory, the server MUST recall the delegation from the other |
| 12644 |
clients, unless those clients have made provisions to be notified of |
| 12645 |
that sort of modification. |
| 12646 |
|
| 12647 |
|
| 12648 |
|
| 12649 |
|
| 12650 |
|
| 12651 |
|
| 12652 |
<span class="grey">Shepler, et al. Standards Track [Page 226]</span></pre> |
| 12653 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-227" ></span> |
| 12654 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12655 |
|
| 12656 |
|
| 12657 |
Delegations can be recalled by the server at any time. Normally, the |
| 12658 |
server will recall the delegation when the directory changes in a way |
| 12659 |
that is not covered by the notification, or when the directory |
| 12660 |
changes and notifications have not been requested. If another client |
| 12661 |
removes the directory for which a delegation has been granted, the |
| 12662 |
server will recall the delegation. |
| 12663 |
|
| 12664 |
<span class="h4"><a class="selflink" id="section-10.9.3" href="#section-10.9.3">10.9.3</a>. Attributes in Support of Directory Notifications</span> |
| 12665 |
|
| 12666 |
See <a href="#section-5.11">Section 5.11</a> for a description of the attributes associated with |
| 12667 |
directory notifications. |
| 12668 |
|
| 12669 |
<span class="h4"><a class="selflink" id="section-10.9.4" href="#section-10.9.4">10.9.4</a>. Directory Delegation Recall</span> |
| 12670 |
|
| 12671 |
The server will recall the directory delegation by sending a callback |
| 12672 |
to the client. It will use the same callback procedure as used for |
| 12673 |
recalling file delegations. The server will recall the delegation |
| 12674 |
when the directory changes in a way that is not covered by the |
| 12675 |
notification. However, the server need not recall the delegation if |
| 12676 |
attributes of an entry within the directory change. |
| 12677 |
|
| 12678 |
If the server notices that handing out a delegation for a directory |
| 12679 |
is causing too many notifications to be sent out, it may decide to |
| 12680 |
not hand out delegations for that directory and/or recall those |
| 12681 |
already granted. If a client tries to remove the directory for which |
| 12682 |
a delegation has been granted, the server will recall all associated |
| 12683 |
delegations. |
| 12684 |
|
| 12685 |
The implementation sections for a number of operations describe |
| 12686 |
situations in which notification or delegation recall would be |
| 12687 |
required under some common circumstances. In this regard, a similar |
| 12688 |
set of caveats to those listed in <a href="#section-10.2">Section 10.2</a> apply. |
| 12689 |
|
| 12690 |
o For CREATE, see <a href="#section-18.4.4">Section 18.4.4</a>. |
| 12691 |
|
| 12692 |
o For LINK, see <a href="#section-18.9.4">Section 18.9.4</a>. |
| 12693 |
|
| 12694 |
o For OPEN, see <a href="#section-18.16.4">Section 18.16.4</a>. |
| 12695 |
|
| 12696 |
o For REMOVE, see <a href="#section-18.25.4">Section 18.25.4</a>. |
| 12697 |
|
| 12698 |
o For RENAME, see <a href="#section-18.26.4">Section 18.26.4</a>. |
| 12699 |
|
| 12700 |
o For SETATTR, see <a href="#section-18.30.4">Section 18.30.4</a>. |
| 12701 |
|
| 12702 |
|
| 12703 |
|
| 12704 |
|
| 12705 |
|
| 12706 |
|
| 12707 |
|
| 12708 |
<span class="grey">Shepler, et al. Standards Track [Page 227]</span></pre> |
| 12709 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-228" ></span> |
| 12710 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12711 |
|
| 12712 |
|
| 12713 |
<span class="h4"><a class="selflink" id="section-10.9.5" href="#section-10.9.5">10.9.5</a>. Directory Delegation Recovery</span> |
| 12714 |
|
| 12715 |
Recovery from client or server restart for state on regular files has |
| 12716 |
two main goals: avoiding the necessity of breaking application |
| 12717 |
guarantees with respect to locked files and delivery of updates |
| 12718 |
cached at the client. Neither of these goals applies to directories |
| 12719 |
protected by OPEN_DELEGATE_READ delegations and notifications. Thus, |
| 12720 |
no provision is made for reclaiming directory delegations in the |
| 12721 |
event of client or server restart. The client can simply establish a |
| 12722 |
directory delegation in the same fashion as was done initially. |
| 12723 |
|
| 12724 |
<span class="h2"><a class="selflink" id="section-11" href="#section-11">11</a>. Multi-Server Namespace</span> |
| 12725 |
|
| 12726 |
NFSv4.1 supports attributes that allow a namespace to extend beyond |
| 12727 |
the boundaries of a single server. It is RECOMMENDED that clients |
| 12728 |
and servers support construction of such multi-server namespaces. |
| 12729 |
Use of such multi-server namespaces is OPTIONAL, however, and for |
| 12730 |
many purposes, single-server namespaces are perfectly acceptable. |
| 12731 |
Use of multi-server namespaces can provide many advantages, however, |
| 12732 |
by separating a file system's logical position in a namespace from |
| 12733 |
the (possibly changing) logistical and administrative considerations |
| 12734 |
that result in particular file systems being located on particular |
| 12735 |
servers. |
| 12736 |
|
| 12737 |
<span class="h3"><a class="selflink" id="section-11.1" href="#section-11.1">11.1</a>. Location Attributes</span> |
| 12738 |
|
| 12739 |
NFSv4.1 contains RECOMMENDED attributes that allow file systems on |
| 12740 |
one server to be associated with one or more instances of that file |
| 12741 |
system on other servers. These attributes specify such file system |
| 12742 |
instances by specifying a server address target (either as a DNS name |
| 12743 |
representing one or more IP addresses or as a literal IP address) |
| 12744 |
together with the path of that file system within the associated |
| 12745 |
single-server namespace. |
| 12746 |
|
| 12747 |
The fs_locations_info RECOMMENDED attribute allows specification of |
| 12748 |
one or more file system instance locations where the data |
| 12749 |
corresponding to a given file system may be found. This attribute |
| 12750 |
provides to the client, in addition to information about file system |
| 12751 |
instance locations, significant information about the various file |
| 12752 |
system instance choices (e.g., priority for use, writability, |
| 12753 |
currency, etc.). It also includes information to help the client |
| 12754 |
efficiently effect as seamless a transition as possible among |
| 12755 |
multiple file system instances, when and if that should be necessary. |
| 12756 |
|
| 12757 |
|
| 12758 |
|
| 12759 |
|
| 12760 |
|
| 12761 |
|
| 12762 |
|
| 12763 |
|
| 12764 |
<span class="grey">Shepler, et al. Standards Track [Page 228]</span></pre> |
| 12765 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-229" ></span> |
| 12766 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12767 |
|
| 12768 |
|
| 12769 |
The fs_locations RECOMMENDED attribute is inherited from NFSv4.0 and |
| 12770 |
only allows specification of the file system locations where the data |
| 12771 |
corresponding to a given file system may be found. Servers SHOULD |
| 12772 |
make this attribute available whenever fs_locations_info is |
| 12773 |
supported, but client use of fs_locations_info is to be preferred. |
| 12774 |
|
| 12775 |
<span class="h3"><a class="selflink" id="section-11.2" href="#section-11.2">11.2</a>. File System Presence or Absence</span> |
| 12776 |
|
| 12777 |
A given location in an NFSv4.1 namespace (typically but not |
| 12778 |
necessarily a multi-server namespace) can have a number of file |
| 12779 |
system instance locations associated with it (via the fs_locations or |
| 12780 |
fs_locations_info attribute). There may also be an actual current |
| 12781 |
file system at that location, accessible via normal namespace |
| 12782 |
operations (e.g., LOOKUP). In this case, the file system is said to |
| 12783 |
be "present" at that position in the namespace, and clients will |
| 12784 |
typically use it, reserving use of additional locations specified via |
| 12785 |
the location-related attributes to situations in which the principal |
| 12786 |
location is no longer available. |
| 12787 |
|
| 12788 |
When there is no actual file system at the namespace location in |
| 12789 |
question, the file system is said to be "absent". An absent file |
| 12790 |
system contains no files or directories other than the root. Any |
| 12791 |
reference to it, except to access a small set of attributes useful in |
| 12792 |
determining alternate locations, will result in an error, |
| 12793 |
NFS4ERR_MOVED. Note that if the server ever returns the error |
| 12794 |
NFS4ERR_MOVED, it MUST support the fs_locations attribute and SHOULD |
| 12795 |
support the fs_locations_info and fs_status attributes. |
| 12796 |
|
| 12797 |
While the error name suggests that we have a case of a file system |
| 12798 |
that once was present, and has only become absent later, this is only |
| 12799 |
one possibility. A position in the namespace may be permanently |
| 12800 |
absent with the set of file system(s) designated by the location |
| 12801 |
attributes being the only realization. The name NFS4ERR_MOVED |
| 12802 |
reflects an earlier, more limited conception of its function, but |
| 12803 |
this error will be returned whenever the referenced file system is |
| 12804 |
absent, whether it has moved or not. |
| 12805 |
|
| 12806 |
Except in the case of GETATTR-type operations (to be discussed |
| 12807 |
later), when the current filehandle at the start of an operation is |
| 12808 |
within an absent file system, that operation is not performed and the |
| 12809 |
error NFS4ERR_MOVED is returned, to indicate that the file system is |
| 12810 |
absent on the current server. |
| 12811 |
|
| 12812 |
Because a GETFH cannot succeed if the current filehandle is within an |
| 12813 |
absent file system, filehandles within an absent file system cannot |
| 12814 |
be transferred to the client. When a client does have filehandles |
| 12815 |
|
| 12816 |
|
| 12817 |
|
| 12818 |
|
| 12819 |
|
| 12820 |
<span class="grey">Shepler, et al. Standards Track [Page 229]</span></pre> |
| 12821 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-230" ></span> |
| 12822 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12823 |
|
| 12824 |
|
| 12825 |
within an absent file system, it is the result of obtaining them when |
| 12826 |
the file system was present, and having the file system become absent |
| 12827 |
subsequently. |
| 12828 |
|
| 12829 |
It should be noted that because the check for the current filehandle |
| 12830 |
being within an absent file system happens at the start of every |
| 12831 |
operation, operations that change the current filehandle so that it |
| 12832 |
is within an absent file system will not result in an error. This |
| 12833 |
allows such combinations as PUTFH-GETATTR and LOOKUP-GETATTR to be |
| 12834 |
used to get attribute information, particularly location attribute |
| 12835 |
information, as discussed below. |
| 12836 |
|
| 12837 |
The RECOMMENDED file system attribute fs_status can be used to |
| 12838 |
interrogate the present/absent status of a given file system. |
| 12839 |
|
| 12840 |
<span class="h3"><a class="selflink" id="section-11.3" href="#section-11.3">11.3</a>. Getting Attributes for an Absent File System</span> |
| 12841 |
|
| 12842 |
When a file system is absent, most attributes are not available, but |
| 12843 |
it is necessary to allow the client access to the small set of |
| 12844 |
attributes that are available, and most particularly those that give |
| 12845 |
information about the correct current locations for this file system: |
| 12846 |
fs_locations and fs_locations_info. |
| 12847 |
|
| 12848 |
<span class="h4"><a class="selflink" id="section-11.3.1" href="#section-11.3.1">11.3.1</a>. GETATTR within an Absent File System</span> |
| 12849 |
|
| 12850 |
As mentioned above, an exception is made for GETATTR in that |
| 12851 |
attributes may be obtained for a filehandle within an absent file |
| 12852 |
system. This exception only applies if the attribute mask contains |
| 12853 |
at least one attribute bit that indicates the client is interested in |
| 12854 |
a result regarding an absent file system: fs_locations, |
| 12855 |
fs_locations_info, or fs_status. If none of these attributes is |
| 12856 |
requested, GETATTR will result in an NFS4ERR_MOVED error. |
| 12857 |
|
| 12858 |
When a GETATTR is done on an absent file system, the set of supported |
| 12859 |
attributes is very limited. Many attributes, including those that |
| 12860 |
are normally REQUIRED, will not be available on an absent file |
| 12861 |
system. In addition to the attributes mentioned above (fs_locations, |
| 12862 |
fs_locations_info, fs_status), the following attributes SHOULD be |
| 12863 |
available on absent file systems. In the case of RECOMMENDED |
| 12864 |
attributes, they should be available at least to the same degree that |
| 12865 |
they are available on present file systems. |
| 12866 |
|
| 12867 |
change_policy: This attribute is useful for absent file systems and |
| 12868 |
can be helpful in summarizing to the client when any of the |
| 12869 |
location-related attributes change. |
| 12870 |
|
| 12871 |
|
| 12872 |
|
| 12873 |
|
| 12874 |
|
| 12875 |
|
| 12876 |
<span class="grey">Shepler, et al. Standards Track [Page 230]</span></pre> |
| 12877 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-231" ></span> |
| 12878 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12879 |
|
| 12880 |
|
| 12881 |
fsid: This attribute should be provided so that the client can |
| 12882 |
determine file system boundaries, including, in particular, the |
| 12883 |
boundary between present and absent file systems. This value must |
| 12884 |
be different from any other fsid on the current server and need |
| 12885 |
have no particular relationship to fsids on any particular |
| 12886 |
destination to which the client might be directed. |
| 12887 |
|
| 12888 |
mounted_on_fileid: For objects at the top of an absent file system, |
| 12889 |
this attribute needs to be available. Since the fileid is within |
| 12890 |
the present parent file system, there should be no need to |
| 12891 |
reference the absent file system to provide this information. |
| 12892 |
|
| 12893 |
Other attributes SHOULD NOT be made available for absent file |
| 12894 |
systems, even when it is possible to provide them. The server should |
| 12895 |
not assume that more information is always better and should avoid |
| 12896 |
gratuitously providing additional information. |
| 12897 |
|
| 12898 |
When a GETATTR operation includes a bit mask for one of the |
| 12899 |
attributes fs_locations, fs_locations_info, or fs_status, but where |
| 12900 |
the bit mask includes attributes that are not supported, GETATTR will |
| 12901 |
not return an error, but will return the mask of the actual |
| 12902 |
attributes supported with the results. |
| 12903 |
|
| 12904 |
Handling of VERIFY/NVERIFY is similar to GETATTR in that if the |
| 12905 |
attribute mask does not include fs_locations, fs_locations_info, or |
| 12906 |
fs_status, the error NFS4ERR_MOVED will result. It differs in that |
| 12907 |
any appearance in the attribute mask of an attribute not supported |
| 12908 |
for an absent file system (and note that this will include some |
| 12909 |
normally REQUIRED attributes) will also cause an NFS4ERR_MOVED |
| 12910 |
result. |
| 12911 |
|
| 12912 |
<span class="h4"><a class="selflink" id="section-11.3.2" href="#section-11.3.2">11.3.2</a>. READDIR and Absent File Systems</span> |
| 12913 |
|
| 12914 |
A READDIR performed when the current filehandle is within an absent |
| 12915 |
file system will result in an NFS4ERR_MOVED error, since, unlike the |
| 12916 |
case of GETATTR, no such exception is made for READDIR. |
| 12917 |
|
| 12918 |
Attributes for an absent file system may be fetched via a READDIR for |
| 12919 |
a directory in a present file system, when that directory contains |
| 12920 |
the root directories of one or more absent file systems. In this |
| 12921 |
case, the handling is as follows: |
| 12922 |
|
| 12923 |
o If the attribute set requested includes one of the attributes |
| 12924 |
fs_locations, fs_locations_info, or fs_status, then fetching of |
| 12925 |
attributes proceeds normally and no NFS4ERR_MOVED indication is |
| 12926 |
returned, even when the rdattr_error attribute is requested. |
| 12927 |
|
| 12928 |
|
| 12929 |
|
| 12930 |
|
| 12931 |
|
| 12932 |
<span class="grey">Shepler, et al. Standards Track [Page 231]</span></pre> |
| 12933 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-232" ></span> |
| 12934 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12935 |
|
| 12936 |
|
| 12937 |
o If the attribute set requested does not include one of the |
| 12938 |
attributes fs_locations, fs_locations_info, or fs_status, then if |
| 12939 |
the rdattr_error attribute is requested, each directory entry for |
| 12940 |
the root of an absent file system will report NFS4ERR_MOVED as the |
| 12941 |
value of the rdattr_error attribute. |
| 12942 |
|
| 12943 |
o If the attribute set requested does not include any of the |
| 12944 |
attributes fs_locations, fs_locations_info, fs_status, or |
| 12945 |
rdattr_error, then the occurrence of the root of an absent file |
| 12946 |
system within the directory will result in the READDIR failing |
| 12947 |
with an NFS4ERR_MOVED error. |
| 12948 |
|
| 12949 |
o The unavailability of an attribute because of a file system's |
| 12950 |
absence, even one that is ordinarily REQUIRED, does not result in |
| 12951 |
any error indication. The set of attributes returned for the root |
| 12952 |
directory of the absent file system in that case is simply |
| 12953 |
restricted to those actually available. |
| 12954 |
|
| 12955 |
<span class="h3"><a class="selflink" id="section-11.4" href="#section-11.4">11.4</a>. Uses of Location Information</span> |
| 12956 |
|
| 12957 |
The location-bearing attributes (fs_locations and fs_locations_info), |
| 12958 |
together with the possibility of absent file systems, provide a |
| 12959 |
number of important facilities in providing reliable, manageable, and |
| 12960 |
scalable data access. |
| 12961 |
|
| 12962 |
When a file system is present, these attributes can provide |
| 12963 |
alternative locations, to be used to access the same data, in the |
| 12964 |
event of server failures, communications problems, or other |
| 12965 |
difficulties that make continued access to the current file system |
| 12966 |
impossible or otherwise impractical. Under some circumstances, |
| 12967 |
multiple alternative locations may be used simultaneously to provide |
| 12968 |
higher-performance access to the file system in question. Provision |
| 12969 |
of such alternate locations is referred to as "replication" although |
| 12970 |
there are cases in which replicated sets of data are not in fact |
| 12971 |
present, and the replicas are instead different paths to the same |
| 12972 |
data. |
| 12973 |
|
| 12974 |
When a file system is present and becomes absent, clients can be |
| 12975 |
given the opportunity to have continued access to their data, at an |
| 12976 |
alternate location. In this case, a continued attempt to use the |
| 12977 |
data in the now-absent file system will result in an NFS4ERR_MOVED |
| 12978 |
error and, at that point, the successor locations (typically only one |
| 12979 |
although multiple choices are possible) can be fetched and used to |
| 12980 |
continue access. Transfer of the file system contents to the new |
| 12981 |
location is referred to as "migration", but it should be kept in mind |
| 12982 |
that there are cases in which this term can be used, like |
| 12983 |
"replication", when there is no actual data migration per se. |
| 12984 |
|
| 12985 |
|
| 12986 |
|
| 12987 |
|
| 12988 |
<span class="grey">Shepler, et al. Standards Track [Page 232]</span></pre> |
| 12989 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-233" ></span> |
| 12990 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 12991 |
|
| 12992 |
|
| 12993 |
Where a file system was not previously present, specification of file |
| 12994 |
system location provides a means by which file systems located on one |
| 12995 |
server can be associated with a namespace defined by another server, |
| 12996 |
thus allowing a general multi-server namespace facility. A |
| 12997 |
designation of such a location, in place of an absent file system, is |
| 12998 |
called a "referral". |
| 12999 |
|
| 13000 |
Because client support for location-related attributes is OPTIONAL, a |
| 13001 |
server may (but is not required to) take action to hide migration and |
| 13002 |
referral events from such clients, by acting as a proxy, for example. |
| 13003 |
The server can determine the presence of client support from the |
| 13004 |
arguments of the EXCHANGE_ID operation (see <a href="#section-18.35.3">Section 18.35.3</a>). |
| 13005 |
|
| 13006 |
<span class="h4"><a class="selflink" id="section-11.4.1" href="#section-11.4.1">11.4.1</a>. File System Replication</span> |
| 13007 |
|
| 13008 |
The fs_locations and fs_locations_info attributes provide alternative |
| 13009 |
locations, to be used to access data in place of or in addition to |
| 13010 |
the current file system instance. On first access to a file system, |
| 13011 |
the client should obtain the value of the set of alternate locations |
| 13012 |
by interrogating the fs_locations or fs_locations_info attribute, |
| 13013 |
with the latter being preferred. |
| 13014 |
|
| 13015 |
In the event that server failures, communications problems, or other |
| 13016 |
difficulties make continued access to the current file system |
| 13017 |
impossible or otherwise impractical, the client can use the alternate |
| 13018 |
locations as a way to get continued access to its data. Depending on |
| 13019 |
specific attributes of these alternate locations, as indicated within |
| 13020 |
the fs_locations_info attribute, multiple locations may be used |
| 13021 |
simultaneously, to provide higher performance through the |
| 13022 |
exploitation of multiple paths between client and target file system. |
| 13023 |
|
| 13024 |
The alternate locations may be physical replicas of the (typically |
| 13025 |
read-only) file system data, or they may reflect alternate paths to |
| 13026 |
the same server or provide for the use of various forms of server |
| 13027 |
clustering in which multiple servers provide alternate ways of |
| 13028 |
accessing the same physical file system. How these different modes |
| 13029 |
of file system transition are represented within the fs_locations and |
| 13030 |
fs_locations_info attributes and how the client deals with file |
| 13031 |
system transition issues will be discussed in detail below. |
| 13032 |
|
| 13033 |
Multiple server addresses, whether they are derived from a single |
| 13034 |
entry with a DNS name representing a set of IP addresses or from |
| 13035 |
multiple entries each with its own server address, may correspond to |
| 13036 |
the same actual server. The fact that two addresses correspond to |
| 13037 |
the same server is shown by a common so_major_id field within the |
| 13038 |
eir_server_owner field returned by EXCHANGE_ID (see <a href="#section-18.35.3">Section 18.35.3</a>). |
| 13039 |
|
| 13040 |
|
| 13041 |
|
| 13042 |
|
| 13043 |
|
| 13044 |
<span class="grey">Shepler, et al. Standards Track [Page 233]</span></pre> |
| 13045 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-234" ></span> |
| 13046 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13047 |
|
| 13048 |
|
| 13049 |
For a detailed discussion of how server address targets interact with |
| 13050 |
the determination of server identity specified by the server owner |
| 13051 |
field, see <a href="#section-11.5">Section 11.5</a>. |
| 13052 |
|
| 13053 |
<span class="h4"><a class="selflink" id="section-11.4.2" href="#section-11.4.2">11.4.2</a>. File System Migration</span> |
| 13054 |
|
| 13055 |
When a file system is present and becomes absent, clients can be |
| 13056 |
given the opportunity to have continued access to their data, at an |
| 13057 |
alternate location, as specified by the fs_locations or |
| 13058 |
fs_locations_info attribute. Typically, a client will be accessing |
| 13059 |
the file system in question, get an NFS4ERR_MOVED error, and then use |
| 13060 |
the fs_locations or fs_locations_info attribute to determine the new |
| 13061 |
location of the data. When fs_locations_info is used, additional |
| 13062 |
information will be available that will define the nature of the |
| 13063 |
client's handling of the transition to a new server. |
| 13064 |
|
| 13065 |
Such migration can be helpful in providing load balancing or general |
| 13066 |
resource reallocation. The protocol does not specify how the file |
| 13067 |
system will be moved between servers. It is anticipated that a |
| 13068 |
number of different server-to-server transfer mechanisms might be |
| 13069 |
used with the choice left to the server implementor. The NFSv4.1 |
| 13070 |
protocol specifies the method used to communicate the migration event |
| 13071 |
between client and server. |
| 13072 |
|
| 13073 |
The new location may be an alternate communication path to the same |
| 13074 |
server or, in the case of various forms of server clustering, another |
| 13075 |
server providing access to the same physical file system. The |
| 13076 |
client's responsibilities in dealing with this transition depend on |
| 13077 |
the specific nature of the new access path as well as how and whether |
| 13078 |
data was in fact migrated. These issues will be discussed in detail |
| 13079 |
below. |
| 13080 |
|
| 13081 |
When multiple server addresses correspond to the same actual server, |
| 13082 |
as shown by a common value for the so_major_id field of the |
| 13083 |
eir_server_owner field returned by EXCHANGE_ID, the location or |
| 13084 |
locations may designate alternate server addresses in the form of |
| 13085 |
specific server network addresses. These can be used to access the |
| 13086 |
file system in question at those addresses and when it is no longer |
| 13087 |
accessible at the original address. |
| 13088 |
|
| 13089 |
Although a single successor location is typical, multiple locations |
| 13090 |
may be provided, together with information that allows priority among |
| 13091 |
the choices to be indicated, via information in the fs_locations_info |
| 13092 |
attribute. Where suitable, clustering mechanisms make it possible to |
| 13093 |
provide multiple identical file systems or paths to them; this allows |
| 13094 |
the client the opportunity to deal with any resource or |
| 13095 |
communications issues that might limit data availability. |
| 13096 |
|
| 13097 |
|
| 13098 |
|
| 13099 |
|
| 13100 |
<span class="grey">Shepler, et al. Standards Track [Page 234]</span></pre> |
| 13101 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-235" ></span> |
| 13102 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13103 |
|
| 13104 |
|
| 13105 |
When an alternate location is designated as the target for migration, |
| 13106 |
it must designate the same data (with metadata being the same to the |
| 13107 |
degree indicated by the fs_locations_info attribute). Where file |
| 13108 |
systems are writable, a change made on the original file system must |
| 13109 |
be visible on all migration targets. Where a file system is not |
| 13110 |
writable but represents a read-only copy (possibly periodically |
| 13111 |
updated) of a writable file system, similar requirements apply to the |
| 13112 |
propagation of updates. Any change visible in the original file |
| 13113 |
system must already be effected on all migration targets, to avoid |
| 13114 |
any possibility that a client, in effecting a transition to the |
| 13115 |
migration target, will see any reversion in file system state. |
| 13116 |
|
| 13117 |
<span class="h4"><a class="selflink" id="section-11.4.3" href="#section-11.4.3">11.4.3</a>. Referrals</span> |
| 13118 |
|
| 13119 |
Referrals provide a way of placing a file system in a location within |
| 13120 |
the namespace essentially without respect to its physical location on |
| 13121 |
a given server. This allows a single server or a set of servers to |
| 13122 |
present a multi-server namespace that encompasses file systems |
| 13123 |
located on multiple servers. Some likely uses of this include |
| 13124 |
establishment of site-wide or organization-wide namespaces, or even |
| 13125 |
knitting such together into a truly global namespace. |
| 13126 |
|
| 13127 |
Referrals occur when a client determines, upon first referencing a |
| 13128 |
position in the current namespace, that it is part of a new file |
| 13129 |
system and that the file system is absent. When this occurs, |
| 13130 |
typically by receiving the error NFS4ERR_MOVED, the actual location |
| 13131 |
or locations of the file system can be determined by fetching the |
| 13132 |
fs_locations or fs_locations_info attribute. |
| 13133 |
|
| 13134 |
The locations-related attribute may designate a single file system |
| 13135 |
location or multiple file system locations, to be selected based on |
| 13136 |
the needs of the client. The server, in the fs_locations_info |
| 13137 |
attribute, may specify priorities to be associated with various file |
| 13138 |
system location choices. The server may assign different priorities |
| 13139 |
to different locations as reported to individual clients, in order to |
| 13140 |
adapt to client physical location or to effect load balancing. When |
| 13141 |
both read-only and read-write file systems are present, some of the |
| 13142 |
read-only locations might not be absolutely up-to-date (as they would |
| 13143 |
have to be in the case of replication and migration). Servers may |
| 13144 |
also specify file system locations that include client-substituted |
| 13145 |
variables so that different clients are referred to different file |
| 13146 |
systems (with different data contents) based on client attributes |
| 13147 |
such as CPU architecture. |
| 13148 |
|
| 13149 |
When the fs_locations_info attribute indicates that there are |
| 13150 |
multiple possible targets listed, the relationships among them may be |
| 13151 |
important to the client in selecting which one to use. The same |
| 13152 |
rules specified in <a href="#section-11.4.1">Section 11.4.1</a> defining the appropriate standards |
| 13153 |
|
| 13154 |
|
| 13155 |
|
| 13156 |
<span class="grey">Shepler, et al. Standards Track [Page 235]</span></pre> |
| 13157 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-236" ></span> |
| 13158 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13159 |
|
| 13160 |
|
| 13161 |
for the data propagation apply to these multiple replicas as well. |
| 13162 |
For example, the client might prefer a writable target on a server |
| 13163 |
that has additional writable replicas to which it subsequently might |
| 13164 |
switch. Note that, as distinguished from the case of replication, |
| 13165 |
there is no need to deal with the case of propagation of updates made |
| 13166 |
by the current client, since the current client has not accessed the |
| 13167 |
file system in question. |
| 13168 |
|
| 13169 |
Use of multi-server namespaces is enabled by NFSv4.1 but is not |
| 13170 |
required. The use of multi-server namespaces and their scope will |
| 13171 |
depend on the applications used and system administration |
| 13172 |
preferences. |
| 13173 |
|
| 13174 |
Multi-server namespaces can be established by a single server |
| 13175 |
providing a large set of referrals to all of the included file |
| 13176 |
systems. Alternatively, a single multi-server namespace may be |
| 13177 |
administratively segmented with separate referral file systems (on |
| 13178 |
separate servers) for each separately administered portion of the |
| 13179 |
namespace. The top-level referral file system or any segment may use |
| 13180 |
replicated referral file systems for higher availability. |
| 13181 |
|
| 13182 |
Generally, multi-server namespaces are for the most part uniform, in |
| 13183 |
that the same data made available to one client at a given location |
| 13184 |
in the namespace is made available to all clients at that location. |
| 13185 |
However, there are facilities provided that allow different clients |
| 13186 |
to be directed to different sets of data, so as to adapt to such |
| 13187 |
client characteristics as CPU architecture. |
| 13188 |
|
| 13189 |
<span class="h3"><a class="selflink" id="section-11.5" href="#section-11.5">11.5</a>. Location Entries and Server Identity</span> |
| 13190 |
|
| 13191 |
As mentioned above, a single location entry may have a server address |
| 13192 |
target in the form of a DNS name that may represent multiple IP |
| 13193 |
addresses, while multiple location entries may have their own server |
| 13194 |
address targets that reference the same server. Whether two IP |
| 13195 |
addresses designate the same server is indicated by the existence of |
| 13196 |
a common so_major_id field within the eir_server_owner field returned |
| 13197 |
by EXCHANGE_ID (see <a href="#section-18.35.3">Section 18.35.3</a>), subject to further verification |
| 13198 |
(for details see <a href="#section-2.10.5">Section 2.10.5</a>). |
| 13199 |
|
| 13200 |
When multiple addresses for the same server exist, the client may |
| 13201 |
assume that for each file system in the namespace of a given server |
| 13202 |
network address, there exist file systems at corresponding namespace |
| 13203 |
locations for each of the other server network addresses. It may do |
| 13204 |
this even in the absence of explicit listing in fs_locations and |
| 13205 |
fs_locations_info. Such corresponding file system locations can be |
| 13206 |
used as alternate locations, just as those explicitly specified via |
| 13207 |
the fs_locations and fs_locations_info attributes. Where these |
| 13208 |
specific addresses are explicitly designated in the fs_locations_info |
| 13209 |
|
| 13210 |
|
| 13211 |
|
| 13212 |
<span class="grey">Shepler, et al. Standards Track [Page 236]</span></pre> |
| 13213 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-237" ></span> |
| 13214 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13215 |
|
| 13216 |
|
| 13217 |
attribute, the conditions of use specified in this attribute (e.g., |
| 13218 |
priorities, specification of simultaneous use) may limit the client's |
| 13219 |
use of these alternate locations. |
| 13220 |
|
| 13221 |
If a single location entry designates multiple server IP addresses, |
| 13222 |
the client cannot assume that these addresses are multiple paths to |
| 13223 |
the same server. In most cases, they will be, but the client MUST |
| 13224 |
verify that before acting on that assumption. When two server |
| 13225 |
addresses are designated by a single location entry and they |
| 13226 |
correspond to different servers, this normally indicates some sort of |
| 13227 |
misconfiguration, and so the client should avoid using such location |
| 13228 |
entries when alternatives are available. When they are not, clients |
| 13229 |
should pick one of IP addresses and use it, without using others that |
| 13230 |
are not directed to the same server. |
| 13231 |
|
| 13232 |
<span class="h3"><a class="selflink" id="section-11.6" href="#section-11.6">11.6</a>. Additional Client-Side Considerations</span> |
| 13233 |
|
| 13234 |
When clients make use of servers that implement referrals, |
| 13235 |
replication, and migration, care should be taken that a user who |
| 13236 |
mounts a given file system that includes a referral or a relocated |
| 13237 |
file system continues to see a coherent picture of that user-side |
| 13238 |
file system despite the fact that it contains a number of server-side |
| 13239 |
file systems that may be on different servers. |
| 13240 |
|
| 13241 |
One important issue is upward navigation from the root of a server- |
| 13242 |
side file system to its parent (specified as ".." in UNIX), in the |
| 13243 |
case in which it transitions to that file system as a result of |
| 13244 |
referral, migration, or a transition as a result of replication. |
| 13245 |
When the client is at such a point, and it needs to ascend to the |
| 13246 |
parent, it must go back to the parent as seen within the multi-server |
| 13247 |
namespace rather than sending a LOOKUPP operation to the server, |
| 13248 |
which would result in the parent within that server's single-server |
| 13249 |
namespace. In order to do this, the client needs to remember the |
| 13250 |
filehandles that represent such file system roots and use these |
| 13251 |
instead of sending a LOOKUPP operation to the current server. This |
| 13252 |
will allow the client to present to applications a consistent |
| 13253 |
namespace, where upward navigation and downward navigation are |
| 13254 |
consistent. |
| 13255 |
|
| 13256 |
Another issue concerns refresh of referral locations. When referrals |
| 13257 |
are used extensively, they may change as server configurations |
| 13258 |
change. It is expected that clients will cache information related |
| 13259 |
to traversing referrals so that future client-side requests are |
| 13260 |
resolved locally without server communication. This is usually |
| 13261 |
rooted in client-side name look up caching. Clients should |
| 13262 |
periodically purge this data for referral points in order to detect |
| 13263 |
changes in location information. When the change_policy attribute |
| 13264 |
|
| 13265 |
|
| 13266 |
|
| 13267 |
|
| 13268 |
<span class="grey">Shepler, et al. Standards Track [Page 237]</span></pre> |
| 13269 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-238" ></span> |
| 13270 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13271 |
|
| 13272 |
|
| 13273 |
changes for directories that hold referral entries or for the |
| 13274 |
referral entries themselves, clients should consider any associated |
| 13275 |
cached referral information to be out of date. |
| 13276 |
|
| 13277 |
<span class="h3"><a class="selflink" id="section-11.7" href="#section-11.7">11.7</a>. Effecting File System Transitions</span> |
| 13278 |
|
| 13279 |
Transitions between file system instances, whether due to switching |
| 13280 |
between replicas upon server unavailability or to server-initiated |
| 13281 |
migration events, are best dealt with together. This is so even |
| 13282 |
though, for the server, pragmatic considerations will normally force |
| 13283 |
different implementation strategies for planned and unplanned |
| 13284 |
transitions. Even though the prototypical use cases of replication |
| 13285 |
and migration contain distinctive sets of features, when all |
| 13286 |
possibilities for these operations are considered, there is an |
| 13287 |
underlying unity of these operations, from the client's point of |
| 13288 |
view, that makes treating them together desirable. |
| 13289 |
|
| 13290 |
A number of methods are possible for servers to replicate data and to |
| 13291 |
track client state in order to allow clients to transition between |
| 13292 |
file system instances with a minimum of disruption. Such methods |
| 13293 |
vary between those that use inter-server clustering techniques to |
| 13294 |
limit the changes seen by the client, to those that are less |
| 13295 |
aggressive, use more standard methods of replicating data, and impose |
| 13296 |
a greater burden on the client to adapt to the transition. |
| 13297 |
|
| 13298 |
The NFSv4.1 protocol does not impose choices on clients and servers |
| 13299 |
with regard to that spectrum of transition methods. In fact, there |
| 13300 |
are many valid choices, depending on client and application |
| 13301 |
requirements and their interaction with server implementation |
| 13302 |
choices. The NFSv4.1 protocol does define the specific choices that |
| 13303 |
can be made, how these choices are communicated to the client, and |
| 13304 |
how the client is to deal with any discontinuities. |
| 13305 |
|
| 13306 |
In the sections below, references will be made to various possible |
| 13307 |
server implementation choices as a way of illustrating the transition |
| 13308 |
scenarios that clients may deal with. The intent here is not to |
| 13309 |
define or limit server implementations but rather to illustrate the |
| 13310 |
range of issues that clients may face. |
| 13311 |
|
| 13312 |
In the discussion below, references will be made to a file system |
| 13313 |
having a particular property or to two file systems (typically the |
| 13314 |
source and destination) belonging to a common class of any of several |
| 13315 |
types. Two file systems that belong to such a class share some |
| 13316 |
important aspects of file system behavior that clients may depend |
| 13317 |
upon when present, to easily effect a seamless transition between |
| 13318 |
file system instances. Conversely, where the file systems do not |
| 13319 |
|
| 13320 |
|
| 13321 |
|
| 13322 |
|
| 13323 |
|
| 13324 |
<span class="grey">Shepler, et al. Standards Track [Page 238]</span></pre> |
| 13325 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-239" ></span> |
| 13326 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13327 |
|
| 13328 |
|
| 13329 |
belong to such a common class, the client has to deal with various |
| 13330 |
sorts of implementation discontinuities that may cause performance or |
| 13331 |
other issues in effecting a transition. |
| 13332 |
|
| 13333 |
Where the fs_locations_info attribute is available, such file system |
| 13334 |
classification data will be made directly available to the client |
| 13335 |
(see <a href="#section-11.10">Section 11.10</a> for details). When only fs_locations is |
| 13336 |
available, default assumptions with regard to such classifications |
| 13337 |
have to be inferred (see <a href="#section-11.9">Section 11.9</a> for details). |
| 13338 |
|
| 13339 |
In cases in which one server is expected to accept opaque values from |
| 13340 |
the client that originated from another server, the servers SHOULD |
| 13341 |
encode the "opaque" values in big-endian byte order. If this is |
| 13342 |
done, servers acting as replicas or immigrating file systems will be |
| 13343 |
able to parse values like stateids, directory cookies, filehandles, |
| 13344 |
etc., even if their native byte order is different from that of other |
| 13345 |
servers cooperating in the replication and migration of the file |
| 13346 |
system. |
| 13347 |
|
| 13348 |
<span class="h4"><a class="selflink" id="section-11.7.1" href="#section-11.7.1">11.7.1</a>. File System Transitions and Simultaneous Access</span> |
| 13349 |
|
| 13350 |
When a single file system may be accessed at multiple locations, |
| 13351 |
either because of an indication of file system identity as reported |
| 13352 |
by the fs_locations or fs_locations_info attributes or because two |
| 13353 |
file system instances have corresponding locations on server |
| 13354 |
addresses that connect to the same server (as indicated by a common |
| 13355 |
so_major_id field in the eir_server_owner field returned by |
| 13356 |
EXCHANGE_ID), the client will, depending on specific circumstances as |
| 13357 |
discussed below, either: |
| 13358 |
|
| 13359 |
o Access multiple instances simultaneously, each of which represents |
| 13360 |
an alternate path to the same data and metadata. |
| 13361 |
|
| 13362 |
o Access one instance (or set of instances) and then transition to |
| 13363 |
an alternative instance (or set of instances) as a result of |
| 13364 |
network issues, server unresponsiveness, or server-directed |
| 13365 |
migration. The transition may involve changes in filehandles, |
| 13366 |
fileids, the change attribute, and/or locking state, depending on |
| 13367 |
the attributes of the source and destination file system |
| 13368 |
instances, as specified in the fs_locations_info attribute. |
| 13369 |
|
| 13370 |
Which of these choices is possible, and how a transition is effected, |
| 13371 |
is governed by equivalence classes of file system instances as |
| 13372 |
reported by the fs_locations_info attribute, and for file system |
| 13373 |
instances in the same location within a multi-homed single-server |
| 13374 |
namespace, as indicated by the value of the so_major_id field of the |
| 13375 |
eir_server_owner field returned by EXCHANGE_ID. |
| 13376 |
|
| 13377 |
|
| 13378 |
|
| 13379 |
|
| 13380 |
<span class="grey">Shepler, et al. Standards Track [Page 239]</span></pre> |
| 13381 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-240" ></span> |
| 13382 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13383 |
|
| 13384 |
|
| 13385 |
<span class="h4"><a class="selflink" id="section-11.7.2" href="#section-11.7.2">11.7.2</a>. Simultaneous Use and Transparent Transitions</span> |
| 13386 |
|
| 13387 |
When two file system instances have the same location within their |
| 13388 |
respective single-server namespaces and those two server network |
| 13389 |
addresses designate the same server (as indicated by the same value |
| 13390 |
of the so_major_id field of the eir_server_owner field returned in |
| 13391 |
response to EXCHANGE_ID), those file system instances can be treated |
| 13392 |
as the same, and either used together simultaneously or serially with |
| 13393 |
no transition activity required on the part of the client. In this |
| 13394 |
case, we refer to the transition as "transparent", and the client in |
| 13395 |
transferring access from one to the other is acting as it would in |
| 13396 |
the event that communication is interrupted, with a new connection |
| 13397 |
and possibly a new session being established to continue access to |
| 13398 |
the same file system. |
| 13399 |
|
| 13400 |
Whether simultaneous use of the two file system instances is valid is |
| 13401 |
controlled by whether the fs_locations_info attribute shows the two |
| 13402 |
instances as having the same simultaneous-use class. See |
| 13403 |
<a href="#section-11.10.1">Section 11.10.1</a> for information about the definition of the various |
| 13404 |
use classes, including the simultaneous-use class. |
| 13405 |
|
| 13406 |
Note that for two such file systems, any information within the |
| 13407 |
fs_locations_info attribute that indicates the need for special |
| 13408 |
transition activity, i.e., the appearance of the two file system |
| 13409 |
instances with different handle, fileid, write-verifier, change, and |
| 13410 |
readdir classes, indicates a serious problem. The client, if it |
| 13411 |
allows transition to the file system instance at all, must not treat |
| 13412 |
this as a transparent transition. The server SHOULD NOT indicate |
| 13413 |
that these instances belong to different handle, fileid, write- |
| 13414 |
verifier, change, and readdir classes, whether or not the two |
| 13415 |
instances are shown belonging to the same simultaneous-use class. |
| 13416 |
|
| 13417 |
Where these conditions do not apply, a non-transparent file system |
| 13418 |
instance transition is required with the details depending on the |
| 13419 |
respective handle, fileid, write-verifier, change, and readdir |
| 13420 |
classes of the two file system instances, and whether the two |
| 13421 |
servers' addresses in question have the same eir_server_scope value |
| 13422 |
as reported by EXCHANGE_ID. |
| 13423 |
|
| 13424 |
<span class="h5"><a class="selflink" id="section-11.7.2.1" href="#section-11.7.2.1">11.7.2.1</a>. Simultaneous Use of File System Instances</span> |
| 13425 |
|
| 13426 |
When the conditions in <a href="#section-11.7.2">Section 11.7.2</a> hold, in either of the |
| 13427 |
following two cases, the client may use the two file system instances |
| 13428 |
simultaneously. |
| 13429 |
|
| 13430 |
o The fs_locations_info attribute does not contain separate per- |
| 13431 |
network-address entries for file system instances at the distinct |
| 13432 |
network addresses. This includes the case in which the |
| 13433 |
|
| 13434 |
|
| 13435 |
|
| 13436 |
<span class="grey">Shepler, et al. Standards Track [Page 240]</span></pre> |
| 13437 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-241" ></span> |
| 13438 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13439 |
|
| 13440 |
|
| 13441 |
fs_locations_info attribute is unavailable. In this case, the |
| 13442 |
fact that the two server addresses connect to the same server (as |
| 13443 |
indicated by the two addresses sharing the same the so_major_id |
| 13444 |
value and subsequently confirmed as described in <a href="#section-2.10.5">Section 2.10.5</a>) |
| 13445 |
justifies simultaneous use, and there is no fs_locations_info |
| 13446 |
attribute information contradicting that. |
| 13447 |
|
| 13448 |
o The fs_locations_info attribute indicates that two file system |
| 13449 |
instances belong to the same simultaneous-use class. |
| 13450 |
|
| 13451 |
In this case, the client may use both file system instances |
| 13452 |
simultaneously, as representations of the same file system, whether |
| 13453 |
that happens because the two network addresses connect to the same |
| 13454 |
physical server or because different servers connect to clustered |
| 13455 |
file systems and export their data in common. When simultaneous use |
| 13456 |
is in effect, any change made to one file system instance must be |
| 13457 |
immediately reflected in the other file system instance(s). Locks |
| 13458 |
are treated as part of a common lease, associated with a common |
| 13459 |
client ID. Depending on the details of the eir_server_owner returned |
| 13460 |
by EXCHANGE_ID, the two server instances may be accessed by different |
| 13461 |
sessions or a single session in common. |
| 13462 |
|
| 13463 |
<span class="h5"><a class="selflink" id="section-11.7.2.2" href="#section-11.7.2.2">11.7.2.2</a>. Transparent File System Transitions</span> |
| 13464 |
|
| 13465 |
When the conditions in <a href="#section-11.7.2.1">Section 11.7.2.1</a> hold and the |
| 13466 |
fs_locations_info attribute explicitly shows the file system |
| 13467 |
instances for these distinct network addresses as belonging to |
| 13468 |
different simultaneous-use classes, the file system instances should |
| 13469 |
not be used by the client simultaneously. Rather, they should be |
| 13470 |
used serially with one being used unless and until communication |
| 13471 |
difficulties, lack of responsiveness, or an explicit migration event |
| 13472 |
causes another file system instance (or set of file system instances |
| 13473 |
sharing a common simultaneous-use class) to be used. |
| 13474 |
|
| 13475 |
When a change of file system instance is to be done, the client will |
| 13476 |
use the same client ID already in effect. If the client already has |
| 13477 |
connections to the new server address, these will be used. |
| 13478 |
Otherwise, new connections to existing sessions or new sessions |
| 13479 |
associated with the existing client ID are established as indicated |
| 13480 |
by the eir_server_owner returned by EXCHANGE_ID. |
| 13481 |
|
| 13482 |
In all such transparent transition cases, the following apply: |
| 13483 |
|
| 13484 |
o If filehandles are persistent, they stay the same. If filehandles |
| 13485 |
are volatile, they either stay the same or expire, but the reason |
| 13486 |
for expiration is not due to the file system transition. |
| 13487 |
|
| 13488 |
o Fileid values do not change across the transition. |
| 13489 |
|
| 13490 |
|
| 13491 |
|
| 13492 |
<span class="grey">Shepler, et al. Standards Track [Page 241]</span></pre> |
| 13493 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-242" ></span> |
| 13494 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13495 |
|
| 13496 |
|
| 13497 |
o The file system will have the same fsid in both the old and new |
| 13498 |
locations. |
| 13499 |
|
| 13500 |
o Change attribute values are consistent across the transition and |
| 13501 |
do not have to be refetched. When change attributes indicate that |
| 13502 |
a cached object is still valid, it can remain cached. |
| 13503 |
|
| 13504 |
o Client and state identifiers retain their validity across the |
| 13505 |
transition, except where their staleness is recognized and |
| 13506 |
reported by the new server. Except where such staleness requires |
| 13507 |
it, no lock reclamation is needed. Any such staleness is an |
| 13508 |
indication that the server should be considered to have restarted |
| 13509 |
and is reported as discussed in <a href="#section-8.4.2">Section 8.4.2</a>. |
| 13510 |
|
| 13511 |
o Write verifiers are presumed to retain their validity and can be |
| 13512 |
used to compare with verifiers returned by COMMIT on the new |
| 13513 |
server. If COMMIT on the new server returns an identical |
| 13514 |
verifier, then it is expected that the new server has all of the |
| 13515 |
data that was written unstably to the original server and has |
| 13516 |
committed that data to stable storage as requested. |
| 13517 |
|
| 13518 |
o Readdir cookies are presumed to retain their validity and can be |
| 13519 |
presented to subsequent READDIR requests together with the readdir |
| 13520 |
verifier with which they are associated. When the verifier is |
| 13521 |
accepted as valid, the cookie will continue the READDIR operation |
| 13522 |
so that the entire directory can be obtained by the client. |
| 13523 |
|
| 13524 |
<span class="h4"><a class="selflink" id="section-11.7.3" href="#section-11.7.3">11.7.3</a>. Filehandles and File System Transitions</span> |
| 13525 |
|
| 13526 |
There are a number of ways in which filehandles can be handled across |
| 13527 |
a file system transition. These can be divided into two broad |
| 13528 |
classes depending upon whether the two file systems across which the |
| 13529 |
transition happens share sufficient state to effect some sort of |
| 13530 |
continuity of file system handling. |
| 13531 |
|
| 13532 |
When there is no such cooperation in filehandle assignment, the two |
| 13533 |
file systems are reported as being in different handle classes. In |
| 13534 |
this case, all filehandles are assumed to expire as part of the file |
| 13535 |
system transition. Note that this behavior does not depend on the |
| 13536 |
fh_expire_type attribute and supersedes the specification of the |
| 13537 |
FH4_VOL_MIGRATION bit, which only affects behavior when |
| 13538 |
fs_locations_info is not available. |
| 13539 |
|
| 13540 |
When there is cooperation in filehandle assignment, the two file |
| 13541 |
systems are reported as being in the same handle classes. In this |
| 13542 |
case, persistent filehandles remain valid after the file system |
| 13543 |
|
| 13544 |
|
| 13545 |
|
| 13546 |
|
| 13547 |
|
| 13548 |
<span class="grey">Shepler, et al. Standards Track [Page 242]</span></pre> |
| 13549 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-243" ></span> |
| 13550 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13551 |
|
| 13552 |
|
| 13553 |
transition, while volatile filehandles (excluding those that are only |
| 13554 |
volatile due to the FH4_VOL_MIGRATION bit) are subject to expiration |
| 13555 |
on the target server. |
| 13556 |
|
| 13557 |
<span class="h4"><a class="selflink" id="section-11.7.4" href="#section-11.7.4">11.7.4</a>. Fileids and File System Transitions</span> |
| 13558 |
|
| 13559 |
In NFSv4.0, the issue of continuity of fileids in the event of a file |
| 13560 |
system transition was not addressed. The general expectation had |
| 13561 |
been that in situations in which the two file system instances are |
| 13562 |
created by a single vendor using some sort of file system image copy, |
| 13563 |
fileids will be consistent across the transition, while in the |
| 13564 |
analogous multi-vendor transitions they will not. This poses |
| 13565 |
difficulties, especially for the client without special knowledge of |
| 13566 |
the transition mechanisms adopted by the server. Note that although |
| 13567 |
fileid is not a REQUIRED attribute, many servers support fileids and |
| 13568 |
many clients provide APIs that depend on fileids. |
| 13569 |
|
| 13570 |
It is important to note that while clients themselves may have no |
| 13571 |
trouble with a fileid changing as a result of a file system |
| 13572 |
transition event, applications do typically have access to the fileid |
| 13573 |
(e.g., via stat). The result is that an application may work |
| 13574 |
perfectly well if there is no file system instance transition or if |
| 13575 |
any such transition is among instances created by a single vendor, |
| 13576 |
yet be unable to deal with the situation in which a multi-vendor |
| 13577 |
transition occurs at the wrong time. |
| 13578 |
|
| 13579 |
Providing the same fileids in a multi-vendor (multiple server |
| 13580 |
vendors) environment has generally been held to be quite difficult. |
| 13581 |
While there is work to be done, it needs to be pointed out that this |
| 13582 |
difficulty is partly self-imposed. Servers have typically identified |
| 13583 |
fileid with inode number, i.e. with a quantity used to find the file |
| 13584 |
in question. This identification poses special difficulties for |
| 13585 |
migration of a file system between vendors where assigning the same |
| 13586 |
index to a given file may not be possible. Note here that a fileid |
| 13587 |
is not required to be useful to find the file in question, only that |
| 13588 |
it is unique within the given file system. Servers prepared to |
| 13589 |
accept a fileid as a single piece of metadata and store it apart from |
| 13590 |
the value used to index the file information can relatively easily |
| 13591 |
maintain a fileid value across a migration event, allowing a truly |
| 13592 |
transparent migration event. |
| 13593 |
|
| 13594 |
In any case, where servers can provide continuity of fileids, they |
| 13595 |
should, and the client should be able to find out that such |
| 13596 |
continuity is available and take appropriate action. Information |
| 13597 |
about the continuity (or lack thereof) of fileids across a file |
| 13598 |
system transition is represented by specifying whether the file |
| 13599 |
systems in question are of the same fileid class. |
| 13600 |
|
| 13601 |
|
| 13602 |
|
| 13603 |
|
| 13604 |
<span class="grey">Shepler, et al. Standards Track [Page 243]</span></pre> |
| 13605 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-244" ></span> |
| 13606 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13607 |
|
| 13608 |
|
| 13609 |
Note that when consistent fileids do not exist across a transition |
| 13610 |
(either because there is no continuity of fileids or because fileid |
| 13611 |
is not a supported attribute on one of instances involved), and there |
| 13612 |
are no reliable filehandles across a transition event (either because |
| 13613 |
there is no filehandle continuity or because the filehandles are |
| 13614 |
volatile), the client is in a position where it cannot verify that |
| 13615 |
files it was accessing before the transition are the same objects. |
| 13616 |
It is forced to assume that no object has been renamed, and, unless |
| 13617 |
there are guarantees that provide this (e.g., the file system is |
| 13618 |
read-only), problems for applications may occur. Therefore, use of |
| 13619 |
such configurations should be limited to situations where the |
| 13620 |
problems that this may cause can be tolerated. |
| 13621 |
|
| 13622 |
<span class="h4"><a class="selflink" id="section-11.7.5" href="#section-11.7.5">11.7.5</a>. Fsids and File System Transitions</span> |
| 13623 |
|
| 13624 |
Since fsids are generally only unique within a per-server basis, it |
| 13625 |
is likely that they will change during a file system transition. One |
| 13626 |
exception is the case of transparent transitions, but in that case we |
| 13627 |
have multiple network addresses that are defined as the same server |
| 13628 |
(as specified by a common value of the so_major_id field of |
| 13629 |
eir_server_owner). Clients should not make the fsids received from |
| 13630 |
the server visible to applications since they may not be globally |
| 13631 |
unique, and because they may change during a file system transition |
| 13632 |
event. Applications are best served if they are isolated from such |
| 13633 |
transitions to the extent possible. |
| 13634 |
|
| 13635 |
Although normally a single source file system will transition to a |
| 13636 |
single target file system, there is a provision for splitting a |
| 13637 |
single source file system into multiple target file systems, by |
| 13638 |
specifying the FSLI4F_MULTI_FS flag. |
| 13639 |
|
| 13640 |
<span class="h5"><a class="selflink" id="section-11.7.5.1" href="#section-11.7.5.1">11.7.5.1</a>. File System Splitting</span> |
| 13641 |
|
| 13642 |
When a file system transition is made and the fs_locations_info |
| 13643 |
indicates that the file system in question may be split into multiple |
| 13644 |
file systems (via the FSLI4F_MULTI_FS flag), the client SHOULD do |
| 13645 |
GETATTRs to determine the fsid attribute on all known objects within |
| 13646 |
the file system undergoing transition to determine the new file |
| 13647 |
system boundaries. |
| 13648 |
|
| 13649 |
Clients may maintain the fsids passed to existing applications by |
| 13650 |
mapping all of the fsids for the descendant file systems to the |
| 13651 |
common fsid used for the original file system. |
| 13652 |
|
| 13653 |
Splitting a file system may be done on a transition between file |
| 13654 |
systems of the same fileid class, since the fact that fileids are |
| 13655 |
unique within the source file system ensure they will be unique in |
| 13656 |
each of the target file systems. |
| 13657 |
|
| 13658 |
|
| 13659 |
|
| 13660 |
<span class="grey">Shepler, et al. Standards Track [Page 244]</span></pre> |
| 13661 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-245" ></span> |
| 13662 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13663 |
|
| 13664 |
|
| 13665 |
<span class="h4"><a class="selflink" id="section-11.7.6" href="#section-11.7.6">11.7.6</a>. The Change Attribute and File System Transitions</span> |
| 13666 |
|
| 13667 |
Since the change attribute is defined as a server-specific one, |
| 13668 |
change attributes fetched from one server are normally presumed to be |
| 13669 |
invalid on another server. Such a presumption is troublesome since |
| 13670 |
it would invalidate all cached change attributes, requiring |
| 13671 |
refetching. Even more disruptive, the absence of any assured |
| 13672 |
continuity for the change attribute means that even if the same value |
| 13673 |
is retrieved on refetch, no conclusions can be drawn as to whether |
| 13674 |
the object in question has changed. The identical change attribute |
| 13675 |
could be merely an artifact of a modified file with a different |
| 13676 |
change attribute construction algorithm, with that new algorithm just |
| 13677 |
happening to result in an identical change value. |
| 13678 |
|
| 13679 |
When the two file systems have consistent change attribute formats, |
| 13680 |
and this fact is communicated to the client by reporting in the same |
| 13681 |
change class, the client may assume a continuity of change attribute |
| 13682 |
construction and handle this situation just as it would be handled |
| 13683 |
without any file system transition. |
| 13684 |
|
| 13685 |
<span class="h4"><a class="selflink" id="section-11.7.7" href="#section-11.7.7">11.7.7</a>. Lock State and File System Transitions</span> |
| 13686 |
|
| 13687 |
In a file system transition, the client needs to handle cases in |
| 13688 |
which the two servers have cooperated in state management and in |
| 13689 |
which they have not. Cooperation by two servers in state management |
| 13690 |
requires coordination of client IDs. Before the client attempts to |
| 13691 |
use a client ID associated with one server in a request to the server |
| 13692 |
of the other file system, it must eliminate the possibility that two |
| 13693 |
non-cooperating servers have assigned the same client ID by accident. |
| 13694 |
The client needs to compare the eir_server_scope values returned by |
| 13695 |
each server. If the scope values do not match, then the servers have |
| 13696 |
not cooperated in state management. If the scope values match, then |
| 13697 |
this indicates the servers have cooperated in assigning client IDs to |
| 13698 |
the point that they will reject client IDs that refer to state they |
| 13699 |
do not know about. See <a href="#section-2.10.4">Section 2.10.4</a> for more information about the |
| 13700 |
use of server scope. |
| 13701 |
|
| 13702 |
In the case of migration, the servers involved in the migration of a |
| 13703 |
file system SHOULD transfer all server state from the original to the |
| 13704 |
new server. When this is done, it must be done in a way that is |
| 13705 |
transparent to the client. With replication, such a degree of common |
| 13706 |
state is typically not the case. Clients, however, should use the |
| 13707 |
information provided by the eir_server_scope returned by EXCHANGE_ID |
| 13708 |
(as modified by the validation procedures described in |
| 13709 |
<a href="#section-2.10.4">Section 2.10.4</a>) to determine whether such sharing may be in effect, |
| 13710 |
rather than making assumptions based on the reason for the |
| 13711 |
transition. |
| 13712 |
|
| 13713 |
|
| 13714 |
|
| 13715 |
|
| 13716 |
<span class="grey">Shepler, et al. Standards Track [Page 245]</span></pre> |
| 13717 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-246" ></span> |
| 13718 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13719 |
|
| 13720 |
|
| 13721 |
This state transfer will reduce disruption to the client when a file |
| 13722 |
system transition occurs. If the servers are successful in |
| 13723 |
transferring all state, the client can attempt to establish sessions |
| 13724 |
associated with the client ID used for the source file system |
| 13725 |
instance. If the server accepts that as a valid client ID, then the |
| 13726 |
client may use the existing stateids associated with that client ID |
| 13727 |
for the old file system instance in connection with that same client |
| 13728 |
ID in connection with the transitioned file system instance. If the |
| 13729 |
client in question already had a client ID on the target system, it |
| 13730 |
may interrogate the stateid values from the source system under that |
| 13731 |
new client ID, with the assurance that if they are accepted as valid, |
| 13732 |
then they represent validly transferred lock state for the source |
| 13733 |
file system, which has been transferred to the target server. |
| 13734 |
|
| 13735 |
When the two servers belong to the same server scope, it does not |
| 13736 |
mean that when dealing with the transition, the client will not have |
| 13737 |
to reclaim state. However, it does mean that the client may proceed |
| 13738 |
using its current client ID when establishing communication with the |
| 13739 |
new server, and the new server will either recognize the client ID as |
| 13740 |
valid or reject it, in which case locks must be reclaimed by the |
| 13741 |
client. |
| 13742 |
|
| 13743 |
File systems cooperating in state management may actually share state |
| 13744 |
or simply divide the identifier space so as to recognize (and reject |
| 13745 |
as stale) each other's stateids and client IDs. Servers that do |
| 13746 |
share state may not do so under all conditions or at all times. If |
| 13747 |
the server cannot be sure when accepting a client ID that it reflects |
| 13748 |
the locks the client was given, the server must treat all associated |
| 13749 |
state as stale and report it as such to the client. |
| 13750 |
|
| 13751 |
When the two file system instances are on servers that do not share a |
| 13752 |
server scope value, the client must establish a new client ID on the |
| 13753 |
destination, if it does not have one already, and reclaim locks if |
| 13754 |
allowed by the server. In this case, old stateids and client IDs |
| 13755 |
should not be presented to the new server since there is no assurance |
| 13756 |
that they will not conflict with IDs valid on that server. Note that |
| 13757 |
in this case, lock reclaim may be attempted even when the servers |
| 13758 |
involved in the transfer have different server scope values (see |
| 13759 |
<a href="#section-8.4.2.1">Section 8.4.2.1</a> for the contrary case of reclaim after server |
| 13760 |
reboot). Servers with different server scope values may cooperate to |
| 13761 |
allow reclaim for locks associated with the transfer of a file system |
| 13762 |
even if they do not cooperate sufficiently to share a server scope. |
| 13763 |
|
| 13764 |
In either case, when actual locks are not known to be maintained, the |
| 13765 |
destination server may establish a grace period specific to the given |
| 13766 |
file system, with non-reclaim locks being rejected for that file |
| 13767 |
system, even though normal locks are being granted for other file |
| 13768 |
|
| 13769 |
|
| 13770 |
|
| 13771 |
|
| 13772 |
<span class="grey">Shepler, et al. Standards Track [Page 246]</span></pre> |
| 13773 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-247" ></span> |
| 13774 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13775 |
|
| 13776 |
|
| 13777 |
systems. Clients should not infer the absence of a grace period for |
| 13778 |
file systems being transitioned to a server from responses to |
| 13779 |
requests for other file systems. |
| 13780 |
|
| 13781 |
In the case of lock reclamation for a given file system after a file |
| 13782 |
system transition, edge conditions can arise similar to those for |
| 13783 |
reclaim after server restart (although in the case of the planned |
| 13784 |
state transfer associated with migration, these can be avoided by |
| 13785 |
securely recording lock state as part of state migration). Unless |
| 13786 |
the destination server can guarantee that locks will not be |
| 13787 |
incorrectly granted, the destination server should not allow lock |
| 13788 |
reclaims and should avoid establishing a grace period. |
| 13789 |
|
| 13790 |
Once all locks have been reclaimed, or there were no locks to |
| 13791 |
reclaim, the client indicates that there are no more reclaims to be |
| 13792 |
done for the file system in question by sending a RECLAIM_COMPLETE |
| 13793 |
operation with the rca_one_fs parameter set to true. Once this has |
| 13794 |
been done, non-reclaim locking operations may be done, and any |
| 13795 |
subsequent request to do reclaims will be rejected with the error |
| 13796 |
NFS4ERR_NO_GRACE. |
| 13797 |
|
| 13798 |
Information about client identity may be propagated between servers |
| 13799 |
in the form of client_owner4 and associated verifiers, under the |
| 13800 |
assumption that the client presents the same values to all the |
| 13801 |
servers with which it deals. |
| 13802 |
|
| 13803 |
Servers are encouraged to provide facilities to allow locks to be |
| 13804 |
reclaimed on the new server after a file system transition. Often, |
| 13805 |
however, in cases in which the two servers do not share a server |
| 13806 |
scope value, such facilities may not be available and the client |
| 13807 |
should be prepared to re-obtain locks, even though it is possible |
| 13808 |
that the client may have its LOCK or OPEN request denied due to a |
| 13809 |
conflicting lock. |
| 13810 |
|
| 13811 |
The consequences of having no facilities available to reclaim locks |
| 13812 |
on the new server will depend on the type of environment. In some |
| 13813 |
environments, such as the transition between read-only file systems, |
| 13814 |
such denial of locks should not pose large difficulties in practice. |
| 13815 |
When an attempt to re-establish a lock on a new server is denied, the |
| 13816 |
client should treat the situation as if its original lock had been |
| 13817 |
revoked. Note that when the lock is granted, the client cannot |
| 13818 |
assume that no conflicting lock could have been granted in the |
| 13819 |
interim. Where change attribute continuity is present, the client |
| 13820 |
may check the change attribute to check for unwanted file |
| 13821 |
modifications. Where even this is not available, and the file system |
| 13822 |
is not read-only, a client may reasonably treat all pending locks as |
| 13823 |
having been revoked. |
| 13824 |
|
| 13825 |
|
| 13826 |
|
| 13827 |
|
| 13828 |
<span class="grey">Shepler, et al. Standards Track [Page 247]</span></pre> |
| 13829 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-248" ></span> |
| 13830 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13831 |
|
| 13832 |
|
| 13833 |
<span class="h5"><a class="selflink" id="section-11.7.7.1" href="#section-11.7.7.1">11.7.7.1</a>. Leases and File System Transitions</span> |
| 13834 |
|
| 13835 |
In the case of lease renewal, the client may not be submitting |
| 13836 |
requests for a file system that has been transferred to another |
| 13837 |
server. This can occur because of the lease renewal mechanism. The |
| 13838 |
client renews the lease associated with all file systems when |
| 13839 |
submitting a request on an associated session, regardless of the |
| 13840 |
specific file system being referenced. |
| 13841 |
|
| 13842 |
In order for the client to schedule renewal of its lease where there |
| 13843 |
is locking state that may have been relocated to the new server, the |
| 13844 |
client must find out about lease relocation before that lease expire. |
| 13845 |
To accomplish this, the SEQUENCE operation will return the status bit |
| 13846 |
SEQ4_STATUS_LEASE_MOVED if responsibility for any of the renewed |
| 13847 |
locking state has been transferred to a new server. This will |
| 13848 |
continue until the client receives an NFS4ERR_MOVED error for each of |
| 13849 |
the file systems for which there has been locking state relocation. |
| 13850 |
|
| 13851 |
When a client receives an SEQ4_STATUS_LEASE_MOVED indication from a |
| 13852 |
server, for each file system of the server for which the client has |
| 13853 |
locking state, the client should perform an operation. For |
| 13854 |
simplicity, the client may choose to reference all file systems, but |
| 13855 |
what is important is that it must reference all file systems for |
| 13856 |
which there was locking state where that state has moved. Once the |
| 13857 |
client receives an NFS4ERR_MOVED error for each such file system, the |
| 13858 |
server will clear the SEQ4_STATUS_LEASE_MOVED indication. The client |
| 13859 |
can terminate the process of checking file systems once this |
| 13860 |
indication is cleared (but only if the client has received a reply |
| 13861 |
for all outstanding SEQUENCE requests on all sessions it has with the |
| 13862 |
server), since there are no others for which locking state has moved. |
| 13863 |
|
| 13864 |
A client may use GETATTR of the fs_status (or fs_locations_info) |
| 13865 |
attribute on all of the file systems to get absence indications in a |
| 13866 |
single (or a few) request(s), since absent file systems will not |
| 13867 |
cause an error in this context. However, it still must do an |
| 13868 |
operation that receives NFS4ERR_MOVED on each file system, in order |
| 13869 |
to clear the SEQ4_STATUS_LEASE_MOVED indication. |
| 13870 |
|
| 13871 |
Once the set of file systems with transferred locking state has been |
| 13872 |
determined, the client can follow the normal process to obtain the |
| 13873 |
new server information (through the fs_locations and |
| 13874 |
fs_locations_info attributes) and perform renewal of that lease on |
| 13875 |
the new server, unless information in the fs_locations_info attribute |
| 13876 |
shows that no state could have been transferred. If the server has |
| 13877 |
not had state transferred to it transparently, the client will |
| 13878 |
receive NFS4ERR_STALE_CLIENTID from the new server, as described |
| 13879 |
above, and the client can then reclaim locks as is done in the event |
| 13880 |
of server failure. |
| 13881 |
|
| 13882 |
|
| 13883 |
|
| 13884 |
<span class="grey">Shepler, et al. Standards Track [Page 248]</span></pre> |
| 13885 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-249" ></span> |
| 13886 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13887 |
|
| 13888 |
|
| 13889 |
<span class="h5"><a class="selflink" id="section-11.7.7.2" href="#section-11.7.7.2">11.7.7.2</a>. Transitions and the Lease_time Attribute</span> |
| 13890 |
|
| 13891 |
In order that the client may appropriately manage its lease in the |
| 13892 |
case of a file system transition, the destination server must |
| 13893 |
establish proper values for the lease_time attribute. |
| 13894 |
|
| 13895 |
When state is transferred transparently, that state should include |
| 13896 |
the correct value of the lease_time attribute. The lease_time |
| 13897 |
attribute on the destination server must never be less than that on |
| 13898 |
the source, since this would result in premature expiration of a |
| 13899 |
lease granted by the source server. Upon transitions in which state |
| 13900 |
is transferred transparently, the client is under no obligation to |
| 13901 |
refetch the lease_time attribute and may continue to use the value |
| 13902 |
previously fetched (on the source server). |
| 13903 |
|
| 13904 |
If state has not been transferred transparently, either because the |
| 13905 |
associated servers are shown as having different eir_server_scope |
| 13906 |
strings or because the client ID is rejected when presented to the |
| 13907 |
new server, the client should fetch the value of lease_time on the |
| 13908 |
new (i.e., destination) server, and use it for subsequent locking |
| 13909 |
requests. However, the server must respect a grace period of at |
| 13910 |
least as long as the lease_time on the source server, in order to |
| 13911 |
ensure that clients have ample time to reclaim their lock before |
| 13912 |
potentially conflicting non-reclaimed locks are granted. |
| 13913 |
|
| 13914 |
<span class="h4"><a class="selflink" id="section-11.7.8" href="#section-11.7.8">11.7.8</a>. Write Verifiers and File System Transitions</span> |
| 13915 |
|
| 13916 |
In a file system transition, the two file systems may be clustered in |
| 13917 |
the handling of unstably written data. When this is the case, and |
| 13918 |
the two file systems belong to the same write-verifier class, write |
| 13919 |
verifiers returned from one system may be compared to those returned |
| 13920 |
by the other and superfluous writes avoided. |
| 13921 |
|
| 13922 |
When two file systems belong to different write-verifier classes, any |
| 13923 |
verifier generated by one must not be compared to one provided by the |
| 13924 |
other. Instead, it should be treated as not equal even when the |
| 13925 |
values are identical. |
| 13926 |
|
| 13927 |
<span class="h4"><a class="selflink" id="section-11.7.9" href="#section-11.7.9">11.7.9</a>. Readdir Cookies and Verifiers and File System Transitions</span> |
| 13928 |
|
| 13929 |
In a file system transition, the two file systems may be consistent |
| 13930 |
in their handling of READDIR cookies and verifiers. When this is the |
| 13931 |
case, and the two file systems belong to the same readdir class, |
| 13932 |
READDIR cookies and verifiers from one system may be recognized by |
| 13933 |
the other and READDIR operations started on one server may be validly |
| 13934 |
continued on the other, simply by presenting the cookie and verifier |
| 13935 |
returned by a READDIR operation done on the first file system to the |
| 13936 |
second. |
| 13937 |
|
| 13938 |
|
| 13939 |
|
| 13940 |
<span class="grey">Shepler, et al. Standards Track [Page 249]</span></pre> |
| 13941 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-250" ></span> |
| 13942 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13943 |
|
| 13944 |
|
| 13945 |
When two file systems belong to different readdir classes, any |
| 13946 |
READDIR cookie and verifier generated by one is not valid on the |
| 13947 |
second, and must not be presented to that server by the client. The |
| 13948 |
client should act as if the verifier was rejected. |
| 13949 |
|
| 13950 |
<span class="h4"><a class="selflink" id="section-11.7.10" href="#section-11.7.10">11.7.10</a>. File System Data and File System Transitions</span> |
| 13951 |
|
| 13952 |
When multiple replicas exist and are used simultaneously or in |
| 13953 |
succession by a client, applications using them will normally expect |
| 13954 |
that they contain either the same data or data that is consistent |
| 13955 |
with the normal sorts of changes that are made by other clients |
| 13956 |
updating the data of the file system (with metadata being the same to |
| 13957 |
the degree indicated by the fs_locations_info attribute). However, |
| 13958 |
when multiple file systems are presented as replicas of one another, |
| 13959 |
the precise relationship between the data of one and the data of |
| 13960 |
another is not, as a general matter, specified by the NFSv4.1 |
| 13961 |
protocol. It is quite possible to present as replicas file systems |
| 13962 |
where the data of those file systems is sufficiently different that |
| 13963 |
some applications have problems dealing with the transition between |
| 13964 |
replicas. The namespace will typically be constructed so that |
| 13965 |
applications can choose an appropriate level of support, so that in |
| 13966 |
one position in the namespace a varied set of replicas will be |
| 13967 |
listed, while in another only those that are up-to-date may be |
| 13968 |
considered replicas. The protocol does define four special cases of |
| 13969 |
the relationship among replicas to be specified by the server and |
| 13970 |
relied upon by clients: |
| 13971 |
|
| 13972 |
o When multiple server addresses correspond to the same actual |
| 13973 |
server, as indicated by a common so_major_id field within the |
| 13974 |
eir_server_owner field returned by EXCHANGE_ID, the client may |
| 13975 |
depend on the fact that changes to data, metadata, or locks made |
| 13976 |
on one file system are immediately reflected on others. |
| 13977 |
|
| 13978 |
o When multiple replicas exist and are used simultaneously by a |
| 13979 |
client (see the FSLIB4_CLSIMUL definition within |
| 13980 |
fs_locations_info), they must designate the same data. Where file |
| 13981 |
systems are writable, a change made on one instance must be |
| 13982 |
visible on all instances, immediately upon the earlier of the |
| 13983 |
return of the modifying requester or the visibility of that change |
| 13984 |
on any of the associated replicas. This allows a client to use |
| 13985 |
these replicas simultaneously without any special adaptation to |
| 13986 |
the fact that there are multiple replicas. In this case, locks |
| 13987 |
(whether share reservations or byte-range locks) and delegations |
| 13988 |
obtained on one replica are immediately reflected on all replicas, |
| 13989 |
even though these locks will be managed under a set of client IDs. |
| 13990 |
|
| 13991 |
|
| 13992 |
|
| 13993 |
|
| 13994 |
|
| 13995 |
|
| 13996 |
<span class="grey">Shepler, et al. Standards Track [Page 250]</span></pre> |
| 13997 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-251" ></span> |
| 13998 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 13999 |
|
| 14000 |
|
| 14001 |
o When one replica is designated as the successor instance to |
| 14002 |
another existing instance after return NFS4ERR_MOVED (i.e., the |
| 14003 |
case of migration), the client may depend on the fact that all |
| 14004 |
changes written to stable storage on the original instance are |
| 14005 |
written to stable storage of the successor (uncommitted writes are |
| 14006 |
dealt with in <a href="#section-11.7.8">Section 11.7.8</a>). |
| 14007 |
|
| 14008 |
o Where a file system is not writable but represents a read-only |
| 14009 |
copy (possibly periodically updated) of a writable file system, |
| 14010 |
clients have similar requirements with regard to the propagation |
| 14011 |
of updates. They may need a guarantee that any change visible on |
| 14012 |
the original file system instance must be immediately visible on |
| 14013 |
any replica before the client transitions access to that replica, |
| 14014 |
in order to avoid any possibility that a client, in effecting a |
| 14015 |
transition to a replica, will see any reversion in file system |
| 14016 |
state. The specific means of this guarantee varies based on the |
| 14017 |
value of the fss_type field that is reported as part of the |
| 14018 |
fs_status attribute (see <a href="#section-11.11">Section 11.11</a>). Since these file systems |
| 14019 |
are presumed to be unsuitable for simultaneous use, there is no |
| 14020 |
specification of how locking is handled; in general, locks |
| 14021 |
obtained on one file system will be separate from those on others. |
| 14022 |
Since these are going to be read-only file systems, this is not |
| 14023 |
expected to pose an issue for clients or applications. |
| 14024 |
|
| 14025 |
<span class="h3"><a class="selflink" id="section-11.8" href="#section-11.8">11.8</a>. Effecting File System Referrals</span> |
| 14026 |
|
| 14027 |
Referrals are effected when an absent file system is encountered and |
| 14028 |
one or more alternate locations are made available by the |
| 14029 |
fs_locations or fs_locations_info attributes. The client will |
| 14030 |
typically get an NFS4ERR_MOVED error, fetch the appropriate location |
| 14031 |
information, and proceed to access the file system on a different |
| 14032 |
server, even though it retains its logical position within the |
| 14033 |
original namespace. Referrals differ from migration events in that |
| 14034 |
they happen only when the client has not previously referenced the |
| 14035 |
file system in question (so there is nothing to transition). |
| 14036 |
Referrals can only come into effect when an absent file system is |
| 14037 |
encountered at its root. |
| 14038 |
|
| 14039 |
The examples given in the sections below are somewhat artificial in |
| 14040 |
that an actual client will not typically do a multi-component look |
| 14041 |
up, but will have cached information regarding the upper levels of |
| 14042 |
the name hierarchy. However, these example are chosen to make the |
| 14043 |
required behavior clear and easy to put within the scope of a small |
| 14044 |
number of requests, without getting unduly into details of how |
| 14045 |
specific clients might choose to cache things. |
| 14046 |
|
| 14047 |
|
| 14048 |
|
| 14049 |
|
| 14050 |
|
| 14051 |
|
| 14052 |
<span class="grey">Shepler, et al. Standards Track [Page 251]</span></pre> |
| 14053 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-252" ></span> |
| 14054 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14055 |
|
| 14056 |
|
| 14057 |
<span class="h4"><a class="selflink" id="section-11.8.1" href="#section-11.8.1">11.8.1</a>. Referral Example (LOOKUP)</span> |
| 14058 |
|
| 14059 |
Let us suppose that the following COMPOUND is sent in an environment |
| 14060 |
in which /this/is/the/path is absent from the target server. This |
| 14061 |
may be for a number of reasons. It may be that the file system has |
| 14062 |
moved, or it may be that the target server is functioning mainly, or |
| 14063 |
solely, to refer clients to the servers on which various file systems |
| 14064 |
are located. |
| 14065 |
|
| 14066 |
o PUTROOTFH |
| 14067 |
|
| 14068 |
o LOOKUP "this" |
| 14069 |
|
| 14070 |
o LOOKUP "is" |
| 14071 |
|
| 14072 |
o LOOKUP "the" |
| 14073 |
|
| 14074 |
o LOOKUP "path" |
| 14075 |
|
| 14076 |
o GETFH |
| 14077 |
|
| 14078 |
o GETATTR (fsid, fileid, size, time_modify) |
| 14079 |
|
| 14080 |
Under the given circumstances, the following will be the result. |
| 14081 |
|
| 14082 |
o PUTROOTFH --> NFS_OK. The current fh is now the root of the |
| 14083 |
pseudo-fs. |
| 14084 |
|
| 14085 |
o LOOKUP "this" --> NFS_OK. The current fh is for /this and is |
| 14086 |
within the pseudo-fs. |
| 14087 |
|
| 14088 |
o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is |
| 14089 |
within the pseudo-fs. |
| 14090 |
|
| 14091 |
o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and |
| 14092 |
is within the pseudo-fs. |
| 14093 |
|
| 14094 |
o LOOKUP "path" --> NFS_OK. The current fh is for /this/is/the/path |
| 14095 |
and is within a new, absent file system, but ... the client will |
| 14096 |
never see the value of that fh. |
| 14097 |
|
| 14098 |
o GETFH --> NFS4ERR_MOVED. Fails because current fh is in an absent |
| 14099 |
file system at the start of the operation, and the specification |
| 14100 |
makes no exception for GETFH. |
| 14101 |
|
| 14102 |
o GETATTR (fsid, fileid, size, time_modify). Not executed because |
| 14103 |
the failure of the GETFH stops processing of the COMPOUND. |
| 14104 |
|
| 14105 |
|
| 14106 |
|
| 14107 |
|
| 14108 |
<span class="grey">Shepler, et al. Standards Track [Page 252]</span></pre> |
| 14109 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-253" ></span> |
| 14110 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14111 |
|
| 14112 |
|
| 14113 |
Given the failure of the GETFH, the client has the job of determining |
| 14114 |
the root of the absent file system and where to find that file |
| 14115 |
system, i.e., the server and path relative to that server's root fh. |
| 14116 |
Note that in this example, the client did not obtain filehandles and |
| 14117 |
attribute information (e.g., fsid) for the intermediate directories, |
| 14118 |
so that it would not be sure where the absent file system starts. It |
| 14119 |
could be the case, for example, that /this/is/the is the root of the |
| 14120 |
moved file system and that the reason that the look up of "path" |
| 14121 |
succeeded is that the file system was not absent on that operation |
| 14122 |
but was moved between the last LOOKUP and the GETFH (since COMPOUND |
| 14123 |
is not atomic). Even if we had the fsids for all of the intermediate |
| 14124 |
directories, we could have no way of knowing that /this/is/the/path |
| 14125 |
was the root of a new file system, since we don't yet have its fsid. |
| 14126 |
|
| 14127 |
In order to get the necessary information, let us re-send the chain |
| 14128 |
of LOOKUPs with GETFHs and GETATTRs to at least get the fsids so we |
| 14129 |
can be sure where the appropriate file system boundaries are. The |
| 14130 |
client could choose to get fs_locations_info at the same time but in |
| 14131 |
most cases the client will have a good guess as to where file system |
| 14132 |
boundaries are (because of where NFS4ERR_MOVED was, and was not, |
| 14133 |
received) making fetching of fs_locations_info unnecessary. |
| 14134 |
|
| 14135 |
OP01: PUTROOTFH --> NFS_OK |
| 14136 |
|
| 14137 |
- Current fh is root of pseudo-fs. |
| 14138 |
|
| 14139 |
OP02: GETATTR(fsid) --> NFS_OK |
| 14140 |
|
| 14141 |
- Just for completeness. Normally, clients will know the fsid of |
| 14142 |
the pseudo-fs as soon as they establish communication with a |
| 14143 |
server. |
| 14144 |
|
| 14145 |
OP03: LOOKUP "this" --> NFS_OK |
| 14146 |
|
| 14147 |
OP04: GETATTR(fsid) --> NFS_OK |
| 14148 |
|
| 14149 |
- Get current fsid to see where file system boundaries are. The |
| 14150 |
fsid will be that for the pseudo-fs in this example, so no |
| 14151 |
boundary. |
| 14152 |
|
| 14153 |
OP05: GETFH --> NFS_OK |
| 14154 |
|
| 14155 |
- Current fh is for /this and is within pseudo-fs. |
| 14156 |
|
| 14157 |
OP06: LOOKUP "is" --> NFS_OK |
| 14158 |
|
| 14159 |
- Current fh is for /this/is and is within pseudo-fs. |
| 14160 |
|
| 14161 |
|
| 14162 |
|
| 14163 |
|
| 14164 |
<span class="grey">Shepler, et al. Standards Track [Page 253]</span></pre> |
| 14165 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-254" ></span> |
| 14166 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14167 |
|
| 14168 |
|
| 14169 |
OP07: GETATTR(fsid) --> NFS_OK |
| 14170 |
|
| 14171 |
- Get current fsid to see where file system boundaries are. The |
| 14172 |
fsid will be that for the pseudo-fs in this example, so no |
| 14173 |
boundary. |
| 14174 |
|
| 14175 |
OP08: GETFH --> NFS_OK |
| 14176 |
|
| 14177 |
- Current fh is for /this/is and is within pseudo-fs. |
| 14178 |
|
| 14179 |
OP09: LOOKUP "the" --> NFS_OK |
| 14180 |
|
| 14181 |
- Current fh is for /this/is/the and is within pseudo-fs. |
| 14182 |
|
| 14183 |
OP10: GETATTR(fsid) --> NFS_OK |
| 14184 |
|
| 14185 |
- Get current fsid to see where file system boundaries are. The |
| 14186 |
fsid will be that for the pseudo-fs in this example, so no |
| 14187 |
boundary. |
| 14188 |
|
| 14189 |
OP11: GETFH --> NFS_OK |
| 14190 |
|
| 14191 |
- Current fh is for /this/is/the and is within pseudo-fs. |
| 14192 |
|
| 14193 |
OP12: LOOKUP "path" --> NFS_OK |
| 14194 |
|
| 14195 |
- Current fh is for /this/is/the/path and is within a new, absent |
| 14196 |
file system, but ... |
| 14197 |
|
| 14198 |
- The client will never see the value of that fh. |
| 14199 |
|
| 14200 |
OP13: GETATTR(fsid, fs_locations_info) --> NFS_OK |
| 14201 |
|
| 14202 |
- We are getting the fsid to know where the file system boundaries |
| 14203 |
are. In this operation, the fsid will be different than that of |
| 14204 |
the parent directory (which in turn was retrieved in OP10). Note |
| 14205 |
that the fsid we are given will not necessarily be preserved at |
| 14206 |
the new location. That fsid might be different, and in fact the |
| 14207 |
fsid we have for this file system might be a valid fsid of a |
| 14208 |
different file system on that new server. |
| 14209 |
|
| 14210 |
- In this particular case, we are pretty sure anyway that what has |
| 14211 |
moved is /this/is/the/path rather than /this/is/the since we have |
| 14212 |
the fsid of the latter and it is that of the pseudo-fs, which |
| 14213 |
presumably cannot move. However, in other examples, we might not |
| 14214 |
have this kind of information to rely on (e.g., /this/is/the might |
| 14215 |
be a non-pseudo file system separate from /this/is/the/path), so |
| 14216 |
we need to have other reliable source information on the boundary |
| 14217 |
|
| 14218 |
|
| 14219 |
|
| 14220 |
<span class="grey">Shepler, et al. Standards Track [Page 254]</span></pre> |
| 14221 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-255" ></span> |
| 14222 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14223 |
|
| 14224 |
|
| 14225 |
of the file system that is moved. If, for example, the file |
| 14226 |
system /this/is had moved, we would have a case of migration |
| 14227 |
rather than referral, and once the boundaries of the migrated file |
| 14228 |
system was clear we could fetch fs_locations_info. |
| 14229 |
|
| 14230 |
- We are fetching fs_locations_info because the fact that we got an |
| 14231 |
NFS4ERR_MOVED at this point means that it is most likely that this |
| 14232 |
is a referral and we need the destination. Even if it is the case |
| 14233 |
that /this/is/the is a file system that has migrated, we will |
| 14234 |
still need the location information for that file system. |
| 14235 |
|
| 14236 |
OP14: GETFH --> NFS4ERR_MOVED |
| 14237 |
|
| 14238 |
- Fails because current fh is in an absent file system at the start |
| 14239 |
of the operation, and the specification makes no exception for |
| 14240 |
GETFH. Note that this means the server will never send the client |
| 14241 |
a filehandle from within an absent file system. |
| 14242 |
|
| 14243 |
Given the above, the client knows where the root of the absent file |
| 14244 |
system is (/this/is/the/path) by noting where the change of fsid |
| 14245 |
occurred (between "the" and "path"). The fs_locations_info attribute |
| 14246 |
also gives the client the actual location of the absent file system, |
| 14247 |
so that the referral can proceed. The server gives the client the |
| 14248 |
bare minimum of information about the absent file system so that |
| 14249 |
there will be very little scope for problems of conflict between |
| 14250 |
information sent by the referring server and information of the file |
| 14251 |
system's home. No filehandles and very few attributes are present on |
| 14252 |
the referring server, and the client can treat those it receives as |
| 14253 |
transient information with the function of enabling the referral. |
| 14254 |
|
| 14255 |
<span class="h4"><a class="selflink" id="section-11.8.2" href="#section-11.8.2">11.8.2</a>. Referral Example (READDIR)</span> |
| 14256 |
|
| 14257 |
Another context in which a client may encounter referrals is when it |
| 14258 |
does a READDIR on a directory in which some of the sub-directories |
| 14259 |
are the roots of absent file systems. |
| 14260 |
|
| 14261 |
Suppose such a directory is read as follows: |
| 14262 |
|
| 14263 |
o PUTROOTFH |
| 14264 |
|
| 14265 |
o LOOKUP "this" |
| 14266 |
|
| 14267 |
o LOOKUP "is" |
| 14268 |
|
| 14269 |
o LOOKUP "the" |
| 14270 |
|
| 14271 |
o READDIR (fsid, size, time_modify, mounted_on_fileid) |
| 14272 |
|
| 14273 |
|
| 14274 |
|
| 14275 |
|
| 14276 |
<span class="grey">Shepler, et al. Standards Track [Page 255]</span></pre> |
| 14277 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-256" ></span> |
| 14278 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14279 |
|
| 14280 |
|
| 14281 |
In this case, because rdattr_error is not requested, |
| 14282 |
fs_locations_info is not requested, and some of the attributes cannot |
| 14283 |
be provided, the result will be an NFS4ERR_MOVED error on the |
| 14284 |
READDIR, with the detailed results as follows: |
| 14285 |
|
| 14286 |
o PUTROOTFH --> NFS_OK. The current fh is at the root of the |
| 14287 |
pseudo-fs. |
| 14288 |
|
| 14289 |
o LOOKUP "this" --> NFS_OK. The current fh is for /this and is |
| 14290 |
within the pseudo-fs. |
| 14291 |
|
| 14292 |
o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is |
| 14293 |
within the pseudo-fs. |
| 14294 |
|
| 14295 |
o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and |
| 14296 |
is within the pseudo-fs. |
| 14297 |
|
| 14298 |
o READDIR (fsid, size, time_modify, mounted_on_fileid) --> |
| 14299 |
NFS4ERR_MOVED. Note that the same error would have been returned |
| 14300 |
if /this/is/the had migrated, but it is returned because the |
| 14301 |
directory contains the root of an absent file system. |
| 14302 |
|
| 14303 |
So now suppose that we re-send with rdattr_error: |
| 14304 |
|
| 14305 |
o PUTROOTFH |
| 14306 |
|
| 14307 |
o LOOKUP "this" |
| 14308 |
|
| 14309 |
o LOOKUP "is" |
| 14310 |
|
| 14311 |
o LOOKUP "the" |
| 14312 |
|
| 14313 |
o READDIR (rdattr_error, fsid, size, time_modify, mounted_on_fileid) |
| 14314 |
|
| 14315 |
The results will be: |
| 14316 |
|
| 14317 |
o PUTROOTFH --> NFS_OK. The current fh is at the root of the |
| 14318 |
pseudo-fs. |
| 14319 |
|
| 14320 |
o LOOKUP "this" --> NFS_OK. The current fh is for /this and is |
| 14321 |
within the pseudo-fs. |
| 14322 |
|
| 14323 |
o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is |
| 14324 |
within the pseudo-fs. |
| 14325 |
|
| 14326 |
o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and |
| 14327 |
is within the pseudo-fs. |
| 14328 |
|
| 14329 |
|
| 14330 |
|
| 14331 |
|
| 14332 |
<span class="grey">Shepler, et al. Standards Track [Page 256]</span></pre> |
| 14333 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-257" ></span> |
| 14334 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14335 |
|
| 14336 |
|
| 14337 |
o READDIR (rdattr_error, fsid, size, time_modify, mounted_on_fileid) |
| 14338 |
--> NFS_OK. The attributes for directory entry with the component |
| 14339 |
named "path" will only contain rdattr_error with the value |
| 14340 |
NFS4ERR_MOVED, together with an fsid value and a value for |
| 14341 |
mounted_on_fileid. |
| 14342 |
|
| 14343 |
So suppose we do another READDIR to get fs_locations_info (although |
| 14344 |
we could have used a GETATTR directly, as in <a href="#section-11.8.1">Section 11.8.1</a>). |
| 14345 |
|
| 14346 |
o PUTROOTFH |
| 14347 |
|
| 14348 |
o LOOKUP "this" |
| 14349 |
|
| 14350 |
o LOOKUP "is" |
| 14351 |
|
| 14352 |
o LOOKUP "the" |
| 14353 |
|
| 14354 |
o READDIR (rdattr_error, fs_locations_info, mounted_on_fileid, fsid, |
| 14355 |
size, time_modify) |
| 14356 |
|
| 14357 |
The results would be: |
| 14358 |
|
| 14359 |
o PUTROOTFH --> NFS_OK. The current fh is at the root of the |
| 14360 |
pseudo-fs. |
| 14361 |
|
| 14362 |
o LOOKUP "this" --> NFS_OK. The current fh is for /this and is |
| 14363 |
within the pseudo-fs. |
| 14364 |
|
| 14365 |
o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is |
| 14366 |
within the pseudo-fs. |
| 14367 |
|
| 14368 |
o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and |
| 14369 |
is within the pseudo-fs. |
| 14370 |
|
| 14371 |
o READDIR (rdattr_error, fs_locations_info, mounted_on_fileid, fsid, |
| 14372 |
size, time_modify) --> NFS_OK. The attributes will be as shown |
| 14373 |
below. |
| 14374 |
|
| 14375 |
The attributes for the directory entry with the component named |
| 14376 |
"path" will only contain: |
| 14377 |
|
| 14378 |
o rdattr_error (value: NFS_OK) |
| 14379 |
|
| 14380 |
o fs_locations_info |
| 14381 |
|
| 14382 |
o mounted_on_fileid (value: unique fileid within referring file |
| 14383 |
system) |
| 14384 |
|
| 14385 |
|
| 14386 |
|
| 14387 |
|
| 14388 |
<span class="grey">Shepler, et al. Standards Track [Page 257]</span></pre> |
| 14389 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-258" ></span> |
| 14390 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14391 |
|
| 14392 |
|
| 14393 |
o fsid (value: unique value within referring server) |
| 14394 |
|
| 14395 |
The attributes for entry "path" will not contain size or time_modify |
| 14396 |
because these attributes are not available within an absent file |
| 14397 |
system. |
| 14398 |
|
| 14399 |
<span class="h3"><a class="selflink" id="section-11.9" href="#section-11.9">11.9</a>. The Attribute fs_locations</span> |
| 14400 |
|
| 14401 |
The fs_locations attribute is structured in the following way: |
| 14402 |
|
| 14403 |
|
| 14404 |
struct fs_location4 { |
| 14405 |
utf8str_cis server<>; |
| 14406 |
pathname4 rootpath; |
| 14407 |
}; |
| 14408 |
|
| 14409 |
|
| 14410 |
struct fs_locations4 { |
| 14411 |
pathname4 fs_root; |
| 14412 |
fs_location4 locations<>; |
| 14413 |
}; |
| 14414 |
|
| 14415 |
The fs_location4 data type is used to represent the location of a |
| 14416 |
file system by providing a server name and the path to the root of |
| 14417 |
the file system within that server's namespace. When a set of |
| 14418 |
servers have corresponding file systems at the same path within their |
| 14419 |
namespaces, an array of server names may be provided. An entry in |
| 14420 |
the server array is a UTF-8 string and represents one of a |
| 14421 |
traditional DNS host name, IPv4 address, IPv6 address, or a zero- |
| 14422 |
length string. An IPv4 or IPv6 address is represented as a universal |
| 14423 |
address (see <a href="#section-3.3.9">Section 3.3.9</a> and [<a href="#ref-15" title=""IANA Considerations for Remote Procedure Call (RPC) Network Identifiers and Universal Address Formats"">15</a>]), minus the netid, and either |
| 14424 |
with or without the trailing ".p1.p2" suffix that represents the port |
| 14425 |
number. If the suffix is omitted, then the default port, 2049, |
| 14426 |
SHOULD be assumed. A zero-length string SHOULD be used to indicate |
| 14427 |
the current address being used for the RPC call. It is not a |
| 14428 |
requirement that all servers that share the same rootpath be listed |
| 14429 |
in one fs_location4 instance. The array of server names is provided |
| 14430 |
for convenience. Servers that share the same rootpath may also be |
| 14431 |
listed in separate fs_location4 entries in the fs_locations |
| 14432 |
attribute. |
| 14433 |
|
| 14434 |
The fs_locations4 data type and fs_locations attribute contain an |
| 14435 |
array of such locations. Since the namespace of each server may be |
| 14436 |
constructed differently, the "fs_root" field is provided. The path |
| 14437 |
represented by fs_root represents the location of the file system in |
| 14438 |
the current server's namespace, i.e., that of the server from which |
| 14439 |
the fs_locations attribute was obtained. The fs_root path is meant |
| 14440 |
to aid the client by clearly referencing the root of the file system |
| 14441 |
|
| 14442 |
|
| 14443 |
|
| 14444 |
<span class="grey">Shepler, et al. Standards Track [Page 258]</span></pre> |
| 14445 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-259" ></span> |
| 14446 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14447 |
|
| 14448 |
|
| 14449 |
whose locations are being reported, no matter what object within the |
| 14450 |
current file system the current filehandle designates. The fs_root |
| 14451 |
is simply the pathname the client used to reach the object on the |
| 14452 |
current server (i.e., the object to which the fs_locations attribute |
| 14453 |
applies). |
| 14454 |
|
| 14455 |
When the fs_locations attribute is interrogated and there are no |
| 14456 |
alternate file system locations, the server SHOULD return a zero- |
| 14457 |
length array of fs_location4 structures, together with a valid |
| 14458 |
fs_root. |
| 14459 |
|
| 14460 |
As an example, suppose there is a replicated file system located at |
| 14461 |
two servers (servA and servB). At servA, the file system is located |
| 14462 |
at path /a/b/c. At, servB the file system is located at path /x/y/z. |
| 14463 |
If the client were to obtain the fs_locations value for the directory |
| 14464 |
at /a/b/c/d, it might not necessarily know that the file system's |
| 14465 |
root is located in servA's namespace at /a/b/c. When the client |
| 14466 |
switches to servB, it will need to determine that the directory it |
| 14467 |
first referenced at servA is now represented by the path /x/y/z/d on |
| 14468 |
servB. To facilitate this, the fs_locations attribute provided by |
| 14469 |
servA would have an fs_root value of /a/b/c and two entries in |
| 14470 |
fs_locations. One entry in fs_locations will be for itself (servA) |
| 14471 |
and the other will be for servB with a path of /x/y/z. With this |
| 14472 |
information, the client is able to substitute /x/y/z for the /a/b/c |
| 14473 |
at the beginning of its access path and construct /x/y/z/d to use for |
| 14474 |
the new server. |
| 14475 |
|
| 14476 |
Note that there is no requirement that the number of components in |
| 14477 |
each rootpath be the same; there is no relation between the number of |
| 14478 |
components in rootpath or fs_root, and none of the components in a |
| 14479 |
rootpath and fs_root have to be the same. In the above example, we |
| 14480 |
could have had a third element in the locations array, with server |
| 14481 |
equal to "servC" and rootpath equal to "/I/II", and a fourth element |
| 14482 |
in locations with server equal to "servD" and rootpath equal to |
| 14483 |
"/aleph/beth/gimel/daleth/he". |
| 14484 |
|
| 14485 |
The relationship between fs_root to a rootpath is that the client |
| 14486 |
replaces the pathname indicated in fs_root for the current server for |
| 14487 |
the substitute indicated in rootpath for the new server. |
| 14488 |
|
| 14489 |
For an example of a referred or migrated file system, suppose there |
| 14490 |
is a file system located at serv1. At serv1, the file system is |
| 14491 |
located at /az/buky/vedi/glagoli. The client finds that object at |
| 14492 |
glagoli has migrated (or is a referral). The client gets the |
| 14493 |
fs_locations attribute, which contains an fs_root of /az/buky/vedi/ |
| 14494 |
glagoli, and one element in the locations array, with server equal to |
| 14495 |
|
| 14496 |
|
| 14497 |
|
| 14498 |
|
| 14499 |
|
| 14500 |
<span class="grey">Shepler, et al. Standards Track [Page 259]</span></pre> |
| 14501 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-260" ></span> |
| 14502 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14503 |
|
| 14504 |
|
| 14505 |
serv2, and rootpath equal to /izhitsa/fita. The client replaces /az/ |
| 14506 |
buky/vedi/glagoli with /izhitsa/fita, and uses the latter pathname on |
| 14507 |
serv2. |
| 14508 |
|
| 14509 |
Thus, the server MUST return an fs_root that is equal to the path the |
| 14510 |
client used to reach the object to which the fs_locations attribute |
| 14511 |
applies. Otherwise, the client cannot determine the new path to use |
| 14512 |
on the new server. |
| 14513 |
|
| 14514 |
Since the fs_locations attribute lacks information defining various |
| 14515 |
attributes of the various file system choices presented, it SHOULD |
| 14516 |
only be interrogated and used when fs_locations_info is not |
| 14517 |
available. When fs_locations is used, information about the specific |
| 14518 |
locations should be assumed based on the following rules. |
| 14519 |
|
| 14520 |
The following rules are general and apply irrespective of the |
| 14521 |
context. |
| 14522 |
|
| 14523 |
o All listed file system instances should be considered as of the |
| 14524 |
same handle class, if and only if, the current fh_expire_type |
| 14525 |
attribute does not include the FH4_VOL_MIGRATION bit. Note that |
| 14526 |
in the case of referral, filehandle issues do not apply since |
| 14527 |
there can be no filehandles known within the current file system, |
| 14528 |
nor is there any access to the fh_expire_type attribute on the |
| 14529 |
referring (absent) file system. |
| 14530 |
|
| 14531 |
o All listed file system instances should be considered as of the |
| 14532 |
same fileid class if and only if the fh_expire_type attribute |
| 14533 |
indicates persistent filehandles and does not include the |
| 14534 |
FH4_VOL_MIGRATION bit. Note that in the case of referral, fileid |
| 14535 |
issues do not apply since there can be no fileids known within the |
| 14536 |
referring (absent) file system, nor is there any access to the |
| 14537 |
fh_expire_type attribute. |
| 14538 |
|
| 14539 |
o All file system instances servers should be considered as of |
| 14540 |
different change classes. |
| 14541 |
|
| 14542 |
For other class assignments, handling of file system transitions |
| 14543 |
depends on the reasons for the transition: |
| 14544 |
|
| 14545 |
o When the transition is due to migration, that is, the client was |
| 14546 |
directed to a new file system after receiving an NFS4ERR_MOVED |
| 14547 |
error, the target should be treated as being of the same write- |
| 14548 |
verifier class as the source. |
| 14549 |
|
| 14550 |
|
| 14551 |
|
| 14552 |
|
| 14553 |
|
| 14554 |
|
| 14555 |
|
| 14556 |
<span class="grey">Shepler, et al. Standards Track [Page 260]</span></pre> |
| 14557 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-261" ></span> |
| 14558 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14559 |
|
| 14560 |
|
| 14561 |
o When the transition is due to failover to another replica, that |
| 14562 |
is, the client selected another replica without receiving an |
| 14563 |
NFS4ERR_MOVED error, the target should be treated as being of a |
| 14564 |
different write-verifier class from the source. |
| 14565 |
|
| 14566 |
The specific choices reflect typical implementation patterns for |
| 14567 |
failover and controlled migration, respectively. Since other choices |
| 14568 |
are possible and useful, this information is better obtained by using |
| 14569 |
fs_locations_info. When a server implementation needs to communicate |
| 14570 |
other choices, it MUST support the fs_locations_info attribute. |
| 14571 |
|
| 14572 |
See <a href="#section-21">Section 21</a> for a discussion on the recommendations for the |
| 14573 |
security flavor to be used by any GETATTR operation that requests the |
| 14574 |
"fs_locations" attribute. |
| 14575 |
|
| 14576 |
<span class="h3"><a class="selflink" id="section-11.10" href="#section-11.10">11.10</a>. The Attribute fs_locations_info</span> |
| 14577 |
|
| 14578 |
The fs_locations_info attribute is intended as a more functional |
| 14579 |
replacement for fs_locations that will continue to exist and be |
| 14580 |
supported. Clients can use it to get a more complete set of |
| 14581 |
information about alternative file system locations. When the server |
| 14582 |
does not support fs_locations_info, fs_locations can be used to get a |
| 14583 |
subset of the information. A server that supports fs_locations_info |
| 14584 |
MUST support fs_locations as well. |
| 14585 |
|
| 14586 |
There is additional information present in fs_locations_info, that is |
| 14587 |
not available in fs_locations: |
| 14588 |
|
| 14589 |
o Attribute continuity information. This information will allow a |
| 14590 |
client to select a location that meets the transparency |
| 14591 |
requirements of the applications accessing the data and to |
| 14592 |
leverage optimizations due to the server guarantees of attribute |
| 14593 |
continuity (e.g., if between multiple server locations the change |
| 14594 |
attribute of a file of the file system is continuous, the client |
| 14595 |
does not have to invalidate the file's cache if the change |
| 14596 |
attribute is the same among all locations). |
| 14597 |
|
| 14598 |
o File system identity information that indicates when multiple |
| 14599 |
replicas, from the client's point of view, correspond to the same |
| 14600 |
target file system, allowing them to be used interchangeably, |
| 14601 |
without disruption, as multiple paths to the same thing. |
| 14602 |
|
| 14603 |
o Information that will bear on the suitability of various replicas, |
| 14604 |
depending on the use that the client intends. For example, many |
| 14605 |
applications need an absolutely up-to-date copy (e.g., those that |
| 14606 |
write), while others may only need access to the most up-to-date |
| 14607 |
copy reasonably available. |
| 14608 |
|
| 14609 |
|
| 14610 |
|
| 14611 |
|
| 14612 |
<span class="grey">Shepler, et al. Standards Track [Page 261]</span></pre> |
| 14613 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-262" ></span> |
| 14614 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14615 |
|
| 14616 |
|
| 14617 |
o Server-derived preference information for replicas, which can be |
| 14618 |
used to implement load-balancing while giving the client the |
| 14619 |
entire file system list to be used in case the primary fails. |
| 14620 |
|
| 14621 |
The fs_locations_info attribute is structured similarly to the |
| 14622 |
fs_locations attribute. A top-level structure (fs_locations_info4) |
| 14623 |
contains the entire attribute including the root pathname of the file |
| 14624 |
system and an array of lower-level structures that define replicas |
| 14625 |
that share a common rootpath on their respective servers. The lower- |
| 14626 |
level structure in turn (fs_locations_item4) contains a specific |
| 14627 |
pathname and information on one or more individual server replicas. |
| 14628 |
For that last lowest-level, fs_locations_info has an |
| 14629 |
fs_locations_server4 structure that contains per-server-replica |
| 14630 |
information in addition to the server name. This per-server-replica |
| 14631 |
information includes a nominally opaque array, fls_info, in which |
| 14632 |
specific pieces of information are located at the specific indices |
| 14633 |
listed below. |
| 14634 |
|
| 14635 |
The attribute will always contain at least a single |
| 14636 |
fs_locations_server entry. Typically, this will be an entry with the |
| 14637 |
FS4LIGF_CUR_REQ flag set, although in the case of a referral there |
| 14638 |
will be no entry with that flag set. |
| 14639 |
|
| 14640 |
It should be noted that fs_locations_info attributes returned by |
| 14641 |
servers for various replicas may differ for various reasons. One |
| 14642 |
server may know about a set of replicas that are not known to other |
| 14643 |
servers. Further, compatibility attributes may differ. Filehandles |
| 14644 |
might be of the same class going from replica A to replica B but not |
| 14645 |
going in the reverse direction. This might happen because the |
| 14646 |
filehandles are the same, but replica B's server implementation might |
| 14647 |
not have provision to note and report that equivalence. |
| 14648 |
|
| 14649 |
The fs_locations_info attribute consists of a root pathname |
| 14650 |
(fli_fs_root, just like fs_root in the fs_locations attribute), |
| 14651 |
together with an array of fs_location_item4 structures. The |
| 14652 |
fs_location_item4 structures in turn consist of a root pathname |
| 14653 |
(fli_rootpath) together with an array (fli_entries) of elements of |
| 14654 |
data type fs_locations_server4, all defined as follows. |
| 14655 |
|
| 14656 |
|
| 14657 |
|
| 14658 |
|
| 14659 |
|
| 14660 |
|
| 14661 |
|
| 14662 |
|
| 14663 |
|
| 14664 |
|
| 14665 |
|
| 14666 |
|
| 14667 |
|
| 14668 |
<span class="grey">Shepler, et al. Standards Track [Page 262]</span></pre> |
| 14669 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-263" ></span> |
| 14670 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14671 |
|
| 14672 |
|
| 14673 |
/* |
| 14674 |
* Defines an individual server replica |
| 14675 |
*/ |
| 14676 |
struct fs_locations_server4 { |
| 14677 |
int32_t fls_currency; |
| 14678 |
opaque fls_info<>; |
| 14679 |
utf8str_cis fls_server; |
| 14680 |
}; |
| 14681 |
|
| 14682 |
/* |
| 14683 |
* Byte indices of items within |
| 14684 |
* fls_info: flag fields, class numbers, |
| 14685 |
* bytes indicating ranks and orders. |
| 14686 |
*/ |
| 14687 |
const FSLI4BX_GFLAGS = 0; |
| 14688 |
const FSLI4BX_TFLAGS = 1; |
| 14689 |
const FSLI4BX_CLSIMUL = 2; |
| 14690 |
const FSLI4BX_CLHANDLE = 3; |
| 14691 |
const FSLI4BX_CLFILEID = 4; |
| 14692 |
const FSLI4BX_CLWRITEVER = 5; |
| 14693 |
const FSLI4BX_CLCHANGE = 6; |
| 14694 |
const FSLI4BX_CLREADDIR = 7; |
| 14695 |
|
| 14696 |
const FSLI4BX_READRANK = 8; |
| 14697 |
const FSLI4BX_WRITERANK = 9; |
| 14698 |
const FSLI4BX_READORDER = 10; |
| 14699 |
const FSLI4BX_WRITEORDER = 11; |
| 14700 |
|
| 14701 |
/* |
| 14702 |
* Bits defined within the general flag byte. |
| 14703 |
*/ |
| 14704 |
const FSLI4GF_WRITABLE = 0x01; |
| 14705 |
const FSLI4GF_CUR_REQ = 0x02; |
| 14706 |
const FSLI4GF_ABSENT = 0x04; |
| 14707 |
const FSLI4GF_GOING = 0x08; |
| 14708 |
const FSLI4GF_SPLIT = 0x10; |
| 14709 |
|
| 14710 |
|
| 14711 |
|
| 14712 |
|
| 14713 |
|
| 14714 |
|
| 14715 |
|
| 14716 |
|
| 14717 |
|
| 14718 |
|
| 14719 |
|
| 14720 |
|
| 14721 |
|
| 14722 |
|
| 14723 |
|
| 14724 |
<span class="grey">Shepler, et al. Standards Track [Page 263]</span></pre> |
| 14725 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-264" ></span> |
| 14726 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14727 |
|
| 14728 |
|
| 14729 |
/* |
| 14730 |
* Bits defined within the transport flag byte. |
| 14731 |
*/ |
| 14732 |
const FSLI4TF_RDMA = 0x01; |
| 14733 |
|
| 14734 |
/* |
| 14735 |
* Defines a set of replicas sharing |
| 14736 |
* a common value of the rootpath |
| 14737 |
* with in the corresponding |
| 14738 |
* single-server namespaces. |
| 14739 |
*/ |
| 14740 |
struct fs_locations_item4 { |
| 14741 |
fs_locations_server4 fli_entries<>; |
| 14742 |
pathname4 fli_rootpath; |
| 14743 |
}; |
| 14744 |
|
| 14745 |
/* |
| 14746 |
* Defines the overall structure of |
| 14747 |
* the fs_locations_info attribute. |
| 14748 |
*/ |
| 14749 |
struct fs_locations_info4 { |
| 14750 |
uint32_t fli_flags; |
| 14751 |
int32_t fli_valid_for; |
| 14752 |
pathname4 fli_fs_root; |
| 14753 |
fs_locations_item4 fli_items<>; |
| 14754 |
}; |
| 14755 |
|
| 14756 |
/* |
| 14757 |
* Flag bits in fli_flags. |
| 14758 |
*/ |
| 14759 |
const FSLI4IF_VAR_SUB = 0x00000001; |
| 14760 |
|
| 14761 |
typedef fs_locations_info4 fattr4_fs_locations_info; |
| 14762 |
|
| 14763 |
As noted above, the fs_locations_info attribute, when supported, may |
| 14764 |
be requested of absent file systems without causing NFS4ERR_MOVED to |
| 14765 |
be returned. It is generally expected that it will be available for |
| 14766 |
both present and absent file systems even if only a single |
| 14767 |
fs_locations_server4 entry is present, designating the current |
| 14768 |
(present) file system, or two fs_locations_server4 entries |
| 14769 |
designating the previous location of an absent file system (the one |
| 14770 |
just referenced) and its successor location. Servers are strongly |
| 14771 |
urged to support this attribute on all file systems if they support |
| 14772 |
it on any file system. |
| 14773 |
|
| 14774 |
|
| 14775 |
|
| 14776 |
|
| 14777 |
|
| 14778 |
|
| 14779 |
|
| 14780 |
<span class="grey">Shepler, et al. Standards Track [Page 264]</span></pre> |
| 14781 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-265" ></span> |
| 14782 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14783 |
|
| 14784 |
|
| 14785 |
The data presented in the fs_locations_info attribute may be obtained |
| 14786 |
by the server in any number of ways, including specification by the |
| 14787 |
administrator or by current protocols for transferring data among |
| 14788 |
replicas and protocols not yet developed. NFSv4.1 only defines how |
| 14789 |
this information is presented by the server to the client. |
| 14790 |
|
| 14791 |
<span class="h4"><a class="selflink" id="section-11.10.1" href="#section-11.10.1">11.10.1</a>. The fs_locations_server4 Structure</span> |
| 14792 |
|
| 14793 |
The fs_locations_server4 structure consists of the following items: |
| 14794 |
|
| 14795 |
o An indication of how up-to-date the file system is (fls_currency) |
| 14796 |
in seconds. This value is relative to the master copy. A |
| 14797 |
negative value indicates that the server is unable to give any |
| 14798 |
reasonably useful value here. A value of zero indicates that the |
| 14799 |
file system is the actual writable data or a reliably coherent and |
| 14800 |
fully up-to-date copy. Positive values indicate how out-of-date |
| 14801 |
this copy can normally be before it is considered for update. |
| 14802 |
Such a value is not a guarantee that such updates will always be |
| 14803 |
performed on the required schedule but instead serves as a hint |
| 14804 |
about how far the copy of the data would be expected to be behind |
| 14805 |
the most up-to-date copy. |
| 14806 |
|
| 14807 |
o A counted array of one-byte values (fls_info) containing |
| 14808 |
information about the particular file system instance. This data |
| 14809 |
includes general flags, transport capability flags, file system |
| 14810 |
equivalence class information, and selection priority information. |
| 14811 |
The encoding will be discussed below. |
| 14812 |
|
| 14813 |
o The server string (fls_server). For the case of the replica |
| 14814 |
currently being accessed (via GETATTR), a zero-length string MAY |
| 14815 |
be used to indicate the current address being used for the RPC |
| 14816 |
call. The fls_server field can also be an IPv4 or IPv6 address, |
| 14817 |
formatted the same way as an IPv4 or IPv6 address in the "server" |
| 14818 |
field of the fs_location4 data type (see <a href="#section-11.9">Section 11.9</a>). |
| 14819 |
|
| 14820 |
Data within the fls_info array is in the form of 8-bit data items |
| 14821 |
with constants giving the offsets within the array of various values |
| 14822 |
describing this particular file system instance. This style of |
| 14823 |
definition was chosen, in preference to explicit XDR structure |
| 14824 |
definitions for these values, for a number of reasons. |
| 14825 |
|
| 14826 |
o The kinds of data in the fls_info array, representing flags, file |
| 14827 |
system classes, and priorities among sets of file systems |
| 14828 |
representing the same data, are such that 8 bits provide a quite |
| 14829 |
acceptable range of values. Even where there might be more than |
| 14830 |
256 such file system instances, having more than 256 distinct |
| 14831 |
classes or priorities is unlikely. |
| 14832 |
|
| 14833 |
|
| 14834 |
|
| 14835 |
|
| 14836 |
<span class="grey">Shepler, et al. Standards Track [Page 265]</span></pre> |
| 14837 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-266" ></span> |
| 14838 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14839 |
|
| 14840 |
|
| 14841 |
o Explicit definition of the various specific data items within XDR |
| 14842 |
would limit expandability in that any extension within a |
| 14843 |
subsequent minor version would require yet another attribute, |
| 14844 |
leading to specification and implementation clumsiness. |
| 14845 |
|
| 14846 |
o Such explicit definitions would also make it impossible to propose |
| 14847 |
Standards Track extensions apart from a full minor version. |
| 14848 |
|
| 14849 |
This encoding scheme can be adapted to the specification of multi- |
| 14850 |
byte numeric values, even though none are currently defined. If |
| 14851 |
extensions are made via Standards Track RFCs, multi-byte quantities |
| 14852 |
will be encoded as a range of bytes with a range of indices, with the |
| 14853 |
byte interpreted in big-endian byte order. Further, any such index |
| 14854 |
assignments are constrained so that the relevant quantities will not |
| 14855 |
cross XDR word boundaries. |
| 14856 |
|
| 14857 |
The set of fls_info data is subject to expansion in a future minor |
| 14858 |
version, or in a Standards Track RFC, within the context of a single |
| 14859 |
minor version. The server SHOULD NOT send and the client MUST NOT |
| 14860 |
use indices within the fls_info array that are not defined in |
| 14861 |
Standards Track RFCs. |
| 14862 |
|
| 14863 |
The fls_info array contains: |
| 14864 |
|
| 14865 |
o Two 8-bit flag fields, one devoted to general file-system |
| 14866 |
characteristics and a second reserved for transport-related |
| 14867 |
capabilities. |
| 14868 |
|
| 14869 |
o Six 8-bit class values that define various file system equivalence |
| 14870 |
classes as explained below. |
| 14871 |
|
| 14872 |
o Four 8-bit priority values that govern file system selection as |
| 14873 |
explained below. |
| 14874 |
|
| 14875 |
The general file system characteristics flag (at byte index |
| 14876 |
FSLI4BX_GFLAGS) has the following bits defined within it: |
| 14877 |
|
| 14878 |
o FSLI4GF_WRITABLE indicates that this file system target is |
| 14879 |
writable, allowing it to be selected by clients that may need to |
| 14880 |
write on this file system. When the current file system instance |
| 14881 |
is writable and is defined as of the same simultaneous use class |
| 14882 |
(as specified by the value at index FSLI4BX_CLSIMUL) to which the |
| 14883 |
client was previously writing, then it must incorporate within its |
| 14884 |
data any committed write made on the source file system instance. |
| 14885 |
See <a href="#section-11.7.8">Section 11.7.8</a>, which discusses the write-verifier class. |
| 14886 |
While there is no harm in not setting this flag for a file system |
| 14887 |
that turns out to be writable, turning the flag on for a read-only |
| 14888 |
|
| 14889 |
|
| 14890 |
|
| 14891 |
|
| 14892 |
<span class="grey">Shepler, et al. Standards Track [Page 266]</span></pre> |
| 14893 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-267" ></span> |
| 14894 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14895 |
|
| 14896 |
|
| 14897 |
file system can cause problems for clients that select a migration |
| 14898 |
or replication target based on the flag and then find themselves |
| 14899 |
unable to write. |
| 14900 |
|
| 14901 |
o FSLI4GF_CUR_REQ indicates that this replica is the one on which |
| 14902 |
the request is being made. Only a single server entry may have |
| 14903 |
this flag set and, in the case of a referral, no entry will have |
| 14904 |
it. |
| 14905 |
|
| 14906 |
o FSLI4GF_ABSENT indicates that this entry corresponds to an absent |
| 14907 |
file system replica. It can only be set if FSLI4GF_CUR_REQ is |
| 14908 |
set. When both such bits are set, it indicates that a file system |
| 14909 |
instance is not usable but that the information in the entry can |
| 14910 |
be used to determine the sorts of continuity available when |
| 14911 |
switching from this replica to other possible replicas. Since |
| 14912 |
this bit can only be true if FSLI4GF_CUR_REQ is true, the value |
| 14913 |
could be determined using the fs_status attribute, but the |
| 14914 |
information is also made available here for the convenience of the |
| 14915 |
client. An entry with this bit, since it represents a true file |
| 14916 |
system (albeit absent), does not appear in the event of a |
| 14917 |
referral, but only when a file system has been accessed at this |
| 14918 |
location and has subsequently been migrated. |
| 14919 |
|
| 14920 |
o FSLI4GF_GOING indicates that a replica, while still available, |
| 14921 |
should not be used further. The client, if using it, should make |
| 14922 |
an orderly transfer to another file system instance as |
| 14923 |
expeditiously as possible. It is expected that file systems going |
| 14924 |
out of service will be announced as FSLI4GF_GOING some time before |
| 14925 |
the actual loss of service. It is also expected that the |
| 14926 |
fli_valid_for value will be sufficiently small to allow clients to |
| 14927 |
detect and act on scheduled events, while large enough that the |
| 14928 |
cost of the requests to fetch the fs_locations_info values will |
| 14929 |
not be excessive. Values on the order of ten minutes seem |
| 14930 |
reasonable. |
| 14931 |
|
| 14932 |
When this flag is seen as part of a transition into a new file |
| 14933 |
system, a client might choose to transfer immediately to another |
| 14934 |
replica, or it may reference the current file system and only |
| 14935 |
transition when a migration event occurs. Similarly, when this |
| 14936 |
flag appears as a replica in the referral, clients would likely |
| 14937 |
avoid being referred to this instance whenever there is another |
| 14938 |
choice. |
| 14939 |
|
| 14940 |
o FSLI4GF_SPLIT indicates that when a transition occurs from the |
| 14941 |
current file system instance to this one, the replacement may |
| 14942 |
consist of multiple file systems. In this case, the client has to |
| 14943 |
be prepared for the possibility that objects on the same file |
| 14944 |
system before migration will be on different ones after. Note |
| 14945 |
|
| 14946 |
|
| 14947 |
|
| 14948 |
<span class="grey">Shepler, et al. Standards Track [Page 267]</span></pre> |
| 14949 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-268" ></span> |
| 14950 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 14951 |
|
| 14952 |
|
| 14953 |
that FSLI4GF_SPLIT is not incompatible with the file systems |
| 14954 |
belonging to the same fileid class since, if one has a set of |
| 14955 |
fileids that are unique within a file system, each subset assigned |
| 14956 |
to a smaller file system after migration would not have any |
| 14957 |
conflicts internal to that file system. |
| 14958 |
|
| 14959 |
A client, in the case of a split file system, will interrogate |
| 14960 |
existing files with which it has continuing connection (it is free |
| 14961 |
to simply forget cached filehandles). If the client remembers the |
| 14962 |
directory filehandle associated with each open file, it may |
| 14963 |
proceed upward using LOOKUPP to find the new file system |
| 14964 |
boundaries. Note that in the event of a referral, there will not |
| 14965 |
be any such files and so these actions will not be performed. |
| 14966 |
Instead, a reference to a portion of the original file system now |
| 14967 |
split off into other file systems will encounter an fsid change |
| 14968 |
and possibly a further referral. |
| 14969 |
|
| 14970 |
Once the client recognizes that one file system has been split |
| 14971 |
into two, it can prevent the disruption of running applications by |
| 14972 |
presenting the two file systems as a single one until a convenient |
| 14973 |
point to recognize the transition, such as a restart. This would |
| 14974 |
require a mapping from the server's fsids to fsids as seen by the |
| 14975 |
client, but this is already necessary for other reasons. As noted |
| 14976 |
above, existing fileids within the two descendant file systems |
| 14977 |
will not conflict. Providing non-conflicting fileids for newly |
| 14978 |
created files on the split file systems is the responsibility of |
| 14979 |
the server (or servers working in concert). The server can encode |
| 14980 |
filehandles such that filehandles generated before the split event |
| 14981 |
can be discerned from those generated after the split, allowing |
| 14982 |
the server to determine when the need for emulating two file |
| 14983 |
systems as one is over. |
| 14984 |
|
| 14985 |
Although it is possible for this flag to be present in the event |
| 14986 |
of referral, it would generally be of little interest to the |
| 14987 |
client, since the client is not expected to have information |
| 14988 |
regarding the current contents of the absent file system. |
| 14989 |
|
| 14990 |
The transport-flag field (at byte index FSLI4BX_TFLAGS) contains the |
| 14991 |
following bits related to the transport capabilities of the specific |
| 14992 |
file system. |
| 14993 |
|
| 14994 |
o FSLI4TF_RDMA indicates that this file system provides NFSv4.1 file |
| 14995 |
system access using an RDMA-capable transport. |
| 14996 |
|
| 14997 |
Attribute continuity and file system identity information are |
| 14998 |
expressed by defining equivalence relations on the sets of file |
| 14999 |
systems presented to the client. Each such relation is expressed as |
| 15000 |
a set of file system equivalence classes. For each relation, a file |
| 15001 |
|
| 15002 |
|
| 15003 |
|
| 15004 |
<span class="grey">Shepler, et al. Standards Track [Page 268]</span></pre> |
| 15005 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-269" ></span> |
| 15006 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15007 |
|
| 15008 |
|
| 15009 |
system has an 8-bit class number. Two file systems belong to the |
| 15010 |
same class if both have identical non-zero class numbers. Zero is |
| 15011 |
treated as non-matching. Most often, the relevant question for the |
| 15012 |
client will be whether a given replica is identical to / continuous |
| 15013 |
with the current one in a given respect, but the information should |
| 15014 |
be available also as to whether two other replicas match in that |
| 15015 |
respect as well. |
| 15016 |
|
| 15017 |
The following fields specify the file system's class numbers for the |
| 15018 |
equivalence relations used in determining the nature of file system |
| 15019 |
transitions. See <a href="#section-11.7">Section 11.7</a> and its various subsections for |
| 15020 |
details about how this information is to be used. Servers may assign |
| 15021 |
these values as they wish, so long as file system instances that |
| 15022 |
share the same value have the specified relationship to one another; |
| 15023 |
conversely, file systems that have the specified relationship to one |
| 15024 |
another share a common class value. As each instance entry is added, |
| 15025 |
the relationships of this instance to previously entered instances |
| 15026 |
can be consulted, and if one is found that bears the specified |
| 15027 |
relationship, that entry's class value can be copied to the new |
| 15028 |
entry. When no such previous entry exists, a new value for that byte |
| 15029 |
index (not previously used) can be selected, most likely by |
| 15030 |
incrementing the value of the last class value assigned for that |
| 15031 |
index. |
| 15032 |
|
| 15033 |
o The field with byte index FSLI4BX_CLSIMUL defines the |
| 15034 |
simultaneous-use class for the file system. |
| 15035 |
|
| 15036 |
o The field with byte index FSLI4BX_CLHANDLE defines the handle |
| 15037 |
class for the file system. |
| 15038 |
|
| 15039 |
o The field with byte index FSLI4BX_CLFILEID defines the fileid |
| 15040 |
class for the file system. |
| 15041 |
|
| 15042 |
o The field with byte index FSLI4BX_CLWRITEVER defines the write- |
| 15043 |
verifier class for the file system. |
| 15044 |
|
| 15045 |
o The field with byte index FSLI4BX_CLCHANGE defines the change |
| 15046 |
class for the file system. |
| 15047 |
|
| 15048 |
o The field with byte index FSLI4BX_CLREADDIR defines the readdir |
| 15049 |
class for the file system. |
| 15050 |
|
| 15051 |
Server-specified preference information is also provided via 8-bit |
| 15052 |
values within the fls_info array. The values provide a rank and an |
| 15053 |
order (see below) to be used with separate values specifiable for the |
| 15054 |
cases of read-only and writable file systems. These values are |
| 15055 |
compared for different file systems to establish the server-specified |
| 15056 |
preference, with lower values indicating "more preferred". |
| 15057 |
|
| 15058 |
|
| 15059 |
|
| 15060 |
<span class="grey">Shepler, et al. Standards Track [Page 269]</span></pre> |
| 15061 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-270" ></span> |
| 15062 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15063 |
|
| 15064 |
|
| 15065 |
Rank is used to express a strict server-imposed ordering on clients, |
| 15066 |
with lower values indicating "more preferred". Clients should |
| 15067 |
attempt to use all replicas with a given rank before they use one |
| 15068 |
with a higher rank. Only if all of those file systems are |
| 15069 |
unavailable should the client proceed to those of a higher rank. |
| 15070 |
Because specifying a rank will override client preferences, servers |
| 15071 |
should be conservative about using this mechanism, particularly when |
| 15072 |
the environment is one in which client communication characteristics |
| 15073 |
are neither tightly controlled nor visible to the server. |
| 15074 |
|
| 15075 |
Within a rank, the order value is used to specify the server's |
| 15076 |
preference to guide the client's selection when the client's own |
| 15077 |
preferences are not controlling, with lower values of order |
| 15078 |
indicating "more preferred". If replicas are approximately equal in |
| 15079 |
all respects, clients should defer to the order specified by the |
| 15080 |
server. When clients look at server latency as part of their |
| 15081 |
selection, they are free to use this criterion but it is suggested |
| 15082 |
that when latency differences are not significant, the server- |
| 15083 |
specified order should guide selection. |
| 15084 |
|
| 15085 |
o The field at byte index FSLI4BX_READRANK gives the rank value to |
| 15086 |
be used for read-only access. |
| 15087 |
|
| 15088 |
o The field at byte index FSLI4BX_READORDER gives the order value to |
| 15089 |
be used for read-only access. |
| 15090 |
|
| 15091 |
o The field at byte index FSLI4BX_WRITERANK gives the rank value to |
| 15092 |
be used for writable access. |
| 15093 |
|
| 15094 |
o The field at byte index FSLI4BX_WRITEORDER gives the order value |
| 15095 |
to be used for writable access. |
| 15096 |
|
| 15097 |
Depending on the potential need for write access by a given client, |
| 15098 |
one of the pairs of rank and order values is used. The read rank and |
| 15099 |
order should only be used if the client knows that only reading will |
| 15100 |
ever be done or if it is prepared to switch to a different replica in |
| 15101 |
the event that any write access capability is required in the future. |
| 15102 |
|
| 15103 |
<span class="h4"><a class="selflink" id="section-11.10.2" href="#section-11.10.2">11.10.2</a>. The fs_locations_info4 Structure</span> |
| 15104 |
|
| 15105 |
The fs_locations_info4 structure, encoding the fs_locations_info |
| 15106 |
attribute, contains the following: |
| 15107 |
|
| 15108 |
o The fli_flags field, which contains general flags that affect the |
| 15109 |
interpretation of this fs_locations_info4 structure and all |
| 15110 |
fs_locations_item4 structures within it. The only flag currently |
| 15111 |
defined is FSLI4IF_VAR_SUB. All bits in the fli_flags field that |
| 15112 |
are not defined should always be returned as zero. |
| 15113 |
|
| 15114 |
|
| 15115 |
|
| 15116 |
<span class="grey">Shepler, et al. Standards Track [Page 270]</span></pre> |
| 15117 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-271" ></span> |
| 15118 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15119 |
|
| 15120 |
|
| 15121 |
o The fli_fs_root field, which contains the pathname of the root of |
| 15122 |
the current file system on the current server, just as it does in |
| 15123 |
the fs_locations4 structure. |
| 15124 |
|
| 15125 |
o An array called fli_items of fs_locations4_item structures, which |
| 15126 |
contain information about replicas of the current file system. |
| 15127 |
Where the current file system is actually present, or has been |
| 15128 |
present, i.e., this is not a referral situation, one of the |
| 15129 |
fs_locations_item4 structures will contain an fs_locations_server4 |
| 15130 |
for the current server. This structure will have FSLI4GF_ABSENT |
| 15131 |
set if the current file system is absent, i.e., normal access to |
| 15132 |
it will return NFS4ERR_MOVED. |
| 15133 |
|
| 15134 |
o The fli_valid_for field specifies a time in seconds for which it |
| 15135 |
is reasonable for a client to use the fs_locations_info attribute |
| 15136 |
without refetch. The fli_valid_for value does not provide a |
| 15137 |
guarantee of validity since servers can unexpectedly go out of |
| 15138 |
service or become inaccessible for any number of reasons. Clients |
| 15139 |
are well-advised to refetch this information for an actively |
| 15140 |
accessed file system at every fli_valid_for seconds. This is |
| 15141 |
particularly important when file system replicas may go out of |
| 15142 |
service in a controlled way using the FSLI4GF_GOING flag to |
| 15143 |
communicate an ongoing change. The server should set |
| 15144 |
fli_valid_for to a value that allows well-behaved clients to |
| 15145 |
notice the FSLI4GF_GOING flag and make an orderly switch before |
| 15146 |
the loss of service becomes effective. If this value is zero, |
| 15147 |
then no refetch interval is appropriate and the client need not |
| 15148 |
refetch this data on any particular schedule. In the event of a |
| 15149 |
transition to a new file system instance, a new value of the |
| 15150 |
fs_locations_info attribute will be fetched at the destination. |
| 15151 |
It is to be expected that this may have a different fli_valid_for |
| 15152 |
value, which the client should then use in the same fashion as the |
| 15153 |
previous value. |
| 15154 |
|
| 15155 |
The FSLI4IF_VAR_SUB flag within fli_flags controls whether variable |
| 15156 |
substitution is to be enabled. See <a href="#section-11.10.3">Section 11.10.3</a> for an |
| 15157 |
explanation of variable substitution. |
| 15158 |
|
| 15159 |
<span class="h4"><a class="selflink" id="section-11.10.3" href="#section-11.10.3">11.10.3</a>. The fs_locations_item4 Structure</span> |
| 15160 |
|
| 15161 |
The fs_locations_item4 structure contains a pathname (in the field |
| 15162 |
fli_rootpath) that encodes the path of the target file system |
| 15163 |
replicas on the set of servers designated by the included |
| 15164 |
fs_locations_server4 entries. The precise manner in which this |
| 15165 |
target location is specified depends on the value of the |
| 15166 |
FSLI4IF_VAR_SUB flag within the associated fs_locations_info4 |
| 15167 |
structure. |
| 15168 |
|
| 15169 |
|
| 15170 |
|
| 15171 |
|
| 15172 |
<span class="grey">Shepler, et al. Standards Track [Page 271]</span></pre> |
| 15173 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-272" ></span> |
| 15174 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15175 |
|
| 15176 |
|
| 15177 |
If this flag is not set, then fli_rootpath simply designates the |
| 15178 |
location of the target file system within each server's single-server |
| 15179 |
namespace just as it does for the rootpath within the fs_location4 |
| 15180 |
structure. When this bit is set, however, component entries of a |
| 15181 |
certain form are subject to client-specific variable substitution so |
| 15182 |
as to allow a degree of namespace non-uniformity in order to |
| 15183 |
accommodate the selection of client-specific file system targets to |
| 15184 |
adapt to different client architectures or other characteristics. |
| 15185 |
|
| 15186 |
When such substitution is in effect, a variable beginning with the |
| 15187 |
string "${" and ending with the string "}" and containing a colon is |
| 15188 |
to be replaced by the client-specific value associated with that |
| 15189 |
variable. The string "unknown" should be used by the client when it |
| 15190 |
has no value for such a variable. The pathname resulting from such |
| 15191 |
substitutions is used to designate the target file system, so that |
| 15192 |
different clients may have different file systems, corresponding to |
| 15193 |
that location in the multi-server namespace. |
| 15194 |
|
| 15195 |
As mentioned above, such substituted pathname variables contain a |
| 15196 |
colon. The part before the colon is to be a DNS domain name, and the |
| 15197 |
part after is to be a case-insensitive alphanumeric string. |
| 15198 |
|
| 15199 |
Where the domain is "ietf.org", only variable names defined in this |
| 15200 |
document or subsequent Standards Track RFCs are subject to such |
| 15201 |
substitution. Organizations are free to use their domain names to |
| 15202 |
create their own sets of client-specific variables, to be subject to |
| 15203 |
such substitution. In cases where such variables are intended to be |
| 15204 |
used more broadly than a single organization, publication of an |
| 15205 |
Informational RFC defining such variables is RECOMMENDED. |
| 15206 |
|
| 15207 |
The variable ${ietf.org:CPU_ARCH} is used to denote that the CPU |
| 15208 |
architecture object files are compiled. This specification does not |
| 15209 |
limit the acceptable values (except that they must be valid UTF-8 |
| 15210 |
strings), but such values as "x86", "x86_64", and "sparc" would be |
| 15211 |
expected to be used in line with industry practice. |
| 15212 |
|
| 15213 |
The variable ${ietf.org:OS_TYPE} is used to denote the operating |
| 15214 |
system, and thus the kernel and library APIs, for which code might be |
| 15215 |
compiled. This specification does not limit the acceptable values |
| 15216 |
(except that they must be valid UTF-8 strings), but such values as |
| 15217 |
"linux" and "freebsd" would be expected to be used in line with |
| 15218 |
industry practice. |
| 15219 |
|
| 15220 |
The variable ${ietf.org:OS_VERSION} is used to denote the operating |
| 15221 |
system version, and thus the specific details of versioned |
| 15222 |
interfaces, for which code might be compiled. This specification |
| 15223 |
does not limit the acceptable values (except that they must be valid |
| 15224 |
UTF-8 strings). However, combinations of numbers and letters with |
| 15225 |
|
| 15226 |
|
| 15227 |
|
| 15228 |
<span class="grey">Shepler, et al. Standards Track [Page 272]</span></pre> |
| 15229 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-273" ></span> |
| 15230 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15231 |
|
| 15232 |
|
| 15233 |
interspersed dots would be expected to be used in line with industry |
| 15234 |
practice, with the details of the version format depending on the |
| 15235 |
specific value of the variable ${ietf.org:OS_TYPE} with which it is |
| 15236 |
used. |
| 15237 |
|
| 15238 |
Use of these variables could result in the direction of different |
| 15239 |
clients to different file systems on the same server, as appropriate |
| 15240 |
to particular clients. In cases in which the target file systems are |
| 15241 |
located on different servers, a single server could serve as a |
| 15242 |
referral point so that each valid combination of variable values |
| 15243 |
would designate a referral hosted on a single server, with the |
| 15244 |
targets of those referrals on a number of different servers. |
| 15245 |
|
| 15246 |
Because namespace administration is affected by the values selected |
| 15247 |
to substitute for various variables, clients should provide |
| 15248 |
convenient means of determining what variable substitutions a client |
| 15249 |
will implement, as well as, where appropriate, providing means to |
| 15250 |
control the substitutions to be used. The exact means by which this |
| 15251 |
will be done is outside the scope of this specification. |
| 15252 |
|
| 15253 |
Although variable substitution is most suitable for use in the |
| 15254 |
context of referrals, it may be used in the context of replication |
| 15255 |
and migration. If it is used in these contexts, the server must |
| 15256 |
ensure that no matter what values the client presents for the |
| 15257 |
substituted variables, the result is always a valid successor file |
| 15258 |
system instance to that from which a transition is occurring, i.e., |
| 15259 |
that the data is identical or represents a later image of a writable |
| 15260 |
file system. |
| 15261 |
|
| 15262 |
Note that when fli_rootpath is a null pathname (that is, one with |
| 15263 |
zero components), the file system designated is at the root of the |
| 15264 |
specified server, whether or not the FSLI4IF_VAR_SUB flag within the |
| 15265 |
associated fs_locations_info4 structure is set. |
| 15266 |
|
| 15267 |
<span class="h3"><a class="selflink" id="section-11.11" href="#section-11.11">11.11</a>. The Attribute fs_status</span> |
| 15268 |
|
| 15269 |
In an environment in which multiple copies of the same basic set of |
| 15270 |
data are available, information regarding the particular source of |
| 15271 |
such data and the relationships among different copies can be very |
| 15272 |
helpful in providing consistent data to applications. |
| 15273 |
|
| 15274 |
enum fs4_status_type { |
| 15275 |
STATUS4_FIXED = 1, |
| 15276 |
STATUS4_UPDATED = 2, |
| 15277 |
STATUS4_VERSIONED = 3, |
| 15278 |
STATUS4_WRITABLE = 4, |
| 15279 |
STATUS4_REFERRAL = 5 |
| 15280 |
}; |
| 15281 |
|
| 15282 |
|
| 15283 |
|
| 15284 |
<span class="grey">Shepler, et al. Standards Track [Page 273]</span></pre> |
| 15285 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-274" ></span> |
| 15286 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15287 |
|
| 15288 |
|
| 15289 |
struct fs4_status { |
| 15290 |
bool fss_absent; |
| 15291 |
fs4_status_type fss_type; |
| 15292 |
utf8str_cs fss_source; |
| 15293 |
utf8str_cs fss_current; |
| 15294 |
int32_t fss_age; |
| 15295 |
nfstime4 fss_version; |
| 15296 |
}; |
| 15297 |
|
| 15298 |
The boolean fss_absent indicates whether the file system is currently |
| 15299 |
absent. This value will be set if the file system was previously |
| 15300 |
present and becomes absent, or if the file system has never been |
| 15301 |
present and the type is STATUS4_REFERRAL. When this boolean is set |
| 15302 |
and the type is not STATUS4_REFERRAL, the remaining information in |
| 15303 |
the fs4_status reflects that last valid when the file system was |
| 15304 |
present. |
| 15305 |
|
| 15306 |
The fss_type field indicates the kind of file system image |
| 15307 |
represented. This is of particular importance when using the version |
| 15308 |
values to determine appropriate succession of file system images. |
| 15309 |
When fss_absent is set, and the file system was previously present, |
| 15310 |
the value of fss_type reflected is that when the file was last |
| 15311 |
present. Five values are distinguished: |
| 15312 |
|
| 15313 |
o STATUS4_FIXED, which indicates a read-only image in the sense that |
| 15314 |
it will never change. The possibility is allowed that, as a |
| 15315 |
result of migration or switch to a different image, changed data |
| 15316 |
can be accessed, but within the confines of this instance, no |
| 15317 |
change is allowed. The client can use this fact to cache |
| 15318 |
aggressively. |
| 15319 |
|
| 15320 |
o STATUS4_VERSIONED, which indicates that the image, like the |
| 15321 |
STATUS4_UPDATED case, is updated externally, but it provides a |
| 15322 |
guarantee that the server will carefully update an associated |
| 15323 |
version value so that the client can protect itself from a |
| 15324 |
situation in which it reads data from one version of the file |
| 15325 |
system and then later reads data from an earlier version of the |
| 15326 |
same file system. See below for a discussion of how this can be |
| 15327 |
done. |
| 15328 |
|
| 15329 |
o STATUS4_UPDATED, which indicates an image that cannot be updated |
| 15330 |
by the user writing to it but that may be changed externally, |
| 15331 |
typically because it is a periodically updated copy of another |
| 15332 |
writable file system somewhere else. In this case, version |
| 15333 |
information is not provided, and the client does not have the |
| 15334 |
responsibility of making sure that this version only advances upon |
| 15335 |
a file system instance transition. In this case, it is the |
| 15336 |
responsibility of the server to make sure that the data presented |
| 15337 |
|
| 15338 |
|
| 15339 |
|
| 15340 |
<span class="grey">Shepler, et al. Standards Track [Page 274]</span></pre> |
| 15341 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-275" ></span> |
| 15342 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15343 |
|
| 15344 |
|
| 15345 |
after a file system instance transition is a proper successor |
| 15346 |
image and includes all changes seen by the client and any change |
| 15347 |
made before all such changes. |
| 15348 |
|
| 15349 |
o STATUS4_WRITABLE, which indicates that the file system is an |
| 15350 |
actual writable one. The client need not, of course, actually |
| 15351 |
write to the file system, but once it does, it should not accept a |
| 15352 |
transition to anything other than a writable instance of that same |
| 15353 |
file system. |
| 15354 |
|
| 15355 |
o STATUS4_REFERRAL, which indicates that the file system in question |
| 15356 |
is absent and has never been present on this server. |
| 15357 |
|
| 15358 |
Note that in the STATUS4_UPDATED and STATUS4_VERSIONED cases, the |
| 15359 |
server is responsible for the appropriate handling of locks that are |
| 15360 |
inconsistent with external changes to delegations. If a server gives |
| 15361 |
out delegations, they SHOULD be recalled before an inconsistent |
| 15362 |
change is made to the data, and MUST be revoked if this is not |
| 15363 |
possible. Similarly, if an OPEN is inconsistent with data that is |
| 15364 |
changed (the OPEN has OPEN4_SHARE_DENY_WRITE/OPEN4_SHARE_DENY_BOTH |
| 15365 |
and the data is changed), that OPEN SHOULD be considered |
| 15366 |
administratively revoked. |
| 15367 |
|
| 15368 |
The opaque strings fss_source and fss_current provide a way of |
| 15369 |
presenting information about the source of the file system image |
| 15370 |
being present. It is not intended that the client do anything with |
| 15371 |
this information other than make it available to administrative |
| 15372 |
tools. It is intended that this information be helpful when |
| 15373 |
researching possible problems with a file system image that might |
| 15374 |
arise when it is unclear if the correct image is being accessed and, |
| 15375 |
if not, how that image came to be made. This kind of diagnostic |
| 15376 |
information will be helpful, if, as seems likely, copies of file |
| 15377 |
systems are made in many different ways (e.g., simple user-level |
| 15378 |
copies, file-system-level point-in-time copies, clones of the |
| 15379 |
underlying storage), under a variety of administrative arrangements. |
| 15380 |
In such environments, determining how a given set of data was |
| 15381 |
constructed can be very helpful in resolving problems. |
| 15382 |
|
| 15383 |
The opaque string fss_source is used to indicate the source of a |
| 15384 |
given file system with the expectation that tools capable of creating |
| 15385 |
a file system image propagate this information, when possible. It is |
| 15386 |
understood that this may not always be possible since a user-level |
| 15387 |
copy may be thought of as creating a new data set and the tools used |
| 15388 |
may have no mechanism to propagate this data. When a file system is |
| 15389 |
initially created, it is desirable to associate with it data |
| 15390 |
regarding how the file system was created, where it was created, who |
| 15391 |
created it, etc. Making this information available in this attribute |
| 15392 |
|
| 15393 |
|
| 15394 |
|
| 15395 |
|
| 15396 |
<span class="grey">Shepler, et al. Standards Track [Page 275]</span></pre> |
| 15397 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-276" ></span> |
| 15398 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15399 |
|
| 15400 |
|
| 15401 |
in a human-readable string will be helpful for applications and |
| 15402 |
system administrators and will also serve to make it available when |
| 15403 |
the original file system is used to make subsequent copies. |
| 15404 |
|
| 15405 |
The opaque string fss_current should provide whatever information is |
| 15406 |
available about the source of the current copy. Such information |
| 15407 |
includes the tool creating it, any relevant parameters to that tool, |
| 15408 |
the time at which the copy was done, the user making the change, the |
| 15409 |
server on which the change was made, etc. All information should be |
| 15410 |
in a human-readable string. |
| 15411 |
|
| 15412 |
The field fss_age provides an indication of how out-of-date the file |
| 15413 |
system currently is with respect to its ultimate data source (in case |
| 15414 |
of cascading data updates). This complements the fls_currency field |
| 15415 |
of fs_locations_server4 (see <a href="#section-11.10">Section 11.10</a>) in the following way: the |
| 15416 |
information in fls_currency gives a bound for how out of date the |
| 15417 |
data in a file system might typically get, while the value in fss_age |
| 15418 |
gives a bound on how out-of-date that data actually is. Negative |
| 15419 |
values imply that no information is available. A zero means that |
| 15420 |
this data is known to be current. A positive value means that this |
| 15421 |
data is known to be no older than that number of seconds with respect |
| 15422 |
to the ultimate data source. Using this value, the client may be |
| 15423 |
able to decide that a data copy is too old, so that it may search for |
| 15424 |
a newer version to use. |
| 15425 |
|
| 15426 |
The fss_version field provides a version identification, in the form |
| 15427 |
of a time value, such that successive versions always have later time |
| 15428 |
values. When the fs_type is anything other than STATUS4_VERSIONED, |
| 15429 |
the server may provide such a value, but there is no guarantee as to |
| 15430 |
its validity and clients will not use it except to provide additional |
| 15431 |
information to add to fss_source and fss_current. |
| 15432 |
|
| 15433 |
When fss_type is STATUS4_VERSIONED, servers SHOULD provide a value of |
| 15434 |
fss_version that progresses monotonically whenever any new version of |
| 15435 |
the data is established. This allows the client, if reliable image |
| 15436 |
progression is important to it, to fetch this attribute as part of |
| 15437 |
each COMPOUND where data or metadata from the file system is used. |
| 15438 |
|
| 15439 |
When it is important to the client to make sure that only valid |
| 15440 |
successor images are accepted, it must make sure that it does not |
| 15441 |
read data or metadata from the file system without updating its sense |
| 15442 |
of the current state of the image. This is to avoid the possibility |
| 15443 |
that the fs_status that the client holds will be one for an earlier |
| 15444 |
image, which would cause the client to accept a new file system |
| 15445 |
instance that is later than that but still earlier than the updated |
| 15446 |
data read by the client. |
| 15447 |
|
| 15448 |
|
| 15449 |
|
| 15450 |
|
| 15451 |
|
| 15452 |
<span class="grey">Shepler, et al. Standards Track [Page 276]</span></pre> |
| 15453 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-277" ></span> |
| 15454 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15455 |
|
| 15456 |
|
| 15457 |
In order to accept valid images reliably, the client must do a |
| 15458 |
GETATTR of the fs_status attribute that follows any interrogation of |
| 15459 |
data or metadata within the file system in question. Often this is |
| 15460 |
most conveniently done by appending such a GETATTR after all other |
| 15461 |
operations that reference a given file system. When errors occur |
| 15462 |
between reading file system data and performing such a GETATTR, care |
| 15463 |
must be exercised to make sure that the data in question is not used |
| 15464 |
before obtaining the proper fs_status value. In this connection, |
| 15465 |
when an OPEN is done within such a versioned file system and the |
| 15466 |
associated GETATTR of fs_status is not successfully completed, the |
| 15467 |
open file in question must not be accessed until that fs_status is |
| 15468 |
fetched. |
| 15469 |
|
| 15470 |
The procedure above will ensure that before using any data from the |
| 15471 |
file system the client has in hand a newly-fetched current version of |
| 15472 |
the file system image. Multiple values for multiple requests in |
| 15473 |
flight can be resolved by assembling them into the required partial |
| 15474 |
order (and the elements should form a total order within the partial |
| 15475 |
order) and using the last. The client may then, when switching among |
| 15476 |
file system instances, decline to use an instance that does not have |
| 15477 |
an fss_type of STATUS4_VERSIONED or whose fss_version field is |
| 15478 |
earlier than the last one obtained from the predecessor file system |
| 15479 |
instance. |
| 15480 |
|
| 15481 |
<span class="h2"><a class="selflink" id="section-12" href="#section-12">12</a>. Parallel NFS (pNFS)</span> |
| 15482 |
|
| 15483 |
<span class="h3"><a class="selflink" id="section-12.1" href="#section-12.1">12.1</a>. Introduction</span> |
| 15484 |
|
| 15485 |
pNFS is an OPTIONAL feature within NFSv4.1; the pNFS feature set |
| 15486 |
allows direct client access to the storage devices containing file |
| 15487 |
data. When file data for a single NFSv4 server is stored on multiple |
| 15488 |
and/or higher-throughput storage devices (by comparison to the |
| 15489 |
server's throughput capability), the result can be significantly |
| 15490 |
better file access performance. The relationship among multiple |
| 15491 |
clients, a single server, and multiple storage devices for pNFS |
| 15492 |
(server and clients have access to all storage devices) is shown in |
| 15493 |
Figure 1. |
| 15494 |
|
| 15495 |
|
| 15496 |
|
| 15497 |
|
| 15498 |
|
| 15499 |
|
| 15500 |
|
| 15501 |
|
| 15502 |
|
| 15503 |
|
| 15504 |
|
| 15505 |
|
| 15506 |
|
| 15507 |
|
| 15508 |
<span class="grey">Shepler, et al. Standards Track [Page 277]</span></pre> |
| 15509 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-278" ></span> |
| 15510 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15511 |
|
| 15512 |
|
| 15513 |
+-----------+ |
| 15514 |
|+-----------+ +-----------+ |
| 15515 |
||+-----------+ | | |
| 15516 |
||| | NFSv4.1 + pNFS | | |
| 15517 |
+|| Clients |<------------------------------>| Server | |
| 15518 |
+| | | | |
| 15519 |
+-----------+ | | |
| 15520 |
||| +-----------+ |
| 15521 |
||| | |
| 15522 |
||| | |
| 15523 |
||| Storage +-----------+ | |
| 15524 |
||| Protocol |+-----------+ | |
| 15525 |
||+----------------||+-----------+ Control | |
| 15526 |
|+-----------------||| | Protocol| |
| 15527 |
+------------------+|| Storage |------------+ |
| 15528 |
+| Devices | |
| 15529 |
+-----------+ |
| 15530 |
|
| 15531 |
Figure 1 |
| 15532 |
|
| 15533 |
In this model, the clients, server, and storage devices are |
| 15534 |
responsible for managing file access. This is in contrast to NFSv4 |
| 15535 |
without pNFS, where it is primarily the server's responsibility; some |
| 15536 |
of this responsibility may be delegated to the client under strictly |
| 15537 |
specified conditions. See <a href="#section-12.2.5">Section 12.2.5</a> for a discussion of the |
| 15538 |
Storage Protocol. See <a href="#section-12.2.6">Section 12.2.6</a> for a discussion of the Control |
| 15539 |
Protocol. |
| 15540 |
|
| 15541 |
pNFS takes the form of OPTIONAL operations that manage protocol |
| 15542 |
objects called 'layouts' (<a href="#section-12.2.7">Section 12.2.7</a>) that contain a byte-range |
| 15543 |
and storage location information. The layout is managed in a similar |
| 15544 |
fashion as NFSv4.1 data delegations. For example, the layout is |
| 15545 |
leased, recallable, and revocable. However, layouts are distinct |
| 15546 |
abstractions and are manipulated with new operations. When a client |
| 15547 |
holds a layout, it is granted the ability to directly access the |
| 15548 |
byte-range at the storage location specified in the layout. |
| 15549 |
|
| 15550 |
There are interactions between layouts and other NFSv4.1 abstractions |
| 15551 |
such as data delegations and byte-range locking. Delegation issues |
| 15552 |
are discussed in <a href="#section-12.5.5">Section 12.5.5</a>. Byte-range locking issues are |
| 15553 |
discussed in Sections <a href="#section-12.2.9">12.2.9</a> and <a href="#section-12.5.1">12.5.1</a>. |
| 15554 |
|
| 15555 |
<span class="h3"><a class="selflink" id="section-12.2" href="#section-12.2">12.2</a>. pNFS Definitions</span> |
| 15556 |
|
| 15557 |
NFSv4.1's pNFS feature provides parallel data access to a file system |
| 15558 |
that stripes its content across multiple storage servers. The first |
| 15559 |
instantiation of pNFS, as part of NFSv4.1, separates the file system |
| 15560 |
protocol processing into two parts: metadata processing and data |
| 15561 |
|
| 15562 |
|
| 15563 |
|
| 15564 |
<span class="grey">Shepler, et al. Standards Track [Page 278]</span></pre> |
| 15565 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-279" ></span> |
| 15566 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15567 |
|
| 15568 |
|
| 15569 |
processing. Data consist of the contents of regular files that are |
| 15570 |
striped across storage servers. Data striping occurs in at least two |
| 15571 |
ways: on a file-by-file basis and, within sufficiently large files, |
| 15572 |
on a block-by-block basis. In contrast, striped access to metadata |
| 15573 |
by pNFS clients is not provided in NFSv4.1, even though the file |
| 15574 |
system back end of a pNFS server might stripe metadata. Metadata |
| 15575 |
consist of everything else, including the contents of non-regular |
| 15576 |
files (e.g., directories); see <a href="#section-12.2.1">Section 12.2.1</a>. The metadata |
| 15577 |
functionality is implemented by an NFSv4.1 server that supports pNFS |
| 15578 |
and the operations described in <a href="#section-18">Section 18</a>; such a server is called a |
| 15579 |
metadata server (<a href="#section-12.2.2">Section 12.2.2</a>). |
| 15580 |
|
| 15581 |
The data functionality is implemented by one or more storage devices, |
| 15582 |
each of which are accessed by the client via a storage protocol. A |
| 15583 |
subset (defined in <a href="#section-13.6">Section 13.6</a>) of NFSv4.1 is one such storage |
| 15584 |
protocol. New terms are introduced to the NFSv4.1 nomenclature and |
| 15585 |
existing terms are clarified to allow for the description of the pNFS |
| 15586 |
feature. |
| 15587 |
|
| 15588 |
<span class="h4"><a class="selflink" id="section-12.2.1" href="#section-12.2.1">12.2.1</a>. Metadata</span> |
| 15589 |
|
| 15590 |
Information about a file system object, such as its name, location |
| 15591 |
within the namespace, owner, ACL, and other attributes. Metadata may |
| 15592 |
also include storage location information, and this will vary based |
| 15593 |
on the underlying storage mechanism that is used. |
| 15594 |
|
| 15595 |
<span class="h4"><a class="selflink" id="section-12.2.2" href="#section-12.2.2">12.2.2</a>. Metadata Server</span> |
| 15596 |
|
| 15597 |
An NFSv4.1 server that supports the pNFS feature. A variety of |
| 15598 |
architectural choices exist for the metadata server and its use of |
| 15599 |
file system information held at the server. Some servers may contain |
| 15600 |
metadata only for file objects residing at the metadata server, while |
| 15601 |
the file data resides on associated storage devices. Other metadata |
| 15602 |
servers may hold both metadata and a varying degree of file data. |
| 15603 |
|
| 15604 |
<span class="h4"><a class="selflink" id="section-12.2.3" href="#section-12.2.3">12.2.3</a>. pNFS Client</span> |
| 15605 |
|
| 15606 |
An NFSv4.1 client that supports pNFS operations and supports at least |
| 15607 |
one storage protocol for performing I/O to storage devices. |
| 15608 |
|
| 15609 |
<span class="h4"><a class="selflink" id="section-12.2.4" href="#section-12.2.4">12.2.4</a>. Storage Device</span> |
| 15610 |
|
| 15611 |
A storage device stores a regular file's data, but leaves metadata |
| 15612 |
management to the metadata server. A storage device could be another |
| 15613 |
NFSv4.1 server, an object-based storage device (OSD), a block device |
| 15614 |
accessed over a System Area Network (SAN, e.g., either FiberChannel |
| 15615 |
or iSCSI SAN), or some other entity. |
| 15616 |
|
| 15617 |
|
| 15618 |
|
| 15619 |
|
| 15620 |
<span class="grey">Shepler, et al. Standards Track [Page 279]</span></pre> |
| 15621 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-280" ></span> |
| 15622 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15623 |
|
| 15624 |
|
| 15625 |
<span class="h4"><a class="selflink" id="section-12.2.5" href="#section-12.2.5">12.2.5</a>. Storage Protocol</span> |
| 15626 |
|
| 15627 |
As noted in Figure 1, the storage protocol is the method used by the |
| 15628 |
client to store and retrieve data directly from the storage devices. |
| 15629 |
|
| 15630 |
The NFSv4.1 pNFS feature has been structured to allow for a variety |
| 15631 |
of storage protocols to be defined and used. One example storage |
| 15632 |
protocol is NFSv4.1 itself (as documented in <a href="#section-13">Section 13</a>). Other |
| 15633 |
options for the storage protocol are described elsewhere and include: |
| 15634 |
|
| 15635 |
o Block/volume protocols such as Internet SCSI (iSCSI) [<a href="#ref-48" title=""Internet Small Computer Systems Interface (iSCSI)"">48</a>] and FCP |
| 15636 |
[<a href="#ref-49" title=""Fibre Channel Protocol for SCSI, 2nd Version (FCP-2)"">49</a>]. The block/volume protocol support can be independent of the |
| 15637 |
addressing structure of the block/volume protocol used, allowing |
| 15638 |
more than one protocol to access the same file data and enabling |
| 15639 |
extensibility to other block/volume protocols. See [<a href="#ref-41" title=""Parallel NFS (pNFS) Block/Volume Layout"">41</a>] for a |
| 15640 |
layout specification that allows pNFS to use block/volume storage |
| 15641 |
protocols. |
| 15642 |
|
| 15643 |
o Object protocols such as OSD over iSCSI or Fibre Channel [<a href="#ref-50" title=""Object-Based Storage Device Commands (OSD)"">50</a>]. |
| 15644 |
See [<a href="#ref-40" title=""Object-Based Parallel NFS (pNFS) Operations"">40</a>] for a layout specification that allows pNFS to use object |
| 15645 |
storage protocols. |
| 15646 |
|
| 15647 |
It is possible that various storage protocols are available to both |
| 15648 |
client and server and it may be possible that a client and server do |
| 15649 |
not have a matching storage protocol available to them. Because of |
| 15650 |
this, the pNFS server MUST support normal NFSv4.1 access to any file |
| 15651 |
accessible by the pNFS feature; this will allow for continued |
| 15652 |
interoperability between an NFSv4.1 client and server. |
| 15653 |
|
| 15654 |
<span class="h4"><a class="selflink" id="section-12.2.6" href="#section-12.2.6">12.2.6</a>. Control Protocol</span> |
| 15655 |
|
| 15656 |
As noted in Figure 1, the control protocol is used by the exported |
| 15657 |
file system between the metadata server and storage devices. |
| 15658 |
Specification of such protocols is outside the scope of the NFSv4.1 |
| 15659 |
protocol. Such control protocols would be used to control activities |
| 15660 |
such as the allocation and deallocation of storage, the management of |
| 15661 |
state required by the storage devices to perform client access |
| 15662 |
control, and, depending on the storage protocol, the enforcement of |
| 15663 |
authentication and authorization so that restrictions that would be |
| 15664 |
enforced by the metadata server are also enforced by the storage |
| 15665 |
device. |
| 15666 |
|
| 15667 |
A particular control protocol is not REQUIRED by NFSv4.1 but |
| 15668 |
requirements are placed on the control protocol for maintaining |
| 15669 |
attributes like modify time, the change attribute, and the end-of- |
| 15670 |
file (EOF) position. Note that if pNFS is layered over a clustered, |
| 15671 |
|
| 15672 |
|
| 15673 |
|
| 15674 |
|
| 15675 |
|
| 15676 |
<span class="grey">Shepler, et al. Standards Track [Page 280]</span></pre> |
| 15677 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-281" ></span> |
| 15678 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15679 |
|
| 15680 |
|
| 15681 |
parallel file system (e.g., PVFS [<a href="#ref-51" title=""PVFS: A Parallel File System for Linux Clusters."">51</a>]), the mechanisms that enable |
| 15682 |
clustering and parallelism in that file system can be considered the |
| 15683 |
control protocol. |
| 15684 |
|
| 15685 |
<span class="h4"><a class="selflink" id="section-12.2.7" href="#section-12.2.7">12.2.7</a>. Layout Types</span> |
| 15686 |
|
| 15687 |
A layout describes the mapping of a file's data to the storage |
| 15688 |
devices that hold the data. A layout is said to belong to a specific |
| 15689 |
layout type (data type layouttype4, see <a href="#section-3.3.13">Section 3.3.13</a>). The layout |
| 15690 |
type allows for variants to handle different storage protocols, such |
| 15691 |
as those associated with block/volume [<a href="#ref-41" title=""Parallel NFS (pNFS) Block/Volume Layout"">41</a>], object [<a href="#ref-40" title=""Object-Based Parallel NFS (pNFS) Operations"">40</a>], and file |
| 15692 |
(<a href="#section-13">Section 13</a>) layout types. A metadata server, along with its control |
| 15693 |
protocol, MUST support at least one layout type. A private sub-range |
| 15694 |
of the layout type namespace is also defined. Values from the |
| 15695 |
private layout type range MAY be used for internal testing or |
| 15696 |
experimentation (see <a href="#section-3.3.13">Section 3.3.13</a>). |
| 15697 |
|
| 15698 |
As an example, the organization of the file layout type could be an |
| 15699 |
array of tuples (e.g., device ID, filehandle), along with a |
| 15700 |
definition of how the data is stored across the devices (e.g., |
| 15701 |
striping). A block/volume layout might be an array of tuples that |
| 15702 |
store <device ID, block number, block count> along with information |
| 15703 |
about block size and the associated file offset of the block number. |
| 15704 |
An object layout might be an array of tuples <device ID, object ID> |
| 15705 |
and an additional structure (i.e., the aggregation map) that defines |
| 15706 |
how the logical byte sequence of the file data is serialized into the |
| 15707 |
different objects. Note that the actual layouts are typically more |
| 15708 |
complex than these simple expository examples. |
| 15709 |
|
| 15710 |
Requests for pNFS-related operations will often specify a layout |
| 15711 |
type. Examples of such operations are GETDEVICEINFO and LAYOUTGET. |
| 15712 |
The response for these operations will include structures such as a |
| 15713 |
device_addr4 or a layout4, each of which includes a layout type |
| 15714 |
within it. The layout type sent by the server MUST always be the |
| 15715 |
same one requested by the client. When a server sends a response |
| 15716 |
that includes a different layout type, the client SHOULD ignore the |
| 15717 |
response and behave as if the server had returned an error response. |
| 15718 |
|
| 15719 |
<span class="h4"><a class="selflink" id="section-12.2.8" href="#section-12.2.8">12.2.8</a>. Layout</span> |
| 15720 |
|
| 15721 |
A layout defines how a file's data is organized on one or more |
| 15722 |
storage devices. There are many potential layout types; each of the |
| 15723 |
layout types are differentiated by the storage protocol used to |
| 15724 |
access data and by the aggregation scheme that lays out the file data |
| 15725 |
on the underlying storage devices. A layout is precisely identified |
| 15726 |
by the tuple <client ID, filehandle, layout type, iomode, range>, |
| 15727 |
where filehandle refers to the filehandle of the file on the metadata |
| 15728 |
server. |
| 15729 |
|
| 15730 |
|
| 15731 |
|
| 15732 |
<span class="grey">Shepler, et al. Standards Track [Page 281]</span></pre> |
| 15733 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-282" ></span> |
| 15734 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15735 |
|
| 15736 |
|
| 15737 |
It is important to define when layouts overlap and/or conflict with |
| 15738 |
each other. For two layouts with overlapping byte-ranges to actually |
| 15739 |
overlap each other, both layouts must be of the same layout type, |
| 15740 |
correspond to the same filehandle, and have the same iomode. Layouts |
| 15741 |
conflict when they overlap and differ in the content of the layout |
| 15742 |
(i.e., the storage device/file mapping parameters differ). Note that |
| 15743 |
differing iomodes do not lead to conflicting layouts. It is |
| 15744 |
permissible for layouts with different iomodes, pertaining to the |
| 15745 |
same byte-range, to be held by the same client. An example of this |
| 15746 |
would be copy-on-write functionality for a block/volume layout type. |
| 15747 |
|
| 15748 |
<span class="h4"><a class="selflink" id="section-12.2.9" href="#section-12.2.9">12.2.9</a>. Layout Iomode</span> |
| 15749 |
|
| 15750 |
The layout iomode (data type layoutiomode4, see <a href="#section-3.3.20">Section 3.3.20</a>) |
| 15751 |
indicates to the metadata server the client's intent to perform |
| 15752 |
either just READ operations or a mixture containing READ and WRITE |
| 15753 |
operations. For certain layout types, it is useful for a client to |
| 15754 |
specify this intent at the time it sends LAYOUTGET (<a href="#section-18.43">Section 18.43</a>). |
| 15755 |
For example, for block/volume-based protocols, block allocation could |
| 15756 |
occur when a LAYOUTIOMODE4_RW iomode is specified. A special |
| 15757 |
LAYOUTIOMODE4_ANY iomode is defined and can only be used for |
| 15758 |
LAYOUTRETURN and CB_LAYOUTRECALL, not for LAYOUTGET. It specifies |
| 15759 |
that layouts pertaining to both LAYOUTIOMODE4_READ and |
| 15760 |
LAYOUTIOMODE4_RW iomodes are being returned or recalled, |
| 15761 |
respectively. |
| 15762 |
|
| 15763 |
A storage device may validate I/O with regard to the iomode; this is |
| 15764 |
dependent upon storage device implementation and layout type. Thus, |
| 15765 |
if the client's layout iomode is inconsistent with the I/O being |
| 15766 |
performed, the storage device may reject the client's I/O with an |
| 15767 |
error indicating that a new layout with the correct iomode should be |
| 15768 |
obtained via LAYOUTGET. For example, if a client gets a layout with |
| 15769 |
a LAYOUTIOMODE4_READ iomode and performs a WRITE to a storage device, |
| 15770 |
the storage device is allowed to reject that WRITE. |
| 15771 |
|
| 15772 |
The use of the layout iomode does not conflict with OPEN share modes |
| 15773 |
or byte-range LOCK operations; open share mode and byte-range lock |
| 15774 |
conflicts are enforced as they are without the use of pNFS and are |
| 15775 |
logically separate from the pNFS layout level. Open share modes and |
| 15776 |
byte-range locks are the preferred method for restricting user access |
| 15777 |
to data files. For example, an OPEN of OPEN4_SHARE_ACCESS_WRITE does |
| 15778 |
not conflict with a LAYOUTGET containing an iomode of |
| 15779 |
LAYOUTIOMODE4_RW performed by another client. Applications that |
| 15780 |
depend on writing into the same file concurrently may use byte-range |
| 15781 |
locking to serialize their accesses. |
| 15782 |
|
| 15783 |
|
| 15784 |
|
| 15785 |
|
| 15786 |
|
| 15787 |
|
| 15788 |
<span class="grey">Shepler, et al. Standards Track [Page 282]</span></pre> |
| 15789 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-283" ></span> |
| 15790 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15791 |
|
| 15792 |
|
| 15793 |
<span class="h4"><a class="selflink" id="section-12.2.10" href="#section-12.2.10">12.2.10</a>. Device IDs</span> |
| 15794 |
|
| 15795 |
The device ID (data type deviceid4, see <a href="#section-3.3.14">Section 3.3.14</a>) identifies a |
| 15796 |
group of storage devices. The scope of a device ID is the pair |
| 15797 |
<client ID, layout type>. In practice, a significant amount of |
| 15798 |
information may be required to fully address a storage device. |
| 15799 |
Rather than embedding all such information in a layout, layouts embed |
| 15800 |
device IDs. The NFSv4.1 operation GETDEVICEINFO (<a href="#section-18.40">Section 18.40</a>) is |
| 15801 |
used to retrieve the complete address information (including all |
| 15802 |
device addresses for the device ID) regarding the storage device |
| 15803 |
according to its layout type and device ID. For example, the address |
| 15804 |
of an NFSv4.1 data server or of an object-based storage device could |
| 15805 |
be an IP address and port. The address of a block storage device |
| 15806 |
could be a volume label. |
| 15807 |
|
| 15808 |
Clients cannot expect the mapping between a device ID and its storage |
| 15809 |
device address(es) to persist across metadata server restart. See |
| 15810 |
<a href="#section-12.7.4">Section 12.7.4</a> for a description of how recovery works in that |
| 15811 |
situation. |
| 15812 |
|
| 15813 |
A device ID lives as long as there is a layout referring to the |
| 15814 |
device ID. If there are no layouts referring to the device ID, the |
| 15815 |
server is free to delete the device ID any time. Once a device ID is |
| 15816 |
deleted by the server, the server MUST NOT reuse the device ID for |
| 15817 |
the same layout type and client ID again. This requirement is |
| 15818 |
feasible because the device ID is 16 bytes long, leaving sufficient |
| 15819 |
room to store a generation number if the server's implementation |
| 15820 |
requires most of the rest of the device ID's content to be reused. |
| 15821 |
This requirement is necessary because otherwise the race conditions |
| 15822 |
between asynchronous notification of device ID addition and deletion |
| 15823 |
would be too difficult to sort out. |
| 15824 |
|
| 15825 |
Device ID to device address mappings are not leased, and can be |
| 15826 |
changed at any time. (Note that while device ID to device address |
| 15827 |
mappings are likely to change after the metadata server restarts, the |
| 15828 |
server is not required to change the mappings.) A server has two |
| 15829 |
choices for changing mappings. It can recall all layouts referring |
| 15830 |
to the device ID or it can use a notification mechanism. |
| 15831 |
|
| 15832 |
The NFSv4.1 protocol has no optimal way to recall all layouts that |
| 15833 |
referred to a particular device ID (unless the server associates a |
| 15834 |
single device ID with a single fsid or a single client ID; in which |
| 15835 |
case, CB_LAYOUTRECALL has options for recalling all layouts |
| 15836 |
associated with the fsid, client ID pair, or just the client ID). |
| 15837 |
|
| 15838 |
Via a notification mechanism (see <a href="#section-20.12">Section 20.12</a>), device ID to device |
| 15839 |
address mappings can change over the duration of server operation |
| 15840 |
without recalling or revoking the layouts that refer to device ID. |
| 15841 |
|
| 15842 |
|
| 15843 |
|
| 15844 |
<span class="grey">Shepler, et al. Standards Track [Page 283]</span></pre> |
| 15845 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-284" ></span> |
| 15846 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15847 |
|
| 15848 |
|
| 15849 |
The notification mechanism can also delete a device ID, but only if |
| 15850 |
the client has no layouts referring to the device ID. A notification |
| 15851 |
of a change to a device ID to device address mapping will immediately |
| 15852 |
or eventually invalidate some or all of the device ID's mappings. |
| 15853 |
The server MUST support notifications and the client must request |
| 15854 |
them before they can be used. For further information about the |
| 15855 |
notification types <a href="#section-20.12">Section 20.12</a>. |
| 15856 |
|
| 15857 |
<span class="h3"><a class="selflink" id="section-12.3" href="#section-12.3">12.3</a>. pNFS Operations</span> |
| 15858 |
|
| 15859 |
NFSv4.1 has several operations that are needed for pNFS servers, |
| 15860 |
regardless of layout type or storage protocol. These operations are |
| 15861 |
all sent to a metadata server and summarized here. While pNFS is an |
| 15862 |
OPTIONAL feature, if pNFS is implemented, some operations are |
| 15863 |
REQUIRED in order to comply with pNFS. See <a href="#section-17">Section 17</a>. |
| 15864 |
|
| 15865 |
These are the fore channel pNFS operations: |
| 15866 |
|
| 15867 |
GETDEVICEINFO (<a href="#section-18.40">Section 18.40</a>), as noted previously |
| 15868 |
(<a href="#section-12.2.10">Section 12.2.10</a>), returns the mapping of device ID to storage |
| 15869 |
device address. |
| 15870 |
|
| 15871 |
GETDEVICELIST (<a href="#section-18.41">Section 18.41</a>) allows clients to fetch all device IDs |
| 15872 |
for a specific file system. |
| 15873 |
|
| 15874 |
LAYOUTGET (<a href="#section-18.43">Section 18.43</a>) is used by a client to get a layout for a |
| 15875 |
file. |
| 15876 |
|
| 15877 |
LAYOUTCOMMIT (<a href="#section-18.42">Section 18.42</a>) is used to inform the metadata server |
| 15878 |
of the client's intent to commit data that has been written to the |
| 15879 |
storage device (the storage device as originally indicated in the |
| 15880 |
return value of LAYOUTGET). |
| 15881 |
|
| 15882 |
LAYOUTRETURN (<a href="#section-18.44">Section 18.44</a>) is used to return layouts for a file, a |
| 15883 |
file system ID (FSID), or a client ID. |
| 15884 |
|
| 15885 |
These are the backchannel pNFS operations: |
| 15886 |
|
| 15887 |
CB_LAYOUTRECALL (<a href="#section-20.3">Section 20.3</a>) recalls a layout, all layouts |
| 15888 |
belonging to a file system, or all layouts belonging to a client |
| 15889 |
ID. |
| 15890 |
|
| 15891 |
CB_RECALL_ANY (<a href="#section-20.6">Section 20.6</a>) tells a client that it needs to return |
| 15892 |
some number of recallable objects, including layouts, to the |
| 15893 |
metadata server. |
| 15894 |
|
| 15895 |
|
| 15896 |
|
| 15897 |
|
| 15898 |
|
| 15899 |
|
| 15900 |
<span class="grey">Shepler, et al. Standards Track [Page 284]</span></pre> |
| 15901 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-285" ></span> |
| 15902 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15903 |
|
| 15904 |
|
| 15905 |
CB_RECALLABLE_OBJ_AVAIL (<a href="#section-20.7">Section 20.7</a>) tells a client that a |
| 15906 |
recallable object that it was denied (in case of pNFS, a layout |
| 15907 |
denied by LAYOUTGET) due to resource exhaustion is now available. |
| 15908 |
|
| 15909 |
CB_NOTIFY_DEVICEID (<a href="#section-20.12">Section 20.12</a>) notifies the client of changes to |
| 15910 |
device IDs. |
| 15911 |
|
| 15912 |
<span class="h3"><a class="selflink" id="section-12.4" href="#section-12.4">12.4</a>. pNFS Attributes</span> |
| 15913 |
|
| 15914 |
A number of attributes specific to pNFS are listed and described in |
| 15915 |
<a href="#section-5.12">Section 5.12</a>. |
| 15916 |
|
| 15917 |
<span class="h3"><a class="selflink" id="section-12.5" href="#section-12.5">12.5</a>. Layout Semantics</span> |
| 15918 |
|
| 15919 |
<span class="h4"><a class="selflink" id="section-12.5.1" href="#section-12.5.1">12.5.1</a>. Guarantees Provided by Layouts</span> |
| 15920 |
|
| 15921 |
Layouts grant to the client the ability to access data located at a |
| 15922 |
storage device with the appropriate storage protocol. The client is |
| 15923 |
guaranteed the layout will be recalled when one of two things occur: |
| 15924 |
either a conflicting layout is requested or the state encapsulated by |
| 15925 |
the layout becomes invalid (this can happen when an event directly or |
| 15926 |
indirectly modifies the layout). When a layout is recalled and |
| 15927 |
returned by the client, the client continues with the ability to |
| 15928 |
access file data with normal NFSv4.1 operations through the metadata |
| 15929 |
server. Only the ability to access the storage devices is affected. |
| 15930 |
|
| 15931 |
The requirement of NFSv4.1 that all user access rights MUST be |
| 15932 |
obtained through the appropriate OPEN, LOCK, and ACCESS operations is |
| 15933 |
not modified with the existence of layouts. Layouts are provided to |
| 15934 |
NFSv4.1 clients, and user access still follows the rules of the |
| 15935 |
protocol as if they did not exist. It is a requirement that for a |
| 15936 |
client to access a storage device, a layout must be held by the |
| 15937 |
client. If a storage device receives an I/O request for a byte-range |
| 15938 |
for which the client does not hold a layout, the storage device |
| 15939 |
SHOULD reject that I/O request. Note that the act of modifying a |
| 15940 |
file for which a layout is held does not necessarily conflict with |
| 15941 |
the holding of the layout that describes the file being modified. |
| 15942 |
Therefore, it is the requirement of the storage protocol or layout |
| 15943 |
type that determines the necessary behavior. For example, block/ |
| 15944 |
volume layout types require that the layout's iomode agree with the |
| 15945 |
type of I/O being performed. |
| 15946 |
|
| 15947 |
Depending upon the layout type and storage protocol in use, storage |
| 15948 |
device access permissions may be granted by LAYOUTGET and may be |
| 15949 |
encoded within the type-specific layout. For an example of storage |
| 15950 |
device access permissions, see an object-based protocol such as [<a href="#ref-50" title=""Object-Based Storage Device Commands (OSD)"">50</a>]. |
| 15951 |
If access permissions are encoded within the layout, the metadata |
| 15952 |
server SHOULD recall the layout when those permissions become invalid |
| 15953 |
|
| 15954 |
|
| 15955 |
|
| 15956 |
<span class="grey">Shepler, et al. Standards Track [Page 285]</span></pre> |
| 15957 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-286" ></span> |
| 15958 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 15959 |
|
| 15960 |
|
| 15961 |
for any reason -- for example, when a file becomes unwritable or |
| 15962 |
inaccessible to a client. Note, clients are still required to |
| 15963 |
perform the appropriate OPEN, LOCK, and ACCESS operations as |
| 15964 |
described above. The degree to which it is possible for the client |
| 15965 |
to circumvent these operations and the consequences of doing so must |
| 15966 |
be clearly specified by the individual layout type specifications. |
| 15967 |
In addition, these specifications must be clear about the |
| 15968 |
requirements and non-requirements for the checking performed by the |
| 15969 |
server. |
| 15970 |
|
| 15971 |
In the presence of pNFS functionality, mandatory byte-range locks |
| 15972 |
MUST behave as they would without pNFS. Therefore, if mandatory file |
| 15973 |
locks and layouts are provided simultaneously, the storage device |
| 15974 |
MUST be able to enforce the mandatory byte-range locks. For example, |
| 15975 |
if one client obtains a mandatory byte-range lock and a second client |
| 15976 |
accesses the storage device, the storage device MUST appropriately |
| 15977 |
restrict I/O for the range of the mandatory byte-range lock. If the |
| 15978 |
storage device is incapable of providing this check in the presence |
| 15979 |
of mandatory byte-range locks, then the metadata server MUST NOT |
| 15980 |
grant layouts and mandatory byte-range locks simultaneously. |
| 15981 |
|
| 15982 |
<span class="h4"><a class="selflink" id="section-12.5.2" href="#section-12.5.2">12.5.2</a>. Getting a Layout</span> |
| 15983 |
|
| 15984 |
A client obtains a layout with the LAYOUTGET operation. The metadata |
| 15985 |
server will grant layouts of a particular type (e.g., block/volume, |
| 15986 |
object, or file). The client selects an appropriate layout type that |
| 15987 |
the server supports and the client is prepared to use. The layout |
| 15988 |
returned to the client might not exactly match the requested byte- |
| 15989 |
range as described in <a href="#section-18.43.3">Section 18.43.3</a>. As needed a client may send |
| 15990 |
multiple LAYOUTGET operations; these might result in multiple |
| 15991 |
overlapping, non-conflicting layouts (see <a href="#section-12.2.8">Section 12.2.8</a>). |
| 15992 |
|
| 15993 |
In order to get a layout, the client must first have opened the file |
| 15994 |
via the OPEN operation. When a client has no layout on a file, it |
| 15995 |
MUST present an open stateid, a delegation stateid, or a byte-range |
| 15996 |
lock stateid in the loga_stateid argument. A successful LAYOUTGET |
| 15997 |
result includes a layout stateid. The first successful LAYOUTGET |
| 15998 |
processed by the server using a non-layout stateid as an argument |
| 15999 |
MUST have the "seqid" field of the layout stateid in the response set |
| 16000 |
to one. Thereafter, the client MUST use a layout stateid (see |
| 16001 |
<a href="#section-12.5.3">Section 12.5.3</a>) on future invocations of LAYOUTGET on the file, and |
| 16002 |
the "seqid" MUST NOT be set to zero. Once the layout has been |
| 16003 |
retrieved, it can be held across multiple OPEN and CLOSE sequences. |
| 16004 |
Therefore, a client may hold a layout for a file that is not |
| 16005 |
currently open by any user on the client. This allows for the |
| 16006 |
caching of layouts beyond CLOSE. |
| 16007 |
|
| 16008 |
|
| 16009 |
|
| 16010 |
|
| 16011 |
|
| 16012 |
<span class="grey">Shepler, et al. Standards Track [Page 286]</span></pre> |
| 16013 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-287" ></span> |
| 16014 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16015 |
|
| 16016 |
|
| 16017 |
The storage protocol used by the client to access the data on the |
| 16018 |
storage device is determined by the layout's type. The client is |
| 16019 |
responsible for matching the layout type with an available method to |
| 16020 |
interpret and use the layout. The method for this layout type |
| 16021 |
selection is outside the scope of the pNFS functionality. |
| 16022 |
|
| 16023 |
Although the metadata server is in control of the layout for a file, |
| 16024 |
the pNFS client can provide hints to the server when a file is opened |
| 16025 |
or created about the preferred layout type and aggregation schemes. |
| 16026 |
pNFS introduces a layout_hint attribute (<a href="#section-5.12.4">Section 5.12.4</a>) that the |
| 16027 |
client can set at file creation time to provide a hint to the server |
| 16028 |
for new files. Setting this attribute separately, after the file has |
| 16029 |
been created might make it difficult, or impossible, for the server |
| 16030 |
implementation to comply. |
| 16031 |
|
| 16032 |
Because the EXCLUSIVE4 createmode4 does not allow the setting of |
| 16033 |
attributes at file creation time, NFSv4.1 introduces the EXCLUSIVE4_1 |
| 16034 |
createmode4, which does allow attributes to be set at file creation |
| 16035 |
time. In addition, if the session is created with persistent reply |
| 16036 |
caches, EXCLUSIVE4_1 is neither necessary nor allowed. Instead, |
| 16037 |
GUARDED4 both works better and is prescribed. Table 10 in |
| 16038 |
<a href="#section-18.16.3">Section 18.16.3</a> summarizes how a client is allowed to send an |
| 16039 |
exclusive create. |
| 16040 |
|
| 16041 |
<span class="h4"><a class="selflink" id="section-12.5.3" href="#section-12.5.3">12.5.3</a>. Layout Stateid</span> |
| 16042 |
|
| 16043 |
As with all other stateids, the layout stateid consists of a "seqid" |
| 16044 |
and "other" field. Once a layout stateid is established, the "other" |
| 16045 |
field will stay constant unless the stateid is revoked or the client |
| 16046 |
returns all layouts on the file and the server disposes of the |
| 16047 |
stateid. The "seqid" field is initially set to one, and is never |
| 16048 |
zero on any NFSv4.1 operation that uses layout stateids, whether it |
| 16049 |
is a fore channel or backchannel operation. After the layout stateid |
| 16050 |
is established, the server increments by one the value of the "seqid" |
| 16051 |
in each subsequent LAYOUTGET and LAYOUTRETURN response, and in each |
| 16052 |
CB_LAYOUTRECALL request. |
| 16053 |
|
| 16054 |
Given the design goal of pNFS to provide parallelism, the layout |
| 16055 |
stateid differs from other stateid types in that the client is |
| 16056 |
expected to send LAYOUTGET and LAYOUTRETURN operations in parallel. |
| 16057 |
The "seqid" value is used by the client to properly sort responses to |
| 16058 |
LAYOUTGET and LAYOUTRETURN. The "seqid" is also used to prevent race |
| 16059 |
conditions between LAYOUTGET and CB_LAYOUTRECALL. Given that the |
| 16060 |
processing rules differ from layout stateids and other stateid types, |
| 16061 |
only the pNFS sections of this document should be considered to |
| 16062 |
determine proper layout stateid handling. |
| 16063 |
|
| 16064 |
|
| 16065 |
|
| 16066 |
|
| 16067 |
|
| 16068 |
<span class="grey">Shepler, et al. Standards Track [Page 287]</span></pre> |
| 16069 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-288" ></span> |
| 16070 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16071 |
|
| 16072 |
|
| 16073 |
Once the client receives a layout stateid, it MUST use the correct |
| 16074 |
"seqid" for subsequent LAYOUTGET or LAYOUTRETURN operations. The |
| 16075 |
correct "seqid" is defined as the highest "seqid" value from |
| 16076 |
responses of fully processed LAYOUTGET or LAYOUTRETURN operations or |
| 16077 |
arguments of a fully processed CB_LAYOUTRECALL operation. Since the |
| 16078 |
server is incrementing the "seqid" value on each layout operation, |
| 16079 |
the client may determine the order of operation processing by |
| 16080 |
inspecting the "seqid" value. In the case of overlapping layout |
| 16081 |
ranges, the ordering information will provide the client the |
| 16082 |
knowledge of which layout ranges are held. Note that overlapping |
| 16083 |
layout ranges may occur because of the client's specific requests or |
| 16084 |
because the server is allowed to expand the range of a requested |
| 16085 |
layout and notify the client in the LAYOUTRETURN results. Additional |
| 16086 |
layout stateid sequencing requirements are provided in |
| 16087 |
<a href="#section-12.5.5.2">Section 12.5.5.2</a>. |
| 16088 |
|
| 16089 |
The client's receipt of a "seqid" is not sufficient for subsequent |
| 16090 |
use. The client must fully process the operations before the "seqid" |
| 16091 |
can be used. For LAYOUTGET results, if the client is not using the |
| 16092 |
forgetful model (<a href="#section-12.5.5.1">Section 12.5.5.1</a>), it MUST first update its record |
| 16093 |
of what ranges of the file's layout it has before using the seqid. |
| 16094 |
For LAYOUTRETURN results, the client MUST delete the range from its |
| 16095 |
record of what ranges of the file's layout it had before using the |
| 16096 |
seqid. For CB_LAYOUTRECALL arguments, the client MUST send a |
| 16097 |
response to the recall before using the seqid. The fundamental |
| 16098 |
requirement in client processing is that the "seqid" is used to |
| 16099 |
provide the order of processing. LAYOUTGET results may be processed |
| 16100 |
in parallel. LAYOUTRETURN results may be processed in parallel. |
| 16101 |
LAYOUTGET and LAYOUTRETURN responses may be processed in parallel as |
| 16102 |
long as the ranges do not overlap. CB_LAYOUTRECALL request |
| 16103 |
processing MUST be processed in "seqid" order at all times. |
| 16104 |
|
| 16105 |
Once a client has no more layouts on a file, the layout stateid is no |
| 16106 |
longer valid and MUST NOT be used. Any attempt to use such a layout |
| 16107 |
stateid will result in NFS4ERR_BAD_STATEID. |
| 16108 |
|
| 16109 |
<span class="h4"><a class="selflink" id="section-12.5.4" href="#section-12.5.4">12.5.4</a>. Committing a Layout</span> |
| 16110 |
|
| 16111 |
Allowing for varying storage protocol capabilities, the pNFS protocol |
| 16112 |
does not require the metadata server and storage devices to have a |
| 16113 |
consistent view of file attributes and data location mappings. Data |
| 16114 |
location mapping refers to aspects such as which offsets store data |
| 16115 |
as opposed to storing holes (see <a href="#section-13.4.4">Section 13.4.4</a> for a discussion). |
| 16116 |
Related issues arise for storage protocols where a layout may hold |
| 16117 |
provisionally allocated blocks where the allocation of those blocks |
| 16118 |
does not survive a complete restart of both the client and server. |
| 16119 |
|
| 16120 |
|
| 16121 |
|
| 16122 |
|
| 16123 |
|
| 16124 |
<span class="grey">Shepler, et al. Standards Track [Page 288]</span></pre> |
| 16125 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-289" ></span> |
| 16126 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16127 |
|
| 16128 |
|
| 16129 |
Because of this inconsistency, it is necessary to resynchronize the |
| 16130 |
client with the metadata server and its storage devices and make any |
| 16131 |
potential changes available to other clients. This is accomplished |
| 16132 |
by use of the LAYOUTCOMMIT operation. |
| 16133 |
|
| 16134 |
The LAYOUTCOMMIT operation is responsible for committing a modified |
| 16135 |
layout to the metadata server. The data should be written and |
| 16136 |
committed to the appropriate storage devices before the LAYOUTCOMMIT |
| 16137 |
occurs. The scope of the LAYOUTCOMMIT operation depends on the |
| 16138 |
storage protocol in use. It is important to note that the level of |
| 16139 |
synchronization is from the point of view of the client that sent the |
| 16140 |
LAYOUTCOMMIT. The updated state on the metadata server need only |
| 16141 |
reflect the state as of the client's last operation previous to the |
| 16142 |
LAYOUTCOMMIT. The metadata server is not REQUIRED to maintain a |
| 16143 |
global view that accounts for other clients' I/O that may have |
| 16144 |
occurred within the same time frame. |
| 16145 |
|
| 16146 |
For block/volume-based layouts, LAYOUTCOMMIT may require updating the |
| 16147 |
block list that comprises the file and committing this layout to |
| 16148 |
stable storage. For file-based layouts, synchronization of |
| 16149 |
attributes between the metadata and storage devices, primarily the |
| 16150 |
size attribute, is required. |
| 16151 |
|
| 16152 |
The control protocol is free to synchronize the attributes before it |
| 16153 |
receives a LAYOUTCOMMIT; however, upon successful completion of a |
| 16154 |
LAYOUTCOMMIT, state that exists on the metadata server that describes |
| 16155 |
the file MUST be synchronized with the state that exists on the |
| 16156 |
storage devices that comprise that file as of the client's last sent |
| 16157 |
operation. Thus, a client that queries the size of a file between a |
| 16158 |
WRITE to a storage device and the LAYOUTCOMMIT might observe a size |
| 16159 |
that does not reflect the actual data written. |
| 16160 |
|
| 16161 |
The client MUST have a layout in order to send a LAYOUTCOMMIT |
| 16162 |
operation. |
| 16163 |
|
| 16164 |
<span class="h5"><a class="selflink" id="section-12.5.4.1" href="#section-12.5.4.1">12.5.4.1</a>. LAYOUTCOMMIT and change/time_modify</span> |
| 16165 |
|
| 16166 |
The change and time_modify attributes may be updated by the server |
| 16167 |
when the LAYOUTCOMMIT operation is processed. The reason for this is |
| 16168 |
that some layout types do not support the update of these attributes |
| 16169 |
when the storage devices process I/O operations. If a client has a |
| 16170 |
layout with the LAYOUTIOMODE4_RW iomode on the file, the client MAY |
| 16171 |
provide a suggested value to the server for time_modify within the |
| 16172 |
arguments to LAYOUTCOMMIT. Based on the layout type, the provided |
| 16173 |
value may or may not be used. The server should sanity-check the |
| 16174 |
client-provided values before they are used. For example, the server |
| 16175 |
|
| 16176 |
|
| 16177 |
|
| 16178 |
|
| 16179 |
|
| 16180 |
<span class="grey">Shepler, et al. Standards Track [Page 289]</span></pre> |
| 16181 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-290" ></span> |
| 16182 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16183 |
|
| 16184 |
|
| 16185 |
should ensure that time does not flow backwards. The client always |
| 16186 |
has the option to set time_modify through an explicit SETATTR |
| 16187 |
operation. |
| 16188 |
|
| 16189 |
For some layout protocols, the storage device is able to notify the |
| 16190 |
metadata server of the occurrence of an I/O; as a result, the change |
| 16191 |
and time_modify attributes may be updated at the metadata server. |
| 16192 |
For a metadata server that is capable of monitoring updates to the |
| 16193 |
change and time_modify attributes, LAYOUTCOMMIT processing is not |
| 16194 |
required to update the change attribute. In this case, the metadata |
| 16195 |
server must ensure that no further update to the data has occurred |
| 16196 |
since the last update of the attributes; file-based protocols may |
| 16197 |
have enough information to make this determination or may update the |
| 16198 |
change attribute upon each file modification. This also applies for |
| 16199 |
the time_modify attribute. If the server implementation is able to |
| 16200 |
determine that the file has not been modified since the last |
| 16201 |
time_modify update, the server need not update time_modify at |
| 16202 |
LAYOUTCOMMIT. At LAYOUTCOMMIT completion, the updated attributes |
| 16203 |
should be visible if that file was modified since the latest previous |
| 16204 |
LAYOUTCOMMIT or LAYOUTGET. |
| 16205 |
|
| 16206 |
<span class="h5"><a class="selflink" id="section-12.5.4.2" href="#section-12.5.4.2">12.5.4.2</a>. LAYOUTCOMMIT and size</span> |
| 16207 |
|
| 16208 |
The size of a file may be updated when the LAYOUTCOMMIT operation is |
| 16209 |
used by the client. One of the fields in the argument to |
| 16210 |
LAYOUTCOMMIT is loca_last_write_offset; this field indicates the |
| 16211 |
highest byte offset written but not yet committed with the |
| 16212 |
LAYOUTCOMMIT operation. The data type of loca_last_write_offset is |
| 16213 |
newoffset4 and is switched on a boolean value, no_newoffset, that |
| 16214 |
indicates if a previous write occurred or not. If no_newoffset is |
| 16215 |
FALSE, an offset is not given. If the client has a layout with |
| 16216 |
LAYOUTIOMODE4_RW iomode on the file, with a byte-range (denoted by |
| 16217 |
the values of lo_offset and lo_length) that overlaps |
| 16218 |
loca_last_write_offset, then the client MAY set no_newoffset to TRUE |
| 16219 |
and provide an offset that will update the file size. Keep in mind |
| 16220 |
that offset is not the same as length, though they are related. For |
| 16221 |
example, a loca_last_write_offset value of zero means that one byte |
| 16222 |
was written at offset zero, and so the length of the file is at least |
| 16223 |
one byte. |
| 16224 |
|
| 16225 |
The metadata server may do one of the following: |
| 16226 |
|
| 16227 |
1. Update the file's size using the last write offset provided by |
| 16228 |
the client as either the true file size or as a hint of the file |
| 16229 |
size. If the metadata server has a method available, any new |
| 16230 |
value for file size should be sanity-checked. For example, the |
| 16231 |
file must not be truncated if the client presents a last write |
| 16232 |
offset less than the file's current size. |
| 16233 |
|
| 16234 |
|
| 16235 |
|
| 16236 |
<span class="grey">Shepler, et al. Standards Track [Page 290]</span></pre> |
| 16237 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-291" ></span> |
| 16238 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16239 |
|
| 16240 |
|
| 16241 |
2. Ignore the client-provided last write offset; the metadata server |
| 16242 |
must have sufficient knowledge from other sources to determine |
| 16243 |
the file's size. For example, the metadata server queries the |
| 16244 |
storage devices with the control protocol. |
| 16245 |
|
| 16246 |
The method chosen to update the file's size will depend on the |
| 16247 |
storage device's and/or the control protocol's capabilities. For |
| 16248 |
example, if the storage devices are block devices with no knowledge |
| 16249 |
of file size, the metadata server must rely on the client to set the |
| 16250 |
last write offset appropriately. |
| 16251 |
|
| 16252 |
The results of LAYOUTCOMMIT contain a new size value in the form of a |
| 16253 |
newsize4 union data type. If the file's size is set as a result of |
| 16254 |
LAYOUTCOMMIT, the metadata server must reply with the new size; |
| 16255 |
otherwise, the new size is not provided. If the file size is |
| 16256 |
updated, the metadata server SHOULD update the storage devices such |
| 16257 |
that the new file size is reflected when LAYOUTCOMMIT processing is |
| 16258 |
complete. For example, the client should be able to read up to the |
| 16259 |
new file size. |
| 16260 |
|
| 16261 |
The client can extend the length of a file or truncate a file by |
| 16262 |
sending a SETATTR operation to the metadata server with the size |
| 16263 |
attribute specified. If the size specified is larger than the |
| 16264 |
current size of the file, the file is "zero extended", i.e., zeros |
| 16265 |
are implicitly added between the file's previous EOF and the new EOF. |
| 16266 |
(In many implementations, the zero-extended byte-range of the file |
| 16267 |
consists of unallocated holes in the file.) When the client writes |
| 16268 |
past EOF via WRITE, the SETATTR operation does not need to be used. |
| 16269 |
|
| 16270 |
<span class="h5"><a class="selflink" id="section-12.5.4.3" href="#section-12.5.4.3">12.5.4.3</a>. LAYOUTCOMMIT and layoutupdate</span> |
| 16271 |
|
| 16272 |
The LAYOUTCOMMIT argument contains a loca_layoutupdate field |
| 16273 |
(<a href="#section-18.42.1">Section 18.42.1</a>) of data type layoutupdate4 (<a href="#section-3.3.18">Section 3.3.18</a>). This |
| 16274 |
argument is a layout-type-specific structure. The structure can be |
| 16275 |
used to pass arbitrary layout-type-specific information from the |
| 16276 |
client to the metadata server at LAYOUTCOMMIT time. For example, if |
| 16277 |
using a block/volume layout, the client can indicate to the metadata |
| 16278 |
server which reserved or allocated blocks the client used or did not |
| 16279 |
use. The content of loca_layoutupdate (field lou_body) need not be |
| 16280 |
the same layout-type-specific content returned by LAYOUTGET |
| 16281 |
(<a href="#section-18.43.2">Section 18.43.2</a>) in the loc_body field of the lo_content field of |
| 16282 |
the logr_layout field. The content of loca_layoutupdate is defined |
| 16283 |
by the layout type specification and is opaque to LAYOUTCOMMIT. |
| 16284 |
|
| 16285 |
|
| 16286 |
|
| 16287 |
|
| 16288 |
|
| 16289 |
|
| 16290 |
|
| 16291 |
|
| 16292 |
<span class="grey">Shepler, et al. Standards Track [Page 291]</span></pre> |
| 16293 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-292" ></span> |
| 16294 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16295 |
|
| 16296 |
|
| 16297 |
<span class="h4"><a class="selflink" id="section-12.5.5" href="#section-12.5.5">12.5.5</a>. Recalling a Layout</span> |
| 16298 |
|
| 16299 |
Since a layout protects a client's access to a file via a direct |
| 16300 |
client-storage-device path, a layout need only be recalled when it is |
| 16301 |
semantically unable to serve this function. Typically, this occurs |
| 16302 |
when the layout no longer encapsulates the true location of the file |
| 16303 |
over the byte-range it represents. Any operation or action, such as |
| 16304 |
server-driven restriping or load balancing, that changes the layout |
| 16305 |
will result in a recall of the layout. A layout is recalled by the |
| 16306 |
CB_LAYOUTRECALL callback operation (see <a href="#section-20.3">Section 20.3</a>) and returned |
| 16307 |
with LAYOUTRETURN (see <a href="#section-18.44">Section 18.44</a>). The CB_LAYOUTRECALL operation |
| 16308 |
may recall a layout identified by a byte-range, all layouts |
| 16309 |
associated with a file system ID (FSID), or all layouts associated |
| 16310 |
with a client ID. <a href="#section-12.5.5.2">Section 12.5.5.2</a> discusses sequencing issues |
| 16311 |
surrounding the getting, returning, and recalling of layouts. |
| 16312 |
|
| 16313 |
An iomode is also specified when recalling a layout. Generally, the |
| 16314 |
iomode in the recall request must match the layout being returned; |
| 16315 |
for example, a recall with an iomode of LAYOUTIOMODE4_RW should cause |
| 16316 |
the client to only return LAYOUTIOMODE4_RW layouts and not |
| 16317 |
LAYOUTIOMODE4_READ layouts. However, a special LAYOUTIOMODE4_ANY |
| 16318 |
enumeration is defined to enable recalling a layout of any iomode; in |
| 16319 |
other words, the client must return both LAYOUTIOMODE4_READ and |
| 16320 |
LAYOUTIOMODE4_RW layouts. |
| 16321 |
|
| 16322 |
A REMOVE operation SHOULD cause the metadata server to recall the |
| 16323 |
layout to prevent the client from accessing a non-existent file and |
| 16324 |
to reclaim state stored on the client. Since a REMOVE may be delayed |
| 16325 |
until the last close of the file has occurred, the recall may also be |
| 16326 |
delayed until this time. After the last reference on the file has |
| 16327 |
been released and the file has been removed, the client should no |
| 16328 |
longer be able to perform I/O using the layout. In the case of a |
| 16329 |
file-based layout, the data server SHOULD return NFS4ERR_STALE in |
| 16330 |
response to any operation on the removed file. |
| 16331 |
|
| 16332 |
Once a layout has been returned, the client MUST NOT send I/Os to the |
| 16333 |
storage devices for the file, byte-range, and iomode represented by |
| 16334 |
the returned layout. If a client does send an I/O to a storage |
| 16335 |
device for which it does not hold a layout, the storage device SHOULD |
| 16336 |
reject the I/O. |
| 16337 |
|
| 16338 |
Although pNFS does not alter the file data caching capabilities of |
| 16339 |
clients, or their semantics, it recognizes that some clients may |
| 16340 |
perform more aggressive write-behind caching to optimize the benefits |
| 16341 |
provided by pNFS. However, write-behind caching may negatively |
| 16342 |
affect the latency in returning a layout in response to a |
| 16343 |
CB_LAYOUTRECALL; this is similar to file delegations and the impact |
| 16344 |
that file data caching has on DELEGRETURN. Client implementations |
| 16345 |
|
| 16346 |
|
| 16347 |
|
| 16348 |
<span class="grey">Shepler, et al. Standards Track [Page 292]</span></pre> |
| 16349 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-293" ></span> |
| 16350 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16351 |
|
| 16352 |
|
| 16353 |
SHOULD limit the amount of unwritten data they have outstanding at |
| 16354 |
any one time in order to prevent excessively long responses to |
| 16355 |
CB_LAYOUTRECALL. Once a layout is recalled, a server MUST wait one |
| 16356 |
lease period before taking further action. As soon as a lease period |
| 16357 |
has passed, the server may choose to fence the client's access to the |
| 16358 |
storage devices if the server perceives the client has taken too long |
| 16359 |
to return a layout. However, just as in the case of data delegation |
| 16360 |
and DELEGRETURN, the server may choose to wait, given that the client |
| 16361 |
is showing forward progress on its way to returning the layout. This |
| 16362 |
forward progress can take the form of successful interaction with the |
| 16363 |
storage devices or of sub-portions of the layout being returned by |
| 16364 |
the client. The server can also limit exposure to these problems by |
| 16365 |
limiting the byte-ranges initially provided in the layouts and thus |
| 16366 |
the amount of outstanding modified data. |
| 16367 |
|
| 16368 |
<span class="h5"><a class="selflink" id="section-12.5.5.1" href="#section-12.5.5.1">12.5.5.1</a>. Layout Recall Callback Robustness</span> |
| 16369 |
|
| 16370 |
It has been assumed thus far that pNFS client state (layout ranges |
| 16371 |
and iomode) for a file exactly matches that of the pNFS server for |
| 16372 |
that file. This assumption leads to the implication that any |
| 16373 |
callback results in a LAYOUTRETURN or set of LAYOUTRETURNs that |
| 16374 |
exactly match the range in the callback, since both client and server |
| 16375 |
agree about the state being maintained. However, it can be useful if |
| 16376 |
this assumption does not always hold. For example: |
| 16377 |
|
| 16378 |
o If conflicts that require callbacks are very rare, and a server |
| 16379 |
can use a multi-file callback to recover per-client resources |
| 16380 |
(e.g., via an FSID recall or a multi-file recall within a single |
| 16381 |
CB_COMPOUND), the result may be significantly less client-server |
| 16382 |
pNFS traffic. |
| 16383 |
|
| 16384 |
o It may be useful for servers to maintain information about what |
| 16385 |
ranges are held by a client on a coarse-grained basis, leading to |
| 16386 |
the server's layout ranges being beyond those actually held by the |
| 16387 |
client. In the extreme, a server could manage conflicts on a per- |
| 16388 |
file basis, only sending whole-file callbacks even though clients |
| 16389 |
may request and be granted sub-file ranges. |
| 16390 |
|
| 16391 |
o It may be useful for clients to "forget" details about what |
| 16392 |
layouts and ranges the client actually has, leading to the |
| 16393 |
server's layout ranges being beyond those that the client "thinks" |
| 16394 |
it has. As long as the client does not assume it has layouts that |
| 16395 |
are beyond what the server has granted, this is a safe practice. |
| 16396 |
When a client forgets what ranges and layouts it has, and it |
| 16397 |
receives a CB_LAYOUTRECALL operation, the client MUST follow up |
| 16398 |
with a LAYOUTRETURN for what the server recalled, or alternatively |
| 16399 |
return the NFS4ERR_NOMATCHING_LAYOUT error if it has no layout to |
| 16400 |
return in the recalled range. |
| 16401 |
|
| 16402 |
|
| 16403 |
|
| 16404 |
<span class="grey">Shepler, et al. Standards Track [Page 293]</span></pre> |
| 16405 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-294" ></span> |
| 16406 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16407 |
|
| 16408 |
|
| 16409 |
o In order to avoid errors, it is vital that a client not assign |
| 16410 |
itself layout permissions beyond what the server has granted, and |
| 16411 |
that the server not forget layout permissions that have been |
| 16412 |
granted. On the other hand, if a server believes that a client |
| 16413 |
holds a layout that the client does not know about, it is useful |
| 16414 |
for the client to cleanly indicate completion of the requested |
| 16415 |
recall either by sending a LAYOUTRETURN operation for the entire |
| 16416 |
requested range or by returning an NFS4ERR_NOMATCHING_LAYOUT error |
| 16417 |
to the CB_LAYOUTRECALL. |
| 16418 |
|
| 16419 |
Thus, in light of the above, it is useful for a server to be able to |
| 16420 |
send callbacks for layout ranges it has not granted to a client, and |
| 16421 |
for a client to return ranges it does not hold. A pNFS client MUST |
| 16422 |
always return layouts that comprise the full range specified by the |
| 16423 |
recall. Note, the full recalled layout range need not be returned as |
| 16424 |
part of a single operation, but may be returned in portions. This |
| 16425 |
allows the client to stage the flushing of dirty data and commits and |
| 16426 |
returns of layouts. Also, it indicates to the metadata server that |
| 16427 |
the client is making progress. |
| 16428 |
|
| 16429 |
When a layout is returned, the client MUST NOT have any outstanding |
| 16430 |
I/O requests to the storage devices involved in the layout. |
| 16431 |
Rephrasing, the client MUST NOT return the layout while it has |
| 16432 |
outstanding I/O requests to the storage device. |
| 16433 |
|
| 16434 |
Even with this requirement for the client, it is possible that I/O |
| 16435 |
requests may be presented to a storage device no longer allowed to |
| 16436 |
perform them. Since the server has no strict control as to when the |
| 16437 |
client will return the layout, the server may later decide to |
| 16438 |
unilaterally revoke the client's access to the storage devices as |
| 16439 |
provided by the layout. In choosing to revoke access, the server |
| 16440 |
must deal with the possibility of lingering I/O requests, i.e., I/O |
| 16441 |
requests that are still in flight to storage devices identified by |
| 16442 |
the revoked layout. All layout type specifications MUST define |
| 16443 |
whether unilateral layout revocation by the metadata server is |
| 16444 |
supported; if it is, the specification must also describe how |
| 16445 |
lingering writes are processed. For example, storage devices |
| 16446 |
identified by the revoked layout could be fenced off from the client |
| 16447 |
that held the layout. |
| 16448 |
|
| 16449 |
In order to ensure client/server convergence with regard to layout |
| 16450 |
state, the final LAYOUTRETURN operation in a sequence of LAYOUTRETURN |
| 16451 |
operations for a particular recall MUST specify the entire range |
| 16452 |
being recalled, echoing the recalled layout type, iomode, recall/ |
| 16453 |
return type (FILE, FSID, or ALL), and byte-range, even if layouts |
| 16454 |
pertaining to partial ranges were previously returned. In addition, |
| 16455 |
if the client holds no layouts that overlap the range being recalled, |
| 16456 |
|
| 16457 |
|
| 16458 |
|
| 16459 |
|
| 16460 |
<span class="grey">Shepler, et al. Standards Track [Page 294]</span></pre> |
| 16461 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-295" ></span> |
| 16462 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16463 |
|
| 16464 |
|
| 16465 |
the client should return the NFS4ERR_NOMATCHING_LAYOUT error code to |
| 16466 |
CB_LAYOUTRECALL. This allows the server to update its view of the |
| 16467 |
client's layout state. |
| 16468 |
|
| 16469 |
<span class="h5"><a class="selflink" id="section-12.5.5.2" href="#section-12.5.5.2">12.5.5.2</a>. Sequencing of Layout Operations</span> |
| 16470 |
|
| 16471 |
As with other stateful operations, pNFS requires the correct |
| 16472 |
sequencing of layout operations. pNFS uses the "seqid" in the layout |
| 16473 |
stateid to provide the correct sequencing between regular operations |
| 16474 |
and callbacks. It is the server's responsibility to avoid |
| 16475 |
inconsistencies regarding the layouts provided and the client's |
| 16476 |
responsibility to properly serialize its layout requests and layout |
| 16477 |
returns. |
| 16478 |
|
| 16479 |
<span class="h6"><a class="selflink" id="section-12.5.5.2.1" href="#section-12.5.5.2.1">12.5.5.2.1</a>. Layout Recall and Return Sequencing</span> |
| 16480 |
|
| 16481 |
One critical issue with regard to layout operations sequencing |
| 16482 |
concerns callbacks. The protocol must defend against races between |
| 16483 |
the reply to a LAYOUTGET or LAYOUTRETURN operation and a subsequent |
| 16484 |
CB_LAYOUTRECALL. A client MUST NOT process a CB_LAYOUTRECALL that |
| 16485 |
implies one or more outstanding LAYOUTGET or LAYOUTRETURN operations |
| 16486 |
to which the client has not yet received a reply. The client detects |
| 16487 |
such a CB_LAYOUTRECALL by examining the "seqid" field of the recall's |
| 16488 |
layout stateid. If the "seqid" is not exactly one higher than what |
| 16489 |
the client currently has recorded, and the client has at least one |
| 16490 |
LAYOUTGET and/or LAYOUTRETURN operation outstanding, the client knows |
| 16491 |
the server sent the CB_LAYOUTRECALL after sending a response to an |
| 16492 |
outstanding LAYOUTGET or LAYOUTRETURN. The client MUST wait before |
| 16493 |
processing such a CB_LAYOUTRECALL until it processes all replies for |
| 16494 |
outstanding LAYOUTGET and LAYOUTRETURN operations for the |
| 16495 |
corresponding file with seqid less than the seqid given by |
| 16496 |
CB_LAYOUTRECALL (lor_stateid; see <a href="#section-20.3">Section 20.3</a>.) |
| 16497 |
|
| 16498 |
In addition to the seqid-based mechanism, <a href="#section-2.10.6.3">Section 2.10.6.3</a> describes |
| 16499 |
the sessions mechanism for allowing the client to detect callback |
| 16500 |
race conditions and delay processing such a CB_LAYOUTRECALL. The |
| 16501 |
server MAY reference conflicting operations in the CB_SEQUENCE that |
| 16502 |
precedes the CB_LAYOUTRECALL. Because the server has already sent |
| 16503 |
replies for these operations before sending the callback, the replies |
| 16504 |
may race with the CB_LAYOUTRECALL. The client MUST wait for all the |
| 16505 |
referenced calls to complete and update its view of the layout state |
| 16506 |
before processing the CB_LAYOUTRECALL. |
| 16507 |
|
| 16508 |
<span class="h6"><a class="selflink" id="section-12.5.5.2.1.1" href="#section-12.5.5.2.1.1">12.5.5.2.1.1</a>. Get/Return Sequencing</span> |
| 16509 |
|
| 16510 |
The protocol allows the client to send concurrent LAYOUTGET and |
| 16511 |
LAYOUTRETURN operations to the server. The protocol does not provide |
| 16512 |
any means for the server to process the requests in the same order in |
| 16513 |
|
| 16514 |
|
| 16515 |
|
| 16516 |
<span class="grey">Shepler, et al. Standards Track [Page 295]</span></pre> |
| 16517 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-296" ></span> |
| 16518 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16519 |
|
| 16520 |
|
| 16521 |
which they were created. However, through the use of the "seqid" |
| 16522 |
field in the layout stateid, the client can determine the order in |
| 16523 |
which parallel outstanding operations were processed by the server. |
| 16524 |
Thus, when a layout retrieved by an outstanding LAYOUTGET operation |
| 16525 |
intersects with a layout returned by an outstanding LAYOUTRETURN on |
| 16526 |
the same file, the order in which the two conflicting operations are |
| 16527 |
processed determines the final state of the overlapping layout. The |
| 16528 |
order is determined by the "seqid" returned in each operation: the |
| 16529 |
operation with the higher seqid was executed later. |
| 16530 |
|
| 16531 |
It is permissible for the client to send multiple parallel LAYOUTGET |
| 16532 |
operations for the same file or multiple parallel LAYOUTRETURN |
| 16533 |
operations for the same file or a mix of both. |
| 16534 |
|
| 16535 |
It is permissible for the client to use the current stateid (see |
| 16536 |
<a href="#section-16.2.3.1.2">Section 16.2.3.1.2</a>) for LAYOUTGET operations, for example, when |
| 16537 |
compounding LAYOUTGETs or compounding OPEN and LAYOUTGETs. It is |
| 16538 |
also permissible to use the current stateid when compounding |
| 16539 |
LAYOUTRETURNs. |
| 16540 |
|
| 16541 |
It is permissible for the client to use the current stateid when |
| 16542 |
combining LAYOUTRETURN and LAYOUTGET operations for the same file in |
| 16543 |
the same COMPOUND request since the server MUST process these in |
| 16544 |
order. However, if a client does send such COMPOUND requests, it |
| 16545 |
MUST NOT have more than one outstanding for the same file at the same |
| 16546 |
time, and it MUST NOT have other LAYOUTGET or LAYOUTRETURN operations |
| 16547 |
outstanding at the same time for that same file. |
| 16548 |
|
| 16549 |
<span class="h6"><a class="selflink" id="section-12.5.5.2.1.2" href="#section-12.5.5.2.1.2">12.5.5.2.1.2</a>. Client Considerations</span> |
| 16550 |
|
| 16551 |
Consider a pNFS client that has sent a LAYOUTGET, and before it |
| 16552 |
receives the reply to LAYOUTGET, it receives a CB_LAYOUTRECALL for |
| 16553 |
the same file with an overlapping range. There are two |
| 16554 |
possibilities, which the client can distinguish via the layout |
| 16555 |
stateid in the recall. |
| 16556 |
|
| 16557 |
1. The server processed the LAYOUTGET before sending the recall, so |
| 16558 |
the LAYOUTGET must be waited for because it may be carrying |
| 16559 |
layout information that will need to be returned to deal with the |
| 16560 |
CB_LAYOUTRECALL. |
| 16561 |
|
| 16562 |
2. The server sent the callback before receiving the LAYOUTGET. The |
| 16563 |
server will not respond to the LAYOUTGET until the |
| 16564 |
CB_LAYOUTRECALL is processed. |
| 16565 |
|
| 16566 |
If these possibilities cannot be distinguished, a deadlock could |
| 16567 |
result, as the client must wait for the LAYOUTGET response before |
| 16568 |
processing the recall in the first case, but that response will not |
| 16569 |
|
| 16570 |
|
| 16571 |
|
| 16572 |
<span class="grey">Shepler, et al. Standards Track [Page 296]</span></pre> |
| 16573 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-297" ></span> |
| 16574 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16575 |
|
| 16576 |
|
| 16577 |
arrive until after the recall is processed in the second case. Note |
| 16578 |
that in the first case, the "seqid" in the layout stateid of the |
| 16579 |
recall is two greater than what the client has recorded; in the |
| 16580 |
second case, the "seqid" is one greater than what the client has |
| 16581 |
recorded. This allows the client to disambiguate between the two |
| 16582 |
cases. The client thus knows precisely which possibility applies. |
| 16583 |
|
| 16584 |
In case 1, the client knows it needs to wait for the LAYOUTGET |
| 16585 |
response before processing the recall (or the client can return |
| 16586 |
NFS4ERR_DELAY). |
| 16587 |
|
| 16588 |
In case 2, the client will not wait for the LAYOUTGET response before |
| 16589 |
processing the recall because waiting would cause deadlock. |
| 16590 |
Therefore, the action at the client will only require waiting in the |
| 16591 |
case that the client has not yet seen the server's earlier responses |
| 16592 |
to the LAYOUTGET operation(s). |
| 16593 |
|
| 16594 |
The recall process can be considered completed when the final |
| 16595 |
LAYOUTRETURN operation for the recalled range is completed. The |
| 16596 |
LAYOUTRETURN uses the layout stateid (with seqid) specified in |
| 16597 |
CB_LAYOUTRECALL. If the client uses multiple LAYOUTRETURNs in |
| 16598 |
processing the recall, the first LAYOUTRETURN will use the layout |
| 16599 |
stateid as specified in CB_LAYOUTRECALL. Subsequent LAYOUTRETURNs |
| 16600 |
will use the highest seqid as is the usual case. |
| 16601 |
|
| 16602 |
<span class="h6"><a class="selflink" id="section-12.5.5.2.1.3" href="#section-12.5.5.2.1.3">12.5.5.2.1.3</a>. Server Considerations</span> |
| 16603 |
|
| 16604 |
Consider a race from the metadata server's point of view. The |
| 16605 |
metadata server has sent a CB_LAYOUTRECALL and receives an |
| 16606 |
overlapping LAYOUTGET for the same file before the LAYOUTRETURN(s) |
| 16607 |
that respond to the CB_LAYOUTRECALL. There are three cases: |
| 16608 |
|
| 16609 |
1. The client sent the LAYOUTGET before processing the |
| 16610 |
CB_LAYOUTRECALL. The "seqid" in the layout stateid of the |
| 16611 |
arguments of LAYOUTGET is one less than the "seqid" in |
| 16612 |
CB_LAYOUTRECALL. The server returns NFS4ERR_RECALLCONFLICT to |
| 16613 |
the client, which indicates to the client that there is a pending |
| 16614 |
recall. |
| 16615 |
|
| 16616 |
2. The client sent the LAYOUTGET after processing the |
| 16617 |
CB_LAYOUTRECALL, but the LAYOUTGET arrived before the |
| 16618 |
LAYOUTRETURN and the response to CB_LAYOUTRECALL that completed |
| 16619 |
that processing. The "seqid" in the layout stateid of LAYOUTGET |
| 16620 |
is equal to or greater than that of the "seqid" in |
| 16621 |
CB_LAYOUTRECALL. The server has not received a response to the |
| 16622 |
CB_LAYOUTRECALL, so it returns NFS4ERR_RECALLCONFLICT. |
| 16623 |
|
| 16624 |
3. The client sent the LAYOUTGET after processing the |
| 16625 |
|
| 16626 |
|
| 16627 |
|
| 16628 |
<span class="grey">Shepler, et al. Standards Track [Page 297]</span></pre> |
| 16629 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-298" ></span> |
| 16630 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16631 |
|
| 16632 |
|
| 16633 |
CB_LAYOUTRECALL; the server received the CB_LAYOUTRECALL |
| 16634 |
response, but the LAYOUTGET arrived before the LAYOUTRETURN that |
| 16635 |
completed that processing. The "seqid" in the layout stateid of |
| 16636 |
LAYOUTGET is equal to that of the "seqid" in CB_LAYOUTRECALL. |
| 16637 |
|
| 16638 |
The server has received a response to the CB_LAYOUTRECALL, so it |
| 16639 |
returns NFS4ERR_RETURNCONFLICT. |
| 16640 |
|
| 16641 |
<span class="h6"><a class="selflink" id="section-12.5.5.2.1.4" href="#section-12.5.5.2.1.4">12.5.5.2.1.4</a>. Wraparound and Validation of Seqid</span> |
| 16642 |
|
| 16643 |
The rules for layout stateid processing differ from other stateids in |
| 16644 |
the protocol because the "seqid" value cannot be zero and the |
| 16645 |
stateid's "seqid" value changes in a CB_LAYOUTRECALL operation. The |
| 16646 |
non-zero requirement combined with the inherent parallelism of layout |
| 16647 |
operations means that a set of LAYOUTGET and LAYOUTRETURN operations |
| 16648 |
may contain the same value for "seqid". The server uses a slightly |
| 16649 |
modified version of the modulo arithmetic as described in |
| 16650 |
<a href="#section-2.10.6.1">Section 2.10.6.1</a> when incrementing the layout stateid's "seqid". The |
| 16651 |
difference is that zero is not a valid value for "seqid"; when the |
| 16652 |
value of a "seqid" is 0xFFFFFFFF, the next valid value will be |
| 16653 |
0x00000001. The modulo arithmetic is also used for the comparisons |
| 16654 |
of "seqid" values in the processing of CB_LAYOUTRECALL events as |
| 16655 |
described above in <a href="#section-12.5.5.2.1.3">Section 12.5.5.2.1.3</a>. |
| 16656 |
|
| 16657 |
Just as the server validates the "seqid" in the event of |
| 16658 |
CB_LAYOUTRECALL usage, as described in <a href="#section-12.5.5.2.1.3">Section 12.5.5.2.1.3</a>, the |
| 16659 |
server also validates the "seqid" value to ensure that it is within |
| 16660 |
an appropriate range. This range represents the degree of |
| 16661 |
parallelism the server supports for layout stateids. If the client |
| 16662 |
is sending multiple layout operations to the server in parallel, by |
| 16663 |
definition, the "seqid" value in the supplied stateid will not be the |
| 16664 |
current "seqid" as held by the server. The range of parallelism |
| 16665 |
spans from the highest or current "seqid" to a "seqid" value in the |
| 16666 |
past. To assist in the discussion, the server's current "seqid" |
| 16667 |
value for a layout stateid is defined as SERVER_CURRENT_SEQID. The |
| 16668 |
lowest "seqid" value that is acceptable to the server is represented |
| 16669 |
by PAST_SEQID. And the value for the range of valid "seqid"s or |
| 16670 |
range of parallelism is VALID_SEQID_RANGE. Therefore, the following |
| 16671 |
holds: VALID_SEQID_RANGE = SERVER_CURRENT_SEQID - PAST_SEQID. In the |
| 16672 |
following, all arithmetic is the modulo arithmetic as described |
| 16673 |
above. |
| 16674 |
|
| 16675 |
The server MUST support a minimum VALID_SEQID_RANGE. The minimum is |
| 16676 |
defined as: VALID_SEQID_RANGE = summation over 1..N of |
| 16677 |
(ca_maxoperations(i) - 1), where N is the number of session fore |
| 16678 |
channels and ca_maxoperations(i) is the value of the ca_maxoperations |
| 16679 |
returned from CREATE_SESSION of the i'th session. The reason for "- |
| 16680 |
1" is to allow for the required SEQUENCE operation. The server MAY |
| 16681 |
|
| 16682 |
|
| 16683 |
|
| 16684 |
<span class="grey">Shepler, et al. Standards Track [Page 298]</span></pre> |
| 16685 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-299" ></span> |
| 16686 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16687 |
|
| 16688 |
|
| 16689 |
support a VALID_SEQID_RANGE value larger than the minimum. The |
| 16690 |
maximum VALID_SEQID_RANGE is (2 ^ 32 - 2) (accounting for zero not |
| 16691 |
being a valid "seqid" value). |
| 16692 |
|
| 16693 |
If the server finds the "seqid" is zero, the NFS4ERR_BAD_STATEID |
| 16694 |
error is returned to the client. The server further validates the |
| 16695 |
"seqid" to ensure it is within the range of parallelism, |
| 16696 |
VALID_SEQID_RANGE. If the "seqid" value is outside of that range, |
| 16697 |
the error NFS4ERR_OLD_STATEID is returned to the client. Upon |
| 16698 |
receipt of NFS4ERR_OLD_STATEID, the client updates the stateid in the |
| 16699 |
layout request based on processing of other layout requests and re- |
| 16700 |
sends the operation to the server. |
| 16701 |
|
| 16702 |
<span class="h6"><a class="selflink" id="section-12.5.5.2.1.5" href="#section-12.5.5.2.1.5">12.5.5.2.1.5</a>. Bulk Recall and Return</span> |
| 16703 |
|
| 16704 |
pNFS supports recalling and returning all layouts that are for files |
| 16705 |
belonging to a particular fsid (LAYOUTRECALL4_FSID, |
| 16706 |
LAYOUTRETURN4_FSID) or client ID (LAYOUTRECALL4_ALL, |
| 16707 |
LAYOUTRETURN4_ALL). There are no "bulk" stateids, so detection of |
| 16708 |
races via the seqid is not possible. The server MUST NOT initiate |
| 16709 |
bulk recall while another recall is in progress, or the corresponding |
| 16710 |
LAYOUTRETURN is in progress or pending. In the event the server |
| 16711 |
sends a bulk recall while the client has a pending or in-progress |
| 16712 |
LAYOUTRETURN, CB_LAYOUTRECALL, or LAYOUTGET, the client returns |
| 16713 |
NFS4ERR_DELAY. In the event the client sends a LAYOUTGET or |
| 16714 |
LAYOUTRETURN while a bulk recall is in progress, the server returns |
| 16715 |
NFS4ERR_RECALLCONFLICT. If the client sends a LAYOUTGET or |
| 16716 |
LAYOUTRETURN after the server receives NFS4ERR_DELAY from a bulk |
| 16717 |
recall, then to ensure forward progress, the server MAY return |
| 16718 |
NFS4ERR_RECALLCONFLICT. |
| 16719 |
|
| 16720 |
Once a CB_LAYOUTRECALL of LAYOUTRECALL4_ALL is sent, the server MUST |
| 16721 |
NOT allow the client to use any layout stateid except for |
| 16722 |
LAYOUTCOMMIT operations. Once the client receives a CB_LAYOUTRECALL |
| 16723 |
of LAYOUTRECALL4_ALL, it MUST NOT use any layout stateid except for |
| 16724 |
LAYOUTCOMMIT operations. Once a LAYOUTRETURN of LAYOUTRETURN4_ALL is |
| 16725 |
sent, all layout stateids granted to the client ID are freed. The |
| 16726 |
client MUST NOT use the layout stateids again. It MUST use LAYOUTGET |
| 16727 |
to obtain new layout stateids. |
| 16728 |
|
| 16729 |
Once a CB_LAYOUTRECALL of LAYOUTRECALL4_FSID is sent, the server MUST |
| 16730 |
NOT allow the client to use any layout stateid that refers to a file |
| 16731 |
with the specified fsid except for LAYOUTCOMMIT operations. Once the |
| 16732 |
client receives a CB_LAYOUTRECALL of LAYOUTRECALL4_ALL, it MUST NOT |
| 16733 |
use any layout stateid that refers to a file with the specified fsid |
| 16734 |
except for LAYOUTCOMMIT operations. Once a LAYOUTRETURN of |
| 16735 |
LAYOUTRETURN4_FSID is sent, all layout stateids granted to the |
| 16736 |
referenced fsid are freed. The client MUST NOT use those freed |
| 16737 |
|
| 16738 |
|
| 16739 |
|
| 16740 |
<span class="grey">Shepler, et al. Standards Track [Page 299]</span></pre> |
| 16741 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-300" ></span> |
| 16742 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16743 |
|
| 16744 |
|
| 16745 |
layout stateids for files with the referenced fsid again. |
| 16746 |
Subsequently, for any file with the referenced fsid, to use a layout, |
| 16747 |
the client MUST first send a LAYOUTGET operation in order to obtain a |
| 16748 |
new layout stateid for that file. |
| 16749 |
|
| 16750 |
If the server has sent a bulk CB_LAYOUTRECALL and receives a |
| 16751 |
LAYOUTGET, or a LAYOUTRETURN with a stateid, the server MUST return |
| 16752 |
NFS4ERR_RECALLCONFLICT. If the server has sent a bulk |
| 16753 |
CB_LAYOUTRECALL and receives a LAYOUTRETURN with an lr_returntype |
| 16754 |
that is not equal to the lor_recalltype of the CB_LAYOUTRECALL, the |
| 16755 |
server MUST return NFS4ERR_RECALLCONFLICT. |
| 16756 |
|
| 16757 |
<span class="h4"><a class="selflink" id="section-12.5.6" href="#section-12.5.6">12.5.6</a>. Revoking Layouts</span> |
| 16758 |
|
| 16759 |
Parallel NFS permits servers to revoke layouts from clients that fail |
| 16760 |
to respond to recalls and/or fail to renew their lease in time. |
| 16761 |
Depending on the layout type, the server might revoke the layout and |
| 16762 |
might take certain actions with respect to the client's I/O to data |
| 16763 |
servers. |
| 16764 |
|
| 16765 |
<span class="h4"><a class="selflink" id="section-12.5.7" href="#section-12.5.7">12.5.7</a>. Metadata Server Write Propagation</span> |
| 16766 |
|
| 16767 |
Asynchronous writes written through the metadata server may be |
| 16768 |
propagated lazily to the storage devices. For data written |
| 16769 |
asynchronously through the metadata server, a client performing a |
| 16770 |
read at the appropriate storage device is not guaranteed to see the |
| 16771 |
newly written data until a COMMIT occurs at the metadata server. |
| 16772 |
While the write is pending, reads to the storage device may give out |
| 16773 |
either the old data, the new data, or a mixture of new and old. Upon |
| 16774 |
completion of a synchronous WRITE or COMMIT (for asynchronously |
| 16775 |
written data), the metadata server MUST ensure that storage devices |
| 16776 |
give out the new data and that the data has been written to stable |
| 16777 |
storage. If the server implements its storage in any way such that |
| 16778 |
it cannot obey these constraints, then it MUST recall the layouts to |
| 16779 |
prevent reads being done that cannot be handled correctly. Note that |
| 16780 |
the layouts MUST be recalled prior to the server responding to the |
| 16781 |
associated WRITE operations. |
| 16782 |
|
| 16783 |
<span class="h3"><a class="selflink" id="section-12.6" href="#section-12.6">12.6</a>. pNFS Mechanics</span> |
| 16784 |
|
| 16785 |
This section describes the operations flow taken by a pNFS client to |
| 16786 |
a metadata server and storage device. |
| 16787 |
|
| 16788 |
When a pNFS client encounters a new FSID, it sends a GETATTR to the |
| 16789 |
NFSv4.1 server for the fs_layout_type (<a href="#section-5.12.1">Section 5.12.1</a>) attribute. If |
| 16790 |
the attribute returns at least one layout type, and the layout types |
| 16791 |
returned are among the set supported by the client, the client knows |
| 16792 |
that pNFS is a possibility for the file system. If, from the server |
| 16793 |
|
| 16794 |
|
| 16795 |
|
| 16796 |
<span class="grey">Shepler, et al. Standards Track [Page 300]</span></pre> |
| 16797 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-301" ></span> |
| 16798 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16799 |
|
| 16800 |
|
| 16801 |
that returned the new FSID, the client does not have a client ID that |
| 16802 |
came from an EXCHANGE_ID result that returned |
| 16803 |
EXCHGID4_FLAG_USE_PNFS_MDS, it MUST send an EXCHANGE_ID to the server |
| 16804 |
with the EXCHGID4_FLAG_USE_PNFS_MDS bit set. If the server's |
| 16805 |
response does not have EXCHGID4_FLAG_USE_PNFS_MDS, then contrary to |
| 16806 |
what the fs_layout_type attribute said, the server does not support |
| 16807 |
pNFS, and the client will not be able use pNFS to that server; in |
| 16808 |
this case, the server MUST return NFS4ERR_NOTSUPP in response to any |
| 16809 |
pNFS operation. |
| 16810 |
|
| 16811 |
The client then creates a session, requesting a persistent session, |
| 16812 |
so that exclusive creates can be done with single round trip via the |
| 16813 |
createmode4 of GUARDED4. If the session ends up not being |
| 16814 |
persistent, the client will use EXCLUSIVE4_1 for exclusive creates. |
| 16815 |
|
| 16816 |
If a file is to be created on a pNFS-enabled file system, the client |
| 16817 |
uses the OPEN operation. With the normal set of attributes that may |
| 16818 |
be provided upon OPEN used for creation, there is an OPTIONAL |
| 16819 |
layout_hint attribute. The client's use of layout_hint allows the |
| 16820 |
client to express its preference for a layout type and its associated |
| 16821 |
layout details. The use of a createmode4 of UNCHECKED4, GUARDED4, or |
| 16822 |
EXCLUSIVE4_1 will allow the client to provide the layout_hint |
| 16823 |
attribute at create time. The client MUST NOT use EXCLUSIVE4 (see |
| 16824 |
Table 10). The client is RECOMMENDED to combine a GETATTR operation |
| 16825 |
after the OPEN within the same COMPOUND. The GETATTR may then |
| 16826 |
retrieve the layout_type attribute for the newly created file. The |
| 16827 |
client will then know what layout type the server has chosen for the |
| 16828 |
file and therefore what storage protocol the client must use. |
| 16829 |
|
| 16830 |
If the client wants to open an existing file, then it also includes a |
| 16831 |
GETATTR to determine what layout type the file supports. |
| 16832 |
|
| 16833 |
The GETATTR in either the file creation or plain file open case can |
| 16834 |
also include the layout_blksize and layout_alignment attributes so |
| 16835 |
that the client can determine optimal offsets and lengths for I/O on |
| 16836 |
the file. |
| 16837 |
|
| 16838 |
Assuming the client supports the layout type returned by GETATTR and |
| 16839 |
it chooses to use pNFS for data access, it then sends LAYOUTGET using |
| 16840 |
the filehandle and stateid returned by OPEN, specifying the range it |
| 16841 |
wants to do I/O on. The response is a layout, which may be a subset |
| 16842 |
of the range for which the client asked. It also includes device IDs |
| 16843 |
and a description of how data is organized (or in the case of |
| 16844 |
writing, how data is to be organized) across the devices. The device |
| 16845 |
IDs and data description are encoded in a format that is specific to |
| 16846 |
the layout type, but the client is expected to understand. |
| 16847 |
|
| 16848 |
|
| 16849 |
|
| 16850 |
|
| 16851 |
|
| 16852 |
<span class="grey">Shepler, et al. Standards Track [Page 301]</span></pre> |
| 16853 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-302" ></span> |
| 16854 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16855 |
|
| 16856 |
|
| 16857 |
When the client wants to send an I/O, it determines to which device |
| 16858 |
ID it needs to send the I/O command by examining the data description |
| 16859 |
in the layout. It then sends a GETDEVICEINFO to find the device |
| 16860 |
address(es) of the device ID. The client then sends the I/O request |
| 16861 |
to one of device ID's device addresses, using the storage protocol |
| 16862 |
defined for the layout type. Note that if a client has multiple I/Os |
| 16863 |
to send, these I/O requests may be done in parallel. |
| 16864 |
|
| 16865 |
If the I/O was a WRITE, then at some point the client may want to use |
| 16866 |
LAYOUTCOMMIT to commit the modification time and the new size of the |
| 16867 |
file (if it believes it extended the file size) to the metadata |
| 16868 |
server and the modified data to the file system. |
| 16869 |
|
| 16870 |
<span class="h3"><a class="selflink" id="section-12.7" href="#section-12.7">12.7</a>. Recovery</span> |
| 16871 |
|
| 16872 |
Recovery is complicated by the distributed nature of the pNFS |
| 16873 |
protocol. In general, crash recovery for layouts is similar to crash |
| 16874 |
recovery for delegations in the base NFSv4.1 protocol. However, the |
| 16875 |
client's ability to perform I/O without contacting the metadata |
| 16876 |
server introduces subtleties that must be handled correctly if the |
| 16877 |
possibility of file system corruption is to be avoided. |
| 16878 |
|
| 16879 |
<span class="h4"><a class="selflink" id="section-12.7.1" href="#section-12.7.1">12.7.1</a>. Recovery from Client Restart</span> |
| 16880 |
|
| 16881 |
Client recovery for layouts is similar to client recovery for other |
| 16882 |
lock and delegation state. When a pNFS client restarts, it will lose |
| 16883 |
all information about the layouts that it previously owned. There |
| 16884 |
are two methods by which the server can reclaim these resources and |
| 16885 |
allow otherwise conflicting layouts to be provided to other clients. |
| 16886 |
|
| 16887 |
The first is through the expiry of the client's lease. If the client |
| 16888 |
recovery time is longer than the lease period, the client's lease |
| 16889 |
will expire and the server will know that state may be released. For |
| 16890 |
layouts, the server may release the state immediately upon lease |
| 16891 |
expiry or it may allow the layout to persist, awaiting possible lease |
| 16892 |
revival, as long as no other layout conflicts. |
| 16893 |
|
| 16894 |
The second is through the client restarting in less time than it |
| 16895 |
takes for the lease period to expire. In such a case, the client |
| 16896 |
will contact the server through the standard EXCHANGE_ID protocol. |
| 16897 |
The server will find that the client's co_ownerid matches the |
| 16898 |
co_ownerid of the previous client invocation, but that the verifier |
| 16899 |
is different. The server uses this as a signal to release all layout |
| 16900 |
state associated with the client's previous invocation. In this |
| 16901 |
scenario, the data written by the client but not covered by a |
| 16902 |
successful LAYOUTCOMMIT is in an undefined state; it may have been |
| 16903 |
|
| 16904 |
|
| 16905 |
|
| 16906 |
|
| 16907 |
|
| 16908 |
<span class="grey">Shepler, et al. Standards Track [Page 302]</span></pre> |
| 16909 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-303" ></span> |
| 16910 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16911 |
|
| 16912 |
|
| 16913 |
written or it may now be lost. This is acceptable behavior and it is |
| 16914 |
the client's responsibility to use LAYOUTCOMMIT to achieve the |
| 16915 |
desired level of stability. |
| 16916 |
|
| 16917 |
<span class="h4"><a class="selflink" id="section-12.7.2" href="#section-12.7.2">12.7.2</a>. Dealing with Lease Expiration on the Client</span> |
| 16918 |
|
| 16919 |
If a client believes its lease has expired, it MUST NOT send I/O to |
| 16920 |
the storage device until it has validated its lease. The client can |
| 16921 |
send a SEQUENCE operation to the metadata server. If the SEQUENCE |
| 16922 |
operation is successful, but sr_status_flag has |
| 16923 |
SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED, |
| 16924 |
SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED, or |
| 16925 |
SEQ4_STATUS_ADMIN_STATE_REVOKED set, the client MUST NOT use |
| 16926 |
currently held layouts. The client has two choices to recover from |
| 16927 |
the lease expiration. First, for all modified but uncommitted data, |
| 16928 |
the client writes it to the metadata server using the FILE_SYNC4 flag |
| 16929 |
for the WRITEs, or WRITE and COMMIT. Second, the client re- |
| 16930 |
establishes a client ID and session with the server and obtains new |
| 16931 |
layouts and device-ID-to-device-address mappings for the modified |
| 16932 |
data ranges and then writes the data to the storage devices with the |
| 16933 |
newly obtained layouts. |
| 16934 |
|
| 16935 |
If sr_status_flags from the metadata server has |
| 16936 |
SEQ4_STATUS_RESTART_RECLAIM_NEEDED set (or SEQUENCE returns |
| 16937 |
NFS4ERR_BAD_SESSION and CREATE_SESSION returns |
| 16938 |
NFS4ERR_STALE_CLIENTID), then the metadata server has restarted, and |
| 16939 |
the client SHOULD recover using the methods described in |
| 16940 |
<a href="#section-12.7.4">Section 12.7.4</a>. |
| 16941 |
|
| 16942 |
If sr_status_flags from the metadata server has |
| 16943 |
SEQ4_STATUS_LEASE_MOVED set, then the client recovers by following |
| 16944 |
the procedure described in <a href="#section-11.7.7.1">Section 11.7.7.1</a>. After that, the client |
| 16945 |
may get an indication that the layout state was not moved with the |
| 16946 |
file system. The client recovers as in the other applicable |
| 16947 |
situations discussed in the first two paragraphs of this section. |
| 16948 |
|
| 16949 |
If sr_status_flags reports no loss of state, then the lease for the |
| 16950 |
layouts that the client has are valid and renewed, and the client can |
| 16951 |
once again send I/O requests to the storage devices. |
| 16952 |
|
| 16953 |
While clients SHOULD NOT send I/Os to storage devices that may extend |
| 16954 |
past the lease expiration time period, this is not always possible, |
| 16955 |
for example, an extended network partition that starts after the I/O |
| 16956 |
is sent and does not heal until the I/O request is received by the |
| 16957 |
storage device. Thus, the metadata server and/or storage devices are |
| 16958 |
responsible for protecting themselves from I/Os that are both sent |
| 16959 |
before the lease expires and arrive after the lease expires. See |
| 16960 |
<a href="#section-12.7.3">Section 12.7.3</a>. |
| 16961 |
|
| 16962 |
|
| 16963 |
|
| 16964 |
<span class="grey">Shepler, et al. Standards Track [Page 303]</span></pre> |
| 16965 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-304" ></span> |
| 16966 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 16967 |
|
| 16968 |
|
| 16969 |
<span class="h4"><a class="selflink" id="section-12.7.3" href="#section-12.7.3">12.7.3</a>. Dealing with Loss of Layout State on the Metadata Server</span> |
| 16970 |
|
| 16971 |
This is a description of the case where all of the following are |
| 16972 |
true: |
| 16973 |
|
| 16974 |
o the metadata server has not restarted |
| 16975 |
|
| 16976 |
o a pNFS client's layouts have been discarded (usually because the |
| 16977 |
client's lease expired) and are invalid |
| 16978 |
|
| 16979 |
o an I/O from the pNFS client arrives at the storage device |
| 16980 |
|
| 16981 |
The metadata server and its storage devices MUST solve this by |
| 16982 |
fencing the client. In other words, they MUST solve this by |
| 16983 |
preventing the execution of I/O operations from the client to the |
| 16984 |
storage devices after layout state loss. The details of how fencing |
| 16985 |
is done are specific to the layout type. The solution for NFSv4.1 |
| 16986 |
file-based layouts is described in (<a href="#section-13.11">Section 13.11</a>), and solutions for |
| 16987 |
other layout types are in their respective external specification |
| 16988 |
documents. |
| 16989 |
|
| 16990 |
<span class="h4"><a class="selflink" id="section-12.7.4" href="#section-12.7.4">12.7.4</a>. Recovery from Metadata Server Restart</span> |
| 16991 |
|
| 16992 |
The pNFS client will discover that the metadata server has restarted |
| 16993 |
via the methods described in <a href="#section-8.4.2">Section 8.4.2</a> and discussed in a pNFS- |
| 16994 |
specific context in Paragraph 2, of <a href="#section-12.7.2">Section 12.7.2</a>. The client MUST |
| 16995 |
stop using layouts and delete the device ID to device address |
| 16996 |
mappings it previously received from the metadata server. Having |
| 16997 |
done that, if the client wrote data to the storage device without |
| 16998 |
committing the layouts via LAYOUTCOMMIT, then the client has |
| 16999 |
additional work to do in order to have the client, metadata server, |
| 17000 |
and storage device(s) all synchronized on the state of the data. |
| 17001 |
|
| 17002 |
o If the client has data still modified and unwritten in the |
| 17003 |
client's memory, the client has only two choices. |
| 17004 |
|
| 17005 |
1. The client can obtain a layout via LAYOUTGET after the |
| 17006 |
server's grace period and write the data to the storage |
| 17007 |
devices. |
| 17008 |
|
| 17009 |
2. The client can WRITE that data through the metadata server |
| 17010 |
using the WRITE (<a href="#section-18.32">Section 18.32</a>) operation, and then obtain |
| 17011 |
layouts as desired. |
| 17012 |
|
| 17013 |
o If the client asynchronously wrote data to the storage device, but |
| 17014 |
still has a copy of the data in its memory, then it has available |
| 17015 |
to it the recovery options listed above in the previous bullet |
| 17016 |
|
| 17017 |
|
| 17018 |
|
| 17019 |
|
| 17020 |
<span class="grey">Shepler, et al. Standards Track [Page 304]</span></pre> |
| 17021 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-305" ></span> |
| 17022 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17023 |
|
| 17024 |
|
| 17025 |
point. If the metadata server is also in its grace period, the |
| 17026 |
client has available to it the options below in the next bullet |
| 17027 |
point. |
| 17028 |
|
| 17029 |
o The client does not have a copy of the data in its memory and the |
| 17030 |
metadata server is still in its grace period. The client cannot |
| 17031 |
use LAYOUTGET (within or outside the grace period) to reclaim a |
| 17032 |
layout because the contents of the response from LAYOUTGET may not |
| 17033 |
match what it had previously. The range might be different or the |
| 17034 |
client might get the same range but the content of the layout |
| 17035 |
might be different. Even if the content of the layout appears to |
| 17036 |
be the same, the device IDs may map to different device addresses, |
| 17037 |
and even if the device addresses are the same, the device |
| 17038 |
addresses could have been assigned to a different storage device. |
| 17039 |
The option of retrieving the data from the storage device and |
| 17040 |
writing it to the metadata server per the recovery scenario |
| 17041 |
described above is not available because, again, the mappings of |
| 17042 |
range to device ID, device ID to device address, and device |
| 17043 |
address to physical device are stale, and new mappings via new |
| 17044 |
LAYOUTGET do not solve the problem. |
| 17045 |
|
| 17046 |
The only recovery option for this scenario is to send a |
| 17047 |
LAYOUTCOMMIT in reclaim mode, which the metadata server will |
| 17048 |
accept as long as it is in its grace period. The use of |
| 17049 |
LAYOUTCOMMIT in reclaim mode informs the metadata server that the |
| 17050 |
layout has changed. It is critical that the metadata server |
| 17051 |
receive this information before its grace period ends, and thus |
| 17052 |
before it starts allowing updates to the file system. |
| 17053 |
|
| 17054 |
To send LAYOUTCOMMIT in reclaim mode, the client sets the |
| 17055 |
loca_reclaim field of the operation's arguments (<a href="#section-18.42.1">Section 18.42.1</a>) |
| 17056 |
to TRUE. During the metadata server's recovery grace period (and |
| 17057 |
only during the recovery grace period) the metadata server is |
| 17058 |
prepared to accept LAYOUTCOMMIT requests with the loca_reclaim |
| 17059 |
field set to TRUE. |
| 17060 |
|
| 17061 |
When loca_reclaim is TRUE, the client is attempting to commit |
| 17062 |
changes to the layout that occurred prior to the restart of the |
| 17063 |
metadata server. The metadata server applies some consistency |
| 17064 |
checks on the loca_layoutupdate field of the arguments to |
| 17065 |
determine whether the client can commit the data written to the |
| 17066 |
storage device to the file system. The loca_layoutupdate field is |
| 17067 |
of data type layoutupdate4 and contains layout-type-specific |
| 17068 |
content (in the lou_body field of loca_layoutupdate). The layout- |
| 17069 |
type-specific information that loca_layoutupdate might have is |
| 17070 |
discussed in <a href="#section-12.5.4.3">Section 12.5.4.3</a>. If the metadata server's |
| 17071 |
consistency checks on loca_layoutupdate succeed, then the metadata |
| 17072 |
server MUST commit the data (as described by the loca_offset, |
| 17073 |
|
| 17074 |
|
| 17075 |
|
| 17076 |
<span class="grey">Shepler, et al. Standards Track [Page 305]</span></pre> |
| 17077 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-306" ></span> |
| 17078 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17079 |
|
| 17080 |
|
| 17081 |
loca_length, and loca_layoutupdate fields of the arguments) that |
| 17082 |
was written to the storage device. If the metadata server's |
| 17083 |
consistency checks on loca_layoutupdate fail, the metadata server |
| 17084 |
rejects the LAYOUTCOMMIT operation and makes no changes to the |
| 17085 |
file system. However, any time LAYOUTCOMMIT with loca_reclaim |
| 17086 |
TRUE fails, the pNFS client has lost all the data in the range |
| 17087 |
defined by <loca_offset, loca_length>. A client can defend |
| 17088 |
against this risk by caching all data, whether written |
| 17089 |
synchronously or asynchronously in its memory, and by not |
| 17090 |
releasing the cached data until a successful LAYOUTCOMMIT. This |
| 17091 |
condition does not hold true for all layout types; for example, |
| 17092 |
file-based storage devices need not suffer from this limitation. |
| 17093 |
|
| 17094 |
o The client does not have a copy of the data in its memory and the |
| 17095 |
metadata server is no longer in its grace period; i.e., the |
| 17096 |
metadata server returns NFS4ERR_NO_GRACE. As with the scenario in |
| 17097 |
the above bullet point, the failure of LAYOUTCOMMIT means the data |
| 17098 |
in the range <loca_offset, loca_length> lost. The defense against |
| 17099 |
the risk is the same -- cache all written data on the client until |
| 17100 |
a successful LAYOUTCOMMIT. |
| 17101 |
|
| 17102 |
<span class="h4"><a class="selflink" id="section-12.7.5" href="#section-12.7.5">12.7.5</a>. Operations during Metadata Server Grace Period</span> |
| 17103 |
|
| 17104 |
Some of the recovery scenarios thus far noted that some operations |
| 17105 |
(namely, WRITE and LAYOUTGET) might be permitted during the metadata |
| 17106 |
server's grace period. The metadata server may allow these |
| 17107 |
operations during its grace period. For LAYOUTGET, the metadata |
| 17108 |
server must reliably determine that servicing such a request will not |
| 17109 |
conflict with an impending LAYOUTCOMMIT reclaim request. For WRITE, |
| 17110 |
the metadata server must reliably determine that servicing the |
| 17111 |
request will not conflict with an impending OPEN or with a LOCK where |
| 17112 |
the file has mandatory byte-range locking enabled. |
| 17113 |
|
| 17114 |
As mentioned previously, for expediency, the metadata server might |
| 17115 |
reject some operations (namely, WRITE and LAYOUTGET) during its grace |
| 17116 |
period, because the simplest correct approach is to reject all non- |
| 17117 |
reclaim pNFS requests and WRITE operations by returning the |
| 17118 |
NFS4ERR_GRACE error. However, depending on the storage protocol |
| 17119 |
(which is specific to the layout type) and metadata server |
| 17120 |
implementation, the metadata server may be able to determine that a |
| 17121 |
particular request is safe. For example, a metadata server may save |
| 17122 |
provisional allocation mappings for each file to stable storage, as |
| 17123 |
well as information about potentially conflicting OPEN share modes |
| 17124 |
and mandatory byte-range locks that might have been in effect at the |
| 17125 |
time of restart, and the metadata server may use this information |
| 17126 |
during the recovery grace period to determine that a WRITE request is |
| 17127 |
safe. |
| 17128 |
|
| 17129 |
|
| 17130 |
|
| 17131 |
|
| 17132 |
<span class="grey">Shepler, et al. Standards Track [Page 306]</span></pre> |
| 17133 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-307" ></span> |
| 17134 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17135 |
|
| 17136 |
|
| 17137 |
<span class="h4"><a class="selflink" id="section-12.7.6" href="#section-12.7.6">12.7.6</a>. Storage Device Recovery</span> |
| 17138 |
|
| 17139 |
Recovery from storage device restart is mostly dependent upon the |
| 17140 |
layout type in use. However, there are a few general techniques a |
| 17141 |
client can use if it discovers a storage device has crashed while |
| 17142 |
holding modified, uncommitted data that was asynchronously written. |
| 17143 |
First and foremost, it is important to realize that the client is the |
| 17144 |
only one that has the information necessary to recover non-committed |
| 17145 |
data since it holds the modified data and probably nothing else does. |
| 17146 |
Second, the best solution is for the client to err on the side of |
| 17147 |
caution and attempt to rewrite the modified data through another |
| 17148 |
path. |
| 17149 |
|
| 17150 |
The client SHOULD immediately WRITE the data to the metadata server, |
| 17151 |
with the stable field in the WRITE4args set to FILE_SYNC4. Once it |
| 17152 |
does this, there is no need to wait for the original storage device. |
| 17153 |
|
| 17154 |
<span class="h3"><a class="selflink" id="section-12.8" href="#section-12.8">12.8</a>. Metadata and Storage Device Roles</span> |
| 17155 |
|
| 17156 |
If the same physical hardware is used to implement both a metadata |
| 17157 |
server and storage device, then the same hardware entity is to be |
| 17158 |
understood to be implementing two distinct roles and it is important |
| 17159 |
that it be clearly understood on behalf of which role the hardware is |
| 17160 |
executing at any given time. |
| 17161 |
|
| 17162 |
Two sub-cases can be distinguished. |
| 17163 |
|
| 17164 |
1. The storage device uses NFSv4.1 as the storage protocol, i.e., |
| 17165 |
the same physical hardware is used to implement both a metadata |
| 17166 |
and data server. See <a href="#section-13.1">Section 13.1</a> for a description of how |
| 17167 |
multiple roles are handled. |
| 17168 |
|
| 17169 |
2. The storage device does not use NFSv4.1 as the storage protocol, |
| 17170 |
and the same physical hardware is used to implement both a |
| 17171 |
metadata and storage device. Whether distinct network addresses |
| 17172 |
are used to access the metadata server and storage device is |
| 17173 |
immaterial. This is because it is always clear to the pNFS |
| 17174 |
client and server, from the upper-layer protocol being used |
| 17175 |
(NFSv4.1 or non-NFSv4.1), to which role the request to the common |
| 17176 |
server network address is directed. |
| 17177 |
|
| 17178 |
<span class="h3"><a class="selflink" id="section-12.9" href="#section-12.9">12.9</a>. Security Considerations for pNFS</span> |
| 17179 |
|
| 17180 |
pNFS separates file system metadata and data and provides access to |
| 17181 |
both. There are pNFS-specific operations (listed in <a href="#section-12.3">Section 12.3</a>) |
| 17182 |
that provide access to the metadata; all existing NFSv4.1 |
| 17183 |
conventional (non-pNFS) security mechanisms and features apply to |
| 17184 |
accessing the metadata. The combination of components in a pNFS |
| 17185 |
|
| 17186 |
|
| 17187 |
|
| 17188 |
<span class="grey">Shepler, et al. Standards Track [Page 307]</span></pre> |
| 17189 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-308" ></span> |
| 17190 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17191 |
|
| 17192 |
|
| 17193 |
system (see Figure 1) is required to preserve the security properties |
| 17194 |
of NFSv4.1 with respect to an entity that is accessing a storage |
| 17195 |
device from a client, including security countermeasures to defend |
| 17196 |
against threats for which NFSv4.1 provides defenses in environments |
| 17197 |
where these threats are considered significant. |
| 17198 |
|
| 17199 |
In some cases, the security countermeasures for connections to |
| 17200 |
storage devices may take the form of physical isolation or a |
| 17201 |
recommendation to avoid the use of pNFS in an environment. For |
| 17202 |
example, it may be impractical to provide confidentiality protection |
| 17203 |
for some storage protocols to protect against eavesdropping. In |
| 17204 |
environments where eavesdropping on such protocols is of sufficient |
| 17205 |
concern to require countermeasures, physical isolation of the |
| 17206 |
communication channel (e.g., via direct connection from client(s) to |
| 17207 |
storage device(s)) and/or a decision to forgo use of pNFS (e.g., and |
| 17208 |
fall back to conventional NFSv4.1) may be appropriate courses of |
| 17209 |
action. |
| 17210 |
|
| 17211 |
Where communication with storage devices is subject to the same |
| 17212 |
threats as client-to-metadata server communication, the protocols |
| 17213 |
used for that communication need to provide security mechanisms as |
| 17214 |
strong as or no weaker than those available via RPCSEC_GSS for |
| 17215 |
NFSv4.1. Except for the storage protocol used for the |
| 17216 |
LAYOUT4_NFSV4_1_FILES layout (see <a href="#section-13">Section 13</a>), i.e., except for |
| 17217 |
NFSv4.1, it is beyond the scope of this document to specify the |
| 17218 |
security mechanisms for storage access protocols. |
| 17219 |
|
| 17220 |
pNFS implementations MUST NOT remove NFSv4.1's access controls. The |
| 17221 |
combination of clients, storage devices, and the metadata server are |
| 17222 |
responsible for ensuring that all client-to-storage-device file data |
| 17223 |
access respects NFSv4.1's ACLs and file open modes. This entails |
| 17224 |
performing both of these checks on every access in the client, the |
| 17225 |
storage device, or both (as applicable; when the storage device is an |
| 17226 |
NFSv4.1 server, the storage device is ultimately responsible for |
| 17227 |
controlling access as described in <a href="#section-13.9.2">Section 13.9.2</a>). If a pNFS |
| 17228 |
configuration performs these checks only in the client, the risk of a |
| 17229 |
misbehaving client obtaining unauthorized access is an important |
| 17230 |
consideration in determining when it is appropriate to use such a |
| 17231 |
pNFS configuration. Such layout types SHOULD NOT be used when |
| 17232 |
client-only access checks do not provide sufficient assurance that |
| 17233 |
NFSv4.1 access control is being applied correctly. (This is not a |
| 17234 |
problem for the file layout type described in <a href="#section-13">Section 13</a> because the |
| 17235 |
storage access protocol for LAYOUT4_NFSV4_1_FILES is NFSv4.1, and |
| 17236 |
thus the security model for storage device access via |
| 17237 |
LAYOUT4_NFSv4_1_FILES is the same as that of the metadata server.) |
| 17238 |
For handling of access control specific to a layout, the reader |
| 17239 |
|
| 17240 |
|
| 17241 |
|
| 17242 |
|
| 17243 |
|
| 17244 |
<span class="grey">Shepler, et al. Standards Track [Page 308]</span></pre> |
| 17245 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-309" ></span> |
| 17246 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17247 |
|
| 17248 |
|
| 17249 |
should examine the layout specification, such as the NFSv4.1/ |
| 17250 |
file-based layout (<a href="#section-13">Section 13</a>) of this document, the blocks layout |
| 17251 |
[<a href="#ref-41" title=""Parallel NFS (pNFS) Block/Volume Layout"">41</a>], and objects layout [<a href="#ref-40" title=""Object-Based Parallel NFS (pNFS) Operations"">40</a>]. |
| 17252 |
|
| 17253 |
<span class="h2"><a class="selflink" id="section-13" href="#section-13">13</a>. NFSv4.1 as a Storage Protocol in pNFS: the File Layout Type</span> |
| 17254 |
|
| 17255 |
This section describes the semantics and format of NFSv4.1 file-based |
| 17256 |
layouts for pNFS. NFSv4.1 file-based layouts use the |
| 17257 |
LAYOUT4_NFSV4_1_FILES layout type. The LAYOUT4_NFSV4_1_FILES type |
| 17258 |
defines striping data across multiple NFSv4.1 data servers. |
| 17259 |
|
| 17260 |
<span class="h3"><a class="selflink" id="section-13.1" href="#section-13.1">13.1</a>. Client ID and Session Considerations</span> |
| 17261 |
|
| 17262 |
Sessions are a REQUIRED feature of NFSv4.1, and this extends to both |
| 17263 |
the metadata server and file-based (NFSv4.1-based) data servers. |
| 17264 |
|
| 17265 |
The role a server plays in pNFS is determined by the result it |
| 17266 |
returns from EXCHANGE_ID. The roles are: |
| 17267 |
|
| 17268 |
o Metadata server (EXCHGID4_FLAG_USE_PNFS_MDS is set in the result |
| 17269 |
eir_flags). |
| 17270 |
|
| 17271 |
o Data server (EXCHGID4_FLAG_USE_PNFS_DS). |
| 17272 |
|
| 17273 |
o Non-metadata server (EXCHGID4_FLAG_USE_NON_PNFS). This is an |
| 17274 |
NFSv4.1 server that does not support operations (e.g., LAYOUTGET) |
| 17275 |
or attributes that pertain to pNFS. |
| 17276 |
|
| 17277 |
The client MAY request zero or more of EXCHGID4_FLAG_USE_NON_PNFS, |
| 17278 |
EXCHGID4_FLAG_USE_PNFS_DS, or EXCHGID4_FLAG_USE_PNFS_MDS, even though |
| 17279 |
some combinations (e.g., EXCHGID4_FLAG_USE_NON_PNFS | |
| 17280 |
EXCHGID4_FLAG_USE_PNFS_MDS) are contradictory. However, the server |
| 17281 |
MUST only return the following acceptable combinations: |
| 17282 |
|
| 17283 |
+--------------------------------------------------------+ |
| 17284 |
| Acceptable Results from EXCHANGE_ID | |
| 17285 |
+--------------------------------------------------------+ |
| 17286 |
| EXCHGID4_FLAG_USE_PNFS_MDS | |
| 17287 |
| EXCHGID4_FLAG_USE_PNFS_MDS | EXCHGID4_FLAG_USE_PNFS_DS | |
| 17288 |
| EXCHGID4_FLAG_USE_PNFS_DS | |
| 17289 |
| EXCHGID4_FLAG_USE_NON_PNFS | |
| 17290 |
| EXCHGID4_FLAG_USE_PNFS_DS | EXCHGID4_FLAG_USE_NON_PNFS | |
| 17291 |
+--------------------------------------------------------+ |
| 17292 |
|
| 17293 |
As the above table implies, a server can have one or two roles. A |
| 17294 |
server can be both a metadata server and a data server, or it can be |
| 17295 |
both a data server and non-metadata server. In addition to returning |
| 17296 |
two roles in the EXCHANGE_ID's results, and thus serving both roles |
| 17297 |
|
| 17298 |
|
| 17299 |
|
| 17300 |
<span class="grey">Shepler, et al. Standards Track [Page 309]</span></pre> |
| 17301 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-310" ></span> |
| 17302 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17303 |
|
| 17304 |
|
| 17305 |
via a common client ID, a server can serve two roles by returning a |
| 17306 |
unique client ID and server owner for each role in each of two |
| 17307 |
EXCHANGE_ID results, with each result indicating each role. |
| 17308 |
|
| 17309 |
In the case of a server with concurrent pNFS roles that are served by |
| 17310 |
a common client ID, if the EXCHANGE_ID request from the client has |
| 17311 |
zero or a combination of the bits set in eia_flags, the server result |
| 17312 |
should set bits that represent the higher of the acceptable |
| 17313 |
combination of the server roles, with a preference to match the roles |
| 17314 |
requested by the client. Thus, if a client request has |
| 17315 |
(EXCHGID4_FLAG_USE_NON_PNFS | EXCHGID4_FLAG_USE_PNFS_MDS | |
| 17316 |
EXCHGID4_FLAG_USE_PNFS_DS) flags set, and the server is both a |
| 17317 |
metadata server and a data server, serving both the roles by a common |
| 17318 |
client ID, the server SHOULD return with (EXCHGID4_FLAG_USE_PNFS_MDS |
| 17319 |
| EXCHGID4_FLAG_USE_PNFS_DS) set. |
| 17320 |
|
| 17321 |
In the case of a server that has multiple concurrent pNFS roles, each |
| 17322 |
role served by a unique client ID, if the client specifies zero or a |
| 17323 |
combination of roles in the request, the server results SHOULD return |
| 17324 |
only one of the roles from the combination specified by the client |
| 17325 |
request. If the role specified by the server result does not match |
| 17326 |
the intended use by the client, the client should send the |
| 17327 |
EXCHANGE_ID specifying just the interested pNFS role. |
| 17328 |
|
| 17329 |
If a pNFS metadata client gets a layout that refers it to an NFSv4.1 |
| 17330 |
data server, it needs a client ID on that data server. If it does |
| 17331 |
not yet have a client ID from the server that had the |
| 17332 |
EXCHGID4_FLAG_USE_PNFS_DS flag set in the EXCHANGE_ID results, then |
| 17333 |
the client needs to send an EXCHANGE_ID to the data server, using the |
| 17334 |
same co_ownerid as it sent to the metadata server, with the |
| 17335 |
EXCHGID4_FLAG_USE_PNFS_DS flag set in the arguments. If the server's |
| 17336 |
EXCHANGE_ID results have EXCHGID4_FLAG_USE_PNFS_DS set, then the |
| 17337 |
client may use the client ID to create sessions that will exchange |
| 17338 |
pNFS data operations. The client ID returned by the data server has |
| 17339 |
no relationship with the client ID returned by a metadata server |
| 17340 |
unless the client IDs are equal, and the server owners and server |
| 17341 |
scopes of the data server and metadata server are equal. |
| 17342 |
|
| 17343 |
In NFSv4.1, the session ID in the SEQUENCE operation implies the |
| 17344 |
client ID, which in turn might be used by the server to map the |
| 17345 |
stateid to the right client/server pair. However, when a data server |
| 17346 |
is presented with a READ or WRITE operation with a stateid, because |
| 17347 |
the stateid is associated with a client ID on a metadata server, and |
| 17348 |
because the session ID in the preceding SEQUENCE operation is tied to |
| 17349 |
the client ID of the data server, the data server has no obvious way |
| 17350 |
to determine the metadata server from the COMPOUND procedure, and |
| 17351 |
|
| 17352 |
|
| 17353 |
|
| 17354 |
|
| 17355 |
|
| 17356 |
<span class="grey">Shepler, et al. Standards Track [Page 310]</span></pre> |
| 17357 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-311" ></span> |
| 17358 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17359 |
|
| 17360 |
|
| 17361 |
thus has no way to validate the stateid. One RECOMMENDED approach is |
| 17362 |
for pNFS servers to encode metadata server routing and/or identity |
| 17363 |
information in the data server filehandles as returned in the layout. |
| 17364 |
|
| 17365 |
If metadata server routing and/or identity information is encoded in |
| 17366 |
data server filehandles, when the metadata server identity or |
| 17367 |
location changes, the data server filehandles it gave out will become |
| 17368 |
invalid (stale), and so the metadata server MUST first recall the |
| 17369 |
layouts. Invalidating a data server filehandle does not render the |
| 17370 |
NFS client's data cache invalid. The client's cache should map a |
| 17371 |
data server filehandle to a metadata server filehandle, and a |
| 17372 |
metadata server filehandle to cached data. |
| 17373 |
|
| 17374 |
If a server is both a metadata server and a data server, the server |
| 17375 |
might need to distinguish operations on files that are directed to |
| 17376 |
the metadata server from those that are directed to the data server. |
| 17377 |
It is RECOMMENDED that the values of the filehandles returned by the |
| 17378 |
LAYOUTGET operation be different than the value of the filehandle |
| 17379 |
returned by the OPEN of the same file. |
| 17380 |
|
| 17381 |
Another scenario is for the metadata server and the storage device to |
| 17382 |
be distinct from one client's point of view, and the roles reversed |
| 17383 |
from another client's point of view. For example, in the cluster |
| 17384 |
file system model, a metadata server to one client might be a data |
| 17385 |
server to another client. If NFSv4.1 is being used as the storage |
| 17386 |
protocol, then pNFS servers need to encode the values of filehandles |
| 17387 |
according to their specific roles. |
| 17388 |
|
| 17389 |
<span class="h4"><a class="selflink" id="section-13.1.1" href="#section-13.1.1">13.1.1</a>. Sessions Considerations for Data Servers</span> |
| 17390 |
|
| 17391 |
<a href="#section-2.10.11.2">Section 2.10.11.2</a> states that a client has to keep its lease renewed |
| 17392 |
in order to prevent a session from being deleted by the server. If |
| 17393 |
the reply to EXCHANGE_ID has just the EXCHGID4_FLAG_USE_PNFS_DS role |
| 17394 |
set, then (as noted in <a href="#section-13.6">Section 13.6</a>) the client will not be able to |
| 17395 |
determine the data server's lease_time attribute because GETATTR will |
| 17396 |
not be permitted. Instead, the rule is that any time a client |
| 17397 |
receives a layout referring it to a data server that returns just the |
| 17398 |
EXCHGID4_FLAG_USE_PNFS_DS role, the client MAY assume that the |
| 17399 |
lease_time attribute from the metadata server that returned the |
| 17400 |
layout applies to the data server. Thus, the data server MUST be |
| 17401 |
aware of the values of all lease_time attributes of all metadata |
| 17402 |
servers for which it is providing I/O, and it MUST use the maximum of |
| 17403 |
all such lease_time values as the lease interval for all client IDs |
| 17404 |
and sessions established on it. |
| 17405 |
|
| 17406 |
For example, if one metadata server has a lease_time attribute of 20 |
| 17407 |
seconds, and a second metadata server has a lease_time attribute of |
| 17408 |
10 seconds, then if both servers return layouts that refer to an |
| 17409 |
|
| 17410 |
|
| 17411 |
|
| 17412 |
<span class="grey">Shepler, et al. Standards Track [Page 311]</span></pre> |
| 17413 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-312" ></span> |
| 17414 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17415 |
|
| 17416 |
|
| 17417 |
EXCHGID4_FLAG_USE_PNFS_DS-only data server, the data server MUST |
| 17418 |
renew a client's lease if the interval between two SEQUENCE |
| 17419 |
operations on different COMPOUND requests is less than 20 seconds. |
| 17420 |
|
| 17421 |
<span class="h3"><a class="selflink" id="section-13.2" href="#section-13.2">13.2</a>. File Layout Definitions</span> |
| 17422 |
|
| 17423 |
The following definitions apply to the LAYOUT4_NFSV4_1_FILES layout |
| 17424 |
type and may be applicable to other layout types. |
| 17425 |
|
| 17426 |
Unit. A unit is a fixed-size quantity of data written to a data |
| 17427 |
server. |
| 17428 |
|
| 17429 |
Pattern. A pattern is a method of distributing one or more equal |
| 17430 |
sized units across a set of data servers. A pattern is iterated |
| 17431 |
one or more times. |
| 17432 |
|
| 17433 |
Stripe. A stripe is a set of data distributed across a set of data |
| 17434 |
servers in a pattern before that pattern repeats. |
| 17435 |
|
| 17436 |
Stripe Count. A stripe count is the number of units in a pattern. |
| 17437 |
|
| 17438 |
Stripe Width. A stripe width is the size of a stripe in bytes. The |
| 17439 |
stripe width = the stripe count * the size of the stripe unit. |
| 17440 |
|
| 17441 |
Hereafter, this document will refer to a unit that is a written in a |
| 17442 |
pattern as a "stripe unit". |
| 17443 |
|
| 17444 |
A pattern may have more stripe units than data servers. If so, some |
| 17445 |
data servers will have more than one stripe unit per stripe. A data |
| 17446 |
server that has multiple stripe units per stripe MAY store each unit |
| 17447 |
in a different data file (and depending on the implementation, will |
| 17448 |
possibly assign a unique data filehandle to each data file). |
| 17449 |
|
| 17450 |
<span class="h3"><a class="selflink" id="section-13.3" href="#section-13.3">13.3</a>. File Layout Data Types</span> |
| 17451 |
|
| 17452 |
The high level NFSv4.1 layout types are nfsv4_1_file_layouthint4, |
| 17453 |
nfsv4_1_file_layout_ds_addr4, and nfsv4_1_file_layout4. |
| 17454 |
|
| 17455 |
The SETATTR operation supports a layout hint attribute |
| 17456 |
(<a href="#section-5.12.4">Section 5.12.4</a>). When the client sets a layout hint (data type |
| 17457 |
layouthint4) with a layout type of LAYOUT4_NFSV4_1_FILES (the |
| 17458 |
loh_type field), the loh_body field contains a value of data type |
| 17459 |
nfsv4_1_file_layouthint4. |
| 17460 |
|
| 17461 |
|
| 17462 |
|
| 17463 |
|
| 17464 |
|
| 17465 |
|
| 17466 |
|
| 17467 |
|
| 17468 |
<span class="grey">Shepler, et al. Standards Track [Page 312]</span></pre> |
| 17469 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-313" ></span> |
| 17470 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17471 |
|
| 17472 |
|
| 17473 |
const NFL4_UFLG_MASK = 0x0000003F; |
| 17474 |
const NFL4_UFLG_DENSE = 0x00000001; |
| 17475 |
const NFL4_UFLG_COMMIT_THRU_MDS = 0x00000002; |
| 17476 |
const NFL4_UFLG_STRIPE_UNIT_SIZE_MASK |
| 17477 |
= 0xFFFFFFC0; |
| 17478 |
|
| 17479 |
typedef uint32_t nfl_util4; |
| 17480 |
|
| 17481 |
enum filelayout_hint_care4 { |
| 17482 |
NFLH4_CARE_DENSE = NFL4_UFLG_DENSE, |
| 17483 |
|
| 17484 |
NFLH4_CARE_COMMIT_THRU_MDS |
| 17485 |
= NFL4_UFLG_COMMIT_THRU_MDS, |
| 17486 |
|
| 17487 |
NFLH4_CARE_STRIPE_UNIT_SIZE |
| 17488 |
= 0x00000040, |
| 17489 |
|
| 17490 |
NFLH4_CARE_STRIPE_COUNT = 0x00000080 |
| 17491 |
}; |
| 17492 |
|
| 17493 |
/* Encoded in the loh_body field of data type layouthint4: */ |
| 17494 |
|
| 17495 |
struct nfsv4_1_file_layouthint4 { |
| 17496 |
uint32_t nflh_care; |
| 17497 |
nfl_util4 nflh_util; |
| 17498 |
count4 nflh_stripe_count; |
| 17499 |
}; |
| 17500 |
|
| 17501 |
The generic layout hint structure is described in <a href="#section-3.3.19">Section 3.3.19</a>. |
| 17502 |
The client uses the layout hint in the layout_hint (<a href="#section-5.12.4">Section 5.12.4</a>) |
| 17503 |
attribute to indicate the preferred type of layout to be used for a |
| 17504 |
newly created file. The LAYOUT4_NFSV4_1_FILES layout-type-specific |
| 17505 |
content for the layout hint is composed of three fields. The first |
| 17506 |
field, nflh_care, is a set of flags indicating which values of the |
| 17507 |
hint the client cares about. If the NFLH4_CARE_DENSE flag is set, |
| 17508 |
then the client indicates in the second field, nflh_util, a |
| 17509 |
preference for how the data file is packed (<a href="#section-13.4.4">Section 13.4.4</a>), which is |
| 17510 |
controlled by the value of the expression nflh_util & NFL4_UFLG_DENSE |
| 17511 |
("&" represents the bitwise AND operator). If the |
| 17512 |
NFLH4_CARE_COMMIT_THRU_MDS flag is set, then the client indicates a |
| 17513 |
preference for whether the client should send COMMIT operations to |
| 17514 |
the metadata server or data server (<a href="#section-13.7">Section 13.7</a>), which is |
| 17515 |
controlled by the value of nflh_util & NFL4_UFLG_COMMIT_THRU_MDS. If |
| 17516 |
the NFLH4_CARE_STRIPE_UNIT_SIZE flag is set, the client indicates its |
| 17517 |
preferred stripe unit size, which is indicated in nflh_util & |
| 17518 |
NFL4_UFLG_STRIPE_UNIT_SIZE_MASK (thus, the stripe unit size MUST be a |
| 17519 |
multiple of 64 bytes). The minimum stripe unit size is 64 bytes. If |
| 17520 |
|
| 17521 |
|
| 17522 |
|
| 17523 |
|
| 17524 |
<span class="grey">Shepler, et al. Standards Track [Page 313]</span></pre> |
| 17525 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-314" ></span> |
| 17526 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17527 |
|
| 17528 |
|
| 17529 |
the NFLH4_CARE_STRIPE_COUNT flag is set, the client indicates in the |
| 17530 |
third field, nflh_stripe_count, the stripe count. The stripe count |
| 17531 |
multiplied by the stripe unit size is the stripe width. |
| 17532 |
|
| 17533 |
When LAYOUTGET returns a LAYOUT4_NFSV4_1_FILES layout (indicated in |
| 17534 |
the loc_type field of the lo_content field), the loc_body field of |
| 17535 |
the lo_content field contains a value of data type |
| 17536 |
nfsv4_1_file_layout4. Among other content, nfsv4_1_file_layout4 has |
| 17537 |
a storage device ID (field nfl_deviceid) of data type deviceid4. The |
| 17538 |
GETDEVICEINFO operation maps a device ID to a storage device address |
| 17539 |
(type device_addr4). When GETDEVICEINFO returns a device address |
| 17540 |
with a layout type of LAYOUT4_NFSV4_1_FILES (the da_layout_type |
| 17541 |
field), the da_addr_body field contains a value of data type |
| 17542 |
nfsv4_1_file_layout_ds_addr4. |
| 17543 |
|
| 17544 |
typedef netaddr4 multipath_list4<>; |
| 17545 |
|
| 17546 |
/* |
| 17547 |
* Encoded in the da_addr_body field of |
| 17548 |
* data type device_addr4: |
| 17549 |
*/ |
| 17550 |
struct nfsv4_1_file_layout_ds_addr4 { |
| 17551 |
uint32_t nflda_stripe_indices<>; |
| 17552 |
multipath_list4 nflda_multipath_ds_list<>; |
| 17553 |
}; |
| 17554 |
|
| 17555 |
The nfsv4_1_file_layout_ds_addr4 data type represents the device |
| 17556 |
address. It is composed of two fields: |
| 17557 |
|
| 17558 |
1. nflda_multipath_ds_list: An array of lists of data servers, where |
| 17559 |
each list can be one or more elements, and each element |
| 17560 |
represents a data server address that may serve equally as the |
| 17561 |
target of I/O operations (see <a href="#section-13.5">Section 13.5</a>). The length of this |
| 17562 |
array might be different than the stripe count. |
| 17563 |
|
| 17564 |
2. nflda_stripe_indices: An array of indices used to index into |
| 17565 |
nflda_multipath_ds_list. The value of each element of |
| 17566 |
nflda_stripe_indices MUST be less than the number of elements in |
| 17567 |
nflda_multipath_ds_list. Each element of nflda_multipath_ds_list |
| 17568 |
SHOULD be referred to by one or more elements of |
| 17569 |
nflda_stripe_indices. The number of elements in |
| 17570 |
nflda_stripe_indices is always equal to the stripe count. |
| 17571 |
|
| 17572 |
|
| 17573 |
|
| 17574 |
|
| 17575 |
|
| 17576 |
|
| 17577 |
|
| 17578 |
|
| 17579 |
|
| 17580 |
<span class="grey">Shepler, et al. Standards Track [Page 314]</span></pre> |
| 17581 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-315" ></span> |
| 17582 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17583 |
|
| 17584 |
|
| 17585 |
/* |
| 17586 |
* Encoded in the loc_body field of |
| 17587 |
* data type layout_content4: |
| 17588 |
*/ |
| 17589 |
struct nfsv4_1_file_layout4 { |
| 17590 |
deviceid4 nfl_deviceid; |
| 17591 |
nfl_util4 nfl_util; |
| 17592 |
uint32_t nfl_first_stripe_index; |
| 17593 |
offset4 nfl_pattern_offset; |
| 17594 |
nfs_fh4 nfl_fh_list<>; |
| 17595 |
}; |
| 17596 |
|
| 17597 |
The nfsv4_1_file_layout4 data type represents the layout. It is |
| 17598 |
composed of the following fields: |
| 17599 |
|
| 17600 |
1. nfl_deviceid: The device ID that maps to a value of type |
| 17601 |
nfsv4_1_file_layout_ds_addr4. |
| 17602 |
|
| 17603 |
2. nfl_util: Like the nflh_util field of data type |
| 17604 |
nfsv4_1_file_layouthint4, a compact representation of how the |
| 17605 |
data on a file on each data server is packed, whether the client |
| 17606 |
should send COMMIT operations to the metadata server or data |
| 17607 |
server, and the stripe unit size. If a server returns two or |
| 17608 |
more overlapping layouts, each stripe unit size in each |
| 17609 |
overlapping layout MUST be the same. |
| 17610 |
|
| 17611 |
3. nfl_first_stripe_index: The index into the first element of the |
| 17612 |
nflda_stripe_indices array to use. |
| 17613 |
|
| 17614 |
4. nfl_pattern_offset: This field is the logical offset into the |
| 17615 |
file where the striping pattern starts. It is required for |
| 17616 |
converting the client's logical I/O offset (e.g., the current |
| 17617 |
offset in a POSIX file descriptor before the read() or write() |
| 17618 |
system call is sent) into the stripe unit number (see |
| 17619 |
<a href="#section-13.4.1">Section 13.4.1</a>). |
| 17620 |
|
| 17621 |
If dense packing is used, then nfl_pattern_offset is also needed |
| 17622 |
to convert the client's logical I/O offset to an offset on the |
| 17623 |
file on the data server corresponding to the stripe unit number |
| 17624 |
(see <a href="#section-13.4.4">Section 13.4.4</a>). |
| 17625 |
|
| 17626 |
Note that nfl_pattern_offset is not always the same as lo_offset. |
| 17627 |
For example, via the LAYOUTGET operation, a client might request |
| 17628 |
a layout starting at offset 1000 of a file that has its striping |
| 17629 |
pattern start at offset zero. |
| 17630 |
|
| 17631 |
|
| 17632 |
|
| 17633 |
|
| 17634 |
|
| 17635 |
|
| 17636 |
<span class="grey">Shepler, et al. Standards Track [Page 315]</span></pre> |
| 17637 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-316" ></span> |
| 17638 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17639 |
|
| 17640 |
|
| 17641 |
5. nfl_fh_list: An array of data server filehandles for each list of |
| 17642 |
data servers in each element of the nflda_multipath_ds_list |
| 17643 |
array. The number of elements in nfl_fh_list depends on whether |
| 17644 |
sparse or dense packing is being used. |
| 17645 |
|
| 17646 |
* If sparse packing is being used, the number of elements in |
| 17647 |
nfl_fh_list MUST be one of three values: |
| 17648 |
|
| 17649 |
+ Zero. This means that filehandles used for each data |
| 17650 |
server are the same as the filehandle returned by the OPEN |
| 17651 |
operation from the metadata server. |
| 17652 |
|
| 17653 |
+ One. This means that every data server uses the same |
| 17654 |
filehandle: what is specified in nfl_fh_list[0]. |
| 17655 |
|
| 17656 |
+ The same number of elements in nflda_multipath_ds_list. |
| 17657 |
Thus, in this case, when sending an I/O operation to any |
| 17658 |
data server in nflda_multipath_ds_list[X], the filehandle |
| 17659 |
in nfl_fh_list[X] MUST be used. |
| 17660 |
|
| 17661 |
See the discussion on sparse packing in <a href="#section-13.4.4">Section 13.4.4</a>. |
| 17662 |
|
| 17663 |
|
| 17664 |
* If dense packing is being used, the number of elements in |
| 17665 |
nfl_fh_list MUST be the same as the number of elements in |
| 17666 |
nflda_stripe_indices. Thus, when sending an I/O operation to |
| 17667 |
any data server in |
| 17668 |
nflda_multipath_ds_list[nflda_stripe_indices[Y]], the |
| 17669 |
filehandle in nfl_fh_list[Y] MUST be used. In addition, any |
| 17670 |
time there exists i and j, (i != j), such that the |
| 17671 |
intersection of |
| 17672 |
nflda_multipath_ds_list[nflda_stripe_indices[i]] and |
| 17673 |
nflda_multipath_ds_list[nflda_stripe_indices[j]] is not empty, |
| 17674 |
then nfl_fh_list[i] MUST NOT equal nfl_fh_list[j]. In other |
| 17675 |
words, when dense packing is being used, if a data server |
| 17676 |
appears in two or more units of a striping pattern, each |
| 17677 |
reference to the data server MUST use a different filehandle. |
| 17678 |
|
| 17679 |
Indeed, if there are multiple striping patterns, as indicated |
| 17680 |
by the presence of multiple objects of data type layout4 |
| 17681 |
(either returned in one or multiple LAYOUTGET operations), and |
| 17682 |
a data server is the target of a unit of one pattern and |
| 17683 |
another unit of another pattern, then each reference to each |
| 17684 |
data server MUST use a different filehandle. |
| 17685 |
|
| 17686 |
See the discussion on dense packing in <a href="#section-13.4.4">Section 13.4.4</a>. |
| 17687 |
|
| 17688 |
The details on the interpretation of the layout are in <a href="#section-13.4">Section 13.4</a>. |
| 17689 |
|
| 17690 |
|
| 17691 |
|
| 17692 |
<span class="grey">Shepler, et al. Standards Track [Page 316]</span></pre> |
| 17693 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-317" ></span> |
| 17694 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17695 |
|
| 17696 |
|
| 17697 |
<span class="h3"><a class="selflink" id="section-13.4" href="#section-13.4">13.4</a>. Interpreting the File Layout</span> |
| 17698 |
|
| 17699 |
<span class="h4"><a class="selflink" id="section-13.4.1" href="#section-13.4.1">13.4.1</a>. Determining the Stripe Unit Number</span> |
| 17700 |
|
| 17701 |
To find the stripe unit number that corresponds to the client's |
| 17702 |
logical file offset, the pattern offset will also be used. The i'th |
| 17703 |
stripe unit (SUi) is: |
| 17704 |
|
| 17705 |
relative_offset = file_offset - nfl_pattern_offset; |
| 17706 |
SUi = floor(relative_offset / stripe_unit_size); |
| 17707 |
|
| 17708 |
<span class="h4"><a class="selflink" id="section-13.4.2" href="#section-13.4.2">13.4.2</a>. Interpreting the File Layout Using Sparse Packing</span> |
| 17709 |
|
| 17710 |
When sparse packing is used, the algorithm for determining the |
| 17711 |
filehandle and set of data-server network addresses to write stripe |
| 17712 |
unit i (SUi) to is: |
| 17713 |
|
| 17714 |
|
| 17715 |
stripe_count = number of elements in nflda_stripe_indices; |
| 17716 |
|
| 17717 |
j = (SUi + nfl_first_stripe_index) % stripe_count; |
| 17718 |
|
| 17719 |
idx = nflda_stripe_indices[j]; |
| 17720 |
|
| 17721 |
fh_count = number of elements in nfl_fh_list; |
| 17722 |
ds_count = number of elements in nflda_multipath_ds_list; |
| 17723 |
|
| 17724 |
switch (fh_count) { |
| 17725 |
case ds_count: |
| 17726 |
fh = nfl_fh_list[idx]; |
| 17727 |
break; |
| 17728 |
|
| 17729 |
case 1: |
| 17730 |
fh = nfl_fh_list[0]; |
| 17731 |
break; |
| 17732 |
|
| 17733 |
case 0: |
| 17734 |
fh = filehandle returned by OPEN; |
| 17735 |
break; |
| 17736 |
|
| 17737 |
default: |
| 17738 |
throw a fatal exception; |
| 17739 |
break; |
| 17740 |
} |
| 17741 |
|
| 17742 |
address_list = nflda_multipath_ds_list[idx]; |
| 17743 |
|
| 17744 |
|
| 17745 |
|
| 17746 |
|
| 17747 |
|
| 17748 |
<span class="grey">Shepler, et al. Standards Track [Page 317]</span></pre> |
| 17749 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-318" ></span> |
| 17750 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17751 |
|
| 17752 |
|
| 17753 |
The client would then select a data server from address_list, and |
| 17754 |
send a READ or WRITE operation using the filehandle specified in fh. |
| 17755 |
|
| 17756 |
Consider the following example: |
| 17757 |
|
| 17758 |
Suppose we have a device address consisting of seven data servers, |
| 17759 |
arranged in three equivalence (<a href="#section-13.5">Section 13.5</a>) classes: |
| 17760 |
|
| 17761 |
{ A, B, C, D }, { E }, { F, G } |
| 17762 |
|
| 17763 |
where A through G are network addresses. |
| 17764 |
|
| 17765 |
Then |
| 17766 |
|
| 17767 |
nflda_multipath_ds_list<> = { A, B, C, D }, { E }, { F, G } |
| 17768 |
|
| 17769 |
i.e., |
| 17770 |
|
| 17771 |
nflda_multipath_ds_list[0] = { A, B, C, D } |
| 17772 |
|
| 17773 |
nflda_multipath_ds_list[1] = { E } |
| 17774 |
|
| 17775 |
nflda_multipath_ds_list[2] = { F, G } |
| 17776 |
|
| 17777 |
Suppose the striping index array is: |
| 17778 |
|
| 17779 |
nflda_stripe_indices<> = { 2, 0, 1, 0 } |
| 17780 |
|
| 17781 |
Now suppose the client gets a layout that has a device ID that maps |
| 17782 |
to the above device address. The initial index contains |
| 17783 |
|
| 17784 |
nfl_first_stripe_index = 2, |
| 17785 |
|
| 17786 |
and the filehandle list is |
| 17787 |
|
| 17788 |
nfl_fh_list = { 0x36, 0x87, 0x67 }. |
| 17789 |
|
| 17790 |
If the client wants to write to SU0, the set of valid { network |
| 17791 |
address, filehandle } combinations for SUi are determined by: |
| 17792 |
|
| 17793 |
nfl_first_stripe_index = 2 |
| 17794 |
|
| 17795 |
|
| 17796 |
|
| 17797 |
|
| 17798 |
|
| 17799 |
|
| 17800 |
|
| 17801 |
|
| 17802 |
|
| 17803 |
|
| 17804 |
<span class="grey">Shepler, et al. Standards Track [Page 318]</span></pre> |
| 17805 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-319" ></span> |
| 17806 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17807 |
|
| 17808 |
|
| 17809 |
So |
| 17810 |
|
| 17811 |
idx = nflda_stripe_indices[(0 + 2) % 4] |
| 17812 |
|
| 17813 |
= nflda_stripe_indices[2] |
| 17814 |
|
| 17815 |
= 1 |
| 17816 |
|
| 17817 |
So |
| 17818 |
|
| 17819 |
nflda_multipath_ds_list[1] = { E } |
| 17820 |
|
| 17821 |
and |
| 17822 |
|
| 17823 |
nfl_fh_list[1] = { 0x87 } |
| 17824 |
|
| 17825 |
The client can thus write SU0 to { 0x87, { E } }. |
| 17826 |
|
| 17827 |
The destinations of the first 13 storage units are: |
| 17828 |
|
| 17829 |
+-----+------------+--------------+ |
| 17830 |
| SUi | filehandle | data servers | |
| 17831 |
+-----+------------+--------------+ |
| 17832 |
| 0 | 87 | E | |
| 17833 |
| 1 | 36 | A,B,C,D | |
| 17834 |
| 2 | 67 | F,G | |
| 17835 |
| 3 | 36 | A,B,C,D | |
| 17836 |
| 4 | 87 | E | |
| 17837 |
| 5 | 36 | A,B,C,D | |
| 17838 |
| 6 | 67 | F,G | |
| 17839 |
| 7 | 36 | A,B,C,D | |
| 17840 |
| 8 | 87 | E | |
| 17841 |
| 9 | 36 | A,B,C,D | |
| 17842 |
| 10 | 67 | F,G | |
| 17843 |
| 11 | 36 | A,B,C,D | |
| 17844 |
| 12 | 87 | E | |
| 17845 |
+-----+------------+--------------+ |
| 17846 |
|
| 17847 |
<span class="h4"><a class="selflink" id="section-13.4.3" href="#section-13.4.3">13.4.3</a>. Interpreting the File Layout Using Dense Packing</span> |
| 17848 |
|
| 17849 |
When dense packing is used, the algorithm for determining the |
| 17850 |
filehandle and set of data server network addresses to write stripe |
| 17851 |
unit i (SUi) to is: |
| 17852 |
|
| 17853 |
|
| 17854 |
|
| 17855 |
|
| 17856 |
|
| 17857 |
|
| 17858 |
|
| 17859 |
|
| 17860 |
<span class="grey">Shepler, et al. Standards Track [Page 319]</span></pre> |
| 17861 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-320" ></span> |
| 17862 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17863 |
|
| 17864 |
|
| 17865 |
stripe_count = number of elements in nflda_stripe_indices; |
| 17866 |
|
| 17867 |
j = (SUi + nfl_first_stripe_index) % stripe_count; |
| 17868 |
|
| 17869 |
idx = nflda_stripe_indices[j]; |
| 17870 |
|
| 17871 |
fh_count = number of elements in nfl_fh_list; |
| 17872 |
ds_count = number of elements in nflda_multipath_ds_list; |
| 17873 |
|
| 17874 |
switch (fh_count) { |
| 17875 |
case stripe_count: |
| 17876 |
fh = nfl_fh_list[j]; |
| 17877 |
break; |
| 17878 |
|
| 17879 |
default: |
| 17880 |
throw a fatal exception; |
| 17881 |
break; |
| 17882 |
} |
| 17883 |
|
| 17884 |
address_list = nflda_multipath_ds_list[idx]; |
| 17885 |
|
| 17886 |
|
| 17887 |
The client would then select a data server from address_list, and |
| 17888 |
send a READ or WRITE operation using the filehandle specified in fh. |
| 17889 |
|
| 17890 |
Consider the following example (which is the same as the sparse |
| 17891 |
packing example, except for the filehandle list): |
| 17892 |
|
| 17893 |
Suppose we have a device address consisting of seven data servers, |
| 17894 |
arranged in three equivalence (<a href="#section-13.5">Section 13.5</a>) classes: |
| 17895 |
|
| 17896 |
{ A, B, C, D }, { E }, { F, G } |
| 17897 |
|
| 17898 |
where A through G are network addresses. |
| 17899 |
|
| 17900 |
Then |
| 17901 |
|
| 17902 |
nflda_multipath_ds_list<> = { A, B, C, D }, { E }, { F, G } |
| 17903 |
|
| 17904 |
i.e., |
| 17905 |
|
| 17906 |
nflda_multipath_ds_list[0] = { A, B, C, D } |
| 17907 |
|
| 17908 |
nflda_multipath_ds_list[1] = { E } |
| 17909 |
|
| 17910 |
nflda_multipath_ds_list[2] = { F, G } |
| 17911 |
|
| 17912 |
|
| 17913 |
|
| 17914 |
|
| 17915 |
|
| 17916 |
<span class="grey">Shepler, et al. Standards Track [Page 320]</span></pre> |
| 17917 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-321" ></span> |
| 17918 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17919 |
|
| 17920 |
|
| 17921 |
Suppose the striping index array is: |
| 17922 |
|
| 17923 |
nflda_stripe_indices<> = { 2, 0, 1, 0 } |
| 17924 |
|
| 17925 |
Now suppose the client gets a layout that has a device ID that maps |
| 17926 |
to the above device address. The initial index contains |
| 17927 |
|
| 17928 |
nfl_first_stripe_index = 2, |
| 17929 |
|
| 17930 |
and |
| 17931 |
|
| 17932 |
nfl_fh_list = { 0x67, 0x37, 0x87, 0x36 }. |
| 17933 |
|
| 17934 |
The interesting examples for dense packing are SU1 and SU3 because |
| 17935 |
each stripe unit refers to the same data server list, yet each stripe |
| 17936 |
unit MUST use a different filehandle. If the client wants to write |
| 17937 |
to SU1, the set of valid { network address, filehandle } combinations |
| 17938 |
for SUi are determined by: |
| 17939 |
|
| 17940 |
nfl_first_stripe_index = 2 |
| 17941 |
|
| 17942 |
So |
| 17943 |
|
| 17944 |
j = (1 + 2) % 4 = 3 |
| 17945 |
|
| 17946 |
idx = nflda_stripe_indices[j] |
| 17947 |
|
| 17948 |
= nflda_stripe_indices[3] |
| 17949 |
|
| 17950 |
= 0 |
| 17951 |
|
| 17952 |
So |
| 17953 |
|
| 17954 |
nflda_multipath_ds_list[0] = { A, B, C, D } |
| 17955 |
|
| 17956 |
and |
| 17957 |
|
| 17958 |
nfl_fh_list[3] = { 0x36 } |
| 17959 |
|
| 17960 |
The client can thus write SU1 to { 0x36, { A, B, C, D } }. |
| 17961 |
|
| 17962 |
For SU3, j = (3 + 2) % 4 = 1, and nflda_stripe_indices[1] = 0. Then |
| 17963 |
nflda_multipath_ds_list[0] = { A, B, C, D }, and nfl_fh_list[1] = |
| 17964 |
0x37. The client can thus write SU3 to { 0x37, { A, B, C, D } }. |
| 17965 |
|
| 17966 |
|
| 17967 |
|
| 17968 |
|
| 17969 |
|
| 17970 |
|
| 17971 |
|
| 17972 |
<span class="grey">Shepler, et al. Standards Track [Page 321]</span></pre> |
| 17973 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-322" ></span> |
| 17974 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 17975 |
|
| 17976 |
|
| 17977 |
The destinations of the first 13 storage units are: |
| 17978 |
|
| 17979 |
+-----+------------+--------------+ |
| 17980 |
| SUi | filehandle | data servers | |
| 17981 |
+-----+------------+--------------+ |
| 17982 |
| 0 | 87 | E | |
| 17983 |
| 1 | 36 | A,B,C,D | |
| 17984 |
| 2 | 67 | F,G | |
| 17985 |
| 3 | 37 | A,B,C,D | |
| 17986 |
| 4 | 87 | E | |
| 17987 |
| 5 | 36 | A,B,C,D | |
| 17988 |
| 6 | 67 | F,G | |
| 17989 |
| 7 | 37 | A,B,C,D | |
| 17990 |
| 8 | 87 | E | |
| 17991 |
| 9 | 36 | A,B,C,D | |
| 17992 |
| 10 | 67 | F,G | |
| 17993 |
| 11 | 37 | A,B,C,D | |
| 17994 |
| 12 | 87 | E | |
| 17995 |
+-----+------------+--------------+ |
| 17996 |
|
| 17997 |
<span class="h4"><a class="selflink" id="section-13.4.4" href="#section-13.4.4">13.4.4</a>. Sparse and Dense Stripe Unit Packing</span> |
| 17998 |
|
| 17999 |
The flag NFL4_UFLG_DENSE of the nfl_util4 data type (field nflh_util |
| 18000 |
of the data type nfsv4_1_file_layouthint4 and field nfl_util of data |
| 18001 |
type nfsv4_1_file_layout_ds_addr4) specifies how the data is packed |
| 18002 |
within the data file on a data server. It allows for two different |
| 18003 |
data packings: sparse and dense. The packing type determines the |
| 18004 |
calculation that will be made to map the client-visible file offset |
| 18005 |
to the offset within the data file located on the data server. |
| 18006 |
|
| 18007 |
If nfl_util & NFL4_UFLG_DENSE is zero, this means that sparse packing |
| 18008 |
is being used. Hence, the logical offsets of the file as viewed by a |
| 18009 |
client sending READs and WRITEs directly to the metadata server are |
| 18010 |
the same offsets each data server uses when storing a stripe unit. |
| 18011 |
The effect then, for striping patterns consisting of at least two |
| 18012 |
stripe units, is for each data server file to be sparse or "holey". |
| 18013 |
So for example, suppose there is a pattern with three stripe units, |
| 18014 |
the stripe unit size is 4096 bytes, and there are three data servers |
| 18015 |
in the pattern. Then, the file in data server 1 will have stripe |
| 18016 |
units 0, 3, 6, 9, ... filled; data server 2's file will have stripe |
| 18017 |
units 1, 4, 7, 10, ... filled; and data server 3's file will have |
| 18018 |
stripe units 2, 5, 8, 11, ... filled. The unfilled stripe units of |
| 18019 |
each file will be holes; hence, the files in each data server are |
| 18020 |
sparse. |
| 18021 |
|
| 18022 |
If sparse packing is being used and a client attempts I/O to one of |
| 18023 |
the holes, then an error MUST be returned by the data server. Using |
| 18024 |
the above example, if data server 3 received a READ or WRITE |
| 18025 |
|
| 18026 |
|
| 18027 |
|
| 18028 |
<span class="grey">Shepler, et al. Standards Track [Page 322]</span></pre> |
| 18029 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-323" ></span> |
| 18030 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18031 |
|
| 18032 |
|
| 18033 |
operation for block 4, the data server would return |
| 18034 |
NFS4ERR_PNFS_IO_HOLE. Thus, data servers need to understand the |
| 18035 |
striping pattern in order to support sparse packing. |
| 18036 |
|
| 18037 |
If nfl_util & NFL4_UFLG_DENSE is one, this means that dense packing |
| 18038 |
is being used, and the data server files have no holes. Dense |
| 18039 |
packing might be selected because the data server does not |
| 18040 |
(efficiently) support holey files or because the data server cannot |
| 18041 |
recognize read-ahead unless there are no holes. If dense packing is |
| 18042 |
indicated in the layout, the data files will be packed. Using the |
| 18043 |
same striping pattern and stripe unit size that were used for the |
| 18044 |
sparse packing example, the corresponding dense packing example would |
| 18045 |
have all stripe units of all data files filled as follows: |
| 18046 |
|
| 18047 |
o Logical stripe units 0, 3, 6, ... of the file would live on stripe |
| 18048 |
units 0, 1, 2, ... of the file of data server 1. |
| 18049 |
|
| 18050 |
o Logical stripe units 1, 4, 7, ... of the file would live on stripe |
| 18051 |
units 0, 1, 2, ... of the file of data server 2. |
| 18052 |
|
| 18053 |
o Logical stripe units 2, 5, 8, ... of the file would live on stripe |
| 18054 |
units 0, 1, 2, ... of the file of data server 3. |
| 18055 |
|
| 18056 |
Because dense packing does not leave holes on the data servers, the |
| 18057 |
pNFS client is allowed to write to any offset of any data file of any |
| 18058 |
data server in the stripe. Thus, the data servers need not know the |
| 18059 |
file's striping pattern. |
| 18060 |
|
| 18061 |
The calculation to determine the byte offset within the data file for |
| 18062 |
dense data server layouts is: |
| 18063 |
|
| 18064 |
stripe_width = stripe_unit_size * N; |
| 18065 |
where N = number of elements in nflda_stripe_indices. |
| 18066 |
|
| 18067 |
relative_offset = file_offset - nfl_pattern_offset; |
| 18068 |
|
| 18069 |
data_file_offset = floor(relative_offset / stripe_width) |
| 18070 |
* stripe_unit_size |
| 18071 |
+ relative_offset % stripe_unit_size |
| 18072 |
|
| 18073 |
If dense packing is being used, and a data server appears more than |
| 18074 |
once in a striping pattern, then to distinguish one stripe unit from |
| 18075 |
another, the data server MUST use a different filehandle. Let's |
| 18076 |
suppose there are two data servers. Logical stripe units 0, 3, 6 are |
| 18077 |
served by data server 1; logical stripe units 1, 4, 7 are served by |
| 18078 |
data server 2; and logical stripe units 2, 5, 8 are also served by |
| 18079 |
data server 2. Unless data server 2 has two filehandles (each |
| 18080 |
referring to a different data file), then, for example, a write to |
| 18081 |
|
| 18082 |
|
| 18083 |
|
| 18084 |
<span class="grey">Shepler, et al. Standards Track [Page 323]</span></pre> |
| 18085 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-324" ></span> |
| 18086 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18087 |
|
| 18088 |
|
| 18089 |
logical stripe unit 1 overwrites the write to logical stripe unit 2 |
| 18090 |
because both logical stripe units are located in the same stripe unit |
| 18091 |
(0) of data server 2. |
| 18092 |
|
| 18093 |
<span class="h3"><a class="selflink" id="section-13.5" href="#section-13.5">13.5</a>. Data Server Multipathing</span> |
| 18094 |
|
| 18095 |
The NFSv4.1 file layout supports multipathing to multiple data server |
| 18096 |
addresses. Data-server-level multipathing is used for bandwidth |
| 18097 |
scaling via trunking (<a href="#section-2.10.5">Section 2.10.5</a>) and for higher availability of |
| 18098 |
use in the case of a data-server failure. Multipathing allows the |
| 18099 |
client to switch to another data server address which may be that of |
| 18100 |
another data server that is exporting the same data stripe unit, |
| 18101 |
without having to contact the metadata server for a new layout. |
| 18102 |
|
| 18103 |
To support data server multipathing, each element of the |
| 18104 |
nflda_multipath_ds_list contains an array of one more data server |
| 18105 |
network addresses. This array (data type multipath_list4) represents |
| 18106 |
a list of data servers (each identified by a network address), with |
| 18107 |
the possibility that some data servers will appear in the list |
| 18108 |
multiple times. |
| 18109 |
|
| 18110 |
The client is free to use any of the network addresses as a |
| 18111 |
destination to send data server requests. If some network addresses |
| 18112 |
are less optimal paths to the data than others, then the MDS SHOULD |
| 18113 |
NOT include those network addresses in an element of |
| 18114 |
nflda_multipath_ds_list. If less optimal network addresses exist to |
| 18115 |
provide failover, the RECOMMENDED method to offer the addresses is to |
| 18116 |
provide them in a replacement device-ID-to-device-address mapping, or |
| 18117 |
a replacement device ID. When a client finds that no data server in |
| 18118 |
an element of nflda_multipath_ds_list responds, it SHOULD send a |
| 18119 |
GETDEVICEINFO to attempt to replace the existing device-ID-to-device- |
| 18120 |
address mappings. If the MDS detects that all data servers |
| 18121 |
represented by an element of nflda_multipath_ds_list are unavailable, |
| 18122 |
the MDS SHOULD send a CB_NOTIFY_DEVICEID (if the client has indicated |
| 18123 |
it wants device ID notifications for changed device IDs) to change |
| 18124 |
the device-ID-to-device-address mappings to the available data |
| 18125 |
servers. If the device ID itself will be replaced, the MDS SHOULD |
| 18126 |
recall all layouts with the device ID, and thus force the client to |
| 18127 |
get new layouts and device ID mappings via LAYOUTGET and |
| 18128 |
GETDEVICEINFO. |
| 18129 |
|
| 18130 |
Generally, if two network addresses appear in an element of |
| 18131 |
nflda_multipath_ds_list, they will designate the same data server, |
| 18132 |
and the two data server addresses will support the implementation of |
| 18133 |
client ID or session trunking (the latter is RECOMMENDED) as defined |
| 18134 |
in <a href="#section-2.10.5">Section 2.10.5</a>. The two data server addresses will share the same |
| 18135 |
server owner or major ID of the server owner. It is not always |
| 18136 |
|
| 18137 |
|
| 18138 |
|
| 18139 |
|
| 18140 |
<span class="grey">Shepler, et al. Standards Track [Page 324]</span></pre> |
| 18141 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-325" ></span> |
| 18142 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18143 |
|
| 18144 |
|
| 18145 |
necessary for the two data server addresses to designate the same |
| 18146 |
server with trunking being used. For example, the data could be |
| 18147 |
read-only, and the data consist of exact replicas. |
| 18148 |
|
| 18149 |
<span class="h3"><a class="selflink" id="section-13.6" href="#section-13.6">13.6</a>. Operations Sent to NFSv4.1 Data Servers</span> |
| 18150 |
|
| 18151 |
Clients accessing data on an NFSv4.1 data server MUST send only the |
| 18152 |
NULL procedure and COMPOUND procedures whose operations are taken |
| 18153 |
only from two restricted subsets of the operations defined as valid |
| 18154 |
NFSv4.1 operations. Clients MUST use the filehandle specified by the |
| 18155 |
layout when accessing data on NFSv4.1 data servers. |
| 18156 |
|
| 18157 |
The first of these operation subsets consists of management |
| 18158 |
operations. This subset consists of the BACKCHANNEL_CTL, |
| 18159 |
BIND_CONN_TO_SESSION, CREATE_SESSION, DESTROY_CLIENTID, |
| 18160 |
DESTROY_SESSION, EXCHANGE_ID, SECINFO_NO_NAME, SET_SSV, and SEQUENCE |
| 18161 |
operations. The client may use these operations in order to set up |
| 18162 |
and maintain the appropriate client IDs, sessions, and security |
| 18163 |
contexts involved in communication with the data server. Henceforth, |
| 18164 |
these will be referred to as data-server housekeeping operations. |
| 18165 |
|
| 18166 |
The second subset consists of COMMIT, READ, WRITE, and PUTFH. These |
| 18167 |
operations MUST be used with a current filehandle specified by the |
| 18168 |
layout. In the case of PUTFH, the new current filehandle MUST be one |
| 18169 |
taken from the layout. Henceforth, these will be referred to as |
| 18170 |
data-server I/O operations. As described in <a href="#section-12.5.1">Section 12.5.1</a>, a client |
| 18171 |
MUST NOT send an I/O to a data server for which it does not hold a |
| 18172 |
valid layout; the data server MUST reject such an I/O. |
| 18173 |
|
| 18174 |
Unless the server has a concurrent non-data-server personality -- |
| 18175 |
i.e., EXCHANGE_ID results returned (EXCHGID4_FLAG_USE_PNFS_DS | |
| 18176 |
EXCHGID4_FLAG_USE_PNFS_MDS) or (EXCHGID4_FLAG_USE_PNFS_DS | |
| 18177 |
EXCHGID4_FLAG_USE_NON_PNFS) see <a href="#section-13.1">Section 13.1</a> -- any attempted use of |
| 18178 |
operations against a data server other than those specified in the |
| 18179 |
two subsets above MUST return NFS4ERR_NOTSUPP to the client. |
| 18180 |
|
| 18181 |
When the server has concurrent data-server and non-data-server |
| 18182 |
personalities, each COMPOUND sent by the client MUST be constructed |
| 18183 |
so that it is appropriate to one of the two personalities, and it |
| 18184 |
MUST NOT contain operations directed to a mix of those personalities. |
| 18185 |
The server MUST enforce this. To understand the constraints, |
| 18186 |
operations within a COMPOUND are divided into the following three |
| 18187 |
classes: |
| 18188 |
|
| 18189 |
1. An operation that is ambiguous regarding its personality |
| 18190 |
assignment. This includes all of the data-server housekeeping |
| 18191 |
operations. Additionally, if the server has assigned filehandles |
| 18192 |
so that the ones defined by the layout are the same as those used |
| 18193 |
|
| 18194 |
|
| 18195 |
|
| 18196 |
<span class="grey">Shepler, et al. Standards Track [Page 325]</span></pre> |
| 18197 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-326" ></span> |
| 18198 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18199 |
|
| 18200 |
|
| 18201 |
by the metadata server, all operations using such filehandles are |
| 18202 |
within this class, with the following exception. The exception |
| 18203 |
is that if the operation uses a stateid that is incompatible with |
| 18204 |
a data-server personality (e.g., a special stateid or the stateid |
| 18205 |
has a non-zero "seqid" field, see <a href="#section-13.9.1">Section 13.9.1</a>), the operation |
| 18206 |
is in class 3, as described below. A COMPOUND containing |
| 18207 |
multiple class 1 operations (and operations of no other class) |
| 18208 |
MAY be sent to a server with multiple concurrent data server and |
| 18209 |
non-data-server personalities. |
| 18210 |
|
| 18211 |
2. An operation that is unambiguously referable to the data-server |
| 18212 |
personality. This includes data-server I/O operations where the |
| 18213 |
filehandle is one that can only be validly directed to the data- |
| 18214 |
server personality. |
| 18215 |
|
| 18216 |
3. An operation that is unambiguously referable to the non-data- |
| 18217 |
server personality. This includes all COMPOUND operations that |
| 18218 |
are neither data-server housekeeping nor data-server I/O |
| 18219 |
operations, plus data-server I/O operations where the current fh |
| 18220 |
(or the one to be made the current fh in the case of PUTFH) is |
| 18221 |
only valid on the metadata server or where a stateid is used that |
| 18222 |
is incompatible with the data server, i.e., is a special stateid |
| 18223 |
or has a non-zero seqid value. |
| 18224 |
|
| 18225 |
When a COMPOUND first executes an operation from class 3 above, it |
| 18226 |
acts as a normal COMPOUND on any other server, and the data-server |
| 18227 |
personality ceases to be relevant. There are no special restrictions |
| 18228 |
on the operations in the COMPOUND to limit them to those for a data |
| 18229 |
server. When a PUTFH is done, filehandles derived from the layout |
| 18230 |
are not valid. If their format is not normally acceptable, then |
| 18231 |
NFS4ERR_BADHANDLE MUST result. Similarly, current filehandles for |
| 18232 |
other operations do not accept filehandles derived from layouts and |
| 18233 |
are not normally usable on the metadata server. Using these will |
| 18234 |
result in NFS4ERR_STALE. |
| 18235 |
|
| 18236 |
When a COMPOUND first executes an operation from class 2, which would |
| 18237 |
be PUTFH where the filehandle is one from a layout, the COMPOUND |
| 18238 |
henceforth is interpreted with respect to the data-server |
| 18239 |
personality. Operations outside the two classes discussed above MUST |
| 18240 |
result in NFS4ERR_NOTSUPP. Filehandles are validated using the rules |
| 18241 |
of the data server, resulting in NFS4ERR_BADHANDLE and/or |
| 18242 |
NFS4ERR_STALE even when they would not normally do so when addressed |
| 18243 |
to the non-data-server personality. Stateids must obey the rules of |
| 18244 |
the data server in that any use of special stateids or stateids with |
| 18245 |
non-zero seqid values must result in NFS4ERR_BAD_STATEID. |
| 18246 |
|
| 18247 |
|
| 18248 |
|
| 18249 |
|
| 18250 |
|
| 18251 |
|
| 18252 |
<span class="grey">Shepler, et al. Standards Track [Page 326]</span></pre> |
| 18253 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-327" ></span> |
| 18254 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18255 |
|
| 18256 |
|
| 18257 |
Until the server first executes an operation from class 2 or class 3, |
| 18258 |
the client MUST NOT depend on the operation being executed by either |
| 18259 |
the data-server or the non-data-server personality. The server MUST |
| 18260 |
pick one personality consistently for a given COMPOUND, with the only |
| 18261 |
possible transition being a single one when the first operation from |
| 18262 |
class 2 or class 3 is executed. |
| 18263 |
|
| 18264 |
Because of the complexity induced by assigning filehandles so they |
| 18265 |
can be used on both a data server and a metadata server, it is |
| 18266 |
RECOMMENDED that where the same server can have both personalities, |
| 18267 |
the server assign separate unique filehandles to both personalities. |
| 18268 |
This makes it unambiguous for which server a given request is |
| 18269 |
intended. |
| 18270 |
|
| 18271 |
GETATTR and SETATTR MUST be directed to the metadata server. In the |
| 18272 |
case of a SETATTR of the size attribute, the control protocol is |
| 18273 |
responsible for propagating size updates/truncations to the data |
| 18274 |
servers. In the case of extending WRITEs to the data servers, the |
| 18275 |
new size must be visible on the metadata server once a LAYOUTCOMMIT |
| 18276 |
has completed (see <a href="#section-12.5.4.2">Section 12.5.4.2</a>). <a href="#section-13.10">Section 13.10</a> describes the |
| 18277 |
mechanism by which the client is to handle data-server files that do |
| 18278 |
not reflect the metadata server's size. |
| 18279 |
|
| 18280 |
<span class="h3"><a class="selflink" id="section-13.7" href="#section-13.7">13.7</a>. COMMIT through Metadata Server</span> |
| 18281 |
|
| 18282 |
The file layout provides two alternate means of providing for the |
| 18283 |
commit of data written through data servers. The flag |
| 18284 |
NFL4_UFLG_COMMIT_THRU_MDS in the field nfl_util of the file layout |
| 18285 |
(data type nfsv4_1_file_layout4) is an indication from the metadata |
| 18286 |
server to the client of the REQUIRED way of performing COMMIT, either |
| 18287 |
by sending the COMMIT to the data server or the metadata server. |
| 18288 |
These two methods of dealing with the issue correspond to broad |
| 18289 |
styles of implementation for a pNFS server supporting the file layout |
| 18290 |
type. |
| 18291 |
|
| 18292 |
o When the flag is FALSE, COMMIT operations MUST to be sent to the |
| 18293 |
data server to which the corresponding WRITE operations were sent. |
| 18294 |
This approach is sometimes useful when file striping is |
| 18295 |
implemented within the pNFS server (instead of the file system), |
| 18296 |
with the individual data servers each implementing their own file |
| 18297 |
systems. |
| 18298 |
|
| 18299 |
o When the flag is TRUE, COMMIT operations MUST be sent to the |
| 18300 |
metadata server, rather than to the individual data servers. This |
| 18301 |
approach is sometimes useful when file striping is implemented |
| 18302 |
within the clustered file system that is the backend to the pNFS |
| 18303 |
server. In such an implementation, each COMMIT to each data |
| 18304 |
server might result in repeated writes of metadata blocks to the |
| 18305 |
|
| 18306 |
|
| 18307 |
|
| 18308 |
<span class="grey">Shepler, et al. Standards Track [Page 327]</span></pre> |
| 18309 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-328" ></span> |
| 18310 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18311 |
|
| 18312 |
|
| 18313 |
detriment of write performance. Sending a single COMMIT to the |
| 18314 |
metadata server can be more efficient when there exists a |
| 18315 |
clustered file system capable of implementing such a coordinated |
| 18316 |
COMMIT. |
| 18317 |
|
| 18318 |
If nfl_util & NFL4_UFLG_COMMIT_THRU_MDS is TRUE, then in order to |
| 18319 |
maintain the current NFSv4.1 commit and recovery model, the data |
| 18320 |
servers MUST return a common writeverf verifier in all WRITE |
| 18321 |
responses for a given file layout, and the metadata server's |
| 18322 |
COMMIT implementation must return the same writeverf. The value |
| 18323 |
of the writeverf verifier MUST be changed at the metadata server |
| 18324 |
or any data server that is referenced in the layout, whenever |
| 18325 |
there is a server event that can possibly lead to loss of |
| 18326 |
uncommitted data. The scope of the verifier can be for a file or |
| 18327 |
for the entire pNFS server. It might be more difficult for the |
| 18328 |
server to maintain the verifier at the file level, but the benefit |
| 18329 |
is that only events that impact a given file will require recovery |
| 18330 |
action. |
| 18331 |
|
| 18332 |
Note that if the layout specified dense packing, then the offset used |
| 18333 |
to a COMMIT to the MDS may differ than that of an offset used to a |
| 18334 |
COMMIT to the data server. |
| 18335 |
|
| 18336 |
The single COMMIT to the metadata server will return a verifier, and |
| 18337 |
the client should compare it to all the verifiers from the WRITEs and |
| 18338 |
fail the COMMIT if there are any mismatched verifiers. If COMMIT to |
| 18339 |
the metadata server fails, the client should re-send WRITEs for all |
| 18340 |
the modified data in the file. The client should treat modified data |
| 18341 |
with a mismatched verifier as a WRITE failure and try to recover by |
| 18342 |
resending the WRITEs to the original data server or using another |
| 18343 |
path to that data if the layout has not been recalled. |
| 18344 |
Alternatively, the client can obtain a new layout or it could rewrite |
| 18345 |
the data directly to the metadata server. If nfl_util & |
| 18346 |
NFL4_UFLG_COMMIT_THRU_MDS is FALSE, sending a COMMIT to the metadata |
| 18347 |
server might have no effect. If nfl_util & NFL4_UFLG_COMMIT_THRU_MDS |
| 18348 |
is FALSE, a COMMIT sent to the metadata server should be used only to |
| 18349 |
commit data that was written to the metadata server. See |
| 18350 |
<a href="#section-12.7.6">Section 12.7.6</a> for recovery options. |
| 18351 |
|
| 18352 |
<span class="h3"><a class="selflink" id="section-13.8" href="#section-13.8">13.8</a>. The Layout Iomode</span> |
| 18353 |
|
| 18354 |
The layout iomode need not be used by the metadata server when |
| 18355 |
servicing NFSv4.1 file-based layouts, although in some circumstances |
| 18356 |
it may be useful. For example, if the server implementation supports |
| 18357 |
reading from read-only replicas or mirrors, it would be useful for |
| 18358 |
the server to return a layout enabling the client to do so. As such, |
| 18359 |
the client SHOULD set the iomode based on its intent to read or write |
| 18360 |
the data. The client may default to an iomode of LAYOUTIOMODE4_RW. |
| 18361 |
|
| 18362 |
|
| 18363 |
|
| 18364 |
<span class="grey">Shepler, et al. Standards Track [Page 328]</span></pre> |
| 18365 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-329" ></span> |
| 18366 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18367 |
|
| 18368 |
|
| 18369 |
The iomode need not be checked by the data servers when clients |
| 18370 |
perform I/O. However, the data servers SHOULD still validate that |
| 18371 |
the client holds a valid layout and return an error if the client |
| 18372 |
does not. |
| 18373 |
|
| 18374 |
<span class="h3"><a class="selflink" id="section-13.9" href="#section-13.9">13.9</a>. Metadata and Data Server State Coordination</span> |
| 18375 |
|
| 18376 |
<span class="h4"><a class="selflink" id="section-13.9.1" href="#section-13.9.1">13.9.1</a>. Global Stateid Requirements</span> |
| 18377 |
|
| 18378 |
When the client sends I/O to a data server, the stateid used MUST NOT |
| 18379 |
be a layout stateid as returned by LAYOUTGET or sent by |
| 18380 |
CB_LAYOUTRECALL. Permitted stateids are based on one of the |
| 18381 |
following: an OPEN stateid (the stateid field of data type OPEN4resok |
| 18382 |
as returned by OPEN), a delegation stateid (the stateid field of data |
| 18383 |
types open_read_delegation4 and open_write_delegation4 as returned by |
| 18384 |
OPEN or WANT_DELEGATION, or as sent by CB_PUSH_DELEG), or a stateid |
| 18385 |
returned by the LOCK or LOCKU operations. The stateid sent to the |
| 18386 |
data server MUST be sent with the seqid set to zero, indicating the |
| 18387 |
most current version of that stateid, rather than indicating a |
| 18388 |
specific non-zero seqid value. In no case is the use of special |
| 18389 |
stateid values allowed. |
| 18390 |
|
| 18391 |
The stateid used for I/O MUST have the same effect and be subject to |
| 18392 |
the same validation on a data server as it would if the I/O was being |
| 18393 |
performed on the metadata server itself in the absence of pNFS. This |
| 18394 |
has the implication that stateids are globally valid on both the |
| 18395 |
metadata and data servers. This requires the metadata server to |
| 18396 |
propagate changes in LOCK and OPEN state to the data servers, so that |
| 18397 |
the data servers can validate I/O accesses. This is discussed |
| 18398 |
further in <a href="#section-13.9.2">Section 13.9.2</a>. Depending on when stateids are |
| 18399 |
propagated, the existence of a valid stateid on the data server may |
| 18400 |
act as proof of a valid layout. |
| 18401 |
|
| 18402 |
Clients performing I/O operations need to select an appropriate |
| 18403 |
stateid based on the locks (including opens and delegations) held by |
| 18404 |
the client and the various types of state-owners sending the I/O |
| 18405 |
requests. The rules for doing so when referencing data servers are |
| 18406 |
somewhat different from those discussed in <a href="#section-8.2.5">Section 8.2.5</a>, which apply |
| 18407 |
when accessing metadata servers. |
| 18408 |
|
| 18409 |
The following rules, applied in order of decreasing priority, govern |
| 18410 |
the selection of the appropriate stateid: |
| 18411 |
|
| 18412 |
o If the client holds a delegation for the file in question, the |
| 18413 |
delegation stateid should be used. |
| 18414 |
|
| 18415 |
|
| 18416 |
|
| 18417 |
|
| 18418 |
|
| 18419 |
|
| 18420 |
<span class="grey">Shepler, et al. Standards Track [Page 329]</span></pre> |
| 18421 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-330" ></span> |
| 18422 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18423 |
|
| 18424 |
|
| 18425 |
o Otherwise, there must be an OPEN stateid for the current open- |
| 18426 |
owner, and that OPEN stateid for the open file in question is |
| 18427 |
used, unless mandatory locking prevents that. See below. |
| 18428 |
|
| 18429 |
o If the data server had previously responded with NFS4ERR_LOCKED to |
| 18430 |
use of the OPEN stateid, then the client should use the byte-range |
| 18431 |
lock stateid whenever one exists for that open file with the |
| 18432 |
current lock-owner. |
| 18433 |
|
| 18434 |
o Special stateids should never be used. If they are used, the data |
| 18435 |
server MUST reject the I/O with an NFS4ERR_BAD_STATEID error. |
| 18436 |
|
| 18437 |
<span class="h4"><a class="selflink" id="section-13.9.2" href="#section-13.9.2">13.9.2</a>. Data Server State Propagation</span> |
| 18438 |
|
| 18439 |
Since the metadata server, which handles byte-range lock and open- |
| 18440 |
mode state changes as well as ACLs, might not be co-located with the |
| 18441 |
data servers where I/O accesses are validated, the server |
| 18442 |
implementation MUST take care of propagating changes of this state to |
| 18443 |
the data servers. Once the propagation to the data servers is |
| 18444 |
complete, the full effect of those changes MUST be in effect at the |
| 18445 |
data servers. However, some state changes need not be propagated |
| 18446 |
immediately, although all changes SHOULD be propagated promptly. |
| 18447 |
These state propagations have an impact on the design of the control |
| 18448 |
protocol, even though the control protocol is outside of the scope of |
| 18449 |
this specification. Immediate propagation refers to the synchronous |
| 18450 |
propagation of state from the metadata server to the data server(s); |
| 18451 |
the propagation must be complete before returning to the client. |
| 18452 |
|
| 18453 |
<span class="h5"><a class="selflink" id="section-13.9.2.1" href="#section-13.9.2.1">13.9.2.1</a>. Lock State Propagation</span> |
| 18454 |
|
| 18455 |
If the pNFS server supports mandatory byte-range locking, any |
| 18456 |
mandatory byte-range locks on a file MUST be made effective at the |
| 18457 |
data servers before the request that establishes them returns to the |
| 18458 |
caller. The effect MUST be the same as if the mandatory byte-range |
| 18459 |
lock state were synchronously propagated to the data servers, even |
| 18460 |
though the details of the control protocol may avoid actual transfer |
| 18461 |
of the state under certain circumstances. |
| 18462 |
|
| 18463 |
On the other hand, since advisory byte-range lock state is not used |
| 18464 |
for checking I/O accesses at the data servers, there is no semantic |
| 18465 |
reason for propagating advisory byte-range lock state to the data |
| 18466 |
servers. Since updates to advisory locks neither confer nor remove |
| 18467 |
privileges, these changes need not be propagated immediately, and may |
| 18468 |
not need to be propagated promptly. The updates to advisory locks |
| 18469 |
need only be propagated when the data server needs to resolve a |
| 18470 |
question about a stateid. In fact, if byte-range locking is not |
| 18471 |
mandatory (i.e., is advisory) the clients are advised to avoid using |
| 18472 |
|
| 18473 |
|
| 18474 |
|
| 18475 |
|
| 18476 |
<span class="grey">Shepler, et al. Standards Track [Page 330]</span></pre> |
| 18477 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-331" ></span> |
| 18478 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18479 |
|
| 18480 |
|
| 18481 |
the byte-range lock-based stateids for I/O. The stateids returned by |
| 18482 |
OPEN are sufficient and eliminate overhead for this kind of state |
| 18483 |
propagation. |
| 18484 |
|
| 18485 |
If a client gets back an NFS4ERR_LOCKED error from a data server, |
| 18486 |
this is an indication that mandatory byte-range locking is in force. |
| 18487 |
The client recovers from this by getting a byte-range lock that |
| 18488 |
covers the affected range and re-sends the I/O with the stateid of |
| 18489 |
the byte-range lock. |
| 18490 |
|
| 18491 |
<span class="h5"><a class="selflink" id="section-13.9.2.2" href="#section-13.9.2.2">13.9.2.2</a>. Open and Deny Mode Validation</span> |
| 18492 |
|
| 18493 |
Open and deny mode validation MUST be performed against the open and |
| 18494 |
deny mode(s) held by the data servers. When access is reduced or a |
| 18495 |
deny mode made more restrictive (because of CLOSE or OPEN_DOWNGRADE), |
| 18496 |
the data server MUST prevent any I/Os that would be denied if |
| 18497 |
performed on the metadata server. When access is expanded, the data |
| 18498 |
server MUST make sure that no requests are subsequently rejected |
| 18499 |
because of open or deny issues that no longer apply, given the |
| 18500 |
previous relaxation. |
| 18501 |
|
| 18502 |
<span class="h5"><a class="selflink" id="section-13.9.2.3" href="#section-13.9.2.3">13.9.2.3</a>. File Attributes</span> |
| 18503 |
|
| 18504 |
Since the SETATTR operation has the ability to modify state that is |
| 18505 |
visible on both the metadata and data servers (e.g., the size), care |
| 18506 |
must be taken to ensure that the resultant state across the set of |
| 18507 |
data servers is consistent, especially when truncating or growing the |
| 18508 |
file. |
| 18509 |
|
| 18510 |
As described earlier, the LAYOUTCOMMIT operation is used to ensure |
| 18511 |
that the metadata is synchronized with changes made to the data |
| 18512 |
servers. For the NFSv4.1-based data storage protocol, it is |
| 18513 |
necessary to re-synchronize state such as the size attribute, and the |
| 18514 |
setting of mtime/change/atime. See <a href="#section-12.5.4">Section 12.5.4</a> for a full |
| 18515 |
description of the semantics regarding LAYOUTCOMMIT and attribute |
| 18516 |
synchronization. It should be noted that by using an NFSv4.1-based |
| 18517 |
layout type, it is possible to synchronize this state before |
| 18518 |
LAYOUTCOMMIT occurs. For example, the control protocol can be used |
| 18519 |
to query the attributes present on the data servers. |
| 18520 |
|
| 18521 |
Any changes to file attributes that control authorization or access |
| 18522 |
as reflected by ACCESS calls or READs and WRITEs on the metadata |
| 18523 |
server, MUST be propagated to the data servers for enforcement on |
| 18524 |
READ and WRITE I/O calls. If the changes made on the metadata server |
| 18525 |
result in more restrictive access permissions for any user, those |
| 18526 |
changes MUST be propagated to the data servers synchronously. |
| 18527 |
|
| 18528 |
|
| 18529 |
|
| 18530 |
|
| 18531 |
|
| 18532 |
<span class="grey">Shepler, et al. Standards Track [Page 331]</span></pre> |
| 18533 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-332" ></span> |
| 18534 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18535 |
|
| 18536 |
|
| 18537 |
The OPEN operation (<a href="#section-18.16.4">Section 18.16.4</a>) does not impose any requirement |
| 18538 |
that I/O operations on an open file have the same credentials as the |
| 18539 |
OPEN itself (unless EXCHGID4_FLAG_BIND_PRINC_STATEID is set when |
| 18540 |
EXCHANGE_ID creates the client ID), and so it requires the server's |
| 18541 |
READ and WRITE operations to perform appropriate access checking. |
| 18542 |
Changes to ACLs also require new access checking by READ and WRITE on |
| 18543 |
the server. The propagation of access-right changes due to changes |
| 18544 |
in ACLs may be asynchronous only if the server implementation is able |
| 18545 |
to determine that the updated ACL is not more restrictive for any |
| 18546 |
user specified in the old ACL. Due to the relative infrequency of |
| 18547 |
ACL updates, it is suggested that all changes be propagated |
| 18548 |
synchronously. |
| 18549 |
|
| 18550 |
<span class="h3"><a class="selflink" id="section-13.10" href="#section-13.10">13.10</a>. Data Server Component File Size</span> |
| 18551 |
|
| 18552 |
A potential problem exists when a component data file on a particular |
| 18553 |
data server has grown past EOF; the problem exists for both dense and |
| 18554 |
sparse layouts. Imagine the following scenario: a client creates a |
| 18555 |
new file (size == 0) and writes to byte 131072; the client then seeks |
| 18556 |
to the beginning of the file and reads byte 100. The client should |
| 18557 |
receive zeroes back as a result of the READ. However, if the |
| 18558 |
striping pattern directs the client to send the READ to a data server |
| 18559 |
other than the one that received the client's original WRITE, the |
| 18560 |
data server servicing the READ may believe that the file's size is |
| 18561 |
still 0 bytes. In that event, the data server's READ response will |
| 18562 |
contain zero bytes and an indication of EOF. The data server can |
| 18563 |
only return zeroes if it knows that the file's size has been |
| 18564 |
extended. This would require the immediate propagation of the file's |
| 18565 |
size to all data servers, which is potentially very costly. |
| 18566 |
Therefore, the client that has initiated the extension of the file's |
| 18567 |
size MUST be prepared to deal with these EOF conditions. When the |
| 18568 |
offset in the arguments to READ is less than the client's view of the |
| 18569 |
file size, if the READ response indicates EOF and/or contains fewer |
| 18570 |
bytes than requested, the client will interpret such a response as a |
| 18571 |
hole in the file, and the NFS client will substitute zeroes for the |
| 18572 |
data. |
| 18573 |
|
| 18574 |
The NFSv4.1 protocol only provides close-to-open file data cache |
| 18575 |
semantics; meaning that when the file is closed, all modified data is |
| 18576 |
written to the server. When a subsequent OPEN of the file is done, |
| 18577 |
the change attribute is inspected for a difference from a cached |
| 18578 |
value for the change attribute. For the case above, this means that |
| 18579 |
a LAYOUTCOMMIT will be done at close (along with the data WRITEs) and |
| 18580 |
will update the file's size and change attribute. Access from |
| 18581 |
another client after that point will result in the appropriate size |
| 18582 |
being returned. |
| 18583 |
|
| 18584 |
|
| 18585 |
|
| 18586 |
|
| 18587 |
|
| 18588 |
<span class="grey">Shepler, et al. Standards Track [Page 332]</span></pre> |
| 18589 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-333" ></span> |
| 18590 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18591 |
|
| 18592 |
|
| 18593 |
<span class="h3"><a class="selflink" id="section-13.11" href="#section-13.11">13.11</a>. Layout Revocation and Fencing</span> |
| 18594 |
|
| 18595 |
As described in <a href="#section-12.7">Section 12.7</a>, the layout-type-specific storage |
| 18596 |
protocol is responsible for handling the effects of I/Os that started |
| 18597 |
before lease expiration and extend through lease expiration. The |
| 18598 |
LAYOUT4_NFSV4_1_FILES layout type can prevent all I/Os to data |
| 18599 |
servers from being executed after lease expiration (this prevention |
| 18600 |
is called "fencing"), without relying on a precise client lease timer |
| 18601 |
and without requiring data servers to maintain lease timers. The |
| 18602 |
LAYOUT4_NFSV4_1_FILES pNFS server has the flexibility to revoke |
| 18603 |
individual layouts, and thus fence I/O on a per-file basis. |
| 18604 |
|
| 18605 |
In addition to lease expiration, the reasons a layout can be revoked |
| 18606 |
include: client fails to respond to a CB_LAYOUTRECALL, the metadata |
| 18607 |
server restarts, or administrative intervention. Regardless of the |
| 18608 |
reason, once a client's layout has been revoked, the pNFS server MUST |
| 18609 |
prevent the client from sending I/O for the affected file from and to |
| 18610 |
all data servers; in other words, it MUST fence the client from the |
| 18611 |
affected file on the data servers. |
| 18612 |
|
| 18613 |
Fencing works as follows. As described in <a href="#section-13.1">Section 13.1</a>, in COMPOUND |
| 18614 |
procedure requests to the data server, the data filehandle provided |
| 18615 |
by the PUTFH operation and the stateid in the READ or WRITE operation |
| 18616 |
are used to ensure that the client has a valid layout for the I/O |
| 18617 |
being performed; if it does not, the I/O is rejected with |
| 18618 |
NFS4ERR_PNFS_NO_LAYOUT. The server can simply check the stateid and, |
| 18619 |
additionally, make the data filehandle stale if the layout specified |
| 18620 |
a data filehandle that is different from the metadata server's |
| 18621 |
filehandle for the file (see the nfl_fh_list description in |
| 18622 |
<a href="#section-13.3">Section 13.3</a>). |
| 18623 |
|
| 18624 |
Before the metadata server takes any action to revoke layout state |
| 18625 |
given out by a previous instance, it must make sure that all layout |
| 18626 |
state from that previous instance are invalidated at the data |
| 18627 |
servers. This has the following implications. |
| 18628 |
|
| 18629 |
o The metadata server must not restripe a file until it has |
| 18630 |
contacted all of the data servers to invalidate the layouts from |
| 18631 |
the previous instance. |
| 18632 |
|
| 18633 |
o The metadata server must not give out mandatory locks that |
| 18634 |
conflict with layouts from the previous instance without either |
| 18635 |
doing a specific layout invalidation (as it would have to do |
| 18636 |
anyway) or doing a global data server invalidation. |
| 18637 |
|
| 18638 |
|
| 18639 |
|
| 18640 |
|
| 18641 |
|
| 18642 |
|
| 18643 |
|
| 18644 |
<span class="grey">Shepler, et al. Standards Track [Page 333]</span></pre> |
| 18645 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-334" ></span> |
| 18646 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18647 |
|
| 18648 |
|
| 18649 |
<span class="h3"><a class="selflink" id="section-13.12" href="#section-13.12">13.12</a>. Security Considerations for the File Layout Type</span> |
| 18650 |
|
| 18651 |
The NFSv4.1 file layout type MUST adhere to the security |
| 18652 |
considerations outlined in <a href="#section-12.9">Section 12.9</a>. NFSv4.1 data servers MUST |
| 18653 |
make all of the required access checks on each READ or WRITE I/O as |
| 18654 |
determined by the NFSv4.1 protocol. If the metadata server would |
| 18655 |
deny a READ or WRITE operation on a file due to its ACL, mode |
| 18656 |
attribute, open access mode, open deny mode, mandatory byte-range |
| 18657 |
lock state, or any other attributes and state, the data server MUST |
| 18658 |
also deny the READ or WRITE operation. This impacts the control |
| 18659 |
protocol and the propagation of state from the metadata server to the |
| 18660 |
data servers; see <a href="#section-13.9.2">Section 13.9.2</a> for more details. |
| 18661 |
|
| 18662 |
The methods for authentication, integrity, and privacy for data |
| 18663 |
servers based on the LAYOUT4_NFSV4_1_FILES layout type are the same |
| 18664 |
as those used by metadata servers. Metadata and data servers use ONC |
| 18665 |
RPC security flavors to authenticate, and SECINFO and SECINFO_NO_NAME |
| 18666 |
to negotiate the security mechanism and services to be used. Thus, |
| 18667 |
when using the LAYOUT4_NFSV4_1_FILES layout type, the impact on the |
| 18668 |
RPC-based security model due to pNFS (as alluded to in Sections <a href="#section-1.7.1">1.7.1</a> |
| 18669 |
and 1.7.2.2) is zero. |
| 18670 |
|
| 18671 |
For a given file object, a metadata server MAY require different |
| 18672 |
security parameters (secinfo4 value) than the data server. For a |
| 18673 |
given file object with multiple data servers, the secinfo4 value |
| 18674 |
SHOULD be the same across all data servers. If the secinfo4 values |
| 18675 |
across a metadata server and its data servers differ for a specific |
| 18676 |
file, the mapping of the principal to the server's internal user |
| 18677 |
identifier MUST be the same in order for the access-control checks |
| 18678 |
based on ACL, mode, open and deny mode, and mandatory locking to be |
| 18679 |
consistent across on the pNFS server. |
| 18680 |
|
| 18681 |
If an NFSv4.1 implementation supports pNFS and supports NFSv4.1 file |
| 18682 |
layouts, then the implementation MUST support the SECINFO_NO_NAME |
| 18683 |
operation on both the metadata and data servers. |
| 18684 |
|
| 18685 |
<span class="h2"><a class="selflink" id="section-14" href="#section-14">14</a>. Internationalization</span> |
| 18686 |
|
| 18687 |
The primary issue in which NFSv4.1 needs to deal with |
| 18688 |
internationalization, or I18N, is with respect to file names and |
| 18689 |
other strings as used within the protocol. The choice of string |
| 18690 |
representation must allow reasonable name/string access to clients |
| 18691 |
that use various languages. The UTF-8 encoding of the UCS (Universal |
| 18692 |
Multiple-Octet Coded Character Set) as defined by ISO10646 [<a href="#ref-21" title=""Information Technology - Universal Multiple-octet coded Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane"">21</a>] |
| 18693 |
allows for this type of access and follows the policy described in |
| 18694 |
"IETF Policy on Character Sets and Languages", <a href="./rfc2277">RFC 2277</a> [<a href="#ref-22" title=""IETF Policy on Character Sets and Languages"">22</a>]. |
| 18695 |
|
| 18696 |
|
| 18697 |
|
| 18698 |
|
| 18699 |
|
| 18700 |
<span class="grey">Shepler, et al. Standards Track [Page 334]</span></pre> |
| 18701 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-335" ></span> |
| 18702 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18703 |
|
| 18704 |
|
| 18705 |
<a href="./rfc3454">RFC 3454</a> [<a href="#ref-19" title=""Preparation of Internationalized Strings ("">19</a>], otherwise know as "stringprep", documents a framework |
| 18706 |
for using Unicode/UTF-8 in networking protocols so as "to increase |
| 18707 |
the likelihood that string input and string comparison work in ways |
| 18708 |
that make sense for typical users throughout the world". A protocol |
| 18709 |
must define a profile of stringprep "in order to fully specify the |
| 18710 |
processing options". The remainder of this section defines the |
| 18711 |
NFSv4.1 stringprep profiles. Much of the terminology used for the |
| 18712 |
remainder of this section comes from stringprep. |
| 18713 |
|
| 18714 |
There are three UTF-8 string types defined for NFSv4.1: utf8str_cs, |
| 18715 |
utf8str_cis, and utf8str_mixed. Separate profiles are defined for |
| 18716 |
each. Each profile defines the following, as required by stringprep: |
| 18717 |
|
| 18718 |
o The intended applicability of the profile. |
| 18719 |
|
| 18720 |
o The character repertoire that is the input and output to |
| 18721 |
stringprep (which is Unicode 3.2 for the referenced version of |
| 18722 |
stringprep). However, NFSv4.1 implementations are not limited to |
| 18723 |
3.2. |
| 18724 |
|
| 18725 |
o The mapping tables from stringprep used (as described in <a href="#section-3">Section 3</a> |
| 18726 |
of stringprep). |
| 18727 |
|
| 18728 |
o Any additional mapping tables specific to the profile. |
| 18729 |
|
| 18730 |
o The Unicode normalization used, if any (as described in <a href="#section-4">Section 4</a> |
| 18731 |
of stringprep). |
| 18732 |
|
| 18733 |
o The tables from the stringprep listing of characters that are |
| 18734 |
prohibited as output (as described in <a href="#section-5">Section 5</a> of stringprep). |
| 18735 |
|
| 18736 |
o The bidirectional string testing used, if any (as described in |
| 18737 |
<a href="#section-6">Section 6</a> of stringprep). |
| 18738 |
|
| 18739 |
o Any additional characters that are prohibited as output specific |
| 18740 |
to the profile. |
| 18741 |
|
| 18742 |
Stringprep discusses Unicode characters, whereas NFSv4.1 renders |
| 18743 |
UTF-8 characters. Since there is a one-to-one mapping from UTF-8 to |
| 18744 |
Unicode, when the remainder of this document refers to Unicode, the |
| 18745 |
reader should assume UTF-8. |
| 18746 |
|
| 18747 |
Much of the text for the profiles comes from <a href="./rfc3491">RFC 3491</a> [<a href="#ref-23" title=""Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)"">23</a>]. |
| 18748 |
|
| 18749 |
|
| 18750 |
|
| 18751 |
|
| 18752 |
|
| 18753 |
|
| 18754 |
|
| 18755 |
|
| 18756 |
<span class="grey">Shepler, et al. Standards Track [Page 335]</span></pre> |
| 18757 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-336" ></span> |
| 18758 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18759 |
|
| 18760 |
|
| 18761 |
<span class="h3"><a class="selflink" id="section-14.1" href="#section-14.1">14.1</a>. Stringprep Profile for the utf8str_cs Type</span> |
| 18762 |
|
| 18763 |
Every use of the utf8str_cs type definition in the NFSv4 protocol |
| 18764 |
specification follows the profile named nfs4_cs_prep. |
| 18765 |
|
| 18766 |
<span class="h4"><a class="selflink" id="section-14.1.1" href="#section-14.1.1">14.1.1</a>. Intended Applicability of the nfs4_cs_prep Profile</span> |
| 18767 |
|
| 18768 |
The utf8str_cs type is a case-sensitive string of UTF-8 characters. |
| 18769 |
Its primary use in NFSv4.1 is for naming components and pathnames. |
| 18770 |
Components and pathnames are stored on the server's file system. Two |
| 18771 |
valid distinct UTF-8 strings might be the same after processing via |
| 18772 |
the utf8str_cs profile. If the strings are two names inside a |
| 18773 |
directory, the NFSv4.1 server will need to either: |
| 18774 |
|
| 18775 |
o disallow the creation of a second name if its post-processed form |
| 18776 |
collides with that of an existing name, or |
| 18777 |
|
| 18778 |
o allow the creation of the second name, but arrange so that after |
| 18779 |
post-processing, the second name is different than the post- |
| 18780 |
processed form of the first name. |
| 18781 |
|
| 18782 |
<span class="h4"><a class="selflink" id="section-14.1.2" href="#section-14.1.2">14.1.2</a>. Character Repertoire of nfs4_cs_prep</span> |
| 18783 |
|
| 18784 |
The nfs4_cs_prep profile uses Unicode 3.2, as defined in stringprep's |
| 18785 |
<a href="#appendix-A.1">Appendix A.1</a>. However, NFSv4.1 implementations are not limited to |
| 18786 |
3.2. |
| 18787 |
|
| 18788 |
<span class="h4"><a class="selflink" id="section-14.1.3" href="#section-14.1.3">14.1.3</a>. Mapping Used by nfs4_cs_prep</span> |
| 18789 |
|
| 18790 |
The nfs4_cs_prep profile specifies mapping using the following tables |
| 18791 |
from stringprep: |
| 18792 |
|
| 18793 |
Table B.1 |
| 18794 |
|
| 18795 |
Table B.2 is normally not part of the nfs4_cs_prep profile as it is |
| 18796 |
primarily for dealing with case-insensitive comparisons. However, if |
| 18797 |
the NFSv4.1 file server supports the case_insensitive file system |
| 18798 |
attribute, and if case_insensitive is TRUE, the NFSv4.1 server MUST |
| 18799 |
use Table B.2 (in addition to Table B1) when processing utf8str_cs |
| 18800 |
strings, and the NFSv4.1 client MUST assume Table B.2 (in addition to |
| 18801 |
Table B.1) is being used. |
| 18802 |
|
| 18803 |
If the case_preserving attribute is present and set to FALSE, then |
| 18804 |
the NFSv4.1 server MUST use Table B.2 to map case when processing |
| 18805 |
utf8str_cs strings. Whether the server maps from lower to upper case |
| 18806 |
or from upper to lower case is an implementation dependency. |
| 18807 |
|
| 18808 |
|
| 18809 |
|
| 18810 |
|
| 18811 |
|
| 18812 |
<span class="grey">Shepler, et al. Standards Track [Page 336]</span></pre> |
| 18813 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-337" ></span> |
| 18814 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18815 |
|
| 18816 |
|
| 18817 |
<span class="h4"><a class="selflink" id="section-14.1.4" href="#section-14.1.4">14.1.4</a>. Normalization used by nfs4_cs_prep</span> |
| 18818 |
|
| 18819 |
The nfs4_cs_prep profile does not specify a normalization form. A |
| 18820 |
later revision of this specification may specify a particular |
| 18821 |
normalization form. Therefore, the server and client can expect that |
| 18822 |
they may receive unnormalized characters within protocol requests and |
| 18823 |
responses. If the operating environment requires normalization, then |
| 18824 |
the implementation must normalize utf8str_cs strings within the |
| 18825 |
protocol before presenting the information to an application (at the |
| 18826 |
client) or local file system (at the server). |
| 18827 |
|
| 18828 |
<span class="h4"><a class="selflink" id="section-14.1.5" href="#section-14.1.5">14.1.5</a>. Prohibited Output for nfs4_cs_prep</span> |
| 18829 |
|
| 18830 |
The nfs4_cs_prep profile RECOMMENDS prohibiting the use of the |
| 18831 |
following tables from stringprep: |
| 18832 |
|
| 18833 |
Table C.5 |
| 18834 |
|
| 18835 |
Table C.6 |
| 18836 |
|
| 18837 |
<span class="h4"><a class="selflink" id="section-14.1.6" href="#section-14.1.6">14.1.6</a>. Bidirectional Output for nfs4_cs_prep</span> |
| 18838 |
|
| 18839 |
The nfs4_cs_prep profile does not specify any checking of |
| 18840 |
bidirectional strings. |
| 18841 |
|
| 18842 |
<span class="h3"><a class="selflink" id="section-14.2" href="#section-14.2">14.2</a>. Stringprep Profile for the utf8str_cis Type</span> |
| 18843 |
|
| 18844 |
Every use of the utf8str_cis type definition in the NFSv4.1 protocol |
| 18845 |
specification follows the profile named nfs4_cis_prep. |
| 18846 |
|
| 18847 |
<span class="h4"><a class="selflink" id="section-14.2.1" href="#section-14.2.1">14.2.1</a>. Intended Applicability of the nfs4_cis_prep Profile</span> |
| 18848 |
|
| 18849 |
The utf8str_cis type is a case-insensitive string of UTF-8 |
| 18850 |
characters. Its primary use in NFSv4.1 is for naming NFS servers. |
| 18851 |
|
| 18852 |
<span class="h4"><a class="selflink" id="section-14.2.2" href="#section-14.2.2">14.2.2</a>. Character Repertoire of nfs4_cis_prep</span> |
| 18853 |
|
| 18854 |
The nfs4_cis_prep profile uses Unicode 3.2, as defined in |
| 18855 |
stringprep's <a href="#appendix-A.1">Appendix A.1</a>. However, NFSv4.1 implementations are not |
| 18856 |
limited to 3.2. |
| 18857 |
|
| 18858 |
|
| 18859 |
|
| 18860 |
|
| 18861 |
|
| 18862 |
|
| 18863 |
|
| 18864 |
|
| 18865 |
|
| 18866 |
|
| 18867 |
|
| 18868 |
<span class="grey">Shepler, et al. Standards Track [Page 337]</span></pre> |
| 18869 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-338" ></span> |
| 18870 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18871 |
|
| 18872 |
|
| 18873 |
<span class="h4"><a class="selflink" id="section-14.2.3" href="#section-14.2.3">14.2.3</a>. Mapping Used by nfs4_cis_prep</span> |
| 18874 |
|
| 18875 |
The nfs4_cis_prep profile specifies mapping using the following |
| 18876 |
tables from stringprep: |
| 18877 |
|
| 18878 |
Table B.1 |
| 18879 |
|
| 18880 |
Table B.2 |
| 18881 |
|
| 18882 |
<span class="h4"><a class="selflink" id="section-14.2.4" href="#section-14.2.4">14.2.4</a>. Normalization Used by nfs4_cis_prep</span> |
| 18883 |
|
| 18884 |
The nfs4_cis_prep profile specifies using Unicode normalization form |
| 18885 |
KC, as described in stringprep. |
| 18886 |
|
| 18887 |
<span class="h4"><a class="selflink" id="section-14.2.5" href="#section-14.2.5">14.2.5</a>. Prohibited Output for nfs4_cis_prep</span> |
| 18888 |
|
| 18889 |
The nfs4_cis_prep profile specifies prohibiting using the following |
| 18890 |
tables from stringprep: |
| 18891 |
|
| 18892 |
Table C.1.2 |
| 18893 |
|
| 18894 |
Table C.2.2 |
| 18895 |
|
| 18896 |
Table C.3 |
| 18897 |
|
| 18898 |
Table C.4 |
| 18899 |
|
| 18900 |
Table C.5 |
| 18901 |
|
| 18902 |
Table C.6 |
| 18903 |
|
| 18904 |
Table C.7 |
| 18905 |
|
| 18906 |
Table C.8 |
| 18907 |
|
| 18908 |
Table C.9 |
| 18909 |
|
| 18910 |
<span class="h4"><a class="selflink" id="section-14.2.6" href="#section-14.2.6">14.2.6</a>. Bidirectional Output for nfs4_cis_prep</span> |
| 18911 |
|
| 18912 |
The nfs4_cis_prep profile specifies checking bidirectional strings as |
| 18913 |
described in stringprep's <a href="#section-6">Section 6</a>. |
| 18914 |
|
| 18915 |
<span class="h3"><a class="selflink" id="section-14.3" href="#section-14.3">14.3</a>. Stringprep Profile for the utf8str_mixed Type</span> |
| 18916 |
|
| 18917 |
Every use of the utf8str_mixed type definition in the NFSv4.1 |
| 18918 |
protocol specification follows the profile named nfs4_mixed_prep. |
| 18919 |
|
| 18920 |
|
| 18921 |
|
| 18922 |
|
| 18923 |
|
| 18924 |
<span class="grey">Shepler, et al. Standards Track [Page 338]</span></pre> |
| 18925 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-339" ></span> |
| 18926 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18927 |
|
| 18928 |
|
| 18929 |
<span class="h4"><a class="selflink" id="section-14.3.1" href="#section-14.3.1">14.3.1</a>. Intended Applicability of the nfs4_mixed_prep Profile</span> |
| 18930 |
|
| 18931 |
The utf8str_mixed type is a string of UTF-8 characters, with a prefix |
| 18932 |
that is case sensitive, a separator equal to '@', and a suffix that |
| 18933 |
is a fully qualified domain name. Its primary use in NFSv4.1 is for |
| 18934 |
naming principals identified in an Access Control Entry. |
| 18935 |
|
| 18936 |
<span class="h4"><a class="selflink" id="section-14.3.2" href="#section-14.3.2">14.3.2</a>. Character Repertoire of nfs4_mixed_prep</span> |
| 18937 |
|
| 18938 |
The nfs4_mixed_prep profile uses Unicode 3.2, as defined in |
| 18939 |
stringprep's <a href="#appendix-A.1">Appendix A.1</a>. However, NFSv4.1 implementations are not |
| 18940 |
limited to 3.2. |
| 18941 |
|
| 18942 |
<span class="h4"><a class="selflink" id="section-14.3.3" href="#section-14.3.3">14.3.3</a>. Mapping Used by nfs4_cis_prep</span> |
| 18943 |
|
| 18944 |
For the prefix and the separator of a utf8str_mixed string, the |
| 18945 |
nfs4_mixed_prep profile specifies mapping using the following table |
| 18946 |
from stringprep: |
| 18947 |
|
| 18948 |
Table B.1 |
| 18949 |
|
| 18950 |
For the suffix of a utf8str_mixed string, the nfs4_mixed_prep profile |
| 18951 |
specifies mapping using the following tables from stringprep: |
| 18952 |
|
| 18953 |
Table B.1 |
| 18954 |
|
| 18955 |
Table B.2 |
| 18956 |
|
| 18957 |
<span class="h4"><a class="selflink" id="section-14.3.4" href="#section-14.3.4">14.3.4</a>. Normalization Used by nfs4_mixed_prep</span> |
| 18958 |
|
| 18959 |
The nfs4_mixed_prep profile specifies using Unicode normalization |
| 18960 |
form KC, as described in stringprep. |
| 18961 |
|
| 18962 |
<span class="h4"><a class="selflink" id="section-14.3.5" href="#section-14.3.5">14.3.5</a>. Prohibited Output for nfs4_mixed_prep</span> |
| 18963 |
|
| 18964 |
The nfs4_mixed_prep profile specifies prohibiting using the following |
| 18965 |
tables from stringprep: |
| 18966 |
|
| 18967 |
Table C.1.2 |
| 18968 |
|
| 18969 |
Table C.2.2 |
| 18970 |
|
| 18971 |
Table C.3 |
| 18972 |
|
| 18973 |
Table C.4 |
| 18974 |
|
| 18975 |
Table C.5 |
| 18976 |
|
| 18977 |
|
| 18978 |
|
| 18979 |
|
| 18980 |
<span class="grey">Shepler, et al. Standards Track [Page 339]</span></pre> |
| 18981 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-340" ></span> |
| 18982 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 18983 |
|
| 18984 |
|
| 18985 |
Table C.6 |
| 18986 |
|
| 18987 |
Table C.7 |
| 18988 |
|
| 18989 |
Table C.8 |
| 18990 |
|
| 18991 |
Table C.9 |
| 18992 |
|
| 18993 |
<span class="h4"><a class="selflink" id="section-14.3.6" href="#section-14.3.6">14.3.6</a>. Bidirectional Output for nfs4_mixed_prep</span> |
| 18994 |
|
| 18995 |
The nfs4_mixed_prep profile specifies checking bidirectional strings |
| 18996 |
as described in stringprep's <a href="#section-6">Section 6</a>. |
| 18997 |
|
| 18998 |
<span class="h3"><a class="selflink" id="section-14.4" href="#section-14.4">14.4</a>. UTF-8 Capabilities</span> |
| 18999 |
|
| 19000 |
const FSCHARSET_CAP4_CONTAINS_NON_UTF8 = 0x1; |
| 19001 |
const FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 = 0x2; |
| 19002 |
|
| 19003 |
typedef uint32_t fs_charset_cap4; |
| 19004 |
|
| 19005 |
Because some operating environments and file systems do not enforce |
| 19006 |
character set encodings, NFSv4.1 supports the fs_charset_cap |
| 19007 |
attribute (<a href="#section-5.8.2.11">Section 5.8.2.11</a>) that indicates to the client a file |
| 19008 |
system's UTF-8 capabilities. The attribute is an integer containing |
| 19009 |
a pair of flags. The first flag is FSCHARSET_CAP4_CONTAINS_NON_UTF8, |
| 19010 |
which, if set to one, tells the client that the file system contains |
| 19011 |
non-UTF-8 characters, and the server will not convert non-UTF |
| 19012 |
characters to UTF-8 if the client reads a symlink or directory, |
| 19013 |
neither will operations with component names or pathnames in the |
| 19014 |
arguments convert the strings to UTF-8. The second flag is |
| 19015 |
FSCHARSET_CAP4_ALLOWS_ONLY_UTF8, which, if set to one, indicates that |
| 19016 |
the server will accept (and generate) only UTF-8 characters on the |
| 19017 |
file system. If FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 is set to one, |
| 19018 |
FSCHARSET_CAP4_CONTAINS_NON_UTF8 MUST be set to zero. |
| 19019 |
FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 SHOULD always be set to one. |
| 19020 |
|
| 19021 |
<span class="h3"><a class="selflink" id="section-14.5" href="#section-14.5">14.5</a>. UTF-8 Related Errors</span> |
| 19022 |
|
| 19023 |
Where the client sends an invalid UTF-8 string, the server should |
| 19024 |
return NFS4ERR_INVAL (see Table 5). This includes cases in which |
| 19025 |
inappropriate prefixes are detected and where the count includes |
| 19026 |
trailing bytes that do not constitute a full UCS character. |
| 19027 |
|
| 19028 |
Where the client-supplied string is valid UTF-8 but contains |
| 19029 |
characters that are not supported by the server as a value for that |
| 19030 |
string (e.g., names containing characters outside of Unicode plane 0 |
| 19031 |
|
| 19032 |
|
| 19033 |
|
| 19034 |
|
| 19035 |
|
| 19036 |
<span class="grey">Shepler, et al. Standards Track [Page 340]</span></pre> |
| 19037 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-341" ></span> |
| 19038 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19039 |
|
| 19040 |
|
| 19041 |
on file systems that fail to support such characters despite their |
| 19042 |
presence in the Unicode standard), the server should return |
| 19043 |
NFS4ERR_BADCHAR. |
| 19044 |
|
| 19045 |
Where a UTF-8 string is used as a file name, and the file system |
| 19046 |
(while supporting all of the characters within the name) does not |
| 19047 |
allow that particular name to be used, the server should return the |
| 19048 |
error NFS4ERR_BADNAME (Table 5). This includes situations in which |
| 19049 |
the server file system imposes a normalization constraint on name |
| 19050 |
strings, but will also include such situations as file system |
| 19051 |
prohibitions of "." and ".." as file names for certain operations, |
| 19052 |
and other such constraints. |
| 19053 |
|
| 19054 |
<span class="h2"><a class="selflink" id="section-15" href="#section-15">15</a>. Error Values</span> |
| 19055 |
|
| 19056 |
NFS error numbers are assigned to failed operations within a Compound |
| 19057 |
(COMPOUND or CB_COMPOUND) request. A Compound request contains a |
| 19058 |
number of NFS operations that have their results encoded in sequence |
| 19059 |
in a Compound reply. The results of successful operations will |
| 19060 |
consist of an NFS4_OK status followed by the encoded results of the |
| 19061 |
operation. If an NFS operation fails, an error status will be |
| 19062 |
entered in the reply and the Compound request will be terminated. |
| 19063 |
|
| 19064 |
<span class="h3"><a class="selflink" id="section-15.1" href="#section-15.1">15.1</a>. Error Definitions</span> |
| 19065 |
|
| 19066 |
Protocol Error Definitions |
| 19067 |
|
| 19068 |
+-----------------------------------+--------+-------------------+ |
| 19069 |
| Error | Number | Description | |
| 19070 |
+-----------------------------------+--------+-------------------+ |
| 19071 |
| NFS4_OK | 0 | <a href="#section-15.1.3.1">Section 15.1.3.1</a> | |
| 19072 |
| NFS4ERR_ACCESS | 13 | <a href="#section-15.1.6.1">Section 15.1.6.1</a> | |
| 19073 |
| NFS4ERR_ATTRNOTSUPP | 10032 | <a href="#section-15.1.15.1">Section 15.1.15.1</a> | |
| 19074 |
| NFS4ERR_ADMIN_REVOKED | 10047 | <a href="#section-15.1.5.1">Section 15.1.5.1</a> | |
| 19075 |
| NFS4ERR_BACK_CHAN_BUSY | 10057 | <a href="#section-15.1.12.1">Section 15.1.12.1</a> | |
| 19076 |
| NFS4ERR_BADCHAR | 10040 | <a href="#section-15.1.7.1">Section 15.1.7.1</a> | |
| 19077 |
| NFS4ERR_BADHANDLE | 10001 | <a href="#section-15.1.2.1">Section 15.1.2.1</a> | |
| 19078 |
| NFS4ERR_BADIOMODE | 10049 | <a href="#section-15.1.10.1">Section 15.1.10.1</a> | |
| 19079 |
| NFS4ERR_BADLAYOUT | 10050 | <a href="#section-15.1.10.2">Section 15.1.10.2</a> | |
| 19080 |
| NFS4ERR_BADNAME | 10041 | <a href="#section-15.1.7.2">Section 15.1.7.2</a> | |
| 19081 |
| NFS4ERR_BADOWNER | 10039 | <a href="#section-15.1.15.2">Section 15.1.15.2</a> | |
| 19082 |
| NFS4ERR_BADSESSION | 10052 | <a href="#section-15.1.11.1">Section 15.1.11.1</a> | |
| 19083 |
| NFS4ERR_BADSLOT | 10053 | <a href="#section-15.1.11.2">Section 15.1.11.2</a> | |
| 19084 |
| NFS4ERR_BADTYPE | 10007 | <a href="#section-15.1.4.1">Section 15.1.4.1</a> | |
| 19085 |
| NFS4ERR_BADXDR | 10036 | <a href="#section-15.1.1.1">Section 15.1.1.1</a> | |
| 19086 |
| NFS4ERR_BAD_COOKIE | 10003 | <a href="#section-15.1.1.2">Section 15.1.1.2</a> | |
| 19087 |
| NFS4ERR_BAD_HIGH_SLOT | 10077 | <a href="#section-15.1.11.3">Section 15.1.11.3</a> | |
| 19088 |
| NFS4ERR_BAD_RANGE | 10042 | <a href="#section-15.1.8.1">Section 15.1.8.1</a> | |
| 19089 |
|
| 19090 |
|
| 19091 |
|
| 19092 |
<span class="grey">Shepler, et al. Standards Track [Page 341]</span></pre> |
| 19093 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-342" ></span> |
| 19094 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19095 |
|
| 19096 |
|
| 19097 |
| NFS4ERR_BAD_SEQID | 10026 | <a href="#section-15.1.16.1">Section 15.1.16.1</a> | |
| 19098 |
| NFS4ERR_BAD_SESSION_DIGEST | 10051 | <a href="#section-15.1.12.2">Section 15.1.12.2</a> | |
| 19099 |
| NFS4ERR_BAD_STATEID | 10025 | <a href="#section-15.1.5.2">Section 15.1.5.2</a> | |
| 19100 |
| NFS4ERR_CB_PATH_DOWN | 10048 | <a href="#section-15.1.11.4">Section 15.1.11.4</a> | |
| 19101 |
| NFS4ERR_CLID_INUSE | 10017 | <a href="#section-15.1.13.2">Section 15.1.13.2</a> | |
| 19102 |
| NFS4ERR_CLIENTID_BUSY | 10074 | <a href="#section-15.1.13.1">Section 15.1.13.1</a> | |
| 19103 |
| NFS4ERR_COMPLETE_ALREADY | 10054 | <a href="#section-15.1.9.1">Section 15.1.9.1</a> | |
| 19104 |
| NFS4ERR_CONN_NOT_BOUND_TO_SESSION | 10055 | <a href="#section-15.1.11.6">Section 15.1.11.6</a> | |
| 19105 |
| NFS4ERR_DEADLOCK | 10045 | <a href="#section-15.1.8.2">Section 15.1.8.2</a> | |
| 19106 |
| NFS4ERR_DEADSESSION | 10078 | <a href="#section-15.1.11.5">Section 15.1.11.5</a> | |
| 19107 |
| NFS4ERR_DELAY | 10008 | <a href="#section-15.1.1.3">Section 15.1.1.3</a> | |
| 19108 |
| NFS4ERR_DELEG_ALREADY_WANTED | 10056 | <a href="#section-15.1.14.1">Section 15.1.14.1</a> | |
| 19109 |
| NFS4ERR_DELEG_REVOKED | 10087 | <a href="#section-15.1.5.3">Section 15.1.5.3</a> | |
| 19110 |
| NFS4ERR_DENIED | 10010 | <a href="#section-15.1.8.3">Section 15.1.8.3</a> | |
| 19111 |
| NFS4ERR_DIRDELEG_UNAVAIL | 10084 | <a href="#section-15.1.14.2">Section 15.1.14.2</a> | |
| 19112 |
| NFS4ERR_DQUOT | 69 | <a href="#section-15.1.4.2">Section 15.1.4.2</a> | |
| 19113 |
| NFS4ERR_ENCR_ALG_UNSUPP | 10079 | <a href="#section-15.1.13.3">Section 15.1.13.3</a> | |
| 19114 |
| NFS4ERR_EXIST | 17 | <a href="#section-15.1.4.3">Section 15.1.4.3</a> | |
| 19115 |
| NFS4ERR_EXPIRED | 10011 | <a href="#section-15.1.5.4">Section 15.1.5.4</a> | |
| 19116 |
| NFS4ERR_FBIG | 27 | <a href="#section-15.1.4.4">Section 15.1.4.4</a> | |
| 19117 |
| NFS4ERR_FHEXPIRED | 10014 | <a href="#section-15.1.2.2">Section 15.1.2.2</a> | |
| 19118 |
| NFS4ERR_FILE_OPEN | 10046 | <a href="#section-15.1.4.5">Section 15.1.4.5</a> | |
| 19119 |
| NFS4ERR_GRACE | 10013 | <a href="#section-15.1.9.2">Section 15.1.9.2</a> | |
| 19120 |
| NFS4ERR_HASH_ALG_UNSUPP | 10072 | <a href="#section-15.1.13.4">Section 15.1.13.4</a> | |
| 19121 |
| NFS4ERR_INVAL | 22 | <a href="#section-15.1.1.4">Section 15.1.1.4</a> | |
| 19122 |
| NFS4ERR_IO | 5 | <a href="#section-15.1.4.6">Section 15.1.4.6</a> | |
| 19123 |
| NFS4ERR_ISDIR | 21 | <a href="#section-15.1.2.3">Section 15.1.2.3</a> | |
| 19124 |
| NFS4ERR_LAYOUTTRYLATER | 10058 | <a href="#section-15.1.10.3">Section 15.1.10.3</a> | |
| 19125 |
| NFS4ERR_LAYOUTUNAVAILABLE | 10059 | <a href="#section-15.1.10.4">Section 15.1.10.4</a> | |
| 19126 |
| NFS4ERR_LEASE_MOVED | 10031 | <a href="#section-15.1.16.2">Section 15.1.16.2</a> | |
| 19127 |
| NFS4ERR_LOCKED | 10012 | <a href="#section-15.1.8.4">Section 15.1.8.4</a> | |
| 19128 |
| NFS4ERR_LOCKS_HELD | 10037 | <a href="#section-15.1.8.5">Section 15.1.8.5</a> | |
| 19129 |
| NFS4ERR_LOCK_NOTSUPP | 10043 | <a href="#section-15.1.8.6">Section 15.1.8.6</a> | |
| 19130 |
| NFS4ERR_LOCK_RANGE | 10028 | <a href="#section-15.1.8.7">Section 15.1.8.7</a> | |
| 19131 |
| NFS4ERR_MINOR_VERS_MISMATCH | 10021 | <a href="#section-15.1.3.2">Section 15.1.3.2</a> | |
| 19132 |
| NFS4ERR_MLINK | 31 | <a href="#section-15.1.4.7">Section 15.1.4.7</a> | |
| 19133 |
| NFS4ERR_MOVED | 10019 | <a href="#section-15.1.2.4">Section 15.1.2.4</a> | |
| 19134 |
| NFS4ERR_NAMETOOLONG | 63 | <a href="#section-15.1.7.3">Section 15.1.7.3</a> | |
| 19135 |
| NFS4ERR_NOENT | 2 | <a href="#section-15.1.4.8">Section 15.1.4.8</a> | |
| 19136 |
| NFS4ERR_NOFILEHANDLE | 10020 | <a href="#section-15.1.2.5">Section 15.1.2.5</a> | |
| 19137 |
| NFS4ERR_NOMATCHING_LAYOUT | 10060 | <a href="#section-15.1.10.5">Section 15.1.10.5</a> | |
| 19138 |
| NFS4ERR_NOSPC | 28 | <a href="#section-15.1.4.9">Section 15.1.4.9</a> | |
| 19139 |
| NFS4ERR_NOTDIR | 20 | <a href="#section-15.1.2.6">Section 15.1.2.6</a> | |
| 19140 |
| NFS4ERR_NOTEMPTY | 66 | <a href="#section-15.1.4.10">Section 15.1.4.10</a> | |
| 19141 |
| NFS4ERR_NOTSUPP | 10004 | <a href="#section-15.1.1.5">Section 15.1.1.5</a> | |
| 19142 |
| NFS4ERR_NOT_ONLY_OP | 10081 | <a href="#section-15.1.3.3">Section 15.1.3.3</a> | |
| 19143 |
| NFS4ERR_NOT_SAME | 10027 | <a href="#section-15.1.15.3">Section 15.1.15.3</a> | |
| 19144 |
| NFS4ERR_NO_GRACE | 10033 | <a href="#section-15.1.9.3">Section 15.1.9.3</a> | |
| 19145 |
|
| 19146 |
|
| 19147 |
|
| 19148 |
<span class="grey">Shepler, et al. Standards Track [Page 342]</span></pre> |
| 19149 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-343" ></span> |
| 19150 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19151 |
|
| 19152 |
|
| 19153 |
| NFS4ERR_NXIO | 6 | <a href="#section-15.1.16.3">Section 15.1.16.3</a> | |
| 19154 |
| NFS4ERR_OLD_STATEID | 10024 | <a href="#section-15.1.5.5">Section 15.1.5.5</a> | |
| 19155 |
| NFS4ERR_OPENMODE | 10038 | <a href="#section-15.1.8.8">Section 15.1.8.8</a> | |
| 19156 |
| NFS4ERR_OP_ILLEGAL | 10044 | <a href="#section-15.1.3.4">Section 15.1.3.4</a> | |
| 19157 |
| NFS4ERR_OP_NOT_IN_SESSION | 10071 | <a href="#section-15.1.3.5">Section 15.1.3.5</a> | |
| 19158 |
| NFS4ERR_PERM | 1 | <a href="#section-15.1.6.2">Section 15.1.6.2</a> | |
| 19159 |
| NFS4ERR_PNFS_IO_HOLE | 10075 | <a href="#section-15.1.10.6">Section 15.1.10.6</a> | |
| 19160 |
| NFS4ERR_PNFS_NO_LAYOUT | 10080 | <a href="#section-15.1.10.7">Section 15.1.10.7</a> | |
| 19161 |
| NFS4ERR_RECALLCONFLICT | 10061 | <a href="#section-15.1.14.3">Section 15.1.14.3</a> | |
| 19162 |
| NFS4ERR_RECLAIM_BAD | 10034 | <a href="#section-15.1.9.4">Section 15.1.9.4</a> | |
| 19163 |
| NFS4ERR_RECLAIM_CONFLICT | 10035 | <a href="#section-15.1.9.5">Section 15.1.9.5</a> | |
| 19164 |
| NFS4ERR_REJECT_DELEG | 10085 | <a href="#section-15.1.14.4">Section 15.1.14.4</a> | |
| 19165 |
| NFS4ERR_REP_TOO_BIG | 10066 | <a href="#section-15.1.3.6">Section 15.1.3.6</a> | |
| 19166 |
| NFS4ERR_REP_TOO_BIG_TO_CACHE | 10067 | <a href="#section-15.1.3.7">Section 15.1.3.7</a> | |
| 19167 |
| NFS4ERR_REQ_TOO_BIG | 10065 | <a href="#section-15.1.3.8">Section 15.1.3.8</a> | |
| 19168 |
| NFS4ERR_RESTOREFH | 10030 | <a href="#section-15.1.16.4">Section 15.1.16.4</a> | |
| 19169 |
| NFS4ERR_RETRY_UNCACHED_REP | 10068 | <a href="#section-15.1.3.9">Section 15.1.3.9</a> | |
| 19170 |
| NFS4ERR_RETURNCONFLICT | 10086 | <a href="#section-15.1.10.8">Section 15.1.10.8</a> | |
| 19171 |
| NFS4ERR_ROFS | 30 | <a href="#section-15.1.4.11">Section 15.1.4.11</a> | |
| 19172 |
| NFS4ERR_SAME | 10009 | <a href="#section-15.1.15.4">Section 15.1.15.4</a> | |
| 19173 |
| NFS4ERR_SHARE_DENIED | 10015 | <a href="#section-15.1.8.9">Section 15.1.8.9</a> | |
| 19174 |
| NFS4ERR_SEQUENCE_POS | 10064 | <a href="#section-15.1.3.10">Section 15.1.3.10</a> | |
| 19175 |
| NFS4ERR_SEQ_FALSE_RETRY | 10076 | <a href="#section-15.1.11.7">Section 15.1.11.7</a> | |
| 19176 |
| NFS4ERR_SEQ_MISORDERED | 10063 | <a href="#section-15.1.11.8">Section 15.1.11.8</a> | |
| 19177 |
| NFS4ERR_SERVERFAULT | 10006 | <a href="#section-15.1.1.6">Section 15.1.1.6</a> | |
| 19178 |
| NFS4ERR_STALE | 70 | <a href="#section-15.1.2.7">Section 15.1.2.7</a> | |
| 19179 |
| NFS4ERR_STALE_CLIENTID | 10022 | <a href="#section-15.1.13.5">Section 15.1.13.5</a> | |
| 19180 |
| NFS4ERR_STALE_STATEID | 10023 | <a href="#section-15.1.16.5">Section 15.1.16.5</a> | |
| 19181 |
| NFS4ERR_SYMLINK | 10029 | <a href="#section-15.1.2.8">Section 15.1.2.8</a> | |
| 19182 |
| NFS4ERR_TOOSMALL | 10005 | <a href="#section-15.1.1.7">Section 15.1.1.7</a> | |
| 19183 |
| NFS4ERR_TOO_MANY_OPS | 10070 | <a href="#section-15.1.3.11">Section 15.1.3.11</a> | |
| 19184 |
| NFS4ERR_UNKNOWN_LAYOUTTYPE | 10062 | <a href="#section-15.1.10.9">Section 15.1.10.9</a> | |
| 19185 |
| NFS4ERR_UNSAFE_COMPOUND | 10069 | <a href="#section-15.1.3.12">Section 15.1.3.12</a> | |
| 19186 |
| NFS4ERR_WRONGSEC | 10016 | <a href="#section-15.1.6.3">Section 15.1.6.3</a> | |
| 19187 |
| NFS4ERR_WRONG_CRED | 10082 | <a href="#section-15.1.6.4">Section 15.1.6.4</a> | |
| 19188 |
| NFS4ERR_WRONG_TYPE | 10083 | <a href="#section-15.1.2.9">Section 15.1.2.9</a> | |
| 19189 |
| NFS4ERR_XDEV | 18 | <a href="#section-15.1.4.12">Section 15.1.4.12</a> | |
| 19190 |
+-----------------------------------+--------+-------------------+ |
| 19191 |
|
| 19192 |
Table 5 |
| 19193 |
|
| 19194 |
<span class="h4"><a class="selflink" id="section-15.1.1" href="#section-15.1.1">15.1.1</a>. General Errors</span> |
| 19195 |
|
| 19196 |
This section deals with errors that are applicable to a broad set of |
| 19197 |
different purposes. |
| 19198 |
|
| 19199 |
|
| 19200 |
|
| 19201 |
|
| 19202 |
|
| 19203 |
|
| 19204 |
<span class="grey">Shepler, et al. Standards Track [Page 343]</span></pre> |
| 19205 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-344" ></span> |
| 19206 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19207 |
|
| 19208 |
|
| 19209 |
<span class="h5"><a class="selflink" id="section-15.1.1.1" href="#section-15.1.1.1">15.1.1.1</a>. NFS4ERR_BADXDR (Error Code 10036)</span> |
| 19210 |
|
| 19211 |
The arguments for this operation do not match those specified in the |
| 19212 |
XDR definition. This includes situations in which the request ends |
| 19213 |
before all the arguments have been seen. Note that this error |
| 19214 |
applies when fixed enumerations (these include booleans) have a value |
| 19215 |
within the input stream that is not valid for the enum. A replier |
| 19216 |
may pre-parse all operations for a Compound procedure before doing |
| 19217 |
any operation execution and return RPC-level XDR errors in that case. |
| 19218 |
|
| 19219 |
<span class="h5"><a class="selflink" id="section-15.1.1.2" href="#section-15.1.1.2">15.1.1.2</a>. NFS4ERR_BAD_COOKIE (Error Code 10003)</span> |
| 19220 |
|
| 19221 |
Used for operations that provide a set of information indexed by some |
| 19222 |
quantity provided by the client or cookie sent by the server for an |
| 19223 |
earlier invocation. Where the value cannot be used for its intended |
| 19224 |
purpose, this error results. |
| 19225 |
|
| 19226 |
<span class="h5"><a class="selflink" id="section-15.1.1.3" href="#section-15.1.1.3">15.1.1.3</a>. NFS4ERR_DELAY (Error Code 10008)</span> |
| 19227 |
|
| 19228 |
For any of a number of reasons, the replier could not process this |
| 19229 |
operation in what was deemed a reasonable time. The client should |
| 19230 |
wait and then try the request with a new slot and sequence value. |
| 19231 |
|
| 19232 |
Some examples of scenarios that might lead to this situation: |
| 19233 |
|
| 19234 |
o A server that supports hierarchical storage receives a request to |
| 19235 |
process a file that had been migrated. |
| 19236 |
|
| 19237 |
o An operation requires a delegation recall to proceed, and waiting |
| 19238 |
for this delegation recall makes processing this request in a |
| 19239 |
timely fashion impossible. |
| 19240 |
|
| 19241 |
In such cases, the error NFS4ERR_DELAY allows these preparatory |
| 19242 |
operations to proceed without holding up client resources such as a |
| 19243 |
session slot. After delaying for period of time, the client can then |
| 19244 |
re-send the operation in question (but not with the same slot ID and |
| 19245 |
sequence ID; one or both MUST be different on the re-send). |
| 19246 |
|
| 19247 |
Note that without the ability to return NFS4ERR_DELAY and the |
| 19248 |
client's willingness to re-send when receiving it, deadlock might |
| 19249 |
result. For example, if a recall is done, and if the delegation |
| 19250 |
return or operations preparatory to delegation return are held up by |
| 19251 |
other operations that need the delegation to be returned, session |
| 19252 |
slots might not be available. The result could be deadlock. |
| 19253 |
|
| 19254 |
|
| 19255 |
|
| 19256 |
|
| 19257 |
|
| 19258 |
|
| 19259 |
|
| 19260 |
<span class="grey">Shepler, et al. Standards Track [Page 344]</span></pre> |
| 19261 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-345" ></span> |
| 19262 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19263 |
|
| 19264 |
|
| 19265 |
<span class="h5"><a class="selflink" id="section-15.1.1.4" href="#section-15.1.1.4">15.1.1.4</a>. NFS4ERR_INVAL (Error Code 22)</span> |
| 19266 |
|
| 19267 |
The arguments for this operation are not valid for some reason, even |
| 19268 |
though they do match those specified in the XDR definition for the |
| 19269 |
request. |
| 19270 |
|
| 19271 |
<span class="h5"><a class="selflink" id="section-15.1.1.5" href="#section-15.1.1.5">15.1.1.5</a>. NFS4ERR_NOTSUPP (Error Code 10004)</span> |
| 19272 |
|
| 19273 |
Operation not supported, either because the operation is an OPTIONAL |
| 19274 |
one and is not supported by this server or because the operation MUST |
| 19275 |
NOT be implemented in the current minor version. |
| 19276 |
|
| 19277 |
<span class="h5"><a class="selflink" id="section-15.1.1.6" href="#section-15.1.1.6">15.1.1.6</a>. NFS4ERR_SERVERFAULT (Error Code 10006)</span> |
| 19278 |
|
| 19279 |
An error occurred on the server that does not map to any of the |
| 19280 |
specific legal NFSv4.1 protocol error values. The client should |
| 19281 |
translate this into an appropriate error. UNIX clients may choose to |
| 19282 |
translate this to EIO. |
| 19283 |
|
| 19284 |
<span class="h5"><a class="selflink" id="section-15.1.1.7" href="#section-15.1.1.7">15.1.1.7</a>. NFS4ERR_TOOSMALL (Error Code 10005)</span> |
| 19285 |
|
| 19286 |
Used where an operation returns a variable amount of data, with a |
| 19287 |
limit specified by the client. Where the data returned cannot be fit |
| 19288 |
within the limit specified by the client, this error results. |
| 19289 |
|
| 19290 |
<span class="h4"><a class="selflink" id="section-15.1.2" href="#section-15.1.2">15.1.2</a>. Filehandle Errors</span> |
| 19291 |
|
| 19292 |
These errors deal with the situation in which the current or saved |
| 19293 |
filehandle, or the filehandle passed to PUTFH intended to become the |
| 19294 |
current filehandle, is invalid in some way. This includes situations |
| 19295 |
in which the filehandle is a valid filehandle in general but is not |
| 19296 |
of the appropriate object type for the current operation. |
| 19297 |
|
| 19298 |
Where the error description indicates a problem with the current or |
| 19299 |
saved filehandle, it is to be understood that filehandles are only |
| 19300 |
checked for the condition if they are implicit arguments of the |
| 19301 |
operation in question. |
| 19302 |
|
| 19303 |
<span class="h5"><a class="selflink" id="section-15.1.2.1" href="#section-15.1.2.1">15.1.2.1</a>. NFS4ERR_BADHANDLE (Error Code 10001)</span> |
| 19304 |
|
| 19305 |
Illegal NFS filehandle for the current server. The current file |
| 19306 |
handle failed internal consistency checks. Once accepted as valid |
| 19307 |
(by PUTFH), no subsequent status change can cause the filehandle to |
| 19308 |
generate this error. |
| 19309 |
|
| 19310 |
|
| 19311 |
|
| 19312 |
|
| 19313 |
|
| 19314 |
|
| 19315 |
|
| 19316 |
<span class="grey">Shepler, et al. Standards Track [Page 345]</span></pre> |
| 19317 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-346" ></span> |
| 19318 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19319 |
|
| 19320 |
|
| 19321 |
<span class="h5"><a class="selflink" id="section-15.1.2.2" href="#section-15.1.2.2">15.1.2.2</a>. NFS4ERR_FHEXPIRED (Error Code 10014)</span> |
| 19322 |
|
| 19323 |
A current or saved filehandle that is an argument to the current |
| 19324 |
operation is volatile and has expired at the server. |
| 19325 |
|
| 19326 |
<span class="h5"><a class="selflink" id="section-15.1.2.3" href="#section-15.1.2.3">15.1.2.3</a>. NFS4ERR_ISDIR (Error Code 21)</span> |
| 19327 |
|
| 19328 |
The current or saved filehandle designates a directory when the |
| 19329 |
current operation does not allow a directory to be accepted as the |
| 19330 |
target of this operation. |
| 19331 |
|
| 19332 |
<span class="h5"><a class="selflink" id="section-15.1.2.4" href="#section-15.1.2.4">15.1.2.4</a>. NFS4ERR_MOVED (Error Code 10019)</span> |
| 19333 |
|
| 19334 |
The file system that contains the current filehandle object is not |
| 19335 |
present at the server. It may have been relocated or migrated to |
| 19336 |
another server, or it may have never been present. The client may |
| 19337 |
obtain the new file system location by obtaining the "fs_locations" |
| 19338 |
or "fs_locations_info" attribute for the current filehandle. For |
| 19339 |
further discussion, refer to <a href="#section-11.2">Section 11.2</a>. |
| 19340 |
|
| 19341 |
<span class="h5"><a class="selflink" id="section-15.1.2.5" href="#section-15.1.2.5">15.1.2.5</a>. NFS4ERR_NOFILEHANDLE (Error Code 10020)</span> |
| 19342 |
|
| 19343 |
The logical current or saved filehandle value is required by the |
| 19344 |
current operation and is not set. This may be a result of a |
| 19345 |
malformed COMPOUND operation (i.e., no PUTFH or PUTROOTFH before an |
| 19346 |
operation that requires the current filehandle be set). |
| 19347 |
|
| 19348 |
<span class="h5"><a class="selflink" id="section-15.1.2.6" href="#section-15.1.2.6">15.1.2.6</a>. NFS4ERR_NOTDIR (Error Code 20)</span> |
| 19349 |
|
| 19350 |
The current (or saved) filehandle designates an object that is not a |
| 19351 |
directory for an operation in which a directory is required. |
| 19352 |
|
| 19353 |
<span class="h5"><a class="selflink" id="section-15.1.2.7" href="#section-15.1.2.7">15.1.2.7</a>. NFS4ERR_STALE (Error Code 70)</span> |
| 19354 |
|
| 19355 |
The current or saved filehandle value designating an argument to the |
| 19356 |
current operation is invalid. The file referred to by that |
| 19357 |
filehandle no longer exists or access to it has been revoked. |
| 19358 |
|
| 19359 |
<span class="h5"><a class="selflink" id="section-15.1.2.8" href="#section-15.1.2.8">15.1.2.8</a>. NFS4ERR_SYMLINK (Error Code 10029)</span> |
| 19360 |
|
| 19361 |
The current filehandle designates a symbolic link when the current |
| 19362 |
operation does not allow a symbolic link as the target. |
| 19363 |
|
| 19364 |
|
| 19365 |
|
| 19366 |
|
| 19367 |
|
| 19368 |
|
| 19369 |
|
| 19370 |
|
| 19371 |
|
| 19372 |
<span class="grey">Shepler, et al. Standards Track [Page 346]</span></pre> |
| 19373 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-347" ></span> |
| 19374 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19375 |
|
| 19376 |
|
| 19377 |
<span class="h5"><a class="selflink" id="section-15.1.2.9" href="#section-15.1.2.9">15.1.2.9</a>. NFS4ERR_WRONG_TYPE (Error Code 10083)</span> |
| 19378 |
|
| 19379 |
The current (or saved) filehandle designates an object that is of an |
| 19380 |
invalid type for the current operation, and there is no more specific |
| 19381 |
error (such as NFS4ERR_ISDIR or NFS4ERR_SYMLINK) that applies. Note |
| 19382 |
that in NFSv4.0, such situations generally resulted in the less- |
| 19383 |
specific error NFS4ERR_INVAL. |
| 19384 |
|
| 19385 |
<span class="h4"><a class="selflink" id="section-15.1.3" href="#section-15.1.3">15.1.3</a>. Compound Structure Errors</span> |
| 19386 |
|
| 19387 |
This section deals with errors that relate to the overall structure |
| 19388 |
of a Compound request (by which we mean to include both COMPOUND and |
| 19389 |
CB_COMPOUND), rather than to particular operations. |
| 19390 |
|
| 19391 |
There are a number of basic constraints on the operations that may |
| 19392 |
appear in a Compound request. Sessions add to these basic |
| 19393 |
constraints by requiring a Sequence operation (either SEQUENCE or |
| 19394 |
CB_SEQUENCE) at the start of the Compound. |
| 19395 |
|
| 19396 |
<span class="h5"><a class="selflink" id="section-15.1.3.1" href="#section-15.1.3.1">15.1.3.1</a>. NFS_OK (Error code 0)</span> |
| 19397 |
|
| 19398 |
Indicates the operation completed successfully, in that all of the |
| 19399 |
constituent operations completed without error. |
| 19400 |
|
| 19401 |
<span class="h5"><a class="selflink" id="section-15.1.3.2" href="#section-15.1.3.2">15.1.3.2</a>. NFS4ERR_MINOR_VERS_MISMATCH (Error code 10021)</span> |
| 19402 |
|
| 19403 |
The minor version specified is not one that the current listener |
| 19404 |
supports. This value is returned in the overall status for the |
| 19405 |
Compound but is not associated with a specific operation since the |
| 19406 |
results will specify a result count of zero. |
| 19407 |
|
| 19408 |
<span class="h5"><a class="selflink" id="section-15.1.3.3" href="#section-15.1.3.3">15.1.3.3</a>. NFS4ERR_NOT_ONLY_OP (Error Code 10081)</span> |
| 19409 |
|
| 19410 |
Certain operations, which are allowed to be executed outside of a |
| 19411 |
session, MUST be the only operation within a Compound whenever the |
| 19412 |
Compound does not start with a Sequence operation. This error |
| 19413 |
results when that constraint is not met. |
| 19414 |
|
| 19415 |
<span class="h5"><a class="selflink" id="section-15.1.3.4" href="#section-15.1.3.4">15.1.3.4</a>. NFS4ERR_OP_ILLEGAL (Error Code 10044)</span> |
| 19416 |
|
| 19417 |
The operation code is not a valid one for the current Compound |
| 19418 |
procedure. The opcode in the result stream matched with this error |
| 19419 |
is the ILLEGAL value, although the value that appears in the request |
| 19420 |
stream may be different. Where an illegal value appears and the |
| 19421 |
replier pre-parses all operations for a Compound procedure before |
| 19422 |
doing any operation execution, an RPC-level XDR error may be |
| 19423 |
returned. |
| 19424 |
|
| 19425 |
|
| 19426 |
|
| 19427 |
|
| 19428 |
<span class="grey">Shepler, et al. Standards Track [Page 347]</span></pre> |
| 19429 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-348" ></span> |
| 19430 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19431 |
|
| 19432 |
|
| 19433 |
<span class="h5"><a class="selflink" id="section-15.1.3.5" href="#section-15.1.3.5">15.1.3.5</a>. NFS4ERR_OP_NOT_IN_SESSION (Error Code 10071)</span> |
| 19434 |
|
| 19435 |
Most forward operations and all callback operations are only valid |
| 19436 |
within the context of a session, so that the Compound request in |
| 19437 |
question MUST begin with a Sequence operation. If an attempt is made |
| 19438 |
to execute these operations outside the context of session, this |
| 19439 |
error results. |
| 19440 |
|
| 19441 |
<span class="h5"><a class="selflink" id="section-15.1.3.6" href="#section-15.1.3.6">15.1.3.6</a>. NFS4ERR_REP_TOO_BIG (Error Code 10066)</span> |
| 19442 |
|
| 19443 |
The reply to a Compound would exceed the channel's negotiated maximum |
| 19444 |
response size. |
| 19445 |
|
| 19446 |
<span class="h5"><a class="selflink" id="section-15.1.3.7" href="#section-15.1.3.7">15.1.3.7</a>. NFS4ERR_REP_TOO_BIG_TO_CACHE (Error Code 10067)</span> |
| 19447 |
|
| 19448 |
The reply to a Compound would exceed the channel's negotiated maximum |
| 19449 |
size for replies cached in the reply cache when the Sequence for the |
| 19450 |
current request specifies that this request is to be cached. |
| 19451 |
|
| 19452 |
<span class="h5"><a class="selflink" id="section-15.1.3.8" href="#section-15.1.3.8">15.1.3.8</a>. NFS4ERR_REQ_TOO_BIG (Error Code 10065)</span> |
| 19453 |
|
| 19454 |
The Compound request exceeds the channel's negotiated maximum size |
| 19455 |
for requests. |
| 19456 |
|
| 19457 |
<span class="h5"><a class="selflink" id="section-15.1.3.9" href="#section-15.1.3.9">15.1.3.9</a>. NFS4ERR_RETRY_UNCACHED_REP (Error Code 10068)</span> |
| 19458 |
|
| 19459 |
The requester has attempted a retry of a Compound that it previously |
| 19460 |
requested not be placed in the reply cache. |
| 19461 |
|
| 19462 |
<span class="h5"><a class="selflink" id="section-15.1.3.10" href="#section-15.1.3.10">15.1.3.10</a>. NFS4ERR_SEQUENCE_POS (Error Code 10064)</span> |
| 19463 |
|
| 19464 |
A Sequence operation appeared in a position other than the first |
| 19465 |
operation of a Compound request. |
| 19466 |
|
| 19467 |
<span class="h5"><a class="selflink" id="section-15.1.3.11" href="#section-15.1.3.11">15.1.3.11</a>. NFS4ERR_TOO_MANY_OPS (Error Code 10070)</span> |
| 19468 |
|
| 19469 |
The Compound request has too many operations, exceeding the count |
| 19470 |
negotiated when the session was created. |
| 19471 |
|
| 19472 |
<span class="h5"><a class="selflink" id="section-15.1.3.12" href="#section-15.1.3.12">15.1.3.12</a>. NFS4ERR_UNSAFE_COMPOUND (Error Code 10068)</span> |
| 19473 |
|
| 19474 |
The client has sent a COMPOUND request with an unsafe mix of |
| 19475 |
operations -- specifically, with a non-idempotent operation that |
| 19476 |
changes the current filehandle and that is not followed by a GETFH. |
| 19477 |
|
| 19478 |
|
| 19479 |
|
| 19480 |
|
| 19481 |
|
| 19482 |
|
| 19483 |
|
| 19484 |
<span class="grey">Shepler, et al. Standards Track [Page 348]</span></pre> |
| 19485 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-349" ></span> |
| 19486 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19487 |
|
| 19488 |
|
| 19489 |
<span class="h4"><a class="selflink" id="section-15.1.4" href="#section-15.1.4">15.1.4</a>. File System Errors</span> |
| 19490 |
|
| 19491 |
These errors describe situations that occurred in the underlying file |
| 19492 |
system implementation rather than in the protocol or any NFSv4.x |
| 19493 |
feature. |
| 19494 |
|
| 19495 |
<span class="h5"><a class="selflink" id="section-15.1.4.1" href="#section-15.1.4.1">15.1.4.1</a>. NFS4ERR_BADTYPE (Error Code 10007)</span> |
| 19496 |
|
| 19497 |
An attempt was made to create an object with an inappropriate type |
| 19498 |
specified to CREATE. This may be because the type is undefined, |
| 19499 |
because the type is not supported by the server, or because the type |
| 19500 |
is not intended to be created by CREATE (such as a regular file or |
| 19501 |
named attribute, for which OPEN is used to do the file creation). |
| 19502 |
|
| 19503 |
<span class="h5"><a class="selflink" id="section-15.1.4.2" href="#section-15.1.4.2">15.1.4.2</a>. NFS4ERR_DQUOT (Error Code 19)</span> |
| 19504 |
|
| 19505 |
Resource (quota) hard limit exceeded. The user's resource limit on |
| 19506 |
the server has been exceeded. |
| 19507 |
|
| 19508 |
<span class="h5"><a class="selflink" id="section-15.1.4.3" href="#section-15.1.4.3">15.1.4.3</a>. NFS4ERR_EXIST (Error Code 17)</span> |
| 19509 |
|
| 19510 |
A file of the specified target name (when creating, renaming, or |
| 19511 |
linking) already exists. |
| 19512 |
|
| 19513 |
<span class="h5"><a class="selflink" id="section-15.1.4.4" href="#section-15.1.4.4">15.1.4.4</a>. NFS4ERR_FBIG (Error Code 27)</span> |
| 19514 |
|
| 19515 |
The file is too large. The operation would have caused the file to |
| 19516 |
grow beyond the server's limit. |
| 19517 |
|
| 19518 |
<span class="h5"><a class="selflink" id="section-15.1.4.5" href="#section-15.1.4.5">15.1.4.5</a>. NFS4ERR_FILE_OPEN (Error Code 10046)</span> |
| 19519 |
|
| 19520 |
The operation is not allowed because a file involved in the operation |
| 19521 |
is currently open. Servers may, but are not required to, disallow |
| 19522 |
linking-to, removing, or renaming open files. |
| 19523 |
|
| 19524 |
<span class="h5"><a class="selflink" id="section-15.1.4.6" href="#section-15.1.4.6">15.1.4.6</a>. NFS4ERR_IO (Error Code 5)</span> |
| 19525 |
|
| 19526 |
Indicates that an I/O error occurred for which the file system was |
| 19527 |
unable to provide recovery. |
| 19528 |
|
| 19529 |
<span class="h5"><a class="selflink" id="section-15.1.4.7" href="#section-15.1.4.7">15.1.4.7</a>. NFS4ERR_MLINK (Error Code 31)</span> |
| 19530 |
|
| 19531 |
The request would have caused the server's limit for the number of |
| 19532 |
hard links a file may have to be exceeded. |
| 19533 |
|
| 19534 |
|
| 19535 |
|
| 19536 |
|
| 19537 |
|
| 19538 |
|
| 19539 |
|
| 19540 |
<span class="grey">Shepler, et al. Standards Track [Page 349]</span></pre> |
| 19541 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-350" ></span> |
| 19542 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19543 |
|
| 19544 |
|
| 19545 |
<span class="h5"><a class="selflink" id="section-15.1.4.8" href="#section-15.1.4.8">15.1.4.8</a>. NFS4ERR_NOENT (Error Code 2)</span> |
| 19546 |
|
| 19547 |
Indicates no such file or directory. The file or directory name |
| 19548 |
specified does not exist. |
| 19549 |
|
| 19550 |
<span class="h5"><a class="selflink" id="section-15.1.4.9" href="#section-15.1.4.9">15.1.4.9</a>. NFS4ERR_NOSPC (Error Code 28)</span> |
| 19551 |
|
| 19552 |
Indicates there is no space left on the device. The operation would |
| 19553 |
have caused the server's file system to exceed its limit. |
| 19554 |
|
| 19555 |
<span class="h5"><a class="selflink" id="section-15.1.4.10" href="#section-15.1.4.10">15.1.4.10</a>. NFS4ERR_NOTEMPTY (Error Code 66)</span> |
| 19556 |
|
| 19557 |
An attempt was made to remove a directory that was not empty. |
| 19558 |
|
| 19559 |
<span class="h5"><a class="selflink" id="section-15.1.4.11" href="#section-15.1.4.11">15.1.4.11</a>. NFS4ERR_ROFS (Error Code 30)</span> |
| 19560 |
|
| 19561 |
Indicates a read-only file system. A modifying operation was |
| 19562 |
attempted on a read-only file system. |
| 19563 |
|
| 19564 |
<span class="h5"><a class="selflink" id="section-15.1.4.12" href="#section-15.1.4.12">15.1.4.12</a>. NFS4ERR_XDEV (Error Code 18)</span> |
| 19565 |
|
| 19566 |
Indicates an attempt to do an operation, such as linking, that |
| 19567 |
inappropriately crosses a boundary. This may be due to such |
| 19568 |
boundaries as: |
| 19569 |
|
| 19570 |
o that between file systems (where the fsids are different). |
| 19571 |
|
| 19572 |
o that between different named attribute directories or between a |
| 19573 |
named attribute directory and an ordinary directory. |
| 19574 |
|
| 19575 |
o that between byte-ranges of a file system that the file system |
| 19576 |
implementation treats as separate (for example, for space |
| 19577 |
accounting purposes), and where cross-connection between the byte- |
| 19578 |
ranges are not allowed. |
| 19579 |
|
| 19580 |
<span class="h4"><a class="selflink" id="section-15.1.5" href="#section-15.1.5">15.1.5</a>. State Management Errors</span> |
| 19581 |
|
| 19582 |
These errors indicate problems with the stateid (or one of the |
| 19583 |
stateids) passed to a given operation. This includes situations in |
| 19584 |
which the stateid is invalid as well as situations in which the |
| 19585 |
stateid is valid but designates locking state that has been revoked. |
| 19586 |
Depending on the operation, the stateid when valid may designate |
| 19587 |
opens, byte-range locks, file or directory delegations, layouts, or |
| 19588 |
device maps. |
| 19589 |
|
| 19590 |
|
| 19591 |
|
| 19592 |
|
| 19593 |
|
| 19594 |
|
| 19595 |
|
| 19596 |
<span class="grey">Shepler, et al. Standards Track [Page 350]</span></pre> |
| 19597 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-351" ></span> |
| 19598 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19599 |
|
| 19600 |
|
| 19601 |
<span class="h5"><a class="selflink" id="section-15.1.5.1" href="#section-15.1.5.1">15.1.5.1</a>. NFS4ERR_ADMIN_REVOKED (Error Code 10047)</span> |
| 19602 |
|
| 19603 |
A stateid designates locking state of any type that has been revoked |
| 19604 |
due to administrative interaction, possibly while the lease is valid. |
| 19605 |
|
| 19606 |
<span class="h5"><a class="selflink" id="section-15.1.5.2" href="#section-15.1.5.2">15.1.5.2</a>. NFS4ERR_BAD_STATEID (Error Code 10026)</span> |
| 19607 |
|
| 19608 |
A stateid does not properly designate any valid state. See Sections |
| 19609 |
8.2.4 and 8.2.3 for a discussion of how stateids are validated. |
| 19610 |
|
| 19611 |
<span class="h5"><a class="selflink" id="section-15.1.5.3" href="#section-15.1.5.3">15.1.5.3</a>. NFS4ERR_DELEG_REVOKED (Error Code 10087)</span> |
| 19612 |
|
| 19613 |
A stateid designates recallable locking state of any type (delegation |
| 19614 |
or layout) that has been revoked due to the failure of the client to |
| 19615 |
return the lock when it was recalled. |
| 19616 |
|
| 19617 |
<span class="h5"><a class="selflink" id="section-15.1.5.4" href="#section-15.1.5.4">15.1.5.4</a>. NFS4ERR_EXPIRED (Error Code 10011)</span> |
| 19618 |
|
| 19619 |
A stateid designates locking state of any type that has been revoked |
| 19620 |
due to expiration of the client's lease, either immediately upon |
| 19621 |
lease expiration, or following a later request for a conflicting |
| 19622 |
lock. |
| 19623 |
|
| 19624 |
<span class="h5"><a class="selflink" id="section-15.1.5.5" href="#section-15.1.5.5">15.1.5.5</a>. NFS4ERR_OLD_STATEID (Error Code 10024)</span> |
| 19625 |
|
| 19626 |
A stateid with a non-zero seqid value does match the current seqid |
| 19627 |
for the state designated by the user. |
| 19628 |
|
| 19629 |
<span class="h4"><a class="selflink" id="section-15.1.6" href="#section-15.1.6">15.1.6</a>. Security Errors</span> |
| 19630 |
|
| 19631 |
These are the various permission-related errors in NFSv4.1. |
| 19632 |
|
| 19633 |
<span class="h5"><a class="selflink" id="section-15.1.6.1" href="#section-15.1.6.1">15.1.6.1</a>. NFS4ERR_ACCESS (Error Code 13)</span> |
| 19634 |
|
| 19635 |
Indicates permission denied. The caller does not have the correct |
| 19636 |
permission to perform the requested operation. Contrast this with |
| 19637 |
NFS4ERR_PERM (<a href="#section-15.1.6.2">Section 15.1.6.2</a>), which restricts itself to owner or |
| 19638 |
privileged-user permission failures, and NFS4ERR_WRONG_CRED |
| 19639 |
(<a href="#section-15.1.6.4">Section 15.1.6.4</a>), which deals with appropriate permission to delete |
| 19640 |
or modify transient objects based on the credentials of the user that |
| 19641 |
created them. |
| 19642 |
|
| 19643 |
<span class="h5"><a class="selflink" id="section-15.1.6.2" href="#section-15.1.6.2">15.1.6.2</a>. NFS4ERR_PERM (Error Code 1)</span> |
| 19644 |
|
| 19645 |
Indicates requester is not the owner. The operation was not allowed |
| 19646 |
because the caller is neither a privileged user (root) nor the owner |
| 19647 |
of the target of the operation. |
| 19648 |
|
| 19649 |
|
| 19650 |
|
| 19651 |
|
| 19652 |
<span class="grey">Shepler, et al. Standards Track [Page 351]</span></pre> |
| 19653 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-352" ></span> |
| 19654 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19655 |
|
| 19656 |
|
| 19657 |
<span class="h5"><a class="selflink" id="section-15.1.6.3" href="#section-15.1.6.3">15.1.6.3</a>. NFS4ERR_WRONGSEC (Error Code 10016)</span> |
| 19658 |
|
| 19659 |
Indicates that the security mechanism being used by the client for |
| 19660 |
the operation does not match the server's security policy. The |
| 19661 |
client should change the security mechanism being used and re-send |
| 19662 |
the operation (but not with the same slot ID and sequence ID; one or |
| 19663 |
both MUST be different on the re-send). SECINFO and SECINFO_NO_NAME |
| 19664 |
can be used to determine the appropriate mechanism. |
| 19665 |
|
| 19666 |
<span class="h5"><a class="selflink" id="section-15.1.6.4" href="#section-15.1.6.4">15.1.6.4</a>. NFS4ERR_WRONG_CRED (Error Code 10082)</span> |
| 19667 |
|
| 19668 |
An operation that manipulates state was attempted by a principal that |
| 19669 |
was not allowed to modify that piece of state. |
| 19670 |
|
| 19671 |
<span class="h4"><a class="selflink" id="section-15.1.7" href="#section-15.1.7">15.1.7</a>. Name Errors</span> |
| 19672 |
|
| 19673 |
Names in NFSv4 are UTF-8 strings. When the strings are not valid |
| 19674 |
UTF-8 or are of length zero, the error NFS4ERR_INVAL results. |
| 19675 |
Besides this, there are a number of other errors to indicate specific |
| 19676 |
problems with names. |
| 19677 |
|
| 19678 |
<span class="h5"><a class="selflink" id="section-15.1.7.1" href="#section-15.1.7.1">15.1.7.1</a>. NFS4ERR_BADCHAR (Error Code 10040)</span> |
| 19679 |
|
| 19680 |
A UTF-8 string contains a character that is not supported by the |
| 19681 |
server in the context in which it being used. |
| 19682 |
|
| 19683 |
<span class="h5"><a class="selflink" id="section-15.1.7.2" href="#section-15.1.7.2">15.1.7.2</a>. NFS4ERR_BADNAME (Error Code 10041)</span> |
| 19684 |
|
| 19685 |
A name string in a request consisted of valid UTF-8 characters |
| 19686 |
supported by the server, but the name is not supported by the server |
| 19687 |
as a valid name for the current operation. An example might be |
| 19688 |
creating a file or directory named ".." on a server whose file system |
| 19689 |
uses that name for links to parent directories. |
| 19690 |
|
| 19691 |
<span class="h5"><a class="selflink" id="section-15.1.7.3" href="#section-15.1.7.3">15.1.7.3</a>. NFS4ERR_NAMETOOLONG (Error Code 63)</span> |
| 19692 |
|
| 19693 |
Returned when the filename in an operation exceeds the server's |
| 19694 |
implementation limit. |
| 19695 |
|
| 19696 |
<span class="h4"><a class="selflink" id="section-15.1.8" href="#section-15.1.8">15.1.8</a>. Locking Errors</span> |
| 19697 |
|
| 19698 |
This section deals with errors related to locking, both as to share |
| 19699 |
reservations and byte-range locking. It does not deal with errors |
| 19700 |
specific to the process of reclaiming locks. Those are dealt with in |
| 19701 |
<a href="#section-15.1.9">Section 15.1.9</a>. |
| 19702 |
|
| 19703 |
|
| 19704 |
|
| 19705 |
|
| 19706 |
|
| 19707 |
|
| 19708 |
<span class="grey">Shepler, et al. Standards Track [Page 352]</span></pre> |
| 19709 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-353" ></span> |
| 19710 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19711 |
|
| 19712 |
|
| 19713 |
<span class="h5"><a class="selflink" id="section-15.1.8.1" href="#section-15.1.8.1">15.1.8.1</a>. NFS4ERR_BAD_RANGE (Error Code 10042)</span> |
| 19714 |
|
| 19715 |
The byte-range of a LOCK, LOCKT, or LOCKU operation is not allowed by |
| 19716 |
the server. For example, this error results when a server that only |
| 19717 |
supports 32-bit ranges receives a range that cannot be handled by |
| 19718 |
that server. (See <a href="#section-18.10.3">Section 18.10.3</a>.) |
| 19719 |
|
| 19720 |
<span class="h5"><a class="selflink" id="section-15.1.8.2" href="#section-15.1.8.2">15.1.8.2</a>. NFS4ERR_DEADLOCK (Error Code 10045)</span> |
| 19721 |
|
| 19722 |
The server has been able to determine a byte-range locking deadlock |
| 19723 |
condition for a READW_LT or WRITEW_LT LOCK operation. |
| 19724 |
|
| 19725 |
<span class="h5"><a class="selflink" id="section-15.1.8.3" href="#section-15.1.8.3">15.1.8.3</a>. NFS4ERR_DENIED (Error Code 10010)</span> |
| 19726 |
|
| 19727 |
An attempt to lock a file is denied. Since this may be a temporary |
| 19728 |
condition, the client is encouraged to re-send the lock request (but |
| 19729 |
not with the same slot ID and sequence ID; one or both MUST be |
| 19730 |
different on the re-send) until the lock is accepted. See |
| 19731 |
<a href="#section-9.6">Section 9.6</a> for a discussion of the re-send. |
| 19732 |
|
| 19733 |
<span class="h5"><a class="selflink" id="section-15.1.8.4" href="#section-15.1.8.4">15.1.8.4</a>. NFS4ERR_LOCKED (Error Code 10012)</span> |
| 19734 |
|
| 19735 |
A READ or WRITE operation was attempted on a file where there was a |
| 19736 |
conflict between the I/O and an existing lock: |
| 19737 |
|
| 19738 |
o There is a share reservation inconsistent with the I/O being done. |
| 19739 |
|
| 19740 |
o The range to be read or written intersects an existing mandatory |
| 19741 |
byte-range lock. |
| 19742 |
|
| 19743 |
<span class="h5"><a class="selflink" id="section-15.1.8.5" href="#section-15.1.8.5">15.1.8.5</a>. NFS4ERR_LOCKS_HELD (Error Code 10037)</span> |
| 19744 |
|
| 19745 |
An operation was prevented by the unexpected presence of locks. |
| 19746 |
|
| 19747 |
<span class="h5"><a class="selflink" id="section-15.1.8.6" href="#section-15.1.8.6">15.1.8.6</a>. NFS4ERR_LOCK_NOTSUPP (Error Code 10043)</span> |
| 19748 |
|
| 19749 |
A LOCK operation was attempted that would require the upgrade or |
| 19750 |
downgrade of a byte-range lock range already held by the owner, and |
| 19751 |
the server does not support atomic upgrade or downgrade of locks. |
| 19752 |
|
| 19753 |
<span class="h5"><a class="selflink" id="section-15.1.8.7" href="#section-15.1.8.7">15.1.8.7</a>. NFS4ERR_LOCK_RANGE (Error Code 10028)</span> |
| 19754 |
|
| 19755 |
A LOCK operation is operating on a range that overlaps in part a |
| 19756 |
currently held byte-range lock for the current lock-owner and does |
| 19757 |
not precisely match a single such byte-range lock where the server |
| 19758 |
does not support this type of request, and thus does not implement |
| 19759 |
|
| 19760 |
|
| 19761 |
|
| 19762 |
|
| 19763 |
|
| 19764 |
<span class="grey">Shepler, et al. Standards Track [Page 353]</span></pre> |
| 19765 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-354" ></span> |
| 19766 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19767 |
|
| 19768 |
|
| 19769 |
POSIX locking semantics [<a href="#ref-24" title="">24</a>]. See Sections <a href="#section-18.10.4">18.10.4</a>, <a href="#section-18.11.4">18.11.4</a>, and |
| 19770 |
18.12.4 for a discussion of how this applies to LOCK, LOCKT, and |
| 19771 |
LOCKU respectively. |
| 19772 |
|
| 19773 |
<span class="h5"><a class="selflink" id="section-15.1.8.8" href="#section-15.1.8.8">15.1.8.8</a>. NFS4ERR_OPENMODE (Error Code 10038)</span> |
| 19774 |
|
| 19775 |
The client attempted a READ, WRITE, LOCK, or other operation not |
| 19776 |
sanctioned by the stateid passed (e.g., writing to a file opened for |
| 19777 |
read-only access). |
| 19778 |
|
| 19779 |
<span class="h5"><a class="selflink" id="section-15.1.8.9" href="#section-15.1.8.9">15.1.8.9</a>. NFS4ERR_SHARE_DENIED (Error Code 10015)</span> |
| 19780 |
|
| 19781 |
An attempt to OPEN a file with a share reservation has failed because |
| 19782 |
of a share conflict. |
| 19783 |
|
| 19784 |
<span class="h4"><a class="selflink" id="section-15.1.9" href="#section-15.1.9">15.1.9</a>. Reclaim Errors</span> |
| 19785 |
|
| 19786 |
These errors relate to the process of reclaiming locks after a server |
| 19787 |
restart. |
| 19788 |
|
| 19789 |
<span class="h5"><a class="selflink" id="section-15.1.9.1" href="#section-15.1.9.1">15.1.9.1</a>. NFS4ERR_COMPLETE_ALREADY (Error Code 10054)</span> |
| 19790 |
|
| 19791 |
The client previously sent a successful RECLAIM_COMPLETE operation. |
| 19792 |
An additional RECLAIM_COMPLETE operation is not necessary and results |
| 19793 |
in this error. |
| 19794 |
|
| 19795 |
<span class="h5"><a class="selflink" id="section-15.1.9.2" href="#section-15.1.9.2">15.1.9.2</a>. NFS4ERR_GRACE (Error Code 10013)</span> |
| 19796 |
|
| 19797 |
The server was in its recovery or grace period. The locking request |
| 19798 |
was not a reclaim request and so could not be granted during that |
| 19799 |
period. |
| 19800 |
|
| 19801 |
<span class="h5"><a class="selflink" id="section-15.1.9.3" href="#section-15.1.9.3">15.1.9.3</a>. NFS4ERR_NO_GRACE (Error Code 10033)</span> |
| 19802 |
|
| 19803 |
A reclaim of client state was attempted in circumstances in which the |
| 19804 |
server cannot guarantee that conflicting state has not been provided |
| 19805 |
to another client. This can occur because the reclaim has been done |
| 19806 |
outside of the grace period of the server, after the client has done |
| 19807 |
a RECLAIM_COMPLETE operation, or because previous operations have |
| 19808 |
created a situation in which the server is not able to determine that |
| 19809 |
a reclaim-interfering edge condition does not exist. |
| 19810 |
|
| 19811 |
<span class="h5"><a class="selflink" id="section-15.1.9.4" href="#section-15.1.9.4">15.1.9.4</a>. NFS4ERR_RECLAIM_BAD (Error Code 10034)</span> |
| 19812 |
|
| 19813 |
The server has determined that a reclaim attempted by the client is |
| 19814 |
not valid, i.e. the lock specified as being reclaimed could not |
| 19815 |
possibly have existed before the server restart. A server is not |
| 19816 |
obliged to make this determination and will typically rely on the |
| 19817 |
|
| 19818 |
|
| 19819 |
|
| 19820 |
<span class="grey">Shepler, et al. Standards Track [Page 354]</span></pre> |
| 19821 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-355" ></span> |
| 19822 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19823 |
|
| 19824 |
|
| 19825 |
client to only reclaim locks that the client was granted prior to |
| 19826 |
restart. However, when a server does have reliable information to |
| 19827 |
enable it make this determination, this error indicates that the |
| 19828 |
reclaim has been rejected as invalid. This is as opposed to the |
| 19829 |
error NFS4ERR_RECLAIM_CONFLICT (see <a href="#section-15.1.9.5">Section 15.1.9.5</a>) where the |
| 19830 |
server can only determine that there has been an invalid reclaim, but |
| 19831 |
cannot determine which request is invalid. |
| 19832 |
|
| 19833 |
<span class="h5"><a class="selflink" id="section-15.1.9.5" href="#section-15.1.9.5">15.1.9.5</a>. NFS4ERR_RECLAIM_CONFLICT (Error Code 10035)</span> |
| 19834 |
|
| 19835 |
The reclaim attempted by the client has encountered a conflict and |
| 19836 |
cannot be satisfied. Potentially indicates a misbehaving client, |
| 19837 |
although not necessarily the one receiving the error. The |
| 19838 |
misbehavior might be on the part of the client that established the |
| 19839 |
lock with which this client conflicted. See also <a href="#section-15.1.9.4">Section 15.1.9.4</a> |
| 19840 |
for the related error, NFS4ERR_RECLAIM_BAD. |
| 19841 |
|
| 19842 |
<span class="h4"><a class="selflink" id="section-15.1.10" href="#section-15.1.10">15.1.10</a>. pNFS Errors</span> |
| 19843 |
|
| 19844 |
This section deals with pNFS-related errors including those that are |
| 19845 |
associated with using NFSv4.1 to communicate with a data server. |
| 19846 |
|
| 19847 |
<span class="h5"><a class="selflink" id="section-15.1.10.1" href="#section-15.1.10.1">15.1.10.1</a>. NFS4ERR_BADIOMODE (Error Code 10049)</span> |
| 19848 |
|
| 19849 |
An invalid or inappropriate layout iomode was specified. For example |
| 19850 |
an inappropriate layout iomode, suppose a client's LAYOUTGET |
| 19851 |
operation specified an iomode of LAYOUTIOMODE4_RW, and the server is |
| 19852 |
neither able nor willing to let the client send write requests to |
| 19853 |
data servers; the server can reply with NFS4ERR_BADIOMODE. The |
| 19854 |
client would then send another LAYOUTGET with an iomode of |
| 19855 |
LAYOUTIOMODE4_READ. |
| 19856 |
|
| 19857 |
<span class="h5"><a class="selflink" id="section-15.1.10.2" href="#section-15.1.10.2">15.1.10.2</a>. NFS4ERR_BADLAYOUT (Error Code 10050)</span> |
| 19858 |
|
| 19859 |
The layout specified is invalid in some way. For LAYOUTCOMMIT, this |
| 19860 |
indicates that the specified layout is not held by the client or is |
| 19861 |
not of mode LAYOUTIOMODE4_RW. For LAYOUTGET, it indicates that a |
| 19862 |
layout matching the client's specification as to minimum length |
| 19863 |
cannot be granted. |
| 19864 |
|
| 19865 |
<span class="h5"><a class="selflink" id="section-15.1.10.3" href="#section-15.1.10.3">15.1.10.3</a>. NFS4ERR_LAYOUTTRYLATER (Error Code 10058)</span> |
| 19866 |
|
| 19867 |
Layouts are temporarily unavailable for the file. The client should |
| 19868 |
re-send later (but not with the same slot ID and sequence ID; one or |
| 19869 |
both MUST be different on the re-send). |
| 19870 |
|
| 19871 |
|
| 19872 |
|
| 19873 |
|
| 19874 |
|
| 19875 |
|
| 19876 |
<span class="grey">Shepler, et al. Standards Track [Page 355]</span></pre> |
| 19877 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-356" ></span> |
| 19878 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19879 |
|
| 19880 |
|
| 19881 |
<span class="h5"><a class="selflink" id="section-15.1.10.4" href="#section-15.1.10.4">15.1.10.4</a>. NFS4ERR_LAYOUTUNAVAILABLE (Error Code 10059)</span> |
| 19882 |
|
| 19883 |
Returned when layouts are not available for the current file system |
| 19884 |
or the particular specified file. |
| 19885 |
|
| 19886 |
<span class="h5"><a class="selflink" id="section-15.1.10.5" href="#section-15.1.10.5">15.1.10.5</a>. NFS4ERR_NOMATCHING_LAYOUT (Error Code 10060)</span> |
| 19887 |
|
| 19888 |
Returned when layouts are recalled and the client has no layouts |
| 19889 |
matching the specification of the layouts being recalled. |
| 19890 |
|
| 19891 |
<span class="h5"><a class="selflink" id="section-15.1.10.6" href="#section-15.1.10.6">15.1.10.6</a>. NFS4ERR_PNFS_IO_HOLE (Error Code 10075)</span> |
| 19892 |
|
| 19893 |
The pNFS client has attempted to read from or write to an illegal |
| 19894 |
hole of a file of a data server that is using sparse packing. See |
| 19895 |
<a href="#section-13.4.4">Section 13.4.4</a>. |
| 19896 |
|
| 19897 |
<span class="h5"><a class="selflink" id="section-15.1.10.7" href="#section-15.1.10.7">15.1.10.7</a>. NFS4ERR_PNFS_NO_LAYOUT (Error Code 10080)</span> |
| 19898 |
|
| 19899 |
The pNFS client has attempted to read from or write to a file (using |
| 19900 |
a request to a data server) without holding a valid layout. This |
| 19901 |
includes the case where the client had a layout, but the iomode does |
| 19902 |
not allow a WRITE. |
| 19903 |
|
| 19904 |
<span class="h5"><a class="selflink" id="section-15.1.10.8" href="#section-15.1.10.8">15.1.10.8</a>. NFS4ERR_RETURNCONFLICT (Error Code 10086)</span> |
| 19905 |
|
| 19906 |
A layout is unavailable due to an attempt to perform the LAYOUTGET |
| 19907 |
before a pending LAYOUTRETURN on the file has been received. See |
| 19908 |
<a href="#section-12.5.5.2.1.3">Section 12.5.5.2.1.3</a>. |
| 19909 |
|
| 19910 |
<span class="h5"><a class="selflink" id="section-15.1.10.9" href="#section-15.1.10.9">15.1.10.9</a>. NFS4ERR_UNKNOWN_LAYOUTTYPE (Error Code 10062)</span> |
| 19911 |
|
| 19912 |
The client has specified a layout type that is not supported by the |
| 19913 |
server. |
| 19914 |
|
| 19915 |
<span class="h4"><a class="selflink" id="section-15.1.11" href="#section-15.1.11">15.1.11</a>. Session Use Errors</span> |
| 19916 |
|
| 19917 |
This section deals with errors encountered when using sessions, that |
| 19918 |
is, errors encountered when a request uses a Sequence (i.e., either |
| 19919 |
SEQUENCE or CB_SEQUENCE) operation. |
| 19920 |
|
| 19921 |
<span class="h5"><a class="selflink" id="section-15.1.11.1" href="#section-15.1.11.1">15.1.11.1</a>. NFS4ERR_BADSESSION (Error Code 10052)</span> |
| 19922 |
|
| 19923 |
The specified session ID is unknown to the server to which the |
| 19924 |
operation is addressed. |
| 19925 |
|
| 19926 |
|
| 19927 |
|
| 19928 |
|
| 19929 |
|
| 19930 |
|
| 19931 |
|
| 19932 |
<span class="grey">Shepler, et al. Standards Track [Page 356]</span></pre> |
| 19933 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-357" ></span> |
| 19934 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19935 |
|
| 19936 |
|
| 19937 |
<span class="h5"><a class="selflink" id="section-15.1.11.2" href="#section-15.1.11.2">15.1.11.2</a>. NFS4ERR_BADSLOT (Error Code 10053)</span> |
| 19938 |
|
| 19939 |
The requester sent a Sequence operation that attempted to use a slot |
| 19940 |
the replier does not have in its slot table. It is possible the slot |
| 19941 |
may have been retired. |
| 19942 |
|
| 19943 |
<span class="h5"><a class="selflink" id="section-15.1.11.3" href="#section-15.1.11.3">15.1.11.3</a>. NFS4ERR_BAD_HIGH_SLOT (Error Code 10077)</span> |
| 19944 |
|
| 19945 |
The highest_slot argument in a Sequence operation exceeds the |
| 19946 |
replier's enforced highest_slotid. |
| 19947 |
|
| 19948 |
<span class="h5"><a class="selflink" id="section-15.1.11.4" href="#section-15.1.11.4">15.1.11.4</a>. NFS4ERR_CB_PATH_DOWN (Error Code 10048)</span> |
| 19949 |
|
| 19950 |
There is a problem contacting the client via the callback path. The |
| 19951 |
function of this error has been mostly superseded by the use of |
| 19952 |
status flags in the reply to the SEQUENCE operation (see |
| 19953 |
<a href="#section-18.46">Section 18.46</a>). |
| 19954 |
|
| 19955 |
<span class="h5"><a class="selflink" id="section-15.1.11.5" href="#section-15.1.11.5">15.1.11.5</a>. NFS4ERR_DEADSESSION (Error Code 10078)</span> |
| 19956 |
|
| 19957 |
The specified session is a persistent session that is dead and does |
| 19958 |
not accept new requests or perform new operations on existing |
| 19959 |
requests (in the case in which a request was partially executed |
| 19960 |
before server restart). |
| 19961 |
|
| 19962 |
<span class="h5"><a class="selflink" id="section-15.1.11.6" href="#section-15.1.11.6">15.1.11.6</a>. NFS4ERR_CONN_NOT_BOUND_TO_SESSION (Error Code 10055)</span> |
| 19963 |
|
| 19964 |
A Sequence operation was sent on a connection that has not been |
| 19965 |
associated with the specified session, where the client specified |
| 19966 |
that connection association was to be enforced with SP4_MACH_CRED or |
| 19967 |
SP4_SSV state protection. |
| 19968 |
|
| 19969 |
<span class="h5"><a class="selflink" id="section-15.1.11.7" href="#section-15.1.11.7">15.1.11.7</a>. NFS4ERR_SEQ_FALSE_RETRY (Error Code 10076)</span> |
| 19970 |
|
| 19971 |
The requester sent a Sequence operation with a slot ID and sequence |
| 19972 |
ID that are in the reply cache, but the replier has detected that the |
| 19973 |
retried request is not the same as the original request. See |
| 19974 |
<a href="#section-2.10.6.1.3.1">Section 2.10.6.1.3.1</a>. |
| 19975 |
|
| 19976 |
<span class="h5"><a class="selflink" id="section-15.1.11.8" href="#section-15.1.11.8">15.1.11.8</a>. NFS4ERR_SEQ_MISORDERED (Error Code 10063)</span> |
| 19977 |
|
| 19978 |
The requester sent a Sequence operation with an invalid sequence ID. |
| 19979 |
|
| 19980 |
<span class="h4"><a class="selflink" id="section-15.1.12" href="#section-15.1.12">15.1.12</a>. Session Management Errors</span> |
| 19981 |
|
| 19982 |
This section deals with errors associated with requests used in |
| 19983 |
session management. |
| 19984 |
|
| 19985 |
|
| 19986 |
|
| 19987 |
|
| 19988 |
<span class="grey">Shepler, et al. Standards Track [Page 357]</span></pre> |
| 19989 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-358" ></span> |
| 19990 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 19991 |
|
| 19992 |
|
| 19993 |
<span class="h5"><a class="selflink" id="section-15.1.12.1" href="#section-15.1.12.1">15.1.12.1</a>. NFS4ERR_BACK_CHAN_BUSY (Error Code 10057)</span> |
| 19994 |
|
| 19995 |
An attempt was made to destroy a session when the session cannot be |
| 19996 |
destroyed because the server has callback requests outstanding. |
| 19997 |
|
| 19998 |
<span class="h5"><a class="selflink" id="section-15.1.12.2" href="#section-15.1.12.2">15.1.12.2</a>. NFS4ERR_BAD_SESSION_DIGEST (Error Code 10051)</span> |
| 19999 |
|
| 20000 |
The digest used in a SET_SSV request is not valid. |
| 20001 |
|
| 20002 |
<span class="h4"><a class="selflink" id="section-15.1.13" href="#section-15.1.13">15.1.13</a>. Client Management Errors</span> |
| 20003 |
|
| 20004 |
This section deals with errors associated with requests used to |
| 20005 |
create and manage client IDs. |
| 20006 |
|
| 20007 |
<span class="h5"><a class="selflink" id="section-15.1.13.1" href="#section-15.1.13.1">15.1.13.1</a>. NFS4ERR_CLIENTID_BUSY (Error Code 10074)</span> |
| 20008 |
|
| 20009 |
The DESTROY_CLIENTID operation has found there are sessions and/or |
| 20010 |
unexpired state associated with the client ID to be destroyed. |
| 20011 |
|
| 20012 |
<span class="h5"><a class="selflink" id="section-15.1.13.2" href="#section-15.1.13.2">15.1.13.2</a>. NFS4ERR_CLID_INUSE (Error Code 10017)</span> |
| 20013 |
|
| 20014 |
While processing an EXCHANGE_ID operation, the server was presented |
| 20015 |
with a co_ownerid field that matches an existing client with valid |
| 20016 |
leased state, but the principal sending the EXCHANGE_ID operation |
| 20017 |
differs from the principal that established the existing client. |
| 20018 |
This indicates a collision (most likely due to chance) between |
| 20019 |
clients. The client should recover by changing the co_ownerid and |
| 20020 |
re-sending EXCHANGE_ID (but not with the same slot ID and sequence |
| 20021 |
ID; one or both MUST be different on the re-send). |
| 20022 |
|
| 20023 |
<span class="h5"><a class="selflink" id="section-15.1.13.3" href="#section-15.1.13.3">15.1.13.3</a>. NFS4ERR_ENCR_ALG_UNSUPP (Error Code 10079)</span> |
| 20024 |
|
| 20025 |
An EXCHANGE_ID was sent that specified state protection via SSV, and |
| 20026 |
where the set of encryption algorithms presented by the client did |
| 20027 |
not include any supported by the server. |
| 20028 |
|
| 20029 |
<span class="h5"><a class="selflink" id="section-15.1.13.4" href="#section-15.1.13.4">15.1.13.4</a>. NFS4ERR_HASH_ALG_UNSUPP (Error Code 10072)</span> |
| 20030 |
|
| 20031 |
An EXCHANGE_ID was sent that specified state protection via SSV, and |
| 20032 |
where the set of hashing algorithms presented by the client did not |
| 20033 |
include any supported by the server. |
| 20034 |
|
| 20035 |
<span class="h5"><a class="selflink" id="section-15.1.13.5" href="#section-15.1.13.5">15.1.13.5</a>. NFS4ERR_STALE_CLIENTID (Error Code 10022)</span> |
| 20036 |
|
| 20037 |
A client ID not recognized by the server was passed to an operation. |
| 20038 |
Note that unlike the case of NFSv4.0, client IDs are not passed |
| 20039 |
explicitly to the server in ordinary locking operations and cannot |
| 20040 |
result in this error. Instead, when there is a server restart, it is |
| 20041 |
|
| 20042 |
|
| 20043 |
|
| 20044 |
<span class="grey">Shepler, et al. Standards Track [Page 358]</span></pre> |
| 20045 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-359" ></span> |
| 20046 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20047 |
|
| 20048 |
|
| 20049 |
first manifested through an error on the associated session, and the |
| 20050 |
staleness of the client ID is detected when trying to associate a |
| 20051 |
client ID with a new session. |
| 20052 |
|
| 20053 |
<span class="h4"><a class="selflink" id="section-15.1.14" href="#section-15.1.14">15.1.14</a>. Delegation Errors</span> |
| 20054 |
|
| 20055 |
This section deals with errors associated with requesting and |
| 20056 |
returning delegations. |
| 20057 |
|
| 20058 |
<span class="h5"><a class="selflink" id="section-15.1.14.1" href="#section-15.1.14.1">15.1.14.1</a>. NFS4ERR_DELEG_ALREADY_WANTED (Error Code 10056)</span> |
| 20059 |
|
| 20060 |
The client has requested a delegation when it had already registered |
| 20061 |
that it wants that same delegation. |
| 20062 |
|
| 20063 |
<span class="h5"><a class="selflink" id="section-15.1.14.2" href="#section-15.1.14.2">15.1.14.2</a>. NFS4ERR_DIRDELEG_UNAVAIL (Error Code 10084)</span> |
| 20064 |
|
| 20065 |
This error is returned when the server is unable or unwilling to |
| 20066 |
provide a requested directory delegation. |
| 20067 |
|
| 20068 |
<span class="h5"><a class="selflink" id="section-15.1.14.3" href="#section-15.1.14.3">15.1.14.3</a>. NFS4ERR_RECALLCONFLICT (Error Code 10061)</span> |
| 20069 |
|
| 20070 |
A recallable object (i.e., a layout or delegation) is unavailable due |
| 20071 |
to a conflicting recall operation that is currently in progress for |
| 20072 |
that object. |
| 20073 |
|
| 20074 |
<span class="h5"><a class="selflink" id="section-15.1.14.4" href="#section-15.1.14.4">15.1.14.4</a>. NFS4ERR_REJECT_DELEG (Error Code 10085)</span> |
| 20075 |
|
| 20076 |
The callback operation invoked to deal with a new delegation has |
| 20077 |
rejected it. |
| 20078 |
|
| 20079 |
<span class="h4"><a class="selflink" id="section-15.1.15" href="#section-15.1.15">15.1.15</a>. Attribute Handling Errors</span> |
| 20080 |
|
| 20081 |
This section deals with errors specific to attribute handling within |
| 20082 |
NFSv4. |
| 20083 |
|
| 20084 |
<span class="h5"><a class="selflink" id="section-15.1.15.1" href="#section-15.1.15.1">15.1.15.1</a>. NFS4ERR_ATTRNOTSUPP (Error Code 10032)</span> |
| 20085 |
|
| 20086 |
An attribute specified is not supported by the server. This error |
| 20087 |
MUST NOT be returned by the GETATTR operation. |
| 20088 |
|
| 20089 |
<span class="h5"><a class="selflink" id="section-15.1.15.2" href="#section-15.1.15.2">15.1.15.2</a>. NFS4ERR_BADOWNER (Error Code 10039)</span> |
| 20090 |
|
| 20091 |
This error is returned when an owner or owner_group attribute value |
| 20092 |
or the who field of an ACE within an ACL attribute value cannot be |
| 20093 |
translated to a local representation. |
| 20094 |
|
| 20095 |
|
| 20096 |
|
| 20097 |
|
| 20098 |
|
| 20099 |
|
| 20100 |
<span class="grey">Shepler, et al. Standards Track [Page 359]</span></pre> |
| 20101 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-360" ></span> |
| 20102 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20103 |
|
| 20104 |
|
| 20105 |
<span class="h5"><a class="selflink" id="section-15.1.15.3" href="#section-15.1.15.3">15.1.15.3</a>. NFS4ERR_NOT_SAME (Error Code 10027)</span> |
| 20106 |
|
| 20107 |
This error is returned by the VERIFY operation to signify that the |
| 20108 |
attributes compared were not the same as those provided in the |
| 20109 |
client's request. |
| 20110 |
|
| 20111 |
<span class="h5"><a class="selflink" id="section-15.1.15.4" href="#section-15.1.15.4">15.1.15.4</a>. NFS4ERR_SAME (Error Code 10009)</span> |
| 20112 |
|
| 20113 |
This error is returned by the NVERIFY operation to signify that the |
| 20114 |
attributes compared were the same as those provided in the client's |
| 20115 |
request. |
| 20116 |
|
| 20117 |
<span class="h4"><a class="selflink" id="section-15.1.16" href="#section-15.1.16">15.1.16</a>. Obsoleted Errors</span> |
| 20118 |
|
| 20119 |
These errors MUST NOT be generated by any NFSv4.1 operation. This |
| 20120 |
can be for a number of reasons. |
| 20121 |
|
| 20122 |
o The function provided by the error has been superseded by one of |
| 20123 |
the status bits returned by the SEQUENCE operation. |
| 20124 |
|
| 20125 |
o The new session structure and associated change in locking have |
| 20126 |
made the error unnecessary. |
| 20127 |
|
| 20128 |
o There has been a restructuring of some errors for NFSv4.1 that |
| 20129 |
resulted in the elimination of certain errors. |
| 20130 |
|
| 20131 |
<span class="h5"><a class="selflink" id="section-15.1.16.1" href="#section-15.1.16.1">15.1.16.1</a>. NFS4ERR_BAD_SEQID (Error Code 10026)</span> |
| 20132 |
|
| 20133 |
The sequence number (seqid) in a locking request is neither the next |
| 20134 |
expected number or the last number processed. These seqids are |
| 20135 |
ignored in NFSv4.1. |
| 20136 |
|
| 20137 |
<span class="h5"><a class="selflink" id="section-15.1.16.2" href="#section-15.1.16.2">15.1.16.2</a>. NFS4ERR_LEASE_MOVED (Error Code 10031)</span> |
| 20138 |
|
| 20139 |
A lease being renewed is associated with a file system that has been |
| 20140 |
migrated to a new server. The error has been superseded by the |
| 20141 |
SEQ4_STATUS_LEASE_MOVED status bit (see <a href="#section-18.46">Section 18.46</a>). |
| 20142 |
|
| 20143 |
<span class="h5"><a class="selflink" id="section-15.1.16.3" href="#section-15.1.16.3">15.1.16.3</a>. NFS4ERR_NXIO (Error Code 5)</span> |
| 20144 |
|
| 20145 |
I/O error. No such device or address. This error is for errors |
| 20146 |
involving block and character device access, but because NFSv4.1 is |
| 20147 |
not a device-access protocol, this error is not applicable. |
| 20148 |
|
| 20149 |
|
| 20150 |
|
| 20151 |
|
| 20152 |
|
| 20153 |
|
| 20154 |
|
| 20155 |
|
| 20156 |
<span class="grey">Shepler, et al. Standards Track [Page 360]</span></pre> |
| 20157 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-361" ></span> |
| 20158 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20159 |
|
| 20160 |
|
| 20161 |
<span class="h5"><a class="selflink" id="section-15.1.16.4" href="#section-15.1.16.4">15.1.16.4</a>. NFS4ERR_RESTOREFH (Error Code 10030)</span> |
| 20162 |
|
| 20163 |
The RESTOREFH operation does not have a saved filehandle (identified |
| 20164 |
by SAVEFH) to operate upon. In NFSv4.1, this error has been |
| 20165 |
superseded by NFS4ERR_NOFILEHANDLE. |
| 20166 |
|
| 20167 |
<span class="h5"><a class="selflink" id="section-15.1.16.5" href="#section-15.1.16.5">15.1.16.5</a>. NFS4ERR_STALE_STATEID (Error Code 10023)</span> |
| 20168 |
|
| 20169 |
A stateid generated by an earlier server instance was used. This |
| 20170 |
error is moot in NFSv4.1 because all operations that take a stateid |
| 20171 |
MUST be preceded by the SEQUENCE operation, and the earlier server |
| 20172 |
instance is detected by the session infrastructure that supports |
| 20173 |
SEQUENCE. |
| 20174 |
|
| 20175 |
<span class="h3"><a class="selflink" id="section-15.2" href="#section-15.2">15.2</a>. Operations and Their Valid Errors</span> |
| 20176 |
|
| 20177 |
This section contains a table that gives the valid error returns for |
| 20178 |
each protocol operation. The error code NFS4_OK (indicating no |
| 20179 |
error) is not listed but should be understood to be returnable by all |
| 20180 |
operations with two important exceptions: |
| 20181 |
|
| 20182 |
o The operations that MUST NOT be implemented: OPEN_CONFIRM, |
| 20183 |
RELEASE_LOCKOWNER, RENEW, SETCLIENTID, and SETCLIENTID_CONFIRM. |
| 20184 |
|
| 20185 |
o The invalid operation: ILLEGAL. |
| 20186 |
|
| 20187 |
|
| 20188 |
|
| 20189 |
|
| 20190 |
|
| 20191 |
|
| 20192 |
|
| 20193 |
|
| 20194 |
|
| 20195 |
|
| 20196 |
|
| 20197 |
|
| 20198 |
|
| 20199 |
|
| 20200 |
|
| 20201 |
|
| 20202 |
|
| 20203 |
|
| 20204 |
|
| 20205 |
|
| 20206 |
|
| 20207 |
|
| 20208 |
|
| 20209 |
|
| 20210 |
|
| 20211 |
|
| 20212 |
<span class="grey">Shepler, et al. Standards Track [Page 361]</span></pre> |
| 20213 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-362" ></span> |
| 20214 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20215 |
|
| 20216 |
|
| 20217 |
Valid Error Returns for Each Protocol Operation |
| 20218 |
|
| 20219 |
+----------------------+--------------------------------------------+ |
| 20220 |
| Operation | Errors | |
| 20221 |
+----------------------+--------------------------------------------+ |
| 20222 |
| ACCESS | NFS4ERR_ACCESS, NFS4ERR_BADXDR, | |
| 20223 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20224 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | |
| 20225 |
| | NFS4ERR_IO, NFS4ERR_MOVED, | |
| 20226 |
| | NFS4ERR_NOFILEHANDLE, | |
| 20227 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20228 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20229 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20230 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20231 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20232 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20233 |
| | NFS4ERR_TOO_MANY_OPS | |
| 20234 |
| BACKCHANNEL_CTL | NFS4ERR_BADXDR, NFS4ERR_DEADSESSION, | |
| 20235 |
| | NFS4ERR_DELAY, NFS4ERR_INVAL, | |
| 20236 |
| | NFS4ERR_NOENT, NFS4ERR_OP_NOT_IN_SESSION, | |
| 20237 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20238 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20239 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20240 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20241 |
| | NFS4ERR_TOO_MANY_OPS | |
| 20242 |
| BIND_CONN_TO_SESSION | NFS4ERR_BADSESSION, NFS4ERR_BADXDR, | |
| 20243 |
| | NFS4ERR_BAD_SESSION_DIGEST, | |
| 20244 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20245 |
| | NFS4ERR_INVAL, NFS4ERR_NOT_ONLY_OP, | |
| 20246 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20247 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20248 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20249 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20250 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_TOO_MANY_OPS | |
| 20251 |
| CLOSE | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADXDR, | |
| 20252 |
| | NFS4ERR_BAD_STATEID, NFS4ERR_DEADSESSION, | |
| 20253 |
| | NFS4ERR_DELAY, NFS4ERR_EXPIRED, | |
| 20254 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_LOCKS_HELD, | |
| 20255 |
| | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | |
| 20256 |
| | NFS4ERR_OLD_STATEID, | |
| 20257 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20258 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20259 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20260 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20261 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20262 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20263 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_CRED | |
| 20264 |
| COMMIT | NFS4ERR_ACCESS, NFS4ERR_BADXDR, | |
| 20265 |
|
| 20266 |
|
| 20267 |
|
| 20268 |
<span class="grey">Shepler, et al. Standards Track [Page 362]</span></pre> |
| 20269 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-363" ></span> |
| 20270 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20271 |
|
| 20272 |
|
| 20273 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20274 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_IO, | |
| 20275 |
| | NFS4ERR_ISDIR, NFS4ERR_MOVED, | |
| 20276 |
| | NFS4ERR_NOFILEHANDLE, | |
| 20277 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20278 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20279 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20280 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20281 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20282 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20283 |
| | NFS4ERR_SYMLINK, NFS4ERR_TOO_MANY_OPS, | |
| 20284 |
| | NFS4ERR_WRONG_TYPE | |
| 20285 |
| CREATE | NFS4ERR_ACCESS, NFS4ERR_ATTRNOTSUPP, | |
| 20286 |
| | NFS4ERR_BADCHAR, NFS4ERR_BADNAME, | |
| 20287 |
| | NFS4ERR_BADOWNER, NFS4ERR_BADTYPE, | |
| 20288 |
| | NFS4ERR_BADXDR, NFS4ERR_DEADSESSION, | |
| 20289 |
| | NFS4ERR_DELAY, NFS4ERR_DQUOT, | |
| 20290 |
| | NFS4ERR_EXIST, NFS4ERR_FHEXPIRED, | |
| 20291 |
| | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MLINK, | |
| 20292 |
| | NFS4ERR_MOVED, NFS4ERR_NAMETOOLONG, | |
| 20293 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | |
| 20294 |
| | NFS4ERR_NOTDIR, NFS4ERR_OP_NOT_IN_SESSION, | |
| 20295 |
| | NFS4ERR_PERM, NFS4ERR_REP_TOO_BIG, | |
| 20296 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20297 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20298 |
| | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | |
| 20299 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20300 |
| | NFS4ERR_TOO_MANY_OPS, | |
| 20301 |
| | NFS4ERR_UNSAFE_COMPOUND | |
| 20302 |
| CREATE_SESSION | NFS4ERR_BADXDR, NFS4ERR_CLID_INUSE, | |
| 20303 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20304 |
| | NFS4ERR_INVAL, NFS4ERR_NOENT, | |
| 20305 |
| | NFS4ERR_NOT_ONLY_OP, NFS4ERR_NOSPC, | |
| 20306 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20307 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20308 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20309 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20310 |
| | NFS4ERR_SEQ_MISORDERED, | |
| 20311 |
| | NFS4ERR_SERVERFAULT, | |
| 20312 |
| | NFS4ERR_STALE_CLIENTID, NFS4ERR_TOOSMALL, | |
| 20313 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_CRED | |
| 20314 |
| DELEGPURGE | NFS4ERR_BADXDR, NFS4ERR_DEADSESSION, | |
| 20315 |
| | NFS4ERR_DELAY, NFS4ERR_NOTSUPP, | |
| 20316 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20317 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20318 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20319 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20320 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20321 |
|
| 20322 |
|
| 20323 |
|
| 20324 |
<span class="grey">Shepler, et al. Standards Track [Page 363]</span></pre> |
| 20325 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-364" ></span> |
| 20326 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20327 |
|
| 20328 |
|
| 20329 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_TOO_MANY_OPS, | |
| 20330 |
| | NFS4ERR_WRONG_CRED | |
| 20331 |
| DELEGRETURN | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADXDR, | |
| 20332 |
| | NFS4ERR_BAD_STATEID, NFS4ERR_DEADSESSION, | |
| 20333 |
| | NFS4ERR_DELAY, NFS4ERR_DELEG_REVOKED, | |
| 20334 |
| | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED, | |
| 20335 |
| | NFS4ERR_INVAL, NFS4ERR_MOVED, | |
| 20336 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTSUPP, | |
| 20337 |
| | NFS4ERR_OLD_STATEID, | |
| 20338 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20339 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20340 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20341 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20342 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20343 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20344 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_CRED | |
| 20345 |
| DESTROY_CLIENTID | NFS4ERR_BADXDR, NFS4ERR_CLIENTID_BUSY, | |
| 20346 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20347 |
| | NFS4ERR_NOT_ONLY_OP, NFS4ERR_REP_TOO_BIG, | |
| 20348 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20349 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20350 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20351 |
| | NFS4ERR_SERVERFAULT, | |
| 20352 |
| | NFS4ERR_STALE_CLIENTID, | |
| 20353 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_CRED | |
| 20354 |
| DESTROY_SESSION | NFS4ERR_BACK_CHAN_BUSY, | |
| 20355 |
| | NFS4ERR_BADSESSION, NFS4ERR_BADXDR, | |
| 20356 |
| | NFS4ERR_CB_PATH_DOWN, | |
| 20357 |
| | NFS4ERR_CONN_NOT_BOUND_TO_SESSION, | |
| 20358 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20359 |
| | NFS4ERR_NOT_ONLY_OP, NFS4ERR_REP_TOO_BIG, | |
| 20360 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20361 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20362 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20363 |
| | NFS4ERR_SERVERFAULT, | |
| 20364 |
| | NFS4ERR_STALE_CLIENTID, | |
| 20365 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_CRED | |
| 20366 |
| EXCHANGE_ID | NFS4ERR_BADCHAR, NFS4ERR_BADXDR, | |
| 20367 |
| | NFS4ERR_CLID_INUSE, NFS4ERR_DEADSESSION, | |
| 20368 |
| | NFS4ERR_DELAY, NFS4ERR_ENCR_ALG_UNSUPP, | |
| 20369 |
| | NFS4ERR_HASH_ALG_UNSUPP, NFS4ERR_INVAL, | |
| 20370 |
| | NFS4ERR_NOENT, NFS4ERR_NOT_ONLY_OP, | |
| 20371 |
| | NFS4ERR_NOT_SAME, NFS4ERR_REP_TOO_BIG, | |
| 20372 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20373 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20374 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20375 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_TOO_MANY_OPS | |
| 20376 |
| FREE_STATEID | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, | |
| 20377 |
|
| 20378 |
|
| 20379 |
|
| 20380 |
<span class="grey">Shepler, et al. Standards Track [Page 364]</span></pre> |
| 20381 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-365" ></span> |
| 20382 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20383 |
|
| 20384 |
|
| 20385 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20386 |
| | NFS4ERR_LOCKS_HELD, NFS4ERR_OLD_STATEID, | |
| 20387 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20388 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20389 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20390 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20391 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20392 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_TOO_MANY_OPS, | |
| 20393 |
| | NFS4ERR_WRONG_CRED | |
| 20394 |
| GET_DIR_DELEGATION | NFS4ERR_ACCESS, NFS4ERR_BADXDR, | |
| 20395 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20396 |
| | NFS4ERR_DIRDELEG_UNAVAIL, | |
| 20397 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | |
| 20398 |
| | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | |
| 20399 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTDIR, | |
| 20400 |
| | NFS4ERR_NOTSUPP, | |
| 20401 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20402 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20403 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20404 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20405 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20406 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20407 |
| | NFS4ERR_TOO_MANY_OPS | |
| 20408 |
| GETATTR | NFS4ERR_ACCESS, NFS4ERR_BADXDR, | |
| 20409 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20410 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | |
| 20411 |
| | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | |
| 20412 |
| | NFS4ERR_NOFILEHANDLE, | |
| 20413 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20414 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20415 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20416 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20417 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20418 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20419 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE | |
| 20420 |
| GETDEVICEINFO | NFS4ERR_BADXDR, NFS4ERR_DEADSESSION, | |
| 20421 |
| | NFS4ERR_DELAY, NFS4ERR_INVAL, | |
| 20422 |
| | NFS4ERR_NOENT, NFS4ERR_NOTSUPP, | |
| 20423 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20424 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20425 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20426 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20427 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20428 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_TOOSMALL, | |
| 20429 |
| | NFS4ERR_TOO_MANY_OPS, | |
| 20430 |
| | NFS4ERR_UNKNOWN_LAYOUTTYPE | |
| 20431 |
| GETDEVICELIST | NFS4ERR_BADXDR, NFS4ERR_BAD_COOKIE, | |
| 20432 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20433 |
|
| 20434 |
|
| 20435 |
|
| 20436 |
<span class="grey">Shepler, et al. Standards Track [Page 365]</span></pre> |
| 20437 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-366" ></span> |
| 20438 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20439 |
|
| 20440 |
|
| 20441 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | |
| 20442 |
| | NFS4ERR_IO, NFS4ERR_NOFILEHANDLE, | |
| 20443 |
| | NFS4ERR_NOTSUPP, NFS4ERR_NOT_SAME, | |
| 20444 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20445 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20446 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20447 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20448 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20449 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_TOO_MANY_OPS, | |
| 20450 |
| | NFS4ERR_UNKNOWN_LAYOUTTYPE | |
| 20451 |
| GETFH | NFS4ERR_FHEXPIRED, NFS4ERR_MOVED, | |
| 20452 |
| | NFS4ERR_NOFILEHANDLE, | |
| 20453 |
| | NFS4ERR_OP_NOT_IN_SESSION, NFS4ERR_STALE | |
| 20454 |
| ILLEGAL | NFS4ERR_BADXDR, NFS4ERR_OP_ILLEGAL | |
| 20455 |
| LAYOUTCOMMIT | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | |
| 20456 |
| | NFS4ERR_ATTRNOTSUPP, NFS4ERR_BADIOMODE, | |
| 20457 |
| | NFS4ERR_BADLAYOUT, NFS4ERR_BADXDR, | |
| 20458 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20459 |
| | NFS4ERR_DELEG_REVOKED, NFS4ERR_EXPIRED, | |
| 20460 |
| | NFS4ERR_FBIG, NFS4ERR_FHEXPIRED, | |
| 20461 |
| | NFS4ERR_GRACE, NFS4ERR_INVAL, NFS4ERR_IO, | |
| 20462 |
| | NFS4ERR_ISDIR NFS4ERR_MOVED, | |
| 20463 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTSUPP, | |
| 20464 |
| | NFS4ERR_NO_GRACE, | |
| 20465 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20466 |
| | NFS4ERR_RECLAIM_BAD, | |
| 20467 |
| | NFS4ERR_RECLAIM_CONFLICT, | |
| 20468 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20469 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20470 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20471 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20472 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20473 |
| | NFS4ERR_SYMLINK, NFS4ERR_TOO_MANY_OPS, | |
| 20474 |
| | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |
| 20475 |
| | NFS4ERR_WRONG_CRED | |
| 20476 |
| LAYOUTGET | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | |
| 20477 |
| | NFS4ERR_BADIOMODE, NFS4ERR_BADLAYOUT, | |
| 20478 |
| | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, | |
| 20479 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20480 |
| | NFS4ERR_DELEG_REVOKED, NFS4ERR_DQUOT, | |
| 20481 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | |
| 20482 |
| | NFS4ERR_INVAL, NFS4ERR_IO, | |
| 20483 |
| | NFS4ERR_LAYOUTTRYLATER, | |
| 20484 |
| | NFS4ERR_LAYOUTUNAVAILABLE, NFS4ERR_LOCKED, | |
| 20485 |
| | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | |
| 20486 |
| | NFS4ERR_NOSPC, NFS4ERR_NOTSUPP, | |
| 20487 |
| | NFS4ERR_OLD_STATEID, NFS4ERR_OPENMODE, | |
| 20488 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20489 |
|
| 20490 |
|
| 20491 |
|
| 20492 |
<span class="grey">Shepler, et al. Standards Track [Page 366]</span></pre> |
| 20493 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-367" ></span> |
| 20494 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20495 |
|
| 20496 |
|
| 20497 |
| | NFS4ERR_RECALLCONFLICT, | |
| 20498 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20499 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20500 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20501 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20502 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20503 |
| | NFS4ERR_TOOSMALL, NFS4ERR_TOO_MANY_OPS, | |
| 20504 |
| | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |
| 20505 |
| | NFS4ERR_WRONG_TYPE | |
| 20506 |
| LAYOUTRETURN | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADXDR, | |
| 20507 |
| | NFS4ERR_BAD_STATEID, NFS4ERR_DEADSESSION, | |
| 20508 |
| | NFS4ERR_DELAY, NFS4ERR_DELEG_REVOKED, | |
| 20509 |
| | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED, | |
| 20510 |
| | NFS4ERR_GRACE, NFS4ERR_INVAL, | |
| 20511 |
| | NFS4ERR_ISDIR, NFS4ERR_MOVED, | |
| 20512 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTSUPP, | |
| 20513 |
| | NFS4ERR_NO_GRACE, NFS4ERR_OLD_STATEID, | |
| 20514 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20515 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20516 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20517 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20518 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20519 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20520 |
| | NFS4ERR_TOO_MANY_OPS, | |
| 20521 |
| | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |
| 20522 |
| | NFS4ERR_WRONG_CRED, NFS4ERR_WRONG_TYPE | |
| 20523 |
| LINK | NFS4ERR_ACCESS, NFS4ERR_BADCHAR, | |
| 20524 |
| | NFS4ERR_BADNAME, NFS4ERR_BADXDR, | |
| 20525 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20526 |
| | NFS4ERR_DQUOT, NFS4ERR_EXIST, | |
| 20527 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_FILE_OPEN, | |
| 20528 |
| | NFS4ERR_GRACE, NFS4ERR_INVAL, | |
| 20529 |
| | NFS4ERR_ISDIR, NFS4ERR_IO, NFS4ERR_MLINK, | |
| 20530 |
| | NFS4ERR_MOVED, NFS4ERR_NAMETOOLONG, | |
| 20531 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | |
| 20532 |
| | NFS4ERR_NOTDIR, NFS4ERR_NOTSUPP, | |
| 20533 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20534 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20535 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20536 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20537 |
| | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | |
| 20538 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20539 |
| | NFS4ERR_SYMLINK, NFS4ERR_TOO_MANY_OPS, | |
| 20540 |
| | NFS4ERR_WRONGSEC, NFS4ERR_WRONG_TYPE, | |
| 20541 |
| | NFS4ERR_XDEV | |
| 20542 |
| LOCK | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | |
| 20543 |
| | NFS4ERR_BADXDR, NFS4ERR_BAD_RANGE, | |
| 20544 |
| | NFS4ERR_BAD_STATEID, NFS4ERR_DEADLOCK, | |
| 20545 |
|
| 20546 |
|
| 20547 |
|
| 20548 |
<span class="grey">Shepler, et al. Standards Track [Page 367]</span></pre> |
| 20549 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-368" ></span> |
| 20550 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20551 |
|
| 20552 |
|
| 20553 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20554 |
| | NFS4ERR_DENIED, NFS4ERR_EXPIRED, | |
| 20555 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | |
| 20556 |
| | NFS4ERR_INVAL, NFS4ERR_ISDIR, | |
| 20557 |
| | NFS4ERR_LOCK_NOTSUPP, NFS4ERR_LOCK_RANGE, | |
| 20558 |
| | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | |
| 20559 |
| | NFS4ERR_NO_GRACE, NFS4ERR_OLD_STATEID, | |
| 20560 |
| | NFS4ERR_OPENMODE, | |
| 20561 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20562 |
| | NFS4ERR_RECLAIM_BAD, | |
| 20563 |
| | NFS4ERR_RECLAIM_CONFLICT, | |
| 20564 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20565 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20566 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20567 |
| | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | |
| 20568 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20569 |
| | NFS4ERR_SYMLINK, NFS4ERR_TOO_MANY_OPS, | |
| 20570 |
| | NFS4ERR_WRONG_CRED, NFS4ERR_WRONG_TYPE | |
| 20571 |
| LOCKT | NFS4ERR_ACCESS, NFS4ERR_BADXDR, | |
| 20572 |
| | NFS4ERR_BAD_RANGE, NFS4ERR_DEADSESSION, | |
| 20573 |
| | NFS4ERR_DELAY, NFS4ERR_DENIED, | |
| 20574 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | |
| 20575 |
| | NFS4ERR_INVAL, NFS4ERR_ISDIR, | |
| 20576 |
| | NFS4ERR_LOCK_RANGE, NFS4ERR_MOVED, | |
| 20577 |
| | NFS4ERR_NOFILEHANDLE, | |
| 20578 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20579 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20580 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20581 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20582 |
| | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | |
| 20583 |
| | NFS4ERR_STALE, NFS4ERR_SYMLINK, | |
| 20584 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_CRED, | |
| 20585 |
| | NFS4ERR_WRONG_TYPE | |
| 20586 |
| LOCKU | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | |
| 20587 |
| | NFS4ERR_BADXDR, NFS4ERR_BAD_RANGE, | |
| 20588 |
| | NFS4ERR_BAD_STATEID, NFS4ERR_DEADSESSION, | |
| 20589 |
| | NFS4ERR_DELAY, NFS4ERR_EXPIRED, | |
| 20590 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | |
| 20591 |
| | NFS4ERR_LOCK_RANGE, NFS4ERR_MOVED, | |
| 20592 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_OLD_STATEID, | |
| 20593 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20594 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20595 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20596 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20597 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20598 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20599 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_CRED | |
| 20600 |
| LOOKUP | NFS4ERR_ACCESS, NFS4ERR_BADCHAR, | |
| 20601 |
|
| 20602 |
|
| 20603 |
|
| 20604 |
<span class="grey">Shepler, et al. Standards Track [Page 368]</span></pre> |
| 20605 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-369" ></span> |
| 20606 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20607 |
|
| 20608 |
|
| 20609 |
| | NFS4ERR_BADNAME, NFS4ERR_BADXDR, | |
| 20610 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20611 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | |
| 20612 |
| | NFS4ERR_IO, NFS4ERR_MOVED, | |
| 20613 |
| | NFS4ERR_NAMETOOLONG, NFS4ERR_NOENT, | |
| 20614 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTDIR, | |
| 20615 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20616 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20617 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20618 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20619 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20620 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20621 |
| | NFS4ERR_SYMLINK, NFS4ERR_TOO_MANY_OPS, | |
| 20622 |
| | NFS4ERR_WRONGSEC | |
| 20623 |
| LOOKUPP | NFS4ERR_ACCESS, NFS4ERR_DEADSESSION, | |
| 20624 |
| | NFS4ERR_DELAY, NFS4ERR_FHEXPIRED, | |
| 20625 |
| | NFS4ERR_IO, NFS4ERR_MOVED, NFS4ERR_NOENT, | |
| 20626 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTDIR, | |
| 20627 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20628 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20629 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20630 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20631 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20632 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20633 |
| | NFS4ERR_SYMLINK, NFS4ERR_TOO_MANY_OPS, | |
| 20634 |
| | NFS4ERR_WRONGSEC | |
| 20635 |
| NVERIFY | NFS4ERR_ACCESS, NFS4ERR_ATTRNOTSUPP, | |
| 20636 |
| | NFS4ERR_BADCHAR, NFS4ERR_BADXDR, | |
| 20637 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20638 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | |
| 20639 |
| | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | |
| 20640 |
| | NFS4ERR_NOFILEHANDLE, | |
| 20641 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20642 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20643 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20644 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20645 |
| | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_SAME, | |
| 20646 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20647 |
| | NFS4ERR_TOO_MANY_OPS, | |
| 20648 |
| | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |
| 20649 |
| | NFS4ERR_WRONG_TYPE | |
| 20650 |
| OPEN | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | |
| 20651 |
| | NFS4ERR_ATTRNOTSUPP, NFS4ERR_BADCHAR, | |
| 20652 |
| | NFS4ERR_BADNAME, NFS4ERR_BADOWNER, | |
| 20653 |
| | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, | |
| 20654 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20655 |
| | NFS4ERR_DELEG_ALREADY_WANTED, | |
| 20656 |
| | NFS4ERR_DELEG_REVOKED, NFS4ERR_DQUOT, | |
| 20657 |
|
| 20658 |
|
| 20659 |
|
| 20660 |
<span class="grey">Shepler, et al. Standards Track [Page 369]</span></pre> |
| 20661 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-370" ></span> |
| 20662 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20663 |
|
| 20664 |
|
| 20665 |
| | NFS4ERR_EXIST, NFS4ERR_EXPIRED, | |
| 20666 |
| | NFS4ERR_FBIG, NFS4ERR_FHEXPIRED, | |
| 20667 |
| | NFS4ERR_GRACE, NFS4ERR_INVAL, | |
| 20668 |
| | NFS4ERR_ISDIR, NFS4ERR_IO, NFS4ERR_MOVED, | |
| 20669 |
| | NFS4ERR_NAMETOOLONG, NFS4ERR_NOENT, | |
| 20670 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | |
| 20671 |
| | NFS4ERR_NOTDIR, NFS4ERR_NO_GRACE, | |
| 20672 |
| | NFS4ERR_OLD_STATEID, | |
| 20673 |
| | NFS4ERR_OP_NOT_IN_SESSION, NFS4ERR_PERM, | |
| 20674 |
| | NFS4ERR_RECLAIM_BAD, | |
| 20675 |
| | NFS4ERR_RECLAIM_CONFLICT, | |
| 20676 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20677 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20678 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20679 |
| | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | |
| 20680 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_SHARE_DENIED, | |
| 20681 |
| | NFS4ERR_STALE, NFS4ERR_SYMLINK, | |
| 20682 |
| | NFS4ERR_TOO_MANY_OPS, | |
| 20683 |
| | NFS4ERR_UNSAFE_COMPOUND, NFS4ERR_WRONGSEC, | |
| 20684 |
| | NFS4ERR_WRONG_TYPE | |
| 20685 |
| OPEN_CONFIRM | NFS4ERR_NOTSUPP | |
| 20686 |
| OPEN_DOWNGRADE | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADXDR, | |
| 20687 |
| | NFS4ERR_BAD_STATEID, NFS4ERR_DEADSESSION, | |
| 20688 |
| | NFS4ERR_DELAY, NFS4ERR_EXPIRED, | |
| 20689 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | |
| 20690 |
| | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | |
| 20691 |
| | NFS4ERR_OLD_STATEID, | |
| 20692 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20693 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20694 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20695 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20696 |
| | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | |
| 20697 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20698 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_CRED | |
| 20699 |
| OPENATTR | NFS4ERR_ACCESS, NFS4ERR_BADXDR, | |
| 20700 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20701 |
| | NFS4ERR_DQUOT, NFS4ERR_FHEXPIRED, | |
| 20702 |
| | NFS4ERR_IO, NFS4ERR_MOVED, NFS4ERR_NOENT, | |
| 20703 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | |
| 20704 |
| | NFS4ERR_NOTSUPP, | |
| 20705 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20706 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20707 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20708 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20709 |
| | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | |
| 20710 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20711 |
| | NFS4ERR_TOO_MANY_OPS, | |
| 20712 |
| | NFS4ERR_UNSAFE_COMPOUND, | |
| 20713 |
|
| 20714 |
|
| 20715 |
|
| 20716 |
<span class="grey">Shepler, et al. Standards Track [Page 370]</span></pre> |
| 20717 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-371" ></span> |
| 20718 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20719 |
|
| 20720 |
|
| 20721 |
| | NFS4ERR_WRONG_TYPE | |
| 20722 |
| PUTFH | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, | |
| 20723 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20724 |
| | NFS4ERR_MOVED, NFS4ERR_OP_NOT_IN_SESSION, | |
| 20725 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20726 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20727 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20728 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20729 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20730 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONGSEC | |
| 20731 |
| PUTPUBFH | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20732 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20733 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20734 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20735 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20736 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20737 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_TOO_MANY_OPS, | |
| 20738 |
| | NFS4ERR_WRONGSEC | |
| 20739 |
| PUTROOTFH | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20740 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20741 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20742 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20743 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20744 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20745 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_TOO_MANY_OPS, | |
| 20746 |
| | NFS4ERR_WRONGSEC | |
| 20747 |
| READ | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | |
| 20748 |
| | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, | |
| 20749 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20750 |
| | NFS4ERR_DELEG_REVOKED, NFS4ERR_EXPIRED, | |
| 20751 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | |
| 20752 |
| | NFS4ERR_INVAL, NFS4ERR_ISDIR, NFS4ERR_IO, | |
| 20753 |
| | NFS4ERR_LOCKED, NFS4ERR_MOVED, | |
| 20754 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_OLD_STATEID, | |
| 20755 |
| | NFS4ERR_OPENMODE, | |
| 20756 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20757 |
| | NFS4ERR_PNFS_IO_HOLE, | |
| 20758 |
| | NFS4ERR_PNFS_NO_LAYOUT, | |
| 20759 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20760 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20761 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20762 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20763 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20764 |
| | NFS4ERR_SYMLINK, NFS4ERR_TOO_MANY_OPS, | |
| 20765 |
| | NFS4ERR_WRONG_TYPE | |
| 20766 |
| READDIR | NFS4ERR_ACCESS, NFS4ERR_BADXDR, | |
| 20767 |
| | NFS4ERR_BAD_COOKIE, NFS4ERR_DEADSESSION, | |
| 20768 |
| | NFS4ERR_DELAY, NFS4ERR_FHEXPIRED, | |
| 20769 |
|
| 20770 |
|
| 20771 |
|
| 20772 |
<span class="grey">Shepler, et al. Standards Track [Page 371]</span></pre> |
| 20773 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-372" ></span> |
| 20774 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20775 |
|
| 20776 |
|
| 20777 |
| | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | |
| 20778 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTDIR, | |
| 20779 |
| | NFS4ERR_NOT_SAME, | |
| 20780 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20781 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20782 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20783 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20784 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20785 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20786 |
| | NFS4ERR_TOOSMALL, NFS4ERR_TOO_MANY_OPS | |
| 20787 |
| READLINK | NFS4ERR_ACCESS, NFS4ERR_DEADSESSION, | |
| 20788 |
| | NFS4ERR_DELAY, NFS4ERR_FHEXPIRED, | |
| 20789 |
| | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | |
| 20790 |
| | NFS4ERR_NOFILEHANDLE, | |
| 20791 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20792 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20793 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20794 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20795 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20796 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20797 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE | |
| 20798 |
| RECLAIM_COMPLETE | NFS4ERR_BADXDR, NFS4ERR_COMPLETE_ALREADY, | |
| 20799 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20800 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | |
| 20801 |
| | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | |
| 20802 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20803 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20804 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20805 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20806 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20807 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20808 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_CRED, | |
| 20809 |
| | NFS4ERR_WRONG_TYPE | |
| 20810 |
| RELEASE_LOCKOWNER | NFS4ERR_NOTSUPP | |
| 20811 |
| REMOVE | NFS4ERR_ACCESS, NFS4ERR_BADCHAR, | |
| 20812 |
| | NFS4ERR_BADNAME, NFS4ERR_BADXDR, | |
| 20813 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20814 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_FILE_OPEN, | |
| 20815 |
| | NFS4ERR_GRACE, NFS4ERR_INVAL, NFS4ERR_IO, | |
| 20816 |
| | NFS4ERR_MOVED, NFS4ERR_NAMETOOLONG, | |
| 20817 |
| | NFS4ERR_NOENT, NFS4ERR_NOFILEHANDLE, | |
| 20818 |
| | NFS4ERR_NOTDIR, NFS4ERR_NOTEMPTY, | |
| 20819 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20820 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20821 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20822 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20823 |
| | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | |
| 20824 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20825 |
|
| 20826 |
|
| 20827 |
|
| 20828 |
<span class="grey">Shepler, et al. Standards Track [Page 372]</span></pre> |
| 20829 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-373" ></span> |
| 20830 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20831 |
|
| 20832 |
|
| 20833 |
| | NFS4ERR_TOO_MANY_OPS | |
| 20834 |
| RENAME | NFS4ERR_ACCESS, NFS4ERR_BADCHAR, | |
| 20835 |
| | NFS4ERR_BADNAME, NFS4ERR_BADXDR, | |
| 20836 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20837 |
| | NFS4ERR_DQUOT, NFS4ERR_EXIST, | |
| 20838 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_FILE_OPEN, | |
| 20839 |
| | NFS4ERR_GRACE, NFS4ERR_INVAL, NFS4ERR_IO, | |
| 20840 |
| | NFS4ERR_MLINK, NFS4ERR_MOVED, | |
| 20841 |
| | NFS4ERR_NAMETOOLONG, NFS4ERR_NOENT, | |
| 20842 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | |
| 20843 |
| | NFS4ERR_NOTDIR, NFS4ERR_NOTEMPTY, | |
| 20844 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20845 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20846 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20847 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20848 |
| | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | |
| 20849 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20850 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONGSEC, | |
| 20851 |
| | NFS4ERR_XDEV | |
| 20852 |
| RENEW | NFS4ERR_NOTSUPP | |
| 20853 |
| RESTOREFH | NFS4ERR_DEADSESSION, NFS4ERR_FHEXPIRED, | |
| 20854 |
| | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | |
| 20855 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20856 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20857 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20858 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20859 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20860 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20861 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONGSEC | |
| 20862 |
| SAVEFH | NFS4ERR_DEADSESSION, NFS4ERR_FHEXPIRED, | |
| 20863 |
| | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, | |
| 20864 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20865 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20866 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20867 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20868 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20869 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20870 |
| | NFS4ERR_TOO_MANY_OPS | |
| 20871 |
| SECINFO | NFS4ERR_ACCESS, NFS4ERR_BADCHAR, | |
| 20872 |
| | NFS4ERR_BADNAME, NFS4ERR_BADXDR, | |
| 20873 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20874 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | |
| 20875 |
| | NFS4ERR_MOVED, NFS4ERR_NAMETOOLONG, | |
| 20876 |
| | NFS4ERR_NOENT, NFS4ERR_NOFILEHANDLE, | |
| 20877 |
| | NFS4ERR_NOTDIR, NFS4ERR_OP_NOT_IN_SESSION, | |
| 20878 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20879 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20880 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20881 |
|
| 20882 |
|
| 20883 |
|
| 20884 |
<span class="grey">Shepler, et al. Standards Track [Page 373]</span></pre> |
| 20885 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-374" ></span> |
| 20886 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20887 |
|
| 20888 |
|
| 20889 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20890 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20891 |
| | NFS4ERR_TOO_MANY_OPS | |
| 20892 |
| SECINFO_NO_NAME | NFS4ERR_ACCESS, NFS4ERR_BADXDR, | |
| 20893 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20894 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | |
| 20895 |
| | NFS4ERR_MOVED, NFS4ERR_NOENT, | |
| 20896 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTDIR, | |
| 20897 |
| | NFS4ERR_NOTSUPP, | |
| 20898 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20899 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20900 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20901 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20902 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20903 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20904 |
| | NFS4ERR_TOO_MANY_OPS | |
| 20905 |
| SEQUENCE | NFS4ERR_BADSESSION, NFS4ERR_BADSLOT, | |
| 20906 |
| | NFS4ERR_BADXDR, NFS4ERR_BAD_HIGH_SLOT, | |
| 20907 |
| | NFS4ERR_CONN_NOT_BOUND_TO_SESSION, | |
| 20908 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20909 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20910 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20911 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20912 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20913 |
| | NFS4ERR_SEQUENCE_POS, | |
| 20914 |
| | NFS4ERR_SEQ_FALSE_RETRY, | |
| 20915 |
| | NFS4ERR_SEQ_MISORDERED, | |
| 20916 |
| | NFS4ERR_TOO_MANY_OPS | |
| 20917 |
| SET_SSV | NFS4ERR_BADXDR, | |
| 20918 |
| | NFS4ERR_BAD_SESSION_DIGEST, | |
| 20919 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20920 |
| | NFS4ERR_INVAL, NFS4ERR_OP_NOT_IN_SESSION, | |
| 20921 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20922 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20923 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20924 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20925 |
| | NFS4ERR_TOO_MANY_OPS | |
| 20926 |
| SETATTR | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | |
| 20927 |
| | NFS4ERR_ATTRNOTSUPP, NFS4ERR_BADCHAR, | |
| 20928 |
| | NFS4ERR_BADOWNER, NFS4ERR_BADXDR, | |
| 20929 |
| | NFS4ERR_BAD_STATEID, NFS4ERR_DEADSESSION, | |
| 20930 |
| | NFS4ERR_DELAY, NFS4ERR_DELEG_REVOKED, | |
| 20931 |
| | NFS4ERR_DQUOT, NFS4ERR_EXPIRED, | |
| 20932 |
| | NFS4ERR_FBIG, NFS4ERR_FHEXPIRED, | |
| 20933 |
| | NFS4ERR_GRACE, NFS4ERR_INVAL, NFS4ERR_IO, | |
| 20934 |
| | NFS4ERR_LOCKED, NFS4ERR_MOVED, | |
| 20935 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | |
| 20936 |
| | NFS4ERR_OLD_STATEID, NFS4ERR_OPENMODE, | |
| 20937 |
|
| 20938 |
|
| 20939 |
|
| 20940 |
<span class="grey">Shepler, et al. Standards Track [Page 374]</span></pre> |
| 20941 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-375" ></span> |
| 20942 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20943 |
|
| 20944 |
|
| 20945 |
| | NFS4ERR_OP_NOT_IN_SESSION, NFS4ERR_PERM, | |
| 20946 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20947 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20948 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20949 |
| | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | |
| 20950 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20951 |
| | NFS4ERR_TOO_MANY_OPS, | |
| 20952 |
| | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |
| 20953 |
| | NFS4ERR_WRONG_TYPE | |
| 20954 |
| SETCLIENTID | NFS4ERR_NOTSUPP | |
| 20955 |
| SETCLIENTID_CONFIRM | NFS4ERR_NOTSUPP | |
| 20956 |
| TEST_STATEID | NFS4ERR_BADXDR, NFS4ERR_DEADSESSION, | |
| 20957 |
| | NFS4ERR_DELAY, NFS4ERR_OP_NOT_IN_SESSION, | |
| 20958 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20959 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20960 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20961 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20962 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_TOO_MANY_OPS | |
| 20963 |
| VERIFY | NFS4ERR_ACCESS, NFS4ERR_ATTRNOTSUPP, | |
| 20964 |
| | NFS4ERR_BADCHAR, NFS4ERR_BADXDR, | |
| 20965 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 20966 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | |
| 20967 |
| | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | |
| 20968 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOT_SAME, | |
| 20969 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20970 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20971 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20972 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20973 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20974 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 20975 |
| | NFS4ERR_TOO_MANY_OPS, | |
| 20976 |
| | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |
| 20977 |
| | NFS4ERR_WRONG_TYPE | |
| 20978 |
| WANT_DELEGATION | NFS4ERR_BADXDR, NFS4ERR_DEADSESSION, | |
| 20979 |
| | NFS4ERR_DELAY, | |
| 20980 |
| | NFS4ERR_DELEG_ALREADY_WANTED, | |
| 20981 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | |
| 20982 |
| | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | |
| 20983 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTSUPP, | |
| 20984 |
| | NFS4ERR_NO_GRACE, | |
| 20985 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 20986 |
| | NFS4ERR_RECALLCONFLICT, | |
| 20987 |
| | NFS4ERR_RECLAIM_BAD, | |
| 20988 |
| | NFS4ERR_RECLAIM_CONFLICT, | |
| 20989 |
| | NFS4ERR_REP_TOO_BIG, | |
| 20990 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 20991 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 20992 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 20993 |
|
| 20994 |
|
| 20995 |
|
| 20996 |
<span class="grey">Shepler, et al. Standards Track [Page 375]</span></pre> |
| 20997 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-376" ></span> |
| 20998 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 20999 |
|
| 21000 |
|
| 21001 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 21002 |
| | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE | |
| 21003 |
| WRITE | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | |
| 21004 |
| | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, | |
| 21005 |
| | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | |
| 21006 |
| | NFS4ERR_DELEG_REVOKED, NFS4ERR_DQUOT, | |
| 21007 |
| | NFS4ERR_EXPIRED, NFS4ERR_FBIG, | |
| 21008 |
| | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | |
| 21009 |
| | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_ISDIR, | |
| 21010 |
| | NFS4ERR_LOCKED, NFS4ERR_MOVED, | |
| 21011 |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | |
| 21012 |
| | NFS4ERR_OLD_STATEID, NFS4ERR_OPENMODE, | |
| 21013 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 21014 |
| | NFS4ERR_PNFS_IO_HOLE, | |
| 21015 |
| | NFS4ERR_PNFS_NO_LAYOUT, | |
| 21016 |
| | NFS4ERR_REP_TOO_BIG, | |
| 21017 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21018 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21019 |
| | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | |
| 21020 |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | |
| 21021 |
| | NFS4ERR_SYMLINK, NFS4ERR_TOO_MANY_OPS, | |
| 21022 |
| | NFS4ERR_WRONG_TYPE | |
| 21023 |
+----------------------+--------------------------------------------+ |
| 21024 |
|
| 21025 |
Table 6 |
| 21026 |
|
| 21027 |
<span class="h3"><a class="selflink" id="section-15.3" href="#section-15.3">15.3</a>. Callback Operations and Their Valid Errors</span> |
| 21028 |
|
| 21029 |
This section contains a table that gives the valid error returns for |
| 21030 |
each callback operation. The error code NFS4_OK (indicating no |
| 21031 |
error) is not listed but should be understood to be returnable by all |
| 21032 |
callback operations with the exception of CB_ILLEGAL. |
| 21033 |
|
| 21034 |
Valid Error Returns for Each Protocol Callback Operation |
| 21035 |
|
| 21036 |
+-------------------------+-----------------------------------------+ |
| 21037 |
| Callback Operation | Errors | |
| 21038 |
+-------------------------+-----------------------------------------+ |
| 21039 |
| CB_GETATTR | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, | |
| 21040 |
| | NFS4ERR_DELAY, NFS4ERR_INVAL, | |
| 21041 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 21042 |
| | NFS4ERR_REP_TOO_BIG, | |
| 21043 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21044 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21045 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 21046 |
| | NFS4ERR_SERVERFAULT, | |
| 21047 |
| | NFS4ERR_TOO_MANY_OPS, | |
| 21048 |
| CB_ILLEGAL | NFS4ERR_BADXDR, NFS4ERR_OP_ILLEGAL | |
| 21049 |
|
| 21050 |
|
| 21051 |
|
| 21052 |
<span class="grey">Shepler, et al. Standards Track [Page 376]</span></pre> |
| 21053 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-377" ></span> |
| 21054 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21055 |
|
| 21056 |
|
| 21057 |
| CB_LAYOUTRECALL | NFS4ERR_BADHANDLE, NFS4ERR_BADIOMODE, | |
| 21058 |
| | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, | |
| 21059 |
| | NFS4ERR_DELAY, NFS4ERR_INVAL, | |
| 21060 |
| | NFS4ERR_NOMATCHING_LAYOUT, | |
| 21061 |
| | NFS4ERR_NOTSUPP, | |
| 21062 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 21063 |
| | NFS4ERR_REP_TOO_BIG, | |
| 21064 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21065 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21066 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 21067 |
| | NFS4ERR_TOO_MANY_OPS, | |
| 21068 |
| | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |
| 21069 |
| | NFS4ERR_WRONG_TYPE | |
| 21070 |
| CB_NOTIFY | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, | |
| 21071 |
| | NFS4ERR_BAD_STATEID, NFS4ERR_DELAY, | |
| 21072 |
| | NFS4ERR_INVAL, NFS4ERR_NOTSUPP, | |
| 21073 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 21074 |
| | NFS4ERR_REP_TOO_BIG, | |
| 21075 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21076 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21077 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 21078 |
| | NFS4ERR_SERVERFAULT, | |
| 21079 |
| | NFS4ERR_TOO_MANY_OPS | |
| 21080 |
| CB_NOTIFY_DEVICEID | NFS4ERR_BADXDR, NFS4ERR_DELAY, | |
| 21081 |
| | NFS4ERR_INVAL, NFS4ERR_NOTSUPP, | |
| 21082 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 21083 |
| | NFS4ERR_REP_TOO_BIG, | |
| 21084 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21085 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21086 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 21087 |
| | NFS4ERR_SERVERFAULT, | |
| 21088 |
| | NFS4ERR_TOO_MANY_OPS | |
| 21089 |
| CB_NOTIFY_LOCK | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, | |
| 21090 |
| | NFS4ERR_BAD_STATEID, NFS4ERR_DELAY, | |
| 21091 |
| | NFS4ERR_NOTSUPP, | |
| 21092 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 21093 |
| | NFS4ERR_REP_TOO_BIG, | |
| 21094 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21095 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21096 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 21097 |
| | NFS4ERR_SERVERFAULT, | |
| 21098 |
| | NFS4ERR_TOO_MANY_OPS | |
| 21099 |
| CB_PUSH_DELEG | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, | |
| 21100 |
| | NFS4ERR_DELAY, NFS4ERR_INVAL, | |
| 21101 |
| | NFS4ERR_NOTSUPP, | |
| 21102 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 21103 |
| | NFS4ERR_REJECT_DELEG, | |
| 21104 |
| | NFS4ERR_REP_TOO_BIG, | |
| 21105 |
|
| 21106 |
|
| 21107 |
|
| 21108 |
<span class="grey">Shepler, et al. Standards Track [Page 377]</span></pre> |
| 21109 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-378" ></span> |
| 21110 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21111 |
|
| 21112 |
|
| 21113 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21114 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21115 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 21116 |
| | NFS4ERR_SERVERFAULT, | |
| 21117 |
| | NFS4ERR_TOO_MANY_OPS, | |
| 21118 |
| | NFS4ERR_WRONG_TYPE | |
| 21119 |
| CB_RECALL | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, | |
| 21120 |
| | NFS4ERR_BAD_STATEID, NFS4ERR_DELAY, | |
| 21121 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 21122 |
| | NFS4ERR_REP_TOO_BIG, | |
| 21123 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21124 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21125 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 21126 |
| | NFS4ERR_SERVERFAULT, | |
| 21127 |
| | NFS4ERR_TOO_MANY_OPS | |
| 21128 |
| CB_RECALL_ANY | NFS4ERR_BADXDR, NFS4ERR_DELAY, | |
| 21129 |
| | NFS4ERR_INVAL, | |
| 21130 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 21131 |
| | NFS4ERR_REP_TOO_BIG, | |
| 21132 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21133 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21134 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 21135 |
| | NFS4ERR_TOO_MANY_OPS | |
| 21136 |
| CB_RECALLABLE_OBJ_AVAIL | NFS4ERR_BADXDR, NFS4ERR_DELAY, | |
| 21137 |
| | NFS4ERR_INVAL, NFS4ERR_NOTSUPP, | |
| 21138 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 21139 |
| | NFS4ERR_REP_TOO_BIG, | |
| 21140 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21141 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21142 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 21143 |
| | NFS4ERR_SERVERFAULT, | |
| 21144 |
| | NFS4ERR_TOO_MANY_OPS | |
| 21145 |
| CB_RECALL_SLOT | NFS4ERR_BADXDR, NFS4ERR_BAD_HIGH_SLOT, | |
| 21146 |
| | NFS4ERR_DELAY, | |
| 21147 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 21148 |
| | NFS4ERR_REP_TOO_BIG, | |
| 21149 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21150 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21151 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 21152 |
| | NFS4ERR_TOO_MANY_OPS | |
| 21153 |
| CB_SEQUENCE | NFS4ERR_BADSESSION, NFS4ERR_BADSLOT, | |
| 21154 |
| | NFS4ERR_BADXDR, NFS4ERR_BAD_HIGH_SLOT, | |
| 21155 |
| | NFS4ERR_CONN_NOT_BOUND_TO_SESSION, | |
| 21156 |
| | NFS4ERR_DELAY, NFS4ERR_REP_TOO_BIG, | |
| 21157 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21158 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21159 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 21160 |
| | NFS4ERR_SEQUENCE_POS, | |
| 21161 |
|
| 21162 |
|
| 21163 |
|
| 21164 |
<span class="grey">Shepler, et al. Standards Track [Page 378]</span></pre> |
| 21165 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-379" ></span> |
| 21166 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21167 |
|
| 21168 |
|
| 21169 |
| | NFS4ERR_SEQ_FALSE_RETRY, | |
| 21170 |
| | NFS4ERR_SEQ_MISORDERED, | |
| 21171 |
| | NFS4ERR_TOO_MANY_OPS | |
| 21172 |
| CB_WANTS_CANCELLED | NFS4ERR_BADXDR, NFS4ERR_DELAY, | |
| 21173 |
| | NFS4ERR_NOTSUPP, | |
| 21174 |
| | NFS4ERR_OP_NOT_IN_SESSION, | |
| 21175 |
| | NFS4ERR_REP_TOO_BIG, | |
| 21176 |
| | NFS4ERR_REP_TOO_BIG_TO_CACHE, | |
| 21177 |
| | NFS4ERR_REQ_TOO_BIG, | |
| 21178 |
| | NFS4ERR_RETRY_UNCACHED_REP, | |
| 21179 |
| | NFS4ERR_SERVERFAULT, | |
| 21180 |
| | NFS4ERR_TOO_MANY_OPS | |
| 21181 |
+-------------------------+-----------------------------------------+ |
| 21182 |
|
| 21183 |
Table 7 |
| 21184 |
|
| 21185 |
<span class="h3"><a class="selflink" id="section-15.4" href="#section-15.4">15.4</a>. Errors and the Operations That Use Them</span> |
| 21186 |
|
| 21187 |
+-----------------------------------+-------------------------------+ |
| 21188 |
| Error | Operations | |
| 21189 |
+-----------------------------------+-------------------------------+ |
| 21190 |
| NFS4ERR_ACCESS | ACCESS, COMMIT, CREATE, | |
| 21191 |
| | GETATTR, GET_DIR_DELEGATION, | |
| 21192 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21193 |
| | LINK, LOCK, LOCKT, LOCKU, | |
| 21194 |
| | LOOKUP, LOOKUPP, NVERIFY, | |
| 21195 |
| | OPEN, OPENATTR, READ, | |
| 21196 |
| | READDIR, READLINK, REMOVE, | |
| 21197 |
| | RENAME, SECINFO, | |
| 21198 |
| | SECINFO_NO_NAME, SETATTR, | |
| 21199 |
| | VERIFY, WRITE | |
| 21200 |
| NFS4ERR_ADMIN_REVOKED | CLOSE, DELEGRETURN, | |
| 21201 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21202 |
| | LAYOUTRETURN, LOCK, LOCKU, | |
| 21203 |
| | OPEN, OPEN_DOWNGRADE, READ, | |
| 21204 |
| | SETATTR, WRITE | |
| 21205 |
| NFS4ERR_ATTRNOTSUPP | CREATE, LAYOUTCOMMIT, | |
| 21206 |
| | NVERIFY, OPEN, SETATTR, | |
| 21207 |
| | VERIFY | |
| 21208 |
| NFS4ERR_BACK_CHAN_BUSY | DESTROY_SESSION | |
| 21209 |
| NFS4ERR_BADCHAR | CREATE, EXCHANGE_ID, LINK, | |
| 21210 |
| | LOOKUP, NVERIFY, OPEN, | |
| 21211 |
| | REMOVE, RENAME, SECINFO, | |
| 21212 |
| | SETATTR, VERIFY | |
| 21213 |
| NFS4ERR_BADHANDLE | CB_GETATTR, CB_LAYOUTRECALL, | |
| 21214 |
| | CB_NOTIFY, CB_NOTIFY_LOCK, | |
| 21215 |
| | CB_PUSH_DELEG, CB_RECALL, | |
| 21216 |
| | PUTFH | |
| 21217 |
|
| 21218 |
|
| 21219 |
|
| 21220 |
<span class="grey">Shepler, et al. Standards Track [Page 379]</span></pre> |
| 21221 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-380" ></span> |
| 21222 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21223 |
|
| 21224 |
|
| 21225 |
| NFS4ERR_BADIOMODE | CB_LAYOUTRECALL, | |
| 21226 |
| | LAYOUTCOMMIT, LAYOUTGET | |
| 21227 |
| NFS4ERR_BADLAYOUT | LAYOUTCOMMIT, LAYOUTGET | |
| 21228 |
| NFS4ERR_BADNAME | CREATE, LINK, LOOKUP, OPEN, | |
| 21229 |
| | REMOVE, RENAME, SECINFO | |
| 21230 |
| NFS4ERR_BADOWNER | CREATE, OPEN, SETATTR | |
| 21231 |
| NFS4ERR_BADSESSION | BIND_CONN_TO_SESSION, | |
| 21232 |
| | CB_SEQUENCE, DESTROY_SESSION, | |
| 21233 |
| | SEQUENCE | |
| 21234 |
| NFS4ERR_BADSLOT | CB_SEQUENCE, SEQUENCE | |
| 21235 |
| NFS4ERR_BADTYPE | CREATE | |
| 21236 |
| NFS4ERR_BADXDR | ACCESS, BACKCHANNEL_CTL, | |
| 21237 |
| | BIND_CONN_TO_SESSION, | |
| 21238 |
| | CB_GETATTR, CB_ILLEGAL, | |
| 21239 |
| | CB_LAYOUTRECALL, CB_NOTIFY, | |
| 21240 |
| | CB_NOTIFY_DEVICEID, | |
| 21241 |
| | CB_NOTIFY_LOCK, | |
| 21242 |
| | CB_PUSH_DELEG, CB_RECALL, | |
| 21243 |
| | CB_RECALLABLE_OBJ_AVAIL, | |
| 21244 |
| | CB_RECALL_ANY, | |
| 21245 |
| | CB_RECALL_SLOT, CB_SEQUENCE, | |
| 21246 |
| | CB_WANTS_CANCELLED, CLOSE, | |
| 21247 |
| | COMMIT, CREATE, | |
| 21248 |
| | CREATE_SESSION, DELEGPURGE, | |
| 21249 |
| | DELEGRETURN, | |
| 21250 |
| | DESTROY_CLIENTID, | |
| 21251 |
| | DESTROY_SESSION, EXCHANGE_ID, | |
| 21252 |
| | FREE_STATEID, GETATTR, | |
| 21253 |
| | GETDEVICEINFO, GETDEVICELIST, | |
| 21254 |
| | GET_DIR_DELEGATION, ILLEGAL, | |
| 21255 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21256 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21257 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21258 |
| | NVERIFY, OPEN, OPENATTR, | |
| 21259 |
| | OPEN_DOWNGRADE, PUTFH, READ, | |
| 21260 |
| | READDIR, RECLAIM_COMPLETE, | |
| 21261 |
| | REMOVE, RENAME, SECINFO, | |
| 21262 |
| | SECINFO_NO_NAME, SEQUENCE, | |
| 21263 |
| | SETATTR, SET_SSV, | |
| 21264 |
| | TEST_STATEID, VERIFY, | |
| 21265 |
| | WANT_DELEGATION, WRITE | |
| 21266 |
| NFS4ERR_BAD_COOKIE | GETDEVICELIST, READDIR | |
| 21267 |
| NFS4ERR_BAD_HIGH_SLOT | CB_RECALL_SLOT, CB_SEQUENCE, | |
| 21268 |
| | SEQUENCE | |
| 21269 |
| NFS4ERR_BAD_RANGE | LOCK, LOCKT, LOCKU | |
| 21270 |
| NFS4ERR_BAD_SESSION_DIGEST | BIND_CONN_TO_SESSION, SET_SSV | |
| 21271 |
| NFS4ERR_BAD_STATEID | CB_LAYOUTRECALL, CB_NOTIFY, | |
| 21272 |
| | CB_NOTIFY_LOCK, CB_RECALL, | |
| 21273 |
|
| 21274 |
|
| 21275 |
|
| 21276 |
<span class="grey">Shepler, et al. Standards Track [Page 380]</span></pre> |
| 21277 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-381" ></span> |
| 21278 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21279 |
|
| 21280 |
|
| 21281 |
| | CLOSE, DELEGRETURN, | |
| 21282 |
| | FREE_STATEID, LAYOUTGET, | |
| 21283 |
| | LAYOUTRETURN, LOCK, LOCKU, | |
| 21284 |
| | OPEN, OPEN_DOWNGRADE, READ, | |
| 21285 |
| | SETATTR, WRITE | |
| 21286 |
| NFS4ERR_CB_PATH_DOWN | DESTROY_SESSION | |
| 21287 |
| NFS4ERR_CLID_INUSE | CREATE_SESSION, EXCHANGE_ID | |
| 21288 |
| NFS4ERR_CLIENTID_BUSY | DESTROY_CLIENTID | |
| 21289 |
| NFS4ERR_COMPLETE_ALREADY | RECLAIM_COMPLETE | |
| 21290 |
| NFS4ERR_CONN_NOT_BOUND_TO_SESSION | CB_SEQUENCE, DESTROY_SESSION, | |
| 21291 |
| | SEQUENCE | |
| 21292 |
| NFS4ERR_DEADLOCK | LOCK | |
| 21293 |
| NFS4ERR_DEADSESSION | ACCESS, BACKCHANNEL_CTL, | |
| 21294 |
| | BIND_CONN_TO_SESSION, CLOSE, | |
| 21295 |
| | COMMIT, CREATE, | |
| 21296 |
| | CREATE_SESSION, DELEGPURGE, | |
| 21297 |
| | DELEGRETURN, | |
| 21298 |
| | DESTROY_CLIENTID, | |
| 21299 |
| | DESTROY_SESSION, EXCHANGE_ID, | |
| 21300 |
| | FREE_STATEID, GETATTR, | |
| 21301 |
| | GETDEVICEINFO, GETDEVICELIST, | |
| 21302 |
| | GET_DIR_DELEGATION, | |
| 21303 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21304 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21305 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21306 |
| | LOOKUPP, NVERIFY, OPEN, | |
| 21307 |
| | OPENATTR, OPEN_DOWNGRADE, | |
| 21308 |
| | PUTFH, PUTPUBFH, PUTROOTFH, | |
| 21309 |
| | READ, READDIR, READLINK, | |
| 21310 |
| | RECLAIM_COMPLETE, REMOVE, | |
| 21311 |
| | RENAME, RESTOREFH, SAVEFH, | |
| 21312 |
| | SECINFO, SECINFO_NO_NAME, | |
| 21313 |
| | SEQUENCE, SETATTR, SET_SSV, | |
| 21314 |
| | TEST_STATEID, VERIFY, | |
| 21315 |
| | WANT_DELEGATION, WRITE | |
| 21316 |
| NFS4ERR_DELAY | ACCESS, BACKCHANNEL_CTL, | |
| 21317 |
| | BIND_CONN_TO_SESSION, | |
| 21318 |
| | CB_GETATTR, CB_LAYOUTRECALL, | |
| 21319 |
| | CB_NOTIFY, | |
| 21320 |
| | CB_NOTIFY_DEVICEID, | |
| 21321 |
| | CB_NOTIFY_LOCK, | |
| 21322 |
| | CB_PUSH_DELEG, CB_RECALL, | |
| 21323 |
| | CB_RECALLABLE_OBJ_AVAIL, | |
| 21324 |
| | CB_RECALL_ANY, | |
| 21325 |
| | CB_RECALL_SLOT, CB_SEQUENCE, | |
| 21326 |
| | CB_WANTS_CANCELLED, CLOSE, | |
| 21327 |
| | COMMIT, CREATE, | |
| 21328 |
| | CREATE_SESSION, DELEGPURGE, | |
| 21329 |
|
| 21330 |
|
| 21331 |
|
| 21332 |
<span class="grey">Shepler, et al. Standards Track [Page 381]</span></pre> |
| 21333 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-382" ></span> |
| 21334 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21335 |
|
| 21336 |
|
| 21337 |
| | DELEGRETURN, | |
| 21338 |
| | DESTROY_CLIENTID, | |
| 21339 |
| | DESTROY_SESSION, EXCHANGE_ID, | |
| 21340 |
| | FREE_STATEID, GETATTR, | |
| 21341 |
| | GETDEVICEINFO, GETDEVICELIST, | |
| 21342 |
| | GET_DIR_DELEGATION, | |
| 21343 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21344 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21345 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21346 |
| | LOOKUPP, NVERIFY, OPEN, | |
| 21347 |
| | OPENATTR, OPEN_DOWNGRADE, | |
| 21348 |
| | PUTFH, PUTPUBFH, PUTROOTFH, | |
| 21349 |
| | READ, READDIR, READLINK, | |
| 21350 |
| | RECLAIM_COMPLETE, REMOVE, | |
| 21351 |
| | RENAME, SECINFO, | |
| 21352 |
| | SECINFO_NO_NAME, SEQUENCE, | |
| 21353 |
| | SETATTR, SET_SSV, | |
| 21354 |
| | TEST_STATEID, VERIFY, | |
| 21355 |
| | WANT_DELEGATION, WRITE | |
| 21356 |
| NFS4ERR_DELEG_ALREADY_WANTED | OPEN, WANT_DELEGATION | |
| 21357 |
| NFS4ERR_DELEG_REVOKED | DELEGRETURN, LAYOUTCOMMIT, | |
| 21358 |
| | LAYOUTGET, LAYOUTRETURN, | |
| 21359 |
| | OPEN, READ, SETATTR, WRITE | |
| 21360 |
| NFS4ERR_DENIED | LOCK, LOCKT | |
| 21361 |
| NFS4ERR_DIRDELEG_UNAVAIL | GET_DIR_DELEGATION | |
| 21362 |
| NFS4ERR_DQUOT | CREATE, LAYOUTGET, LINK, | |
| 21363 |
| | OPEN, OPENATTR, RENAME, | |
| 21364 |
| | SETATTR, WRITE | |
| 21365 |
| NFS4ERR_ENCR_ALG_UNSUPP | EXCHANGE_ID | |
| 21366 |
| NFS4ERR_EXIST | CREATE, LINK, OPEN, RENAME | |
| 21367 |
| NFS4ERR_EXPIRED | CLOSE, DELEGRETURN, | |
| 21368 |
| | LAYOUTCOMMIT, LAYOUTRETURN, | |
| 21369 |
| | LOCK, LOCKU, OPEN, | |
| 21370 |
| | OPEN_DOWNGRADE, READ, | |
| 21371 |
| | SETATTR, WRITE | |
| 21372 |
| NFS4ERR_FBIG | LAYOUTCOMMIT, OPEN, SETATTR, | |
| 21373 |
| | WRITE | |
| 21374 |
| NFS4ERR_FHEXPIRED | ACCESS, CLOSE, COMMIT, | |
| 21375 |
| | CREATE, DELEGRETURN, GETATTR, | |
| 21376 |
| | GETDEVICELIST, GETFH, | |
| 21377 |
| | GET_DIR_DELEGATION, | |
| 21378 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21379 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21380 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21381 |
| | LOOKUPP, NVERIFY, OPEN, | |
| 21382 |
| | OPENATTR, OPEN_DOWNGRADE, | |
| 21383 |
| | READ, READDIR, READLINK, | |
| 21384 |
| | RECLAIM_COMPLETE, REMOVE, | |
| 21385 |
|
| 21386 |
|
| 21387 |
|
| 21388 |
<span class="grey">Shepler, et al. Standards Track [Page 382]</span></pre> |
| 21389 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-383" ></span> |
| 21390 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21391 |
|
| 21392 |
|
| 21393 |
| | RENAME, RESTOREFH, SAVEFH, | |
| 21394 |
| | SECINFO, SECINFO_NO_NAME, | |
| 21395 |
| | SETATTR, VERIFY, | |
| 21396 |
| | WANT_DELEGATION, WRITE | |
| 21397 |
| NFS4ERR_FILE_OPEN | LINK, REMOVE, RENAME | |
| 21398 |
| NFS4ERR_GRACE | GETATTR, GET_DIR_DELEGATION, | |
| 21399 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21400 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21401 |
| | LOCKT, NVERIFY, OPEN, READ, | |
| 21402 |
| | REMOVE, RENAME, SETATTR, | |
| 21403 |
| | VERIFY, WANT_DELEGATION, | |
| 21404 |
| | WRITE | |
| 21405 |
| NFS4ERR_HASH_ALG_UNSUPP | EXCHANGE_ID | |
| 21406 |
| NFS4ERR_INVAL | ACCESS, BACKCHANNEL_CTL, | |
| 21407 |
| | BIND_CONN_TO_SESSION, | |
| 21408 |
| | CB_GETATTR, CB_LAYOUTRECALL, | |
| 21409 |
| | CB_NOTIFY, | |
| 21410 |
| | CB_NOTIFY_DEVICEID, | |
| 21411 |
| | CB_PUSH_DELEG, | |
| 21412 |
| | CB_RECALLABLE_OBJ_AVAIL, | |
| 21413 |
| | CB_RECALL_ANY, CREATE, | |
| 21414 |
| | CREATE_SESSION, DELEGRETURN, | |
| 21415 |
| | EXCHANGE_ID, GETATTR, | |
| 21416 |
| | GETDEVICEINFO, GETDEVICELIST, | |
| 21417 |
| | GET_DIR_DELEGATION, | |
| 21418 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21419 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21420 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21421 |
| | NVERIFY, OPEN, | |
| 21422 |
| | OPEN_DOWNGRADE, READ, | |
| 21423 |
| | READDIR, READLINK, | |
| 21424 |
| | RECLAIM_COMPLETE, REMOVE, | |
| 21425 |
| | RENAME, SECINFO, | |
| 21426 |
| | SECINFO_NO_NAME, SETATTR, | |
| 21427 |
| | SET_SSV, VERIFY, | |
| 21428 |
| | WANT_DELEGATION, WRITE | |
| 21429 |
| NFS4ERR_IO | ACCESS, COMMIT, CREATE, | |
| 21430 |
| | GETATTR, GETDEVICELIST, | |
| 21431 |
| | GET_DIR_DELEGATION, | |
| 21432 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21433 |
| | LINK, LOOKUP, LOOKUPP, | |
| 21434 |
| | NVERIFY, OPEN, OPENATTR, | |
| 21435 |
| | READ, READDIR, READLINK, | |
| 21436 |
| | REMOVE, RENAME, SETATTR, | |
| 21437 |
| | VERIFY, WANT_DELEGATION, | |
| 21438 |
| | WRITE | |
| 21439 |
| NFS4ERR_ISDIR | COMMIT, LAYOUTCOMMIT, | |
| 21440 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21441 |
|
| 21442 |
|
| 21443 |
|
| 21444 |
<span class="grey">Shepler, et al. Standards Track [Page 383]</span></pre> |
| 21445 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-384" ></span> |
| 21446 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21447 |
|
| 21448 |
|
| 21449 |
| | LOCKT, OPEN, READ, WRITE | |
| 21450 |
| NFS4ERR_LAYOUTTRYLATER | LAYOUTGET | |
| 21451 |
| NFS4ERR_LAYOUTUNAVAILABLE | LAYOUTGET | |
| 21452 |
| NFS4ERR_LOCKED | LAYOUTGET, READ, SETATTR, | |
| 21453 |
| | WRITE | |
| 21454 |
| NFS4ERR_LOCKS_HELD | CLOSE, FREE_STATEID | |
| 21455 |
| NFS4ERR_LOCK_NOTSUPP | LOCK | |
| 21456 |
| NFS4ERR_LOCK_RANGE | LOCK, LOCKT, LOCKU | |
| 21457 |
| NFS4ERR_MLINK | CREATE, LINK, RENAME | |
| 21458 |
| NFS4ERR_MOVED | ACCESS, CLOSE, COMMIT, | |
| 21459 |
| | CREATE, DELEGRETURN, GETATTR, | |
| 21460 |
| | GETFH, GET_DIR_DELEGATION, | |
| 21461 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21462 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21463 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21464 |
| | LOOKUPP, NVERIFY, OPEN, | |
| 21465 |
| | OPENATTR, OPEN_DOWNGRADE, | |
| 21466 |
| | PUTFH, READ, READDIR, | |
| 21467 |
| | READLINK, RECLAIM_COMPLETE, | |
| 21468 |
| | REMOVE, RENAME, RESTOREFH, | |
| 21469 |
| | SAVEFH, SECINFO, | |
| 21470 |
| | SECINFO_NO_NAME, SETATTR, | |
| 21471 |
| | VERIFY, WANT_DELEGATION, | |
| 21472 |
| | WRITE | |
| 21473 |
| NFS4ERR_NAMETOOLONG | CREATE, LINK, LOOKUP, OPEN, | |
| 21474 |
| | REMOVE, RENAME, SECINFO | |
| 21475 |
| NFS4ERR_NOENT | BACKCHANNEL_CTL, | |
| 21476 |
| | CREATE_SESSION, EXCHANGE_ID, | |
| 21477 |
| | GETDEVICEINFO, LOOKUP, | |
| 21478 |
| | LOOKUPP, OPEN, OPENATTR, | |
| 21479 |
| | REMOVE, RENAME, SECINFO, | |
| 21480 |
| | SECINFO_NO_NAME | |
| 21481 |
| NFS4ERR_NOFILEHANDLE | ACCESS, CLOSE, COMMIT, | |
| 21482 |
| | CREATE, DELEGRETURN, GETATTR, | |
| 21483 |
| | GETDEVICELIST, GETFH, | |
| 21484 |
| | GET_DIR_DELEGATION, | |
| 21485 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21486 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21487 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21488 |
| | LOOKUPP, NVERIFY, OPEN, | |
| 21489 |
| | OPENATTR, OPEN_DOWNGRADE, | |
| 21490 |
| | READ, READDIR, READLINK, | |
| 21491 |
| | RECLAIM_COMPLETE, REMOVE, | |
| 21492 |
| | RENAME, RESTOREFH, SAVEFH, | |
| 21493 |
| | SECINFO, SECINFO_NO_NAME, | |
| 21494 |
| | SETATTR, VERIFY, | |
| 21495 |
| | WANT_DELEGATION, WRITE | |
| 21496 |
| NFS4ERR_NOMATCHING_LAYOUT | CB_LAYOUTRECALL | |
| 21497 |
|
| 21498 |
|
| 21499 |
|
| 21500 |
<span class="grey">Shepler, et al. Standards Track [Page 384]</span></pre> |
| 21501 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-385" ></span> |
| 21502 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21503 |
|
| 21504 |
|
| 21505 |
| NFS4ERR_NOSPC | CREATE, CREATE_SESSION, | |
| 21506 |
| | LAYOUTGET, LINK, OPEN, | |
| 21507 |
| | OPENATTR, RENAME, SETATTR, | |
| 21508 |
| | WRITE | |
| 21509 |
| NFS4ERR_NOTDIR | CREATE, GET_DIR_DELEGATION, | |
| 21510 |
| | LINK, LOOKUP, LOOKUPP, OPEN, | |
| 21511 |
| | READDIR, REMOVE, RENAME, | |
| 21512 |
| | SECINFO, SECINFO_NO_NAME | |
| 21513 |
| NFS4ERR_NOTEMPTY | REMOVE, RENAME | |
| 21514 |
| NFS4ERR_NOTSUPP | CB_LAYOUTRECALL, CB_NOTIFY, | |
| 21515 |
| | CB_NOTIFY_DEVICEID, | |
| 21516 |
| | CB_NOTIFY_LOCK, | |
| 21517 |
| | CB_PUSH_DELEG, | |
| 21518 |
| | CB_RECALLABLE_OBJ_AVAIL, | |
| 21519 |
| | CB_WANTS_CANCELLED, | |
| 21520 |
| | DELEGPURGE, DELEGRETURN, | |
| 21521 |
| | GETDEVICEINFO, GETDEVICELIST, | |
| 21522 |
| | GET_DIR_DELEGATION, | |
| 21523 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21524 |
| | LAYOUTRETURN, LINK, OPENATTR, | |
| 21525 |
| | OPEN_CONFIRM, | |
| 21526 |
| | RELEASE_LOCKOWNER, RENEW, | |
| 21527 |
| | SECINFO_NO_NAME, SETCLIENTID, | |
| 21528 |
| | SETCLIENTID_CONFIRM, | |
| 21529 |
| | WANT_DELEGATION | |
| 21530 |
| NFS4ERR_NOT_ONLY_OP | BIND_CONN_TO_SESSION, | |
| 21531 |
| | CREATE_SESSION, | |
| 21532 |
| | DESTROY_CLIENTID, | |
| 21533 |
| | DESTROY_SESSION, EXCHANGE_ID | |
| 21534 |
| NFS4ERR_NOT_SAME | EXCHANGE_ID, GETDEVICELIST, | |
| 21535 |
| | READDIR, VERIFY | |
| 21536 |
| NFS4ERR_NO_GRACE | LAYOUTCOMMIT, LAYOUTRETURN, | |
| 21537 |
| | LOCK, OPEN, WANT_DELEGATION | |
| 21538 |
| NFS4ERR_OLD_STATEID | CLOSE, DELEGRETURN, | |
| 21539 |
| | FREE_STATEID, LAYOUTGET, | |
| 21540 |
| | LAYOUTRETURN, LOCK, LOCKU, | |
| 21541 |
| | OPEN, OPEN_DOWNGRADE, READ, | |
| 21542 |
| | SETATTR, WRITE | |
| 21543 |
| NFS4ERR_OPENMODE | LAYOUTGET, LOCK, READ, | |
| 21544 |
| | SETATTR, WRITE | |
| 21545 |
| NFS4ERR_OP_ILLEGAL | CB_ILLEGAL, ILLEGAL | |
| 21546 |
| NFS4ERR_OP_NOT_IN_SESSION | ACCESS, BACKCHANNEL_CTL, | |
| 21547 |
| | CB_GETATTR, CB_LAYOUTRECALL, | |
| 21548 |
| | CB_NOTIFY, | |
| 21549 |
| | CB_NOTIFY_DEVICEID, | |
| 21550 |
| | CB_NOTIFY_LOCK, | |
| 21551 |
| | CB_PUSH_DELEG, CB_RECALL, | |
| 21552 |
| | CB_RECALLABLE_OBJ_AVAIL, | |
| 21553 |
|
| 21554 |
|
| 21555 |
|
| 21556 |
<span class="grey">Shepler, et al. Standards Track [Page 385]</span></pre> |
| 21557 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-386" ></span> |
| 21558 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21559 |
|
| 21560 |
|
| 21561 |
| | CB_RECALL_ANY, | |
| 21562 |
| | CB_RECALL_SLOT, | |
| 21563 |
| | CB_WANTS_CANCELLED, CLOSE, | |
| 21564 |
| | COMMIT, CREATE, DELEGPURGE, | |
| 21565 |
| | DELEGRETURN, FREE_STATEID, | |
| 21566 |
| | GETATTR, GETDEVICEINFO, | |
| 21567 |
| | GETDEVICELIST, GETFH, | |
| 21568 |
| | GET_DIR_DELEGATION, | |
| 21569 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21570 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21571 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21572 |
| | LOOKUPP, NVERIFY, OPEN, | |
| 21573 |
| | OPENATTR, OPEN_DOWNGRADE, | |
| 21574 |
| | PUTFH, PUTPUBFH, PUTROOTFH, | |
| 21575 |
| | READ, READDIR, READLINK, | |
| 21576 |
| | RECLAIM_COMPLETE, REMOVE, | |
| 21577 |
| | RENAME, RESTOREFH, SAVEFH, | |
| 21578 |
| | SECINFO, SECINFO_NO_NAME, | |
| 21579 |
| | SETATTR, SET_SSV, | |
| 21580 |
| | TEST_STATEID, VERIFY, | |
| 21581 |
| | WANT_DELEGATION, WRITE | |
| 21582 |
| NFS4ERR_PERM | CREATE, OPEN, SETATTR | |
| 21583 |
| NFS4ERR_PNFS_IO_HOLE | READ, WRITE | |
| 21584 |
| NFS4ERR_PNFS_NO_LAYOUT | READ, WRITE | |
| 21585 |
| NFS4ERR_RECALLCONFLICT | LAYOUTGET, WANT_DELEGATION | |
| 21586 |
| NFS4ERR_RECLAIM_BAD | LAYOUTCOMMIT, LOCK, OPEN, | |
| 21587 |
| | WANT_DELEGATION | |
| 21588 |
| NFS4ERR_RECLAIM_CONFLICT | LAYOUTCOMMIT, LOCK, OPEN, | |
| 21589 |
| | WANT_DELEGATION | |
| 21590 |
| NFS4ERR_REJECT_DELEG | CB_PUSH_DELEG | |
| 21591 |
| NFS4ERR_REP_TOO_BIG | ACCESS, BACKCHANNEL_CTL, | |
| 21592 |
| | BIND_CONN_TO_SESSION, | |
| 21593 |
| | CB_GETATTR, CB_LAYOUTRECALL, | |
| 21594 |
| | CB_NOTIFY, | |
| 21595 |
| | CB_NOTIFY_DEVICEID, | |
| 21596 |
| | CB_NOTIFY_LOCK, | |
| 21597 |
| | CB_PUSH_DELEG, CB_RECALL, | |
| 21598 |
| | CB_RECALLABLE_OBJ_AVAIL, | |
| 21599 |
| | CB_RECALL_ANY, | |
| 21600 |
| | CB_RECALL_SLOT, CB_SEQUENCE, | |
| 21601 |
| | CB_WANTS_CANCELLED, CLOSE, | |
| 21602 |
| | COMMIT, CREATE, | |
| 21603 |
| | CREATE_SESSION, DELEGPURGE, | |
| 21604 |
| | DELEGRETURN, | |
| 21605 |
| | DESTROY_CLIENTID, | |
| 21606 |
| | DESTROY_SESSION, EXCHANGE_ID, | |
| 21607 |
| | FREE_STATEID, GETATTR, | |
| 21608 |
| | GETDEVICEINFO, GETDEVICELIST, | |
| 21609 |
|
| 21610 |
|
| 21611 |
|
| 21612 |
<span class="grey">Shepler, et al. Standards Track [Page 386]</span></pre> |
| 21613 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-387" ></span> |
| 21614 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21615 |
|
| 21616 |
|
| 21617 |
| | GET_DIR_DELEGATION, | |
| 21618 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21619 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21620 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21621 |
| | LOOKUPP, NVERIFY, OPEN, | |
| 21622 |
| | OPENATTR, OPEN_DOWNGRADE, | |
| 21623 |
| | PUTFH, PUTPUBFH, PUTROOTFH, | |
| 21624 |
| | READ, READDIR, READLINK, | |
| 21625 |
| | RECLAIM_COMPLETE, REMOVE, | |
| 21626 |
| | RENAME, RESTOREFH, SAVEFH, | |
| 21627 |
| | SECINFO, SECINFO_NO_NAME, | |
| 21628 |
| | SEQUENCE, SETATTR, SET_SSV, | |
| 21629 |
| | TEST_STATEID, VERIFY, | |
| 21630 |
| | WANT_DELEGATION, WRITE | |
| 21631 |
| NFS4ERR_REP_TOO_BIG_TO_CACHE | ACCESS, BACKCHANNEL_CTL, | |
| 21632 |
| | BIND_CONN_TO_SESSION, | |
| 21633 |
| | CB_GETATTR, CB_LAYOUTRECALL, | |
| 21634 |
| | CB_NOTIFY, | |
| 21635 |
| | CB_NOTIFY_DEVICEID, | |
| 21636 |
| | CB_NOTIFY_LOCK, | |
| 21637 |
| | CB_PUSH_DELEG, CB_RECALL, | |
| 21638 |
| | CB_RECALLABLE_OBJ_AVAIL, | |
| 21639 |
| | CB_RECALL_ANY, | |
| 21640 |
| | CB_RECALL_SLOT, CB_SEQUENCE, | |
| 21641 |
| | CB_WANTS_CANCELLED, CLOSE, | |
| 21642 |
| | COMMIT, CREATE, | |
| 21643 |
| | CREATE_SESSION, DELEGPURGE, | |
| 21644 |
| | DELEGRETURN, | |
| 21645 |
| | DESTROY_CLIENTID, | |
| 21646 |
| | DESTROY_SESSION, EXCHANGE_ID, | |
| 21647 |
| | FREE_STATEID, GETATTR, | |
| 21648 |
| | GETDEVICEINFO, GETDEVICELIST, | |
| 21649 |
| | GET_DIR_DELEGATION, | |
| 21650 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21651 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21652 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21653 |
| | LOOKUPP, NVERIFY, OPEN, | |
| 21654 |
| | OPENATTR, OPEN_DOWNGRADE, | |
| 21655 |
| | PUTFH, PUTPUBFH, PUTROOTFH, | |
| 21656 |
| | READ, READDIR, READLINK, | |
| 21657 |
| | RECLAIM_COMPLETE, REMOVE, | |
| 21658 |
| | RENAME, RESTOREFH, SAVEFH, | |
| 21659 |
| | SECINFO, SECINFO_NO_NAME, | |
| 21660 |
| | SEQUENCE, SETATTR, SET_SSV, | |
| 21661 |
| | TEST_STATEID, VERIFY, | |
| 21662 |
| | WANT_DELEGATION, WRITE | |
| 21663 |
| NFS4ERR_REQ_TOO_BIG | ACCESS, BACKCHANNEL_CTL, | |
| 21664 |
| | BIND_CONN_TO_SESSION, | |
| 21665 |
|
| 21666 |
|
| 21667 |
|
| 21668 |
<span class="grey">Shepler, et al. Standards Track [Page 387]</span></pre> |
| 21669 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-388" ></span> |
| 21670 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21671 |
|
| 21672 |
|
| 21673 |
| | CB_GETATTR, CB_LAYOUTRECALL, | |
| 21674 |
| | CB_NOTIFY, | |
| 21675 |
| | CB_NOTIFY_DEVICEID, | |
| 21676 |
| | CB_NOTIFY_LOCK, | |
| 21677 |
| | CB_PUSH_DELEG, CB_RECALL, | |
| 21678 |
| | CB_RECALLABLE_OBJ_AVAIL, | |
| 21679 |
| | CB_RECALL_ANY, | |
| 21680 |
| | CB_RECALL_SLOT, CB_SEQUENCE, | |
| 21681 |
| | CB_WANTS_CANCELLED, CLOSE, | |
| 21682 |
| | COMMIT, CREATE, | |
| 21683 |
| | CREATE_SESSION, DELEGPURGE, | |
| 21684 |
| | DELEGRETURN, | |
| 21685 |
| | DESTROY_CLIENTID, | |
| 21686 |
| | DESTROY_SESSION, EXCHANGE_ID, | |
| 21687 |
| | FREE_STATEID, GETATTR, | |
| 21688 |
| | GETDEVICEINFO, GETDEVICELIST, | |
| 21689 |
| | GET_DIR_DELEGATION, | |
| 21690 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21691 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21692 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21693 |
| | LOOKUPP, NVERIFY, OPEN, | |
| 21694 |
| | OPENATTR, OPEN_DOWNGRADE, | |
| 21695 |
| | PUTFH, PUTPUBFH, PUTROOTFH, | |
| 21696 |
| | READ, READDIR, READLINK, | |
| 21697 |
| | RECLAIM_COMPLETE, REMOVE, | |
| 21698 |
| | RENAME, RESTOREFH, SAVEFH, | |
| 21699 |
| | SECINFO, SECINFO_NO_NAME, | |
| 21700 |
| | SEQUENCE, SETATTR, SET_SSV, | |
| 21701 |
| | TEST_STATEID, VERIFY, | |
| 21702 |
| | WANT_DELEGATION, WRITE | |
| 21703 |
| NFS4ERR_RETRY_UNCACHED_REP | ACCESS, BACKCHANNEL_CTL, | |
| 21704 |
| | BIND_CONN_TO_SESSION, | |
| 21705 |
| | CB_GETATTR, CB_LAYOUTRECALL, | |
| 21706 |
| | CB_NOTIFY, | |
| 21707 |
| | CB_NOTIFY_DEVICEID, | |
| 21708 |
| | CB_NOTIFY_LOCK, | |
| 21709 |
| | CB_PUSH_DELEG, CB_RECALL, | |
| 21710 |
| | CB_RECALLABLE_OBJ_AVAIL, | |
| 21711 |
| | CB_RECALL_ANY, | |
| 21712 |
| | CB_RECALL_SLOT, CB_SEQUENCE, | |
| 21713 |
| | CB_WANTS_CANCELLED, CLOSE, | |
| 21714 |
| | COMMIT, CREATE, | |
| 21715 |
| | CREATE_SESSION, DELEGPURGE, | |
| 21716 |
| | DELEGRETURN, | |
| 21717 |
| | DESTROY_CLIENTID, | |
| 21718 |
| | DESTROY_SESSION, EXCHANGE_ID, | |
| 21719 |
| | FREE_STATEID, GETATTR, | |
| 21720 |
| | GETDEVICEINFO, GETDEVICELIST, | |
| 21721 |
|
| 21722 |
|
| 21723 |
|
| 21724 |
<span class="grey">Shepler, et al. Standards Track [Page 388]</span></pre> |
| 21725 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-389" ></span> |
| 21726 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21727 |
|
| 21728 |
|
| 21729 |
| | GET_DIR_DELEGATION, | |
| 21730 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21731 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21732 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21733 |
| | LOOKUPP, NVERIFY, OPEN, | |
| 21734 |
| | OPENATTR, OPEN_DOWNGRADE, | |
| 21735 |
| | PUTFH, PUTPUBFH, PUTROOTFH, | |
| 21736 |
| | READ, READDIR, READLINK, | |
| 21737 |
| | RECLAIM_COMPLETE, REMOVE, | |
| 21738 |
| | RENAME, RESTOREFH, SAVEFH, | |
| 21739 |
| | SECINFO, SECINFO_NO_NAME, | |
| 21740 |
| | SEQUENCE, SETATTR, SET_SSV, | |
| 21741 |
| | TEST_STATEID, VERIFY, | |
| 21742 |
| | WANT_DELEGATION, WRITE | |
| 21743 |
| NFS4ERR_ROFS | CREATE, LINK, LOCK, LOCKT, | |
| 21744 |
| | OPEN, OPENATTR, | |
| 21745 |
| | OPEN_DOWNGRADE, REMOVE, | |
| 21746 |
| | RENAME, SETATTR, WRITE | |
| 21747 |
| NFS4ERR_SAME | NVERIFY | |
| 21748 |
| NFS4ERR_SEQUENCE_POS | CB_SEQUENCE, SEQUENCE | |
| 21749 |
| NFS4ERR_SEQ_FALSE_RETRY | CB_SEQUENCE, SEQUENCE | |
| 21750 |
| NFS4ERR_SEQ_MISORDERED | CB_SEQUENCE, CREATE_SESSION, | |
| 21751 |
| | SEQUENCE | |
| 21752 |
| NFS4ERR_SERVERFAULT | ACCESS, BIND_CONN_TO_SESSION, | |
| 21753 |
| | CB_GETATTR, CB_NOTIFY, | |
| 21754 |
| | CB_NOTIFY_DEVICEID, | |
| 21755 |
| | CB_NOTIFY_LOCK, | |
| 21756 |
| | CB_PUSH_DELEG, CB_RECALL, | |
| 21757 |
| | CB_RECALLABLE_OBJ_AVAIL, | |
| 21758 |
| | CB_WANTS_CANCELLED, CLOSE, | |
| 21759 |
| | COMMIT, CREATE, | |
| 21760 |
| | CREATE_SESSION, DELEGPURGE, | |
| 21761 |
| | DELEGRETURN, | |
| 21762 |
| | DESTROY_CLIENTID, | |
| 21763 |
| | DESTROY_SESSION, EXCHANGE_ID, | |
| 21764 |
| | FREE_STATEID, GETATTR, | |
| 21765 |
| | GETDEVICEINFO, GETDEVICELIST, | |
| 21766 |
| | GET_DIR_DELEGATION, | |
| 21767 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21768 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21769 |
| | LOCKU, LOOKUP, LOOKUPP, | |
| 21770 |
| | NVERIFY, OPEN, OPENATTR, | |
| 21771 |
| | OPEN_DOWNGRADE, PUTFH, | |
| 21772 |
| | PUTPUBFH, PUTROOTFH, READ, | |
| 21773 |
| | READDIR, READLINK, | |
| 21774 |
| | RECLAIM_COMPLETE, REMOVE, | |
| 21775 |
| | RENAME, RESTOREFH, SAVEFH, | |
| 21776 |
| | SECINFO, SECINFO_NO_NAME, | |
| 21777 |
|
| 21778 |
|
| 21779 |
|
| 21780 |
<span class="grey">Shepler, et al. Standards Track [Page 389]</span></pre> |
| 21781 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-390" ></span> |
| 21782 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21783 |
|
| 21784 |
|
| 21785 |
| | SETATTR, TEST_STATEID, | |
| 21786 |
| | VERIFY, WANT_DELEGATION, | |
| 21787 |
| | WRITE | |
| 21788 |
| NFS4ERR_SHARE_DENIED | OPEN | |
| 21789 |
| NFS4ERR_STALE | ACCESS, CLOSE, COMMIT, | |
| 21790 |
| | CREATE, DELEGRETURN, GETATTR, | |
| 21791 |
| | GETFH, GET_DIR_DELEGATION, | |
| 21792 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21793 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21794 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21795 |
| | LOOKUPP, NVERIFY, OPEN, | |
| 21796 |
| | OPENATTR, OPEN_DOWNGRADE, | |
| 21797 |
| | PUTFH, READ, READDIR, | |
| 21798 |
| | READLINK, RECLAIM_COMPLETE, | |
| 21799 |
| | REMOVE, RENAME, RESTOREFH, | |
| 21800 |
| | SAVEFH, SECINFO, | |
| 21801 |
| | SECINFO_NO_NAME, SETATTR, | |
| 21802 |
| | VERIFY, WANT_DELEGATION, | |
| 21803 |
| | WRITE | |
| 21804 |
| NFS4ERR_STALE_CLIENTID | CREATE_SESSION, | |
| 21805 |
| | DESTROY_CLIENTID, | |
| 21806 |
| | DESTROY_SESSION | |
| 21807 |
| NFS4ERR_SYMLINK | COMMIT, LAYOUTCOMMIT, LINK, | |
| 21808 |
| | LOCK, LOCKT, LOOKUP, LOOKUPP, | |
| 21809 |
| | OPEN, READ, WRITE | |
| 21810 |
| NFS4ERR_TOOSMALL | CREATE_SESSION, | |
| 21811 |
| | GETDEVICEINFO, LAYOUTGET, | |
| 21812 |
| | READDIR | |
| 21813 |
| NFS4ERR_TOO_MANY_OPS | ACCESS, BACKCHANNEL_CTL, | |
| 21814 |
| | BIND_CONN_TO_SESSION, | |
| 21815 |
| | CB_GETATTR, CB_LAYOUTRECALL, | |
| 21816 |
| | CB_NOTIFY, | |
| 21817 |
| | CB_NOTIFY_DEVICEID, | |
| 21818 |
| | CB_NOTIFY_LOCK, | |
| 21819 |
| | CB_PUSH_DELEG, CB_RECALL, | |
| 21820 |
| | CB_RECALLABLE_OBJ_AVAIL, | |
| 21821 |
| | CB_RECALL_ANY, | |
| 21822 |
| | CB_RECALL_SLOT, CB_SEQUENCE, | |
| 21823 |
| | CB_WANTS_CANCELLED, CLOSE, | |
| 21824 |
| | COMMIT, CREATE, | |
| 21825 |
| | CREATE_SESSION, DELEGPURGE, | |
| 21826 |
| | DELEGRETURN, | |
| 21827 |
| | DESTROY_CLIENTID, | |
| 21828 |
| | DESTROY_SESSION, EXCHANGE_ID, | |
| 21829 |
| | FREE_STATEID, GETATTR, | |
| 21830 |
| | GETDEVICEINFO, GETDEVICELIST, | |
| 21831 |
| | GET_DIR_DELEGATION, | |
| 21832 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21833 |
|
| 21834 |
|
| 21835 |
|
| 21836 |
<span class="grey">Shepler, et al. Standards Track [Page 390]</span></pre> |
| 21837 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-391" ></span> |
| 21838 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21839 |
|
| 21840 |
|
| 21841 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21842 |
| | LOCKT, LOCKU, LOOKUP, | |
| 21843 |
| | LOOKUPP, NVERIFY, OPEN, | |
| 21844 |
| | OPENATTR, OPEN_DOWNGRADE, | |
| 21845 |
| | PUTFH, PUTPUBFH, PUTROOTFH, | |
| 21846 |
| | READ, READDIR, READLINK, | |
| 21847 |
| | RECLAIM_COMPLETE, REMOVE, | |
| 21848 |
| | RENAME, RESTOREFH, SAVEFH, | |
| 21849 |
| | SECINFO, SECINFO_NO_NAME, | |
| 21850 |
| | SEQUENCE, SETATTR, SET_SSV, | |
| 21851 |
| | TEST_STATEID, VERIFY, | |
| 21852 |
| | WANT_DELEGATION, WRITE | |
| 21853 |
| NFS4ERR_UNKNOWN_LAYOUTTYPE | CB_LAYOUTRECALL, | |
| 21854 |
| | GETDEVICEINFO, GETDEVICELIST, | |
| 21855 |
| | LAYOUTCOMMIT, LAYOUTGET, | |
| 21856 |
| | LAYOUTRETURN, NVERIFY, | |
| 21857 |
| | SETATTR, VERIFY | |
| 21858 |
| NFS4ERR_UNSAFE_COMPOUND | CREATE, OPEN, OPENATTR | |
| 21859 |
| NFS4ERR_WRONGSEC | LINK, LOOKUP, LOOKUPP, OPEN, | |
| 21860 |
| | PUTFH, PUTPUBFH, PUTROOTFH, | |
| 21861 |
| | RENAME, RESTOREFH | |
| 21862 |
| NFS4ERR_WRONG_CRED | CLOSE, CREATE_SESSION, | |
| 21863 |
| | DELEGPURGE, DELEGRETURN, | |
| 21864 |
| | DESTROY_CLIENTID, | |
| 21865 |
| | DESTROY_SESSION, | |
| 21866 |
| | FREE_STATEID, LAYOUTCOMMIT, | |
| 21867 |
| | LAYOUTRETURN, LOCK, LOCKT, | |
| 21868 |
| | LOCKU, OPEN_DOWNGRADE, | |
| 21869 |
| | RECLAIM_COMPLETE | |
| 21870 |
| NFS4ERR_WRONG_TYPE | CB_LAYOUTRECALL, | |
| 21871 |
| | CB_PUSH_DELEG, COMMIT, | |
| 21872 |
| | GETATTR, LAYOUTGET, | |
| 21873 |
| | LAYOUTRETURN, LINK, LOCK, | |
| 21874 |
| | LOCKT, NVERIFY, OPEN, | |
| 21875 |
| | OPENATTR, READ, READLINK, | |
| 21876 |
| | RECLAIM_COMPLETE, SETATTR, | |
| 21877 |
| | VERIFY, WANT_DELEGATION, | |
| 21878 |
| | WRITE | |
| 21879 |
| NFS4ERR_XDEV | LINK, RENAME | |
| 21880 |
+-----------------------------------+-------------------------------+ |
| 21881 |
|
| 21882 |
Table 8 |
| 21883 |
|
| 21884 |
<span class="h2"><a class="selflink" id="section-16" href="#section-16">16</a>. NFSv4.1 Procedures</span> |
| 21885 |
|
| 21886 |
Both procedures, NULL and COMPOUND, MUST be implemented. |
| 21887 |
|
| 21888 |
|
| 21889 |
|
| 21890 |
|
| 21891 |
|
| 21892 |
<span class="grey">Shepler, et al. Standards Track [Page 391]</span></pre> |
| 21893 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-392" ></span> |
| 21894 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21895 |
|
| 21896 |
|
| 21897 |
<span class="h3"><a class="selflink" id="section-16.1" href="#section-16.1">16.1</a>. Procedure 0: NULL - No Operation</span> |
| 21898 |
|
| 21899 |
<span class="h4"><a class="selflink" id="section-16.1.1" href="#section-16.1.1">16.1.1</a>. ARGUMENTS</span> |
| 21900 |
|
| 21901 |
void; |
| 21902 |
|
| 21903 |
<span class="h4"><a class="selflink" id="section-16.1.2" href="#section-16.1.2">16.1.2</a>. RESULTS</span> |
| 21904 |
|
| 21905 |
void; |
| 21906 |
|
| 21907 |
<span class="h4"><a class="selflink" id="section-16.1.3" href="#section-16.1.3">16.1.3</a>. DESCRIPTION</span> |
| 21908 |
|
| 21909 |
This is the standard NULL procedure with the standard void argument |
| 21910 |
and void response. This procedure has no functionality associated |
| 21911 |
with it. Because of this, it is sometimes used to measure the |
| 21912 |
overhead of processing a service request. Therefore, the server |
| 21913 |
SHOULD ensure that no unnecessary work is done in servicing this |
| 21914 |
procedure. |
| 21915 |
|
| 21916 |
<span class="h4"><a class="selflink" id="section-16.1.4" href="#section-16.1.4">16.1.4</a>. ERRORS</span> |
| 21917 |
|
| 21918 |
None. |
| 21919 |
|
| 21920 |
<span class="h3"><a class="selflink" id="section-16.2" href="#section-16.2">16.2</a>. Procedure 1: COMPOUND - Compound Operations</span> |
| 21921 |
|
| 21922 |
<span class="h4"><a class="selflink" id="section-16.2.1" href="#section-16.2.1">16.2.1</a>. ARGUMENTS</span> |
| 21923 |
|
| 21924 |
enum nfs_opnum4 { |
| 21925 |
OP_ACCESS = 3, |
| 21926 |
OP_CLOSE = 4, |
| 21927 |
OP_COMMIT = 5, |
| 21928 |
OP_CREATE = 6, |
| 21929 |
OP_DELEGPURGE = 7, |
| 21930 |
OP_DELEGRETURN = 8, |
| 21931 |
OP_GETATTR = 9, |
| 21932 |
OP_GETFH = 10, |
| 21933 |
OP_LINK = 11, |
| 21934 |
OP_LOCK = 12, |
| 21935 |
OP_LOCKT = 13, |
| 21936 |
OP_LOCKU = 14, |
| 21937 |
OP_LOOKUP = 15, |
| 21938 |
OP_LOOKUPP = 16, |
| 21939 |
OP_NVERIFY = 17, |
| 21940 |
OP_OPEN = 18, |
| 21941 |
OP_OPENATTR = 19, |
| 21942 |
OP_OPEN_CONFIRM = 20, /* Mandatory not-to-implement */ |
| 21943 |
OP_OPEN_DOWNGRADE = 21, |
| 21944 |
OP_PUTFH = 22, |
| 21945 |
|
| 21946 |
|
| 21947 |
|
| 21948 |
<span class="grey">Shepler, et al. Standards Track [Page 392]</span></pre> |
| 21949 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-393" ></span> |
| 21950 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 21951 |
|
| 21952 |
|
| 21953 |
OP_PUTPUBFH = 23, |
| 21954 |
OP_PUTROOTFH = 24, |
| 21955 |
OP_READ = 25, |
| 21956 |
OP_READDIR = 26, |
| 21957 |
OP_READLINK = 27, |
| 21958 |
OP_REMOVE = 28, |
| 21959 |
OP_RENAME = 29, |
| 21960 |
OP_RENEW = 30, /* Mandatory not-to-implement */ |
| 21961 |
OP_RESTOREFH = 31, |
| 21962 |
OP_SAVEFH = 32, |
| 21963 |
OP_SECINFO = 33, |
| 21964 |
OP_SETATTR = 34, |
| 21965 |
OP_SETCLIENTID = 35, /* Mandatory not-to-implement */ |
| 21966 |
OP_SETCLIENTID_CONFIRM = 36, /* Mandatory not-to-implement */ |
| 21967 |
OP_VERIFY = 37, |
| 21968 |
OP_WRITE = 38, |
| 21969 |
OP_RELEASE_LOCKOWNER = 39, /* Mandatory not-to-implement */ |
| 21970 |
|
| 21971 |
/* new operations for NFSv4.1 */ |
| 21972 |
OP_BACKCHANNEL_CTL = 40, |
| 21973 |
OP_BIND_CONN_TO_SESSION = 41, |
| 21974 |
OP_EXCHANGE_ID = 42, |
| 21975 |
OP_CREATE_SESSION = 43, |
| 21976 |
OP_DESTROY_SESSION = 44, |
| 21977 |
OP_FREE_STATEID = 45, |
| 21978 |
OP_GET_DIR_DELEGATION = 46, |
| 21979 |
OP_GETDEVICEINFO = 47, |
| 21980 |
OP_GETDEVICELIST = 48, |
| 21981 |
OP_LAYOUTCOMMIT = 49, |
| 21982 |
OP_LAYOUTGET = 50, |
| 21983 |
OP_LAYOUTRETURN = 51, |
| 21984 |
OP_SECINFO_NO_NAME = 52, |
| 21985 |
OP_SEQUENCE = 53, |
| 21986 |
OP_SET_SSV = 54, |
| 21987 |
OP_TEST_STATEID = 55, |
| 21988 |
OP_WANT_DELEGATION = 56, |
| 21989 |
OP_DESTROY_CLIENTID = 57, |
| 21990 |
OP_RECLAIM_COMPLETE = 58, |
| 21991 |
OP_ILLEGAL = 10044 |
| 21992 |
}; |
| 21993 |
|
| 21994 |
|
| 21995 |
|
| 21996 |
|
| 21997 |
|
| 21998 |
|
| 21999 |
|
| 22000 |
|
| 22001 |
|
| 22002 |
|
| 22003 |
|
| 22004 |
<span class="grey">Shepler, et al. Standards Track [Page 393]</span></pre> |
| 22005 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-394" ></span> |
| 22006 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22007 |
|
| 22008 |
|
| 22009 |
union nfs_argop4 switch (nfs_opnum4 argop) { |
| 22010 |
case OP_ACCESS: ACCESS4args opaccess; |
| 22011 |
case OP_CLOSE: CLOSE4args opclose; |
| 22012 |
case OP_COMMIT: COMMIT4args opcommit; |
| 22013 |
case OP_CREATE: CREATE4args opcreate; |
| 22014 |
case OP_DELEGPURGE: DELEGPURGE4args opdelegpurge; |
| 22015 |
case OP_DELEGRETURN: DELEGRETURN4args opdelegreturn; |
| 22016 |
case OP_GETATTR: GETATTR4args opgetattr; |
| 22017 |
case OP_GETFH: void; |
| 22018 |
case OP_LINK: LINK4args oplink; |
| 22019 |
case OP_LOCK: LOCK4args oplock; |
| 22020 |
case OP_LOCKT: LOCKT4args oplockt; |
| 22021 |
case OP_LOCKU: LOCKU4args oplocku; |
| 22022 |
case OP_LOOKUP: LOOKUP4args oplookup; |
| 22023 |
case OP_LOOKUPP: void; |
| 22024 |
case OP_NVERIFY: NVERIFY4args opnverify; |
| 22025 |
case OP_OPEN: OPEN4args opopen; |
| 22026 |
case OP_OPENATTR: OPENATTR4args opopenattr; |
| 22027 |
|
| 22028 |
/* Not for NFSv4.1 */ |
| 22029 |
case OP_OPEN_CONFIRM: OPEN_CONFIRM4args opopen_confirm; |
| 22030 |
|
| 22031 |
case OP_OPEN_DOWNGRADE: |
| 22032 |
OPEN_DOWNGRADE4args opopen_downgrade; |
| 22033 |
|
| 22034 |
case OP_PUTFH: PUTFH4args opputfh; |
| 22035 |
case OP_PUTPUBFH: void; |
| 22036 |
case OP_PUTROOTFH: void; |
| 22037 |
case OP_READ: READ4args opread; |
| 22038 |
case OP_READDIR: READDIR4args opreaddir; |
| 22039 |
case OP_READLINK: void; |
| 22040 |
case OP_REMOVE: REMOVE4args opremove; |
| 22041 |
case OP_RENAME: RENAME4args oprename; |
| 22042 |
|
| 22043 |
/* Not for NFSv4.1 */ |
| 22044 |
case OP_RENEW: RENEW4args oprenew; |
| 22045 |
|
| 22046 |
case OP_RESTOREFH: void; |
| 22047 |
case OP_SAVEFH: void; |
| 22048 |
case OP_SECINFO: SECINFO4args opsecinfo; |
| 22049 |
case OP_SETATTR: SETATTR4args opsetattr; |
| 22050 |
|
| 22051 |
/* Not for NFSv4.1 */ |
| 22052 |
case OP_SETCLIENTID: SETCLIENTID4args opsetclientid; |
| 22053 |
|
| 22054 |
|
| 22055 |
|
| 22056 |
|
| 22057 |
|
| 22058 |
|
| 22059 |
|
| 22060 |
<span class="grey">Shepler, et al. Standards Track [Page 394]</span></pre> |
| 22061 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-395" ></span> |
| 22062 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22063 |
|
| 22064 |
|
| 22065 |
/* Not for NFSv4.1 */ |
| 22066 |
case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4args |
| 22067 |
opsetclientid_confirm; |
| 22068 |
case OP_VERIFY: VERIFY4args opverify; |
| 22069 |
case OP_WRITE: WRITE4args opwrite; |
| 22070 |
|
| 22071 |
/* Not for NFSv4.1 */ |
| 22072 |
case OP_RELEASE_LOCKOWNER: |
| 22073 |
RELEASE_LOCKOWNER4args |
| 22074 |
oprelease_lockowner; |
| 22075 |
|
| 22076 |
/* Operations new to NFSv4.1 */ |
| 22077 |
case OP_BACKCHANNEL_CTL: |
| 22078 |
BACKCHANNEL_CTL4args opbackchannel_ctl; |
| 22079 |
|
| 22080 |
case OP_BIND_CONN_TO_SESSION: |
| 22081 |
BIND_CONN_TO_SESSION4args |
| 22082 |
opbind_conn_to_session; |
| 22083 |
|
| 22084 |
case OP_EXCHANGE_ID: EXCHANGE_ID4args opexchange_id; |
| 22085 |
|
| 22086 |
case OP_CREATE_SESSION: |
| 22087 |
CREATE_SESSION4args opcreate_session; |
| 22088 |
|
| 22089 |
case OP_DESTROY_SESSION: |
| 22090 |
DESTROY_SESSION4args opdestroy_session; |
| 22091 |
|
| 22092 |
case OP_FREE_STATEID: FREE_STATEID4args opfree_stateid; |
| 22093 |
|
| 22094 |
case OP_GET_DIR_DELEGATION: |
| 22095 |
GET_DIR_DELEGATION4args |
| 22096 |
opget_dir_delegation; |
| 22097 |
|
| 22098 |
case OP_GETDEVICEINFO: GETDEVICEINFO4args opgetdeviceinfo; |
| 22099 |
case OP_GETDEVICELIST: GETDEVICELIST4args opgetdevicelist; |
| 22100 |
case OP_LAYOUTCOMMIT: LAYOUTCOMMIT4args oplayoutcommit; |
| 22101 |
case OP_LAYOUTGET: LAYOUTGET4args oplayoutget; |
| 22102 |
case OP_LAYOUTRETURN: LAYOUTRETURN4args oplayoutreturn; |
| 22103 |
|
| 22104 |
case OP_SECINFO_NO_NAME: |
| 22105 |
SECINFO_NO_NAME4args opsecinfo_no_name; |
| 22106 |
|
| 22107 |
case OP_SEQUENCE: SEQUENCE4args opsequence; |
| 22108 |
case OP_SET_SSV: SET_SSV4args opset_ssv; |
| 22109 |
case OP_TEST_STATEID: TEST_STATEID4args optest_stateid; |
| 22110 |
|
| 22111 |
case OP_WANT_DELEGATION: |
| 22112 |
WANT_DELEGATION4args opwant_delegation; |
| 22113 |
|
| 22114 |
|
| 22115 |
|
| 22116 |
<span class="grey">Shepler, et al. Standards Track [Page 395]</span></pre> |
| 22117 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-396" ></span> |
| 22118 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22119 |
|
| 22120 |
|
| 22121 |
case OP_DESTROY_CLIENTID: |
| 22122 |
DESTROY_CLIENTID4args |
| 22123 |
opdestroy_clientid; |
| 22124 |
|
| 22125 |
case OP_RECLAIM_COMPLETE: |
| 22126 |
RECLAIM_COMPLETE4args |
| 22127 |
opreclaim_complete; |
| 22128 |
|
| 22129 |
/* Operations not new to NFSv4.1 */ |
| 22130 |
case OP_ILLEGAL: void; |
| 22131 |
}; |
| 22132 |
|
| 22133 |
|
| 22134 |
struct COMPOUND4args { |
| 22135 |
utf8str_cs tag; |
| 22136 |
uint32_t minorversion; |
| 22137 |
nfs_argop4 argarray<>; |
| 22138 |
}; |
| 22139 |
|
| 22140 |
<span class="h4"><a class="selflink" id="section-16.2.2" href="#section-16.2.2">16.2.2</a>. RESULTS</span> |
| 22141 |
|
| 22142 |
union nfs_resop4 switch (nfs_opnum4 resop) { |
| 22143 |
case OP_ACCESS: ACCESS4res opaccess; |
| 22144 |
case OP_CLOSE: CLOSE4res opclose; |
| 22145 |
case OP_COMMIT: COMMIT4res opcommit; |
| 22146 |
case OP_CREATE: CREATE4res opcreate; |
| 22147 |
case OP_DELEGPURGE: DELEGPURGE4res opdelegpurge; |
| 22148 |
case OP_DELEGRETURN: DELEGRETURN4res opdelegreturn; |
| 22149 |
case OP_GETATTR: GETATTR4res opgetattr; |
| 22150 |
case OP_GETFH: GETFH4res opgetfh; |
| 22151 |
case OP_LINK: LINK4res oplink; |
| 22152 |
case OP_LOCK: LOCK4res oplock; |
| 22153 |
case OP_LOCKT: LOCKT4res oplockt; |
| 22154 |
case OP_LOCKU: LOCKU4res oplocku; |
| 22155 |
case OP_LOOKUP: LOOKUP4res oplookup; |
| 22156 |
case OP_LOOKUPP: LOOKUPP4res oplookupp; |
| 22157 |
case OP_NVERIFY: NVERIFY4res opnverify; |
| 22158 |
case OP_OPEN: OPEN4res opopen; |
| 22159 |
case OP_OPENATTR: OPENATTR4res opopenattr; |
| 22160 |
/* Not for NFSv4.1 */ |
| 22161 |
case OP_OPEN_CONFIRM: OPEN_CONFIRM4res opopen_confirm; |
| 22162 |
|
| 22163 |
case OP_OPEN_DOWNGRADE: |
| 22164 |
OPEN_DOWNGRADE4res |
| 22165 |
opopen_downgrade; |
| 22166 |
|
| 22167 |
case OP_PUTFH: PUTFH4res opputfh; |
| 22168 |
case OP_PUTPUBFH: PUTPUBFH4res opputpubfh; |
| 22169 |
|
| 22170 |
|
| 22171 |
|
| 22172 |
<span class="grey">Shepler, et al. Standards Track [Page 396]</span></pre> |
| 22173 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-397" ></span> |
| 22174 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22175 |
|
| 22176 |
|
| 22177 |
case OP_PUTROOTFH: PUTROOTFH4res opputrootfh; |
| 22178 |
case OP_READ: READ4res opread; |
| 22179 |
case OP_READDIR: READDIR4res opreaddir; |
| 22180 |
case OP_READLINK: READLINK4res opreadlink; |
| 22181 |
case OP_REMOVE: REMOVE4res opremove; |
| 22182 |
case OP_RENAME: RENAME4res oprename; |
| 22183 |
/* Not for NFSv4.1 */ |
| 22184 |
case OP_RENEW: RENEW4res oprenew; |
| 22185 |
case OP_RESTOREFH: RESTOREFH4res oprestorefh; |
| 22186 |
case OP_SAVEFH: SAVEFH4res opsavefh; |
| 22187 |
case OP_SECINFO: SECINFO4res opsecinfo; |
| 22188 |
case OP_SETATTR: SETATTR4res opsetattr; |
| 22189 |
/* Not for NFSv4.1 */ |
| 22190 |
case OP_SETCLIENTID: SETCLIENTID4res opsetclientid; |
| 22191 |
|
| 22192 |
/* Not for NFSv4.1 */ |
| 22193 |
case OP_SETCLIENTID_CONFIRM: |
| 22194 |
SETCLIENTID_CONFIRM4res |
| 22195 |
opsetclientid_confirm; |
| 22196 |
case OP_VERIFY: VERIFY4res opverify; |
| 22197 |
case OP_WRITE: WRITE4res opwrite; |
| 22198 |
|
| 22199 |
/* Not for NFSv4.1 */ |
| 22200 |
case OP_RELEASE_LOCKOWNER: |
| 22201 |
RELEASE_LOCKOWNER4res |
| 22202 |
oprelease_lockowner; |
| 22203 |
|
| 22204 |
/* Operations new to NFSv4.1 */ |
| 22205 |
|
| 22206 |
case OP_BACKCHANNEL_CTL: |
| 22207 |
BACKCHANNEL_CTL4res |
| 22208 |
opbackchannel_ctl; |
| 22209 |
|
| 22210 |
case OP_BIND_CONN_TO_SESSION: |
| 22211 |
BIND_CONN_TO_SESSION4res |
| 22212 |
opbind_conn_to_session; |
| 22213 |
|
| 22214 |
case OP_EXCHANGE_ID: EXCHANGE_ID4res opexchange_id; |
| 22215 |
|
| 22216 |
case OP_CREATE_SESSION: |
| 22217 |
CREATE_SESSION4res |
| 22218 |
opcreate_session; |
| 22219 |
|
| 22220 |
case OP_DESTROY_SESSION: |
| 22221 |
DESTROY_SESSION4res |
| 22222 |
opdestroy_session; |
| 22223 |
|
| 22224 |
|
| 22225 |
|
| 22226 |
|
| 22227 |
|
| 22228 |
<span class="grey">Shepler, et al. Standards Track [Page 397]</span></pre> |
| 22229 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-398" ></span> |
| 22230 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22231 |
|
| 22232 |
|
| 22233 |
case OP_FREE_STATEID: FREE_STATEID4res |
| 22234 |
opfree_stateid; |
| 22235 |
|
| 22236 |
case OP_GET_DIR_DELEGATION: |
| 22237 |
GET_DIR_DELEGATION4res |
| 22238 |
opget_dir_delegation; |
| 22239 |
|
| 22240 |
case OP_GETDEVICEINFO: GETDEVICEINFO4res |
| 22241 |
opgetdeviceinfo; |
| 22242 |
|
| 22243 |
case OP_GETDEVICELIST: GETDEVICELIST4res |
| 22244 |
opgetdevicelist; |
| 22245 |
|
| 22246 |
case OP_LAYOUTCOMMIT: LAYOUTCOMMIT4res oplayoutcommit; |
| 22247 |
case OP_LAYOUTGET: LAYOUTGET4res oplayoutget; |
| 22248 |
case OP_LAYOUTRETURN: LAYOUTRETURN4res oplayoutreturn; |
| 22249 |
|
| 22250 |
case OP_SECINFO_NO_NAME: |
| 22251 |
SECINFO_NO_NAME4res |
| 22252 |
opsecinfo_no_name; |
| 22253 |
|
| 22254 |
case OP_SEQUENCE: SEQUENCE4res opsequence; |
| 22255 |
case OP_SET_SSV: SET_SSV4res opset_ssv; |
| 22256 |
case OP_TEST_STATEID: TEST_STATEID4res optest_stateid; |
| 22257 |
|
| 22258 |
case OP_WANT_DELEGATION: |
| 22259 |
WANT_DELEGATION4res |
| 22260 |
opwant_delegation; |
| 22261 |
|
| 22262 |
case OP_DESTROY_CLIENTID: |
| 22263 |
|
| 22264 |
DESTROY_CLIENTID4res |
| 22265 |
opdestroy_clientid; |
| 22266 |
|
| 22267 |
case OP_RECLAIM_COMPLETE: |
| 22268 |
RECLAIM_COMPLETE4res |
| 22269 |
opreclaim_complete; |
| 22270 |
|
| 22271 |
/* Operations not new to NFSv4.1 */ |
| 22272 |
case OP_ILLEGAL: ILLEGAL4res opillegal; |
| 22273 |
}; |
| 22274 |
|
| 22275 |
|
| 22276 |
struct COMPOUND4res { |
| 22277 |
nfsstat4 status; |
| 22278 |
utf8str_cs tag; |
| 22279 |
nfs_resop4 resarray<>; |
| 22280 |
}; |
| 22281 |
|
| 22282 |
|
| 22283 |
|
| 22284 |
<span class="grey">Shepler, et al. Standards Track [Page 398]</span></pre> |
| 22285 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-399" ></span> |
| 22286 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22287 |
|
| 22288 |
|
| 22289 |
<span class="h4"><a class="selflink" id="section-16.2.3" href="#section-16.2.3">16.2.3</a>. DESCRIPTION</span> |
| 22290 |
|
| 22291 |
The COMPOUND procedure is used to combine one or more NFSv4 |
| 22292 |
operations into a single RPC request. The server interprets each of |
| 22293 |
the operations in turn. If an operation is executed by the server |
| 22294 |
and the status of that operation is NFS4_OK, then the next operation |
| 22295 |
in the COMPOUND procedure is executed. The server continues this |
| 22296 |
process until there are no more operations to be executed or until |
| 22297 |
one of the operations has a status value other than NFS4_OK. |
| 22298 |
|
| 22299 |
In the processing of the COMPOUND procedure, the server may find that |
| 22300 |
it does not have the available resources to execute any or all of the |
| 22301 |
operations within the COMPOUND sequence. See <a href="#section-2.10.6.4">Section 2.10.6.4</a> for a |
| 22302 |
more detailed discussion. |
| 22303 |
|
| 22304 |
The server will generally choose between two methods of decoding the |
| 22305 |
client's request. The first would be the traditional one-pass XDR |
| 22306 |
decode. If there is an XDR decoding error in this case, the RPC XDR |
| 22307 |
decode error would be returned. The second method would be to make |
| 22308 |
an initial pass to decode the basic COMPOUND request and then to XDR |
| 22309 |
decode the individual operations; the most interesting is the decode |
| 22310 |
of attributes. In this case, the server may encounter an XDR decode |
| 22311 |
error during the second pass. If it does, the server would return |
| 22312 |
the error NFS4ERR_BADXDR to signify the decode error. |
| 22313 |
|
| 22314 |
The COMPOUND arguments contain a "minorversion" field. For NFSv4.1, |
| 22315 |
the value for this field is 1. If the server receives a COMPOUND |
| 22316 |
procedure with a minorversion field value that it does not support, |
| 22317 |
the server MUST return an error of NFS4ERR_MINOR_VERS_MISMATCH and a |
| 22318 |
zero-length resultdata array. |
| 22319 |
|
| 22320 |
Contained within the COMPOUND results is a "status" field. If the |
| 22321 |
results array length is non-zero, this status must be equivalent to |
| 22322 |
the status of the last operation that was executed within the |
| 22323 |
COMPOUND procedure. Therefore, if an operation incurred an error |
| 22324 |
then the "status" value will be the same error value as is being |
| 22325 |
returned for the operation that failed. |
| 22326 |
|
| 22327 |
Note that operations zero and one are not defined for the COMPOUND |
| 22328 |
procedure. Operation 2 is not defined and is reserved for future |
| 22329 |
definition and use with minor versioning. If the server receives an |
| 22330 |
operation array that contains operation 2 and the minorversion field |
| 22331 |
has a value of zero, an error of NFS4ERR_OP_ILLEGAL, as described in |
| 22332 |
the next paragraph, is returned to the client. If an operation array |
| 22333 |
contains an operation 2 and the minorversion field is non-zero and |
| 22334 |
the server does not support the minor version, the server returns an |
| 22335 |
|
| 22336 |
|
| 22337 |
|
| 22338 |
|
| 22339 |
|
| 22340 |
<span class="grey">Shepler, et al. Standards Track [Page 399]</span></pre> |
| 22341 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-400" ></span> |
| 22342 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22343 |
|
| 22344 |
|
| 22345 |
error of NFS4ERR_MINOR_VERS_MISMATCH. Therefore, the |
| 22346 |
NFS4ERR_MINOR_VERS_MISMATCH error takes precedence over all other |
| 22347 |
errors. |
| 22348 |
|
| 22349 |
It is possible that the server receives a request that contains an |
| 22350 |
operation that is less than the first legal operation (OP_ACCESS) or |
| 22351 |
greater than the last legal operation (OP_RELEASE_LOCKOWNER). In |
| 22352 |
this case, the server's response will encode the opcode OP_ILLEGAL |
| 22353 |
rather than the illegal opcode of the request. The status field in |
| 22354 |
the ILLEGAL return results will be set to NFS4ERR_OP_ILLEGAL. The |
| 22355 |
COMPOUND procedure's return results will also be NFS4ERR_OP_ILLEGAL. |
| 22356 |
|
| 22357 |
The definition of the "tag" in the request is left to the |
| 22358 |
implementor. It may be used to summarize the content of the Compound |
| 22359 |
request for the benefit of packet-sniffers and engineers debugging |
| 22360 |
implementations. However, the value of "tag" in the response SHOULD |
| 22361 |
be the same value as provided in the request. This applies to the |
| 22362 |
tag field of the CB_COMPOUND procedure as well. |
| 22363 |
|
| 22364 |
<span class="h5"><a class="selflink" id="section-16.2.3.1" href="#section-16.2.3.1">16.2.3.1</a>. Current Filehandle and Stateid</span> |
| 22365 |
|
| 22366 |
The COMPOUND procedure offers a simple environment for the execution |
| 22367 |
of the operations specified by the client. The first two relate to |
| 22368 |
the filehandle while the second two relate to the current stateid. |
| 22369 |
|
| 22370 |
<span class="h6"><a class="selflink" id="section-16.2.3.1.1" href="#section-16.2.3.1.1">16.2.3.1.1</a>. Current Filehandle</span> |
| 22371 |
|
| 22372 |
The current and saved filehandles are used throughout the protocol. |
| 22373 |
Most operations implicitly use the current filehandle as an argument, |
| 22374 |
and many set the current filehandle as part of the results. The |
| 22375 |
combination of client-specified sequences of operations and current |
| 22376 |
and saved filehandle arguments and results allows for greater |
| 22377 |
protocol flexibility. The best or easiest example of current |
| 22378 |
filehandle usage is a sequence like the following: |
| 22379 |
|
| 22380 |
|
| 22381 |
PUTFH fh1 {fh1} |
| 22382 |
LOOKUP "compA" {fh2} |
| 22383 |
GETATTR {fh2} |
| 22384 |
LOOKUP "compB" {fh3} |
| 22385 |
GETATTR {fh3} |
| 22386 |
LOOKUP "compC" {fh4} |
| 22387 |
GETATTR {fh4} |
| 22388 |
GETFH |
| 22389 |
|
| 22390 |
Figure 2 |
| 22391 |
|
| 22392 |
|
| 22393 |
|
| 22394 |
|
| 22395 |
|
| 22396 |
<span class="grey">Shepler, et al. Standards Track [Page 400]</span></pre> |
| 22397 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-401" ></span> |
| 22398 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22399 |
|
| 22400 |
|
| 22401 |
In this example, the PUTFH (<a href="#section-18.19">Section 18.19</a>) operation explicitly sets |
| 22402 |
the current filehandle value while the result of each LOOKUP |
| 22403 |
operation sets the current filehandle value to the resultant file |
| 22404 |
system object. Also, the client is able to insert GETATTR operations |
| 22405 |
using the current filehandle as an argument. |
| 22406 |
|
| 22407 |
The PUTROOTFH (<a href="#section-18.21">Section 18.21</a>) and PUTPUBFH (<a href="#section-18.20">Section 18.20</a>) operations |
| 22408 |
also set the current filehandle. The above example would replace |
| 22409 |
"PUTFH fh1" with PUTROOTFH or PUTPUBFH with no filehandle argument in |
| 22410 |
order to achieve the same effect (on the assumption that "compA" is |
| 22411 |
directly below the root of the namespace). |
| 22412 |
|
| 22413 |
Along with the current filehandle, there is a saved filehandle. |
| 22414 |
While the current filehandle is set as the result of operations like |
| 22415 |
LOOKUP, the saved filehandle must be set directly with the use of the |
| 22416 |
SAVEFH operation. The SAVEFH operation copies the current filehandle |
| 22417 |
value to the saved value. The saved filehandle value is used in |
| 22418 |
combination with the current filehandle value for the LINK and RENAME |
| 22419 |
operations. The RESTOREFH operation will copy the saved filehandle |
| 22420 |
value to the current filehandle value; as a result, the saved |
| 22421 |
filehandle value may be used a sort of "scratch" area for the |
| 22422 |
client's series of operations. |
| 22423 |
|
| 22424 |
<span class="h6"><a class="selflink" id="section-16.2.3.1.2" href="#section-16.2.3.1.2">16.2.3.1.2</a>. Current Stateid</span> |
| 22425 |
|
| 22426 |
With NFSv4.1, additions of a current stateid and a saved stateid have |
| 22427 |
been made to the COMPOUND processing environment; this allows for the |
| 22428 |
passing of stateids between operations. There are no changes to the |
| 22429 |
syntax of the protocol, only changes to the semantics of a few |
| 22430 |
operations. |
| 22431 |
|
| 22432 |
A "current stateid" is the stateid that is associated with the |
| 22433 |
current filehandle. The current stateid may only be changed by an |
| 22434 |
operation that modifies the current filehandle or returns a stateid. |
| 22435 |
|
| 22436 |
If an operation returns a stateid, it MUST set the current stateid to |
| 22437 |
the returned value. If an operation sets the current filehandle but |
| 22438 |
does not return a stateid, the current stateid MUST be set to the |
| 22439 |
all-zeros special stateid, i.e., (seqid, other) = (0, 0). If an |
| 22440 |
operation uses a stateid as an argument but does not return a |
| 22441 |
stateid, the current stateid MUST NOT be changed. For example, |
| 22442 |
PUTFH, PUTROOTFH, and PUTPUBFH will change the current server state |
| 22443 |
from {ocfh, (osid)} to {cfh, (0, 0)}, while LOCK will change the |
| 22444 |
current state from {cfh, (osid} to {cfh, (nsid)}. Operations like |
| 22445 |
LOOKUP that transform a current filehandle and component name into a |
| 22446 |
new current filehandle will also change the current state to {0, 0}. |
| 22447 |
The SAVEFH and RESTOREFH operations will save and restore both the |
| 22448 |
current filehandle and the current stateid as a set. |
| 22449 |
|
| 22450 |
|
| 22451 |
|
| 22452 |
<span class="grey">Shepler, et al. Standards Track [Page 401]</span></pre> |
| 22453 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-402" ></span> |
| 22454 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22455 |
|
| 22456 |
|
| 22457 |
The following example is the common case of a simple READ operation |
| 22458 |
with a normal stateid showing that the PUTFH initializes the current |
| 22459 |
stateid to (0, 0). The subsequent READ with stateid (sid1) leaves |
| 22460 |
the current stateid unchanged. |
| 22461 |
|
| 22462 |
PUTFH fh1 - -> {fh1, (0, 0)} |
| 22463 |
READ (sid1), 0, 1024 {fh1, (0, 0)} -> {fh1, (0, 0)} |
| 22464 |
|
| 22465 |
Figure 3 |
| 22466 |
|
| 22467 |
This next example performs an OPEN with the root filehandle and, as a |
| 22468 |
result, generates stateid (sid1). The next operation specifies the |
| 22469 |
READ with the argument stateid set such that (seqid, other) are equal |
| 22470 |
to (1, 0), but the current stateid set by the previous operation is |
| 22471 |
actually used when the operation is evaluated. This allows correct |
| 22472 |
interaction with any existing, potentially conflicting, locks. |
| 22473 |
|
| 22474 |
PUTROOTFH - -> {fh1, (0, 0)} |
| 22475 |
OPEN "compA" {fh1, (0, 0)} -> {fh2, (sid1)} |
| 22476 |
READ (1, 0), 0, 1024 {fh2, (sid1)} -> {fh2, (sid1)} |
| 22477 |
CLOSE (1, 0) {fh2, (sid1)} -> {fh2, (sid2)} |
| 22478 |
|
| 22479 |
Figure 4 |
| 22480 |
|
| 22481 |
This next example is similar to the second in how it passes the |
| 22482 |
stateid sid2 generated by the LOCK operation to the next READ |
| 22483 |
operation. This allows the client to explicitly surround a single |
| 22484 |
I/O operation with a lock and its appropriate stateid to guarantee |
| 22485 |
correctness with other client locks. The example also shows how |
| 22486 |
SAVEFH and RESTOREFH can save and later reuse a filehandle and |
| 22487 |
stateid, passing them as the current filehandle and stateid to a READ |
| 22488 |
operation. |
| 22489 |
|
| 22490 |
PUTFH fh1 - -> {fh1, (0, 0)} |
| 22491 |
LOCK 0, 1024, (sid1) {fh1, (sid1)} -> {fh1, (sid2)} |
| 22492 |
READ (1, 0), 0, 1024 {fh1, (sid2)} -> {fh1, (sid2)} |
| 22493 |
LOCKU 0, 1024, (1, 0) {fh1, (sid2)} -> {fh1, (sid3)} |
| 22494 |
SAVEFH {fh1, (sid3)} -> {fh1, (sid3)} |
| 22495 |
|
| 22496 |
PUTFH fh2 {fh1, (sid3)} -> {fh2, (0, 0)} |
| 22497 |
WRITE (1, 0), 0, 1024 {fh2, (0, 0)} -> {fh2, (0, 0)} |
| 22498 |
|
| 22499 |
RESTOREFH {fh2, (0, 0)} -> {fh1, (sid3)} |
| 22500 |
READ (1, 0), 1024, 1024 {fh1, (sid3)} -> {fh1, (sid3)} |
| 22501 |
|
| 22502 |
Figure 5 |
| 22503 |
|
| 22504 |
|
| 22505 |
|
| 22506 |
|
| 22507 |
|
| 22508 |
<span class="grey">Shepler, et al. Standards Track [Page 402]</span></pre> |
| 22509 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-403" ></span> |
| 22510 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22511 |
|
| 22512 |
|
| 22513 |
The final example shows a disallowed use of the current stateid. The |
| 22514 |
client is attempting to implicitly pass an anonymous special stateid, |
| 22515 |
(0,0), to the READ operation. The server MUST return |
| 22516 |
NFS4ERR_BAD_STATEID in the reply to the READ operation. |
| 22517 |
|
| 22518 |
PUTFH fh1 - -> {fh1, (0, 0)} |
| 22519 |
READ (1, 0), 0, 1024 {fh1, (0, 0)} -> NFS4ERR_BAD_STATEID |
| 22520 |
|
| 22521 |
Figure 6 |
| 22522 |
|
| 22523 |
<span class="h4"><a class="selflink" id="section-16.2.4" href="#section-16.2.4">16.2.4</a>. ERRORS</span> |
| 22524 |
|
| 22525 |
COMPOUND will of course return every error that each operation on the |
| 22526 |
fore channel can return (see Table 6). However, if COMPOUND returns |
| 22527 |
zero operations, obviously the error returned by COMPOUND has nothing |
| 22528 |
to do with an error returned by an operation. The list of errors |
| 22529 |
COMPOUND will return if it processes zero operations include: |
| 22530 |
|
| 22531 |
COMPOUND Error Returns |
| 22532 |
|
| 22533 |
+------------------------------+------------------------------------+ |
| 22534 |
| Error | Notes | |
| 22535 |
+------------------------------+------------------------------------+ |
| 22536 |
| NFS4ERR_BADCHAR | The tag argument has a character | |
| 22537 |
| | the replier does not support. | |
| 22538 |
| NFS4ERR_BADXDR | | |
| 22539 |
| NFS4ERR_DELAY | | |
| 22540 |
| NFS4ERR_INVAL | The tag argument is not in UTF-8 | |
| 22541 |
| | encoding. | |
| 22542 |
| NFS4ERR_MINOR_VERS_MISMATCH | | |
| 22543 |
| NFS4ERR_SERVERFAULT | | |
| 22544 |
| NFS4ERR_TOO_MANY_OPS | | |
| 22545 |
| NFS4ERR_REP_TOO_BIG | | |
| 22546 |
| NFS4ERR_REP_TOO_BIG_TO_CACHE | | |
| 22547 |
| NFS4ERR_REQ_TOO_BIG | | |
| 22548 |
+------------------------------+------------------------------------+ |
| 22549 |
|
| 22550 |
Table 9 |
| 22551 |
|
| 22552 |
<span class="h2"><a class="selflink" id="section-17" href="#section-17">17</a>. Operations: REQUIRED, RECOMMENDED, or OPTIONAL</span> |
| 22553 |
|
| 22554 |
The following tables summarize the operations of the NFSv4.1 protocol |
| 22555 |
and the corresponding designation of REQUIRED, RECOMMENDED, and |
| 22556 |
OPTIONAL to implement or MUST NOT implement. The designation of MUST |
| 22557 |
NOT implement is reserved for those operations that were defined in |
| 22558 |
NFSv4.0 and MUST NOT be implemented in NFSv4.1. |
| 22559 |
|
| 22560 |
|
| 22561 |
|
| 22562 |
|
| 22563 |
|
| 22564 |
<span class="grey">Shepler, et al. Standards Track [Page 403]</span></pre> |
| 22565 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-404" ></span> |
| 22566 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22567 |
|
| 22568 |
|
| 22569 |
For the most part, the REQUIRED, RECOMMENDED, or OPTIONAL designation |
| 22570 |
for operations sent by the client is for the server implementation. |
| 22571 |
The client is generally required to implement the operations needed |
| 22572 |
for the operating environment for which it serves. For example, a |
| 22573 |
read-only NFSv4.1 client would have no need to implement the WRITE |
| 22574 |
operation and is not required to do so. |
| 22575 |
|
| 22576 |
The REQUIRED or OPTIONAL designation for callback operations sent by |
| 22577 |
the server is for both the client and server. Generally, the client |
| 22578 |
has the option of creating the backchannel and sending the operations |
| 22579 |
on the fore channel that will be a catalyst for the server sending |
| 22580 |
callback operations. A partial exception is CB_RECALL_SLOT; the only |
| 22581 |
way the client can avoid supporting this operation is by not creating |
| 22582 |
a backchannel. |
| 22583 |
|
| 22584 |
Since this is a summary of the operations and their designation, |
| 22585 |
there are subtleties that are not presented here. Therefore, if |
| 22586 |
there is a question of the requirements of implementation, the |
| 22587 |
operation descriptions themselves must be consulted along with other |
| 22588 |
relevant explanatory text within this specification. |
| 22589 |
|
| 22590 |
The abbreviations used in the second and third columns of the table |
| 22591 |
are defined as follows. |
| 22592 |
|
| 22593 |
REQ REQUIRED to implement |
| 22594 |
|
| 22595 |
REC RECOMMEND to implement |
| 22596 |
|
| 22597 |
OPT OPTIONAL to implement |
| 22598 |
|
| 22599 |
MNI MUST NOT implement |
| 22600 |
|
| 22601 |
For the NFSv4.1 features that are OPTIONAL, the operations that |
| 22602 |
support those features are OPTIONAL, and the server would return |
| 22603 |
NFS4ERR_NOTSUPP in response to the client's use of those operations. |
| 22604 |
If an OPTIONAL feature is supported, it is possible that a set of |
| 22605 |
operations related to the feature become REQUIRED to implement. The |
| 22606 |
third column of the table designates the feature(s) and if the |
| 22607 |
operation is REQUIRED or OPTIONAL in the presence of support for the |
| 22608 |
feature. |
| 22609 |
|
| 22610 |
The OPTIONAL features identified and their abbreviations are as |
| 22611 |
follows: |
| 22612 |
|
| 22613 |
pNFS Parallel NFS |
| 22614 |
|
| 22615 |
FDELG File Delegations |
| 22616 |
|
| 22617 |
|
| 22618 |
|
| 22619 |
|
| 22620 |
<span class="grey">Shepler, et al. Standards Track [Page 404]</span></pre> |
| 22621 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-405" ></span> |
| 22622 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22623 |
|
| 22624 |
|
| 22625 |
DDELG Directory Delegations |
| 22626 |
|
| 22627 |
Operations |
| 22628 |
|
| 22629 |
+----------------------+------------+--------------+----------------+ |
| 22630 |
| Operation | REQ, REC, | Feature | Definition | |
| 22631 |
| | OPT, or | (REQ, REC, | | |
| 22632 |
| | MNI | or OPT) | | |
| 22633 |
+----------------------+------------+--------------+----------------+ |
| 22634 |
| ACCESS | REQ | | <a href="#section-18.1">Section 18.1</a> | |
| 22635 |
| BACKCHANNEL_CTL | REQ | | <a href="#section-18.33">Section 18.33</a> | |
| 22636 |
| BIND_CONN_TO_SESSION | REQ | | <a href="#section-18.34">Section 18.34</a> | |
| 22637 |
| CLOSE | REQ | | <a href="#section-18.2">Section 18.2</a> | |
| 22638 |
| COMMIT | REQ | | <a href="#section-18.3">Section 18.3</a> | |
| 22639 |
| CREATE | REQ | | <a href="#section-18.4">Section 18.4</a> | |
| 22640 |
| CREATE_SESSION | REQ | | <a href="#section-18.36">Section 18.36</a> | |
| 22641 |
| DELEGPURGE | OPT | FDELG (REQ) | <a href="#section-18.5">Section 18.5</a> | |
| 22642 |
| DELEGRETURN | OPT | FDELG, | <a href="#section-18.6">Section 18.6</a> | |
| 22643 |
| | | DDELG, pNFS | | |
| 22644 |
| | | (REQ) | | |
| 22645 |
| DESTROY_CLIENTID | REQ | | <a href="#section-18.50">Section 18.50</a> | |
| 22646 |
| DESTROY_SESSION | REQ | | <a href="#section-18.37">Section 18.37</a> | |
| 22647 |
| EXCHANGE_ID | REQ | | <a href="#section-18.35">Section 18.35</a> | |
| 22648 |
| FREE_STATEID | REQ | | <a href="#section-18.38">Section 18.38</a> | |
| 22649 |
| GETATTR | REQ | | <a href="#section-18.7">Section 18.7</a> | |
| 22650 |
| GETDEVICEINFO | OPT | pNFS (REQ) | <a href="#section-18.40">Section 18.40</a> | |
| 22651 |
| GETDEVICELIST | OPT | pNFS (OPT) | <a href="#section-18.41">Section 18.41</a> | |
| 22652 |
| GETFH | REQ | | <a href="#section-18.8">Section 18.8</a> | |
| 22653 |
| GET_DIR_DELEGATION | OPT | DDELG (REQ) | <a href="#section-18.39">Section 18.39</a> | |
| 22654 |
| LAYOUTCOMMIT | OPT | pNFS (REQ) | <a href="#section-18.42">Section 18.42</a> | |
| 22655 |
| LAYOUTGET | OPT | pNFS (REQ) | <a href="#section-18.43">Section 18.43</a> | |
| 22656 |
| LAYOUTRETURN | OPT | pNFS (REQ) | <a href="#section-18.44">Section 18.44</a> | |
| 22657 |
| LINK | OPT | | <a href="#section-18.9">Section 18.9</a> | |
| 22658 |
| LOCK | REQ | | <a href="#section-18.10">Section 18.10</a> | |
| 22659 |
| LOCKT | REQ | | <a href="#section-18.11">Section 18.11</a> | |
| 22660 |
| LOCKU | REQ | | <a href="#section-18.12">Section 18.12</a> | |
| 22661 |
| LOOKUP | REQ | | <a href="#section-18.13">Section 18.13</a> | |
| 22662 |
| LOOKUPP | REQ | | <a href="#section-18.14">Section 18.14</a> | |
| 22663 |
| NVERIFY | REQ | | <a href="#section-18.15">Section 18.15</a> | |
| 22664 |
| OPEN | REQ | | <a href="#section-18.16">Section 18.16</a> | |
| 22665 |
| OPENATTR | OPT | | <a href="#section-18.17">Section 18.17</a> | |
| 22666 |
| OPEN_CONFIRM | MNI | | N/A | |
| 22667 |
| OPEN_DOWNGRADE | REQ | | <a href="#section-18.18">Section 18.18</a> | |
| 22668 |
| PUTFH | REQ | | <a href="#section-18.19">Section 18.19</a> | |
| 22669 |
| PUTPUBFH | REQ | | <a href="#section-18.20">Section 18.20</a> | |
| 22670 |
| PUTROOTFH | REQ | | <a href="#section-18.21">Section 18.21</a> | |
| 22671 |
| READ | REQ | | <a href="#section-18.22">Section 18.22</a> | |
| 22672 |
| READDIR | REQ | | <a href="#section-18.23">Section 18.23</a> | |
| 22673 |
|
| 22674 |
|
| 22675 |
|
| 22676 |
<span class="grey">Shepler, et al. Standards Track [Page 405]</span></pre> |
| 22677 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-406" ></span> |
| 22678 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22679 |
|
| 22680 |
|
| 22681 |
| READLINK | OPT | | <a href="#section-18.24">Section 18.24</a> | |
| 22682 |
| RECLAIM_COMPLETE | REQ | | <a href="#section-18.51">Section 18.51</a> | |
| 22683 |
| RELEASE_LOCKOWNER | MNI | | N/A | |
| 22684 |
| REMOVE | REQ | | <a href="#section-18.25">Section 18.25</a> | |
| 22685 |
| RENAME | REQ | | <a href="#section-18.26">Section 18.26</a> | |
| 22686 |
| RENEW | MNI | | N/A | |
| 22687 |
| RESTOREFH | REQ | | <a href="#section-18.27">Section 18.27</a> | |
| 22688 |
| SAVEFH | REQ | | <a href="#section-18.28">Section 18.28</a> | |
| 22689 |
| SECINFO | REQ | | <a href="#section-18.29">Section 18.29</a> | |
| 22690 |
| SECINFO_NO_NAME | REC | pNFS file | <a href="#section-18.45">Section 18.45</a>, | |
| 22691 |
| | | layout (REQ) | <a href="#section-13.12">Section 13.12</a> | |
| 22692 |
| SEQUENCE | REQ | | <a href="#section-18.46">Section 18.46</a> | |
| 22693 |
| SETATTR | REQ | | <a href="#section-18.30">Section 18.30</a> | |
| 22694 |
| SETCLIENTID | MNI | | N/A | |
| 22695 |
| SETCLIENTID_CONFIRM | MNI | | N/A | |
| 22696 |
| SET_SSV | REQ | | <a href="#section-18.47">Section 18.47</a> | |
| 22697 |
| TEST_STATEID | REQ | | <a href="#section-18.48">Section 18.48</a> | |
| 22698 |
| VERIFY | REQ | | <a href="#section-18.31">Section 18.31</a> | |
| 22699 |
| WANT_DELEGATION | OPT | FDELG (OPT) | <a href="#section-18.49">Section 18.49</a> | |
| 22700 |
| WRITE | REQ | | <a href="#section-18.32">Section 18.32</a> | |
| 22701 |
+----------------------+------------+--------------+----------------+ |
| 22702 |
|
| 22703 |
|
| 22704 |
|
| 22705 |
|
| 22706 |
|
| 22707 |
|
| 22708 |
|
| 22709 |
|
| 22710 |
|
| 22711 |
|
| 22712 |
|
| 22713 |
|
| 22714 |
|
| 22715 |
|
| 22716 |
|
| 22717 |
|
| 22718 |
|
| 22719 |
|
| 22720 |
|
| 22721 |
|
| 22722 |
|
| 22723 |
|
| 22724 |
|
| 22725 |
|
| 22726 |
|
| 22727 |
|
| 22728 |
|
| 22729 |
|
| 22730 |
|
| 22731 |
|
| 22732 |
<span class="grey">Shepler, et al. Standards Track [Page 406]</span></pre> |
| 22733 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-407" ></span> |
| 22734 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22735 |
|
| 22736 |
|
| 22737 |
Callback Operations |
| 22738 |
|
| 22739 |
+-------------------------+-----------+-------------+---------------+ |
| 22740 |
| Operation | REQ, REC, | Feature | Definition | |
| 22741 |
| | OPT, or | (REQ, REC, | | |
| 22742 |
| | MNI | or OPT) | | |
| 22743 |
+-------------------------+-----------+-------------+---------------+ |
| 22744 |
| CB_GETATTR | OPT | FDELG (REQ) | <a href="#section-20.1">Section 20.1</a> | |
| 22745 |
| CB_LAYOUTRECALL | OPT | pNFS (REQ) | <a href="#section-20.3">Section 20.3</a> | |
| 22746 |
| CB_NOTIFY | OPT | DDELG (REQ) | <a href="#section-20.4">Section 20.4</a> | |
| 22747 |
| CB_NOTIFY_DEVICEID | OPT | pNFS (OPT) | <a href="#section-20.12">Section 20.12</a> | |
| 22748 |
| CB_NOTIFY_LOCK | OPT | | <a href="#section-20.11">Section 20.11</a> | |
| 22749 |
| CB_PUSH_DELEG | OPT | FDELG (OPT) | <a href="#section-20.5">Section 20.5</a> | |
| 22750 |
| CB_RECALL | OPT | FDELG, | <a href="#section-20.2">Section 20.2</a> | |
| 22751 |
| | | DDELG, pNFS | | |
| 22752 |
| | | (REQ) | | |
| 22753 |
| CB_RECALL_ANY | OPT | FDELG, | <a href="#section-20.6">Section 20.6</a> | |
| 22754 |
| | | DDELG, pNFS | | |
| 22755 |
| | | (REQ) | | |
| 22756 |
| CB_RECALL_SLOT | REQ | | <a href="#section-20.8">Section 20.8</a> | |
| 22757 |
| CB_RECALLABLE_OBJ_AVAIL | OPT | DDELG, pNFS | <a href="#section-20.7">Section 20.7</a> | |
| 22758 |
| | | (REQ) | | |
| 22759 |
| CB_SEQUENCE | OPT | FDELG, | <a href="#section-20.9">Section 20.9</a> | |
| 22760 |
| | | DDELG, pNFS | | |
| 22761 |
| | | (REQ) | | |
| 22762 |
| CB_WANTS_CANCELLED | OPT | FDELG, | <a href="#section-20.10">Section 20.10</a> | |
| 22763 |
| | | DDELG, pNFS | | |
| 22764 |
| | | (REQ) | | |
| 22765 |
+-------------------------+-----------+-------------+---------------+ |
| 22766 |
|
| 22767 |
<span class="h2"><a class="selflink" id="section-18" href="#section-18">18</a>. NFSv4.1 Operations</span> |
| 22768 |
|
| 22769 |
<span class="h3"><a class="selflink" id="section-18.1" href="#section-18.1">18.1</a>. Operation 3: ACCESS - Check Access Rights</span> |
| 22770 |
|
| 22771 |
<span class="h4"><a class="selflink" id="section-18.1.1" href="#section-18.1.1">18.1.1</a>. ARGUMENTS</span> |
| 22772 |
|
| 22773 |
|
| 22774 |
const ACCESS4_READ = 0x00000001; |
| 22775 |
const ACCESS4_LOOKUP = 0x00000002; |
| 22776 |
const ACCESS4_MODIFY = 0x00000004; |
| 22777 |
const ACCESS4_EXTEND = 0x00000008; |
| 22778 |
const ACCESS4_DELETE = 0x00000010; |
| 22779 |
const ACCESS4_EXECUTE = 0x00000020; |
| 22780 |
|
| 22781 |
struct ACCESS4args { |
| 22782 |
/* CURRENT_FH: object */ |
| 22783 |
uint32_t access; |
| 22784 |
}; |
| 22785 |
|
| 22786 |
|
| 22787 |
|
| 22788 |
<span class="grey">Shepler, et al. Standards Track [Page 407]</span></pre> |
| 22789 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-408" ></span> |
| 22790 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22791 |
|
| 22792 |
|
| 22793 |
<span class="h4"><a class="selflink" id="section-18.1.2" href="#section-18.1.2">18.1.2</a>. RESULTS</span> |
| 22794 |
|
| 22795 |
struct ACCESS4resok { |
| 22796 |
uint32_t supported; |
| 22797 |
uint32_t access; |
| 22798 |
}; |
| 22799 |
|
| 22800 |
union ACCESS4res switch (nfsstat4 status) { |
| 22801 |
case NFS4_OK: |
| 22802 |
ACCESS4resok resok4; |
| 22803 |
default: |
| 22804 |
void; |
| 22805 |
}; |
| 22806 |
|
| 22807 |
|
| 22808 |
<span class="h4"><a class="selflink" id="section-18.1.3" href="#section-18.1.3">18.1.3</a>. DESCRIPTION</span> |
| 22809 |
|
| 22810 |
ACCESS determines the access rights that a user, as identified by the |
| 22811 |
credentials in the RPC request, has with respect to the file system |
| 22812 |
object specified by the current filehandle. The client encodes the |
| 22813 |
set of access rights that are to be checked in the bit mask "access". |
| 22814 |
The server checks the permissions encoded in the bit mask. If a |
| 22815 |
status of NFS4_OK is returned, two bit masks are included in the |
| 22816 |
response. The first, "supported", represents the access rights for |
| 22817 |
which the server can verify reliably. The second, "access", |
| 22818 |
represents the access rights available to the user for the filehandle |
| 22819 |
provided. On success, the current filehandle retains its value. |
| 22820 |
|
| 22821 |
Note that the reply's supported and access fields MUST NOT contain |
| 22822 |
more values than originally set in the request's access field. For |
| 22823 |
example, if the client sends an ACCESS operation with just the |
| 22824 |
ACCESS4_READ value set and the server supports this value, the server |
| 22825 |
MUST NOT set more than ACCESS4_READ in the supported field even if it |
| 22826 |
could have reliably checked other values. |
| 22827 |
|
| 22828 |
The reply's access field MUST NOT contain more values than the |
| 22829 |
supported field. |
| 22830 |
|
| 22831 |
The results of this operation are necessarily advisory in nature. A |
| 22832 |
return status of NFS4_OK and the appropriate bit set in the bit mask |
| 22833 |
do not imply that such access will be allowed to the file system |
| 22834 |
object in the future. This is because access rights can be revoked |
| 22835 |
by the server at any time. |
| 22836 |
|
| 22837 |
The following access permissions may be requested: |
| 22838 |
|
| 22839 |
ACCESS4_READ Read data from file or read a directory. |
| 22840 |
|
| 22841 |
|
| 22842 |
|
| 22843 |
|
| 22844 |
<span class="grey">Shepler, et al. Standards Track [Page 408]</span></pre> |
| 22845 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-409" ></span> |
| 22846 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22847 |
|
| 22848 |
|
| 22849 |
ACCESS4_LOOKUP Look up a name in a directory (no meaning for non- |
| 22850 |
directory objects). |
| 22851 |
|
| 22852 |
ACCESS4_MODIFY Rewrite existing file data or modify existing |
| 22853 |
directory entries. |
| 22854 |
|
| 22855 |
ACCESS4_EXTEND Write new data or add directory entries. |
| 22856 |
|
| 22857 |
ACCESS4_DELETE Delete an existing directory entry. |
| 22858 |
|
| 22859 |
ACCESS4_EXECUTE Execute a regular file (no meaning for a directory). |
| 22860 |
|
| 22861 |
On success, the current filehandle retains its value. |
| 22862 |
|
| 22863 |
ACCESS4_EXECUTE is a challenging semantic to implement because NFS |
| 22864 |
provides remote file access, not remote execution. This leads to the |
| 22865 |
following: |
| 22866 |
|
| 22867 |
o Whether or not a regular file is executable ought to be the |
| 22868 |
responsibility of the NFS client and not the server. And yet the |
| 22869 |
ACCESS operation is specified to seemingly require a server to own |
| 22870 |
that responsibility. |
| 22871 |
|
| 22872 |
o When a client executes a regular file, it has to read the file |
| 22873 |
from the server. Strictly speaking, the server should not allow |
| 22874 |
the client to read a file being executed unless the user has read |
| 22875 |
permissions on the file. Requiring explicit read permissions on |
| 22876 |
executable files in order to access them over NFS is not going to |
| 22877 |
be acceptable to some users and storage administrators. |
| 22878 |
Historically, NFS servers have allowed a user to READ a file if |
| 22879 |
the user has execute access to the file. |
| 22880 |
|
| 22881 |
As a practical example, the UNIX specification [<a href="#ref-52" title=""The Open Group Base Specifications Issue 6, IEEE Std 1003.1, 2004 Edition"">52</a>] states that an |
| 22882 |
implementation claiming conformance to UNIX may indicate in the |
| 22883 |
access() programming interface's result that a privileged user has |
| 22884 |
execute rights, even if no execute permission bits are set on the |
| 22885 |
regular file's attributes. It is possible to claim conformance to |
| 22886 |
the UNIX specification and instead not indicate execute rights in |
| 22887 |
that situation, which is true for some operating environments. |
| 22888 |
Suppose the operating environments of the client and server are |
| 22889 |
implementing the access() semantics for privileged users differently, |
| 22890 |
and the ACCESS operation implementations of the client and server |
| 22891 |
follow their respective access() semantics. This can cause undesired |
| 22892 |
behavior: |
| 22893 |
|
| 22894 |
o Suppose the client's access() interface returns X_OK if the user |
| 22895 |
is privileged and no execute permission bits are set on the |
| 22896 |
regular file's attribute, and the server's access() interface does |
| 22897 |
|
| 22898 |
|
| 22899 |
|
| 22900 |
<span class="grey">Shepler, et al. Standards Track [Page 409]</span></pre> |
| 22901 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-410" ></span> |
| 22902 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22903 |
|
| 22904 |
|
| 22905 |
not return X_OK in that situation. Then the client will be unable |
| 22906 |
to execute files stored on the NFS server that could be executed |
| 22907 |
if stored on a non-NFS file system. |
| 22908 |
|
| 22909 |
o Suppose the client's access() interface does not return X_OK if |
| 22910 |
the user is privileged, and no execute permission bits are set on |
| 22911 |
the regular file's attribute, and the server's access() interface |
| 22912 |
does return X_OK in that situation. Then: |
| 22913 |
|
| 22914 |
* The client will be able to execute files stored on the NFS |
| 22915 |
server that could be executed if stored on a non-NFS file |
| 22916 |
system, unless the client's execution subsystem also checks for |
| 22917 |
execute permission bits. |
| 22918 |
|
| 22919 |
* Even if the execution subsystem is checking for execute |
| 22920 |
permission bits, there are more potential issues. For example, |
| 22921 |
suppose the client is invoking access() to build a "path search |
| 22922 |
table" of all executable files in the user's "search path", |
| 22923 |
where the path is a list of directories each containing |
| 22924 |
executable files. Suppose there are two files each in separate |
| 22925 |
directories of the search path, such that files have the same |
| 22926 |
component name. In the first directory the file has no execute |
| 22927 |
permission bits set, and in the second directory the file has |
| 22928 |
execute bits set. The path search table will indicate that the |
| 22929 |
first directory has the executable file, but the execute |
| 22930 |
subsystem will fail to execute it. The command shell might |
| 22931 |
fail to try the second file in the second directory. And even |
| 22932 |
if it did, this is a potential performance issue. Clearly, the |
| 22933 |
desired outcome for the client is for the path search table to |
| 22934 |
not contain the first file. |
| 22935 |
|
| 22936 |
To deal with the problems described above, the "smart client, stupid |
| 22937 |
server" principle is used. The client owns overall responsibility |
| 22938 |
for determining execute access and relies on the server to parse the |
| 22939 |
execution permissions within the file's mode, acl, and dacl |
| 22940 |
attributes. The rules for the client and server follow: |
| 22941 |
|
| 22942 |
o If the client is sending ACCESS in order to determine if the user |
| 22943 |
can read the file, the client SHOULD set ACCESS4_READ in the |
| 22944 |
request's access field. |
| 22945 |
|
| 22946 |
o If the client's operating environment only grants execution to the |
| 22947 |
user if the user has execute access according to the execute |
| 22948 |
permissions in the mode, acl, and dacl attributes, then if the |
| 22949 |
client wants to determine execute access, the client SHOULD send |
| 22950 |
an ACCESS request with ACCESS4_EXECUTE bit set in the request's |
| 22951 |
access field. |
| 22952 |
|
| 22953 |
|
| 22954 |
|
| 22955 |
|
| 22956 |
<span class="grey">Shepler, et al. Standards Track [Page 410]</span></pre> |
| 22957 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-411" ></span> |
| 22958 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 22959 |
|
| 22960 |
|
| 22961 |
o If the client's operating environment grants execution to the user |
| 22962 |
even if the user does not have execute access according to the |
| 22963 |
execute permissions in the mode, acl, and dacl attributes, then if |
| 22964 |
the client wants to determine execute access, it SHOULD send an |
| 22965 |
ACCESS request with both the ACCESS4_EXECUTE and ACCESS4_READ bits |
| 22966 |
set in the request's access field. This way, if any read or |
| 22967 |
execute permission grants the user read or execute access (or if |
| 22968 |
the server interprets the user as privileged), as indicated by the |
| 22969 |
presence of ACCESS4_EXECUTE and/or ACCESS4_READ in the reply's |
| 22970 |
access field, the client will be able to grant the user execute |
| 22971 |
access to the file. |
| 22972 |
|
| 22973 |
o If the server supports execute permission bits, or some other |
| 22974 |
method for denoting executability (e.g., the suffix of the name of |
| 22975 |
the file might indicate execute), it MUST check only execute |
| 22976 |
permissions, not read permissions, when determining whether or not |
| 22977 |
the reply will have ACCESS4_EXECUTE set in the access field. The |
| 22978 |
server MUST NOT also examine read permission bits when determining |
| 22979 |
whether or not the reply will have ACCESS4_EXECUTE set in the |
| 22980 |
access field. Even if the server's operating environment would |
| 22981 |
grant execute access to the user (e.g., the user is privileged), |
| 22982 |
the server MUST NOT reply with ACCESS4_EXECUTE set in reply's |
| 22983 |
access field unless there is at least one execute permission bit |
| 22984 |
set in the mode, acl, or dacl attributes. In the case of acl and |
| 22985 |
dacl, the "one execute permission bit" MUST be an ACE4_EXECUTE bit |
| 22986 |
set in an ALLOW ACE. |
| 22987 |
|
| 22988 |
o If the server does not support execute permission bits or some |
| 22989 |
other method for denoting executability, it MUST NOT set |
| 22990 |
ACCESS4_EXECUTE in the reply's supported and access fields. If |
| 22991 |
the client set ACCESS4_EXECUTE in the ACCESS request's access |
| 22992 |
field, and ACCESS4_EXECUTE is not set in the reply's supported |
| 22993 |
field, then the client will have to send an ACCESS request with |
| 22994 |
the ACCESS4_READ bit set in the request's access field. |
| 22995 |
|
| 22996 |
o If the server supports read permission bits, it MUST only check |
| 22997 |
for read permissions in the mode, acl, and dacl attributes when it |
| 22998 |
receives an ACCESS request with ACCESS4_READ set in the access |
| 22999 |
field. The server MUST NOT also examine execute permission bits |
| 23000 |
when determining whether the reply will have ACCESS4_READ set in |
| 23001 |
the access field or not. |
| 23002 |
|
| 23003 |
Note that if the ACCESS reply has ACCESS4_READ or ACCESS_EXECUTE set, |
| 23004 |
then the user also has permissions to OPEN (<a href="#section-18.16">Section 18.16</a>) or READ |
| 23005 |
(<a href="#section-18.22">Section 18.22</a>) the file. In other words, if the client sends an |
| 23006 |
ACCESS request with the ACCESS4_READ and ACCESS_EXECUTE set in the |
| 23007 |
access field (or two separate requests, one with ACCESS4_READ set and |
| 23008 |
the other with ACCESS4_EXECUTE set), and the reply has just |
| 23009 |
|
| 23010 |
|
| 23011 |
|
| 23012 |
<span class="grey">Shepler, et al. Standards Track [Page 411]</span></pre> |
| 23013 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-412" ></span> |
| 23014 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23015 |
|
| 23016 |
|
| 23017 |
ACCESS4_EXECUTE set in the access field (or just one reply has |
| 23018 |
ACCESS4_EXECUTE set), then the user has authorization to OPEN or READ |
| 23019 |
the file. |
| 23020 |
|
| 23021 |
<span class="h4"><a class="selflink" id="section-18.1.4" href="#section-18.1.4">18.1.4</a>. IMPLEMENTATION</span> |
| 23022 |
|
| 23023 |
In general, it is not sufficient for the client to attempt to deduce |
| 23024 |
access permissions by inspecting the uid, gid, and mode fields in the |
| 23025 |
file attributes or by attempting to interpret the contents of the ACL |
| 23026 |
attribute. This is because the server may perform uid or gid mapping |
| 23027 |
or enforce additional access-control restrictions. It is also |
| 23028 |
possible that the server may not be in the same ID space as the |
| 23029 |
client. In these cases (and perhaps others), the client cannot |
| 23030 |
reliably perform an access check with only current file attributes. |
| 23031 |
|
| 23032 |
In the NFSv2 protocol, the only reliable way to determine whether an |
| 23033 |
operation was allowed was to try it and see if it succeeded or |
| 23034 |
failed. Using the ACCESS operation in the NFSv4.1 protocol, the |
| 23035 |
client can ask the server to indicate whether or not one or more |
| 23036 |
classes of operations are permitted. The ACCESS operation is |
| 23037 |
provided to allow clients to check before doing a series of |
| 23038 |
operations that will result in an access failure. The OPEN operation |
| 23039 |
provides a point where the server can verify access to the file |
| 23040 |
object and a method to return that information to the client. The |
| 23041 |
ACCESS operation is still useful for directory operations or for use |
| 23042 |
in the case that the UNIX interface access() is used on the client. |
| 23043 |
|
| 23044 |
The information returned by the server in response to an ACCESS call |
| 23045 |
is not permanent. It was correct at the exact time that the server |
| 23046 |
performed the checks, but not necessarily afterwards. The server can |
| 23047 |
revoke access permission at any time. |
| 23048 |
|
| 23049 |
The client should use the effective credentials of the user to build |
| 23050 |
the authentication information in the ACCESS request used to |
| 23051 |
determine access rights. It is the effective user and group |
| 23052 |
credentials that are used in subsequent READ and WRITE operations. |
| 23053 |
|
| 23054 |
Many implementations do not directly support the ACCESS4_DELETE |
| 23055 |
permission. Operating systems like UNIX will ignore the |
| 23056 |
ACCESS4_DELETE bit if set on an access request on a non-directory |
| 23057 |
object. In these systems, delete permission on a file is determined |
| 23058 |
by the access permissions on the directory in which the file resides, |
| 23059 |
instead of being determined by the permissions of the file itself. |
| 23060 |
Therefore, the mask returned enumerating which access rights can be |
| 23061 |
determined will have the ACCESS4_DELETE value set to 0. This |
| 23062 |
indicates to the client that the server was unable to check that |
| 23063 |
particular access right. The ACCESS4_DELETE bit in the access mask |
| 23064 |
returned will then be ignored by the client. |
| 23065 |
|
| 23066 |
|
| 23067 |
|
| 23068 |
<span class="grey">Shepler, et al. Standards Track [Page 412]</span></pre> |
| 23069 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-413" ></span> |
| 23070 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23071 |
|
| 23072 |
|
| 23073 |
<span class="h3"><a class="selflink" id="section-18.2" href="#section-18.2">18.2</a>. Operation 4: CLOSE - Close File</span> |
| 23074 |
|
| 23075 |
<span class="h4"><a class="selflink" id="section-18.2.1" href="#section-18.2.1">18.2.1</a>. ARGUMENTS</span> |
| 23076 |
|
| 23077 |
struct CLOSE4args { |
| 23078 |
/* CURRENT_FH: object */ |
| 23079 |
seqid4 seqid; |
| 23080 |
stateid4 open_stateid; |
| 23081 |
}; |
| 23082 |
|
| 23083 |
|
| 23084 |
<span class="h4"><a class="selflink" id="section-18.2.2" href="#section-18.2.2">18.2.2</a>. RESULTS</span> |
| 23085 |
|
| 23086 |
union CLOSE4res switch (nfsstat4 status) { |
| 23087 |
case NFS4_OK: |
| 23088 |
stateid4 open_stateid; |
| 23089 |
default: |
| 23090 |
void; |
| 23091 |
}; |
| 23092 |
|
| 23093 |
|
| 23094 |
<span class="h4"><a class="selflink" id="section-18.2.3" href="#section-18.2.3">18.2.3</a>. DESCRIPTION</span> |
| 23095 |
|
| 23096 |
The CLOSE operation releases share reservations for the regular or |
| 23097 |
named attribute file as specified by the current filehandle. The |
| 23098 |
share reservations and other state information released at the server |
| 23099 |
as a result of this CLOSE are only those associated with the supplied |
| 23100 |
stateid. State associated with other OPENs is not affected. |
| 23101 |
|
| 23102 |
If byte-range locks are held, the client SHOULD release all locks |
| 23103 |
before sending a CLOSE. The server MAY free all outstanding locks on |
| 23104 |
CLOSE, but some servers may not support the CLOSE of a file that |
| 23105 |
still has byte-range locks held. The server MUST return failure if |
| 23106 |
any locks would exist after the CLOSE. |
| 23107 |
|
| 23108 |
The argument seqid MAY have any value, and the server MUST ignore |
| 23109 |
seqid. |
| 23110 |
|
| 23111 |
On success, the current filehandle retains its value. |
| 23112 |
|
| 23113 |
The server MAY require that the combination of principal, security |
| 23114 |
flavor, and, if applicable, GSS mechanism that sent the OPEN request |
| 23115 |
also be the one to CLOSE the file. This might not be possible if |
| 23116 |
credentials for the principal are no longer available. The server |
| 23117 |
MAY allow the machine credential or SSV credential (see |
| 23118 |
<a href="#section-18.35">Section 18.35</a>) to send CLOSE. |
| 23119 |
|
| 23120 |
|
| 23121 |
|
| 23122 |
|
| 23123 |
|
| 23124 |
<span class="grey">Shepler, et al. Standards Track [Page 413]</span></pre> |
| 23125 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-414" ></span> |
| 23126 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23127 |
|
| 23128 |
|
| 23129 |
<span class="h4"><a class="selflink" id="section-18.2.4" href="#section-18.2.4">18.2.4</a>. IMPLEMENTATION</span> |
| 23130 |
|
| 23131 |
Even though CLOSE returns a stateid, this stateid is not useful to |
| 23132 |
the client and should be treated as deprecated. CLOSE "shuts down" |
| 23133 |
the state associated with all OPENs for the file by a single open- |
| 23134 |
owner. As noted above, CLOSE will either release all file-locking |
| 23135 |
state or return an error. Therefore, the stateid returned by CLOSE |
| 23136 |
is not useful for operations that follow. To help find any uses of |
| 23137 |
this stateid by clients, the server SHOULD return the invalid special |
| 23138 |
stateid (the "other" value is zero and the "seqid" field is |
| 23139 |
NFS4_UINT32_MAX, see <a href="#section-8.2.3">Section 8.2.3</a>). |
| 23140 |
|
| 23141 |
A CLOSE operation may make delegations grantable where they were not |
| 23142 |
previously. Servers may choose to respond immediately if there are |
| 23143 |
pending delegation want requests or may respond to the situation at a |
| 23144 |
later time. |
| 23145 |
|
| 23146 |
<span class="h3"><a class="selflink" id="section-18.3" href="#section-18.3">18.3</a>. Operation 5: COMMIT - Commit Cached Data</span> |
| 23147 |
|
| 23148 |
<span class="h4"><a class="selflink" id="section-18.3.1" href="#section-18.3.1">18.3.1</a>. ARGUMENTS</span> |
| 23149 |
|
| 23150 |
struct COMMIT4args { |
| 23151 |
/* CURRENT_FH: file */ |
| 23152 |
offset4 offset; |
| 23153 |
count4 count; |
| 23154 |
}; |
| 23155 |
|
| 23156 |
<span class="h4"><a class="selflink" id="section-18.3.2" href="#section-18.3.2">18.3.2</a>. RESULTS</span> |
| 23157 |
|
| 23158 |
struct COMMIT4resok { |
| 23159 |
verifier4 writeverf; |
| 23160 |
}; |
| 23161 |
|
| 23162 |
union COMMIT4res switch (nfsstat4 status) { |
| 23163 |
case NFS4_OK: |
| 23164 |
COMMIT4resok resok4; |
| 23165 |
default: |
| 23166 |
void; |
| 23167 |
}; |
| 23168 |
|
| 23169 |
|
| 23170 |
|
| 23171 |
|
| 23172 |
|
| 23173 |
|
| 23174 |
|
| 23175 |
|
| 23176 |
|
| 23177 |
|
| 23178 |
|
| 23179 |
|
| 23180 |
<span class="grey">Shepler, et al. Standards Track [Page 414]</span></pre> |
| 23181 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-415" ></span> |
| 23182 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23183 |
|
| 23184 |
|
| 23185 |
<span class="h4"><a class="selflink" id="section-18.3.3" href="#section-18.3.3">18.3.3</a>. DESCRIPTION</span> |
| 23186 |
|
| 23187 |
The COMMIT operation forces or flushes uncommitted, modified data to |
| 23188 |
stable storage for the file specified by the current filehandle. The |
| 23189 |
flushed data is that which was previously written with one or more |
| 23190 |
WRITE operations that had the "committed" field of their results |
| 23191 |
field set to UNSTABLE4. |
| 23192 |
|
| 23193 |
The offset specifies the position within the file where the flush is |
| 23194 |
to begin. An offset value of zero means to flush data starting at |
| 23195 |
the beginning of the file. The count specifies the number of bytes |
| 23196 |
of data to flush. If the count is zero, a flush from the offset to |
| 23197 |
the end of the file is done. |
| 23198 |
|
| 23199 |
The server returns a write verifier upon successful completion of the |
| 23200 |
COMMIT. The write verifier is used by the client to determine if the |
| 23201 |
server has restarted between the initial WRITE operations and the |
| 23202 |
COMMIT. The client does this by comparing the write verifier |
| 23203 |
returned from the initial WRITE operations and the verifier returned |
| 23204 |
by the COMMIT operation. The server must vary the value of the write |
| 23205 |
verifier at each server event or instantiation that may lead to a |
| 23206 |
loss of uncommitted data. Most commonly this occurs when the server |
| 23207 |
is restarted; however, other events at the server may result in |
| 23208 |
uncommitted data loss as well. |
| 23209 |
|
| 23210 |
On success, the current filehandle retains its value. |
| 23211 |
|
| 23212 |
<span class="h4"><a class="selflink" id="section-18.3.4" href="#section-18.3.4">18.3.4</a>. IMPLEMENTATION</span> |
| 23213 |
|
| 23214 |
The COMMIT operation is similar in operation and semantics to the |
| 23215 |
POSIX fsync() [<a href="#ref-25" title="">25</a>] system interface that synchronizes a file's state |
| 23216 |
with the disk (file data and metadata is flushed to disk or stable |
| 23217 |
storage). COMMIT performs the same operation for a client, flushing |
| 23218 |
any unsynchronized data and metadata on the server to the server's |
| 23219 |
disk or stable storage for the specified file. Like fsync(), it may |
| 23220 |
be that there is some modified data or no modified data to |
| 23221 |
synchronize. The data may have been synchronized by the server's |
| 23222 |
normal periodic buffer synchronization activity. COMMIT should |
| 23223 |
return NFS4_OK, unless there has been an unexpected error. |
| 23224 |
|
| 23225 |
COMMIT differs from fsync() in that it is possible for the client to |
| 23226 |
flush a range of the file (most likely triggered by a buffer- |
| 23227 |
reclamation scheme on the client before the file has been completely |
| 23228 |
written). |
| 23229 |
|
| 23230 |
The server implementation of COMMIT is reasonably simple. If the |
| 23231 |
server receives a full file COMMIT request, that is, starting at |
| 23232 |
offset zero and count zero, it should do the equivalent of applying |
| 23233 |
|
| 23234 |
|
| 23235 |
|
| 23236 |
<span class="grey">Shepler, et al. Standards Track [Page 415]</span></pre> |
| 23237 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-416" ></span> |
| 23238 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23239 |
|
| 23240 |
|
| 23241 |
fsync() to the entire file. Otherwise, it should arrange to have the |
| 23242 |
modified data in the range specified by offset and count to be |
| 23243 |
flushed to stable storage. In both cases, any metadata associated |
| 23244 |
with the file must be flushed to stable storage before returning. It |
| 23245 |
is not an error for there to be nothing to flush on the server. This |
| 23246 |
means that the data and metadata that needed to be flushed have |
| 23247 |
already been flushed or lost during the last server failure. |
| 23248 |
|
| 23249 |
The client implementation of COMMIT is a little more complex. There |
| 23250 |
are two reasons for wanting to commit a client buffer to stable |
| 23251 |
storage. The first is that the client wants to reuse a buffer. In |
| 23252 |
this case, the offset and count of the buffer are sent to the server |
| 23253 |
in the COMMIT request. The server then flushes any modified data |
| 23254 |
based on the offset and count, and flushes any modified metadata |
| 23255 |
associated with the file. It then returns the status of the flush |
| 23256 |
and the write verifier. The second reason for the client to generate |
| 23257 |
a COMMIT is for a full file flush, such as may be done at close. In |
| 23258 |
this case, the client would gather all of the buffers for this file |
| 23259 |
that contain uncommitted data, do the COMMIT operation with an offset |
| 23260 |
of zero and count of zero, and then free all of those buffers. Any |
| 23261 |
other dirty buffers would be sent to the server in the normal |
| 23262 |
fashion. |
| 23263 |
|
| 23264 |
After a buffer is written (via the WRITE operation) by the client |
| 23265 |
with the "committed" field in the result of WRITE set to UNSTABLE4, |
| 23266 |
the buffer must be considered as modified by the client until the |
| 23267 |
buffer has either been flushed via a COMMIT operation or written via |
| 23268 |
a WRITE operation with the "committed" field in the result set to |
| 23269 |
FILE_SYNC4 or DATA_SYNC4. This is done to prevent the buffer from |
| 23270 |
being freed and reused before the data can be flushed to stable |
| 23271 |
storage on the server. |
| 23272 |
|
| 23273 |
When a response is returned from either a WRITE or a COMMIT operation |
| 23274 |
and it contains a write verifier that differs from that previously |
| 23275 |
returned by the server, the client will need to retransmit all of the |
| 23276 |
buffers containing uncommitted data to the server. How this is to be |
| 23277 |
done is up to the implementor. If there is only one buffer of |
| 23278 |
interest, then it should be sent in a WRITE request with the |
| 23279 |
FILE_SYNC4 stable parameter. If there is more than one buffer, it |
| 23280 |
might be worthwhile retransmitting all of the buffers in WRITE |
| 23281 |
operations with the stable parameter set to UNSTABLE4 and then |
| 23282 |
retransmitting the COMMIT operation to flush all of the data on the |
| 23283 |
server to stable storage. However, if the server repeatably returns |
| 23284 |
from COMMIT a verifier that differs from that returned by WRITE, the |
| 23285 |
only way to ensure progress is to retransmit all of the buffers with |
| 23286 |
WRITE requests with the FILE_SYNC4 stable parameter. |
| 23287 |
|
| 23288 |
|
| 23289 |
|
| 23290 |
|
| 23291 |
|
| 23292 |
<span class="grey">Shepler, et al. Standards Track [Page 416]</span></pre> |
| 23293 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-417" ></span> |
| 23294 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23295 |
|
| 23296 |
|
| 23297 |
The above description applies to page-cache-based systems as well as |
| 23298 |
buffer-cache-based systems. In the former systems, the virtual |
| 23299 |
memory system will need to be modified instead of the buffer cache. |
| 23300 |
|
| 23301 |
<span class="h3"><a class="selflink" id="section-18.4" href="#section-18.4">18.4</a>. Operation 6: CREATE - Create a Non-Regular File Object</span> |
| 23302 |
|
| 23303 |
<span class="h4"><a class="selflink" id="section-18.4.1" href="#section-18.4.1">18.4.1</a>. ARGUMENTS</span> |
| 23304 |
|
| 23305 |
union createtype4 switch (nfs_ftype4 type) { |
| 23306 |
case NF4LNK: |
| 23307 |
linktext4 linkdata; |
| 23308 |
case NF4BLK: |
| 23309 |
case NF4CHR: |
| 23310 |
specdata4 devdata; |
| 23311 |
case NF4SOCK: |
| 23312 |
case NF4FIFO: |
| 23313 |
case NF4DIR: |
| 23314 |
void; |
| 23315 |
default: |
| 23316 |
void; /* server should return NFS4ERR_BADTYPE */ |
| 23317 |
}; |
| 23318 |
|
| 23319 |
struct CREATE4args { |
| 23320 |
/* CURRENT_FH: directory for creation */ |
| 23321 |
createtype4 objtype; |
| 23322 |
component4 objname; |
| 23323 |
fattr4 createattrs; |
| 23324 |
}; |
| 23325 |
|
| 23326 |
<span class="h4"><a class="selflink" id="section-18.4.2" href="#section-18.4.2">18.4.2</a>. RESULTS</span> |
| 23327 |
|
| 23328 |
struct CREATE4resok { |
| 23329 |
change_info4 cinfo; |
| 23330 |
bitmap4 attrset; /* attributes set */ |
| 23331 |
}; |
| 23332 |
|
| 23333 |
union CREATE4res switch (nfsstat4 status) { |
| 23334 |
case NFS4_OK: |
| 23335 |
/* new CURRENTFH: created object */ |
| 23336 |
CREATE4resok resok4; |
| 23337 |
default: |
| 23338 |
void; |
| 23339 |
}; |
| 23340 |
|
| 23341 |
|
| 23342 |
|
| 23343 |
|
| 23344 |
|
| 23345 |
|
| 23346 |
|
| 23347 |
|
| 23348 |
<span class="grey">Shepler, et al. Standards Track [Page 417]</span></pre> |
| 23349 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-418" ></span> |
| 23350 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23351 |
|
| 23352 |
|
| 23353 |
<span class="h4"><a class="selflink" id="section-18.4.3" href="#section-18.4.3">18.4.3</a>. DESCRIPTION</span> |
| 23354 |
|
| 23355 |
The CREATE operation creates a file object other than an ordinary |
| 23356 |
file in a directory with a given name. The OPEN operation MUST be |
| 23357 |
used to create a regular file or a named attribute. |
| 23358 |
|
| 23359 |
The current filehandle must be a directory: an object of type NF4DIR. |
| 23360 |
If the current filehandle is an attribute directory (type |
| 23361 |
NF4ATTRDIR), the error NFS4ERR_WRONG_TYPE is returned. If the |
| 23362 |
current file handle designates any other type of object, the error |
| 23363 |
NFS4ERR_NOTDIR results. |
| 23364 |
|
| 23365 |
The objname specifies the name for the new object. The objtype |
| 23366 |
determines the type of object to be created: directory, symlink, etc. |
| 23367 |
If the object type specified is that of an ordinary file, a named |
| 23368 |
attribute, or a named attribute directory, the error NFS4ERR_BADTYPE |
| 23369 |
results. |
| 23370 |
|
| 23371 |
If an object of the same name already exists in the directory, the |
| 23372 |
server will return the error NFS4ERR_EXIST. |
| 23373 |
|
| 23374 |
For the directory where the new file object was created, the server |
| 23375 |
returns change_info4 information in cinfo. With the atomic field of |
| 23376 |
the change_info4 data type, the server will indicate if the before |
| 23377 |
and after change attributes were obtained atomically with respect to |
| 23378 |
the file object creation. |
| 23379 |
|
| 23380 |
If the objname has a length of zero, or if objname does not obey the |
| 23381 |
UTF-8 definition, the error NFS4ERR_INVAL will be returned. |
| 23382 |
|
| 23383 |
The current filehandle is replaced by that of the new object. |
| 23384 |
|
| 23385 |
The createattrs specifies the initial set of attributes for the |
| 23386 |
object. The set of attributes may include any writable attribute |
| 23387 |
valid for the object type. When the operation is successful, the |
| 23388 |
server will return to the client an attribute mask signifying which |
| 23389 |
attributes were successfully set for the object. |
| 23390 |
|
| 23391 |
If createattrs includes neither the owner attribute nor an ACL with |
| 23392 |
an ACE for the owner, and if the server's file system both supports |
| 23393 |
and requires an owner attribute (or an owner ACE), then the server |
| 23394 |
MUST derive the owner (or the owner ACE). This would typically be |
| 23395 |
from the principal indicated in the RPC credentials of the call, but |
| 23396 |
the server's operating environment or file system semantics may |
| 23397 |
dictate other methods of derivation. Similarly, if createattrs |
| 23398 |
includes neither the group attribute nor a group ACE, and if the |
| 23399 |
server's file system both supports and requires the notion of a group |
| 23400 |
attribute (or group ACE), the server MUST derive the group attribute |
| 23401 |
|
| 23402 |
|
| 23403 |
|
| 23404 |
<span class="grey">Shepler, et al. Standards Track [Page 418]</span></pre> |
| 23405 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-419" ></span> |
| 23406 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23407 |
|
| 23408 |
|
| 23409 |
(or the corresponding owner ACE) for the file. This could be from |
| 23410 |
the RPC call's credentials, such as the group principal if the |
| 23411 |
credentials include it (such as with AUTH_SYS), from the group |
| 23412 |
identifier associated with the principal in the credentials (e.g., |
| 23413 |
POSIX systems have a user database [<a href="#ref-26" title="">26</a>] that has a group identifier |
| 23414 |
for every user identifier), inherited from the directory in which the |
| 23415 |
object is created, or whatever else the server's operating |
| 23416 |
environment or file system semantics dictate. This applies to the |
| 23417 |
OPEN operation too. |
| 23418 |
|
| 23419 |
Conversely, it is possible that the client will specify in |
| 23420 |
createattrs an owner attribute, group attribute, or ACL that the |
| 23421 |
principal indicated the RPC call's credentials does not have |
| 23422 |
permissions to create files for. The error to be returned in this |
| 23423 |
instance is NFS4ERR_PERM. This applies to the OPEN operation too. |
| 23424 |
|
| 23425 |
If the current filehandle designates a directory for which another |
| 23426 |
client holds a directory delegation, then, unless the delegation is |
| 23427 |
such that the situation can be resolved by sending a notification, |
| 23428 |
the delegation MUST be recalled, and the CREATE operation MUST NOT |
| 23429 |
proceed until the delegation is returned or revoked. Except where |
| 23430 |
this happens very quickly, one or more NFS4ERR_DELAY errors will be |
| 23431 |
returned to requests made while delegation remains outstanding. |
| 23432 |
|
| 23433 |
When the current filehandle designates a directory for which one or |
| 23434 |
more directory delegations exist, then, when those delegations |
| 23435 |
request such notifications, NOTIFY4_ADD_ENTRY will be generated as a |
| 23436 |
result of this operation. |
| 23437 |
|
| 23438 |
If the capability FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 is set |
| 23439 |
(<a href="#section-14.4">Section 14.4</a>), and a symbolic link is being created, then the |
| 23440 |
content of the symbolic link MUST be in UTF-8 encoding. |
| 23441 |
|
| 23442 |
<span class="h4"><a class="selflink" id="section-18.4.4" href="#section-18.4.4">18.4.4</a>. IMPLEMENTATION</span> |
| 23443 |
|
| 23444 |
If the client desires to set attribute values after the create, a |
| 23445 |
SETATTR operation can be added to the COMPOUND request so that the |
| 23446 |
appropriate attributes will be set. |
| 23447 |
|
| 23448 |
<span class="h3"><a class="selflink" id="section-18.5" href="#section-18.5">18.5</a>. Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery</span> |
| 23449 |
|
| 23450 |
<span class="h4"><a class="selflink" id="section-18.5.1" href="#section-18.5.1">18.5.1</a>. ARGUMENTS</span> |
| 23451 |
|
| 23452 |
struct DELEGPURGE4args { |
| 23453 |
clientid4 clientid; |
| 23454 |
}; |
| 23455 |
|
| 23456 |
|
| 23457 |
|
| 23458 |
|
| 23459 |
|
| 23460 |
<span class="grey">Shepler, et al. Standards Track [Page 419]</span></pre> |
| 23461 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-420" ></span> |
| 23462 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23463 |
|
| 23464 |
|
| 23465 |
<span class="h4"><a class="selflink" id="section-18.5.2" href="#section-18.5.2">18.5.2</a>. RESULTS</span> |
| 23466 |
|
| 23467 |
struct DELEGPURGE4res { |
| 23468 |
nfsstat4 status; |
| 23469 |
}; |
| 23470 |
|
| 23471 |
<span class="h4"><a class="selflink" id="section-18.5.3" href="#section-18.5.3">18.5.3</a>. DESCRIPTION</span> |
| 23472 |
|
| 23473 |
This operation purges all of the delegations awaiting recovery for a |
| 23474 |
given client. This is useful for clients that do not commit |
| 23475 |
delegation information to stable storage to indicate that conflicting |
| 23476 |
requests need not be delayed by the server awaiting recovery of |
| 23477 |
delegation information. |
| 23478 |
|
| 23479 |
The client is NOT specified by the clientid field of the request. |
| 23480 |
The client SHOULD set the client field to zero, and the server MUST |
| 23481 |
ignore the clientid field. Instead, the server MUST derive the |
| 23482 |
client ID from the value of the session ID in the arguments of the |
| 23483 |
SEQUENCE operation that precedes DELEGPURGE in the COMPOUND request. |
| 23484 |
|
| 23485 |
The DELEGPURGE operation should be used by clients that record |
| 23486 |
delegation information on stable storage on the client. In this |
| 23487 |
case, after the client recovers all delegations it knows of, it |
| 23488 |
should immediately send a DELEGPURGE operation. Doing so will notify |
| 23489 |
the server that no additional delegations for the client will be |
| 23490 |
recovered allowing it to free resources, and avoid delaying other |
| 23491 |
clients which make requests that conflict with the unrecovered |
| 23492 |
delegations. The set of delegations known to the server and the |
| 23493 |
client might be different. The reason for this is that after sending |
| 23494 |
a request that resulted in a delegation, the client might experience |
| 23495 |
a failure before it both received the delegation and committed the |
| 23496 |
delegation to the client's stable storage. |
| 23497 |
|
| 23498 |
The server MAY support DELEGPURGE, but if it does not, it MUST NOT |
| 23499 |
support CLAIM_DELEGATE_PREV and MUST NOT support CLAIM_DELEG_PREV_FH. |
| 23500 |
|
| 23501 |
<span class="h3"><a class="selflink" id="section-18.6" href="#section-18.6">18.6</a>. Operation 8: DELEGRETURN - Return Delegation</span> |
| 23502 |
|
| 23503 |
<span class="h4"><a class="selflink" id="section-18.6.1" href="#section-18.6.1">18.6.1</a>. ARGUMENTS</span> |
| 23504 |
|
| 23505 |
struct DELEGRETURN4args { |
| 23506 |
/* CURRENT_FH: delegated object */ |
| 23507 |
stateid4 deleg_stateid; |
| 23508 |
}; |
| 23509 |
|
| 23510 |
|
| 23511 |
|
| 23512 |
|
| 23513 |
|
| 23514 |
|
| 23515 |
|
| 23516 |
<span class="grey">Shepler, et al. Standards Track [Page 420]</span></pre> |
| 23517 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-421" ></span> |
| 23518 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23519 |
|
| 23520 |
|
| 23521 |
<span class="h4"><a class="selflink" id="section-18.6.2" href="#section-18.6.2">18.6.2</a>. RESULTS</span> |
| 23522 |
|
| 23523 |
struct DELEGRETURN4res { |
| 23524 |
nfsstat4 status; |
| 23525 |
}; |
| 23526 |
|
| 23527 |
<span class="h4"><a class="selflink" id="section-18.6.3" href="#section-18.6.3">18.6.3</a>. DESCRIPTION</span> |
| 23528 |
|
| 23529 |
The DELEGRETURN operation returns the delegation represented by the |
| 23530 |
current filehandle and stateid. |
| 23531 |
|
| 23532 |
Delegations may be returned voluntarily (i.e., before the server has |
| 23533 |
recalled them) or when recalled. In either case, the client must |
| 23534 |
properly propagate state changed under the context of the delegation |
| 23535 |
to the server before returning the delegation. |
| 23536 |
|
| 23537 |
The server MAY require that the principal, security flavor, and if |
| 23538 |
applicable, the GSS mechanism, combination that acquired the |
| 23539 |
delegation also be the one to send DELEGRETURN on the file. This |
| 23540 |
might not be possible if credentials for the principal are no longer |
| 23541 |
available. The server MAY allow the machine credential or SSV |
| 23542 |
credential (see <a href="#section-18.35">Section 18.35</a>) to send DELEGRETURN. |
| 23543 |
|
| 23544 |
<span class="h3"><a class="selflink" id="section-18.7" href="#section-18.7">18.7</a>. Operation 9: GETATTR - Get Attributes</span> |
| 23545 |
|
| 23546 |
<span class="h4"><a class="selflink" id="section-18.7.1" href="#section-18.7.1">18.7.1</a>. ARGUMENTS</span> |
| 23547 |
|
| 23548 |
struct GETATTR4args { |
| 23549 |
/* CURRENT_FH: object */ |
| 23550 |
bitmap4 attr_request; |
| 23551 |
}; |
| 23552 |
|
| 23553 |
<span class="h4"><a class="selflink" id="section-18.7.2" href="#section-18.7.2">18.7.2</a>. RESULTS</span> |
| 23554 |
|
| 23555 |
struct GETATTR4resok { |
| 23556 |
fattr4 obj_attributes; |
| 23557 |
}; |
| 23558 |
|
| 23559 |
union GETATTR4res switch (nfsstat4 status) { |
| 23560 |
case NFS4_OK: |
| 23561 |
GETATTR4resok resok4; |
| 23562 |
default: |
| 23563 |
void; |
| 23564 |
}; |
| 23565 |
|
| 23566 |
|
| 23567 |
|
| 23568 |
|
| 23569 |
|
| 23570 |
|
| 23571 |
|
| 23572 |
<span class="grey">Shepler, et al. Standards Track [Page 421]</span></pre> |
| 23573 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-422" ></span> |
| 23574 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23575 |
|
| 23576 |
|
| 23577 |
<span class="h4"><a class="selflink" id="section-18.7.3" href="#section-18.7.3">18.7.3</a>. DESCRIPTION</span> |
| 23578 |
|
| 23579 |
The GETATTR operation will obtain attributes for the file system |
| 23580 |
object specified by the current filehandle. The client sets a bit in |
| 23581 |
the bitmap argument for each attribute value that it would like the |
| 23582 |
server to return. The server returns an attribute bitmap that |
| 23583 |
indicates the attribute values that it was able to return, which will |
| 23584 |
include all attributes requested by the client that are attributes |
| 23585 |
supported by the server for the target file system. This bitmap is |
| 23586 |
followed by the attribute values ordered lowest attribute number |
| 23587 |
first. |
| 23588 |
|
| 23589 |
The server MUST return a value for each attribute that the client |
| 23590 |
requests if the attribute is supported by the server for the target |
| 23591 |
file system. If the server does not support a particular attribute |
| 23592 |
on the target file system, then it MUST NOT return the attribute |
| 23593 |
value and MUST NOT set the attribute bit in the result bitmap. The |
| 23594 |
server MUST return an error if it supports an attribute on the target |
| 23595 |
but cannot obtain its value. In that case, no attribute values will |
| 23596 |
be returned. |
| 23597 |
|
| 23598 |
File systems that are absent should be treated as having support for |
| 23599 |
a very small set of attributes as described in <a href="#section-11.3.1">Section 11.3.1</a>, even |
| 23600 |
if previously, when the file system was present, more attributes were |
| 23601 |
supported. |
| 23602 |
|
| 23603 |
All servers MUST support the REQUIRED attributes as specified in |
| 23604 |
<a href="#section-5.6">Section 5.6</a>, for all file systems, with the exception of absent file |
| 23605 |
systems. |
| 23606 |
|
| 23607 |
On success, the current filehandle retains its value. |
| 23608 |
|
| 23609 |
<span class="h4"><a class="selflink" id="section-18.7.4" href="#section-18.7.4">18.7.4</a>. IMPLEMENTATION</span> |
| 23610 |
|
| 23611 |
Suppose there is an OPEN_DELEGATE_WRITE delegation held by another |
| 23612 |
client for the file in question and size and/or change are among the |
| 23613 |
set of attributes being interrogated. The server has two choices. |
| 23614 |
First, the server can obtain the actual current value of these |
| 23615 |
attributes from the client holding the delegation by using the |
| 23616 |
CB_GETATTR callback. Second, the server, particularly when the |
| 23617 |
delegated client is unresponsive, can recall the delegation in |
| 23618 |
question. The GETATTR MUST NOT proceed until one of the following |
| 23619 |
occurs: |
| 23620 |
|
| 23621 |
o The requested attribute values are returned in the response to |
| 23622 |
CB_GETATTR. |
| 23623 |
|
| 23624 |
o The OPEN_DELEGATE_WRITE delegation is returned. |
| 23625 |
|
| 23626 |
|
| 23627 |
|
| 23628 |
<span class="grey">Shepler, et al. Standards Track [Page 422]</span></pre> |
| 23629 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-423" ></span> |
| 23630 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23631 |
|
| 23632 |
|
| 23633 |
o The OPEN_DELEGATE_WRITE delegation is revoked. |
| 23634 |
|
| 23635 |
Unless one of the above happens very quickly, one or more |
| 23636 |
NFS4ERR_DELAY errors will be returned while a delegation is |
| 23637 |
outstanding. |
| 23638 |
|
| 23639 |
<span class="h3"><a class="selflink" id="section-18.8" href="#section-18.8">18.8</a>. Operation 10: GETFH - Get Current Filehandle</span> |
| 23640 |
|
| 23641 |
<span class="h4"><a class="selflink" id="section-18.8.1" href="#section-18.8.1">18.8.1</a>. ARGUMENTS</span> |
| 23642 |
|
| 23643 |
/* CURRENT_FH: */ |
| 23644 |
void; |
| 23645 |
|
| 23646 |
<span class="h4"><a class="selflink" id="section-18.8.2" href="#section-18.8.2">18.8.2</a>. RESULTS</span> |
| 23647 |
|
| 23648 |
struct GETFH4resok { |
| 23649 |
nfs_fh4 object; |
| 23650 |
}; |
| 23651 |
|
| 23652 |
union GETFH4res switch (nfsstat4 status) { |
| 23653 |
case NFS4_OK: |
| 23654 |
GETFH4resok resok4; |
| 23655 |
default: |
| 23656 |
void; |
| 23657 |
}; |
| 23658 |
|
| 23659 |
<span class="h4"><a class="selflink" id="section-18.8.3" href="#section-18.8.3">18.8.3</a>. DESCRIPTION</span> |
| 23660 |
|
| 23661 |
This operation returns the current filehandle value. |
| 23662 |
|
| 23663 |
On success, the current filehandle retains its value. |
| 23664 |
|
| 23665 |
As described in <a href="#section-2.10.6.4">Section 2.10.6.4</a>, GETFH is REQUIRED or RECOMMENDED to |
| 23666 |
immediately follow certain operations, and servers are free to reject |
| 23667 |
such operations if the client fails to insert GETFH in the request as |
| 23668 |
REQUIRED or RECOMMENDED. <a href="#section-18.16.4.1">Section 18.16.4.1</a> provides additional |
| 23669 |
justification for why GETFH MUST follow OPEN. |
| 23670 |
|
| 23671 |
<span class="h4"><a class="selflink" id="section-18.8.4" href="#section-18.8.4">18.8.4</a>. IMPLEMENTATION</span> |
| 23672 |
|
| 23673 |
Operations that change the current filehandle like LOOKUP or CREATE |
| 23674 |
do not automatically return the new filehandle as a result. For |
| 23675 |
instance, if a client needs to look up a directory entry and obtain |
| 23676 |
its filehandle, then the following request is needed. |
| 23677 |
|
| 23678 |
PUTFH (directory filehandle) |
| 23679 |
LOOKUP (entry name) |
| 23680 |
GETFH |
| 23681 |
|
| 23682 |
|
| 23683 |
|
| 23684 |
<span class="grey">Shepler, et al. Standards Track [Page 423]</span></pre> |
| 23685 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-424" ></span> |
| 23686 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23687 |
|
| 23688 |
|
| 23689 |
<span class="h3"><a class="selflink" id="section-18.9" href="#section-18.9">18.9</a>. Operation 11: LINK - Create Link to a File</span> |
| 23690 |
|
| 23691 |
<span class="h4"><a class="selflink" id="section-18.9.1" href="#section-18.9.1">18.9.1</a>. ARGUMENTS</span> |
| 23692 |
|
| 23693 |
struct LINK4args { |
| 23694 |
/* SAVED_FH: source object */ |
| 23695 |
/* CURRENT_FH: target directory */ |
| 23696 |
component4 newname; |
| 23697 |
}; |
| 23698 |
|
| 23699 |
<span class="h4"><a class="selflink" id="section-18.9.2" href="#section-18.9.2">18.9.2</a>. RESULTS</span> |
| 23700 |
|
| 23701 |
struct LINK4resok { |
| 23702 |
change_info4 cinfo; |
| 23703 |
}; |
| 23704 |
|
| 23705 |
union LINK4res switch (nfsstat4 status) { |
| 23706 |
case NFS4_OK: |
| 23707 |
LINK4resok resok4; |
| 23708 |
default: |
| 23709 |
void; |
| 23710 |
}; |
| 23711 |
|
| 23712 |
<span class="h4"><a class="selflink" id="section-18.9.3" href="#section-18.9.3">18.9.3</a>. DESCRIPTION</span> |
| 23713 |
|
| 23714 |
The LINK operation creates an additional newname for the file |
| 23715 |
represented by the saved filehandle, as set by the SAVEFH operation, |
| 23716 |
in the directory represented by the current filehandle. The existing |
| 23717 |
file and the target directory must reside within the same file system |
| 23718 |
on the server. On success, the current filehandle will continue to |
| 23719 |
be the target directory. If an object exists in the target directory |
| 23720 |
with the same name as newname, the server must return NFS4ERR_EXIST. |
| 23721 |
|
| 23722 |
For the target directory, the server returns change_info4 information |
| 23723 |
in cinfo. With the atomic field of the change_info4 data type, the |
| 23724 |
server will indicate if the before and after change attributes were |
| 23725 |
obtained atomically with respect to the link creation. |
| 23726 |
|
| 23727 |
If the newname has a length of zero, or if newname does not obey the |
| 23728 |
UTF-8 definition, the error NFS4ERR_INVAL will be returned. |
| 23729 |
|
| 23730 |
<span class="h4"><a class="selflink" id="section-18.9.4" href="#section-18.9.4">18.9.4</a>. IMPLEMENTATION</span> |
| 23731 |
|
| 23732 |
The server MAY impose restrictions on the LINK operation such that |
| 23733 |
LINK may not be done when the file is open or when that open is done |
| 23734 |
by particular protocols, or with particular options or access modes. |
| 23735 |
When LINK is rejected because of such restrictions, the error |
| 23736 |
NFS4ERR_FILE_OPEN is returned. |
| 23737 |
|
| 23738 |
|
| 23739 |
|
| 23740 |
<span class="grey">Shepler, et al. Standards Track [Page 424]</span></pre> |
| 23741 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-425" ></span> |
| 23742 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23743 |
|
| 23744 |
|
| 23745 |
If a server does implement such restrictions and those restrictions |
| 23746 |
include cases of NFSv4 opens preventing successful execution of a |
| 23747 |
link, the server needs to recall any delegations that could hide the |
| 23748 |
existence of opens relevant to that decision. The reason is that |
| 23749 |
when a client holds a delegation, the server might not have an |
| 23750 |
accurate account of the opens for that client, since the client may |
| 23751 |
execute OPENs and CLOSEs locally. The LINK operation must be delayed |
| 23752 |
only until a definitive result can be obtained. For example, suppose |
| 23753 |
there are multiple delegations and one of them establishes an open |
| 23754 |
whose presence would prevent the link. Given the server's semantics, |
| 23755 |
NFS4ERR_FILE_OPEN may be returned to the caller as soon as that |
| 23756 |
delegation is returned without waiting for other delegations to be |
| 23757 |
returned. Similarly, if such opens are not associated with |
| 23758 |
delegations, NFS4ERR_FILE_OPEN can be returned immediately with no |
| 23759 |
delegation recall being done. |
| 23760 |
|
| 23761 |
If the current filehandle designates a directory for which another |
| 23762 |
client holds a directory delegation, then, unless the delegation is |
| 23763 |
such that the situation can be resolved by sending a notification, |
| 23764 |
the delegation MUST be recalled, and the operation cannot be |
| 23765 |
performed successfully until the delegation is returned or revoked. |
| 23766 |
Except where this happens very quickly, one or more NFS4ERR_DELAY |
| 23767 |
errors will be returned to requests made while delegation remains |
| 23768 |
outstanding. |
| 23769 |
|
| 23770 |
When the current filehandle designates a directory for which one or |
| 23771 |
more directory delegations exist, then, when those delegations |
| 23772 |
request such notifications, instead of a recall, NOTIFY4_ADD_ENTRY |
| 23773 |
will be generated as a result of the LINK operation. |
| 23774 |
|
| 23775 |
If the current file system supports the numlinks attribute, and other |
| 23776 |
clients have delegations to the file being linked, then those |
| 23777 |
delegations MUST be recalled and the LINK operation MUST NOT proceed |
| 23778 |
until all delegations are returned or revoked. Except where this |
| 23779 |
happens very quickly, one or more NFS4ERR_DELAY errors will be |
| 23780 |
returned to requests made while delegation remains outstanding. |
| 23781 |
|
| 23782 |
Changes to any property of the "hard" linked files are reflected in |
| 23783 |
all of the linked files. When a link is made to a file, the |
| 23784 |
attributes for the file should have a value for numlinks that is one |
| 23785 |
greater than the value before the LINK operation. |
| 23786 |
|
| 23787 |
The statement "file and the target directory must reside within the |
| 23788 |
same file system on the server" means that the fsid fields in the |
| 23789 |
attributes for the objects are the same. If they reside on different |
| 23790 |
file systems, the error NFS4ERR_XDEV is returned. This error may be |
| 23791 |
returned by some servers when there is an internal partitioning of a |
| 23792 |
file system that the LINK operation would violate. |
| 23793 |
|
| 23794 |
|
| 23795 |
|
| 23796 |
<span class="grey">Shepler, et al. Standards Track [Page 425]</span></pre> |
| 23797 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-426" ></span> |
| 23798 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23799 |
|
| 23800 |
|
| 23801 |
On some servers, "." and ".." are illegal values for newname and the |
| 23802 |
error NFS4ERR_BADNAME will be returned if they are specified. |
| 23803 |
|
| 23804 |
When the current filehandle designates a named attribute directory |
| 23805 |
and the object to be linked (the saved filehandle) is not a named |
| 23806 |
attribute for the same object, the error NFS4ERR_XDEV MUST be |
| 23807 |
returned. When the saved filehandle designates a named attribute and |
| 23808 |
the current filehandle is not the appropriate named attribute |
| 23809 |
directory, the error NFS4ERR_XDEV MUST also be returned. |
| 23810 |
|
| 23811 |
When the current filehandle designates a named attribute directory |
| 23812 |
and the object to be linked (the saved filehandle) is a named |
| 23813 |
attribute within that directory, the server may return the error |
| 23814 |
NFS4ERR_NOTSUPP. |
| 23815 |
|
| 23816 |
In the case that newname is already linked to the file represented by |
| 23817 |
the saved filehandle, the server will return NFS4ERR_EXIST. |
| 23818 |
|
| 23819 |
Note that symbolic links are created with the CREATE operation. |
| 23820 |
|
| 23821 |
<span class="h3"><a class="selflink" id="section-18.10" href="#section-18.10">18.10</a>. Operation 12: LOCK - Create Lock</span> |
| 23822 |
|
| 23823 |
<span class="h4"><a class="selflink" id="section-18.10.1" href="#section-18.10.1">18.10.1</a>. ARGUMENTS</span> |
| 23824 |
|
| 23825 |
/* |
| 23826 |
* For LOCK, transition from open_stateid and lock_owner |
| 23827 |
* to a lock stateid. |
| 23828 |
*/ |
| 23829 |
struct open_to_lock_owner4 { |
| 23830 |
seqid4 open_seqid; |
| 23831 |
stateid4 open_stateid; |
| 23832 |
seqid4 lock_seqid; |
| 23833 |
lock_owner4 lock_owner; |
| 23834 |
}; |
| 23835 |
|
| 23836 |
/* |
| 23837 |
* For LOCK, existing lock stateid continues to request new |
| 23838 |
* file lock for the same lock_owner and open_stateid. |
| 23839 |
*/ |
| 23840 |
struct exist_lock_owner4 { |
| 23841 |
stateid4 lock_stateid; |
| 23842 |
seqid4 lock_seqid; |
| 23843 |
}; |
| 23844 |
|
| 23845 |
|
| 23846 |
|
| 23847 |
|
| 23848 |
|
| 23849 |
|
| 23850 |
|
| 23851 |
|
| 23852 |
<span class="grey">Shepler, et al. Standards Track [Page 426]</span></pre> |
| 23853 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-427" ></span> |
| 23854 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23855 |
|
| 23856 |
|
| 23857 |
union locker4 switch (bool new_lock_owner) { |
| 23858 |
case TRUE: |
| 23859 |
open_to_lock_owner4 open_owner; |
| 23860 |
case FALSE: |
| 23861 |
exist_lock_owner4 lock_owner; |
| 23862 |
}; |
| 23863 |
|
| 23864 |
/* |
| 23865 |
* LOCK/LOCKT/LOCKU: Record lock management |
| 23866 |
*/ |
| 23867 |
struct LOCK4args { |
| 23868 |
/* CURRENT_FH: file */ |
| 23869 |
nfs_lock_type4 locktype; |
| 23870 |
bool reclaim; |
| 23871 |
offset4 offset; |
| 23872 |
length4 length; |
| 23873 |
locker4 locker; |
| 23874 |
}; |
| 23875 |
|
| 23876 |
<span class="h4"><a class="selflink" id="section-18.10.2" href="#section-18.10.2">18.10.2</a>. RESULTS</span> |
| 23877 |
|
| 23878 |
struct LOCK4denied { |
| 23879 |
offset4 offset; |
| 23880 |
length4 length; |
| 23881 |
nfs_lock_type4 locktype; |
| 23882 |
lock_owner4 owner; |
| 23883 |
}; |
| 23884 |
|
| 23885 |
struct LOCK4resok { |
| 23886 |
stateid4 lock_stateid; |
| 23887 |
}; |
| 23888 |
|
| 23889 |
union LOCK4res switch (nfsstat4 status) { |
| 23890 |
case NFS4_OK: |
| 23891 |
LOCK4resok resok4; |
| 23892 |
case NFS4ERR_DENIED: |
| 23893 |
LOCK4denied denied; |
| 23894 |
default: |
| 23895 |
void; |
| 23896 |
}; |
| 23897 |
|
| 23898 |
<span class="h4"><a class="selflink" id="section-18.10.3" href="#section-18.10.3">18.10.3</a>. DESCRIPTION</span> |
| 23899 |
|
| 23900 |
The LOCK operation requests a byte-range lock for the byte-range |
| 23901 |
specified by the offset and length parameters, and lock type |
| 23902 |
specified in the locktype parameter. If this is a reclaim request, |
| 23903 |
the reclaim parameter will be TRUE. |
| 23904 |
|
| 23905 |
|
| 23906 |
|
| 23907 |
|
| 23908 |
<span class="grey">Shepler, et al. Standards Track [Page 427]</span></pre> |
| 23909 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-428" ></span> |
| 23910 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23911 |
|
| 23912 |
|
| 23913 |
Bytes in a file may be locked even if those bytes are not currently |
| 23914 |
allocated to the file. To lock the file from a specific offset |
| 23915 |
through the end-of-file (no matter how long the file actually is) use |
| 23916 |
a length field equal to NFS4_UINT64_MAX. The server MUST return |
| 23917 |
NFS4ERR_INVAL under the following combinations of length and offset: |
| 23918 |
|
| 23919 |
o Length is equal to zero. |
| 23920 |
|
| 23921 |
o Length is not equal to NFS4_UINT64_MAX, and the sum of length and |
| 23922 |
offset exceeds NFS4_UINT64_MAX. |
| 23923 |
|
| 23924 |
32-bit servers are servers that support locking for byte offsets that |
| 23925 |
fit within 32 bits (i.e., less than or equal to NFS4_UINT32_MAX). If |
| 23926 |
the client specifies a range that overlaps one or more bytes beyond |
| 23927 |
offset NFS4_UINT32_MAX but does not end at offset NFS4_UINT64_MAX, |
| 23928 |
then such a 32-bit server MUST return the error NFS4ERR_BAD_RANGE. |
| 23929 |
|
| 23930 |
If the server returns NFS4ERR_DENIED, the owner, offset, and length |
| 23931 |
of a conflicting lock are returned. |
| 23932 |
|
| 23933 |
The locker argument specifies the lock-owner that is associated with |
| 23934 |
the LOCK operation. The locker4 structure is a switched union that |
| 23935 |
indicates whether the client has already created byte-range locking |
| 23936 |
state associated with the current open file and lock-owner. In the |
| 23937 |
case in which it has, the argument is just a stateid representing the |
| 23938 |
set of locks associated with that open file and lock-owner, together |
| 23939 |
with a lock_seqid value that MAY be any value and MUST be ignored by |
| 23940 |
the server. In the case where no byte-range locking state has been |
| 23941 |
established, or the client does not have the stateid available, the |
| 23942 |
argument contains the stateid of the open file with which this lock |
| 23943 |
is to be associated, together with the lock-owner with which the lock |
| 23944 |
is to be associated. The open_to_lock_owner case covers the very |
| 23945 |
first lock done by a lock-owner for a given open file and offers a |
| 23946 |
method to use the established state of the open_stateid to transition |
| 23947 |
to the use of a lock stateid. |
| 23948 |
|
| 23949 |
The following fields of the locker parameter MAY be set to any value |
| 23950 |
by the client and MUST be ignored by the server: |
| 23951 |
|
| 23952 |
o The clientid field of the lock_owner field of the open_owner field |
| 23953 |
(locker.open_owner.lock_owner.clientid). The reason the server |
| 23954 |
MUST ignore the clientid field is that the server MUST derive the |
| 23955 |
client ID from the session ID from the SEQUENCE operation of the |
| 23956 |
COMPOUND request. |
| 23957 |
|
| 23958 |
o The open_seqid and lock_seqid fields of the open_owner field |
| 23959 |
(locker.open_owner.open_seqid and locker.open_owner.lock_seqid). |
| 23960 |
|
| 23961 |
|
| 23962 |
|
| 23963 |
|
| 23964 |
<span class="grey">Shepler, et al. Standards Track [Page 428]</span></pre> |
| 23965 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-429" ></span> |
| 23966 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 23967 |
|
| 23968 |
|
| 23969 |
o The lock_seqid field of the lock_owner field |
| 23970 |
(locker.lock_owner.lock_seqid). |
| 23971 |
|
| 23972 |
Note that the client ID appearing in a LOCK4denied structure is the |
| 23973 |
actual client associated with the conflicting lock, whether this is |
| 23974 |
the client ID associated with the current session or a different one. |
| 23975 |
Thus, if the server returns NFS4ERR_DENIED, it MUST set the clientid |
| 23976 |
field of the owner field of the denied field. |
| 23977 |
|
| 23978 |
If the current filehandle is not an ordinary file, an error will be |
| 23979 |
returned to the client. In the case that the current filehandle |
| 23980 |
represents an object of type NF4DIR, NFS4ERR_ISDIR is returned. If |
| 23981 |
the current filehandle designates a symbolic link, NFS4ERR_SYMLINK is |
| 23982 |
returned. In all other cases, NFS4ERR_WRONG_TYPE is returned. |
| 23983 |
|
| 23984 |
On success, the current filehandle retains its value. |
| 23985 |
|
| 23986 |
<span class="h4"><a class="selflink" id="section-18.10.4" href="#section-18.10.4">18.10.4</a>. IMPLEMENTATION</span> |
| 23987 |
|
| 23988 |
If the server is unable to determine the exact offset and length of |
| 23989 |
the conflicting byte-range lock, the same offset and length that were |
| 23990 |
provided in the arguments should be returned in the denied results. |
| 23991 |
|
| 23992 |
LOCK operations are subject to permission checks and to checks |
| 23993 |
against the access type of the associated file. However, the |
| 23994 |
specific right and modes required for various types of locks reflect |
| 23995 |
the semantics of the server-exported file system, and are not |
| 23996 |
specified by the protocol. For example, Windows 2000 allows a write |
| 23997 |
lock of a file open for read access, while a POSIX-compliant system |
| 23998 |
does not. |
| 23999 |
|
| 24000 |
When the client sends a LOCK operation that corresponds to a range |
| 24001 |
that the lock-owner has locked already (with the same or different |
| 24002 |
lock type), or to a sub-range of such a range, or to a byte-range |
| 24003 |
that includes multiple locks already granted to that lock-owner, in |
| 24004 |
whole or in part, and the server does not support such locking |
| 24005 |
operations (i.e., does not support POSIX locking semantics), the |
| 24006 |
server will return the error NFS4ERR_LOCK_RANGE. In that case, the |
| 24007 |
client may return an error, or it may emulate the required |
| 24008 |
operations, using only LOCK for ranges that do not include any bytes |
| 24009 |
already locked by that lock-owner and LOCKU of locks held by that |
| 24010 |
lock-owner (specifying an exactly matching range and type). |
| 24011 |
Similarly, when the client sends a LOCK operation that amounts to |
| 24012 |
upgrading (changing from a READ_LT lock to a WRITE_LT lock) or |
| 24013 |
downgrading (changing from WRITE_LT lock to a READ_LT lock) an |
| 24014 |
existing byte-range lock, and the server does not support such a |
| 24015 |
|
| 24016 |
|
| 24017 |
|
| 24018 |
|
| 24019 |
|
| 24020 |
<span class="grey">Shepler, et al. Standards Track [Page 429]</span></pre> |
| 24021 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-430" ></span> |
| 24022 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24023 |
|
| 24024 |
|
| 24025 |
lock, the server will return NFS4ERR_LOCK_NOTSUPP. Such operations |
| 24026 |
may not perfectly reflect the required semantics in the face of |
| 24027 |
conflicting LOCK operations from other clients. |
| 24028 |
|
| 24029 |
When a client holds an OPEN_DELEGATE_WRITE delegation, the client |
| 24030 |
holding that delegation is assured that there are no opens by other |
| 24031 |
clients. Thus, there can be no conflicting LOCK operations from such |
| 24032 |
clients. Therefore, the client may be handling locking requests |
| 24033 |
locally, without doing LOCK operations on the server. If it does |
| 24034 |
that, it must be prepared to update the lock status on the server, by |
| 24035 |
sending appropriate LOCK and LOCKU operations before returning the |
| 24036 |
delegation. |
| 24037 |
|
| 24038 |
When one or more clients hold OPEN_DELEGATE_READ delegations, any |
| 24039 |
LOCK operation where the server is implementing mandatory locking |
| 24040 |
semantics MUST result in the recall of all such delegations. The |
| 24041 |
LOCK operation may not be granted until all such delegations are |
| 24042 |
returned or revoked. Except where this happens very quickly, one or |
| 24043 |
more NFS4ERR_DELAY errors will be returned to requests made while the |
| 24044 |
delegation remains outstanding. |
| 24045 |
|
| 24046 |
<span class="h3"><a class="selflink" id="section-18.11" href="#section-18.11">18.11</a>. Operation 13: LOCKT - Test for Lock</span> |
| 24047 |
|
| 24048 |
<span class="h4"><a class="selflink" id="section-18.11.1" href="#section-18.11.1">18.11.1</a>. ARGUMENTS</span> |
| 24049 |
|
| 24050 |
struct LOCKT4args { |
| 24051 |
/* CURRENT_FH: file */ |
| 24052 |
nfs_lock_type4 locktype; |
| 24053 |
offset4 offset; |
| 24054 |
length4 length; |
| 24055 |
lock_owner4 owner; |
| 24056 |
}; |
| 24057 |
|
| 24058 |
<span class="h4"><a class="selflink" id="section-18.11.2" href="#section-18.11.2">18.11.2</a>. RESULTS</span> |
| 24059 |
|
| 24060 |
union LOCKT4res switch (nfsstat4 status) { |
| 24061 |
case NFS4ERR_DENIED: |
| 24062 |
LOCK4denied denied; |
| 24063 |
case NFS4_OK: |
| 24064 |
void; |
| 24065 |
default: |
| 24066 |
void; |
| 24067 |
}; |
| 24068 |
|
| 24069 |
|
| 24070 |
|
| 24071 |
|
| 24072 |
|
| 24073 |
|
| 24074 |
|
| 24075 |
|
| 24076 |
<span class="grey">Shepler, et al. Standards Track [Page 430]</span></pre> |
| 24077 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-431" ></span> |
| 24078 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24079 |
|
| 24080 |
|
| 24081 |
<span class="h4"><a class="selflink" id="section-18.11.3" href="#section-18.11.3">18.11.3</a>. DESCRIPTION</span> |
| 24082 |
|
| 24083 |
The LOCKT operation tests the lock as specified in the arguments. If |
| 24084 |
a conflicting lock exists, the owner, offset, length, and type of the |
| 24085 |
conflicting lock are returned. The owner field in the results |
| 24086 |
includes the client ID of the owner of the conflicting lock, whether |
| 24087 |
this is the client ID associated with the current session or a |
| 24088 |
different client ID. If no lock is held, nothing other than NFS4_OK |
| 24089 |
is returned. Lock types READ_LT and READW_LT are processed in the |
| 24090 |
same way in that a conflicting lock test is done without regard to |
| 24091 |
blocking or non-blocking. The same is true for WRITE_LT and |
| 24092 |
WRITEW_LT. |
| 24093 |
|
| 24094 |
The ranges are specified as for LOCK. The NFS4ERR_INVAL and |
| 24095 |
NFS4ERR_BAD_RANGE errors are returned under the same circumstances as |
| 24096 |
for LOCK. |
| 24097 |
|
| 24098 |
The clientid field of the owner MAY be set to any value by the client |
| 24099 |
and MUST be ignored by the server. The reason the server MUST ignore |
| 24100 |
the clientid field is that the server MUST derive the client ID from |
| 24101 |
the session ID from the SEQUENCE operation of the COMPOUND request. |
| 24102 |
|
| 24103 |
If the current filehandle is not an ordinary file, an error will be |
| 24104 |
returned to the client. In the case that the current filehandle |
| 24105 |
represents an object of type NF4DIR, NFS4ERR_ISDIR is returned. If |
| 24106 |
the current filehandle designates a symbolic link, NFS4ERR_SYMLINK is |
| 24107 |
returned. In all other cases, NFS4ERR_WRONG_TYPE is returned. |
| 24108 |
|
| 24109 |
On success, the current filehandle retains its value. |
| 24110 |
|
| 24111 |
<span class="h4"><a class="selflink" id="section-18.11.4" href="#section-18.11.4">18.11.4</a>. IMPLEMENTATION</span> |
| 24112 |
|
| 24113 |
If the server is unable to determine the exact offset and length of |
| 24114 |
the conflicting lock, the same offset and length that were provided |
| 24115 |
in the arguments should be returned in the denied results. |
| 24116 |
|
| 24117 |
LOCKT uses a lock_owner4 rather a stateid4, as is used in LOCK to |
| 24118 |
identify the owner. This is because the client does not have to open |
| 24119 |
the file to test for the existence of a lock, so a stateid might not |
| 24120 |
be available. |
| 24121 |
|
| 24122 |
As noted in <a href="#section-18.10.4">Section 18.10.4</a>, some servers may return |
| 24123 |
NFS4ERR_LOCK_RANGE to certain (otherwise non-conflicting) LOCK |
| 24124 |
operations that overlap ranges already granted to the current lock- |
| 24125 |
owner. |
| 24126 |
|
| 24127 |
|
| 24128 |
|
| 24129 |
|
| 24130 |
|
| 24131 |
|
| 24132 |
<span class="grey">Shepler, et al. Standards Track [Page 431]</span></pre> |
| 24133 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-432" ></span> |
| 24134 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24135 |
|
| 24136 |
|
| 24137 |
The LOCKT operation's test for conflicting locks SHOULD exclude locks |
| 24138 |
for the current lock-owner, and thus should return NFS4_OK in such |
| 24139 |
cases. Note that this means that a server might return NFS4_OK to a |
| 24140 |
LOCKT request even though a LOCK operation for the same range and |
| 24141 |
lock-owner would fail with NFS4ERR_LOCK_RANGE. |
| 24142 |
|
| 24143 |
When a client holds an OPEN_DELEGATE_WRITE delegation, it may choose |
| 24144 |
(see <a href="#section-18.10.4">Section 18.10.4</a>) to handle LOCK requests locally. In such a |
| 24145 |
case, LOCKT requests will similarly be handled locally. |
| 24146 |
|
| 24147 |
<span class="h3"><a class="selflink" id="section-18.12" href="#section-18.12">18.12</a>. Operation 14: LOCKU - Unlock File</span> |
| 24148 |
|
| 24149 |
<span class="h4"><a class="selflink" id="section-18.12.1" href="#section-18.12.1">18.12.1</a>. ARGUMENTS</span> |
| 24150 |
|
| 24151 |
struct LOCKU4args { |
| 24152 |
/* CURRENT_FH: file */ |
| 24153 |
nfs_lock_type4 locktype; |
| 24154 |
seqid4 seqid; |
| 24155 |
stateid4 lock_stateid; |
| 24156 |
offset4 offset; |
| 24157 |
length4 length; |
| 24158 |
}; |
| 24159 |
|
| 24160 |
<span class="h4"><a class="selflink" id="section-18.12.2" href="#section-18.12.2">18.12.2</a>. RESULTS</span> |
| 24161 |
|
| 24162 |
union LOCKU4res switch (nfsstat4 status) { |
| 24163 |
case NFS4_OK: |
| 24164 |
stateid4 lock_stateid; |
| 24165 |
default: |
| 24166 |
void; |
| 24167 |
}; |
| 24168 |
|
| 24169 |
<span class="h4"><a class="selflink" id="section-18.12.3" href="#section-18.12.3">18.12.3</a>. DESCRIPTION</span> |
| 24170 |
|
| 24171 |
The LOCKU operation unlocks the byte-range lock specified by the |
| 24172 |
parameters. The client may set the locktype field to any value that |
| 24173 |
is legal for the nfs_lock_type4 enumerated type, and the server MUST |
| 24174 |
accept any legal value for locktype. Any legal value for locktype |
| 24175 |
has no effect on the success or failure of the LOCKU operation. |
| 24176 |
|
| 24177 |
The ranges are specified as for LOCK. The NFS4ERR_INVAL and |
| 24178 |
NFS4ERR_BAD_RANGE errors are returned under the same circumstances as |
| 24179 |
for LOCK. |
| 24180 |
|
| 24181 |
The seqid parameter MAY be any value and the server MUST ignore it. |
| 24182 |
|
| 24183 |
|
| 24184 |
|
| 24185 |
|
| 24186 |
|
| 24187 |
|
| 24188 |
<span class="grey">Shepler, et al. Standards Track [Page 432]</span></pre> |
| 24189 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-433" ></span> |
| 24190 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24191 |
|
| 24192 |
|
| 24193 |
If the current filehandle is not an ordinary file, an error will be |
| 24194 |
returned to the client. In the case that the current filehandle |
| 24195 |
represents an object of type NF4DIR, NFS4ERR_ISDIR is returned. If |
| 24196 |
the current filehandle designates a symbolic link, NFS4ERR_SYMLINK is |
| 24197 |
returned. In all other cases, NFS4ERR_WRONG_TYPE is returned. |
| 24198 |
|
| 24199 |
On success, the current filehandle retains its value. |
| 24200 |
|
| 24201 |
The server MAY require that the principal, security flavor, and if |
| 24202 |
applicable, the GSS mechanism, combination that sent a LOCK operation |
| 24203 |
also be the one to send LOCKU on the file. This might not be |
| 24204 |
possible if credentials for the principal are no longer available. |
| 24205 |
The server MAY allow the machine credential or SSV credential (see |
| 24206 |
<a href="#section-18.35">Section 18.35</a>) to send LOCKU. |
| 24207 |
|
| 24208 |
<span class="h4"><a class="selflink" id="section-18.12.4" href="#section-18.12.4">18.12.4</a>. IMPLEMENTATION</span> |
| 24209 |
|
| 24210 |
If the area to be unlocked does not correspond exactly to a lock |
| 24211 |
actually held by the lock-owner, the server may return the error |
| 24212 |
NFS4ERR_LOCK_RANGE. This includes the case in which the area is not |
| 24213 |
locked, where the area is a sub-range of the area locked, where it |
| 24214 |
overlaps the area locked without matching exactly, or the area |
| 24215 |
specified includes multiple locks held by the lock-owner. In all of |
| 24216 |
these cases, allowed by POSIX locking [<a href="#ref-24" title="">24</a>] semantics, a client |
| 24217 |
receiving this error should, if it desires support for such |
| 24218 |
operations, simulate the operation using LOCKU on ranges |
| 24219 |
corresponding to locks it actually holds, possibly followed by LOCK |
| 24220 |
operations for the sub-ranges not being unlocked. |
| 24221 |
|
| 24222 |
When a client holds an OPEN_DELEGATE_WRITE delegation, it may choose |
| 24223 |
(see <a href="#section-18.10.4">Section 18.10.4</a>) to handle LOCK requests locally. In such a |
| 24224 |
case, LOCKU operations will similarly be handled locally. |
| 24225 |
|
| 24226 |
<span class="h3"><a class="selflink" id="section-18.13" href="#section-18.13">18.13</a>. Operation 15: LOOKUP - Lookup Filename</span> |
| 24227 |
|
| 24228 |
<span class="h4"><a class="selflink" id="section-18.13.1" href="#section-18.13.1">18.13.1</a>. ARGUMENTS</span> |
| 24229 |
|
| 24230 |
struct LOOKUP4args { |
| 24231 |
/* CURRENT_FH: directory */ |
| 24232 |
component4 objname; |
| 24233 |
}; |
| 24234 |
|
| 24235 |
<span class="h4"><a class="selflink" id="section-18.13.2" href="#section-18.13.2">18.13.2</a>. RESULTS</span> |
| 24236 |
|
| 24237 |
struct LOOKUP4res { |
| 24238 |
/* New CURRENT_FH: object */ |
| 24239 |
nfsstat4 status; |
| 24240 |
}; |
| 24241 |
|
| 24242 |
|
| 24243 |
|
| 24244 |
<span class="grey">Shepler, et al. Standards Track [Page 433]</span></pre> |
| 24245 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-434" ></span> |
| 24246 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24247 |
|
| 24248 |
|
| 24249 |
<span class="h4"><a class="selflink" id="section-18.13.3" href="#section-18.13.3">18.13.3</a>. DESCRIPTION</span> |
| 24250 |
|
| 24251 |
The LOOKUP operation looks up or finds a file system object using the |
| 24252 |
directory specified by the current filehandle. LOOKUP evaluates the |
| 24253 |
component and if the object exists, the current filehandle is |
| 24254 |
replaced with the component's filehandle. |
| 24255 |
|
| 24256 |
If the component cannot be evaluated either because it does not exist |
| 24257 |
or because the client does not have permission to evaluate the |
| 24258 |
component, then an error will be returned and the current filehandle |
| 24259 |
will be unchanged. |
| 24260 |
|
| 24261 |
If the component is a zero-length string or if any component does not |
| 24262 |
obey the UTF-8 definition, the error NFS4ERR_INVAL will be returned. |
| 24263 |
|
| 24264 |
<span class="h4"><a class="selflink" id="section-18.13.4" href="#section-18.13.4">18.13.4</a>. IMPLEMENTATION</span> |
| 24265 |
|
| 24266 |
If the client wants to achieve the effect of a multi-component look |
| 24267 |
up, it may construct a COMPOUND request such as (and obtain each |
| 24268 |
filehandle): |
| 24269 |
|
| 24270 |
PUTFH (directory filehandle) |
| 24271 |
LOOKUP "pub" |
| 24272 |
GETFH |
| 24273 |
LOOKUP "foo" |
| 24274 |
GETFH |
| 24275 |
LOOKUP "bar" |
| 24276 |
GETFH |
| 24277 |
|
| 24278 |
Unlike NFSv3, NFSv4.1 allows LOOKUP requests to cross mountpoints on |
| 24279 |
the server. The client can detect a mountpoint crossing by comparing |
| 24280 |
the fsid attribute of the directory with the fsid attribute of the |
| 24281 |
directory looked up. If the fsids are different, then the new |
| 24282 |
directory is a server mountpoint. UNIX clients that detect a |
| 24283 |
mountpoint crossing will need to mount the server's file system. |
| 24284 |
This needs to be done to maintain the file object identity checking |
| 24285 |
mechanisms common to UNIX clients. |
| 24286 |
|
| 24287 |
Servers that limit NFS access to "shared" or "exported" file systems |
| 24288 |
should provide a pseudo file system into which the exported file |
| 24289 |
systems can be integrated, so that clients can browse the server's |
| 24290 |
namespace. The clients view of a pseudo file system will be limited |
| 24291 |
to paths that lead to exported file systems. |
| 24292 |
|
| 24293 |
Note: previous versions of the protocol assigned special semantics to |
| 24294 |
the names "." and "..". NFSv4.1 assigns no special semantics to |
| 24295 |
these names. The LOOKUPP operator must be used to look up a parent |
| 24296 |
directory. |
| 24297 |
|
| 24298 |
|
| 24299 |
|
| 24300 |
<span class="grey">Shepler, et al. Standards Track [Page 434]</span></pre> |
| 24301 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-435" ></span> |
| 24302 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24303 |
|
| 24304 |
|
| 24305 |
Note that this operation does not follow symbolic links. The client |
| 24306 |
is responsible for all parsing of filenames including filenames that |
| 24307 |
are modified by symbolic links encountered during the look up |
| 24308 |
process. |
| 24309 |
|
| 24310 |
If the current filehandle supplied is not a directory but a symbolic |
| 24311 |
link, the error NFS4ERR_SYMLINK is returned as the error. For all |
| 24312 |
other non-directory file types, the error NFS4ERR_NOTDIR is returned. |
| 24313 |
|
| 24314 |
<span class="h3"><a class="selflink" id="section-18.14" href="#section-18.14">18.14</a>. Operation 16: LOOKUPP - Lookup Parent Directory</span> |
| 24315 |
|
| 24316 |
<span class="h4"><a class="selflink" id="section-18.14.1" href="#section-18.14.1">18.14.1</a>. ARGUMENTS</span> |
| 24317 |
|
| 24318 |
/* CURRENT_FH: object */ |
| 24319 |
void; |
| 24320 |
|
| 24321 |
<span class="h4"><a class="selflink" id="section-18.14.2" href="#section-18.14.2">18.14.2</a>. RESULTS</span> |
| 24322 |
|
| 24323 |
struct LOOKUPP4res { |
| 24324 |
/* new CURRENT_FH: parent directory */ |
| 24325 |
nfsstat4 status; |
| 24326 |
}; |
| 24327 |
|
| 24328 |
<span class="h4"><a class="selflink" id="section-18.14.3" href="#section-18.14.3">18.14.3</a>. DESCRIPTION</span> |
| 24329 |
|
| 24330 |
The current filehandle is assumed to refer to a regular directory or |
| 24331 |
a named attribute directory. LOOKUPP assigns the filehandle for its |
| 24332 |
parent directory to be the current filehandle. If there is no parent |
| 24333 |
directory, an NFS4ERR_NOENT error must be returned. Therefore, |
| 24334 |
NFS4ERR_NOENT will be returned by the server when the current |
| 24335 |
filehandle is at the root or top of the server's file tree. |
| 24336 |
|
| 24337 |
As is the case with LOOKUP, LOOKUPP will also cross mountpoints. |
| 24338 |
|
| 24339 |
If the current filehandle is not a directory or named attribute |
| 24340 |
directory, the error NFS4ERR_NOTDIR is returned. |
| 24341 |
|
| 24342 |
If the requester's security flavor does not match that configured for |
| 24343 |
the parent directory, then the server SHOULD return NFS4ERR_WRONGSEC |
| 24344 |
(a future minor revision of NFSv4 may upgrade this to MUST) in the |
| 24345 |
LOOKUPP response. However, if the server does so, it MUST support |
| 24346 |
the SECINFO_NO_NAME operation (<a href="#section-18.45">Section 18.45</a>), so that the client can |
| 24347 |
gracefully determine the correct security flavor. |
| 24348 |
|
| 24349 |
If the current filehandle is a named attribute directory that is |
| 24350 |
associated with a file system object via OPENATTR (i.e., not a sub- |
| 24351 |
directory of a named attribute directory), LOOKUPP SHOULD return the |
| 24352 |
filehandle of the associated file system object. |
| 24353 |
|
| 24354 |
|
| 24355 |
|
| 24356 |
<span class="grey">Shepler, et al. Standards Track [Page 435]</span></pre> |
| 24357 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-436" ></span> |
| 24358 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24359 |
|
| 24360 |
|
| 24361 |
<span class="h4"><a class="selflink" id="section-18.14.4" href="#section-18.14.4">18.14.4</a>. IMPLEMENTATION</span> |
| 24362 |
|
| 24363 |
An issue to note is upward navigation from named attribute |
| 24364 |
directories. The named attribute directories are essentially |
| 24365 |
detached from the namespace, and this property should be safely |
| 24366 |
represented in the client operating environment. LOOKUPP on a named |
| 24367 |
attribute directory may return the filehandle of the associated file, |
| 24368 |
and conveying this to applications might be unsafe as many |
| 24369 |
applications expect the parent of an object to always be a directory. |
| 24370 |
Therefore, the client may want to hide the parent of named attribute |
| 24371 |
directories (represented as ".." in UNIX) or represent the named |
| 24372 |
attribute directory as its own parent (as is typically done for the |
| 24373 |
file system root directory in UNIX). |
| 24374 |
|
| 24375 |
<span class="h3"><a class="selflink" id="section-18.15" href="#section-18.15">18.15</a>. Operation 17: NVERIFY - Verify Difference in Attributes</span> |
| 24376 |
|
| 24377 |
<span class="h4"><a class="selflink" id="section-18.15.1" href="#section-18.15.1">18.15.1</a>. ARGUMENTS</span> |
| 24378 |
|
| 24379 |
struct NVERIFY4args { |
| 24380 |
/* CURRENT_FH: object */ |
| 24381 |
fattr4 obj_attributes; |
| 24382 |
}; |
| 24383 |
|
| 24384 |
<span class="h4"><a class="selflink" id="section-18.15.2" href="#section-18.15.2">18.15.2</a>. RESULTS</span> |
| 24385 |
|
| 24386 |
struct NVERIFY4res { |
| 24387 |
nfsstat4 status; |
| 24388 |
}; |
| 24389 |
|
| 24390 |
<span class="h4"><a class="selflink" id="section-18.15.3" href="#section-18.15.3">18.15.3</a>. DESCRIPTION</span> |
| 24391 |
|
| 24392 |
This operation is used to prefix a sequence of operations to be |
| 24393 |
performed if one or more attributes have changed on some file system |
| 24394 |
object. If all the attributes match, then the error NFS4ERR_SAME |
| 24395 |
MUST be returned. |
| 24396 |
|
| 24397 |
On success, the current filehandle retains its value. |
| 24398 |
|
| 24399 |
|
| 24400 |
|
| 24401 |
|
| 24402 |
|
| 24403 |
|
| 24404 |
|
| 24405 |
|
| 24406 |
|
| 24407 |
|
| 24408 |
|
| 24409 |
|
| 24410 |
|
| 24411 |
|
| 24412 |
<span class="grey">Shepler, et al. Standards Track [Page 436]</span></pre> |
| 24413 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-437" ></span> |
| 24414 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24415 |
|
| 24416 |
|
| 24417 |
<span class="h4"><a class="selflink" id="section-18.15.4" href="#section-18.15.4">18.15.4</a>. IMPLEMENTATION</span> |
| 24418 |
|
| 24419 |
This operation is useful as a cache validation operator. If the |
| 24420 |
object to which the attributes belong has changed, then the following |
| 24421 |
operations may obtain new data associated with that object, for |
| 24422 |
instance, to check if a file has been changed and obtain new data if |
| 24423 |
it has: |
| 24424 |
|
| 24425 |
SEQUENCE |
| 24426 |
PUTFH fh |
| 24427 |
NVERIFY attrbits attrs |
| 24428 |
READ 0 32767 |
| 24429 |
|
| 24430 |
Contrast this with NFSv3, which would first send a GETATTR in one |
| 24431 |
request/reply round trip, and then if attributes indicated that the |
| 24432 |
client's cache was stale, then send a READ in another request/reply |
| 24433 |
round trip. |
| 24434 |
|
| 24435 |
In the case that a RECOMMENDED attribute is specified in the NVERIFY |
| 24436 |
operation and the server does not support that attribute for the file |
| 24437 |
system object, the error NFS4ERR_ATTRNOTSUPP is returned to the |
| 24438 |
client. |
| 24439 |
|
| 24440 |
When the attribute rdattr_error or any set-only attribute (e.g., |
| 24441 |
time_modify_set) is specified, the error NFS4ERR_INVAL is returned to |
| 24442 |
the client. |
| 24443 |
|
| 24444 |
<span class="h3"><a class="selflink" id="section-18.16" href="#section-18.16">18.16</a>. Operation 18: OPEN - Open a Regular File</span> |
| 24445 |
|
| 24446 |
<span class="h4"><a class="selflink" id="section-18.16.1" href="#section-18.16.1">18.16.1</a>. ARGUMENTS</span> |
| 24447 |
|
| 24448 |
/* |
| 24449 |
* Various definitions for OPEN |
| 24450 |
*/ |
| 24451 |
enum createmode4 { |
| 24452 |
UNCHECKED4 = 0, |
| 24453 |
GUARDED4 = 1, |
| 24454 |
/* Deprecated in NFSv4.1. */ |
| 24455 |
EXCLUSIVE4 = 2, |
| 24456 |
/* |
| 24457 |
* New to NFSv4.1. If session is persistent, |
| 24458 |
* GUARDED4 MUST be used. Otherwise, use |
| 24459 |
* EXCLUSIVE4_1 instead of EXCLUSIVE4. |
| 24460 |
*/ |
| 24461 |
EXCLUSIVE4_1 = 3 |
| 24462 |
}; |
| 24463 |
|
| 24464 |
|
| 24465 |
|
| 24466 |
|
| 24467 |
|
| 24468 |
<span class="grey">Shepler, et al. Standards Track [Page 437]</span></pre> |
| 24469 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-438" ></span> |
| 24470 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24471 |
|
| 24472 |
|
| 24473 |
struct creatverfattr { |
| 24474 |
verifier4 cva_verf; |
| 24475 |
fattr4 cva_attrs; |
| 24476 |
}; |
| 24477 |
|
| 24478 |
union createhow4 switch (createmode4 mode) { |
| 24479 |
case UNCHECKED4: |
| 24480 |
case GUARDED4: |
| 24481 |
fattr4 createattrs; |
| 24482 |
case EXCLUSIVE4: |
| 24483 |
verifier4 createverf; |
| 24484 |
case EXCLUSIVE4_1: |
| 24485 |
creatverfattr ch_createboth; |
| 24486 |
}; |
| 24487 |
|
| 24488 |
enum opentype4 { |
| 24489 |
OPEN4_NOCREATE = 0, |
| 24490 |
OPEN4_CREATE = 1 |
| 24491 |
}; |
| 24492 |
|
| 24493 |
union openflag4 switch (opentype4 opentype) { |
| 24494 |
case OPEN4_CREATE: |
| 24495 |
createhow4 how; |
| 24496 |
default: |
| 24497 |
void; |
| 24498 |
}; |
| 24499 |
|
| 24500 |
/* Next definitions used for OPEN delegation */ |
| 24501 |
enum limit_by4 { |
| 24502 |
NFS_LIMIT_SIZE = 1, |
| 24503 |
NFS_LIMIT_BLOCKS = 2 |
| 24504 |
/* others as needed */ |
| 24505 |
}; |
| 24506 |
|
| 24507 |
struct nfs_modified_limit4 { |
| 24508 |
uint32_t num_blocks; |
| 24509 |
uint32_t bytes_per_block; |
| 24510 |
}; |
| 24511 |
|
| 24512 |
union nfs_space_limit4 switch (limit_by4 limitby) { |
| 24513 |
/* limit specified as file size */ |
| 24514 |
case NFS_LIMIT_SIZE: |
| 24515 |
uint64_t filesize; |
| 24516 |
/* limit specified by number of blocks */ |
| 24517 |
case NFS_LIMIT_BLOCKS: |
| 24518 |
nfs_modified_limit4 mod_blocks; |
| 24519 |
} ; |
| 24520 |
|
| 24521 |
|
| 24522 |
|
| 24523 |
|
| 24524 |
<span class="grey">Shepler, et al. Standards Track [Page 438]</span></pre> |
| 24525 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-439" ></span> |
| 24526 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24527 |
|
| 24528 |
|
| 24529 |
/* |
| 24530 |
* Share Access and Deny constants for open argument |
| 24531 |
*/ |
| 24532 |
const OPEN4_SHARE_ACCESS_READ = 0x00000001; |
| 24533 |
const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; |
| 24534 |
const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; |
| 24535 |
|
| 24536 |
const OPEN4_SHARE_DENY_NONE = 0x00000000; |
| 24537 |
const OPEN4_SHARE_DENY_READ = 0x00000001; |
| 24538 |
const OPEN4_SHARE_DENY_WRITE = 0x00000002; |
| 24539 |
const OPEN4_SHARE_DENY_BOTH = 0x00000003; |
| 24540 |
|
| 24541 |
|
| 24542 |
/* new flags for share_access field of OPEN4args */ |
| 24543 |
const OPEN4_SHARE_ACCESS_WANT_DELEG_MASK = 0xFF00; |
| 24544 |
const OPEN4_SHARE_ACCESS_WANT_NO_PREFERENCE = 0x0000; |
| 24545 |
const OPEN4_SHARE_ACCESS_WANT_READ_DELEG = 0x0100; |
| 24546 |
const OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG = 0x0200; |
| 24547 |
const OPEN4_SHARE_ACCESS_WANT_ANY_DELEG = 0x0300; |
| 24548 |
const OPEN4_SHARE_ACCESS_WANT_NO_DELEG = 0x0400; |
| 24549 |
const OPEN4_SHARE_ACCESS_WANT_CANCEL = 0x0500; |
| 24550 |
|
| 24551 |
const |
| 24552 |
OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL |
| 24553 |
= 0x10000; |
| 24554 |
|
| 24555 |
const |
| 24556 |
OPEN4_SHARE_ACCESS_WANT_PUSH_DELEG_WHEN_UNCONTENDED |
| 24557 |
= 0x20000; |
| 24558 |
|
| 24559 |
enum open_delegation_type4 { |
| 24560 |
OPEN_DELEGATE_NONE = 0, |
| 24561 |
OPEN_DELEGATE_READ = 1, |
| 24562 |
OPEN_DELEGATE_WRITE = 2, |
| 24563 |
OPEN_DELEGATE_NONE_EXT = 3 /* new to v4.1 */ |
| 24564 |
}; |
| 24565 |
|
| 24566 |
enum open_claim_type4 { |
| 24567 |
/* |
| 24568 |
* Not a reclaim. |
| 24569 |
*/ |
| 24570 |
CLAIM_NULL = 0, |
| 24571 |
|
| 24572 |
CLAIM_PREVIOUS = 1, |
| 24573 |
CLAIM_DELEGATE_CUR = 2, |
| 24574 |
CLAIM_DELEGATE_PREV = 3, |
| 24575 |
|
| 24576 |
|
| 24577 |
|
| 24578 |
|
| 24579 |
|
| 24580 |
<span class="grey">Shepler, et al. Standards Track [Page 439]</span></pre> |
| 24581 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-440" ></span> |
| 24582 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24583 |
|
| 24584 |
|
| 24585 |
/* |
| 24586 |
* Not a reclaim. |
| 24587 |
* |
| 24588 |
* Like CLAIM_NULL, but object identified |
| 24589 |
* by the current filehandle. |
| 24590 |
*/ |
| 24591 |
CLAIM_FH = 4, /* new to v4.1 */ |
| 24592 |
|
| 24593 |
/* |
| 24594 |
* Like CLAIM_DELEGATE_CUR, but object identified |
| 24595 |
* by current filehandle. |
| 24596 |
*/ |
| 24597 |
CLAIM_DELEG_CUR_FH = 5, /* new to v4.1 */ |
| 24598 |
|
| 24599 |
/* |
| 24600 |
* Like CLAIM_DELEGATE_PREV, but object identified |
| 24601 |
* by current filehandle. |
| 24602 |
*/ |
| 24603 |
CLAIM_DELEG_PREV_FH = 6 /* new to v4.1 */ |
| 24604 |
}; |
| 24605 |
|
| 24606 |
struct open_claim_delegate_cur4 { |
| 24607 |
stateid4 delegate_stateid; |
| 24608 |
component4 file; |
| 24609 |
}; |
| 24610 |
|
| 24611 |
union open_claim4 switch (open_claim_type4 claim) { |
| 24612 |
/* |
| 24613 |
* No special rights to file. |
| 24614 |
* Ordinary OPEN of the specified file. |
| 24615 |
*/ |
| 24616 |
case CLAIM_NULL: |
| 24617 |
/* CURRENT_FH: directory */ |
| 24618 |
component4 file; |
| 24619 |
/* |
| 24620 |
* Right to the file established by an |
| 24621 |
* open previous to server reboot. File |
| 24622 |
* identified by filehandle obtained at |
| 24623 |
* that time rather than by name. |
| 24624 |
*/ |
| 24625 |
case CLAIM_PREVIOUS: |
| 24626 |
/* CURRENT_FH: file being reclaimed */ |
| 24627 |
open_delegation_type4 delegate_type; |
| 24628 |
|
| 24629 |
|
| 24630 |
|
| 24631 |
|
| 24632 |
|
| 24633 |
|
| 24634 |
|
| 24635 |
|
| 24636 |
<span class="grey">Shepler, et al. Standards Track [Page 440]</span></pre> |
| 24637 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-441" ></span> |
| 24638 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24639 |
|
| 24640 |
|
| 24641 |
/* |
| 24642 |
* Right to file based on a delegation |
| 24643 |
* granted by the server. File is |
| 24644 |
* specified by name. |
| 24645 |
*/ |
| 24646 |
case CLAIM_DELEGATE_CUR: |
| 24647 |
/* CURRENT_FH: directory */ |
| 24648 |
open_claim_delegate_cur4 delegate_cur_info; |
| 24649 |
|
| 24650 |
/* |
| 24651 |
* Right to file based on a delegation |
| 24652 |
* granted to a previous boot instance |
| 24653 |
* of the client. File is specified by name. |
| 24654 |
*/ |
| 24655 |
case CLAIM_DELEGATE_PREV: |
| 24656 |
/* CURRENT_FH: directory */ |
| 24657 |
component4 file_delegate_prev; |
| 24658 |
|
| 24659 |
/* |
| 24660 |
* Like CLAIM_NULL. No special rights |
| 24661 |
* to file. Ordinary OPEN of the |
| 24662 |
* specified file by current filehandle. |
| 24663 |
*/ |
| 24664 |
case CLAIM_FH: /* new to v4.1 */ |
| 24665 |
/* CURRENT_FH: regular file to open */ |
| 24666 |
void; |
| 24667 |
|
| 24668 |
/* |
| 24669 |
* Like CLAIM_DELEGATE_PREV. Right to file based on a |
| 24670 |
* delegation granted to a previous boot |
| 24671 |
* instance of the client. File is identified by |
| 24672 |
* by filehandle. |
| 24673 |
*/ |
| 24674 |
case CLAIM_DELEG_PREV_FH: /* new to v4.1 */ |
| 24675 |
/* CURRENT_FH: file being opened */ |
| 24676 |
void; |
| 24677 |
|
| 24678 |
/* |
| 24679 |
* Like CLAIM_DELEGATE_CUR. Right to file based on |
| 24680 |
* a delegation granted by the server. |
| 24681 |
* File is identified by filehandle. |
| 24682 |
*/ |
| 24683 |
case CLAIM_DELEG_CUR_FH: /* new to v4.1 */ |
| 24684 |
/* CURRENT_FH: file being opened */ |
| 24685 |
stateid4 oc_delegate_stateid; |
| 24686 |
|
| 24687 |
}; |
| 24688 |
|
| 24689 |
|
| 24690 |
|
| 24691 |
|
| 24692 |
<span class="grey">Shepler, et al. Standards Track [Page 441]</span></pre> |
| 24693 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-442" ></span> |
| 24694 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24695 |
|
| 24696 |
|
| 24697 |
/* |
| 24698 |
* OPEN: Open a file, potentially receiving an OPEN delegation |
| 24699 |
*/ |
| 24700 |
struct OPEN4args { |
| 24701 |
seqid4 seqid; |
| 24702 |
uint32_t share_access; |
| 24703 |
uint32_t share_deny; |
| 24704 |
open_owner4 owner; |
| 24705 |
openflag4 openhow; |
| 24706 |
open_claim4 claim; |
| 24707 |
}; |
| 24708 |
|
| 24709 |
<span class="h4"><a class="selflink" id="section-18.16.2" href="#section-18.16.2">18.16.2</a>. RESULTS</span> |
| 24710 |
|
| 24711 |
struct open_read_delegation4 { |
| 24712 |
stateid4 stateid; /* Stateid for delegation*/ |
| 24713 |
bool recall; /* Pre-recalled flag for |
| 24714 |
delegations obtained |
| 24715 |
by reclaim (CLAIM_PREVIOUS) */ |
| 24716 |
|
| 24717 |
nfsace4 permissions; /* Defines users who don't |
| 24718 |
need an ACCESS call to |
| 24719 |
open for read */ |
| 24720 |
}; |
| 24721 |
|
| 24722 |
struct open_write_delegation4 { |
| 24723 |
stateid4 stateid; /* Stateid for delegation */ |
| 24724 |
bool recall; /* Pre-recalled flag for |
| 24725 |
delegations obtained |
| 24726 |
by reclaim |
| 24727 |
(CLAIM_PREVIOUS) */ |
| 24728 |
|
| 24729 |
nfs_space_limit4 |
| 24730 |
space_limit; /* Defines condition that |
| 24731 |
the client must check to |
| 24732 |
determine whether the |
| 24733 |
file needs to be flushed |
| 24734 |
to the server on close. */ |
| 24735 |
|
| 24736 |
nfsace4 permissions; /* Defines users who don't |
| 24737 |
need an ACCESS call as |
| 24738 |
part of a delegated |
| 24739 |
open. */ |
| 24740 |
}; |
| 24741 |
|
| 24742 |
|
| 24743 |
|
| 24744 |
|
| 24745 |
|
| 24746 |
|
| 24747 |
|
| 24748 |
<span class="grey">Shepler, et al. Standards Track [Page 442]</span></pre> |
| 24749 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-443" ></span> |
| 24750 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24751 |
|
| 24752 |
|
| 24753 |
enum why_no_delegation4 { /* new to v4.1 */ |
| 24754 |
WND4_NOT_WANTED = 0, |
| 24755 |
WND4_CONTENTION = 1, |
| 24756 |
WND4_RESOURCE = 2, |
| 24757 |
WND4_NOT_SUPP_FTYPE = 3, |
| 24758 |
WND4_WRITE_DELEG_NOT_SUPP_FTYPE = 4, |
| 24759 |
WND4_NOT_SUPP_UPGRADE = 5, |
| 24760 |
WND4_NOT_SUPP_DOWNGRADE = 6, |
| 24761 |
WND4_CANCELLED = 7, |
| 24762 |
WND4_IS_DIR = 8 |
| 24763 |
}; |
| 24764 |
|
| 24765 |
union open_none_delegation4 /* new to v4.1 */ |
| 24766 |
switch (why_no_delegation4 ond_why) { |
| 24767 |
case WND4_CONTENTION: |
| 24768 |
bool ond_server_will_push_deleg; |
| 24769 |
case WND4_RESOURCE: |
| 24770 |
bool ond_server_will_signal_avail; |
| 24771 |
default: |
| 24772 |
void; |
| 24773 |
}; |
| 24774 |
|
| 24775 |
union open_delegation4 |
| 24776 |
switch (open_delegation_type4 delegation_type) { |
| 24777 |
case OPEN_DELEGATE_NONE: |
| 24778 |
void; |
| 24779 |
case OPEN_DELEGATE_READ: |
| 24780 |
open_read_delegation4 read; |
| 24781 |
case OPEN_DELEGATE_WRITE: |
| 24782 |
open_write_delegation4 write; |
| 24783 |
case OPEN_DELEGATE_NONE_EXT: /* new to v4.1 */ |
| 24784 |
open_none_delegation4 od_whynone; |
| 24785 |
}; |
| 24786 |
|
| 24787 |
/* |
| 24788 |
* Result flags |
| 24789 |
*/ |
| 24790 |
|
| 24791 |
/* Client must confirm open */ |
| 24792 |
const OPEN4_RESULT_CONFIRM = 0x00000002; |
| 24793 |
/* Type of file locking behavior at the server */ |
| 24794 |
const OPEN4_RESULT_LOCKTYPE_POSIX = 0x00000004; |
| 24795 |
/* Server will preserve file if removed while open */ |
| 24796 |
const OPEN4_RESULT_PRESERVE_UNLINKED = 0x00000008; |
| 24797 |
|
| 24798 |
|
| 24799 |
|
| 24800 |
|
| 24801 |
|
| 24802 |
|
| 24803 |
|
| 24804 |
<span class="grey">Shepler, et al. Standards Track [Page 443]</span></pre> |
| 24805 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-444" ></span> |
| 24806 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24807 |
|
| 24808 |
|
| 24809 |
/* |
| 24810 |
* Server may use CB_NOTIFY_LOCK on locks |
| 24811 |
* derived from this open |
| 24812 |
*/ |
| 24813 |
const OPEN4_RESULT_MAY_NOTIFY_LOCK = 0x00000020; |
| 24814 |
|
| 24815 |
struct OPEN4resok { |
| 24816 |
stateid4 stateid; /* Stateid for open */ |
| 24817 |
change_info4 cinfo; /* Directory Change Info */ |
| 24818 |
uint32_t rflags; /* Result flags */ |
| 24819 |
bitmap4 attrset; /* attribute set for create*/ |
| 24820 |
open_delegation4 delegation; /* Info on any open |
| 24821 |
delegation */ |
| 24822 |
}; |
| 24823 |
|
| 24824 |
union OPEN4res switch (nfsstat4 status) { |
| 24825 |
case NFS4_OK: |
| 24826 |
/* New CURRENT_FH: opened file */ |
| 24827 |
OPEN4resok resok4; |
| 24828 |
default: |
| 24829 |
void; |
| 24830 |
}; |
| 24831 |
|
| 24832 |
<span class="h4"><a class="selflink" id="section-18.16.3" href="#section-18.16.3">18.16.3</a>. DESCRIPTION</span> |
| 24833 |
|
| 24834 |
The OPEN operation opens a regular file in a directory with the |
| 24835 |
provided name or filehandle. OPEN can also create a file if a name |
| 24836 |
is provided, and the client specifies it wants to create a file. |
| 24837 |
Specification of whether or not a file is to be created, and the |
| 24838 |
method of creation is via the openhow parameter. The openhow |
| 24839 |
parameter consists of a switched union (data type opengflag4), which |
| 24840 |
switches on the value of opentype (OPEN4_NOCREATE or OPEN4_CREATE). |
| 24841 |
If OPEN4_CREATE is specified, this leads to another switched union |
| 24842 |
(data type createhow4) that supports four cases of creation methods: |
| 24843 |
UNCHECKED4, GUARDED4, EXCLUSIVE4, or EXCLUSIVE4_1. If opentype is |
| 24844 |
OPEN4_CREATE, then the claim field of the claim field MUST be one of |
| 24845 |
CLAIM_NULL, CLAIM_DELEGATE_CUR, or CLAIM_DELEGATE_PREV, because these |
| 24846 |
claim methods include a component of a file name. |
| 24847 |
|
| 24848 |
Upon success (which might entail creation of a new file), the current |
| 24849 |
filehandle is replaced by that of the created or existing object. |
| 24850 |
|
| 24851 |
If the current filehandle is a named attribute directory, OPEN will |
| 24852 |
then create or open a named attribute file. Note that exclusive |
| 24853 |
create of a named attribute is not supported. If the createmode is |
| 24854 |
EXCLUSIVE4 or EXCLUSIVE4_1 and the current filehandle is a named |
| 24855 |
attribute directory, the server will return EINVAL. |
| 24856 |
|
| 24857 |
|
| 24858 |
|
| 24859 |
|
| 24860 |
<span class="grey">Shepler, et al. Standards Track [Page 444]</span></pre> |
| 24861 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-445" ></span> |
| 24862 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24863 |
|
| 24864 |
|
| 24865 |
UNCHECKED4 means that the file should be created if a file of that |
| 24866 |
name does not exist and encountering an existing regular file of that |
| 24867 |
name is not an error. For this type of create, createattrs specifies |
| 24868 |
the initial set of attributes for the file. The set of attributes |
| 24869 |
may include any writable attribute valid for regular files. When an |
| 24870 |
UNCHECKED4 create encounters an existing file, the attributes |
| 24871 |
specified by createattrs are not used, except that when createattrs |
| 24872 |
specifies the size attribute with a size of zero, the existing file |
| 24873 |
is truncated. |
| 24874 |
|
| 24875 |
If GUARDED4 is specified, the server checks for the presence of a |
| 24876 |
duplicate object by name before performing the create. If a |
| 24877 |
duplicate exists, NFS4ERR_EXIST is returned. If the object does not |
| 24878 |
exist, the request is performed as described for UNCHECKED4. |
| 24879 |
|
| 24880 |
For the UNCHECKED4 and GUARDED4 cases, where the operation is |
| 24881 |
successful, the server will return to the client an attribute mask |
| 24882 |
signifying which attributes were successfully set for the object. |
| 24883 |
|
| 24884 |
EXCLUSIVE4_1 and EXCLUSIVE4 specify that the server is to follow |
| 24885 |
exclusive creation semantics, using the verifier to ensure exclusive |
| 24886 |
creation of the target. The server should check for the presence of |
| 24887 |
a duplicate object by name. If the object does not exist, the server |
| 24888 |
creates the object and stores the verifier with the object. If the |
| 24889 |
object does exist and the stored verifier matches the client provided |
| 24890 |
verifier, the server uses the existing object as the newly created |
| 24891 |
object. If the stored verifier does not match, then an error of |
| 24892 |
NFS4ERR_EXIST is returned. |
| 24893 |
|
| 24894 |
If using EXCLUSIVE4, and if the server uses attributes to store the |
| 24895 |
exclusive create verifier, the server will signify which attributes |
| 24896 |
it used by setting the appropriate bits in the attribute mask that is |
| 24897 |
returned in the results. Unlike UNCHECKED4, GUARDED4, and |
| 24898 |
EXCLUSIVE4_1, EXCLUSIVE4 does not support the setting of attributes |
| 24899 |
at file creation, and after a successful OPEN via EXCLUSIVE4, the |
| 24900 |
client MUST send a SETATTR to set attributes to a known state. |
| 24901 |
|
| 24902 |
In NFSv4.1, EXCLUSIVE4 has been deprecated in favor of EXCLUSIVE4_1. |
| 24903 |
Unlike EXCLUSIVE4, attributes may be provided in the EXCLUSIVE4_1 |
| 24904 |
case, but because the server may use attributes of the target object |
| 24905 |
to store the verifier, the set of allowable attributes may be fewer |
| 24906 |
than the set of attributes SETATTR allows. The allowable attributes |
| 24907 |
for EXCLUSIVE4_1 are indicated in the suppattr_exclcreat |
| 24908 |
(<a href="#section-5.8.1.14">Section 5.8.1.14</a>) attribute. If the client attempts to set in |
| 24909 |
cva_attrs an attribute that is not in suppattr_exclcreat, the server |
| 24910 |
MUST return NFS4ERR_INVAL. The response field, attrset, indicates |
| 24911 |
both which attributes the server set from cva_attrs and which |
| 24912 |
attributes the server used to store the verifier. As described in |
| 24913 |
|
| 24914 |
|
| 24915 |
|
| 24916 |
<span class="grey">Shepler, et al. Standards Track [Page 445]</span></pre> |
| 24917 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-446" ></span> |
| 24918 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24919 |
|
| 24920 |
|
| 24921 |
<a href="#section-18.16.4">Section 18.16.4</a>, the client can compare cva_attrs.attrmask with |
| 24922 |
attrset to determine which attributes were used to store the |
| 24923 |
verifier. |
| 24924 |
|
| 24925 |
With the addition of persistent sessions and pNFS, under some |
| 24926 |
conditions EXCLUSIVE4 MUST NOT be used by the client or supported by |
| 24927 |
the server. The following table summarizes the appropriate and |
| 24928 |
mandated exclusive create methods for implementations of NFSv4.1: |
| 24929 |
|
| 24930 |
Required methods for exclusive create |
| 24931 |
|
| 24932 |
+----------------+-----------+---------------+----------------------+ |
| 24933 |
| Persistent | Server | Server | Client Allowed | |
| 24934 |
| Reply Cache | Supports | REQUIRED | | |
| 24935 |
| Enabled | pNFS | | | |
| 24936 |
+----------------+-----------+---------------+----------------------+ |
| 24937 |
| no | no | EXCLUSIVE4_1 | EXCLUSIVE4_1 | |
| 24938 |
| | | and | (SHOULD) or | |
| 24939 |
| | | EXCLUSIVE4 | EXCLUSIVE4 (SHOULD | |
| 24940 |
| | | | NOT) | |
| 24941 |
| no | yes | EXCLUSIVE4_1 | EXCLUSIVE4_1 | |
| 24942 |
| yes | no | GUARDED4 | GUARDED4 | |
| 24943 |
| yes | yes | GUARDED4 | GUARDED4 | |
| 24944 |
+----------------+-----------+---------------+----------------------+ |
| 24945 |
|
| 24946 |
Table 10 |
| 24947 |
|
| 24948 |
If CREATE_SESSION4_FLAG_PERSIST is set in the results of |
| 24949 |
CREATE_SESSION, the reply cache is persistent (see <a href="#section-18.36">Section 18.36</a>). |
| 24950 |
If the EXCHGID4_FLAG_USE_PNFS_MDS flag is set in the results from |
| 24951 |
EXCHANGE_ID, the server is a pNFS server (see <a href="#section-18.35">Section 18.35</a>). If the |
| 24952 |
client attempts to use EXCLUSIVE4 on a persistent session, or a |
| 24953 |
session derived from an EXCHGID4_FLAG_USE_PNFS_MDS client ID, the |
| 24954 |
server MUST return NFS4ERR_INVAL. |
| 24955 |
|
| 24956 |
With persistent sessions, exclusive create semantics are fully |
| 24957 |
achievable via GUARDED4, and so EXCLUSIVE4 or EXCLUSIVE4_1 MUST NOT |
| 24958 |
be used. When pNFS is being used, the layout_hint attribute might |
| 24959 |
not be supported after the file is created. Only the EXCLUSIVE4_1 |
| 24960 |
and GUARDED methods of exclusive file creation allow the atomic |
| 24961 |
setting of attributes. |
| 24962 |
|
| 24963 |
For the target directory, the server returns change_info4 information |
| 24964 |
in cinfo. With the atomic field of the change_info4 data type, the |
| 24965 |
server will indicate if the before and after change attributes were |
| 24966 |
obtained atomically with respect to the link creation. |
| 24967 |
|
| 24968 |
|
| 24969 |
|
| 24970 |
|
| 24971 |
|
| 24972 |
<span class="grey">Shepler, et al. Standards Track [Page 446]</span></pre> |
| 24973 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-447" ></span> |
| 24974 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 24975 |
|
| 24976 |
|
| 24977 |
The OPEN operation provides for Windows share reservation capability |
| 24978 |
with the use of the share_access and share_deny fields of the OPEN |
| 24979 |
arguments. The client specifies at OPEN the required share_access |
| 24980 |
and share_deny modes. For clients that do not directly support |
| 24981 |
SHAREs (i.e., UNIX), the expected deny value is |
| 24982 |
OPEN4_SHARE_DENY_NONE. In the case that there is an existing SHARE |
| 24983 |
reservation that conflicts with the OPEN request, the server returns |
| 24984 |
the error NFS4ERR_SHARE_DENIED. For additional discussion of SHARE |
| 24985 |
semantics, see <a href="#section-9.7">Section 9.7</a>. |
| 24986 |
|
| 24987 |
For each OPEN, the client provides a value for the owner field of the |
| 24988 |
OPEN argument. The owner field is of data type open_owner4, and |
| 24989 |
contains a field called clientid and a field called owner. The |
| 24990 |
client can set the clientid field to any value and the server MUST |
| 24991 |
ignore it. Instead, the server MUST derive the client ID from the |
| 24992 |
session ID of the SEQUENCE operation of the COMPOUND request. |
| 24993 |
|
| 24994 |
The "seqid" field of the request is not used in NFSv4.1, but it MAY |
| 24995 |
be any value and the server MUST ignore it. |
| 24996 |
|
| 24997 |
In the case that the client is recovering state from a server |
| 24998 |
failure, the claim field of the OPEN argument is used to signify that |
| 24999 |
the request is meant to reclaim state previously held. |
| 25000 |
|
| 25001 |
The "claim" field of the OPEN argument is used to specify the file to |
| 25002 |
be opened and the state information that the client claims to |
| 25003 |
possess. There are seven claim types as follows: |
| 25004 |
|
| 25005 |
|
| 25006 |
|
| 25007 |
|
| 25008 |
|
| 25009 |
|
| 25010 |
|
| 25011 |
|
| 25012 |
|
| 25013 |
|
| 25014 |
|
| 25015 |
|
| 25016 |
|
| 25017 |
|
| 25018 |
|
| 25019 |
|
| 25020 |
|
| 25021 |
|
| 25022 |
|
| 25023 |
|
| 25024 |
|
| 25025 |
|
| 25026 |
|
| 25027 |
|
| 25028 |
<span class="grey">Shepler, et al. Standards Track [Page 447]</span></pre> |
| 25029 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-448" ></span> |
| 25030 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25031 |
|
| 25032 |
|
| 25033 |
+----------------------+--------------------------------------------+ |
| 25034 |
| open type | description | |
| 25035 |
+----------------------+--------------------------------------------+ |
| 25036 |
| CLAIM_NULL, CLAIM_FH | For the client, this is a new OPEN request | |
| 25037 |
| | and there is no previous state associated | |
| 25038 |
| | with the file for the client. With | |
| 25039 |
| | CLAIM_NULL, the file is identified by the | |
| 25040 |
| | current filehandle and the specified | |
| 25041 |
| | component name. With CLAIM_FH (new to | |
| 25042 |
| | NFSv4.1), the file is identified by just | |
| 25043 |
| | the current filehandle. | |
| 25044 |
| CLAIM_PREVIOUS | The client is claiming basic OPEN state | |
| 25045 |
| | for a file that was held previous to a | |
| 25046 |
| | server restart. Generally used when a | |
| 25047 |
| | server is returning persistent | |
| 25048 |
| | filehandles; the client may not have the | |
| 25049 |
| | file name to reclaim the OPEN. | |
| 25050 |
| CLAIM_DELEGATE_CUR, | The client is claiming a delegation for | |
| 25051 |
| CLAIM_DELEG_CUR_FH | OPEN as granted by the server. Generally, | |
| 25052 |
| | this is done as part of recalling a | |
| 25053 |
| | delegation. With CLAIM_DELEGATE_CUR, the | |
| 25054 |
| | file is identified by the current | |
| 25055 |
| | filehandle and the specified component | |
| 25056 |
| | name. With CLAIM_DELEG_CUR_FH (new to | |
| 25057 |
| | NFSv4.1), the file is identified by just | |
| 25058 |
| | the current filehandle. | |
| 25059 |
| CLAIM_DELEGATE_PREV, | The client is claiming a delegation | |
| 25060 |
| CLAIM_DELEG_PREV_FH | granted to a previous client instance; | |
| 25061 |
| | used after the client restarts. The | |
| 25062 |
| | server MAY support CLAIM_DELEGATE_PREV | |
| 25063 |
| | and/or CLAIM_DELEG_PREV_FH (new to | |
| 25064 |
| | NFSv4.1). If it does support either claim | |
| 25065 |
| | type, CREATE_SESSION MUST NOT remove the | |
| 25066 |
| | client's delegation state, and the server | |
| 25067 |
| | MUST support the DELEGPURGE operation. | |
| 25068 |
+----------------------+--------------------------------------------+ |
| 25069 |
|
| 25070 |
For OPEN requests that reach the server during the grace period, the |
| 25071 |
server returns an error of NFS4ERR_GRACE. The following claim types |
| 25072 |
are exceptions: |
| 25073 |
|
| 25074 |
o OPEN requests specifying the claim type CLAIM_PREVIOUS are devoted |
| 25075 |
to reclaiming opens after a server restart and are typically only |
| 25076 |
valid during the grace period. |
| 25077 |
|
| 25078 |
o OPEN requests specifying the claim types CLAIM_DELEGATE_CUR and |
| 25079 |
CLAIM_DELEG_CUR_FH are valid both during and after the grace |
| 25080 |
period. Since the granting of the delegation that they are |
| 25081 |
|
| 25082 |
|
| 25083 |
|
| 25084 |
<span class="grey">Shepler, et al. Standards Track [Page 448]</span></pre> |
| 25085 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-449" ></span> |
| 25086 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25087 |
|
| 25088 |
|
| 25089 |
subordinate to assures that there is no conflict with locks to be |
| 25090 |
reclaimed by other clients, the server need not return |
| 25091 |
NFS4ERR_GRACE when these are received during the grace period. |
| 25092 |
|
| 25093 |
For any OPEN request, the server may return an OPEN delegation, which |
| 25094 |
allows further opens and closes to be handled locally on the client |
| 25095 |
as described in <a href="#section-10.4">Section 10.4</a>. Note that delegation is up to the |
| 25096 |
server to decide. The client should never assume that delegation |
| 25097 |
will or will not be granted in a particular instance. It should |
| 25098 |
always be prepared for either case. A partial exception is the |
| 25099 |
reclaim (CLAIM_PREVIOUS) case, in which a delegation type is claimed. |
| 25100 |
In this case, delegation will always be granted, although the server |
| 25101 |
may specify an immediate recall in the delegation structure. |
| 25102 |
|
| 25103 |
The rflags returned by a successful OPEN allow the server to return |
| 25104 |
information governing how the open file is to be handled. |
| 25105 |
|
| 25106 |
o OPEN4_RESULT_CONFIRM is deprecated and MUST NOT be returned by an |
| 25107 |
NFSv4.1 server. |
| 25108 |
|
| 25109 |
o OPEN4_RESULT_LOCKTYPE_POSIX indicates that the server's byte-range |
| 25110 |
locking behavior supports the complete set of POSIX locking |
| 25111 |
techniques [<a href="#ref-24" title="">24</a>]. From this, the client can choose to manage byte- |
| 25112 |
range locking state in a way to handle a mismatch of byte-range |
| 25113 |
locking management. |
| 25114 |
|
| 25115 |
o OPEN4_RESULT_PRESERVE_UNLINKED indicates that the server will |
| 25116 |
preserve the open file if the client (or any other client) removes |
| 25117 |
the file as long as it is open. Furthermore, the server promises |
| 25118 |
to preserve the file through the grace period after server |
| 25119 |
restart, thereby giving the client the opportunity to reclaim its |
| 25120 |
open. |
| 25121 |
|
| 25122 |
o OPEN4_RESULT_MAY_NOTIFY_LOCK indicates that the server may attempt |
| 25123 |
CB_NOTIFY_LOCK callbacks for locks on this file. This flag is a |
| 25124 |
hint only, and may be safely ignored by the client. |
| 25125 |
|
| 25126 |
If the component is of zero length, NFS4ERR_INVAL will be returned. |
| 25127 |
The component is also subject to the normal UTF-8, character support, |
| 25128 |
and name checks. See <a href="#section-14.5">Section 14.5</a> for further discussion. |
| 25129 |
|
| 25130 |
When an OPEN is done and the specified open-owner already has the |
| 25131 |
resulting filehandle open, the result is to "OR" together the new |
| 25132 |
share and deny status together with the existing status. In this |
| 25133 |
case, only a single CLOSE need be done, even though multiple OPENs |
| 25134 |
were completed. When such an OPEN is done, checking of share |
| 25135 |
reservations for the new OPEN proceeds normally, with no exception |
| 25136 |
for the existing OPEN held by the same open-owner. In this case, the |
| 25137 |
|
| 25138 |
|
| 25139 |
|
| 25140 |
<span class="grey">Shepler, et al. Standards Track [Page 449]</span></pre> |
| 25141 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-450" ></span> |
| 25142 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25143 |
|
| 25144 |
|
| 25145 |
stateid returned as an "other" field that matches that of the |
| 25146 |
previous open while the "seqid" field is incremented to reflect the |
| 25147 |
change status due to the new open. |
| 25148 |
|
| 25149 |
If the underlying file system at the server is only accessible in a |
| 25150 |
read-only mode and the OPEN request has specified ACCESS_WRITE or |
| 25151 |
ACCESS_BOTH, the server will return NFS4ERR_ROFS to indicate a read- |
| 25152 |
only file system. |
| 25153 |
|
| 25154 |
As with the CREATE operation, the server MUST derive the owner, owner |
| 25155 |
ACE, group, or group ACE if any of the four attributes are required |
| 25156 |
and supported by the server's file system. For an OPEN with the |
| 25157 |
EXCLUSIVE4 createmode, the server has no choice, since such OPEN |
| 25158 |
calls do not include the createattrs field. Conversely, if |
| 25159 |
createattrs (UNCHECKED4 or GUARDED4) or cva_attrs (EXCLUSIVE4_1) is |
| 25160 |
specified, and includes an owner, owner_group, or ACE that the |
| 25161 |
principal in the RPC call's credentials does not have authorization |
| 25162 |
to create files for, then the server may return NFS4ERR_PERM. |
| 25163 |
|
| 25164 |
In the case of an OPEN that specifies a size of zero (e.g., |
| 25165 |
truncation) and the file has named attributes, the named attributes |
| 25166 |
are left as is and are not removed. |
| 25167 |
|
| 25168 |
NFSv4.1 gives more precise control to clients over acquisition of |
| 25169 |
delegations via the following new flags for the share_access field of |
| 25170 |
OPEN4args: |
| 25171 |
|
| 25172 |
OPEN4_SHARE_ACCESS_WANT_READ_DELEG |
| 25173 |
|
| 25174 |
OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG |
| 25175 |
|
| 25176 |
OPEN4_SHARE_ACCESS_WANT_ANY_DELEG |
| 25177 |
|
| 25178 |
OPEN4_SHARE_ACCESS_WANT_NO_DELEG |
| 25179 |
|
| 25180 |
OPEN4_SHARE_ACCESS_WANT_CANCEL |
| 25181 |
|
| 25182 |
OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL |
| 25183 |
|
| 25184 |
OPEN4_SHARE_ACCESS_WANT_PUSH_DELEG_WHEN_UNCONTENDED |
| 25185 |
|
| 25186 |
If (share_access & OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) is not zero, |
| 25187 |
then the client will have specified one and only one of: |
| 25188 |
|
| 25189 |
OPEN4_SHARE_ACCESS_WANT_READ_DELEG |
| 25190 |
|
| 25191 |
OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG |
| 25192 |
|
| 25193 |
|
| 25194 |
|
| 25195 |
|
| 25196 |
<span class="grey">Shepler, et al. Standards Track [Page 450]</span></pre> |
| 25197 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-451" ></span> |
| 25198 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25199 |
|
| 25200 |
|
| 25201 |
OPEN4_SHARE_ACCESS_WANT_ANY_DELEG |
| 25202 |
|
| 25203 |
OPEN4_SHARE_ACCESS_WANT_NO_DELEG |
| 25204 |
|
| 25205 |
OPEN4_SHARE_ACCESS_WANT_CANCEL |
| 25206 |
|
| 25207 |
Otherwise, the client is neither indicating a desire nor a non-desire |
| 25208 |
for a delegation, and the server MAY or MAY not return a delegation |
| 25209 |
in the OPEN response. |
| 25210 |
|
| 25211 |
If the server supports the new _WANT_ flags and the client sends one |
| 25212 |
or more of the new flags, then in the event the server does not |
| 25213 |
return a delegation, it MUST return a delegation type of |
| 25214 |
OPEN_DELEGATE_NONE_EXT. The field ond_why in the reply indicates why |
| 25215 |
no delegation was returned and will be one of: |
| 25216 |
|
| 25217 |
WND4_NOT_WANTED The client specified |
| 25218 |
OPEN4_SHARE_ACCESS_WANT_NO_DELEG. |
| 25219 |
|
| 25220 |
WND4_CONTENTION There is a conflicting delegation or open on the |
| 25221 |
file. |
| 25222 |
|
| 25223 |
WND4_RESOURCE Resource limitations prevent the server from granting |
| 25224 |
a delegation. |
| 25225 |
|
| 25226 |
WND4_NOT_SUPP_FTYPE The server does not support delegations on this |
| 25227 |
file type. |
| 25228 |
|
| 25229 |
WND4_WRITE_DELEG_NOT_SUPP_FTYPE The server does not support |
| 25230 |
OPEN_DELEGATE_WRITE delegations on this file type. |
| 25231 |
|
| 25232 |
WND4_NOT_SUPP_UPGRADE The server does not support atomic upgrade of |
| 25233 |
an OPEN_DELEGATE_READ delegation to an OPEN_DELEGATE_WRITE |
| 25234 |
delegation. |
| 25235 |
|
| 25236 |
WND4_NOT_SUPP_DOWNGRADE The server does not support atomic downgrade |
| 25237 |
of an OPEN_DELEGATE_WRITE delegation to an OPEN_DELEGATE_READ |
| 25238 |
delegation. |
| 25239 |
|
| 25240 |
WND4_CANCELED The client specified OPEN4_SHARE_ACCESS_WANT_CANCEL |
| 25241 |
and now any "want" for this file object is cancelled. |
| 25242 |
|
| 25243 |
WND4_IS_DIR The specified file object is a directory, and the |
| 25244 |
operation is OPEN or WANT_DELEGATION, which do not support |
| 25245 |
delegations on directories. |
| 25246 |
|
| 25247 |
|
| 25248 |
|
| 25249 |
|
| 25250 |
|
| 25251 |
|
| 25252 |
<span class="grey">Shepler, et al. Standards Track [Page 451]</span></pre> |
| 25253 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-452" ></span> |
| 25254 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25255 |
|
| 25256 |
|
| 25257 |
OPEN4_SHARE_ACCESS_WANT_READ_DELEG, |
| 25258 |
OPEN_SHARE_ACCESS_WANT_WRITE_DELEG, or |
| 25259 |
OPEN_SHARE_ACCESS_WANT_ANY_DELEG mean, respectively, the client wants |
| 25260 |
an OPEN_DELEGATE_READ, OPEN_DELEGATE_WRITE, or any delegation |
| 25261 |
regardless which of OPEN4_SHARE_ACCESS_READ, |
| 25262 |
OPEN4_SHARE_ACCESS_WRITE, or OPEN4_SHARE_ACCESS_BOTH is set. If the |
| 25263 |
client has an OPEN_DELEGATE_READ delegation on a file and requests an |
| 25264 |
OPEN_DELEGATE_WRITE delegation, then the client is requesting atomic |
| 25265 |
upgrade of its OPEN_DELEGATE_READ delegation to an |
| 25266 |
OPEN_DELEGATE_WRITE delegation. If the client has an |
| 25267 |
OPEN_DELEGATE_WRITE delegation on a file and requests an |
| 25268 |
OPEN_DELEGATE_READ delegation, then the client is requesting atomic |
| 25269 |
downgrade to an OPEN_DELEGATE_READ delegation. A server MAY support |
| 25270 |
atomic upgrade or downgrade. If it does, then the returned |
| 25271 |
delegation_type of OPEN_DELEGATE_READ or OPEN_DELEGATE_WRITE that is |
| 25272 |
different from the delegation type the client currently has, |
| 25273 |
indicates successful upgrade or downgrade. If the server does not |
| 25274 |
support atomic delegation upgrade or downgrade, then ond_why will be |
| 25275 |
set to WND4_NOT_SUPP_UPGRADE or WND4_NOT_SUPP_DOWNGRADE. |
| 25276 |
|
| 25277 |
OPEN4_SHARE_ACCESS_WANT_NO_DELEG means that the client wants no |
| 25278 |
delegation. |
| 25279 |
|
| 25280 |
OPEN4_SHARE_ACCESS_WANT_CANCEL means that the client wants no |
| 25281 |
delegation and wants to cancel any previously registered "want" for a |
| 25282 |
delegation. |
| 25283 |
|
| 25284 |
The client may set one or both of |
| 25285 |
OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL and |
| 25286 |
OPEN4_SHARE_ACCESS_WANT_PUSH_DELEG_WHEN_UNCONTENDED. However, they |
| 25287 |
will have no effect unless one of following is set: |
| 25288 |
|
| 25289 |
o OPEN4_SHARE_ACCESS_WANT_READ_DELEG |
| 25290 |
|
| 25291 |
o OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG |
| 25292 |
|
| 25293 |
o OPEN4_SHARE_ACCESS_WANT_ANY_DELEG |
| 25294 |
|
| 25295 |
If the client specifies |
| 25296 |
OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL, then it wishes |
| 25297 |
to register a "want" for a delegation, in the event the OPEN results |
| 25298 |
do not include a delegation. If so and the server denies the |
| 25299 |
delegation due to insufficient resources, the server MAY later inform |
| 25300 |
the client, via the CB_RECALLABLE_OBJ_AVAIL operation, that the |
| 25301 |
resource limitation condition has eased. The server will tell the |
| 25302 |
client that it intends to send a future CB_RECALLABLE_OBJ_AVAIL |
| 25303 |
operation by setting delegation_type in the results to |
| 25304 |
OPEN_DELEGATE_NONE_EXT, ond_why to WND4_RESOURCE, and |
| 25305 |
|
| 25306 |
|
| 25307 |
|
| 25308 |
<span class="grey">Shepler, et al. Standards Track [Page 452]</span></pre> |
| 25309 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-453" ></span> |
| 25310 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25311 |
|
| 25312 |
|
| 25313 |
ond_server_will_signal_avail set to TRUE. If |
| 25314 |
ond_server_will_signal_avail is set to TRUE, the server MUST later |
| 25315 |
send a CB_RECALLABLE_OBJ_AVAIL operation. |
| 25316 |
|
| 25317 |
If the client specifies |
| 25318 |
OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_UNCONTENDED, then it wishes |
| 25319 |
to register a "want" for a delegation, in the event the OPEN results |
| 25320 |
do not include a delegation. If so and the server denies the |
| 25321 |
delegation due to contention, the server MAY later inform the client, |
| 25322 |
via the CB_PUSH_DELEG operation, that the contention condition has |
| 25323 |
eased. The server will tell the client that it intends to send a |
| 25324 |
future CB_PUSH_DELEG operation by setting delegation_type in the |
| 25325 |
results to OPEN_DELEGATE_NONE_EXT, ond_why to WND4_CONTENTION, and |
| 25326 |
ond_server_will_push_deleg to TRUE. If ond_server_will_push_deleg is |
| 25327 |
TRUE, the server MUST later send a CB_PUSH_DELEG operation. |
| 25328 |
|
| 25329 |
If the client has previously registered a want for a delegation on a |
| 25330 |
file, and then sends a request to register a want for a delegation on |
| 25331 |
the same file, the server MUST return a new error: |
| 25332 |
NFS4ERR_DELEG_ALREADY_WANTED. If the client wishes to register a |
| 25333 |
different type of delegation want for the same file, it MUST cancel |
| 25334 |
the existing delegation WANT. |
| 25335 |
|
| 25336 |
<span class="h4"><a class="selflink" id="section-18.16.4" href="#section-18.16.4">18.16.4</a>. IMPLEMENTATION</span> |
| 25337 |
|
| 25338 |
In absence of a persistent session, the client invokes exclusive |
| 25339 |
create by setting the how parameter to EXCLUSIVE4 or EXCLUSIVE4_1. |
| 25340 |
In these cases, the client provides a verifier that can reasonably be |
| 25341 |
expected to be unique. A combination of a client identifier, perhaps |
| 25342 |
the client network address, and a unique number generated by the |
| 25343 |
client, perhaps the RPC transaction identifier, may be appropriate. |
| 25344 |
|
| 25345 |
If the object does not exist, the server creates the object and |
| 25346 |
stores the verifier in stable storage. For file systems that do not |
| 25347 |
provide a mechanism for the storage of arbitrary file attributes, the |
| 25348 |
server may use one or more elements of the object's metadata to store |
| 25349 |
the verifier. The verifier MUST be stored in stable storage to |
| 25350 |
prevent erroneous failure on retransmission of the request. It is |
| 25351 |
assumed that an exclusive create is being performed because exclusive |
| 25352 |
semantics are critical to the application. Because of the expected |
| 25353 |
usage, exclusive CREATE does not rely solely on the server's reply |
| 25354 |
cache for storage of the verifier. A nonpersistent reply cache does |
| 25355 |
not survive a crash and the session and reply cache may be deleted |
| 25356 |
after a network partition that exceeds the lease time, thus opening |
| 25357 |
failure windows. |
| 25358 |
|
| 25359 |
|
| 25360 |
|
| 25361 |
|
| 25362 |
|
| 25363 |
|
| 25364 |
<span class="grey">Shepler, et al. Standards Track [Page 453]</span></pre> |
| 25365 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-454" ></span> |
| 25366 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25367 |
|
| 25368 |
|
| 25369 |
An NFSv4.1 server SHOULD NOT store the verifier in any of the file's |
| 25370 |
RECOMMENDED or REQUIRED attributes. If it does, the server SHOULD |
| 25371 |
use time_modify_set or time_access_set to store the verifier. The |
| 25372 |
server SHOULD NOT store the verifier in the following attributes: |
| 25373 |
|
| 25374 |
acl (it is desirable for access control to be established at |
| 25375 |
creation), |
| 25376 |
|
| 25377 |
dacl (ditto), |
| 25378 |
|
| 25379 |
mode (ditto), |
| 25380 |
|
| 25381 |
owner (ditto), |
| 25382 |
|
| 25383 |
owner_group (ditto), |
| 25384 |
|
| 25385 |
retentevt_set (it may be desired to establish retention at |
| 25386 |
creation) |
| 25387 |
|
| 25388 |
retention_hold (ditto), |
| 25389 |
|
| 25390 |
retention_set (ditto), |
| 25391 |
|
| 25392 |
sacl (it is desirable for auditing control to be established at |
| 25393 |
creation), |
| 25394 |
|
| 25395 |
size (on some servers, size may have a limited range of values), |
| 25396 |
|
| 25397 |
mode_set_masked (as with mode), |
| 25398 |
|
| 25399 |
and |
| 25400 |
|
| 25401 |
time_creation (a meaningful file creation should be set when the |
| 25402 |
file is created). |
| 25403 |
|
| 25404 |
Another alternative for the server is to use a named attribute to |
| 25405 |
store the verifier. |
| 25406 |
|
| 25407 |
Because the EXCLUSIVE4 create method does not specify initial |
| 25408 |
attributes when processing an EXCLUSIVE4 create, the server |
| 25409 |
|
| 25410 |
o SHOULD set the owner of the file to that corresponding to the |
| 25411 |
credential of request's RPC header. |
| 25412 |
|
| 25413 |
o SHOULD NOT leave the file's access control to anyone but the owner |
| 25414 |
of the file. |
| 25415 |
|
| 25416 |
|
| 25417 |
|
| 25418 |
|
| 25419 |
|
| 25420 |
<span class="grey">Shepler, et al. Standards Track [Page 454]</span></pre> |
| 25421 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-455" ></span> |
| 25422 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25423 |
|
| 25424 |
|
| 25425 |
If the server cannot support exclusive create semantics, possibly |
| 25426 |
because of the requirement to commit the verifier to stable storage, |
| 25427 |
it should fail the OPEN request with the error NFS4ERR_NOTSUPP. |
| 25428 |
|
| 25429 |
During an exclusive CREATE request, if the object already exists, the |
| 25430 |
server reconstructs the object's verifier and compares it with the |
| 25431 |
verifier in the request. If they match, the server treats the |
| 25432 |
request as a success. The request is presumed to be a duplicate of |
| 25433 |
an earlier, successful request for which the reply was lost and that |
| 25434 |
the server duplicate request cache mechanism did not detect. If the |
| 25435 |
verifiers do not match, the request is rejected with the status |
| 25436 |
NFS4ERR_EXIST. |
| 25437 |
|
| 25438 |
After the client has performed a successful exclusive create, the |
| 25439 |
attrset response indicates which attributes were used to store the |
| 25440 |
verifier. If EXCLUSIVE4 was used, the attributes set in attrset were |
| 25441 |
used for the verifier. If EXCLUSIVE4_1 was used, the client |
| 25442 |
determines the attributes used for the verifier by comparing attrset |
| 25443 |
with cva_attrs.attrmask; any bits set in the former but not the |
| 25444 |
latter identify the attributes used to store the verifier. The |
| 25445 |
client MUST immediately send a SETATTR to set attributes used to |
| 25446 |
store the verifier. Until it does so, the attributes used to store |
| 25447 |
the verifier cannot be relied upon. The subsequent SETATTR MUST NOT |
| 25448 |
occur in the same COMPOUND request as the OPEN. |
| 25449 |
|
| 25450 |
Unless a persistent session is used, use of the GUARDED4 attribute |
| 25451 |
does not provide exactly once semantics. In particular, if a reply |
| 25452 |
is lost and the server does not detect the retransmission of the |
| 25453 |
request, the operation can fail with NFS4ERR_EXIST, even though the |
| 25454 |
create was performed successfully. The client would use this |
| 25455 |
behavior in the case that the application has not requested an |
| 25456 |
exclusive create but has asked to have the file truncated when the |
| 25457 |
file is opened. In the case of the client timing out and |
| 25458 |
retransmitting the create request, the client can use GUARDED4 to |
| 25459 |
prevent against a sequence like create, write, create (retransmitted) |
| 25460 |
from occurring. |
| 25461 |
|
| 25462 |
For SHARE reservations, the value of the expression (share_access & |
| 25463 |
~OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) MUST be one of |
| 25464 |
OPEN4_SHARE_ACCESS_READ, OPEN4_SHARE_ACCESS_WRITE, or |
| 25465 |
OPEN4_SHARE_ACCESS_BOTH. If not, the server MUST return |
| 25466 |
NFS4ERR_INVAL. The value of share_deny MUST be one of |
| 25467 |
OPEN4_SHARE_DENY_NONE, OPEN4_SHARE_DENY_READ, OPEN4_SHARE_DENY_WRITE, |
| 25468 |
or OPEN4_SHARE_DENY_BOTH. If not, the server MUST return |
| 25469 |
NFS4ERR_INVAL. |
| 25470 |
|
| 25471 |
|
| 25472 |
|
| 25473 |
|
| 25474 |
|
| 25475 |
|
| 25476 |
<span class="grey">Shepler, et al. Standards Track [Page 455]</span></pre> |
| 25477 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-456" ></span> |
| 25478 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25479 |
|
| 25480 |
|
| 25481 |
Based on the share_access value (OPEN4_SHARE_ACCESS_READ, |
| 25482 |
OPEN4_SHARE_ACCESS_WRITE, or OPEN4_SHARE_ACCESS_BOTH), the client |
| 25483 |
should check that the requester has the proper access rights to |
| 25484 |
perform the specified operation. This would generally be the results |
| 25485 |
of applying the ACL access rules to the file for the current |
| 25486 |
requester. However, just as with the ACCESS operation, the client |
| 25487 |
should not attempt to second-guess the server's decisions, as access |
| 25488 |
rights may change and may be subject to server administrative |
| 25489 |
controls outside the ACL framework. If the requester's READ or WRITE |
| 25490 |
operation is not authorized (depending on the share_access value), |
| 25491 |
the server MUST return NFS4ERR_ACCESS. |
| 25492 |
|
| 25493 |
Note that if the client ID was not created with the |
| 25494 |
EXCHGID4_FLAG_BIND_PRINC_STATEID capability set in the reply to |
| 25495 |
EXCHANGE_ID, then the server MUST NOT impose any requirement that |
| 25496 |
READs and WRITEs sent for an open file have the same credentials as |
| 25497 |
the OPEN itself, and the server is REQUIRED to perform access |
| 25498 |
checking on the READs and WRITEs themselves. Otherwise, if the reply |
| 25499 |
to EXCHANGE_ID did have EXCHGID4_FLAG_BIND_PRINC_STATEID set, then |
| 25500 |
with one exception, the credentials used in the OPEN request MUST |
| 25501 |
match those used in the READs and WRITEs, and the stateids in the |
| 25502 |
READs and WRITEs MUST match, or be derived from the stateid from the |
| 25503 |
reply to OPEN. The exception is if SP4_SSV or SP4_MACH_CRED state |
| 25504 |
protection is used, and the spo_must_allow result of EXCHANGE_ID |
| 25505 |
includes the READ and/or WRITE operations. In that case, the machine |
| 25506 |
or SSV credential will be allowed to send READ and/or WRITE. See |
| 25507 |
<a href="#section-18.35">Section 18.35</a>. |
| 25508 |
|
| 25509 |
If the component provided to OPEN is a symbolic link, the error |
| 25510 |
NFS4ERR_SYMLINK will be returned to the client, while if it is a |
| 25511 |
directory the error NFS4ERR_ISDIR will be returned. If the component |
| 25512 |
is neither of those but not an ordinary file, the error |
| 25513 |
NFS4ERR_WRONG_TYPE is returned. If the current filehandle is not a |
| 25514 |
directory, the error NFS4ERR_NOTDIR will be returned. |
| 25515 |
|
| 25516 |
The use of the OPEN4_RESULT_PRESERVE_UNLINKED result flag allows a |
| 25517 |
client to avoid the common implementation practice of renaming an |
| 25518 |
open file to ".nfs<unique value>" after it removes the file. After |
| 25519 |
the server returns OPEN4_RESULT_PRESERVE_UNLINKED, if a client sends |
| 25520 |
a REMOVE operation that would reduce the file's link count to zero, |
| 25521 |
the server SHOULD report a value of zero for the numlinks attribute |
| 25522 |
on the file. |
| 25523 |
|
| 25524 |
If another client has a delegation of the file being opened that |
| 25525 |
conflicts with open being done (sometimes depending on the |
| 25526 |
share_access or share_deny value specified), the delegation(s) MUST |
| 25527 |
be recalled, and the operation cannot proceed until each such |
| 25528 |
delegation is returned or revoked. Except where this happens very |
| 25529 |
|
| 25530 |
|
| 25531 |
|
| 25532 |
<span class="grey">Shepler, et al. Standards Track [Page 456]</span></pre> |
| 25533 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-457" ></span> |
| 25534 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25535 |
|
| 25536 |
|
| 25537 |
quickly, one or more NFS4ERR_DELAY errors will be returned to |
| 25538 |
requests made while delegation remains outstanding. In the case of |
| 25539 |
an OPEN_DELEGATE_WRITE delegation, any open by a different client |
| 25540 |
will conflict, while for an OPEN_DELEGATE_READ delegation, only opens |
| 25541 |
with one of the following characteristics will be considered |
| 25542 |
conflicting: |
| 25543 |
|
| 25544 |
o The value of share_access includes the bit |
| 25545 |
OPEN4_SHARE_ACCESS_WRITE. |
| 25546 |
|
| 25547 |
o The value of share_deny specifies OPEN4_SHARE_DENY_READ or |
| 25548 |
OPEN4_SHARE_DENY_BOTH. |
| 25549 |
|
| 25550 |
o OPEN4_CREATE is specified together with UNCHECKED4, the size |
| 25551 |
attribute is specified as zero (for truncation), and an existing |
| 25552 |
file is truncated. |
| 25553 |
|
| 25554 |
If OPEN4_CREATE is specified and the file does not exist and the |
| 25555 |
current filehandle designates a directory for which another client |
| 25556 |
holds a directory delegation, then, unless the delegation is such |
| 25557 |
that the situation can be resolved by sending a notification, the |
| 25558 |
delegation MUST be recalled, and the operation cannot proceed until |
| 25559 |
the delegation is returned or revoked. Except where this happens |
| 25560 |
very quickly, one or more NFS4ERR_DELAY errors will be returned to |
| 25561 |
requests made while delegation remains outstanding. |
| 25562 |
|
| 25563 |
If OPEN4_CREATE is specified and the file does not exist and the |
| 25564 |
current filehandle designates a directory for which one or more |
| 25565 |
directory delegations exist, then, when those delegations request |
| 25566 |
such notifications, NOTIFY4_ADD_ENTRY will be generated as a result |
| 25567 |
of this operation. |
| 25568 |
|
| 25569 |
<span class="h5"><a class="selflink" id="section-18.16.4.1" href="#section-18.16.4.1">18.16.4.1</a>. Warning to Client Implementors</span> |
| 25570 |
|
| 25571 |
OPEN resembles LOOKUP in that it generates a filehandle for the |
| 25572 |
client to use. Unlike LOOKUP though, OPEN creates server state on |
| 25573 |
the filehandle. In normal circumstances, the client can only release |
| 25574 |
this state with a CLOSE operation. CLOSE uses the current filehandle |
| 25575 |
to determine which file to close. Therefore, the client MUST follow |
| 25576 |
every OPEN operation with a GETFH operation in the same COMPOUND |
| 25577 |
procedure. This will supply the client with the filehandle such that |
| 25578 |
CLOSE can be used appropriately. |
| 25579 |
|
| 25580 |
Simply waiting for the lease on the file to expire is insufficient |
| 25581 |
because the server may maintain the state indefinitely as long as |
| 25582 |
another client does not attempt to make a conflicting access to the |
| 25583 |
same file. |
| 25584 |
|
| 25585 |
|
| 25586 |
|
| 25587 |
|
| 25588 |
<span class="grey">Shepler, et al. Standards Track [Page 457]</span></pre> |
| 25589 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-458" ></span> |
| 25590 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25591 |
|
| 25592 |
|
| 25593 |
See also <a href="#section-2.10.6.4">Section 2.10.6.4</a>. |
| 25594 |
|
| 25595 |
<span class="h3"><a class="selflink" id="section-18.17" href="#section-18.17">18.17</a>. Operation 19: OPENATTR - Open Named Attribute Directory</span> |
| 25596 |
|
| 25597 |
<span class="h4"><a class="selflink" id="section-18.17.1" href="#section-18.17.1">18.17.1</a>. ARGUMENTS</span> |
| 25598 |
|
| 25599 |
struct OPENATTR4args { |
| 25600 |
/* CURRENT_FH: object */ |
| 25601 |
bool createdir; |
| 25602 |
}; |
| 25603 |
|
| 25604 |
|
| 25605 |
<span class="h4"><a class="selflink" id="section-18.17.2" href="#section-18.17.2">18.17.2</a>. RESULTS</span> |
| 25606 |
|
| 25607 |
struct OPENATTR4res { |
| 25608 |
/* |
| 25609 |
* If status is NFS4_OK, |
| 25610 |
* new CURRENT_FH: named attribute |
| 25611 |
* directory |
| 25612 |
*/ |
| 25613 |
nfsstat4 status; |
| 25614 |
}; |
| 25615 |
|
| 25616 |
<span class="h4"><a class="selflink" id="section-18.17.3" href="#section-18.17.3">18.17.3</a>. DESCRIPTION</span> |
| 25617 |
|
| 25618 |
The OPENATTR operation is used to obtain the filehandle of the named |
| 25619 |
attribute directory associated with the current filehandle. The |
| 25620 |
result of the OPENATTR will be a filehandle to an object of type |
| 25621 |
NF4ATTRDIR. From this filehandle, READDIR and LOOKUP operations can |
| 25622 |
be used to obtain filehandles for the various named attributes |
| 25623 |
associated with the original file system object. Filehandles |
| 25624 |
returned within the named attribute directory will designate objects |
| 25625 |
of type of NF4NAMEDATTR. |
| 25626 |
|
| 25627 |
The createdir argument allows the client to signify if a named |
| 25628 |
attribute directory should be created as a result of the OPENATTR |
| 25629 |
operation. Some clients may use the OPENATTR operation with a value |
| 25630 |
of FALSE for createdir to determine if any named attributes exist for |
| 25631 |
the object. If none exist, then NFS4ERR_NOENT will be returned. If |
| 25632 |
createdir has a value of TRUE and no named attribute directory |
| 25633 |
exists, one is created and its filehandle becomes the current |
| 25634 |
filehandle. On the other hand, if createdir has a value of TRUE and |
| 25635 |
the named attribute directory already exists, no error results and |
| 25636 |
the filehandle of the existing directory becomes the current |
| 25637 |
filehandle. The creation of a named attribute directory assumes that |
| 25638 |
the server has implemented named attribute support in this fashion |
| 25639 |
and is not required to do so by this definition. |
| 25640 |
|
| 25641 |
|
| 25642 |
|
| 25643 |
|
| 25644 |
<span class="grey">Shepler, et al. Standards Track [Page 458]</span></pre> |
| 25645 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-459" ></span> |
| 25646 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25647 |
|
| 25648 |
|
| 25649 |
If the current file handle designates an object of type NF4NAMEDATTR |
| 25650 |
(a named attribute) or NF4ATTRDIR (a named attribute directory), an |
| 25651 |
error of NFS4ERR_WRONG_TYPE is returned to the client. Named |
| 25652 |
attributes or a named attribute directory MUST NOT have their own |
| 25653 |
named attributes. |
| 25654 |
|
| 25655 |
<span class="h4"><a class="selflink" id="section-18.17.4" href="#section-18.17.4">18.17.4</a>. IMPLEMENTATION</span> |
| 25656 |
|
| 25657 |
If the server does not support named attributes for the current |
| 25658 |
filehandle, an error of NFS4ERR_NOTSUPP will be returned to the |
| 25659 |
client. |
| 25660 |
|
| 25661 |
<span class="h3"><a class="selflink" id="section-18.18" href="#section-18.18">18.18</a>. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access</span> |
| 25662 |
|
| 25663 |
<span class="h4"><a class="selflink" id="section-18.18.1" href="#section-18.18.1">18.18.1</a>. ARGUMENTS</span> |
| 25664 |
|
| 25665 |
struct OPEN_DOWNGRADE4args { |
| 25666 |
/* CURRENT_FH: opened file */ |
| 25667 |
stateid4 open_stateid; |
| 25668 |
seqid4 seqid; |
| 25669 |
uint32_t share_access; |
| 25670 |
uint32_t share_deny; |
| 25671 |
}; |
| 25672 |
|
| 25673 |
<span class="h4"><a class="selflink" id="section-18.18.2" href="#section-18.18.2">18.18.2</a>. RESULTS</span> |
| 25674 |
|
| 25675 |
struct OPEN_DOWNGRADE4resok { |
| 25676 |
stateid4 open_stateid; |
| 25677 |
}; |
| 25678 |
|
| 25679 |
union OPEN_DOWNGRADE4res switch(nfsstat4 status) { |
| 25680 |
case NFS4_OK: |
| 25681 |
OPEN_DOWNGRADE4resok resok4; |
| 25682 |
default: |
| 25683 |
void; |
| 25684 |
}; |
| 25685 |
|
| 25686 |
<span class="h4"><a class="selflink" id="section-18.18.3" href="#section-18.18.3">18.18.3</a>. DESCRIPTION</span> |
| 25687 |
|
| 25688 |
This operation is used to adjust the access and deny states for a |
| 25689 |
given open. This is necessary when a given open-owner opens the same |
| 25690 |
file multiple times with different access and deny values. In this |
| 25691 |
situation, a close of one of the opens may change the appropriate |
| 25692 |
share_access and share_deny flags to remove bits associated with |
| 25693 |
opens no longer in effect. |
| 25694 |
|
| 25695 |
|
| 25696 |
|
| 25697 |
|
| 25698 |
|
| 25699 |
|
| 25700 |
<span class="grey">Shepler, et al. Standards Track [Page 459]</span></pre> |
| 25701 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-460" ></span> |
| 25702 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25703 |
|
| 25704 |
|
| 25705 |
Valid values for the expression (share_access & |
| 25706 |
~OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) are OPEN4_SHARE_ACCESS_READ, |
| 25707 |
OPEN4_SHARE_ACCESS_WRITE, or OPEN4_SHARE_ACCESS_BOTH. If the client |
| 25708 |
specifies other values, the server MUST reply with NFS4ERR_INVAL. |
| 25709 |
|
| 25710 |
Valid values for the share_deny field are OPEN4_SHARE_DENY_NONE, |
| 25711 |
OPEN4_SHARE_DENY_READ, OPEN4_SHARE_DENY_WRITE, or |
| 25712 |
OPEN4_SHARE_DENY_BOTH. If the client specifies other values, the |
| 25713 |
server MUST reply with NFS4ERR_INVAL. |
| 25714 |
|
| 25715 |
After checking for valid values of share_access and share_deny, the |
| 25716 |
server replaces the current access and deny modes on the file with |
| 25717 |
share_access and share_deny subject to the following constraints: |
| 25718 |
|
| 25719 |
o The bits in share_access SHOULD equal the union of the |
| 25720 |
share_access bits (not including OPEN4_SHARE_WANT_* bits) |
| 25721 |
specified for some subset of the OPENs in effect for the current |
| 25722 |
open-owner on the current file. |
| 25723 |
|
| 25724 |
o The bits in share_deny SHOULD equal the union of the share_deny |
| 25725 |
bits specified for some subset of the OPENs in effect for the |
| 25726 |
current open-owner on the current file. |
| 25727 |
|
| 25728 |
If the above constraints are not respected, the server SHOULD return |
| 25729 |
the error NFS4ERR_INVAL. Since share_access and share_deny bits |
| 25730 |
should be subsets of those already granted, short of a defect in the |
| 25731 |
client or server implementation, it is not possible for the |
| 25732 |
OPEN_DOWNGRADE request to be denied because of conflicting share |
| 25733 |
reservations. |
| 25734 |
|
| 25735 |
The seqid argument is not used in NFSv4.1, MAY be any value, and MUST |
| 25736 |
be ignored by the server. |
| 25737 |
|
| 25738 |
On success, the current filehandle retains its value. |
| 25739 |
|
| 25740 |
<span class="h4"><a class="selflink" id="section-18.18.4" href="#section-18.18.4">18.18.4</a>. IMPLEMENTATION</span> |
| 25741 |
|
| 25742 |
An OPEN_DOWNGRADE operation may make OPEN_DELEGATE_READ delegations |
| 25743 |
grantable where they were not previously. Servers may choose to |
| 25744 |
respond immediately if there are pending delegation want requests or |
| 25745 |
may respond to the situation at a later time. |
| 25746 |
|
| 25747 |
|
| 25748 |
|
| 25749 |
|
| 25750 |
|
| 25751 |
|
| 25752 |
|
| 25753 |
|
| 25754 |
|
| 25755 |
|
| 25756 |
<span class="grey">Shepler, et al. Standards Track [Page 460]</span></pre> |
| 25757 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-461" ></span> |
| 25758 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25759 |
|
| 25760 |
|
| 25761 |
<span class="h3"><a class="selflink" id="section-18.19" href="#section-18.19">18.19</a>. Operation 22: PUTFH - Set Current Filehandle</span> |
| 25762 |
|
| 25763 |
<span class="h4"><a class="selflink" id="section-18.19.1" href="#section-18.19.1">18.19.1</a>. ARGUMENTS</span> |
| 25764 |
|
| 25765 |
struct PUTFH4args { |
| 25766 |
nfs_fh4 object; |
| 25767 |
}; |
| 25768 |
|
| 25769 |
<span class="h4"><a class="selflink" id="section-18.19.2" href="#section-18.19.2">18.19.2</a>. RESULTS</span> |
| 25770 |
|
| 25771 |
struct PUTFH4res { |
| 25772 |
/* |
| 25773 |
* If status is NFS4_OK, |
| 25774 |
* new CURRENT_FH: argument to PUTFH |
| 25775 |
*/ |
| 25776 |
nfsstat4 status; |
| 25777 |
}; |
| 25778 |
|
| 25779 |
<span class="h4"><a class="selflink" id="section-18.19.3" href="#section-18.19.3">18.19.3</a>. DESCRIPTION</span> |
| 25780 |
|
| 25781 |
This operation replaces the current filehandle with the filehandle |
| 25782 |
provided as an argument. It clears the current stateid. |
| 25783 |
|
| 25784 |
If the security mechanism used by the requester does not meet the |
| 25785 |
requirements of the filehandle provided to this operation, the server |
| 25786 |
MUST return NFS4ERR_WRONGSEC. |
| 25787 |
|
| 25788 |
See <a href="#section-16.2.3.1.1">Section 16.2.3.1.1</a> for more details on the current filehandle. |
| 25789 |
|
| 25790 |
See <a href="#section-16.2.3.1.2">Section 16.2.3.1.2</a> for more details on the current stateid. |
| 25791 |
|
| 25792 |
<span class="h4"><a class="selflink" id="section-18.19.4" href="#section-18.19.4">18.19.4</a>. IMPLEMENTATION</span> |
| 25793 |
|
| 25794 |
This operation is used in an NFS request to set the context for file |
| 25795 |
accessing operations that follow in the same COMPOUND request. |
| 25796 |
|
| 25797 |
<span class="h3"><a class="selflink" id="section-18.20" href="#section-18.20">18.20</a>. Operation 23: PUTPUBFH - Set Public Filehandle</span> |
| 25798 |
|
| 25799 |
<span class="h4"><a class="selflink" id="section-18.20.1" href="#section-18.20.1">18.20.1</a>. ARGUMENT</span> |
| 25800 |
|
| 25801 |
void; |
| 25802 |
|
| 25803 |
|
| 25804 |
|
| 25805 |
|
| 25806 |
|
| 25807 |
|
| 25808 |
|
| 25809 |
|
| 25810 |
|
| 25811 |
|
| 25812 |
<span class="grey">Shepler, et al. Standards Track [Page 461]</span></pre> |
| 25813 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-462" ></span> |
| 25814 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25815 |
|
| 25816 |
|
| 25817 |
<span class="h4"><a class="selflink" id="section-18.20.2" href="#section-18.20.2">18.20.2</a>. RESULT</span> |
| 25818 |
|
| 25819 |
struct PUTPUBFH4res { |
| 25820 |
/* |
| 25821 |
* If status is NFS4_OK, |
| 25822 |
* new CURRENT_FH: public fh |
| 25823 |
*/ |
| 25824 |
nfsstat4 status; |
| 25825 |
}; |
| 25826 |
|
| 25827 |
<span class="h4"><a class="selflink" id="section-18.20.3" href="#section-18.20.3">18.20.3</a>. DESCRIPTION</span> |
| 25828 |
|
| 25829 |
This operation replaces the current filehandle with the filehandle |
| 25830 |
that represents the public filehandle of the server's namespace. |
| 25831 |
This filehandle may be different from the "root" filehandle that may |
| 25832 |
be associated with some other directory on the server. |
| 25833 |
|
| 25834 |
PUTPUBFH also clears the current stateid. |
| 25835 |
|
| 25836 |
The public filehandle represents the concepts embodied in <a href="./rfc2054">RFC 2054</a> |
| 25837 |
[<a href="#ref-42" title=""WebNFS Client Specification"">42</a>], <a href="./rfc2055">RFC 2055</a> [<a href="#ref-43" title=""WebNFS Server Specification"">43</a>], and <a href="./rfc2224">RFC 2224</a> [<a href="#ref-53" title=""NFS URL Scheme"">53</a>]. The intent for NFSv4.1 is |
| 25838 |
that the public filehandle (represented by the PUTPUBFH operation) be |
| 25839 |
used as a method of providing WebNFS server compatibility with NFSv3. |
| 25840 |
|
| 25841 |
The public filehandle and the root filehandle (represented by the |
| 25842 |
PUTROOTFH operation) SHOULD be equivalent. If the public and root |
| 25843 |
filehandles are not equivalent, then the directory corresponding to |
| 25844 |
the public filehandle MUST be a descendant of the directory |
| 25845 |
corresponding to the root filehandle. |
| 25846 |
|
| 25847 |
See <a href="#section-16.2.3.1.1">Section 16.2.3.1.1</a> for more details on the current filehandle. |
| 25848 |
|
| 25849 |
See <a href="#section-16.2.3.1.2">Section 16.2.3.1.2</a> for more details on the current stateid. |
| 25850 |
|
| 25851 |
<span class="h4"><a class="selflink" id="section-18.20.4" href="#section-18.20.4">18.20.4</a>. IMPLEMENTATION</span> |
| 25852 |
|
| 25853 |
This operation is used in an NFS request to set the context for file |
| 25854 |
accessing operations that follow in the same COMPOUND request. |
| 25855 |
|
| 25856 |
With the NFSv3 public filehandle, the client is able to specify |
| 25857 |
whether the pathname provided in the LOOKUP should be evaluated as |
| 25858 |
either an absolute path relative to the server's root or relative to |
| 25859 |
the public filehandle. <a href="./rfc2224">RFC 2224</a> [<a href="#ref-53" title=""NFS URL Scheme"">53</a>] contains further discussion of |
| 25860 |
the functionality. With NFSv4.1, that type of specification is not |
| 25861 |
directly available in the LOOKUP operation. The reason for this is |
| 25862 |
because the component separators needed to specify absolute vs. |
| 25863 |
relative are not allowed in NFSv4. Therefore, the client is |
| 25864 |
|
| 25865 |
|
| 25866 |
|
| 25867 |
|
| 25868 |
<span class="grey">Shepler, et al. Standards Track [Page 462]</span></pre> |
| 25869 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-463" ></span> |
| 25870 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25871 |
|
| 25872 |
|
| 25873 |
responsible for constructing its request such that the use of either |
| 25874 |
PUTROOTFH or PUTPUBFH signifies absolute or relative evaluation of an |
| 25875 |
NFS URL, respectively. |
| 25876 |
|
| 25877 |
Note that there are warnings mentioned in <a href="./rfc2224">RFC 2224</a> [<a href="#ref-53" title=""NFS URL Scheme"">53</a>] with respect |
| 25878 |
to the use of absolute evaluation and the restrictions the server may |
| 25879 |
place on that evaluation with respect to how much of its namespace |
| 25880 |
has been made available. These same warnings apply to NFSv4.1. It |
| 25881 |
is likely, therefore, that because of server implementation details, |
| 25882 |
an NFSv3 absolute public filehandle look up may behave differently |
| 25883 |
than an NFSv4.1 absolute resolution. |
| 25884 |
|
| 25885 |
There is a form of security negotiation as described in <a href="./rfc2755">RFC 2755</a> [<a href="#ref-54" title=""Security Negotiation for WebNFS"">54</a>] |
| 25886 |
that uses the public filehandle and an overloading of the pathname. |
| 25887 |
This method is not available with NFSv4.1 as filehandles are not |
| 25888 |
overloaded with special meaning and therefore do not provide the same |
| 25889 |
framework as NFSv3. Clients should therefore use the security |
| 25890 |
negotiation mechanisms described in <a href="#section-2.6">Section 2.6</a>. |
| 25891 |
|
| 25892 |
<span class="h3"><a class="selflink" id="section-18.21" href="#section-18.21">18.21</a>. Operation 24: PUTROOTFH - Set Root Filehandle</span> |
| 25893 |
|
| 25894 |
<span class="h4"><a class="selflink" id="section-18.21.1" href="#section-18.21.1">18.21.1</a>. ARGUMENTS</span> |
| 25895 |
|
| 25896 |
void; |
| 25897 |
|
| 25898 |
<span class="h4"><a class="selflink" id="section-18.21.2" href="#section-18.21.2">18.21.2</a>. RESULTS</span> |
| 25899 |
|
| 25900 |
struct PUTROOTFH4res { |
| 25901 |
/* |
| 25902 |
* If status is NFS4_OK, |
| 25903 |
* new CURRENT_FH: root fh |
| 25904 |
*/ |
| 25905 |
nfsstat4 status; |
| 25906 |
}; |
| 25907 |
|
| 25908 |
<span class="h4"><a class="selflink" id="section-18.21.3" href="#section-18.21.3">18.21.3</a>. DESCRIPTION</span> |
| 25909 |
|
| 25910 |
This operation replaces the current filehandle with the filehandle |
| 25911 |
that represents the root of the server's namespace. From this |
| 25912 |
filehandle, a LOOKUP operation can locate any other filehandle on the |
| 25913 |
server. This filehandle may be different from the "public" |
| 25914 |
filehandle that may be associated with some other directory on the |
| 25915 |
server. |
| 25916 |
|
| 25917 |
PUTROOTFH also clears the current stateid. |
| 25918 |
|
| 25919 |
See <a href="#section-16.2.3.1.1">Section 16.2.3.1.1</a> for more details on the current filehandle. |
| 25920 |
|
| 25921 |
|
| 25922 |
|
| 25923 |
|
| 25924 |
<span class="grey">Shepler, et al. Standards Track [Page 463]</span></pre> |
| 25925 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-464" ></span> |
| 25926 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25927 |
|
| 25928 |
|
| 25929 |
See <a href="#section-16.2.3.1.2">Section 16.2.3.1.2</a> for more details on the current stateid. |
| 25930 |
|
| 25931 |
<span class="h4"><a class="selflink" id="section-18.21.4" href="#section-18.21.4">18.21.4</a>. IMPLEMENTATION</span> |
| 25932 |
|
| 25933 |
This operation is used in an NFS request to set the context for file |
| 25934 |
accessing operations that follow in the same COMPOUND request. |
| 25935 |
|
| 25936 |
<span class="h3"><a class="selflink" id="section-18.22" href="#section-18.22">18.22</a>. Operation 25: READ - Read from File</span> |
| 25937 |
|
| 25938 |
<span class="h4"><a class="selflink" id="section-18.22.1" href="#section-18.22.1">18.22.1</a>. ARGUMENTS</span> |
| 25939 |
|
| 25940 |
struct READ4args { |
| 25941 |
/* CURRENT_FH: file */ |
| 25942 |
stateid4 stateid; |
| 25943 |
offset4 offset; |
| 25944 |
count4 count; |
| 25945 |
}; |
| 25946 |
|
| 25947 |
<span class="h4"><a class="selflink" id="section-18.22.2" href="#section-18.22.2">18.22.2</a>. RESULTS</span> |
| 25948 |
|
| 25949 |
struct READ4resok { |
| 25950 |
bool eof; |
| 25951 |
opaque data<>; |
| 25952 |
}; |
| 25953 |
|
| 25954 |
union READ4res switch (nfsstat4 status) { |
| 25955 |
case NFS4_OK: |
| 25956 |
READ4resok resok4; |
| 25957 |
default: |
| 25958 |
void; |
| 25959 |
}; |
| 25960 |
|
| 25961 |
<span class="h4"><a class="selflink" id="section-18.22.3" href="#section-18.22.3">18.22.3</a>. DESCRIPTION</span> |
| 25962 |
|
| 25963 |
The READ operation reads data from the regular file identified by the |
| 25964 |
current filehandle. |
| 25965 |
|
| 25966 |
The client provides an offset of where the READ is to start and a |
| 25967 |
count of how many bytes are to be read. An offset of zero means to |
| 25968 |
read data starting at the beginning of the file. If offset is |
| 25969 |
greater than or equal to the size of the file, the status NFS4_OK is |
| 25970 |
returned with a data length set to zero and eof is set to TRUE. The |
| 25971 |
READ is subject to access permissions checking. |
| 25972 |
|
| 25973 |
|
| 25974 |
|
| 25975 |
|
| 25976 |
|
| 25977 |
|
| 25978 |
|
| 25979 |
|
| 25980 |
<span class="grey">Shepler, et al. Standards Track [Page 464]</span></pre> |
| 25981 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-465" ></span> |
| 25982 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 25983 |
|
| 25984 |
|
| 25985 |
If the client specifies a count value of zero, the READ succeeds and |
| 25986 |
returns zero bytes of data again subject to access permissions |
| 25987 |
checking. The server may choose to return fewer bytes than specified |
| 25988 |
by the client. The client needs to check for this condition and |
| 25989 |
handle the condition appropriately. |
| 25990 |
|
| 25991 |
Except when special stateids are used, the stateid value for a READ |
| 25992 |
request represents a value returned from a previous byte-range lock |
| 25993 |
or share reservation request or the stateid associated with a |
| 25994 |
delegation. The stateid identifies the associated owners if any and |
| 25995 |
is used by the server to verify that the associated locks are still |
| 25996 |
valid (e.g., have not been revoked). |
| 25997 |
|
| 25998 |
If the read ended at the end-of-file (formally, in a correctly formed |
| 25999 |
READ operation, if offset + count is equal to the size of the file), |
| 26000 |
or the READ operation extends beyond the size of the file (if offset |
| 26001 |
+ count is greater than the size of the file), eof is returned as |
| 26002 |
TRUE; otherwise, it is FALSE. A successful READ of an empty file |
| 26003 |
will always return eof as TRUE. |
| 26004 |
|
| 26005 |
If the current filehandle is not an ordinary file, an error will be |
| 26006 |
returned to the client. In the case that the current filehandle |
| 26007 |
represents an object of type NF4DIR, NFS4ERR_ISDIR is returned. If |
| 26008 |
the current filehandle designates a symbolic link, NFS4ERR_SYMLINK is |
| 26009 |
returned. In all other cases, NFS4ERR_WRONG_TYPE is returned. |
| 26010 |
|
| 26011 |
For a READ with a stateid value of all bits equal to zero, the server |
| 26012 |
MAY allow the READ to be serviced subject to mandatory byte-range |
| 26013 |
locks or the current share deny modes for the file. For a READ with |
| 26014 |
a stateid value of all bits equal to one, the server MAY allow READ |
| 26015 |
operations to bypass locking checks at the server. |
| 26016 |
|
| 26017 |
On success, the current filehandle retains its value. |
| 26018 |
|
| 26019 |
<span class="h4"><a class="selflink" id="section-18.22.4" href="#section-18.22.4">18.22.4</a>. IMPLEMENTATION</span> |
| 26020 |
|
| 26021 |
If the server returns a "short read" (i.e., fewer data than requested |
| 26022 |
and eof is set to FALSE), the client should send another READ to get |
| 26023 |
the remaining data. A server may return less data than requested |
| 26024 |
under several circumstances. The file may have been truncated by |
| 26025 |
another client or perhaps on the server itself, changing the file |
| 26026 |
size from what the requesting client believes to be the case. This |
| 26027 |
would reduce the actual amount of data available to the client. It |
| 26028 |
is possible that the server reduce the transfer size and so return a |
| 26029 |
short read result. Server resource exhaustion may also occur in a |
| 26030 |
short read. |
| 26031 |
|
| 26032 |
|
| 26033 |
|
| 26034 |
|
| 26035 |
|
| 26036 |
<span class="grey">Shepler, et al. Standards Track [Page 465]</span></pre> |
| 26037 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-466" ></span> |
| 26038 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26039 |
|
| 26040 |
|
| 26041 |
If mandatory byte-range locking is in effect for the file, and if the |
| 26042 |
byte-range corresponding to the data to be read from the file is |
| 26043 |
WRITE_LT locked by an owner not associated with the stateid, the |
| 26044 |
server will return the NFS4ERR_LOCKED error. The client should try |
| 26045 |
to get the appropriate READ_LT via the LOCK operation before re- |
| 26046 |
attempting the READ. When the READ completes, the client should |
| 26047 |
release the byte-range lock via LOCKU. |
| 26048 |
|
| 26049 |
If another client has an OPEN_DELEGATE_WRITE delegation for the file |
| 26050 |
being read, the delegation must be recalled, and the operation cannot |
| 26051 |
proceed until that delegation is returned or revoked. Except where |
| 26052 |
this happens very quickly, one or more NFS4ERR_DELAY errors will be |
| 26053 |
returned to requests made while the delegation remains outstanding. |
| 26054 |
Normally, delegations will not be recalled as a result of a READ |
| 26055 |
operation since the recall will occur as a result of an earlier OPEN. |
| 26056 |
However, since it is possible for a READ to be done with a special |
| 26057 |
stateid, the server needs to check for this case even though the |
| 26058 |
client should have done an OPEN previously. |
| 26059 |
|
| 26060 |
<span class="h3"><a class="selflink" id="section-18.23" href="#section-18.23">18.23</a>. Operation 26: READDIR - Read Directory</span> |
| 26061 |
|
| 26062 |
<span class="h4"><a class="selflink" id="section-18.23.1" href="#section-18.23.1">18.23.1</a>. ARGUMENTS</span> |
| 26063 |
|
| 26064 |
struct READDIR4args { |
| 26065 |
/* CURRENT_FH: directory */ |
| 26066 |
nfs_cookie4 cookie; |
| 26067 |
verifier4 cookieverf; |
| 26068 |
count4 dircount; |
| 26069 |
count4 maxcount; |
| 26070 |
bitmap4 attr_request; |
| 26071 |
}; |
| 26072 |
|
| 26073 |
<span class="h4"><a class="selflink" id="section-18.23.2" href="#section-18.23.2">18.23.2</a>. RESULTS</span> |
| 26074 |
|
| 26075 |
struct entry4 { |
| 26076 |
nfs_cookie4 cookie; |
| 26077 |
component4 name; |
| 26078 |
fattr4 attrs; |
| 26079 |
entry4 *nextentry; |
| 26080 |
}; |
| 26081 |
|
| 26082 |
struct dirlist4 { |
| 26083 |
entry4 *entries; |
| 26084 |
bool eof; |
| 26085 |
}; |
| 26086 |
|
| 26087 |
|
| 26088 |
|
| 26089 |
|
| 26090 |
|
| 26091 |
|
| 26092 |
<span class="grey">Shepler, et al. Standards Track [Page 466]</span></pre> |
| 26093 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-467" ></span> |
| 26094 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26095 |
|
| 26096 |
|
| 26097 |
struct READDIR4resok { |
| 26098 |
verifier4 cookieverf; |
| 26099 |
dirlist4 reply; |
| 26100 |
}; |
| 26101 |
|
| 26102 |
union READDIR4res switch (nfsstat4 status) { |
| 26103 |
case NFS4_OK: |
| 26104 |
READDIR4resok resok4; |
| 26105 |
default: |
| 26106 |
void; |
| 26107 |
}; |
| 26108 |
|
| 26109 |
<span class="h4"><a class="selflink" id="section-18.23.3" href="#section-18.23.3">18.23.3</a>. DESCRIPTION</span> |
| 26110 |
|
| 26111 |
The READDIR operation retrieves a variable number of entries from a |
| 26112 |
file system directory and returns client-requested attributes for |
| 26113 |
each entry along with information to allow the client to request |
| 26114 |
additional directory entries in a subsequent READDIR. |
| 26115 |
|
| 26116 |
The arguments contain a cookie value that represents where the |
| 26117 |
READDIR should start within the directory. A value of zero for the |
| 26118 |
cookie is used to start reading at the beginning of the directory. |
| 26119 |
For subsequent READDIR requests, the client specifies a cookie value |
| 26120 |
that is provided by the server on a previous READDIR request. |
| 26121 |
|
| 26122 |
The request's cookieverf field should be set to 0 zero) when the |
| 26123 |
request's cookie field is zero (first read of the directory). On |
| 26124 |
subsequent requests, the cookieverf field must match the cookieverf |
| 26125 |
returned by the READDIR in which the cookie was acquired. If the |
| 26126 |
server determines that the cookieverf is no longer valid for the |
| 26127 |
directory, the error NFS4ERR_NOT_SAME must be returned. |
| 26128 |
|
| 26129 |
The dircount field of the request is a hint of the maximum number of |
| 26130 |
bytes of directory information that should be returned. This value |
| 26131 |
represents the total length of the names of the directory entries and |
| 26132 |
the cookie value for these entries. This length represents the XDR |
| 26133 |
encoding of the data (names and cookies) and not the length in the |
| 26134 |
native format of the server. |
| 26135 |
|
| 26136 |
The maxcount field of the request represents the maximum total size |
| 26137 |
of all of the data being returned within the READDIR4resok structure |
| 26138 |
and includes the XDR overhead. The server MAY return less data. If |
| 26139 |
the server is unable to return a single directory entry within the |
| 26140 |
maxcount limit, the error NFS4ERR_TOOSMALL MUST be returned to the |
| 26141 |
client. |
| 26142 |
|
| 26143 |
|
| 26144 |
|
| 26145 |
|
| 26146 |
|
| 26147 |
|
| 26148 |
<span class="grey">Shepler, et al. Standards Track [Page 467]</span></pre> |
| 26149 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-468" ></span> |
| 26150 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26151 |
|
| 26152 |
|
| 26153 |
Finally, the request's attr_request field represents the list of |
| 26154 |
attributes to be returned for each directory entry supplied by the |
| 26155 |
server. |
| 26156 |
|
| 26157 |
A successful reply consists of a list of directory entries. Each of |
| 26158 |
these entries contains the name of the directory entry, a cookie |
| 26159 |
value for that entry, and the associated attributes as requested. |
| 26160 |
The "eof" flag has a value of TRUE if there are no more entries in |
| 26161 |
the directory. |
| 26162 |
|
| 26163 |
The cookie value is only meaningful to the server and is used as a |
| 26164 |
cursor for the directory entry. As mentioned, this cookie is used by |
| 26165 |
the client for subsequent READDIR operations so that it may continue |
| 26166 |
reading a directory. The cookie is similar in concept to a READ |
| 26167 |
offset but MUST NOT be interpreted as such by the client. Ideally, |
| 26168 |
the cookie value SHOULD NOT change if the directory is modified since |
| 26169 |
the client may be caching these values. |
| 26170 |
|
| 26171 |
In some cases, the server may encounter an error while obtaining the |
| 26172 |
attributes for a directory entry. Instead of returning an error for |
| 26173 |
the entire READDIR operation, the server can instead return the |
| 26174 |
attribute rdattr_error (<a href="#section-5.8.1.12">Section 5.8.1.12</a>). With this, the server is |
| 26175 |
able to communicate the failure to the client and not fail the entire |
| 26176 |
operation in the instance of what might be a transient failure. |
| 26177 |
Obviously, the client must request the fattr4_rdattr_error attribute |
| 26178 |
for this method to work properly. If the client does not request the |
| 26179 |
attribute, the server has no choice but to return failure for the |
| 26180 |
entire READDIR operation. |
| 26181 |
|
| 26182 |
For some file system environments, the directory entries "." and ".." |
| 26183 |
have special meaning, and in other environments, they do not. If the |
| 26184 |
server supports these special entries within a directory, they SHOULD |
| 26185 |
NOT be returned to the client as part of the READDIR response. To |
| 26186 |
enable some client environments, the cookie values of zero, 1, and 2 |
| 26187 |
are to be considered reserved. Note that the UNIX client will use |
| 26188 |
these values when combining the server's response and local |
| 26189 |
representations to enable a fully formed UNIX directory presentation |
| 26190 |
to the application. |
| 26191 |
|
| 26192 |
For READDIR arguments, cookie values of one and two SHOULD NOT be |
| 26193 |
used, and for READDIR results, cookie values of zero, one, and two |
| 26194 |
SHOULD NOT be returned. |
| 26195 |
|
| 26196 |
On success, the current filehandle retains its value. |
| 26197 |
|
| 26198 |
|
| 26199 |
|
| 26200 |
|
| 26201 |
|
| 26202 |
|
| 26203 |
|
| 26204 |
<span class="grey">Shepler, et al. Standards Track [Page 468]</span></pre> |
| 26205 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-469" ></span> |
| 26206 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26207 |
|
| 26208 |
|
| 26209 |
<span class="h4"><a class="selflink" id="section-18.23.4" href="#section-18.23.4">18.23.4</a>. IMPLEMENTATION</span> |
| 26210 |
|
| 26211 |
The server's file system directory representations can differ |
| 26212 |
greatly. A client's programming interfaces may also be bound to the |
| 26213 |
local operating environment in a way that does not translate well |
| 26214 |
into the NFS protocol. Therefore, the use of the dircount and |
| 26215 |
maxcount fields are provided to enable the client to provide hints to |
| 26216 |
the server. If the client is aggressive about attribute collection |
| 26217 |
during a READDIR, the server has an idea of how to limit the encoded |
| 26218 |
response. |
| 26219 |
|
| 26220 |
If dircount is zero, the server bounds the reply's size based on the |
| 26221 |
request's maxcount field. |
| 26222 |
|
| 26223 |
The cookieverf may be used by the server to help manage cookie values |
| 26224 |
that may become stale. It should be a rare occurrence that a server |
| 26225 |
is unable to continue properly reading a directory with the provided |
| 26226 |
cookie/cookieverf pair. The server SHOULD make every effort to avoid |
| 26227 |
this condition since the application at the client might be unable to |
| 26228 |
properly handle this type of failure. |
| 26229 |
|
| 26230 |
The use of the cookieverf will also protect the client from using |
| 26231 |
READDIR cookie values that might be stale. For example, if the file |
| 26232 |
system has been migrated, the server might or might not be able to |
| 26233 |
use the same cookie values to service READDIR as the previous server |
| 26234 |
used. With the client providing the cookieverf, the server is able |
| 26235 |
to provide the appropriate response to the client. This prevents the |
| 26236 |
case where the server accepts a cookie value but the underlying |
| 26237 |
directory has changed and the response is invalid from the client's |
| 26238 |
context of its previous READDIR. |
| 26239 |
|
| 26240 |
Since some servers will not be returning "." and ".." entries as has |
| 26241 |
been done with previous versions of the NFS protocol, the client that |
| 26242 |
requires these entries be present in READDIR responses must fabricate |
| 26243 |
them. |
| 26244 |
|
| 26245 |
<span class="h3"><a class="selflink" id="section-18.24" href="#section-18.24">18.24</a>. Operation 27: READLINK - Read Symbolic Link</span> |
| 26246 |
|
| 26247 |
<span class="h4"><a class="selflink" id="section-18.24.1" href="#section-18.24.1">18.24.1</a>. ARGUMENTS</span> |
| 26248 |
|
| 26249 |
/* CURRENT_FH: symlink */ |
| 26250 |
void; |
| 26251 |
|
| 26252 |
<span class="h4"><a class="selflink" id="section-18.24.2" href="#section-18.24.2">18.24.2</a>. RESULTS</span> |
| 26253 |
|
| 26254 |
struct READLINK4resok { |
| 26255 |
linktext4 link; |
| 26256 |
}; |
| 26257 |
|
| 26258 |
|
| 26259 |
|
| 26260 |
<span class="grey">Shepler, et al. Standards Track [Page 469]</span></pre> |
| 26261 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-470" ></span> |
| 26262 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26263 |
|
| 26264 |
|
| 26265 |
union READLINK4res switch (nfsstat4 status) { |
| 26266 |
case NFS4_OK: |
| 26267 |
READLINK4resok resok4; |
| 26268 |
default: |
| 26269 |
void; |
| 26270 |
}; |
| 26271 |
|
| 26272 |
<span class="h4"><a class="selflink" id="section-18.24.3" href="#section-18.24.3">18.24.3</a>. DESCRIPTION</span> |
| 26273 |
|
| 26274 |
READLINK reads the data associated with a symbolic link. Depending |
| 26275 |
on the value of the UTF-8 capability attribute (<a href="#section-14.4">Section 14.4</a>), the |
| 26276 |
data is encoded in UTF-8. Whether created by an NFS client or |
| 26277 |
created locally on the server, the data in a symbolic link is not |
| 26278 |
interpreted (except possibly to check for proper UTF-8 encoding) when |
| 26279 |
created, but is simply stored. |
| 26280 |
|
| 26281 |
On success, the current filehandle retains its value. |
| 26282 |
|
| 26283 |
<span class="h4"><a class="selflink" id="section-18.24.4" href="#section-18.24.4">18.24.4</a>. IMPLEMENTATION</span> |
| 26284 |
|
| 26285 |
A symbolic link is nominally a pointer to another file. The data is |
| 26286 |
not necessarily interpreted by the server, just stored in the file. |
| 26287 |
It is possible for a client implementation to store a pathname that |
| 26288 |
is not meaningful to the server operating system in a symbolic link. |
| 26289 |
A READLINK operation returns the data to the client for |
| 26290 |
interpretation. If different implementations want to share access to |
| 26291 |
symbolic links, then they must agree on the interpretation of the |
| 26292 |
data in the symbolic link. |
| 26293 |
|
| 26294 |
The READLINK operation is only allowed on objects of type NF4LNK. |
| 26295 |
The server should return the error NFS4ERR_WRONG_TYPE if the object |
| 26296 |
is not of type NF4LNK. |
| 26297 |
|
| 26298 |
<span class="h3"><a class="selflink" id="section-18.25" href="#section-18.25">18.25</a>. Operation 28: REMOVE - Remove File System Object</span> |
| 26299 |
|
| 26300 |
<span class="h4"><a class="selflink" id="section-18.25.1" href="#section-18.25.1">18.25.1</a>. ARGUMENTS</span> |
| 26301 |
|
| 26302 |
struct REMOVE4args { |
| 26303 |
/* CURRENT_FH: directory */ |
| 26304 |
component4 target; |
| 26305 |
}; |
| 26306 |
|
| 26307 |
<span class="h4"><a class="selflink" id="section-18.25.2" href="#section-18.25.2">18.25.2</a>. RESULTS</span> |
| 26308 |
|
| 26309 |
struct REMOVE4resok { |
| 26310 |
change_info4 cinfo; |
| 26311 |
}; |
| 26312 |
|
| 26313 |
|
| 26314 |
|
| 26315 |
|
| 26316 |
<span class="grey">Shepler, et al. Standards Track [Page 470]</span></pre> |
| 26317 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-471" ></span> |
| 26318 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26319 |
|
| 26320 |
|
| 26321 |
union REMOVE4res switch (nfsstat4 status) { |
| 26322 |
case NFS4_OK: |
| 26323 |
REMOVE4resok resok4; |
| 26324 |
default: |
| 26325 |
void; |
| 26326 |
}; |
| 26327 |
|
| 26328 |
<span class="h4"><a class="selflink" id="section-18.25.3" href="#section-18.25.3">18.25.3</a>. DESCRIPTION</span> |
| 26329 |
|
| 26330 |
The REMOVE operation removes (deletes) a directory entry named by |
| 26331 |
filename from the directory corresponding to the current filehandle. |
| 26332 |
If the entry in the directory was the last reference to the |
| 26333 |
corresponding file system object, the object may be destroyed. The |
| 26334 |
directory may be either of type NF4DIR or NF4ATTRDIR. |
| 26335 |
|
| 26336 |
For the directory where the filename was removed, the server returns |
| 26337 |
change_info4 information in cinfo. With the atomic field of the |
| 26338 |
change_info4 data type, the server will indicate if the before and |
| 26339 |
after change attributes were obtained atomically with respect to the |
| 26340 |
removal. |
| 26341 |
|
| 26342 |
If the target has a length of zero, or if the target does not obey |
| 26343 |
the UTF-8 definition (and the server is enforcing UTF-8 encoding; see |
| 26344 |
<a href="#section-14.4">Section 14.4</a>), the error NFS4ERR_INVAL will be returned. |
| 26345 |
|
| 26346 |
On success, the current filehandle retains its value. |
| 26347 |
|
| 26348 |
<span class="h4"><a class="selflink" id="section-18.25.4" href="#section-18.25.4">18.25.4</a>. IMPLEMENTATION</span> |
| 26349 |
|
| 26350 |
NFSv3 required a different operator RMDIR for directory removal and |
| 26351 |
REMOVE for non-directory removal. This allowed clients to skip |
| 26352 |
checking the file type when being passed a non-directory delete |
| 26353 |
system call (e.g., unlink() [<a href="#ref-27" title="">27</a>] in POSIX) to remove a directory, as |
| 26354 |
well as the converse (e.g., a rmdir() on a non-directory) because |
| 26355 |
they knew the server would check the file type. NFSv4.1 REMOVE can |
| 26356 |
be used to delete any directory entry independent of its file type. |
| 26357 |
The implementor of an NFSv4.1 client's entry points from the unlink() |
| 26358 |
and rmdir() system calls should first check the file type against the |
| 26359 |
types the system call is allowed to remove before sending a REMOVE |
| 26360 |
operation. Alternatively, the implementor can produce a COMPOUND |
| 26361 |
call that includes a LOOKUP/VERIFY sequence of operations to verify |
| 26362 |
the file type before a REMOVE operation in the same COMPOUND call. |
| 26363 |
|
| 26364 |
The concept of last reference is server specific. However, if the |
| 26365 |
numlinks field in the previous attributes of the object had the value |
| 26366 |
1, the client should not rely on referring to the object via a |
| 26367 |
filehandle. Likewise, the client should not rely on the resources |
| 26368 |
(disk space, directory entry, and so on) formerly associated with the |
| 26369 |
|
| 26370 |
|
| 26371 |
|
| 26372 |
<span class="grey">Shepler, et al. Standards Track [Page 471]</span></pre> |
| 26373 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-472" ></span> |
| 26374 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26375 |
|
| 26376 |
|
| 26377 |
object becoming immediately available. Thus, if a client needs to be |
| 26378 |
able to continue to access a file after using REMOVE to remove it, |
| 26379 |
the client should take steps to make sure that the file will still be |
| 26380 |
accessible. While the traditional mechanism used is to RENAME the |
| 26381 |
file from its old name to a new hidden name, the NFSv4.1 OPEN |
| 26382 |
operation MAY return a result flag, OPEN4_RESULT_PRESERVE_UNLINKED, |
| 26383 |
which indicates to the client that the file will be preserved if the |
| 26384 |
file has an outstanding open (see <a href="#section-18.16">Section 18.16</a>). |
| 26385 |
|
| 26386 |
If the server finds that the file is still open when the REMOVE |
| 26387 |
arrives: |
| 26388 |
|
| 26389 |
o The server SHOULD NOT delete the file's directory entry if the |
| 26390 |
file was opened with OPEN4_SHARE_DENY_WRITE or |
| 26391 |
OPEN4_SHARE_DENY_BOTH. |
| 26392 |
|
| 26393 |
o If the file was not opened with OPEN4_SHARE_DENY_WRITE or |
| 26394 |
OPEN4_SHARE_DENY_BOTH, the server SHOULD delete the file's |
| 26395 |
directory entry. However, until last CLOSE of the file, the |
| 26396 |
server MAY continue to allow access to the file via its |
| 26397 |
filehandle. |
| 26398 |
|
| 26399 |
o The server MUST NOT delete the directory entry if the reply from |
| 26400 |
OPEN had the flag OPEN4_RESULT_PRESERVE_UNLINKED set. |
| 26401 |
|
| 26402 |
The server MAY implement its own restrictions on removal of a file |
| 26403 |
while it is open. The server might disallow such a REMOVE (or a |
| 26404 |
removal that occurs as part of RENAME). The conditions that |
| 26405 |
influence the restrictions on removal of a file while it is still |
| 26406 |
open include: |
| 26407 |
|
| 26408 |
o Whether certain access protocols (i.e., not just NFS) are holding |
| 26409 |
the file open. |
| 26410 |
|
| 26411 |
o Whether particular options, access modes, or policies on the |
| 26412 |
server are enabled. |
| 26413 |
|
| 26414 |
If a file has an outstanding OPEN and this prevents the removal of |
| 26415 |
the file's directory entry, the error NFS4ERR_FILE_OPEN is returned. |
| 26416 |
|
| 26417 |
Where the determination above cannot be made definitively because |
| 26418 |
delegations are being held, they MUST be recalled to allow processing |
| 26419 |
of the REMOVE to continue. When a delegation is held, the server has |
| 26420 |
no reliable knowledge of the status of OPENs for that client, so |
| 26421 |
unless there are files opened with the particular deny modes by |
| 26422 |
clients without delegations, the determination cannot be made until |
| 26423 |
|
| 26424 |
|
| 26425 |
|
| 26426 |
|
| 26427 |
|
| 26428 |
<span class="grey">Shepler, et al. Standards Track [Page 472]</span></pre> |
| 26429 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-473" ></span> |
| 26430 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26431 |
|
| 26432 |
|
| 26433 |
delegations are recalled, and the operation cannot proceed until each |
| 26434 |
sufficient delegation has been returned or revoked to allow the |
| 26435 |
server to make a correct determination. |
| 26436 |
|
| 26437 |
In all cases in which delegations are recalled, the server is likely |
| 26438 |
to return one or more NFS4ERR_DELAY errors while delegations remain |
| 26439 |
outstanding. |
| 26440 |
|
| 26441 |
If the current filehandle designates a directory for which another |
| 26442 |
client holds a directory delegation, then, unless the situation can |
| 26443 |
be resolved by sending a notification, the directory delegation MUST |
| 26444 |
be recalled, and the operation MUST NOT proceed until the delegation |
| 26445 |
is returned or revoked. Except where this happens very quickly, one |
| 26446 |
or more NFS4ERR_DELAY errors will be returned to requests made while |
| 26447 |
delegation remains outstanding. |
| 26448 |
|
| 26449 |
When the current filehandle designates a directory for which one or |
| 26450 |
more directory delegations exist, then, when those delegations |
| 26451 |
request such notifications, NOTIFY4_REMOVE_ENTRY will be generated as |
| 26452 |
a result of this operation. |
| 26453 |
|
| 26454 |
Note that when a remove occurs as a result of a RENAME, |
| 26455 |
NOTIFY4_REMOVE_ENTRY will only be generated if the removal happens as |
| 26456 |
a separate operation. In the case in which the removal is integrated |
| 26457 |
and atomic with RENAME, the notification of the removal is integrated |
| 26458 |
with notification for the RENAME. See the discussion of the |
| 26459 |
NOTIFY4_RENAME_ENTRY notification in <a href="#section-20.4">Section 20.4</a>. |
| 26460 |
|
| 26461 |
<span class="h3"><a class="selflink" id="section-18.26" href="#section-18.26">18.26</a>. Operation 29: RENAME - Rename Directory Entry</span> |
| 26462 |
|
| 26463 |
<span class="h4"><a class="selflink" id="section-18.26.1" href="#section-18.26.1">18.26.1</a>. ARGUMENTS</span> |
| 26464 |
|
| 26465 |
struct RENAME4args { |
| 26466 |
/* SAVED_FH: source directory */ |
| 26467 |
component4 oldname; |
| 26468 |
/* CURRENT_FH: target directory */ |
| 26469 |
component4 newname; |
| 26470 |
}; |
| 26471 |
|
| 26472 |
<span class="h4"><a class="selflink" id="section-18.26.2" href="#section-18.26.2">18.26.2</a>. RESULTS</span> |
| 26473 |
|
| 26474 |
struct RENAME4resok { |
| 26475 |
change_info4 source_cinfo; |
| 26476 |
change_info4 target_cinfo; |
| 26477 |
}; |
| 26478 |
|
| 26479 |
|
| 26480 |
|
| 26481 |
|
| 26482 |
|
| 26483 |
|
| 26484 |
<span class="grey">Shepler, et al. Standards Track [Page 473]</span></pre> |
| 26485 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-474" ></span> |
| 26486 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26487 |
|
| 26488 |
|
| 26489 |
union RENAME4res switch (nfsstat4 status) { |
| 26490 |
case NFS4_OK: |
| 26491 |
RENAME4resok resok4; |
| 26492 |
default: |
| 26493 |
void; |
| 26494 |
}; |
| 26495 |
|
| 26496 |
<span class="h4"><a class="selflink" id="section-18.26.3" href="#section-18.26.3">18.26.3</a>. DESCRIPTION</span> |
| 26497 |
|
| 26498 |
The RENAME operation renames the object identified by oldname in the |
| 26499 |
source directory corresponding to the saved filehandle, as set by the |
| 26500 |
SAVEFH operation, to newname in the target directory corresponding to |
| 26501 |
the current filehandle. The operation is required to be atomic to |
| 26502 |
the client. Source and target directories MUST reside on the same |
| 26503 |
file system on the server. On success, the current filehandle will |
| 26504 |
continue to be the target directory. |
| 26505 |
|
| 26506 |
If the target directory already contains an entry with the name |
| 26507 |
newname, the source object MUST be compatible with the target: either |
| 26508 |
both are non-directories or both are directories and the target MUST |
| 26509 |
be empty. If compatible, the existing target is removed before the |
| 26510 |
rename occurs or, preferably, the target is removed atomically as |
| 26511 |
part of the rename. See <a href="#section-18.25.4">Section 18.25.4</a> for client and server |
| 26512 |
actions whenever a target is removed. Note however that when the |
| 26513 |
removal is performed atomically with the rename, certain parts of the |
| 26514 |
removal described there are integrated with the rename. For example, |
| 26515 |
notification of the removal will not be via a NOTIFY4_REMOVE_ENTRY |
| 26516 |
but will be indicated as part of the NOTIFY4_ADD_ENTRY or |
| 26517 |
NOTIFY4_RENAME_ENTRY generated by the rename. |
| 26518 |
|
| 26519 |
If the source object and the target are not compatible or if the |
| 26520 |
target is a directory but not empty, the server will return the error |
| 26521 |
NFS4ERR_EXIST. |
| 26522 |
|
| 26523 |
If oldname and newname both refer to the same file (e.g., they might |
| 26524 |
be hard links of each other), then unless the file is open (see |
| 26525 |
<a href="#section-18.26.4">Section 18.26.4</a>), RENAME MUST perform no action and return NFS4_OK. |
| 26526 |
|
| 26527 |
For both directories involved in the RENAME, the server returns |
| 26528 |
change_info4 information. With the atomic field of the change_info4 |
| 26529 |
data type, the server will indicate if the before and after change |
| 26530 |
attributes were obtained atomically with respect to the rename. |
| 26531 |
|
| 26532 |
If oldname refers to a named attribute and the saved and current |
| 26533 |
filehandles refer to different file system objects, the server will |
| 26534 |
return NFS4ERR_XDEV just as if the saved and current filehandles |
| 26535 |
represented directories on different file systems. |
| 26536 |
|
| 26537 |
|
| 26538 |
|
| 26539 |
|
| 26540 |
<span class="grey">Shepler, et al. Standards Track [Page 474]</span></pre> |
| 26541 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-475" ></span> |
| 26542 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26543 |
|
| 26544 |
|
| 26545 |
If oldname or newname has a length of zero, or if oldname or newname |
| 26546 |
does not obey the UTF-8 definition, the error NFS4ERR_INVAL will be |
| 26547 |
returned. |
| 26548 |
|
| 26549 |
<span class="h4"><a class="selflink" id="section-18.26.4" href="#section-18.26.4">18.26.4</a>. IMPLEMENTATION</span> |
| 26550 |
|
| 26551 |
The server MAY impose restrictions on the RENAME operation such that |
| 26552 |
RENAME may not be done when the file being renamed is open or when |
| 26553 |
that open is done by particular protocols, or with particular options |
| 26554 |
or access modes. Similar restrictions may be applied when a file |
| 26555 |
exists with the target name and is open. When RENAME is rejected |
| 26556 |
because of such restrictions, the error NFS4ERR_FILE_OPEN is |
| 26557 |
returned. |
| 26558 |
|
| 26559 |
When oldname and rename refer to the same file and that file is open |
| 26560 |
in a fashion such that RENAME would normally be rejected with |
| 26561 |
NFS4ERR_FILE_OPEN if oldname and newname were different files, then |
| 26562 |
RENAME SHOULD be rejected with NFS4ERR_FILE_OPEN. |
| 26563 |
|
| 26564 |
If a server does implement such restrictions and those restrictions |
| 26565 |
include cases of NFSv4 opens preventing successful execution of a |
| 26566 |
rename, the server needs to recall any delegations that could hide |
| 26567 |
the existence of opens relevant to that decision. This is because |
| 26568 |
when a client holds a delegation, the server might not have an |
| 26569 |
accurate account of the opens for that client, since the client may |
| 26570 |
execute OPENs and CLOSEs locally. The RENAME operation need only be |
| 26571 |
delayed until a definitive result can be obtained. For example, if |
| 26572 |
there are multiple delegations and one of them establishes an open |
| 26573 |
whose presence would prevent the rename, given the server's |
| 26574 |
semantics, NFS4ERR_FILE_OPEN may be returned to the caller as soon as |
| 26575 |
that delegation is returned without waiting for other delegations to |
| 26576 |
be returned. Similarly, if such opens are not associated with |
| 26577 |
delegations, NFS4ERR_FILE_OPEN can be returned immediately with no |
| 26578 |
delegation recall being done. |
| 26579 |
|
| 26580 |
If the current filehandle or the saved filehandle designates a |
| 26581 |
directory for which another client holds a directory delegation, |
| 26582 |
then, unless the situation can be resolved by sending a notification, |
| 26583 |
the delegation MUST be recalled, and the operation cannot proceed |
| 26584 |
until the delegation is returned or revoked. Except where this |
| 26585 |
happens very quickly, one or more NFS4ERR_DELAY errors will be |
| 26586 |
returned to requests made while delegation remains outstanding. |
| 26587 |
|
| 26588 |
When the current and saved filehandles are the same and they |
| 26589 |
designate a directory for which one or more directory delegations |
| 26590 |
exist, then, when those delegations request such notifications, a |
| 26591 |
notification of type NOTIFY4_RENAME_ENTRY will be generated as a |
| 26592 |
result of this operation. When oldname and rename refer to the same |
| 26593 |
|
| 26594 |
|
| 26595 |
|
| 26596 |
<span class="grey">Shepler, et al. Standards Track [Page 475]</span></pre> |
| 26597 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-476" ></span> |
| 26598 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26599 |
|
| 26600 |
|
| 26601 |
file, no notification is generated (because, as <a href="#section-18.26.3">Section 18.26.3</a> |
| 26602 |
states, the server MUST take no action). When a file is removed |
| 26603 |
because it has the same name as the target, if that removal is done |
| 26604 |
atomically with the rename, a NOTIFY4_REMOVE_ENTRY notification will |
| 26605 |
not be generated. Instead, the deletion of the file will be reported |
| 26606 |
as part of the NOTIFY4_RENAME_ENTRY notification. |
| 26607 |
|
| 26608 |
When the current and saved filehandles are not the same: |
| 26609 |
|
| 26610 |
o If the current filehandle designates a directory for which one or |
| 26611 |
more directory delegations exist, then, when those delegations |
| 26612 |
request such notifications, NOTIFY4_ADD_ENTRY will be generated as |
| 26613 |
a result of this operation. When a file is removed because it has |
| 26614 |
the same name as the target, if that removal is done atomically |
| 26615 |
with the rename, a NOTIFY4_REMOVE_ENTRY notification will not be |
| 26616 |
generated. Instead, the deletion of the file will be reported as |
| 26617 |
part of the NOTIFY4_ADD_ENTRY notification. |
| 26618 |
|
| 26619 |
o If the saved filehandle designates a directory for which one or |
| 26620 |
more directory delegations exist, then, when those delegations |
| 26621 |
request such notifications, NOTIFY4_REMOVE_ENTRY will be generated |
| 26622 |
as a result of this operation. |
| 26623 |
|
| 26624 |
If the object being renamed has file delegations held by clients |
| 26625 |
other than the one doing the RENAME, the delegations MUST be |
| 26626 |
recalled, and the operation cannot proceed until each such delegation |
| 26627 |
is returned or revoked. Note that in the case of multiply linked |
| 26628 |
files, the delegation recall requirement applies even if the |
| 26629 |
delegation was obtained through a different name than the one being |
| 26630 |
renamed. In all cases in which delegations are recalled, the server |
| 26631 |
is likely to return one or more NFS4ERR_DELAY errors while the |
| 26632 |
delegation(s) remains outstanding, although it might not do that if |
| 26633 |
the delegations are returned quickly. |
| 26634 |
|
| 26635 |
The RENAME operation must be atomic to the client. The statement |
| 26636 |
"source and target directories MUST reside on the same file system on |
| 26637 |
the server" means that the fsid fields in the attributes for the |
| 26638 |
directories are the same. If they reside on different file systems, |
| 26639 |
the error NFS4ERR_XDEV is returned. |
| 26640 |
|
| 26641 |
Based on the value of the fh_expire_type attribute for the object, |
| 26642 |
the filehandle may or may not expire on a RENAME. However, server |
| 26643 |
implementors are strongly encouraged to attempt to keep filehandles |
| 26644 |
from expiring in this fashion. |
| 26645 |
|
| 26646 |
|
| 26647 |
|
| 26648 |
|
| 26649 |
|
| 26650 |
|
| 26651 |
|
| 26652 |
<span class="grey">Shepler, et al. Standards Track [Page 476]</span></pre> |
| 26653 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-477" ></span> |
| 26654 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26655 |
|
| 26656 |
|
| 26657 |
On some servers, the file names "." and ".." are illegal as either |
| 26658 |
oldname or newname, and will result in the error NFS4ERR_BADNAME. In |
| 26659 |
addition, on many servers the case of oldname or newname being an |
| 26660 |
alias for the source directory will be checked for. Such servers |
| 26661 |
will return the error NFS4ERR_INVAL in these cases. |
| 26662 |
|
| 26663 |
If either of the source or target filehandles are not directories, |
| 26664 |
the server will return NFS4ERR_NOTDIR. |
| 26665 |
|
| 26666 |
<span class="h3"><a class="selflink" id="section-18.27" href="#section-18.27">18.27</a>. Operation 31: RESTOREFH - Restore Saved Filehandle</span> |
| 26667 |
|
| 26668 |
<span class="h4"><a class="selflink" id="section-18.27.1" href="#section-18.27.1">18.27.1</a>. ARGUMENTS</span> |
| 26669 |
|
| 26670 |
/* SAVED_FH: */ |
| 26671 |
void; |
| 26672 |
|
| 26673 |
<span class="h4"><a class="selflink" id="section-18.27.2" href="#section-18.27.2">18.27.2</a>. RESULTS</span> |
| 26674 |
|
| 26675 |
struct RESTOREFH4res { |
| 26676 |
/* |
| 26677 |
* If status is NFS4_OK, |
| 26678 |
* new CURRENT_FH: value of saved fh |
| 26679 |
*/ |
| 26680 |
nfsstat4 status; |
| 26681 |
}; |
| 26682 |
|
| 26683 |
<span class="h4"><a class="selflink" id="section-18.27.3" href="#section-18.27.3">18.27.3</a>. DESCRIPTION</span> |
| 26684 |
|
| 26685 |
The RESTOREFH operation sets the current filehandle and stateid to |
| 26686 |
the values in the saved filehandle and stateid. If there is no saved |
| 26687 |
filehandle, then the server will return the error |
| 26688 |
NFS4ERR_NOFILEHANDLE. |
| 26689 |
|
| 26690 |
See <a href="#section-16.2.3.1.1">Section 16.2.3.1.1</a> for more details on the current filehandle. |
| 26691 |
|
| 26692 |
See <a href="#section-16.2.3.1.2">Section 16.2.3.1.2</a> for more details on the current stateid. |
| 26693 |
|
| 26694 |
|
| 26695 |
|
| 26696 |
|
| 26697 |
|
| 26698 |
|
| 26699 |
|
| 26700 |
|
| 26701 |
|
| 26702 |
|
| 26703 |
|
| 26704 |
|
| 26705 |
|
| 26706 |
|
| 26707 |
|
| 26708 |
<span class="grey">Shepler, et al. Standards Track [Page 477]</span></pre> |
| 26709 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-478" ></span> |
| 26710 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26711 |
|
| 26712 |
|
| 26713 |
<span class="h4"><a class="selflink" id="section-18.27.4" href="#section-18.27.4">18.27.4</a>. IMPLEMENTATION</span> |
| 26714 |
|
| 26715 |
Operations like OPEN and LOOKUP use the current filehandle to |
| 26716 |
represent a directory and replace it with a new filehandle. Assuming |
| 26717 |
that the previous filehandle was saved with a SAVEFH operator, the |
| 26718 |
previous filehandle can be restored as the current filehandle. This |
| 26719 |
is commonly used to obtain post-operation attributes for the |
| 26720 |
directory, e.g., |
| 26721 |
|
| 26722 |
PUTFH (directory filehandle) |
| 26723 |
SAVEFH |
| 26724 |
GETATTR attrbits (pre-op dir attrs) |
| 26725 |
CREATE optbits "foo" attrs |
| 26726 |
GETATTR attrbits (file attributes) |
| 26727 |
RESTOREFH |
| 26728 |
GETATTR attrbits (post-op dir attrs) |
| 26729 |
|
| 26730 |
<span class="h3"><a class="selflink" id="section-18.28" href="#section-18.28">18.28</a>. Operation 32: SAVEFH - Save Current Filehandle</span> |
| 26731 |
|
| 26732 |
<span class="h4"><a class="selflink" id="section-18.28.1" href="#section-18.28.1">18.28.1</a>. ARGUMENTS</span> |
| 26733 |
|
| 26734 |
/* CURRENT_FH: */ |
| 26735 |
void; |
| 26736 |
|
| 26737 |
<span class="h4"><a class="selflink" id="section-18.28.2" href="#section-18.28.2">18.28.2</a>. RESULTS</span> |
| 26738 |
|
| 26739 |
struct SAVEFH4res { |
| 26740 |
/* |
| 26741 |
* If status is NFS4_OK, |
| 26742 |
* new SAVED_FH: value of current fh |
| 26743 |
*/ |
| 26744 |
nfsstat4 status; |
| 26745 |
}; |
| 26746 |
|
| 26747 |
<span class="h4"><a class="selflink" id="section-18.28.3" href="#section-18.28.3">18.28.3</a>. DESCRIPTION</span> |
| 26748 |
|
| 26749 |
The SAVEFH operation saves the current filehandle and stateid. If a |
| 26750 |
previous filehandle was saved, then it is no longer accessible. The |
| 26751 |
saved filehandle can be restored as the current filehandle with the |
| 26752 |
RESTOREFH operator. |
| 26753 |
|
| 26754 |
On success, the current filehandle retains its value. |
| 26755 |
|
| 26756 |
See <a href="#section-16.2.3.1.1">Section 16.2.3.1.1</a> for more details on the current filehandle. |
| 26757 |
|
| 26758 |
See <a href="#section-16.2.3.1.2">Section 16.2.3.1.2</a> for more details on the current stateid. |
| 26759 |
|
| 26760 |
|
| 26761 |
|
| 26762 |
|
| 26763 |
|
| 26764 |
<span class="grey">Shepler, et al. Standards Track [Page 478]</span></pre> |
| 26765 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-479" ></span> |
| 26766 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26767 |
|
| 26768 |
|
| 26769 |
<span class="h4"><a class="selflink" id="section-18.28.4" href="#section-18.28.4">18.28.4</a>. IMPLEMENTATION</span> |
| 26770 |
|
| 26771 |
<span class="h3"><a class="selflink" id="section-18.29" href="#section-18.29">18.29</a>. Operation 33: SECINFO - Obtain Available Security</span> |
| 26772 |
|
| 26773 |
<span class="h4"><a class="selflink" id="section-18.29.1" href="#section-18.29.1">18.29.1</a>. ARGUMENTS</span> |
| 26774 |
|
| 26775 |
struct SECINFO4args { |
| 26776 |
/* CURRENT_FH: directory */ |
| 26777 |
component4 name; |
| 26778 |
}; |
| 26779 |
|
| 26780 |
<span class="h4"><a class="selflink" id="section-18.29.2" href="#section-18.29.2">18.29.2</a>. RESULTS</span> |
| 26781 |
|
| 26782 |
/* |
| 26783 |
* From <a href="./rfc2203">RFC 2203</a> |
| 26784 |
*/ |
| 26785 |
enum rpc_gss_svc_t { |
| 26786 |
RPC_GSS_SVC_NONE = 1, |
| 26787 |
RPC_GSS_SVC_INTEGRITY = 2, |
| 26788 |
RPC_GSS_SVC_PRIVACY = 3 |
| 26789 |
}; |
| 26790 |
|
| 26791 |
struct rpcsec_gss_info { |
| 26792 |
sec_oid4 oid; |
| 26793 |
qop4 qop; |
| 26794 |
rpc_gss_svc_t service; |
| 26795 |
}; |
| 26796 |
|
| 26797 |
/* RPCSEC_GSS has a value of '6' - See <a href="./rfc2203">RFC 2203</a> */ |
| 26798 |
union secinfo4 switch (uint32_t flavor) { |
| 26799 |
case RPCSEC_GSS: |
| 26800 |
rpcsec_gss_info flavor_info; |
| 26801 |
default: |
| 26802 |
void; |
| 26803 |
}; |
| 26804 |
|
| 26805 |
typedef secinfo4 SECINFO4resok<>; |
| 26806 |
|
| 26807 |
union SECINFO4res switch (nfsstat4 status) { |
| 26808 |
case NFS4_OK: |
| 26809 |
/* CURRENTFH: consumed */ |
| 26810 |
SECINFO4resok resok4; |
| 26811 |
default: |
| 26812 |
void; |
| 26813 |
}; |
| 26814 |
|
| 26815 |
|
| 26816 |
|
| 26817 |
|
| 26818 |
|
| 26819 |
|
| 26820 |
<span class="grey">Shepler, et al. Standards Track [Page 479]</span></pre> |
| 26821 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-480" ></span> |
| 26822 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26823 |
|
| 26824 |
|
| 26825 |
<span class="h4"><a class="selflink" id="section-18.29.3" href="#section-18.29.3">18.29.3</a>. DESCRIPTION</span> |
| 26826 |
|
| 26827 |
The SECINFO operation is used by the client to obtain a list of valid |
| 26828 |
RPC authentication flavors for a specific directory filehandle, file |
| 26829 |
name pair. SECINFO should apply the same access methodology used for |
| 26830 |
LOOKUP when evaluating the name. Therefore, if the requester does |
| 26831 |
not have the appropriate access to LOOKUP the name, then SECINFO MUST |
| 26832 |
behave the same way and return NFS4ERR_ACCESS. |
| 26833 |
|
| 26834 |
The result will contain an array that represents the security |
| 26835 |
mechanisms available, with an order corresponding to the server's |
| 26836 |
preferences, the most preferred being first in the array. The client |
| 26837 |
is free to pick whatever security mechanism it both desires and |
| 26838 |
supports, or to pick in the server's preference order the first one |
| 26839 |
it supports. The array entries are represented by the secinfo4 |
| 26840 |
structure. The field 'flavor' will contain a value of AUTH_NONE, |
| 26841 |
AUTH_SYS (as defined in <a href="./rfc5531">RFC 5531</a> [<a href="#ref-3" title=""RPC: Remote Procedure Call Protocol Specification Version 2"">3</a>]), or RPCSEC_GSS (as defined in |
| 26842 |
<a href="./rfc2203">RFC 2203</a> [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>]). The field flavor can also be any other security |
| 26843 |
flavor registered with IANA. |
| 26844 |
|
| 26845 |
For the flavors AUTH_NONE and AUTH_SYS, no additional security |
| 26846 |
information is returned. The same is true of many (if not most) |
| 26847 |
other security flavors, including AUTH_DH. For a return value of |
| 26848 |
RPCSEC_GSS, a security triple is returned that contains the mechanism |
| 26849 |
object identifier (OID, as defined in <a href="./rfc2743">RFC 2743</a> [<a href="#ref-7" title=""Generic Security Service Application Program Interface Version 2, Update 1"">7</a>]), the quality of |
| 26850 |
protection (as defined in <a href="./rfc2743">RFC 2743</a> [<a href="#ref-7" title=""Generic Security Service Application Program Interface Version 2, Update 1"">7</a>]), and the service type (as |
| 26851 |
defined in <a href="./rfc2203">RFC 2203</a> [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>]). It is possible for SECINFO to return |
| 26852 |
multiple entries with flavor equal to RPCSEC_GSS with different |
| 26853 |
security triple values. |
| 26854 |
|
| 26855 |
On success, the current filehandle is consumed (see |
| 26856 |
<a href="#section-2.6.3.1.1.8">Section 2.6.3.1.1.8</a>), and if the next operation after SECINFO tries |
| 26857 |
to use the current filehandle, that operation will fail with the |
| 26858 |
status NFS4ERR_NOFILEHANDLE. |
| 26859 |
|
| 26860 |
If the name has a length of zero, or if the name does not obey the |
| 26861 |
UTF-8 definition (assuming UTF-8 capabilities are enabled; see |
| 26862 |
<a href="#section-14.4">Section 14.4</a>), the error NFS4ERR_INVAL will be returned. |
| 26863 |
|
| 26864 |
See <a href="#section-2.6">Section 2.6</a> for additional information on the use of SECINFO. |
| 26865 |
|
| 26866 |
<span class="h4"><a class="selflink" id="section-18.29.4" href="#section-18.29.4">18.29.4</a>. IMPLEMENTATION</span> |
| 26867 |
|
| 26868 |
The SECINFO operation is expected to be used by the NFS client when |
| 26869 |
the error value of NFS4ERR_WRONGSEC is returned from another NFS |
| 26870 |
operation. This signifies to the client that the server's security |
| 26871 |
|
| 26872 |
|
| 26873 |
|
| 26874 |
|
| 26875 |
|
| 26876 |
<span class="grey">Shepler, et al. Standards Track [Page 480]</span></pre> |
| 26877 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-481" ></span> |
| 26878 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26879 |
|
| 26880 |
|
| 26881 |
policy is different from what the client is currently using. At this |
| 26882 |
point, the client is expected to obtain a list of possible security |
| 26883 |
flavors and choose what best suits its policies. |
| 26884 |
|
| 26885 |
As mentioned, the server's security policies will determine when a |
| 26886 |
client request receives NFS4ERR_WRONGSEC. See Table 8 for a list of |
| 26887 |
operations that can return NFS4ERR_WRONGSEC. In addition, when |
| 26888 |
READDIR returns attributes, the rdattr_error (<a href="#section-5.8.1.12">Section 5.8.1.12</a>) can |
| 26889 |
contain NFS4ERR_WRONGSEC. Note that CREATE and REMOVE MUST NOT |
| 26890 |
return NFS4ERR_WRONGSEC. The rationale for CREATE is that unless the |
| 26891 |
target name exists, it cannot have a separate security policy from |
| 26892 |
the parent directory, and the security policy of the parent was |
| 26893 |
checked when its filehandle was injected into the COMPOUND request's |
| 26894 |
operations stream (for similar reasons, an OPEN operation that |
| 26895 |
creates the target MUST NOT return NFS4ERR_WRONGSEC). If the target |
| 26896 |
name exists, while it might have a separate security policy, that is |
| 26897 |
irrelevant because CREATE MUST return NFS4ERR_EXIST. The rationale |
| 26898 |
for REMOVE is that while that target might have a separate security |
| 26899 |
policy, the target is going to be removed, and so the security policy |
| 26900 |
of the parent trumps that of the object being removed. RENAME and |
| 26901 |
LINK MAY return NFS4ERR_WRONGSEC, but the NFS4ERR_WRONGSEC error |
| 26902 |
applies only to the saved filehandle (see <a href="#section-2.6.3.1.2">Section 2.6.3.1.2</a>). Any |
| 26903 |
NFS4ERR_WRONGSEC error on the current filehandle used by LINK and |
| 26904 |
RENAME MUST be returned by the PUTFH, PUTPUBFH, PUTROOTFH, or |
| 26905 |
RESTOREFH operation that injected the current filehandle. |
| 26906 |
|
| 26907 |
With the exception of LINK and RENAME, the set of operations that can |
| 26908 |
return NFS4ERR_WRONGSEC represents the point at which the client can |
| 26909 |
inject a filehandle into the "current filehandle" at the server. The |
| 26910 |
filehandle is either provided by the client (PUTFH, PUTPUBFH, |
| 26911 |
PUTROOTFH), generated as a result of a name-to-filehandle translation |
| 26912 |
(LOOKUP and OPEN), or generated from the saved filehandle via |
| 26913 |
RESTOREFH. As <a href="#section-2.6.3.1.1.1">Section 2.6.3.1.1.1</a> states, a put filehandle operation |
| 26914 |
followed by SAVEFH MUST NOT return NFS4ERR_WRONGSEC. Thus, the |
| 26915 |
RESTOREFH operation, under certain conditions (see |
| 26916 |
<a href="#section-2.6.3.1.1">Section 2.6.3.1.1</a>), is permitted to return NFS4ERR_WRONGSEC so that |
| 26917 |
security policies can be honored. |
| 26918 |
|
| 26919 |
The READDIR operation will not directly return the NFS4ERR_WRONGSEC |
| 26920 |
error. However, if the READDIR request included a request for |
| 26921 |
attributes, it is possible that the READDIR request's security triple |
| 26922 |
did not match that of a directory entry. If this is the case and the |
| 26923 |
client has requested the rdattr_error attribute, the server will |
| 26924 |
return the NFS4ERR_WRONGSEC error in rdattr_error for the entry. |
| 26925 |
|
| 26926 |
To resolve an error return of NFS4ERR_WRONGSEC, the client does the |
| 26927 |
following: |
| 26928 |
|
| 26929 |
|
| 26930 |
|
| 26931 |
|
| 26932 |
<span class="grey">Shepler, et al. Standards Track [Page 481]</span></pre> |
| 26933 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-482" ></span> |
| 26934 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26935 |
|
| 26936 |
|
| 26937 |
o For LOOKUP and OPEN, the client will use SECINFO with the same |
| 26938 |
current filehandle and name as provided in the original LOOKUP or |
| 26939 |
OPEN to enumerate the available security triples. |
| 26940 |
|
| 26941 |
o For the rdattr_error, the client will use SECINFO with the same |
| 26942 |
current filehandle as provided in the original READDIR. The name |
| 26943 |
passed to SECINFO will be that of the directory entry (as returned |
| 26944 |
from READDIR) that had the NFS4ERR_WRONGSEC error in the |
| 26945 |
rdattr_error attribute. |
| 26946 |
|
| 26947 |
o For PUTFH, PUTROOTFH, PUTPUBFH, RESTOREFH, LINK, and RENAME, the |
| 26948 |
client will use SECINFO_NO_NAME { style = |
| 26949 |
SECINFO_STYLE4_CURRENT_FH }. The client will prefix the |
| 26950 |
SECINFO_NO_NAME operation with the appropriate PUTFH, PUTPUBFH, or |
| 26951 |
PUTROOTFH operation that provides the filehandle originally |
| 26952 |
provided by the PUTFH, PUTPUBFH, PUTROOTFH, or RESTOREFH |
| 26953 |
operation. |
| 26954 |
|
| 26955 |
NOTE: In NFSv4.0, the client was required to use SECINFO, and had |
| 26956 |
to reconstruct the parent of the original filehandle and the |
| 26957 |
component name of the original filehandle. The introduction in |
| 26958 |
NFSv4.1 of SECINFO_NO_NAME obviates the need for reconstruction. |
| 26959 |
|
| 26960 |
o For LOOKUPP, the client will use SECINFO_NO_NAME { style = |
| 26961 |
SECINFO_STYLE4_PARENT } and provide the filehandle that equals the |
| 26962 |
filehandle originally provided to LOOKUPP. |
| 26963 |
|
| 26964 |
See <a href="#section-21">Section 21</a> for a discussion on the recommendations for the |
| 26965 |
security flavor used by SECINFO and SECINFO_NO_NAME. |
| 26966 |
|
| 26967 |
<span class="h3"><a class="selflink" id="section-18.30" href="#section-18.30">18.30</a>. Operation 34: SETATTR - Set Attributes</span> |
| 26968 |
|
| 26969 |
<span class="h4"><a class="selflink" id="section-18.30.1" href="#section-18.30.1">18.30.1</a>. ARGUMENTS</span> |
| 26970 |
|
| 26971 |
struct SETATTR4args { |
| 26972 |
/* CURRENT_FH: target object */ |
| 26973 |
stateid4 stateid; |
| 26974 |
fattr4 obj_attributes; |
| 26975 |
}; |
| 26976 |
|
| 26977 |
<span class="h4"><a class="selflink" id="section-18.30.2" href="#section-18.30.2">18.30.2</a>. RESULTS</span> |
| 26978 |
|
| 26979 |
struct SETATTR4res { |
| 26980 |
nfsstat4 status; |
| 26981 |
bitmap4 attrsset; |
| 26982 |
}; |
| 26983 |
|
| 26984 |
|
| 26985 |
|
| 26986 |
|
| 26987 |
|
| 26988 |
<span class="grey">Shepler, et al. Standards Track [Page 482]</span></pre> |
| 26989 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-483" ></span> |
| 26990 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 26991 |
|
| 26992 |
|
| 26993 |
<span class="h4"><a class="selflink" id="section-18.30.3" href="#section-18.30.3">18.30.3</a>. DESCRIPTION</span> |
| 26994 |
|
| 26995 |
The SETATTR operation changes one or more of the attributes of a file |
| 26996 |
system object. The new attributes are specified with a bitmap and |
| 26997 |
the attributes that follow the bitmap in bit order. |
| 26998 |
|
| 26999 |
The stateid argument for SETATTR is used to provide byte-range |
| 27000 |
locking context that is necessary for SETATTR requests that set the |
| 27001 |
size attribute. Since setting the size attribute modifies the file's |
| 27002 |
data, it has the same locking requirements as a corresponding WRITE. |
| 27003 |
Any SETATTR that sets the size attribute is incompatible with a share |
| 27004 |
reservation that specifies OPEN4_SHARE_DENY_WRITE. The area between |
| 27005 |
the old end-of-file and the new end-of-file is considered to be |
| 27006 |
modified just as would have been the case had the area in question |
| 27007 |
been specified as the target of WRITE, for the purpose of checking |
| 27008 |
conflicts with byte-range locks, for those cases in which a server is |
| 27009 |
implementing mandatory byte-range locking behavior. A valid stateid |
| 27010 |
SHOULD always be specified. When the file size attribute is not set, |
| 27011 |
the special stateid consisting of all bits equal to zero MAY be |
| 27012 |
passed. |
| 27013 |
|
| 27014 |
On either success or failure of the operation, the server will return |
| 27015 |
the attrsset bitmask to represent what (if any) attributes were |
| 27016 |
successfully set. The attrsset in the response is a subset of the |
| 27017 |
attrmask field of the obj_attributes field in the argument. |
| 27018 |
|
| 27019 |
On success, the current filehandle retains its value. |
| 27020 |
|
| 27021 |
<span class="h4"><a class="selflink" id="section-18.30.4" href="#section-18.30.4">18.30.4</a>. IMPLEMENTATION</span> |
| 27022 |
|
| 27023 |
If the request specifies the owner attribute to be set, the server |
| 27024 |
SHOULD allow the operation to succeed if the current owner of the |
| 27025 |
object matches the value specified in the request. Some servers may |
| 27026 |
be implemented in a way as to prohibit the setting of the owner |
| 27027 |
attribute unless the requester has privilege to do so. If the server |
| 27028 |
is lenient in this one case of matching owner values, the client |
| 27029 |
implementation may be simplified in cases of creation of an object |
| 27030 |
(e.g., an exclusive create via OPEN) followed by a SETATTR. |
| 27031 |
|
| 27032 |
The file size attribute is used to request changes to the size of a |
| 27033 |
file. A value of zero causes the file to be truncated, a value less |
| 27034 |
than the current size of the file causes data from new size to the |
| 27035 |
end of the file to be discarded, and a size greater than the current |
| 27036 |
size of the file causes logically zeroed data bytes to be added to |
| 27037 |
the end of the file. Servers are free to implement this using |
| 27038 |
unallocated bytes (holes) or allocated data bytes set to zero. |
| 27039 |
Clients should not make any assumptions regarding a server's |
| 27040 |
|
| 27041 |
|
| 27042 |
|
| 27043 |
|
| 27044 |
<span class="grey">Shepler, et al. Standards Track [Page 483]</span></pre> |
| 27045 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-484" ></span> |
| 27046 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27047 |
|
| 27048 |
|
| 27049 |
implementation of this feature, beyond that the bytes in the affected |
| 27050 |
byte-range returned by READ will be zeroed. Servers MUST support |
| 27051 |
extending the file size via SETATTR. |
| 27052 |
|
| 27053 |
SETATTR is not guaranteed to be atomic. A failed SETATTR may |
| 27054 |
partially change a file's attributes, hence the reason why the reply |
| 27055 |
always includes the status and the list of attributes that were set. |
| 27056 |
|
| 27057 |
If the object whose attributes are being changed has a file |
| 27058 |
delegation that is held by a client other than the one doing the |
| 27059 |
SETATTR, the delegation(s) must be recalled, and the operation cannot |
| 27060 |
proceed to actually change an attribute until each such delegation is |
| 27061 |
returned or revoked. In all cases in which delegations are recalled, |
| 27062 |
the server is likely to return one or more NFS4ERR_DELAY errors while |
| 27063 |
the delegation(s) remains outstanding, although it might not do that |
| 27064 |
if the delegations are returned quickly. |
| 27065 |
|
| 27066 |
If the object whose attributes are being set is a directory and |
| 27067 |
another client holds a directory delegation for that directory, then |
| 27068 |
if enabled, asynchronous notifications will be generated when the set |
| 27069 |
of attributes changed has a non-null intersection with the set of |
| 27070 |
attributes for which notification is requested. Notifications of |
| 27071 |
type NOTIFY4_CHANGE_DIR_ATTRS will be sent to the appropriate |
| 27072 |
client(s), but the SETATTR is not delayed by waiting for these |
| 27073 |
notifications to be sent. |
| 27074 |
|
| 27075 |
If the object whose attributes are being set is a member of the |
| 27076 |
directory for which another client holds a directory delegation, then |
| 27077 |
asynchronous notifications will be generated when the set of |
| 27078 |
attributes changed has a non-null intersection with the set of |
| 27079 |
attributes for which notification is requested. Notifications of |
| 27080 |
type NOTIFY4_CHANGE_CHILD_ATTRS will be sent to the appropriate |
| 27081 |
clients, but the SETATTR is not delayed by waiting for these |
| 27082 |
notifications to be sent. |
| 27083 |
|
| 27084 |
Changing the size of a file with SETATTR indirectly changes the |
| 27085 |
time_modify and change attributes. A client must account for this as |
| 27086 |
size changes can result in data deletion. |
| 27087 |
|
| 27088 |
The attributes time_access_set and time_modify_set are write-only |
| 27089 |
attributes constructed as a switched union so the client can direct |
| 27090 |
the server in setting the time values. If the switched union |
| 27091 |
specifies SET_TO_CLIENT_TIME4, the client has provided an nfstime4 to |
| 27092 |
be used for the operation. If the switch union does not specify |
| 27093 |
SET_TO_CLIENT_TIME4, the server is to use its current time for the |
| 27094 |
SETATTR operation. |
| 27095 |
|
| 27096 |
|
| 27097 |
|
| 27098 |
|
| 27099 |
|
| 27100 |
<span class="grey">Shepler, et al. Standards Track [Page 484]</span></pre> |
| 27101 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-485" ></span> |
| 27102 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27103 |
|
| 27104 |
|
| 27105 |
If server and client times differ, programs that compare client time |
| 27106 |
to file times can break. A time synchronization protocol should be |
| 27107 |
used to limit client/server time skew. |
| 27108 |
|
| 27109 |
Use of a COMPOUND containing a VERIFY operation specifying only the |
| 27110 |
change attribute, immediately followed by a SETATTR, provides a means |
| 27111 |
whereby a client may specify a request that emulates the |
| 27112 |
functionality of the SETATTR guard mechanism of NFSv3. Since the |
| 27113 |
function of the guard mechanism is to avoid changes to the file |
| 27114 |
attributes based on stale information, delays between checking of the |
| 27115 |
guard condition and the setting of the attributes have the potential |
| 27116 |
to compromise this function, as would the corresponding delay in the |
| 27117 |
NFSv4 emulation. Therefore, NFSv4.1 servers SHOULD take care to |
| 27118 |
avoid such delays, to the degree possible, when executing such a |
| 27119 |
request. |
| 27120 |
|
| 27121 |
If the server does not support an attribute as requested by the |
| 27122 |
client, the server SHOULD return NFS4ERR_ATTRNOTSUPP. |
| 27123 |
|
| 27124 |
A mask of the attributes actually set is returned by SETATTR in all |
| 27125 |
cases. That mask MUST NOT include attribute bits not requested to be |
| 27126 |
set by the client. If the attribute masks in the request and reply |
| 27127 |
are equal, the status field in the reply MUST be NFS4_OK. |
| 27128 |
|
| 27129 |
<span class="h3"><a class="selflink" id="section-18.31" href="#section-18.31">18.31</a>. Operation 37: VERIFY - Verify Same Attributes</span> |
| 27130 |
|
| 27131 |
<span class="h4"><a class="selflink" id="section-18.31.1" href="#section-18.31.1">18.31.1</a>. ARGUMENTS</span> |
| 27132 |
|
| 27133 |
struct VERIFY4args { |
| 27134 |
/* CURRENT_FH: object */ |
| 27135 |
fattr4 obj_attributes; |
| 27136 |
}; |
| 27137 |
|
| 27138 |
<span class="h4"><a class="selflink" id="section-18.31.2" href="#section-18.31.2">18.31.2</a>. RESULTS</span> |
| 27139 |
|
| 27140 |
struct VERIFY4res { |
| 27141 |
nfsstat4 status; |
| 27142 |
}; |
| 27143 |
|
| 27144 |
<span class="h4"><a class="selflink" id="section-18.31.3" href="#section-18.31.3">18.31.3</a>. DESCRIPTION</span> |
| 27145 |
|
| 27146 |
The VERIFY operation is used to verify that attributes have the value |
| 27147 |
assumed by the client before proceeding with the following operations |
| 27148 |
in the COMPOUND request. If any of the attributes do not match, then |
| 27149 |
the error NFS4ERR_NOT_SAME must be returned. The current filehandle |
| 27150 |
retains its value after successful completion of the operation. |
| 27151 |
|
| 27152 |
|
| 27153 |
|
| 27154 |
|
| 27155 |
|
| 27156 |
<span class="grey">Shepler, et al. Standards Track [Page 485]</span></pre> |
| 27157 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-486" ></span> |
| 27158 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27159 |
|
| 27160 |
|
| 27161 |
<span class="h4"><a class="selflink" id="section-18.31.4" href="#section-18.31.4">18.31.4</a>. IMPLEMENTATION</span> |
| 27162 |
|
| 27163 |
One possible use of the VERIFY operation is the following series of |
| 27164 |
operations. With this, the client is attempting to verify that the |
| 27165 |
file being removed will match what the client expects to be removed. |
| 27166 |
This series can help prevent the unintended deletion of a file. |
| 27167 |
|
| 27168 |
PUTFH (directory filehandle) |
| 27169 |
LOOKUP (file name) |
| 27170 |
VERIFY (filehandle == fh) |
| 27171 |
PUTFH (directory filehandle) |
| 27172 |
REMOVE (file name) |
| 27173 |
|
| 27174 |
This series does not prevent a second client from removing and |
| 27175 |
creating a new file in the middle of this sequence, but it does help |
| 27176 |
avoid the unintended result. |
| 27177 |
|
| 27178 |
In the case that a RECOMMENDED attribute is specified in the VERIFY |
| 27179 |
operation and the server does not support that attribute for the file |
| 27180 |
system object, the error NFS4ERR_ATTRNOTSUPP is returned to the |
| 27181 |
client. |
| 27182 |
|
| 27183 |
When the attribute rdattr_error or any set-only attribute (e.g., |
| 27184 |
time_modify_set) is specified, the error NFS4ERR_INVAL is returned to |
| 27185 |
the client. |
| 27186 |
|
| 27187 |
<span class="h3"><a class="selflink" id="section-18.32" href="#section-18.32">18.32</a>. Operation 38: WRITE - Write to File</span> |
| 27188 |
|
| 27189 |
<span class="h4"><a class="selflink" id="section-18.32.1" href="#section-18.32.1">18.32.1</a>. ARGUMENTS</span> |
| 27190 |
|
| 27191 |
enum stable_how4 { |
| 27192 |
UNSTABLE4 = 0, |
| 27193 |
DATA_SYNC4 = 1, |
| 27194 |
FILE_SYNC4 = 2 |
| 27195 |
}; |
| 27196 |
|
| 27197 |
struct WRITE4args { |
| 27198 |
/* CURRENT_FH: file */ |
| 27199 |
stateid4 stateid; |
| 27200 |
offset4 offset; |
| 27201 |
stable_how4 stable; |
| 27202 |
opaque data<>; |
| 27203 |
}; |
| 27204 |
|
| 27205 |
|
| 27206 |
|
| 27207 |
|
| 27208 |
|
| 27209 |
|
| 27210 |
|
| 27211 |
|
| 27212 |
<span class="grey">Shepler, et al. Standards Track [Page 486]</span></pre> |
| 27213 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-487" ></span> |
| 27214 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27215 |
|
| 27216 |
|
| 27217 |
<span class="h4"><a class="selflink" id="section-18.32.2" href="#section-18.32.2">18.32.2</a>. RESULTS</span> |
| 27218 |
|
| 27219 |
struct WRITE4resok { |
| 27220 |
count4 count; |
| 27221 |
stable_how4 committed; |
| 27222 |
verifier4 writeverf; |
| 27223 |
}; |
| 27224 |
|
| 27225 |
union WRITE4res switch (nfsstat4 status) { |
| 27226 |
case NFS4_OK: |
| 27227 |
WRITE4resok resok4; |
| 27228 |
default: |
| 27229 |
void; |
| 27230 |
}; |
| 27231 |
|
| 27232 |
<span class="h4"><a class="selflink" id="section-18.32.3" href="#section-18.32.3">18.32.3</a>. DESCRIPTION</span> |
| 27233 |
|
| 27234 |
The WRITE operation is used to write data to a regular file. The |
| 27235 |
target file is specified by the current filehandle. The offset |
| 27236 |
specifies the offset where the data should be written. An offset of |
| 27237 |
zero specifies that the write should start at the beginning of the |
| 27238 |
file. The count, as encoded as part of the opaque data parameter, |
| 27239 |
represents the number of bytes of data that are to be written. If |
| 27240 |
the count is zero, the WRITE will succeed and return a count of zero |
| 27241 |
subject to permissions checking. The server MAY write fewer bytes |
| 27242 |
than requested by the client. |
| 27243 |
|
| 27244 |
The client specifies with the stable parameter the method of how the |
| 27245 |
data is to be processed by the server. If stable is FILE_SYNC4, the |
| 27246 |
server MUST commit the data written plus all file system metadata to |
| 27247 |
stable storage before returning results. This corresponds to the |
| 27248 |
NFSv2 protocol semantics. Any other behavior constitutes a protocol |
| 27249 |
violation. If stable is DATA_SYNC4, then the server MUST commit all |
| 27250 |
of the data to stable storage and enough of the metadata to retrieve |
| 27251 |
the data before returning. The server implementor is free to |
| 27252 |
implement DATA_SYNC4 in the same fashion as FILE_SYNC4, but with a |
| 27253 |
possible performance drop. If stable is UNSTABLE4, the server is |
| 27254 |
free to commit any part of the data and the metadata to stable |
| 27255 |
storage, including all or none, before returning a reply to the |
| 27256 |
client. There is no guarantee whether or when any uncommitted data |
| 27257 |
will subsequently be committed to stable storage. The only |
| 27258 |
guarantees made by the server are that it will not destroy any data |
| 27259 |
without changing the value of writeverf and that it will not commit |
| 27260 |
the data and metadata at a level less than that requested by the |
| 27261 |
client. |
| 27262 |
|
| 27263 |
|
| 27264 |
|
| 27265 |
|
| 27266 |
|
| 27267 |
|
| 27268 |
<span class="grey">Shepler, et al. Standards Track [Page 487]</span></pre> |
| 27269 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-488" ></span> |
| 27270 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27271 |
|
| 27272 |
|
| 27273 |
Except when special stateids are used, the stateid value for a WRITE |
| 27274 |
request represents a value returned from a previous byte-range LOCK |
| 27275 |
or OPEN request or the stateid associated with a delegation. The |
| 27276 |
stateid identifies the associated owners if any and is used by the |
| 27277 |
server to verify that the associated locks are still valid (e.g., |
| 27278 |
have not been revoked). |
| 27279 |
|
| 27280 |
Upon successful completion, the following results are returned. The |
| 27281 |
count result is the number of bytes of data written to the file. The |
| 27282 |
server may write fewer bytes than requested. If so, the actual |
| 27283 |
number of bytes written starting at location, offset, is returned. |
| 27284 |
|
| 27285 |
The server also returns an indication of the level of commitment of |
| 27286 |
the data and metadata via committed. Per Table 11, |
| 27287 |
|
| 27288 |
o The server MAY commit the data at a stronger level than requested. |
| 27289 |
|
| 27290 |
o The server MUST commit the data at a level at least as high as |
| 27291 |
that committed. |
| 27292 |
|
| 27293 |
Valid combinations of the fields stable in the request and committed |
| 27294 |
in the reply. |
| 27295 |
|
| 27296 |
+------------+-----------------------------------+ |
| 27297 |
| stable | committed | |
| 27298 |
+------------+-----------------------------------+ |
| 27299 |
| UNSTABLE4 | FILE_SYNC4, DATA_SYNC4, UNSTABLE4 | |
| 27300 |
| DATA_SYNC4 | FILE_SYNC4, DATA_SYNC4 | |
| 27301 |
| FILE_SYNC4 | FILE_SYNC4 | |
| 27302 |
+------------+-----------------------------------+ |
| 27303 |
|
| 27304 |
Table 11 |
| 27305 |
|
| 27306 |
The final portion of the result is the field writeverf. This field |
| 27307 |
is the write verifier and is a cookie that the client can use to |
| 27308 |
determine whether a server has changed instance state (e.g., server |
| 27309 |
restart) between a call to WRITE and a subsequent call to either |
| 27310 |
WRITE or COMMIT. This cookie MUST be unchanged during a single |
| 27311 |
instance of the NFSv4.1 server and MUST be unique between instances |
| 27312 |
of the NFSv4.1 server. If the cookie changes, then the client MUST |
| 27313 |
assume that any data written with an UNSTABLE4 value for committed |
| 27314 |
and an old writeverf in the reply has been lost and will need to be |
| 27315 |
recovered. |
| 27316 |
|
| 27317 |
If a client writes data to the server with the stable argument set to |
| 27318 |
UNSTABLE4 and the reply yields a committed response of DATA_SYNC4 or |
| 27319 |
UNSTABLE4, the client will follow up some time in the future with a |
| 27320 |
COMMIT operation to synchronize outstanding asynchronous data and |
| 27321 |
|
| 27322 |
|
| 27323 |
|
| 27324 |
<span class="grey">Shepler, et al. Standards Track [Page 488]</span></pre> |
| 27325 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-489" ></span> |
| 27326 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27327 |
|
| 27328 |
|
| 27329 |
metadata with the server's stable storage, barring client error. It |
| 27330 |
is possible that due to client crash or other error that a subsequent |
| 27331 |
COMMIT will not be received by the server. |
| 27332 |
|
| 27333 |
For a WRITE with a stateid value of all bits equal to zero, the |
| 27334 |
server MAY allow the WRITE to be serviced subject to mandatory byte- |
| 27335 |
range locks or the current share deny modes for the file. For a |
| 27336 |
WRITE with a stateid value of all bits equal to 1, the server MUST |
| 27337 |
NOT allow the WRITE operation to bypass locking checks at the server |
| 27338 |
and otherwise is treated as if a stateid of all bits equal to zero |
| 27339 |
were used. |
| 27340 |
|
| 27341 |
On success, the current filehandle retains its value. |
| 27342 |
|
| 27343 |
<span class="h4"><a class="selflink" id="section-18.32.4" href="#section-18.32.4">18.32.4</a>. IMPLEMENTATION</span> |
| 27344 |
|
| 27345 |
It is possible for the server to write fewer bytes of data than |
| 27346 |
requested by the client. In this case, the server SHOULD NOT return |
| 27347 |
an error unless no data was written at all. If the server writes |
| 27348 |
less than the number of bytes specified, the client will need to send |
| 27349 |
another WRITE to write the remaining data. |
| 27350 |
|
| 27351 |
It is assumed that the act of writing data to a file will cause the |
| 27352 |
time_modified and change attributes of the file to be updated. |
| 27353 |
However, these attributes SHOULD NOT be changed unless the contents |
| 27354 |
of the file are changed. Thus, a WRITE request with count set to |
| 27355 |
zero SHOULD NOT cause the time_modified and change attributes of the |
| 27356 |
file to be updated. |
| 27357 |
|
| 27358 |
Stable storage is persistent storage that survives: |
| 27359 |
|
| 27360 |
1. Repeated power failures. |
| 27361 |
|
| 27362 |
2. Hardware failures (of any board, power supply, etc.). |
| 27363 |
|
| 27364 |
3. Repeated software crashes and restarts. |
| 27365 |
|
| 27366 |
This definition does not address failure of the stable storage module |
| 27367 |
itself. |
| 27368 |
|
| 27369 |
The verifier is defined to allow a client to detect different |
| 27370 |
instances of an NFSv4.1 protocol server over which cached, |
| 27371 |
uncommitted data may be lost. In the most likely case, the verifier |
| 27372 |
allows the client to detect server restarts. This information is |
| 27373 |
required so that the client can safely determine whether the server |
| 27374 |
could have lost cached data. If the server fails unexpectedly and |
| 27375 |
the client has uncommitted data from previous WRITE requests (done |
| 27376 |
with the stable argument set to UNSTABLE4 and in which the result |
| 27377 |
|
| 27378 |
|
| 27379 |
|
| 27380 |
<span class="grey">Shepler, et al. Standards Track [Page 489]</span></pre> |
| 27381 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-490" ></span> |
| 27382 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27383 |
|
| 27384 |
|
| 27385 |
committed was returned as UNSTABLE4 as well), the server might not |
| 27386 |
have flushed cached data to stable storage. The burden of recovery |
| 27387 |
is on the client, and the client will need to retransmit the data to |
| 27388 |
the server. |
| 27389 |
|
| 27390 |
A suggested verifier would be to use the time that the server was |
| 27391 |
last started (if restarting the server results in lost buffers). |
| 27392 |
|
| 27393 |
The reply's committed field allows the client to do more effective |
| 27394 |
caching. If the server is committing all WRITE requests to stable |
| 27395 |
storage, then it SHOULD return with committed set to FILE_SYNC4, |
| 27396 |
regardless of the value of the stable field in the arguments. A |
| 27397 |
server that uses an NVRAM accelerator may choose to implement this |
| 27398 |
policy. The client can use this to increase the effectiveness of the |
| 27399 |
cache by discarding cached data that has already been committed on |
| 27400 |
the server. |
| 27401 |
|
| 27402 |
Some implementations may return NFS4ERR_NOSPC instead of |
| 27403 |
NFS4ERR_DQUOT when a user's quota is exceeded. |
| 27404 |
|
| 27405 |
In the case that the current filehandle is of type NF4DIR, the server |
| 27406 |
will return NFS4ERR_ISDIR. If the current file is a symbolic link, |
| 27407 |
the error NFS4ERR_SYMLINK will be returned. Otherwise, if the |
| 27408 |
current filehandle does not designate an ordinary file, the server |
| 27409 |
will return NFS4ERR_WRONG_TYPE. |
| 27410 |
|
| 27411 |
If mandatory byte-range locking is in effect for the file, and the |
| 27412 |
corresponding byte-range of the data to be written to the file is |
| 27413 |
READ_LT or WRITE_LT locked by an owner that is not associated with |
| 27414 |
the stateid, the server MUST return NFS4ERR_LOCKED. If so, the |
| 27415 |
client MUST check if the owner corresponding to the stateid used with |
| 27416 |
the WRITE operation has a conflicting READ_LT lock that overlaps with |
| 27417 |
the byte-range that was to be written. If the stateid's owner has no |
| 27418 |
conflicting READ_LT lock, then the client SHOULD try to get the |
| 27419 |
appropriate write byte-range lock via the LOCK operation before re- |
| 27420 |
attempting the WRITE. When the WRITE completes, the client SHOULD |
| 27421 |
release the byte-range lock via LOCKU. |
| 27422 |
|
| 27423 |
If the stateid's owner had a conflicting READ_LT lock, then the |
| 27424 |
client has no choice but to return an error to the application that |
| 27425 |
attempted the WRITE. The reason is that since the stateid's owner |
| 27426 |
had a READ_LT lock, either the server attempted to temporarily |
| 27427 |
effectively upgrade this READ_LT lock to a WRITE_LT lock or the |
| 27428 |
server has no upgrade capability. If the server attempted to upgrade |
| 27429 |
the READ_LT lock and failed, it is pointless for the client to re- |
| 27430 |
attempt the upgrade via the LOCK operation, because there might be |
| 27431 |
another client also trying to upgrade. If two clients are blocked |
| 27432 |
|
| 27433 |
|
| 27434 |
|
| 27435 |
|
| 27436 |
<span class="grey">Shepler, et al. Standards Track [Page 490]</span></pre> |
| 27437 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-491" ></span> |
| 27438 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27439 |
|
| 27440 |
|
| 27441 |
trying to upgrade the same lock, the clients deadlock. If the server |
| 27442 |
has no upgrade capability, then it is pointless to try a LOCK |
| 27443 |
operation to upgrade. |
| 27444 |
|
| 27445 |
If one or more other clients have delegations for the file being |
| 27446 |
written, those delegations MUST be recalled, and the operation cannot |
| 27447 |
proceed until those delegations are returned or revoked. Except |
| 27448 |
where this happens very quickly, one or more NFS4ERR_DELAY errors |
| 27449 |
will be returned to requests made while the delegation remains |
| 27450 |
outstanding. Normally, delegations will not be recalled as a result |
| 27451 |
of a WRITE operation since the recall will occur as a result of an |
| 27452 |
earlier OPEN. However, since it is possible for a WRITE to be done |
| 27453 |
with a special stateid, the server needs to check for this case even |
| 27454 |
though the client should have done an OPEN previously. |
| 27455 |
|
| 27456 |
<span class="h3"><a class="selflink" id="section-18.33" href="#section-18.33">18.33</a>. Operation 40: BACKCHANNEL_CTL - Backchannel Control</span> |
| 27457 |
|
| 27458 |
<span class="h4"><a class="selflink" id="section-18.33.1" href="#section-18.33.1">18.33.1</a>. ARGUMENT</span> |
| 27459 |
|
| 27460 |
typedef opaque gsshandle4_t<>; |
| 27461 |
|
| 27462 |
struct gss_cb_handles4 { |
| 27463 |
rpc_gss_svc_t gcbp_service; /* <a href="./rfc2203">RFC 2203</a> */ |
| 27464 |
gsshandle4_t gcbp_handle_from_server; |
| 27465 |
gsshandle4_t gcbp_handle_from_client; |
| 27466 |
}; |
| 27467 |
|
| 27468 |
union callback_sec_parms4 switch (uint32_t cb_secflavor) { |
| 27469 |
case AUTH_NONE: |
| 27470 |
void; |
| 27471 |
case AUTH_SYS: |
| 27472 |
authsys_parms cbsp_sys_cred; /* <a href="./rfc1831">RFC 1831</a> */ |
| 27473 |
case RPCSEC_GSS: |
| 27474 |
gss_cb_handles4 cbsp_gss_handles; |
| 27475 |
}; |
| 27476 |
|
| 27477 |
struct BACKCHANNEL_CTL4args { |
| 27478 |
uint32_t bca_cb_program; |
| 27479 |
callback_sec_parms4 bca_sec_parms<>; |
| 27480 |
}; |
| 27481 |
|
| 27482 |
<span class="h4"><a class="selflink" id="section-18.33.2" href="#section-18.33.2">18.33.2</a>. RESULT</span> |
| 27483 |
|
| 27484 |
struct BACKCHANNEL_CTL4res { |
| 27485 |
nfsstat4 bcr_status; |
| 27486 |
}; |
| 27487 |
|
| 27488 |
|
| 27489 |
|
| 27490 |
|
| 27491 |
|
| 27492 |
<span class="grey">Shepler, et al. Standards Track [Page 491]</span></pre> |
| 27493 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-492" ></span> |
| 27494 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27495 |
|
| 27496 |
|
| 27497 |
<span class="h4"><a class="selflink" id="section-18.33.3" href="#section-18.33.3">18.33.3</a>. DESCRIPTION</span> |
| 27498 |
|
| 27499 |
The BACKCHANNEL_CTL operation replaces the backchannel's callback |
| 27500 |
program number and adds (not replaces) RPCSEC_GSS handles for use by |
| 27501 |
the backchannel. |
| 27502 |
|
| 27503 |
The arguments of the BACKCHANNEL_CTL call are a subset of the |
| 27504 |
CREATE_SESSION parameters. In the arguments of BACKCHANNEL_CTL, the |
| 27505 |
bca_cb_program field and bca_sec_parms fields correspond respectively |
| 27506 |
to the csa_cb_program and csa_sec_parms fields of the arguments of |
| 27507 |
CREATE_SESSION (<a href="#section-18.36">Section 18.36</a>). |
| 27508 |
|
| 27509 |
BACKCHANNEL_CTL MUST appear in a COMPOUND that starts with SEQUENCE. |
| 27510 |
|
| 27511 |
If the RPCSEC_GSS handle identified by gcbp_handle_from_server does |
| 27512 |
not exist on the server, the server MUST return NFS4ERR_NOENT. |
| 27513 |
|
| 27514 |
If an RPCSEC_GSS handle is using the SSV context (see |
| 27515 |
<a href="#section-2.10.9">Section 2.10.9</a>), then because each SSV RPCSEC_GSS handle shares a |
| 27516 |
common SSV GSS context, there are security considerations specific to |
| 27517 |
this situation discussed in <a href="#section-2.10.10">Section 2.10.10</a>. |
| 27518 |
|
| 27519 |
<span class="h3"><a class="selflink" id="section-18.34" href="#section-18.34">18.34</a>. Operation 41: BIND_CONN_TO_SESSION - Associate Connection with</span> |
| 27520 |
<span class="h3"> Session</span> |
| 27521 |
|
| 27522 |
<span class="h4"><a class="selflink" id="section-18.34.1" href="#section-18.34.1">18.34.1</a>. ARGUMENT</span> |
| 27523 |
|
| 27524 |
enum channel_dir_from_client4 { |
| 27525 |
CDFC4_FORE = 0x1, |
| 27526 |
CDFC4_BACK = 0x2, |
| 27527 |
CDFC4_FORE_OR_BOTH = 0x3, |
| 27528 |
CDFC4_BACK_OR_BOTH = 0x7 |
| 27529 |
}; |
| 27530 |
|
| 27531 |
struct BIND_CONN_TO_SESSION4args { |
| 27532 |
sessionid4 bctsa_sessid; |
| 27533 |
|
| 27534 |
channel_dir_from_client4 |
| 27535 |
bctsa_dir; |
| 27536 |
|
| 27537 |
bool bctsa_use_conn_in_rdma_mode; |
| 27538 |
}; |
| 27539 |
|
| 27540 |
|
| 27541 |
|
| 27542 |
|
| 27543 |
|
| 27544 |
|
| 27545 |
|
| 27546 |
|
| 27547 |
|
| 27548 |
<span class="grey">Shepler, et al. Standards Track [Page 492]</span></pre> |
| 27549 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-493" ></span> |
| 27550 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27551 |
|
| 27552 |
|
| 27553 |
<span class="h4"><a class="selflink" id="section-18.34.2" href="#section-18.34.2">18.34.2</a>. RESULT</span> |
| 27554 |
|
| 27555 |
enum channel_dir_from_server4 { |
| 27556 |
CDFS4_FORE = 0x1, |
| 27557 |
CDFS4_BACK = 0x2, |
| 27558 |
CDFS4_BOTH = 0x3 |
| 27559 |
}; |
| 27560 |
|
| 27561 |
struct BIND_CONN_TO_SESSION4resok { |
| 27562 |
sessionid4 bctsr_sessid; |
| 27563 |
|
| 27564 |
channel_dir_from_server4 |
| 27565 |
bctsr_dir; |
| 27566 |
|
| 27567 |
bool bctsr_use_conn_in_rdma_mode; |
| 27568 |
}; |
| 27569 |
|
| 27570 |
union BIND_CONN_TO_SESSION4res |
| 27571 |
switch (nfsstat4 bctsr_status) { |
| 27572 |
|
| 27573 |
case NFS4_OK: |
| 27574 |
BIND_CONN_TO_SESSION4resok |
| 27575 |
bctsr_resok4; |
| 27576 |
|
| 27577 |
default: void; |
| 27578 |
}; |
| 27579 |
|
| 27580 |
<span class="h4"><a class="selflink" id="section-18.34.3" href="#section-18.34.3">18.34.3</a>. DESCRIPTION</span> |
| 27581 |
|
| 27582 |
BIND_CONN_TO_SESSION is used to associate additional connections with |
| 27583 |
a session. It MUST be used on the connection being associated with |
| 27584 |
the session. It MUST be the only operation in the COMPOUND |
| 27585 |
procedure. If SP4_NONE (<a href="#section-18.35">Section 18.35</a>) state protection is used, any |
| 27586 |
principal, security flavor, or RPCSEC_GSS context MAY be used to |
| 27587 |
invoke the operation. If SP4_MACH_CRED is used, RPCSEC_GSS MUST be |
| 27588 |
used with the integrity or privacy services, using the principal that |
| 27589 |
created the client ID. If SP4_SSV is used, RPCSEC_GSS with the SSV |
| 27590 |
GSS mechanism (<a href="#section-2.10.9">Section 2.10.9</a>) and integrity or privacy MUST be used. |
| 27591 |
|
| 27592 |
If, when the client ID was created, the client opted for SP4_NONE |
| 27593 |
state protection, the client is not required to use |
| 27594 |
BIND_CONN_TO_SESSION to associate the connection with the session, |
| 27595 |
unless the client wishes to associate the connection with the |
| 27596 |
backchannel. When SP4_NONE protection is used, simply sending a |
| 27597 |
COMPOUND request with a SEQUENCE operation is sufficient to associate |
| 27598 |
the connection with the session specified in SEQUENCE. |
| 27599 |
|
| 27600 |
|
| 27601 |
|
| 27602 |
|
| 27603 |
|
| 27604 |
<span class="grey">Shepler, et al. Standards Track [Page 493]</span></pre> |
| 27605 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-494" ></span> |
| 27606 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27607 |
|
| 27608 |
|
| 27609 |
The field bctsa_dir indicates whether the client wants to associate |
| 27610 |
the connection with the fore channel or the backchannel or both |
| 27611 |
channels. The value CDFC4_FORE_OR_BOTH indicates that the client |
| 27612 |
wants to associate the connection with both the fore channel and |
| 27613 |
backchannel, but will accept the connection being associated to just |
| 27614 |
the fore channel. The value CDFC4_BACK_OR_BOTH indicates that the |
| 27615 |
client wants to associate with both the fore channel and backchannel, |
| 27616 |
but will accept the connection being associated with just the |
| 27617 |
backchannel. The server replies in bctsr_dir which channel(s) the |
| 27618 |
connection is associated with. If the client specified CDFC4_FORE, |
| 27619 |
the server MUST return CDFS4_FORE. If the client specified |
| 27620 |
CDFC4_BACK, the server MUST return CDFS4_BACK. If the client |
| 27621 |
specified CDFC4_FORE_OR_BOTH, the server MUST return CDFS4_FORE or |
| 27622 |
CDFS4_BOTH. If the client specified CDFC4_BACK_OR_BOTH, the server |
| 27623 |
MUST return CDFS4_BACK or CDFS4_BOTH. |
| 27624 |
|
| 27625 |
See the CREATE_SESSION operation (<a href="#section-18.36">Section 18.36</a>), and the description |
| 27626 |
of the argument csa_use_conn_in_rdma_mode to understand |
| 27627 |
bctsa_use_conn_in_rdma_mode, and the description of |
| 27628 |
csr_use_conn_in_rdma_mode to understand bctsr_use_conn_in_rdma_mode. |
| 27629 |
|
| 27630 |
Invoking BIND_CONN_TO_SESSION on a connection already associated with |
| 27631 |
the specified session has no effect, and the server MUST respond with |
| 27632 |
NFS4_OK, unless the client is demanding changes to the set of |
| 27633 |
channels the connection is associated with. If so, the server MUST |
| 27634 |
return NFS4ERR_INVAL. |
| 27635 |
|
| 27636 |
<span class="h4"><a class="selflink" id="section-18.34.4" href="#section-18.34.4">18.34.4</a>. IMPLEMENTATION</span> |
| 27637 |
|
| 27638 |
If a session's channel loses all connections, depending on the client |
| 27639 |
ID's state protection and type of channel, the client might need to |
| 27640 |
use BIND_CONN_TO_SESSION to associate a new connection. If the |
| 27641 |
server restarted and does not keep the reply cache in stable storage, |
| 27642 |
the server will not recognize the session ID. The client will |
| 27643 |
ultimately have to invoke EXCHANGE_ID to create a new client ID and |
| 27644 |
session. |
| 27645 |
|
| 27646 |
Suppose SP4_SSV state protection is being used, and |
| 27647 |
BIND_CONN_TO_SESSION is among the operations included in the |
| 27648 |
spo_must_enforce set when the client ID was created (<a href="#section-18.35">Section 18.35</a>). |
| 27649 |
If so, there is an issue if SET_SSV is sent, no response is returned, |
| 27650 |
and the last connection associated with the client ID drops. The |
| 27651 |
client, per the sessions model, MUST retry the SET_SSV. But it needs |
| 27652 |
a new connection to do so, and MUST associate that connection with |
| 27653 |
the session via a BIND_CONN_TO_SESSION authenticated with the SSV GSS |
| 27654 |
mechanism. The problem is that the RPCSEC_GSS message integrity |
| 27655 |
|
| 27656 |
|
| 27657 |
|
| 27658 |
|
| 27659 |
|
| 27660 |
<span class="grey">Shepler, et al. Standards Track [Page 494]</span></pre> |
| 27661 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-495" ></span> |
| 27662 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27663 |
|
| 27664 |
|
| 27665 |
codes use a subkey derived from the SSV as the key and the SSV may |
| 27666 |
have changed. While there are multiple recovery strategies, a |
| 27667 |
single, general strategy is described here. |
| 27668 |
|
| 27669 |
o The client reconnects. |
| 27670 |
|
| 27671 |
o The client assumes that the SET_SSV was executed, and so sends |
| 27672 |
BIND_CONN_TO_SESSION with the subkey (derived from the new SSV, |
| 27673 |
i.e., what SET_SSV would have set the SSV to) used as the key for |
| 27674 |
the RPCSEC_GSS credential message integrity codes. |
| 27675 |
|
| 27676 |
o If the request succeeds, this means that the original attempted |
| 27677 |
SET_SSV did execute successfully. The client re-sends the |
| 27678 |
original SET_SSV, which the server will reply to via the reply |
| 27679 |
cache. |
| 27680 |
|
| 27681 |
o If the server returns an RPC authentication error, this means that |
| 27682 |
the server's current SSV was not changed (and the SET_SSV was |
| 27683 |
likely not executed). The client then tries BIND_CONN_TO_SESSION |
| 27684 |
with the subkey derived from the old SSV as the key for the |
| 27685 |
RPCSEC_GSS message integrity codes. |
| 27686 |
|
| 27687 |
o The attempted BIND_CONN_TO_SESSION with the old SSV should |
| 27688 |
succeed. If so, the client re-sends the original SET_SSV. If the |
| 27689 |
original SET_SSV was not executed, then the server executes it. |
| 27690 |
If the original SET_SSV was executed but failed, the server will |
| 27691 |
return the SET_SSV from the reply cache. |
| 27692 |
|
| 27693 |
<span class="h3"><a class="selflink" id="section-18.35" href="#section-18.35">18.35</a>. Operation 42: EXCHANGE_ID - Instantiate Client ID</span> |
| 27694 |
|
| 27695 |
The EXCHANGE_ID exchanges long-hand client and server identifiers |
| 27696 |
(owners), and creates a client ID. |
| 27697 |
|
| 27698 |
<span class="h4"><a class="selflink" id="section-18.35.1" href="#section-18.35.1">18.35.1</a>. ARGUMENT</span> |
| 27699 |
|
| 27700 |
const EXCHGID4_FLAG_SUPP_MOVED_REFER = 0x00000001; |
| 27701 |
const EXCHGID4_FLAG_SUPP_MOVED_MIGR = 0x00000002; |
| 27702 |
|
| 27703 |
const EXCHGID4_FLAG_BIND_PRINC_STATEID = 0x00000100; |
| 27704 |
|
| 27705 |
const EXCHGID4_FLAG_USE_NON_PNFS = 0x00010000; |
| 27706 |
const EXCHGID4_FLAG_USE_PNFS_MDS = 0x00020000; |
| 27707 |
const EXCHGID4_FLAG_USE_PNFS_DS = 0x00040000; |
| 27708 |
|
| 27709 |
const EXCHGID4_FLAG_MASK_PNFS = 0x00070000; |
| 27710 |
|
| 27711 |
const EXCHGID4_FLAG_UPD_CONFIRMED_REC_A = 0x40000000; |
| 27712 |
const EXCHGID4_FLAG_CONFIRMED_R = 0x80000000; |
| 27713 |
|
| 27714 |
|
| 27715 |
|
| 27716 |
<span class="grey">Shepler, et al. Standards Track [Page 495]</span></pre> |
| 27717 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-496" ></span> |
| 27718 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27719 |
|
| 27720 |
|
| 27721 |
struct state_protect_ops4 { |
| 27722 |
bitmap4 spo_must_enforce; |
| 27723 |
bitmap4 spo_must_allow; |
| 27724 |
}; |
| 27725 |
|
| 27726 |
struct ssv_sp_parms4 { |
| 27727 |
state_protect_ops4 ssp_ops; |
| 27728 |
sec_oid4 ssp_hash_algs<>; |
| 27729 |
sec_oid4 ssp_encr_algs<>; |
| 27730 |
uint32_t ssp_window; |
| 27731 |
uint32_t ssp_num_gss_handles; |
| 27732 |
}; |
| 27733 |
|
| 27734 |
enum state_protect_how4 { |
| 27735 |
SP4_NONE = 0, |
| 27736 |
SP4_MACH_CRED = 1, |
| 27737 |
SP4_SSV = 2 |
| 27738 |
}; |
| 27739 |
|
| 27740 |
union state_protect4_a switch(state_protect_how4 spa_how) { |
| 27741 |
case SP4_NONE: |
| 27742 |
void; |
| 27743 |
case SP4_MACH_CRED: |
| 27744 |
state_protect_ops4 spa_mach_ops; |
| 27745 |
case SP4_SSV: |
| 27746 |
ssv_sp_parms4 spa_ssv_parms; |
| 27747 |
}; |
| 27748 |
|
| 27749 |
struct EXCHANGE_ID4args { |
| 27750 |
client_owner4 eia_clientowner; |
| 27751 |
uint32_t eia_flags; |
| 27752 |
state_protect4_a eia_state_protect; |
| 27753 |
nfs_impl_id4 eia_client_impl_id<1>; |
| 27754 |
}; |
| 27755 |
|
| 27756 |
<span class="h4"><a class="selflink" id="section-18.35.2" href="#section-18.35.2">18.35.2</a>. RESULT</span> |
| 27757 |
|
| 27758 |
struct ssv_prot_info4 { |
| 27759 |
state_protect_ops4 spi_ops; |
| 27760 |
uint32_t spi_hash_alg; |
| 27761 |
uint32_t spi_encr_alg; |
| 27762 |
uint32_t spi_ssv_len; |
| 27763 |
uint32_t spi_window; |
| 27764 |
gsshandle4_t spi_handles<>; |
| 27765 |
}; |
| 27766 |
|
| 27767 |
|
| 27768 |
|
| 27769 |
|
| 27770 |
|
| 27771 |
|
| 27772 |
<span class="grey">Shepler, et al. Standards Track [Page 496]</span></pre> |
| 27773 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-497" ></span> |
| 27774 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27775 |
|
| 27776 |
|
| 27777 |
union state_protect4_r switch(state_protect_how4 spr_how) { |
| 27778 |
case SP4_NONE: |
| 27779 |
void; |
| 27780 |
case SP4_MACH_CRED: |
| 27781 |
state_protect_ops4 spr_mach_ops; |
| 27782 |
case SP4_SSV: |
| 27783 |
ssv_prot_info4 spr_ssv_info; |
| 27784 |
}; |
| 27785 |
|
| 27786 |
struct EXCHANGE_ID4resok { |
| 27787 |
clientid4 eir_clientid; |
| 27788 |
sequenceid4 eir_sequenceid; |
| 27789 |
uint32_t eir_flags; |
| 27790 |
state_protect4_r eir_state_protect; |
| 27791 |
server_owner4 eir_server_owner; |
| 27792 |
opaque eir_server_scope<NFS4_OPAQUE_LIMIT>; |
| 27793 |
nfs_impl_id4 eir_server_impl_id<1>; |
| 27794 |
}; |
| 27795 |
|
| 27796 |
union EXCHANGE_ID4res switch (nfsstat4 eir_status) { |
| 27797 |
case NFS4_OK: |
| 27798 |
EXCHANGE_ID4resok eir_resok4; |
| 27799 |
|
| 27800 |
default: |
| 27801 |
void; |
| 27802 |
}; |
| 27803 |
|
| 27804 |
<span class="h4"><a class="selflink" id="section-18.35.3" href="#section-18.35.3">18.35.3</a>. DESCRIPTION</span> |
| 27805 |
|
| 27806 |
The client uses the EXCHANGE_ID operation to register a particular |
| 27807 |
client owner with the server. The client ID returned from this |
| 27808 |
operation will be necessary for requests that create state on the |
| 27809 |
server and will serve as a parent object to sessions created by the |
| 27810 |
client. In order to confirm the client ID it must first be used, |
| 27811 |
along with the returned eir_sequenceid, as arguments to |
| 27812 |
CREATE_SESSION. If the flag EXCHGID4_FLAG_CONFIRMED_R is set in the |
| 27813 |
result, eir_flags, then eir_sequenceid MUST be ignored, as it has no |
| 27814 |
relevancy. |
| 27815 |
|
| 27816 |
EXCHANGE_ID MAY be sent in a COMPOUND procedure that starts with |
| 27817 |
SEQUENCE. However, when a client communicates with a server for the |
| 27818 |
first time, it will not have a session, so using SEQUENCE will not be |
| 27819 |
possible. If EXCHANGE_ID is sent without a preceding SEQUENCE, then |
| 27820 |
it MUST be the only operation in the COMPOUND procedure's request. |
| 27821 |
If it is not, the server MUST return NFS4ERR_NOT_ONLY_OP. |
| 27822 |
|
| 27823 |
|
| 27824 |
|
| 27825 |
|
| 27826 |
|
| 27827 |
|
| 27828 |
<span class="grey">Shepler, et al. Standards Track [Page 497]</span></pre> |
| 27829 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-498" ></span> |
| 27830 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27831 |
|
| 27832 |
|
| 27833 |
The eia_clientowner field is composed of a co_verifier field and a |
| 27834 |
co_ownerid string. As noted in <a href="#section-2.4">Section 2.4</a>, the co_ownerid describes |
| 27835 |
the client, and the co_verifier is the incarnation of the client. An |
| 27836 |
EXCHANGE_ID sent with a new incarnation of the client will lead to |
| 27837 |
the server removing lock state of the old incarnation. Whereas an |
| 27838 |
EXCHANGE_ID sent with the current incarnation and co_ownerid will |
| 27839 |
result in an error or an update of the client ID's properties, |
| 27840 |
depending on the arguments to EXCHANGE_ID. |
| 27841 |
|
| 27842 |
A server MUST NOT use the same client ID for two different |
| 27843 |
incarnations of an eir_clientowner. |
| 27844 |
|
| 27845 |
In addition to the client ID and sequence ID, the server returns a |
| 27846 |
server owner (eir_server_owner) and server scope (eir_server_scope). |
| 27847 |
The former field is used for network trunking as described in |
| 27848 |
<a href="#section-2.10.5">Section 2.10.5</a>. The latter field is used to allow clients to |
| 27849 |
determine when client IDs sent by one server may be recognized by |
| 27850 |
another in the event of file system migration (see <a href="#section-11.7.7">Section 11.7.7</a>). |
| 27851 |
|
| 27852 |
The client ID returned by EXCHANGE_ID is only unique relative to the |
| 27853 |
combination of eir_server_owner.so_major_id and eir_server_scope. |
| 27854 |
Thus, if two servers return the same client ID, the onus is on the |
| 27855 |
client to distinguish the client IDs on the basis of |
| 27856 |
eir_server_owner.so_major_id and eir_server_scope. In the event two |
| 27857 |
different servers claim matching server_owner.so_major_id and |
| 27858 |
eir_server_scope, the client can use the verification techniques |
| 27859 |
discussed in <a href="#section-2.10.5">Section 2.10.5</a> to determine if the servers are distinct. |
| 27860 |
If they are distinct, then the client will need to note the |
| 27861 |
destination network addresses of the connections used with each |
| 27862 |
server, and use the network address as the final discriminator. |
| 27863 |
|
| 27864 |
The server, as defined by the unique identity expressed in the |
| 27865 |
so_major_id of the server owner and the server scope, needs to track |
| 27866 |
several properties of each client ID it hands out. The properties |
| 27867 |
apply to the client ID and all sessions associated with the client |
| 27868 |
ID. The properties are derived from the arguments and results of |
| 27869 |
EXCHANGE_ID. The client ID properties include: |
| 27870 |
|
| 27871 |
o The capabilities expressed by the following bits, which come from |
| 27872 |
the results of EXCHANGE_ID: |
| 27873 |
|
| 27874 |
* EXCHGID4_FLAG_SUPP_MOVED_REFER |
| 27875 |
|
| 27876 |
* EXCHGID4_FLAG_SUPP_MOVED_MIGR |
| 27877 |
|
| 27878 |
* EXCHGID4_FLAG_BIND_PRINC_STATEID |
| 27879 |
|
| 27880 |
* EXCHGID4_FLAG_USE_NON_PNFS |
| 27881 |
|
| 27882 |
|
| 27883 |
|
| 27884 |
<span class="grey">Shepler, et al. Standards Track [Page 498]</span></pre> |
| 27885 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-499" ></span> |
| 27886 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27887 |
|
| 27888 |
|
| 27889 |
* EXCHGID4_FLAG_USE_PNFS_MDS |
| 27890 |
|
| 27891 |
* EXCHGID4_FLAG_USE_PNFS_DS |
| 27892 |
|
| 27893 |
These properties may be updated by subsequent EXCHANGE_ID requests |
| 27894 |
on confirmed client IDs though the server MAY refuse to change |
| 27895 |
them. |
| 27896 |
|
| 27897 |
o The state protection method used, one of SP4_NONE, SP4_MACH_CRED, |
| 27898 |
or SP4_SSV, as set by the spa_how field of the arguments to |
| 27899 |
EXCHANGE_ID. Once the client ID is confirmed, this property |
| 27900 |
cannot be updated by subsequent EXCHANGE_ID requests. |
| 27901 |
|
| 27902 |
o For SP4_MACH_CRED or SP4_SSV state protection: |
| 27903 |
|
| 27904 |
* The list of operations (spo_must_enforce) that MUST use the |
| 27905 |
specified state protection. This list comes from the results |
| 27906 |
of EXCHANGE_ID. |
| 27907 |
|
| 27908 |
* The list of operations (spo_must_allow) that MAY use the |
| 27909 |
specified state protection. This list comes from the results |
| 27910 |
of EXCHANGE_ID. |
| 27911 |
|
| 27912 |
Once the client ID is confirmed, these properties cannot be |
| 27913 |
updated by subsequent EXCHANGE_ID requests. |
| 27914 |
|
| 27915 |
o For SP4_SSV protection: |
| 27916 |
|
| 27917 |
* The OID of the hash algorithm. This property is represented by |
| 27918 |
one of the algorithms in the ssp_hash_algs field of the |
| 27919 |
EXCHANGE_ID arguments. Once the client ID is confirmed, this |
| 27920 |
property cannot be updated by subsequent EXCHANGE_ID requests. |
| 27921 |
|
| 27922 |
* The OID of the encryption algorithm. This property is |
| 27923 |
represented by one of the algorithms in the ssp_encr_algs field |
| 27924 |
of the EXCHANGE_ID arguments. Once the client ID is confirmed, |
| 27925 |
this property cannot be updated by subsequent EXCHANGE_ID |
| 27926 |
requests. |
| 27927 |
|
| 27928 |
* The length of the SSV. This property is represented by the |
| 27929 |
spi_ssv_len field in the EXCHANGE_ID results. Once the client |
| 27930 |
ID is confirmed, this property cannot be updated by subsequent |
| 27931 |
EXCHANGE_ID requests. |
| 27932 |
|
| 27933 |
There are REQUIRED and RECOMMENDED relationships among the |
| 27934 |
length of the key of the encryption algorithm ("key length"), |
| 27935 |
the length of the output of hash algorithm ("hash length"), and |
| 27936 |
the length of the SSV ("SSV length"). |
| 27937 |
|
| 27938 |
|
| 27939 |
|
| 27940 |
<span class="grey">Shepler, et al. Standards Track [Page 499]</span></pre> |
| 27941 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-500" ></span> |
| 27942 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27943 |
|
| 27944 |
|
| 27945 |
+ key length MUST be <= hash length. This is because the keys |
| 27946 |
used for the encryption algorithm are actually subkeys |
| 27947 |
derived from the SSV, and the derivation is via the hash |
| 27948 |
algorithm. The selection of an encryption algorithm with a |
| 27949 |
key length that exceeded the length of the output of the |
| 27950 |
hash algorithm would require padding, and thus weaken the |
| 27951 |
use of the encryption algorithm. |
| 27952 |
|
| 27953 |
+ hash length SHOULD be <= SSV length. This is because the |
| 27954 |
SSV is a key used to derive subkeys via an HMAC, and it is |
| 27955 |
recommended that the key used as input to an HMAC be at |
| 27956 |
least as long as the length of the HMAC's hash algorithm's |
| 27957 |
output (see <a href="./rfc2104#section-3">Section 3 of RFC2104</a> [<a href="#ref-11" title=""HMAC: Keyed-Hashing for Message Authentication"">11</a>]). |
| 27958 |
|
| 27959 |
+ key length SHOULD be <= SSV length. This is a transitive |
| 27960 |
result of the above two invariants. |
| 27961 |
|
| 27962 |
+ key length SHOULD be >= hash length / 2. This is because |
| 27963 |
the subkey derivation is via an HMAC and it is recommended |
| 27964 |
that if the HMAC has to be truncated, it should not be |
| 27965 |
truncated to less than half the hash length (see <a href="./rfc2104#section-4">Section 4 |
| 27966 |
of RFC2104</a> [<a href="#ref-11" title=""HMAC: Keyed-Hashing for Message Authentication"">11</a>]). |
| 27967 |
|
| 27968 |
* Number of concurrent versions of the SSV the client and server |
| 27969 |
will support (<a href="#section-2.10.9">Section 2.10.9</a>). This property is represented by |
| 27970 |
spi_window in the EXCHANGE_ID results. The property may be |
| 27971 |
updated by subsequent EXCHANGE_ID requests. |
| 27972 |
|
| 27973 |
o The client's implementation ID as represented by the |
| 27974 |
eia_client_impl_id field of the arguments. The property may be |
| 27975 |
updated by subsequent EXCHANGE_ID requests. |
| 27976 |
|
| 27977 |
o The server's implementation ID as represented by the |
| 27978 |
eir_server_impl_id field of the reply. The property may be |
| 27979 |
updated by replies to subsequent EXCHANGE_ID requests. |
| 27980 |
|
| 27981 |
The eia_flags passed as part of the arguments and the eir_flags |
| 27982 |
results allow the client and server to inform each other of their |
| 27983 |
capabilities as well as indicate how the client ID will be used. |
| 27984 |
Whether a bit is set or cleared on the arguments' flags does not |
| 27985 |
force the server to set or clear the same bit on the results' side. |
| 27986 |
Bits not defined above cannot be set in the eia_flags field. If they |
| 27987 |
are, the server MUST reject the operation with NFS4ERR_INVAL. |
| 27988 |
|
| 27989 |
The EXCHGID4_FLAG_UPD_CONFIRMED_REC_A bit can only be set in |
| 27990 |
eia_flags; it is always off in eir_flags. The |
| 27991 |
EXCHGID4_FLAG_CONFIRMED_R bit can only be set in eir_flags; it is |
| 27992 |
always off in eia_flags. If the server recognizes the co_ownerid and |
| 27993 |
|
| 27994 |
|
| 27995 |
|
| 27996 |
<span class="grey">Shepler, et al. Standards Track [Page 500]</span></pre> |
| 27997 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-501" ></span> |
| 27998 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 27999 |
|
| 28000 |
|
| 28001 |
co_verifier as mapping to a confirmed client ID, it sets |
| 28002 |
EXCHGID4_FLAG_CONFIRMED_R in eir_flags. The |
| 28003 |
EXCHGID4_FLAG_CONFIRMED_R flag allows a client to tell if the client |
| 28004 |
ID it is trying to create already exists and is confirmed. |
| 28005 |
|
| 28006 |
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set in eia_flags, this means |
| 28007 |
that the client is attempting to update properties of an existing |
| 28008 |
confirmed client ID (if the client wants to update properties of an |
| 28009 |
unconfirmed client ID, it MUST NOT set |
| 28010 |
EXCHGID4_FLAG_UPD_CONFIRMED_REC_A). If so, it is RECOMMENDED that |
| 28011 |
the client send the update EXCHANGE_ID operation in the same COMPOUND |
| 28012 |
as a SEQUENCE so that the EXCHANGE_ID is executed exactly once. |
| 28013 |
Whether the client can update the properties of client ID depends on |
| 28014 |
the state protection it selected when the client ID was created, and |
| 28015 |
the principal and security flavor it uses when sending the |
| 28016 |
EXCHANGE_ID request. The situations described in items 6, 7, 8, or 9 |
| 28017 |
of the second numbered list of <a href="#section-18.35.4">Section 18.35.4</a> will apply. Note that |
| 28018 |
if the operation succeeds and returns a client ID that is already |
| 28019 |
confirmed, the server MUST set the EXCHGID4_FLAG_CONFIRMED_R bit in |
| 28020 |
eir_flags. |
| 28021 |
|
| 28022 |
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set in eia_flags, this |
| 28023 |
means that the client is trying to establish a new client ID; it is |
| 28024 |
attempting to trunk data communication to the server |
| 28025 |
(<a href="#section-2.10.5">Section 2.10.5</a>); or it is attempting to update properties of an |
| 28026 |
unconfirmed client ID. The situations described in items 1, 2, 3, 4, |
| 28027 |
or 5 of the second numbered list of <a href="#section-18.35.4">Section 18.35.4</a> will apply. Note |
| 28028 |
that if the operation succeeds and returns a client ID that was |
| 28029 |
previously confirmed, the server MUST set the |
| 28030 |
EXCHGID4_FLAG_CONFIRMED_R bit in eir_flags. |
| 28031 |
|
| 28032 |
When the EXCHGID4_FLAG_SUPP_MOVED_REFER flag bit is set, the client |
| 28033 |
indicates that it is capable of dealing with an NFS4ERR_MOVED error |
| 28034 |
as part of a referral sequence. When this bit is not set, it is |
| 28035 |
still legal for the server to perform a referral sequence. However, |
| 28036 |
a server may use the fact that the client is incapable of correctly |
| 28037 |
responding to a referral, by avoiding it for that particular client. |
| 28038 |
It may, for instance, act as a proxy for that particular file system, |
| 28039 |
at some cost in performance, although it is not obligated to do so. |
| 28040 |
If the server will potentially perform a referral, it MUST set |
| 28041 |
EXCHGID4_FLAG_SUPP_MOVED_REFER in eir_flags. |
| 28042 |
|
| 28043 |
When the EXCHGID4_FLAG_SUPP_MOVED_MIGR is set, the client indicates |
| 28044 |
that it is capable of dealing with an NFS4ERR_MOVED error as part of |
| 28045 |
a file system migration sequence. When this bit is not set, it is |
| 28046 |
still legal for the server to indicate that a file system has moved, |
| 28047 |
when this in fact happens. However, a server may use the fact that |
| 28048 |
the client is incapable of correctly responding to a migration in its |
| 28049 |
|
| 28050 |
|
| 28051 |
|
| 28052 |
<span class="grey">Shepler, et al. Standards Track [Page 501]</span></pre> |
| 28053 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-502" ></span> |
| 28054 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28055 |
|
| 28056 |
|
| 28057 |
scheduling of file systems to migrate so as to avoid migration of |
| 28058 |
file systems being actively used. It may also hide actual migrations |
| 28059 |
from clients unable to deal with them by acting as a proxy for a |
| 28060 |
migrated file system for particular clients, at some cost in |
| 28061 |
performance, although it is not obligated to do so. If the server |
| 28062 |
will potentially perform a migration, it MUST set |
| 28063 |
EXCHGID4_FLAG_SUPP_MOVED_MIGR in eir_flags. |
| 28064 |
|
| 28065 |
When EXCHGID4_FLAG_BIND_PRINC_STATEID is set, the client indicates |
| 28066 |
that it wants the server to bind the stateid to the principal. This |
| 28067 |
means that when a principal creates a stateid, it has to be the one |
| 28068 |
to use the stateid. If the server will perform binding, it will |
| 28069 |
return EXCHGID4_FLAG_BIND_PRINC_STATEID. The server MAY return |
| 28070 |
EXCHGID4_FLAG_BIND_PRINC_STATEID even if the client does not request |
| 28071 |
it. If an update to the client ID changes the value of |
| 28072 |
EXCHGID4_FLAG_BIND_PRINC_STATEID's client ID property, the effect |
| 28073 |
applies only to new stateids. Existing stateids (and all stateids |
| 28074 |
with the same "other" field) that were created with stateid to |
| 28075 |
principal binding in force will continue to have binding in force. |
| 28076 |
Existing stateids (and all stateids with the same "other" field) that |
| 28077 |
were created with stateid to principal not in force will continue to |
| 28078 |
have binding not in force. |
| 28079 |
|
| 28080 |
The EXCHGID4_FLAG_USE_NON_PNFS, EXCHGID4_FLAG_USE_PNFS_MDS, and |
| 28081 |
EXCHGID4_FLAG_USE_PNFS_DS bits are described in <a href="#section-13.1">Section 13.1</a> and |
| 28082 |
convey roles the client ID is to be used for in a pNFS environment. |
| 28083 |
The server MUST set one of the acceptable combinations of these bits |
| 28084 |
(roles) in eir_flags, as specified in <a href="#section-13.1">Section 13.1</a>. Note that the |
| 28085 |
same client owner/server owner pair can have multiple roles. |
| 28086 |
Multiple roles can be associated with the same client ID or with |
| 28087 |
different client IDs. Thus, if a client sends EXCHANGE_ID from the |
| 28088 |
same client owner to the same server owner multiple times, but |
| 28089 |
specifies different pNFS roles each time, the server might return |
| 28090 |
different client IDs. Given that different pNFS roles might have |
| 28091 |
different client IDs, the client may ask for different properties for |
| 28092 |
each role/client ID. |
| 28093 |
|
| 28094 |
The spa_how field of the eia_state_protect field specifies how the |
| 28095 |
client wants to protect its client, locking, and session states from |
| 28096 |
unauthorized changes (<a href="#section-2.10.8.3">Section 2.10.8.3</a>): |
| 28097 |
|
| 28098 |
o SP4_NONE. The client does not request the NFSv4.1 server to |
| 28099 |
enforce state protection. The NFSv4.1 server MUST NOT enforce |
| 28100 |
state protection for the returned client ID. |
| 28101 |
|
| 28102 |
o SP4_MACH_CRED. If spa_how is SP4_MACH_CRED, then the client MUST |
| 28103 |
send the EXCHANGE_ID request with RPCSEC_GSS as the security |
| 28104 |
flavor, and with a service of RPC_GSS_SVC_INTEGRITY or |
| 28105 |
|
| 28106 |
|
| 28107 |
|
| 28108 |
<span class="grey">Shepler, et al. Standards Track [Page 502]</span></pre> |
| 28109 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-503" ></span> |
| 28110 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28111 |
|
| 28112 |
|
| 28113 |
RPC_GSS_SVC_PRIVACY. If SP4_MACH_CRED is specified, then the |
| 28114 |
client wants to use an RPCSEC_GSS-based machine credential to |
| 28115 |
protect its state. The server MUST note the principal the |
| 28116 |
EXCHANGE_ID operation was sent with, and the GSS mechanism used. |
| 28117 |
These notes collectively comprise the machine credential. |
| 28118 |
|
| 28119 |
After the client ID is confirmed, as long as the lease associated |
| 28120 |
with the client ID is unexpired, a subsequent EXCHANGE_ID |
| 28121 |
operation that uses the same eia_clientowner.co_owner as the first |
| 28122 |
EXCHANGE_ID MUST also use the same machine credential as the first |
| 28123 |
EXCHANGE_ID. The server returns the same client ID for the |
| 28124 |
subsequent EXCHANGE_ID as that returned from the first |
| 28125 |
EXCHANGE_ID. |
| 28126 |
|
| 28127 |
o SP4_SSV. If spa_how is SP4_SSV, then the client MUST send the |
| 28128 |
EXCHANGE_ID request with RPCSEC_GSS as the security flavor, and |
| 28129 |
with a service of RPC_GSS_SVC_INTEGRITY or RPC_GSS_SVC_PRIVACY. |
| 28130 |
If SP4_SSV is specified, then the client wants to use the SSV to |
| 28131 |
protect its state. The server records the credential used in the |
| 28132 |
request as the machine credential (as defined above) for the |
| 28133 |
eia_clientowner.co_owner. The CREATE_SESSION operation that |
| 28134 |
confirms the client ID MUST use the same machine credential. |
| 28135 |
|
| 28136 |
When a client specifies SP4_MACH_CRED or SP4_SSV, it also provides |
| 28137 |
two lists of operations (each expressed as a bitmap). The first list |
| 28138 |
is spo_must_enforce and consists of those operations the client MUST |
| 28139 |
send (subject to the server confirming the list of operations in the |
| 28140 |
result of EXCHANGE_ID) with the machine credential (if SP4_MACH_CRED |
| 28141 |
protection is specified) or the SSV-based credential (if SP4_SSV |
| 28142 |
protection is used). The client MUST send the operations with |
| 28143 |
RPCSEC_GSS credentials that specify the RPC_GSS_SVC_INTEGRITY or |
| 28144 |
RPC_GSS_SVC_PRIVACY security service. Typically, the first list of |
| 28145 |
operations includes EXCHANGE_ID, CREATE_SESSION, DELEGPURGE, |
| 28146 |
DESTROY_SESSION, BIND_CONN_TO_SESSION, and DESTROY_CLIENTID. The |
| 28147 |
client SHOULD NOT specify in this list any operations that require a |
| 28148 |
filehandle because the server's access policies MAY conflict with the |
| 28149 |
client's choice, and thus the client would then be unable to access a |
| 28150 |
subset of the server's namespace. |
| 28151 |
|
| 28152 |
Note that if SP4_SSV protection is specified, and the client |
| 28153 |
indicates that CREATE_SESSION must be protected with SP4_SSV, because |
| 28154 |
the SSV cannot exist without a confirmed client ID, the first |
| 28155 |
CREATE_SESSION MUST instead be sent using the machine credential, and |
| 28156 |
the server MUST accept the machine credential. |
| 28157 |
|
| 28158 |
There is a corresponding result, also called spo_must_enforce, of the |
| 28159 |
operations for which the server will require SP4_MACH_CRED or SP4_SSV |
| 28160 |
protection. Normally, the server's result equals the client's |
| 28161 |
|
| 28162 |
|
| 28163 |
|
| 28164 |
<span class="grey">Shepler, et al. Standards Track [Page 503]</span></pre> |
| 28165 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-504" ></span> |
| 28166 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28167 |
|
| 28168 |
|
| 28169 |
argument, but the result MAY be different. If the client requests |
| 28170 |
one or more operations in the set { EXCHANGE_ID, CREATE_SESSION, |
| 28171 |
DELEGPURGE, DESTROY_SESSION, BIND_CONN_TO_SESSION, DESTROY_CLIENTID |
| 28172 |
}, then the result spo_must_enforce MUST include the operations the |
| 28173 |
client requested from that set. |
| 28174 |
|
| 28175 |
If spo_must_enforce in the results has BIND_CONN_TO_SESSION set, then |
| 28176 |
connection binding enforcement is enabled, and the client MUST use |
| 28177 |
the machine (if SP4_MACH_CRED protection is used) or SSV (if SP4_SSV |
| 28178 |
protection is used) credential on calls to BIND_CONN_TO_SESSION. |
| 28179 |
|
| 28180 |
The second list is spo_must_allow and consists of those operations |
| 28181 |
the client wants to have the option of sending with the machine |
| 28182 |
credential or the SSV-based credential, even if the object the |
| 28183 |
operations are performed on is not owned by the machine or SSV |
| 28184 |
credential. |
| 28185 |
|
| 28186 |
The corresponding result, also called spo_must_allow, consists of the |
| 28187 |
operations the server will allow the client to use SP4_SSV or |
| 28188 |
SP4_MACH_CRED credentials with. Normally, the server's result equals |
| 28189 |
the client's argument, but the result MAY be different. |
| 28190 |
|
| 28191 |
The purpose of spo_must_allow is to allow clients to solve the |
| 28192 |
following conundrum. Suppose the client ID is confirmed with |
| 28193 |
EXCHGID4_FLAG_BIND_PRINC_STATEID, and it calls OPEN with the |
| 28194 |
RPCSEC_GSS credentials of a normal user. Now suppose the user's |
| 28195 |
credentials expire, and cannot be renewed (e.g., a Kerberos ticket |
| 28196 |
granting ticket expires, and the user has logged off and will not be |
| 28197 |
acquiring a new ticket granting ticket). The client will be unable |
| 28198 |
to send CLOSE without the user's credentials, which is to say the |
| 28199 |
client has to either leave the state on the server or re-send |
| 28200 |
EXCHANGE_ID with a new verifier to clear all state, that is, unless |
| 28201 |
the client includes CLOSE on the list of operations in spo_must_allow |
| 28202 |
and the server agrees. |
| 28203 |
|
| 28204 |
The SP4_SSV protection parameters also have: |
| 28205 |
|
| 28206 |
ssp_hash_algs: |
| 28207 |
|
| 28208 |
This is the set of algorithms the client supports for the purpose |
| 28209 |
of computing the digests needed for the internal SSV GSS mechanism |
| 28210 |
and for the SET_SSV operation. Each algorithm is specified as an |
| 28211 |
object identifier (OID). The REQUIRED algorithms for a server are |
| 28212 |
id-sha1, id-sha224, id-sha256, id-sha384, and id-sha512 [<a href="#ref-28" title=""Additional Algorithms and Identifiers for RSA Cryptography for use in the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile"">28</a>]. The |
| 28213 |
algorithm the server selects among the set is indicated in |
| 28214 |
spi_hash_alg, a field of spr_ssv_prot_info. The field |
| 28215 |
spi_hash_alg is an index into the array ssp_hash_algs. If the |
| 28216 |
|
| 28217 |
|
| 28218 |
|
| 28219 |
|
| 28220 |
<span class="grey">Shepler, et al. Standards Track [Page 504]</span></pre> |
| 28221 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-505" ></span> |
| 28222 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28223 |
|
| 28224 |
|
| 28225 |
server does not support any of the offered algorithms, it returns |
| 28226 |
NFS4ERR_HASH_ALG_UNSUPP. If ssp_hash_algs is empty, the server |
| 28227 |
MUST return NFS4ERR_INVAL. |
| 28228 |
|
| 28229 |
ssp_encr_algs: |
| 28230 |
|
| 28231 |
This is the set of algorithms the client supports for the purpose |
| 28232 |
of providing privacy protection for the internal SSV GSS |
| 28233 |
mechanism. Each algorithm is specified as an OID. The REQUIRED |
| 28234 |
algorithm for a server is id-aes256-CBC. The RECOMMENDED |
| 28235 |
algorithms are id-aes192-CBC and id-aes128-CBC [<a href="#ref-29" title=""Cryptographic Algorithm Object Registration"">29</a>]. The selected |
| 28236 |
algorithm is returned in spi_encr_alg, an index into |
| 28237 |
ssp_encr_algs. If the server does not support any of the offered |
| 28238 |
algorithms, it returns NFS4ERR_ENCR_ALG_UNSUPP. If ssp_encr_algs |
| 28239 |
is empty, the server MUST return NFS4ERR_INVAL. Note that due to |
| 28240 |
previously stated requirements and recommendations on the |
| 28241 |
relationships between key length and hash length, some |
| 28242 |
combinations of RECOMMENDED and REQUIRED encryption algorithm and |
| 28243 |
hash algorithm either SHOULD NOT or MUST NOT be used. Table 12 |
| 28244 |
summarizes the illegal and discouraged combinations. |
| 28245 |
|
| 28246 |
ssp_window: |
| 28247 |
|
| 28248 |
This is the number of SSV versions the client wants the server to |
| 28249 |
maintain (i.e., each successful call to SET_SSV produces a new |
| 28250 |
version of the SSV). If ssp_window is zero, the server MUST |
| 28251 |
return NFS4ERR_INVAL. The server responds with spi_window, which |
| 28252 |
MUST NOT exceed ssp_window, and MUST be at least one. Any |
| 28253 |
requests on the backchannel or fore channel that are using a |
| 28254 |
version of the SSV that is outside the window will fail with an |
| 28255 |
ONC RPC authentication error, and the requester will have to retry |
| 28256 |
them with the same slot ID and sequence ID. |
| 28257 |
|
| 28258 |
ssp_num_gss_handles: |
| 28259 |
|
| 28260 |
This is the number of RPCSEC_GSS handles the server should create |
| 28261 |
that are based on the GSS SSV mechanism (<a href="#section-2.10.9">Section 2.10.9</a>). It is |
| 28262 |
not the total number of RPCSEC_GSS handles for the client ID. |
| 28263 |
Indeed, subsequent calls to EXCHANGE_ID will add RPCSEC_GSS |
| 28264 |
handles. The server responds with a list of handles in |
| 28265 |
spi_handles. If the client asks for at least one handle and the |
| 28266 |
server cannot create it, the server MUST return an error. The |
| 28267 |
handles in spi_handles are not available for use until the client |
| 28268 |
ID is confirmed, which could be immediately if EXCHANGE_ID returns |
| 28269 |
EXCHGID4_FLAG_CONFIRMED_R, or upon successful confirmation from |
| 28270 |
CREATE_SESSION. |
| 28271 |
|
| 28272 |
|
| 28273 |
|
| 28274 |
|
| 28275 |
|
| 28276 |
<span class="grey">Shepler, et al. Standards Track [Page 505]</span></pre> |
| 28277 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-506" ></span> |
| 28278 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28279 |
|
| 28280 |
|
| 28281 |
While a client ID can span all the connections that are connected |
| 28282 |
to a server sharing the same eir_server_owner.so_major_id, the |
| 28283 |
RPCSEC_GSS handles returned in spi_handles can only be used on |
| 28284 |
connections connected to a server that returns the same the |
| 28285 |
eir_server_owner.so_major_id and eir_server_owner.so_minor_id on |
| 28286 |
each connection. It is permissible for the client to set |
| 28287 |
ssp_num_gss_handles to zero; the client can create more handles |
| 28288 |
with another EXCHANGE_ID call. |
| 28289 |
|
| 28290 |
Because each SSV RPCSEC_GSS handle shares a common SSV GSS |
| 28291 |
context, there are security considerations specific to this |
| 28292 |
situation discussed in <a href="#section-2.10.10">Section 2.10.10</a>. |
| 28293 |
|
| 28294 |
The seq_window (see <a href="./rfc2203#section-5.2.3.1">Section 5.2.3.1 of RFC2203</a> [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>]) of each |
| 28295 |
RPCSEC_GSS handle in spi_handle MUST be the same as the seq_window |
| 28296 |
of the RPCSEC_GSS handle used for the credential of the RPC |
| 28297 |
request that the EXCHANGE_ID request was sent with. |
| 28298 |
|
| 28299 |
+-------------------+----------------------+------------------------+ |
| 28300 |
| Encryption | MUST NOT be combined | SHOULD NOT be combined | |
| 28301 |
| Algorithm | with | with | |
| 28302 |
+-------------------+----------------------+------------------------+ |
| 28303 |
| id-aes128-CBC | | id-sha384, id-sha512 | |
| 28304 |
| id-aes192-CBC | id-sha1 | id-sha512 | |
| 28305 |
| id-aes256-CBC | id-sha1, id-sha224 | | |
| 28306 |
+-------------------+----------------------+------------------------+ |
| 28307 |
|
| 28308 |
Table 12 |
| 28309 |
|
| 28310 |
The arguments include an array of up to one element in length called |
| 28311 |
eia_client_impl_id. If eia_client_impl_id is present, it contains |
| 28312 |
the information identifying the implementation of the client. |
| 28313 |
Similarly, the results include an array of up to one element in |
| 28314 |
length called eir_server_impl_id that identifies the implementation |
| 28315 |
of the server. Servers MUST accept a zero-length eia_client_impl_id |
| 28316 |
array, and clients MUST accept a zero-length eir_server_impl_id |
| 28317 |
array. |
| 28318 |
|
| 28319 |
An example use for implementation identifiers would be diagnostic |
| 28320 |
software that extracts this information in an attempt to identify |
| 28321 |
interoperability problems, performance workload behaviors, or general |
| 28322 |
usage statistics. Since the intent of having access to this |
| 28323 |
information is for planning or general diagnosis only, the client and |
| 28324 |
server MUST NOT interpret this implementation identity information in |
| 28325 |
a way that affects interoperational behavior of the implementation. |
| 28326 |
The reason is that if clients and servers did such a thing, they |
| 28327 |
might use fewer capabilities of the protocol than the peer can |
| 28328 |
support, or the client and server might refuse to interoperate. |
| 28329 |
|
| 28330 |
|
| 28331 |
|
| 28332 |
<span class="grey">Shepler, et al. Standards Track [Page 506]</span></pre> |
| 28333 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-507" ></span> |
| 28334 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28335 |
|
| 28336 |
|
| 28337 |
Because it is possible that some implementations will violate the |
| 28338 |
protocol specification and interpret the identity information, |
| 28339 |
implementations MUST allow the users of the NFSv4 client and server |
| 28340 |
to set the contents of the sent nfs_impl_id structure to any value. |
| 28341 |
|
| 28342 |
<span class="h4"><a class="selflink" id="section-18.35.4" href="#section-18.35.4">18.35.4</a>. IMPLEMENTATION</span> |
| 28343 |
|
| 28344 |
A server's client record is a 5-tuple: |
| 28345 |
|
| 28346 |
1. co_ownerid |
| 28347 |
|
| 28348 |
The client identifier string, from the eia_clientowner |
| 28349 |
structure of the EXCHANGE_ID4args structure. |
| 28350 |
|
| 28351 |
2. co_verifier: |
| 28352 |
|
| 28353 |
A client-specific value used to indicate incarnations (where a |
| 28354 |
client restart represents a new incarnation), from the |
| 28355 |
eia_clientowner structure of the EXCHANGE_ID4args structure. |
| 28356 |
|
| 28357 |
3. principal: |
| 28358 |
|
| 28359 |
The principal that was defined in the RPC header's credential |
| 28360 |
and/or verifier at the time the client record was established. |
| 28361 |
|
| 28362 |
4. client ID: |
| 28363 |
|
| 28364 |
The shorthand client identifier, generated by the server and |
| 28365 |
returned via the eir_clientid field in the EXCHANGE_ID4resok |
| 28366 |
structure. |
| 28367 |
|
| 28368 |
5. confirmed: |
| 28369 |
|
| 28370 |
A private field on the server indicating whether or not a |
| 28371 |
client record has been confirmed. A client record is |
| 28372 |
confirmed if there has been a successful CREATE_SESSION |
| 28373 |
operation to confirm it. Otherwise, it is unconfirmed. An |
| 28374 |
unconfirmed record is established by an EXCHANGE_ID call. Any |
| 28375 |
unconfirmed record that is not confirmed within a lease period |
| 28376 |
SHOULD be removed. |
| 28377 |
|
| 28378 |
The following identifiers represent special values for the fields in |
| 28379 |
the records. |
| 28380 |
|
| 28381 |
ownerid_arg: |
| 28382 |
|
| 28383 |
The value of the eia_clientowner.co_ownerid subfield of the |
| 28384 |
EXCHANGE_ID4args structure of the current request. |
| 28385 |
|
| 28386 |
|
| 28387 |
|
| 28388 |
<span class="grey">Shepler, et al. Standards Track [Page 507]</span></pre> |
| 28389 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-508" ></span> |
| 28390 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28391 |
|
| 28392 |
|
| 28393 |
verifier_arg: |
| 28394 |
|
| 28395 |
The value of the eia_clientowner.co_verifier subfield of the |
| 28396 |
EXCHANGE_ID4args structure of the current request. |
| 28397 |
|
| 28398 |
old_verifier_arg: |
| 28399 |
|
| 28400 |
A value of the eia_clientowner.co_verifier field of a client |
| 28401 |
record received in a previous request; this is distinct from |
| 28402 |
verifier_arg. |
| 28403 |
|
| 28404 |
principal_arg: |
| 28405 |
|
| 28406 |
The value of the RPCSEC_GSS principal for the current request. |
| 28407 |
|
| 28408 |
old_principal_arg: |
| 28409 |
|
| 28410 |
A value of the principal of a client record as defined by the RPC |
| 28411 |
header's credential or verifier of a previous request. This is |
| 28412 |
distinct from principal_arg. |
| 28413 |
|
| 28414 |
clientid_ret: |
| 28415 |
|
| 28416 |
The value of the eir_clientid field the server will return in the |
| 28417 |
EXCHANGE_ID4resok structure for the current request. |
| 28418 |
|
| 28419 |
old_clientid_ret: |
| 28420 |
|
| 28421 |
The value of the eir_clientid field the server returned in the |
| 28422 |
EXCHANGE_ID4resok structure for a previous request. This is |
| 28423 |
distinct from clientid_ret. |
| 28424 |
|
| 28425 |
confirmed: |
| 28426 |
|
| 28427 |
The client ID has been confirmed. |
| 28428 |
|
| 28429 |
unconfirmed: |
| 28430 |
|
| 28431 |
The client ID has not been confirmed. |
| 28432 |
|
| 28433 |
Since EXCHANGE_ID is a non-idempotent operation, we must consider the |
| 28434 |
possibility that retries occur as a result of a client restart, |
| 28435 |
network partition, malfunctioning router, etc. Retries are |
| 28436 |
identified by the value of the eia_clientowner field of |
| 28437 |
EXCHANGE_ID4args, and the method for dealing with them is outlined in |
| 28438 |
the scenarios below. |
| 28439 |
|
| 28440 |
|
| 28441 |
|
| 28442 |
|
| 28443 |
|
| 28444 |
<span class="grey">Shepler, et al. Standards Track [Page 508]</span></pre> |
| 28445 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-509" ></span> |
| 28446 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28447 |
|
| 28448 |
|
| 28449 |
The scenarios are described in terms of the client record(s) a server |
| 28450 |
has for a given co_ownerid. Note that if the client ID was created |
| 28451 |
specifying SP4_SSV state protection and EXCHANGE_ID as the one of the |
| 28452 |
operations in spo_must_allow, then the server MUST authorize |
| 28453 |
EXCHANGE_IDs with the SSV principal in addition to the principal that |
| 28454 |
created the client ID. |
| 28455 |
|
| 28456 |
1. New Owner ID |
| 28457 |
|
| 28458 |
If the server has no client records with |
| 28459 |
eia_clientowner.co_ownerid matching ownerid_arg, and |
| 28460 |
EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set in the |
| 28461 |
EXCHANGE_ID, then a new shorthand client ID (let us call it |
| 28462 |
clientid_ret) is generated, and the following unconfirmed |
| 28463 |
record is added to the server's state. |
| 28464 |
|
| 28465 |
{ ownerid_arg, verifier_arg, principal_arg, clientid_ret, |
| 28466 |
unconfirmed } |
| 28467 |
|
| 28468 |
Subsequently, the server returns clientid_ret. |
| 28469 |
|
| 28470 |
2. Non-Update on Existing Client ID |
| 28471 |
|
| 28472 |
If the server has the following confirmed record, and the |
| 28473 |
request does not have EXCHGID4_FLAG_UPD_CONFIRMED_REC_A set, |
| 28474 |
then the request is the result of a retried request due to a |
| 28475 |
faulty router or lost connection, or the client is trying to |
| 28476 |
determine if it can perform trunking. |
| 28477 |
|
| 28478 |
{ ownerid_arg, verifier_arg, principal_arg, clientid_ret, |
| 28479 |
confirmed } |
| 28480 |
|
| 28481 |
Since the record has been confirmed, the client must have |
| 28482 |
received the server's reply from the initial EXCHANGE_ID |
| 28483 |
request. Since the server has a confirmed record, and since |
| 28484 |
EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set, with the |
| 28485 |
possible exception of eir_server_owner.so_minor_id, the server |
| 28486 |
returns the same result it did when the client ID's properties |
| 28487 |
were last updated (or if never updated, the result when the |
| 28488 |
client ID was created). The confirmed record is unchanged. |
| 28489 |
|
| 28490 |
3. Client Collision |
| 28491 |
|
| 28492 |
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set, and if the |
| 28493 |
server has the following confirmed record, then this request |
| 28494 |
is likely the result of a chance collision between the values |
| 28495 |
of the eia_clientowner.co_ownerid subfield of EXCHANGE_ID4args |
| 28496 |
for two different clients. |
| 28497 |
|
| 28498 |
|
| 28499 |
|
| 28500 |
<span class="grey">Shepler, et al. Standards Track [Page 509]</span></pre> |
| 28501 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-510" ></span> |
| 28502 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28503 |
|
| 28504 |
|
| 28505 |
{ ownerid_arg, *, old_principal_arg, old_clientid_ret, |
| 28506 |
confirmed } |
| 28507 |
|
| 28508 |
If there is currently no state associated with |
| 28509 |
old_clientid_ret, or if there is state but the lease has |
| 28510 |
expired, then this case is effectively equivalent to the New |
| 28511 |
Owner ID case of Paragraph 1. The confirmed record is |
| 28512 |
deleted, the old_clientid_ret and its lock state are deleted, |
| 28513 |
a new shorthand client ID is generated, and the following |
| 28514 |
unconfirmed record is added to the server's state. |
| 28515 |
|
| 28516 |
{ ownerid_arg, verifier_arg, principal_arg, clientid_ret, |
| 28517 |
unconfirmed } |
| 28518 |
|
| 28519 |
Subsequently, the server returns clientid_ret. |
| 28520 |
|
| 28521 |
If old_clientid_ret has an unexpired lease with state, then no |
| 28522 |
state of old_clientid_ret is changed or deleted. The server |
| 28523 |
returns NFS4ERR_CLID_INUSE to indicate that the client should |
| 28524 |
retry with a different value for the |
| 28525 |
eia_clientowner.co_ownerid subfield of EXCHANGE_ID4args. The |
| 28526 |
client record is not changed. |
| 28527 |
|
| 28528 |
4. Replacement of Unconfirmed Record |
| 28529 |
|
| 28530 |
If the EXCHGID4_FLAG_UPD_CONFIRMED_REC_A flag is not set, and |
| 28531 |
the server has the following unconfirmed record, then the |
| 28532 |
client is attempting EXCHANGE_ID again on an unconfirmed |
| 28533 |
client ID, perhaps due to a retry, a client restart before |
| 28534 |
client ID confirmation (i.e., before CREATE_SESSION was |
| 28535 |
called), or some other reason. |
| 28536 |
|
| 28537 |
{ ownerid_arg, *, *, old_clientid_ret, unconfirmed } |
| 28538 |
|
| 28539 |
It is possible that the properties of old_clientid_ret are |
| 28540 |
different than those specified in the current EXCHANGE_ID. |
| 28541 |
Whether or not the properties are being updated, to eliminate |
| 28542 |
ambiguity, the server deletes the unconfirmed record, |
| 28543 |
generates a new client ID (clientid_ret), and establishes the |
| 28544 |
following unconfirmed record: |
| 28545 |
|
| 28546 |
{ ownerid_arg, verifier_arg, principal_arg, clientid_ret, |
| 28547 |
unconfirmed } |
| 28548 |
|
| 28549 |
|
| 28550 |
|
| 28551 |
|
| 28552 |
|
| 28553 |
|
| 28554 |
|
| 28555 |
|
| 28556 |
<span class="grey">Shepler, et al. Standards Track [Page 510]</span></pre> |
| 28557 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-511" ></span> |
| 28558 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28559 |
|
| 28560 |
|
| 28561 |
5. Client Restart |
| 28562 |
|
| 28563 |
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set, and if the |
| 28564 |
server has the following confirmed client record, then this |
| 28565 |
request is likely from a previously confirmed client that has |
| 28566 |
restarted. |
| 28567 |
|
| 28568 |
{ ownerid_arg, old_verifier_arg, principal_arg, |
| 28569 |
old_clientid_ret, confirmed } |
| 28570 |
|
| 28571 |
Since the previous incarnation of the same client will no |
| 28572 |
longer be making requests, once the new client ID is confirmed |
| 28573 |
by CREATE_SESSION, byte-range locks and share reservations |
| 28574 |
should be released immediately rather than forcing the new |
| 28575 |
incarnation to wait for the lease time on the previous |
| 28576 |
incarnation to expire. Furthermore, session state should be |
| 28577 |
removed since if the client had maintained that information |
| 28578 |
across restart, this request would not have been sent. If the |
| 28579 |
server supports neither the CLAIM_DELEGATE_PREV nor |
| 28580 |
CLAIM_DELEG_PREV_FH claim types, associated delegations should |
| 28581 |
be purged as well; otherwise, delegations are retained and |
| 28582 |
recovery proceeds according to <a href="#section-10.2.1">Section 10.2.1</a>. |
| 28583 |
|
| 28584 |
After processing, clientid_ret is returned to the client and |
| 28585 |
this client record is added: |
| 28586 |
|
| 28587 |
{ ownerid_arg, verifier_arg, principal_arg, clientid_ret, |
| 28588 |
unconfirmed } |
| 28589 |
|
| 28590 |
The previously described confirmed record continues to exist, |
| 28591 |
and thus the same ownerid_arg exists in both a confirmed and |
| 28592 |
unconfirmed state at the same time. The number of states can |
| 28593 |
collapse to one once the server receives an applicable |
| 28594 |
CREATE_SESSION or EXCHANGE_ID. |
| 28595 |
|
| 28596 |
+ If the server subsequently receives a successful |
| 28597 |
CREATE_SESSION that confirms clientid_ret, then the server |
| 28598 |
atomically destroys the confirmed record and makes the |
| 28599 |
unconfirmed record confirmed as described in |
| 28600 |
<a href="#section-18.36.4">Section 18.36.4</a>. |
| 28601 |
|
| 28602 |
+ If the server instead subsequently receives an EXCHANGE_ID |
| 28603 |
with the client owner equal to ownerid_arg, one strategy is |
| 28604 |
to simply delete the unconfirmed record, and process the |
| 28605 |
EXCHANGE_ID as described in the entirety of |
| 28606 |
<a href="#section-18.35.4">Section 18.35.4</a>. |
| 28607 |
|
| 28608 |
|
| 28609 |
|
| 28610 |
|
| 28611 |
|
| 28612 |
<span class="grey">Shepler, et al. Standards Track [Page 511]</span></pre> |
| 28613 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-512" ></span> |
| 28614 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28615 |
|
| 28616 |
|
| 28617 |
6. Update |
| 28618 |
|
| 28619 |
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set, and the server |
| 28620 |
has the following confirmed record, then this request is an |
| 28621 |
attempt at an update. |
| 28622 |
|
| 28623 |
{ ownerid_arg, verifier_arg, principal_arg, clientid_ret, |
| 28624 |
confirmed } |
| 28625 |
|
| 28626 |
Since the record has been confirmed, the client must have |
| 28627 |
received the server's reply from the initial EXCHANGE_ID |
| 28628 |
request. The server allows the update, and the client record |
| 28629 |
is left intact. |
| 28630 |
|
| 28631 |
7. Update but No Confirmed Record |
| 28632 |
|
| 28633 |
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set, and the server |
| 28634 |
has no confirmed record corresponding ownerid_arg, then the |
| 28635 |
server returns NFS4ERR_NOENT and leaves any unconfirmed record |
| 28636 |
intact. |
| 28637 |
|
| 28638 |
8. Update but Wrong Verifier |
| 28639 |
|
| 28640 |
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set, and the server |
| 28641 |
has the following confirmed record, then this request is an |
| 28642 |
illegal attempt at an update, perhaps because of a retry from |
| 28643 |
a previous client incarnation. |
| 28644 |
|
| 28645 |
{ ownerid_arg, old_verifier_arg, *, clientid_ret, confirmed } |
| 28646 |
|
| 28647 |
The server returns NFS4ERR_NOT_SAME and leaves the client |
| 28648 |
record intact. |
| 28649 |
|
| 28650 |
9. Update but Wrong Principal |
| 28651 |
|
| 28652 |
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set, and the server |
| 28653 |
has the following confirmed record, then this request is an |
| 28654 |
illegal attempt at an update by an unauthorized principal. |
| 28655 |
|
| 28656 |
{ ownerid_arg, verifier_arg, old_principal_arg, clientid_ret, |
| 28657 |
confirmed } |
| 28658 |
|
| 28659 |
The server returns NFS4ERR_PERM and leaves the client record |
| 28660 |
intact. |
| 28661 |
|
| 28662 |
|
| 28663 |
|
| 28664 |
|
| 28665 |
|
| 28666 |
|
| 28667 |
|
| 28668 |
<span class="grey">Shepler, et al. Standards Track [Page 512]</span></pre> |
| 28669 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-513" ></span> |
| 28670 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28671 |
|
| 28672 |
|
| 28673 |
<span class="h3"><a class="selflink" id="section-18.36" href="#section-18.36">18.36</a>. Operation 43: CREATE_SESSION - Create New Session and Confirm</span> |
| 28674 |
<span class="h3"> Client ID</span> |
| 28675 |
|
| 28676 |
<span class="h4"><a class="selflink" id="section-18.36.1" href="#section-18.36.1">18.36.1</a>. ARGUMENT</span> |
| 28677 |
|
| 28678 |
struct channel_attrs4 { |
| 28679 |
count4 ca_headerpadsize; |
| 28680 |
count4 ca_maxrequestsize; |
| 28681 |
count4 ca_maxresponsesize; |
| 28682 |
count4 ca_maxresponsesize_cached; |
| 28683 |
count4 ca_maxoperations; |
| 28684 |
count4 ca_maxrequests; |
| 28685 |
uint32_t ca_rdma_ird<1>; |
| 28686 |
}; |
| 28687 |
|
| 28688 |
const CREATE_SESSION4_FLAG_PERSIST = 0x00000001; |
| 28689 |
const CREATE_SESSION4_FLAG_CONN_BACK_CHAN = 0x00000002; |
| 28690 |
const CREATE_SESSION4_FLAG_CONN_RDMA = 0x00000004; |
| 28691 |
|
| 28692 |
struct CREATE_SESSION4args { |
| 28693 |
clientid4 csa_clientid; |
| 28694 |
sequenceid4 csa_sequence; |
| 28695 |
|
| 28696 |
uint32_t csa_flags; |
| 28697 |
|
| 28698 |
channel_attrs4 csa_fore_chan_attrs; |
| 28699 |
channel_attrs4 csa_back_chan_attrs; |
| 28700 |
|
| 28701 |
uint32_t csa_cb_program; |
| 28702 |
callback_sec_parms4 csa_sec_parms<>; |
| 28703 |
}; |
| 28704 |
|
| 28705 |
<span class="h4"><a class="selflink" id="section-18.36.2" href="#section-18.36.2">18.36.2</a>. RESULT</span> |
| 28706 |
|
| 28707 |
struct CREATE_SESSION4resok { |
| 28708 |
sessionid4 csr_sessionid; |
| 28709 |
sequenceid4 csr_sequence; |
| 28710 |
|
| 28711 |
uint32_t csr_flags; |
| 28712 |
|
| 28713 |
channel_attrs4 csr_fore_chan_attrs; |
| 28714 |
channel_attrs4 csr_back_chan_attrs; |
| 28715 |
}; |
| 28716 |
|
| 28717 |
|
| 28718 |
|
| 28719 |
|
| 28720 |
|
| 28721 |
|
| 28722 |
|
| 28723 |
|
| 28724 |
<span class="grey">Shepler, et al. Standards Track [Page 513]</span></pre> |
| 28725 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-514" ></span> |
| 28726 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28727 |
|
| 28728 |
|
| 28729 |
union CREATE_SESSION4res switch (nfsstat4 csr_status) { |
| 28730 |
case NFS4_OK: |
| 28731 |
CREATE_SESSION4resok csr_resok4; |
| 28732 |
default: |
| 28733 |
void; |
| 28734 |
}; |
| 28735 |
|
| 28736 |
<span class="h4"><a class="selflink" id="section-18.36.3" href="#section-18.36.3">18.36.3</a>. DESCRIPTION</span> |
| 28737 |
|
| 28738 |
This operation is used by the client to create new session objects on |
| 28739 |
the server. |
| 28740 |
|
| 28741 |
CREATE_SESSION can be sent with or without a preceding SEQUENCE |
| 28742 |
operation in the same COMPOUND procedure. If CREATE_SESSION is sent |
| 28743 |
with a preceding SEQUENCE operation, any session created by |
| 28744 |
CREATE_SESSION has no direct relation to the session specified in the |
| 28745 |
SEQUENCE operation, although the two sessions might be associated |
| 28746 |
with the same client ID. If CREATE_SESSION is sent without a |
| 28747 |
preceding SEQUENCE, then it MUST be the only operation in the |
| 28748 |
COMPOUND procedure's request. If it is not, the server MUST return |
| 28749 |
NFS4ERR_NOT_ONLY_OP. |
| 28750 |
|
| 28751 |
In addition to creating a session, CREATE_SESSION has the following |
| 28752 |
effects: |
| 28753 |
|
| 28754 |
o The first session created with a new client ID serves to confirm |
| 28755 |
the creation of that client's state on the server. The server |
| 28756 |
returns the parameter values for the new session. |
| 28757 |
|
| 28758 |
o The connection CREATE_SESSION that is sent over is associated with |
| 28759 |
the session's fore channel. |
| 28760 |
|
| 28761 |
The arguments and results of CREATE_SESSION are described as follows: |
| 28762 |
|
| 28763 |
csa_clientid: |
| 28764 |
|
| 28765 |
This is the client ID with which the new session will be |
| 28766 |
associated. The corresponding result is csr_sessionid, the |
| 28767 |
session ID of the new session. |
| 28768 |
|
| 28769 |
csa_sequence: |
| 28770 |
|
| 28771 |
Each client ID serializes CREATE_SESSION via a per-client ID |
| 28772 |
sequence number (see <a href="#section-18.36.4">Section 18.36.4</a>). The corresponding result |
| 28773 |
is csr_sequence, which MUST be equal to csa_sequence. |
| 28774 |
|
| 28775 |
|
| 28776 |
|
| 28777 |
|
| 28778 |
|
| 28779 |
|
| 28780 |
<span class="grey">Shepler, et al. Standards Track [Page 514]</span></pre> |
| 28781 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-515" ></span> |
| 28782 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28783 |
|
| 28784 |
|
| 28785 |
In the next three arguments, the client offers a value that is to be |
| 28786 |
a property of the session. Except where stated otherwise, it is |
| 28787 |
RECOMMENDED that the server accept the value. If it is not |
| 28788 |
acceptable, the server MAY use a different value. Regardless, the |
| 28789 |
server MUST return the value the session will use (which will be |
| 28790 |
either what the client offered, or what the server is insisting on) |
| 28791 |
to the client. |
| 28792 |
|
| 28793 |
csa_flags: |
| 28794 |
|
| 28795 |
The csa_flags field contains a list of the following flag bits: |
| 28796 |
|
| 28797 |
CREATE_SESSION4_FLAG_PERSIST: |
| 28798 |
|
| 28799 |
If CREATE_SESSION4_FLAG_PERSIST is set, the client wants the |
| 28800 |
server to provide a persistent reply cache. For sessions in |
| 28801 |
which only idempotent operations will be used (e.g., a read- |
| 28802 |
only session), clients SHOULD NOT set |
| 28803 |
CREATE_SESSION4_FLAG_PERSIST. If the server does not or cannot |
| 28804 |
provide a persistent reply cache, the server MUST NOT set |
| 28805 |
CREATE_SESSION4_FLAG_PERSIST in the field csr_flags. |
| 28806 |
|
| 28807 |
If the server is a pNFS metadata server, for reasons described |
| 28808 |
in <a href="#section-12.5.2">Section 12.5.2</a> it SHOULD support |
| 28809 |
CREATE_SESSION4_FLAG_PERSIST if it supports the layout_hint |
| 28810 |
(<a href="#section-5.12.4">Section 5.12.4</a>) attribute. |
| 28811 |
|
| 28812 |
CREATE_SESSION4_FLAG_CONN_BACK_CHAN: |
| 28813 |
|
| 28814 |
If CREATE_SESSION4_FLAG_CONN_BACK_CHAN is set in csa_flags, the |
| 28815 |
client is requesting that the connection over which the |
| 28816 |
CREATE_SESSION operation arrived be associated with the |
| 28817 |
session's backchannel in addition to its fore channel. If the |
| 28818 |
server agrees, it sets CREATE_SESSION4_FLAG_CONN_BACK_CHAN in |
| 28819 |
the result field csr_flags. If |
| 28820 |
CREATE_SESSION4_FLAG_CONN_BACK_CHAN is not set in csa_flags, |
| 28821 |
then CREATE_SESSION4_FLAG_CONN_BACK_CHAN MUST NOT be set in |
| 28822 |
csr_flags. |
| 28823 |
|
| 28824 |
CREATE_SESSION4_FLAG_CONN_RDMA: |
| 28825 |
|
| 28826 |
If CREATE_SESSION4_FLAG_CONN_RDMA is set in csa_flags, and if |
| 28827 |
the connection over which the CREATE_SESSION operation arrived |
| 28828 |
is currently in non-RDMA mode but has the capability to operate |
| 28829 |
in RDMA mode, then the client is requesting that the server |
| 28830 |
"step up" to RDMA mode on the connection. If the server |
| 28831 |
agrees, it sets CREATE_SESSION4_FLAG_CONN_RDMA in the result |
| 28832 |
field csr_flags. If CREATE_SESSION4_FLAG_CONN_RDMA is not set |
| 28833 |
|
| 28834 |
|
| 28835 |
|
| 28836 |
<span class="grey">Shepler, et al. Standards Track [Page 515]</span></pre> |
| 28837 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-516" ></span> |
| 28838 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28839 |
|
| 28840 |
|
| 28841 |
in csa_flags, then CREATE_SESSION4_FLAG_CONN_RDMA MUST NOT be |
| 28842 |
set in csr_flags. Note that once the server agrees to step up, |
| 28843 |
it and the client MUST exchange all future traffic on the |
| 28844 |
connection with RPC RDMA framing and not Record Marking ([<a href="#ref-8" title=""Remote Direct Memory Access Transport for Remote Procedure Call"">8</a>]). |
| 28845 |
|
| 28846 |
csa_fore_chan_attrs, csa_fore_chan_attrs: |
| 28847 |
|
| 28848 |
The csa_fore_chan_attrs and csa_back_chan_attrs fields apply to |
| 28849 |
attributes of the fore channel (which conveys requests originating |
| 28850 |
from the client to the server), and the backchannel (the channel |
| 28851 |
that conveys callback requests originating from the server to the |
| 28852 |
client), respectively. The results are in corresponding |
| 28853 |
structures called csr_fore_chan_attrs and csr_back_chan_attrs. |
| 28854 |
The results establish attributes for each channel, and on all |
| 28855 |
subsequent use of each channel of the session. Each structure has |
| 28856 |
the following fields: |
| 28857 |
|
| 28858 |
ca_headerpadsize: |
| 28859 |
|
| 28860 |
The maximum amount of padding the requester is willing to apply |
| 28861 |
to ensure that write payloads are aligned on some boundary at |
| 28862 |
the replier. For each channel, the server |
| 28863 |
|
| 28864 |
+ will reply in ca_headerpadsize with its preferred value, or |
| 28865 |
zero if padding is not in use, and |
| 28866 |
|
| 28867 |
+ MAY decrease this value but MUST NOT increase it. |
| 28868 |
|
| 28869 |
ca_maxrequestsize: |
| 28870 |
|
| 28871 |
The maximum size of a COMPOUND or CB_COMPOUND request that will |
| 28872 |
be sent. This size represents the XDR encoded size of the |
| 28873 |
request, including the RPC headers (including security flavor |
| 28874 |
credentials and verifiers) but excludes any RPC transport |
| 28875 |
framing headers. Imagine a request coming over a non-RDMA |
| 28876 |
TCP/IP connection, and that it has a single Record Marking |
| 28877 |
header preceding it. The maximum allowable count encoded in |
| 28878 |
the header will be ca_maxrequestsize. If a requester sends a |
| 28879 |
request that exceeds ca_maxrequestsize, the error |
| 28880 |
NFS4ERR_REQ_TOO_BIG will be returned per the description in |
| 28881 |
<a href="#section-2.10.6.4">Section 2.10.6.4</a>. For each channel, the server MAY decrease |
| 28882 |
this value but MUST NOT increase it. |
| 28883 |
|
| 28884 |
ca_maxresponsesize: |
| 28885 |
|
| 28886 |
The maximum size of a COMPOUND or CB_COMPOUND reply that the |
| 28887 |
requester will accept from the replier including RPC headers |
| 28888 |
(see the ca_maxrequestsize definition). For each channel, the |
| 28889 |
|
| 28890 |
|
| 28891 |
|
| 28892 |
<span class="grey">Shepler, et al. Standards Track [Page 516]</span></pre> |
| 28893 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-517" ></span> |
| 28894 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28895 |
|
| 28896 |
|
| 28897 |
server MAY decrease this value, but MUST NOT increase it. |
| 28898 |
However, if the client selects a value for ca_maxresponsesize |
| 28899 |
such that a replier on a channel could never send a response, |
| 28900 |
the server SHOULD return NFS4ERR_TOOSMALL in the CREATE_SESSION |
| 28901 |
reply. After the session is created, if a requester sends a |
| 28902 |
request for which the size of the reply would exceed this |
| 28903 |
value, the replier will return NFS4ERR_REP_TOO_BIG, per the |
| 28904 |
description in <a href="#section-2.10.6.4">Section 2.10.6.4</a>. |
| 28905 |
|
| 28906 |
ca_maxresponsesize_cached: |
| 28907 |
|
| 28908 |
Like ca_maxresponsesize, but the maximum size of a reply that |
| 28909 |
will be stored in the reply cache (<a href="#section-2.10.6.1">Section 2.10.6.1</a>). For each |
| 28910 |
channel, the server MAY decrease this value, but MUST NOT |
| 28911 |
increase it. If, in the reply to CREATE_SESSION, the value of |
| 28912 |
ca_maxresponsesize_cached of a channel is less than the value |
| 28913 |
of ca_maxresponsesize of the same channel, then this is an |
| 28914 |
indication to the requester that it needs to be selective about |
| 28915 |
which replies it directs the replier to cache; for example, |
| 28916 |
large replies from nonidempotent operations (e.g., COMPOUND |
| 28917 |
requests with a READ operation) should not be cached. The |
| 28918 |
requester decides which replies to cache via an argument to the |
| 28919 |
SEQUENCE (the sa_cachethis field, see <a href="#section-18.46">Section 18.46</a>) or |
| 28920 |
CB_SEQUENCE (the csa_cachethis field, see <a href="#section-20.9">Section 20.9</a>) |
| 28921 |
operations. After the session is created, if a requester sends |
| 28922 |
a request for which the size of the reply would exceed |
| 28923 |
ca_maxresponsesize_cached, the replier will return |
| 28924 |
NFS4ERR_REP_TOO_BIG_TO_CACHE, per the description in |
| 28925 |
<a href="#section-2.10.6.4">Section 2.10.6.4</a>. |
| 28926 |
|
| 28927 |
ca_maxoperations: |
| 28928 |
|
| 28929 |
The maximum number of operations the replier will accept in a |
| 28930 |
COMPOUND or CB_COMPOUND. For the backchannel, the server MUST |
| 28931 |
NOT change the value the client offers. For the fore channel, |
| 28932 |
the server MAY change the requested value. After the session |
| 28933 |
is created, if a requester sends a COMPOUND or CB_COMPOUND with |
| 28934 |
more operations than ca_maxoperations, the replier MUST return |
| 28935 |
NFS4ERR_TOO_MANY_OPS. |
| 28936 |
|
| 28937 |
ca_maxrequests: |
| 28938 |
|
| 28939 |
The maximum number of concurrent COMPOUND or CB_COMPOUND |
| 28940 |
requests the requester will send on the session. Subsequent |
| 28941 |
requests will each be assigned a slot identifier by the |
| 28942 |
requester within the range zero to ca_maxrequests - 1 |
| 28943 |
|
| 28944 |
|
| 28945 |
|
| 28946 |
|
| 28947 |
|
| 28948 |
<span class="grey">Shepler, et al. Standards Track [Page 517]</span></pre> |
| 28949 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-518" ></span> |
| 28950 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 28951 |
|
| 28952 |
|
| 28953 |
inclusive. For the backchannel, the server MUST NOT change the |
| 28954 |
value the client offers. For the fore channel, the server MAY |
| 28955 |
change the requested value. |
| 28956 |
|
| 28957 |
ca_rdma_ird: |
| 28958 |
|
| 28959 |
This array has a maximum of one element. If this array has one |
| 28960 |
element, then the element contains the inbound RDMA read queue |
| 28961 |
depth (IRD). For each channel, the server MAY decrease this |
| 28962 |
value, but MUST NOT increase it. |
| 28963 |
|
| 28964 |
csa_cb_program |
| 28965 |
|
| 28966 |
This is the ONC RPC program number the server MUST use in any |
| 28967 |
callbacks sent through the backchannel to the client. The server |
| 28968 |
MUST specify an ONC RPC program number equal to csa_cb_program and |
| 28969 |
an ONC RPC version number equal to 4 in callbacks sent to the |
| 28970 |
client. If a CB_COMPOUND is sent to the client, the server MUST |
| 28971 |
use a minor version number of 1. There is no corresponding |
| 28972 |
result. |
| 28973 |
|
| 28974 |
csa_sec_parms |
| 28975 |
|
| 28976 |
The field csa_sec_parms is an array of acceptable security |
| 28977 |
credentials the server can use on the session's backchannel. |
| 28978 |
Three security flavors are supported: AUTH_NONE, AUTH_SYS, and |
| 28979 |
RPCSEC_GSS. If AUTH_NONE is specified for a credential, then this |
| 28980 |
says the client is authorizing the server to use AUTH_NONE on all |
| 28981 |
callbacks for the session. If AUTH_SYS is specified, then the |
| 28982 |
client is authorizing the server to use AUTH_SYS on all callbacks, |
| 28983 |
using the credential specified cbsp_sys_cred. If RPCSEC_GSS is |
| 28984 |
specified, then the server is allowed to use the RPCSEC_GSS |
| 28985 |
context specified in cbsp_gss_parms as the RPCSEC_GSS context in |
| 28986 |
the credential of the RPC header of callbacks to the client. |
| 28987 |
There is no corresponding result. |
| 28988 |
|
| 28989 |
The RPCSEC_GSS context for the backchannel is specified via a pair |
| 28990 |
of values of data type gsshandle4_t. The data type gsshandle4_t |
| 28991 |
represents an RPCSEC_GSS handle, and is precisely the same as the |
| 28992 |
data type of the "handle" field of the rpc_gss_init_res data type |
| 28993 |
defined in <a href="#section-5.2.3.1">Section 5.2.3.1</a>, "Context Creation Response - |
| 28994 |
Successful Acceptance", of [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>]. |
| 28995 |
|
| 28996 |
The first RPCSEC_GSS handle, gcbp_handle_from_server, is the fore |
| 28997 |
handle the server returned to the client (either in the handle |
| 28998 |
field of data type rpc_gss_init_res or as one of the elements of |
| 28999 |
the spi_handles field returned in the reply to EXCHANGE_ID) when |
| 29000 |
the RPCSEC_GSS context was created on the server. The second |
| 29001 |
|
| 29002 |
|
| 29003 |
|
| 29004 |
<span class="grey">Shepler, et al. Standards Track [Page 518]</span></pre> |
| 29005 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-519" ></span> |
| 29006 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29007 |
|
| 29008 |
|
| 29009 |
handle, gcbp_handle_from_client, is the back handle to which the |
| 29010 |
client will map the RPCSEC_GSS context. The server can |
| 29011 |
immediately use the value of gcbp_handle_from_client in the |
| 29012 |
RPCSEC_GSS credential in callback RPCs. That is, the value in |
| 29013 |
gcbp_handle_from_client can be used as the value of the field |
| 29014 |
"handle" in data type rpc_gss_cred_t (see <a href="#section-5">Section 5</a>, "Elements of |
| 29015 |
the RPCSEC_GSS Security Protocol", of [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>]) in callback RPCs. The |
| 29016 |
server MUST use the RPCSEC_GSS security service specified in |
| 29017 |
gcbp_service, i.e., it MUST set the "service" field of the |
| 29018 |
rpc_gss_cred_t data type in RPCSEC_GSS credential to the value of |
| 29019 |
gcbp_service (see <a href="#section-5.3.1">Section 5.3.1</a>, "RPC Request Header", of [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>]). |
| 29020 |
|
| 29021 |
If the RPCSEC_GSS handle identified by gcbp_handle_from_server |
| 29022 |
does not exist on the server, the server will return |
| 29023 |
NFS4ERR_NOENT. |
| 29024 |
|
| 29025 |
Within each element of csa_sec_parms, the fore and back RPCSEC_GSS |
| 29026 |
contexts MUST share the same GSS context and MUST have the same |
| 29027 |
seq_window (see <a href="./rfc2203#section-5.2.3.1">Section 5.2.3.1 of RFC2203</a> [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>]). The fore and |
| 29028 |
back RPCSEC_GSS context state are independent of each other as far |
| 29029 |
as the RPCSEC_GSS sequence number (see the seq_num field in the |
| 29030 |
rpc_gss_cred_t data type of Sections <a href="#section-5">5</a> and <a href="#section-5.3.1">5.3.1</a> of [<a href="#ref-4" title=""RPCSEC_GSS Protocol Specification"">4</a>]). |
| 29031 |
|
| 29032 |
If an RPCSEC_GSS handle is using the SSV context (see |
| 29033 |
<a href="#section-2.10.9">Section 2.10.9</a>), then because each SSV RPCSEC_GSS handle shares a |
| 29034 |
common SSV GSS context, there are security considerations specific |
| 29035 |
to this situation discussed in <a href="#section-2.10.10">Section 2.10.10</a>. |
| 29036 |
|
| 29037 |
Once the session is created, the first SEQUENCE or CB_SEQUENCE |
| 29038 |
received on a slot MUST have a sequence ID equal to 1; if not, the |
| 29039 |
replier MUST return NFS4ERR_SEQ_MISORDERED. |
| 29040 |
|
| 29041 |
<span class="h4"><a class="selflink" id="section-18.36.4" href="#section-18.36.4">18.36.4</a>. IMPLEMENTATION</span> |
| 29042 |
|
| 29043 |
To describe a possible implementation, the same notation for client |
| 29044 |
records introduced in the description of EXCHANGE_ID is used with the |
| 29045 |
following addition: |
| 29046 |
|
| 29047 |
clientid_arg: The value of the csa_clientid field of the |
| 29048 |
CREATE_SESSION4args structure of the current request. |
| 29049 |
|
| 29050 |
Since CREATE_SESSION is a non-idempotent operation, we need to |
| 29051 |
consider the possibility that retries may occur as a result of a |
| 29052 |
client restart, network partition, malfunctioning router, etc. For |
| 29053 |
each client ID created by EXCHANGE_ID, the server maintains a |
| 29054 |
separate reply cache (called the CREATE_SESSION reply cache) similar |
| 29055 |
to the session reply cache used for SEQUENCE operations, with two |
| 29056 |
distinctions. |
| 29057 |
|
| 29058 |
|
| 29059 |
|
| 29060 |
<span class="grey">Shepler, et al. Standards Track [Page 519]</span></pre> |
| 29061 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-520" ></span> |
| 29062 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29063 |
|
| 29064 |
|
| 29065 |
o First, this is a reply cache just for detecting and processing |
| 29066 |
CREATE_SESSION requests for a given client ID. |
| 29067 |
|
| 29068 |
o Second, the size of the client ID reply cache is of one slot (and |
| 29069 |
as a result, the CREATE_SESSION request does not carry a slot |
| 29070 |
number). This means that at most one CREATE_SESSION request for a |
| 29071 |
given client ID can be outstanding. |
| 29072 |
|
| 29073 |
As previously stated, CREATE_SESSION can be sent with or without a |
| 29074 |
preceding SEQUENCE operation. Even if a SEQUENCE precedes |
| 29075 |
CREATE_SESSION, the server MUST maintain the CREATE_SESSION reply |
| 29076 |
cache, which is separate from the reply cache for the session |
| 29077 |
associated with a SEQUENCE. If CREATE_SESSION was originally sent by |
| 29078 |
itself, the client MAY send a retry of the CREATE_SESSION operation |
| 29079 |
within a COMPOUND preceded by a SEQUENCE. If CREATE_SESSION was |
| 29080 |
originally sent in a COMPOUND that started with a SEQUENCE, then the |
| 29081 |
client SHOULD send a retry in a COMPOUND that starts with a SEQUENCE |
| 29082 |
that has the same session ID as the SEQUENCE of the original request. |
| 29083 |
However, the client MAY send a retry in a COMPOUND that either has no |
| 29084 |
preceding SEQUENCE, or has a preceding SEQUENCE that refers to a |
| 29085 |
different session than the original CREATE_SESSION. This might be |
| 29086 |
necessary if the client sends a CREATE_SESSION in a COMPOUND preceded |
| 29087 |
by a SEQUENCE with session ID X, and session X no longer exists. |
| 29088 |
Regardless, any retry of CREATE_SESSION, with or without a preceding |
| 29089 |
SEQUENCE, MUST use the same value of csa_sequence as the original. |
| 29090 |
|
| 29091 |
After the client received a reply to an EXCHANGE_ID operation that |
| 29092 |
contains a new, unconfirmed client ID, the server expects the client |
| 29093 |
to follow with a CREATE_SESSION operation to confirm the client ID. |
| 29094 |
The server expects value of csa_sequenceid in the arguments to that |
| 29095 |
CREATE_SESSION to be to equal the value of the field eir_sequenceid |
| 29096 |
that was returned in results of the EXCHANGE_ID that returned the |
| 29097 |
unconfirmed client ID. Before the server replies to that EXCHANGE_ID |
| 29098 |
operation, it initializes the client ID slot to be equal to |
| 29099 |
eir_sequenceid - 1 (accounting for underflow), and records a |
| 29100 |
contrived CREATE_SESSION result with a "cached" result of |
| 29101 |
NFS4ERR_SEQ_MISORDERED. With the client ID slot thus initialized, |
| 29102 |
the processing of the CREATE_SESSION operation is divided into four |
| 29103 |
phases: |
| 29104 |
|
| 29105 |
1. Client record look up. The server looks up the client ID in its |
| 29106 |
client record table. If the server contains no records with |
| 29107 |
client ID equal to clientid_arg, then most likely the client's |
| 29108 |
state has been purged during a period of inactivity, possibly due |
| 29109 |
to a loss of connectivity. NFS4ERR_STALE_CLIENTID is returned, |
| 29110 |
and no changes are made to any client records on the server. |
| 29111 |
Otherwise, the server goes to phase 2. |
| 29112 |
|
| 29113 |
|
| 29114 |
|
| 29115 |
|
| 29116 |
<span class="grey">Shepler, et al. Standards Track [Page 520]</span></pre> |
| 29117 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-521" ></span> |
| 29118 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29119 |
|
| 29120 |
|
| 29121 |
2. Sequence ID processing. If csa_sequenceid is equal to the |
| 29122 |
sequence ID in the client ID's slot, then this is a replay of the |
| 29123 |
previous CREATE_SESSION request, and the server returns the |
| 29124 |
cached result. If csa_sequenceid is not equal to the sequence ID |
| 29125 |
in the slot, and is more than one greater (accounting for |
| 29126 |
wraparound), then the server returns the error |
| 29127 |
NFS4ERR_SEQ_MISORDERED, and does not change the slot. If |
| 29128 |
csa_sequenceid is equal to the slot's sequence ID + 1 (accounting |
| 29129 |
for wraparound), then the slot's sequence ID is set to |
| 29130 |
csa_sequenceid, and the CREATE_SESSION processing goes to the |
| 29131 |
next phase. A subsequent new CREATE_SESSION call over the same |
| 29132 |
client ID MUST use a csa_sequenceid that is one greater than the |
| 29133 |
sequence ID in the slot. |
| 29134 |
|
| 29135 |
3. Client ID confirmation. If this would be the first session for |
| 29136 |
the client ID, the CREATE_SESSION operation serves to confirm the |
| 29137 |
client ID. Otherwise, the client ID confirmation phase is |
| 29138 |
skipped and only the session creation phase occurs. Any case in |
| 29139 |
which there is more than one record with identical values for |
| 29140 |
client ID represents a server implementation error. Operation in |
| 29141 |
the potential valid cases is summarized as follows. |
| 29142 |
|
| 29143 |
* Successful Confirmation |
| 29144 |
|
| 29145 |
If the server has the following unconfirmed record, then |
| 29146 |
this is the expected confirmation of an unconfirmed record. |
| 29147 |
|
| 29148 |
{ ownerid, verifier, principal_arg, clientid_arg, |
| 29149 |
unconfirmed } |
| 29150 |
|
| 29151 |
As noted in <a href="#section-18.35.4">Section 18.35.4</a>, the server might also have the |
| 29152 |
following confirmed record. |
| 29153 |
|
| 29154 |
{ ownerid, old_verifier, principal_arg, old_clientid, |
| 29155 |
confirmed } |
| 29156 |
|
| 29157 |
The server schedules the replacement of both records with: |
| 29158 |
|
| 29159 |
{ ownerid, verifier, principal_arg, clientid_arg, confirmed |
| 29160 |
} |
| 29161 |
|
| 29162 |
The processing of CREATE_SESSION continues on to session |
| 29163 |
creation. Once the session is successfully created, the |
| 29164 |
scheduled client record replacement is committed. If the |
| 29165 |
session is not successfully created, then no changes are |
| 29166 |
made to any client records on the server. |
| 29167 |
|
| 29168 |
|
| 29169 |
|
| 29170 |
|
| 29171 |
|
| 29172 |
<span class="grey">Shepler, et al. Standards Track [Page 521]</span></pre> |
| 29173 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-522" ></span> |
| 29174 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29175 |
|
| 29176 |
|
| 29177 |
* Unsuccessful Confirmation |
| 29178 |
|
| 29179 |
If the server has the following record, then the client has |
| 29180 |
changed principals after the previous EXCHANGE_ID request, |
| 29181 |
or there has been a chance collision between shorthand |
| 29182 |
client identifiers. |
| 29183 |
|
| 29184 |
{ *, *, old_principal_arg, clientid_arg, * } |
| 29185 |
|
| 29186 |
Neither of these cases is permissible. Processing stops |
| 29187 |
and NFS4ERR_CLID_INUSE is returned to the client. No |
| 29188 |
changes are made to any client records on the server. |
| 29189 |
|
| 29190 |
4. Session creation. The server confirmed the client ID, either in |
| 29191 |
this CREATE_SESSION operation, or a previous CREATE_SESSION |
| 29192 |
operation. The server examines the remaining fields of the |
| 29193 |
arguments. |
| 29194 |
|
| 29195 |
The server creates the session by recording the parameter values |
| 29196 |
used (including whether the CREATE_SESSION4_FLAG_PERSIST flag is |
| 29197 |
set and has been accepted by the server) and allocating space for |
| 29198 |
the session reply cache (if there is not enough space, the server |
| 29199 |
returns NFS4ERR_NOSPC). For each slot in the reply cache, the |
| 29200 |
server sets the sequence ID to zero, and records an entry |
| 29201 |
containing a COMPOUND reply with zero operations and the error |
| 29202 |
NFS4ERR_SEQ_MISORDERED. This way, if the first SEQUENCE request |
| 29203 |
sent has a sequence ID equal to zero, the server can simply |
| 29204 |
return what is in the reply cache: NFS4ERR_SEQ_MISORDERED. The |
| 29205 |
client initializes its reply cache for receiving callbacks in the |
| 29206 |
same way, and similarly, the first CB_SEQUENCE operation on a |
| 29207 |
slot after session creation MUST have a sequence ID of one. |
| 29208 |
|
| 29209 |
If the session state is created successfully, the server |
| 29210 |
associates the session with the client ID provided by the client. |
| 29211 |
|
| 29212 |
When a request that had CREATE_SESSION4_FLAG_CONN_RDMA set needs |
| 29213 |
to be retried, the retry MUST be done on a new connection that is |
| 29214 |
in non-RDMA mode. If properties of the new connection are |
| 29215 |
different enough that the arguments to CREATE_SESSION need to |
| 29216 |
change, then a non-retry MUST be sent. The server will |
| 29217 |
eventually dispose of any session that was created on the |
| 29218 |
original connection. |
| 29219 |
|
| 29220 |
On the backchannel, the client and server might wish to have many |
| 29221 |
slots, in some cases perhaps more that the fore channel, in order to |
| 29222 |
deal with the situations where the network link has high latency and |
| 29223 |
|
| 29224 |
|
| 29225 |
|
| 29226 |
|
| 29227 |
|
| 29228 |
<span class="grey">Shepler, et al. Standards Track [Page 522]</span></pre> |
| 29229 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-523" ></span> |
| 29230 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29231 |
|
| 29232 |
|
| 29233 |
is the primary bottleneck for response to recalls. If so, and if the |
| 29234 |
client provides too few slots to the backchannel, the server might |
| 29235 |
limit the number of recallable objects it gives to the client. |
| 29236 |
|
| 29237 |
Implementing RPCSEC_GSS callback support requires changes to both the |
| 29238 |
client and server implementations of RPCSEC_GSS. One possible set of |
| 29239 |
changes includes: |
| 29240 |
|
| 29241 |
o Adding a data structure that wraps the GSS-API context with a |
| 29242 |
reference count. |
| 29243 |
|
| 29244 |
o New functions to increment and decrement the reference count. If |
| 29245 |
the reference count is decremented to zero, the wrapper data |
| 29246 |
structure and the GSS-API context it refers to would be freed. |
| 29247 |
|
| 29248 |
o Change RPCSEC_GSS to create the wrapper data structure upon |
| 29249 |
receiving GSS-API context from gss_accept_sec_context() and |
| 29250 |
gss_init_sec_context(). The reference count would be initialized |
| 29251 |
to 1. |
| 29252 |
|
| 29253 |
o Adding a function to map an existing RPCSEC_GSS handle to a |
| 29254 |
pointer to the wrapper data structure. The reference count would |
| 29255 |
be incremented. |
| 29256 |
|
| 29257 |
o Adding a function to create a new RPCSEC_GSS handle from a pointer |
| 29258 |
to the wrapper data structure. The reference count would be |
| 29259 |
incremented. |
| 29260 |
|
| 29261 |
o Replacing calls from RPCSEC_GSS that free GSS-API contexts, with |
| 29262 |
calls to decrement the reference count on the wrapper data |
| 29263 |
structure. |
| 29264 |
|
| 29265 |
<span class="h3"><a class="selflink" id="section-18.37" href="#section-18.37">18.37</a>. Operation 44: DESTROY_SESSION - Destroy a Session</span> |
| 29266 |
|
| 29267 |
<span class="h4"><a class="selflink" id="section-18.37.1" href="#section-18.37.1">18.37.1</a>. ARGUMENT</span> |
| 29268 |
|
| 29269 |
struct DESTROY_SESSION4args { |
| 29270 |
sessionid4 dsa_sessionid; |
| 29271 |
}; |
| 29272 |
|
| 29273 |
<span class="h4"><a class="selflink" id="section-18.37.2" href="#section-18.37.2">18.37.2</a>. RESULT</span> |
| 29274 |
|
| 29275 |
struct DESTROY_SESSION4res { |
| 29276 |
nfsstat4 dsr_status; |
| 29277 |
}; |
| 29278 |
|
| 29279 |
|
| 29280 |
|
| 29281 |
|
| 29282 |
|
| 29283 |
|
| 29284 |
<span class="grey">Shepler, et al. Standards Track [Page 523]</span></pre> |
| 29285 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-524" ></span> |
| 29286 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29287 |
|
| 29288 |
|
| 29289 |
<span class="h4"><a class="selflink" id="section-18.37.3" href="#section-18.37.3">18.37.3</a>. DESCRIPTION</span> |
| 29290 |
|
| 29291 |
The DESTROY_SESSION operation closes the session and discards the |
| 29292 |
session's reply cache, if any. Any remaining connections associated |
| 29293 |
with the session are immediately disassociated. If the connection |
| 29294 |
has no remaining associated sessions, the connection MAY be closed by |
| 29295 |
the server. Locks, delegations, layouts, wants, and the lease, which |
| 29296 |
are all tied to the client ID, are not affected by DESTROY_SESSION. |
| 29297 |
|
| 29298 |
DESTROY_SESSION MUST be invoked on a connection that is associated |
| 29299 |
with the session being destroyed. In addition, if SP4_MACH_CRED |
| 29300 |
state protection was specified when the client ID was created, the |
| 29301 |
RPCSEC_GSS principal that created the session MUST be the one that |
| 29302 |
destroys the session, using RPCSEC_GSS privacy or integrity. If |
| 29303 |
SP4_SSV state protection was specified when the client ID was |
| 29304 |
created, RPCSEC_GSS using the SSV mechanism (<a href="#section-2.10.9">Section 2.10.9</a>) MUST be |
| 29305 |
used, with integrity or privacy. |
| 29306 |
|
| 29307 |
If the COMPOUND request starts with SEQUENCE, and if the sessionids |
| 29308 |
specified in SEQUENCE and DESTROY_SESSION are the same, then |
| 29309 |
|
| 29310 |
o DESTROY_SESSION MUST be the final operation in the COMPOUND |
| 29311 |
request. |
| 29312 |
|
| 29313 |
o It is advisable to avoid placing DESTROY_SESSION in a COMPOUND |
| 29314 |
request with other state-modifying operations, because the |
| 29315 |
DESTROY_SESSION will destroy the reply cache. |
| 29316 |
|
| 29317 |
o Because the session and its reply cache are destroyed, a client |
| 29318 |
that retries the request may receive an error in reply to the |
| 29319 |
retry, even though the original request was successful. |
| 29320 |
|
| 29321 |
If the COMPOUND request starts with SEQUENCE, and if the sessionids |
| 29322 |
specified in SEQUENCE and DESTROY_SESSION are different, then |
| 29323 |
DESTROY_SESSION can appear in any position of the COMPOUND request |
| 29324 |
(except for the first position). The two sessionids can belong to |
| 29325 |
different client IDs. |
| 29326 |
|
| 29327 |
If the COMPOUND request does not start with SEQUENCE, and if |
| 29328 |
DESTROY_SESSION is not the sole operation, then server MUST return |
| 29329 |
NFS4ERR_NOT_ONLY_OP. |
| 29330 |
|
| 29331 |
If there is a backchannel on the session and the server has |
| 29332 |
outstanding CB_COMPOUND operations for the session which have not |
| 29333 |
been replied to, then the server MAY refuse to destroy the session |
| 29334 |
and return an error. If so, then in the event the backchannel is |
| 29335 |
down, the server SHOULD return NFS4ERR_CB_PATH_DOWN to inform the |
| 29336 |
client that the backchannel needs to be repaired before the server |
| 29337 |
|
| 29338 |
|
| 29339 |
|
| 29340 |
<span class="grey">Shepler, et al. Standards Track [Page 524]</span></pre> |
| 29341 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-525" ></span> |
| 29342 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29343 |
|
| 29344 |
|
| 29345 |
will allow the session to be destroyed. Otherwise, the error |
| 29346 |
CB_BACK_CHAN_BUSY SHOULD be returned to indicate that there are |
| 29347 |
CB_COMPOUNDs that need to be replied to. The client SHOULD reply to |
| 29348 |
all outstanding CB_COMPOUNDs before re-sending DESTROY_SESSION. |
| 29349 |
|
| 29350 |
<span class="h3"><a class="selflink" id="section-18.38" href="#section-18.38">18.38</a>. Operation 45: FREE_STATEID - Free Stateid with No Locks</span> |
| 29351 |
|
| 29352 |
<span class="h4"><a class="selflink" id="section-18.38.1" href="#section-18.38.1">18.38.1</a>. ARGUMENT</span> |
| 29353 |
|
| 29354 |
struct FREE_STATEID4args { |
| 29355 |
stateid4 fsa_stateid; |
| 29356 |
}; |
| 29357 |
|
| 29358 |
<span class="h4"><a class="selflink" id="section-18.38.2" href="#section-18.38.2">18.38.2</a>. RESULT</span> |
| 29359 |
|
| 29360 |
struct FREE_STATEID4res { |
| 29361 |
nfsstat4 fsr_status; |
| 29362 |
}; |
| 29363 |
|
| 29364 |
<span class="h4"><a class="selflink" id="section-18.38.3" href="#section-18.38.3">18.38.3</a>. DESCRIPTION</span> |
| 29365 |
|
| 29366 |
The FREE_STATEID operation is used to free a stateid that no longer |
| 29367 |
has any associated locks (including opens, byte-range locks, |
| 29368 |
delegations, and layouts). This may be because of client LOCKU |
| 29369 |
operations or because of server revocation. If there are valid locks |
| 29370 |
(of any kind) associated with the stateid in question, the error |
| 29371 |
NFS4ERR_LOCKS_HELD will be returned, and the associated stateid will |
| 29372 |
not be freed. |
| 29373 |
|
| 29374 |
When a stateid is freed that had been associated with revoked locks, |
| 29375 |
by sending the FREE_STATEID operation, the client acknowledges the |
| 29376 |
loss of those locks. This allows the server, once all such revoked |
| 29377 |
state is acknowledged, to allow that client again to reclaim locks, |
| 29378 |
without encountering the edge conditions discussed in <a href="#section-8.4.2">Section 8.4.2</a>. |
| 29379 |
|
| 29380 |
Once a successful FREE_STATEID is done for a given stateid, any |
| 29381 |
subsequent use of that stateid will result in an NFS4ERR_BAD_STATEID |
| 29382 |
error. |
| 29383 |
|
| 29384 |
|
| 29385 |
|
| 29386 |
|
| 29387 |
|
| 29388 |
|
| 29389 |
|
| 29390 |
|
| 29391 |
|
| 29392 |
|
| 29393 |
|
| 29394 |
|
| 29395 |
|
| 29396 |
<span class="grey">Shepler, et al. Standards Track [Page 525]</span></pre> |
| 29397 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-526" ></span> |
| 29398 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29399 |
|
| 29400 |
|
| 29401 |
<span class="h3"><a class="selflink" id="section-18.39" href="#section-18.39">18.39</a>. Operation 46: GET_DIR_DELEGATION - Get a Directory Delegation</span> |
| 29402 |
|
| 29403 |
<span class="h4"><a class="selflink" id="section-18.39.1" href="#section-18.39.1">18.39.1</a>. ARGUMENT</span> |
| 29404 |
|
| 29405 |
|
| 29406 |
typedef nfstime4 attr_notice4; |
| 29407 |
|
| 29408 |
struct GET_DIR_DELEGATION4args { |
| 29409 |
/* CURRENT_FH: delegated directory */ |
| 29410 |
bool gdda_signal_deleg_avail; |
| 29411 |
bitmap4 gdda_notification_types; |
| 29412 |
attr_notice4 gdda_child_attr_delay; |
| 29413 |
attr_notice4 gdda_dir_attr_delay; |
| 29414 |
bitmap4 gdda_child_attributes; |
| 29415 |
bitmap4 gdda_dir_attributes; |
| 29416 |
}; |
| 29417 |
|
| 29418 |
<span class="h4"><a class="selflink" id="section-18.39.2" href="#section-18.39.2">18.39.2</a>. RESULT</span> |
| 29419 |
|
| 29420 |
struct GET_DIR_DELEGATION4resok { |
| 29421 |
verifier4 gddr_cookieverf; |
| 29422 |
/* Stateid for get_dir_delegation */ |
| 29423 |
stateid4 gddr_stateid; |
| 29424 |
/* Which notifications can the server support */ |
| 29425 |
bitmap4 gddr_notification; |
| 29426 |
bitmap4 gddr_child_attributes; |
| 29427 |
bitmap4 gddr_dir_attributes; |
| 29428 |
}; |
| 29429 |
|
| 29430 |
enum gddrnf4_status { |
| 29431 |
GDD4_OK = 0, |
| 29432 |
GDD4_UNAVAIL = 1 |
| 29433 |
}; |
| 29434 |
|
| 29435 |
union GET_DIR_DELEGATION4res_non_fatal |
| 29436 |
switch (gddrnf4_status gddrnf_status) { |
| 29437 |
case GDD4_OK: |
| 29438 |
GET_DIR_DELEGATION4resok gddrnf_resok4; |
| 29439 |
case GDD4_UNAVAIL: |
| 29440 |
bool gddrnf_will_signal_deleg_avail; |
| 29441 |
}; |
| 29442 |
|
| 29443 |
|
| 29444 |
|
| 29445 |
|
| 29446 |
|
| 29447 |
|
| 29448 |
|
| 29449 |
|
| 29450 |
|
| 29451 |
|
| 29452 |
<span class="grey">Shepler, et al. Standards Track [Page 526]</span></pre> |
| 29453 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-527" ></span> |
| 29454 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29455 |
|
| 29456 |
|
| 29457 |
union GET_DIR_DELEGATION4res |
| 29458 |
switch (nfsstat4 gddr_status) { |
| 29459 |
case NFS4_OK: |
| 29460 |
GET_DIR_DELEGATION4res_non_fatal gddr_res_non_fatal4; |
| 29461 |
default: |
| 29462 |
void; |
| 29463 |
}; |
| 29464 |
|
| 29465 |
<span class="h4"><a class="selflink" id="section-18.39.3" href="#section-18.39.3">18.39.3</a>. DESCRIPTION</span> |
| 29466 |
|
| 29467 |
The GET_DIR_DELEGATION operation is used by a client to request a |
| 29468 |
directory delegation. The directory is represented by the current |
| 29469 |
filehandle. The client also specifies whether it wants the server to |
| 29470 |
notify it when the directory changes in certain ways by setting one |
| 29471 |
or more bits in a bitmap. The server may refuse to grant the |
| 29472 |
delegation. In that case, the server will return |
| 29473 |
NFS4ERR_DIRDELEG_UNAVAIL. If the server decides to hand out the |
| 29474 |
delegation, it will return a cookie verifier for that directory. If |
| 29475 |
the cookie verifier changes when the client is holding the |
| 29476 |
delegation, the delegation will be recalled unless the client has |
| 29477 |
asked for notification for this event. |
| 29478 |
|
| 29479 |
The server will also return a directory delegation stateid, |
| 29480 |
gddr_stateid, as a result of the GET_DIR_DELEGATION operation. This |
| 29481 |
stateid will appear in callback messages related to the delegation, |
| 29482 |
such as notifications and delegation recalls. The client will use |
| 29483 |
this stateid to return the delegation voluntarily or upon recall. A |
| 29484 |
delegation is returned by calling the DELEGRETURN operation. |
| 29485 |
|
| 29486 |
The server might not be able to support notifications of certain |
| 29487 |
events. If the client asks for such notifications, the server MUST |
| 29488 |
inform the client of its inability to do so as part of the |
| 29489 |
GET_DIR_DELEGATION reply by not setting the appropriate bits in the |
| 29490 |
supported notifications bitmask, gddr_notification, contained in the |
| 29491 |
reply. The server MUST NOT add bits to gddr_notification that the |
| 29492 |
client did not request. |
| 29493 |
|
| 29494 |
The GET_DIR_DELEGATION operation can be used for both normal and |
| 29495 |
named attribute directories. |
| 29496 |
|
| 29497 |
If client sets gdda_signal_deleg_avail to TRUE, then it is |
| 29498 |
registering with the client a "want" for a directory delegation. If |
| 29499 |
the delegation is not available, and the server supports and will |
| 29500 |
honor the "want", the results will have |
| 29501 |
gddrnf_will_signal_deleg_avail set to TRUE and no error will be |
| 29502 |
indicated on return. If so, the client should expect a future |
| 29503 |
CB_RECALLABLE_OBJ_AVAIL operation to indicate that a directory |
| 29504 |
delegation is available. If the server does not wish to honor the |
| 29505 |
|
| 29506 |
|
| 29507 |
|
| 29508 |
<span class="grey">Shepler, et al. Standards Track [Page 527]</span></pre> |
| 29509 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-528" ></span> |
| 29510 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29511 |
|
| 29512 |
|
| 29513 |
"want" or is not able to do so, it returns the error |
| 29514 |
NFS4ERR_DIRDELEG_UNAVAIL. If the delegation is immediately |
| 29515 |
available, the server SHOULD return it with the response to the |
| 29516 |
operation, rather than via a callback. |
| 29517 |
|
| 29518 |
When a client makes a request for a directory delegation while it |
| 29519 |
already holds a directory delegation for that directory (including |
| 29520 |
the case where it has been recalled but not yet returned by the |
| 29521 |
client or revoked by the server), the server MUST reply with the |
| 29522 |
value of gddr_status set to NFS4_OK, the value of gddrnf_status set |
| 29523 |
to GDD4_UNAVAIL, and the value of gddrnf_will_signal_deleg_avail set |
| 29524 |
to FALSE. The delegation the client held before the request remains |
| 29525 |
intact, and its state is unchanged. The current stateid is not |
| 29526 |
changed (see <a href="#section-16.2.3.1.2">Section 16.2.3.1.2</a> for a description of the current |
| 29527 |
stateid). |
| 29528 |
|
| 29529 |
<span class="h4"><a class="selflink" id="section-18.39.4" href="#section-18.39.4">18.39.4</a>. IMPLEMENTATION</span> |
| 29530 |
|
| 29531 |
Directory delegations provide the benefit of improving cache |
| 29532 |
consistency of namespace information. This is done through |
| 29533 |
synchronous callbacks. A server must support synchronous callbacks |
| 29534 |
in order to support directory delegations. In addition to that, |
| 29535 |
asynchronous notifications provide a way to reduce network traffic as |
| 29536 |
well as improve client performance in certain conditions. |
| 29537 |
|
| 29538 |
Notifications are specified in terms of potential changes to the |
| 29539 |
directory. A client can ask to be notified of events by setting one |
| 29540 |
or more bits in gdda_notification_types. The client can ask for |
| 29541 |
notifications on addition of entries to a directory (by setting the |
| 29542 |
NOTIFY4_ADD_ENTRY in gdda_notification_types), notifications on entry |
| 29543 |
removal (NOTIFY4_REMOVE_ENTRY), renames (NOTIFY4_RENAME_ENTRY), |
| 29544 |
directory attribute changes (NOTIFY4_CHANGE_DIR_ATTRIBUTES), and |
| 29545 |
cookie verifier changes (NOTIFY4_CHANGE_COOKIE_VERIFIER) by setting |
| 29546 |
one or more corresponding bits in the gdda_notification_types field. |
| 29547 |
|
| 29548 |
The client can also ask for notifications of changes to attributes of |
| 29549 |
directory entries (NOTIFY4_CHANGE_CHILD_ATTRIBUTES) in order to keep |
| 29550 |
its attribute cache up to date. However, any changes made to child |
| 29551 |
attributes do not cause the delegation to be recalled. If a client |
| 29552 |
is interested in directory entry caching or negative name caching, it |
| 29553 |
can set the gdda_notification_types appropriately to its particular |
| 29554 |
need and the server will notify it of all changes that would |
| 29555 |
otherwise invalidate its name cache. The kind of notification a |
| 29556 |
client asks for may depend on the directory size, its rate of change, |
| 29557 |
and the applications being used to access that directory. The |
| 29558 |
enumeration of the conditions under which a client might ask for a |
| 29559 |
notification is out of the scope of this specification. |
| 29560 |
|
| 29561 |
|
| 29562 |
|
| 29563 |
|
| 29564 |
<span class="grey">Shepler, et al. Standards Track [Page 528]</span></pre> |
| 29565 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-529" ></span> |
| 29566 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29567 |
|
| 29568 |
|
| 29569 |
For attribute notifications, the client will set bits in the |
| 29570 |
gdda_dir_attributes bitmap to indicate which attributes it wants to |
| 29571 |
be notified of. If the server does not support notifications for |
| 29572 |
changes to a certain attribute, it SHOULD NOT set that attribute in |
| 29573 |
the supported attribute bitmap specified in the reply |
| 29574 |
(gddr_dir_attributes). The client will also set in the |
| 29575 |
gdda_child_attributes bitmap the attributes of directory entries it |
| 29576 |
wants to be notified of, and the server will indicate in |
| 29577 |
gddr_child_attributes which attributes of directory entries it will |
| 29578 |
notify the client of. |
| 29579 |
|
| 29580 |
The client will also let the server know if it wants to get the |
| 29581 |
notification as soon as the attribute change occurs or after a |
| 29582 |
certain delay by setting a delay factor; gdda_child_attr_delay is for |
| 29583 |
attribute changes to directory entries and gdda_dir_attr_delay is for |
| 29584 |
attribute changes to the directory. If this delay factor is set to |
| 29585 |
zero, that indicates to the server that the client wants to be |
| 29586 |
notified of any attribute changes as soon as they occur. If the |
| 29587 |
delay factor is set to N seconds, the server will make a best-effort |
| 29588 |
guarantee that attribute updates are synchronized within N seconds. |
| 29589 |
If the client asks for a delay factor that the server does not |
| 29590 |
support or that may cause significant resource consumption on the |
| 29591 |
server by causing the server to send a lot of notifications, the |
| 29592 |
server should not commit to sending out notifications for attributes |
| 29593 |
and therefore must not set the appropriate bit in the |
| 29594 |
gddr_child_attributes and gddr_dir_attributes bitmaps in the |
| 29595 |
response. |
| 29596 |
|
| 29597 |
The client MUST use a security tuple (<a href="#section-2.6.1">Section 2.6.1</a>) that the |
| 29598 |
directory or its applicable ancestor (<a href="#section-2.6">Section 2.6</a>) is exported with. |
| 29599 |
If not, the server MUST return NFS4ERR_WRONGSEC to the operation that |
| 29600 |
both precedes GET_DIR_DELEGATION and sets the current filehandle (see |
| 29601 |
<a href="#section-2.6.3.1">Section 2.6.3.1</a>). |
| 29602 |
|
| 29603 |
The directory delegation covers all the entries in the directory |
| 29604 |
except the parent entry. That means if a directory and its parent |
| 29605 |
both hold directory delegations, any changes to the parent will not |
| 29606 |
cause a notification to be sent for the child even though the child's |
| 29607 |
parent entry points to the parent directory. |
| 29608 |
|
| 29609 |
|
| 29610 |
|
| 29611 |
|
| 29612 |
|
| 29613 |
|
| 29614 |
|
| 29615 |
|
| 29616 |
|
| 29617 |
|
| 29618 |
|
| 29619 |
|
| 29620 |
<span class="grey">Shepler, et al. Standards Track [Page 529]</span></pre> |
| 29621 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-530" ></span> |
| 29622 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29623 |
|
| 29624 |
|
| 29625 |
<span class="h3"><a class="selflink" id="section-18.40" href="#section-18.40">18.40</a>. Operation 47: GETDEVICEINFO - Get Device Information</span> |
| 29626 |
|
| 29627 |
<span class="h4"><a class="selflink" id="section-18.40.1" href="#section-18.40.1">18.40.1</a>. ARGUMENT</span> |
| 29628 |
|
| 29629 |
struct GETDEVICEINFO4args { |
| 29630 |
deviceid4 gdia_device_id; |
| 29631 |
layouttype4 gdia_layout_type; |
| 29632 |
count4 gdia_maxcount; |
| 29633 |
bitmap4 gdia_notify_types; |
| 29634 |
}; |
| 29635 |
|
| 29636 |
<span class="h4"><a class="selflink" id="section-18.40.2" href="#section-18.40.2">18.40.2</a>. RESULT</span> |
| 29637 |
|
| 29638 |
struct GETDEVICEINFO4resok { |
| 29639 |
device_addr4 gdir_device_addr; |
| 29640 |
bitmap4 gdir_notification; |
| 29641 |
}; |
| 29642 |
|
| 29643 |
union GETDEVICEINFO4res switch (nfsstat4 gdir_status) { |
| 29644 |
case NFS4_OK: |
| 29645 |
GETDEVICEINFO4resok gdir_resok4; |
| 29646 |
case NFS4ERR_TOOSMALL: |
| 29647 |
count4 gdir_mincount; |
| 29648 |
default: |
| 29649 |
void; |
| 29650 |
}; |
| 29651 |
|
| 29652 |
<span class="h4"><a class="selflink" id="section-18.40.3" href="#section-18.40.3">18.40.3</a>. DESCRIPTION</span> |
| 29653 |
|
| 29654 |
The GETDEVICEINFO operation returns pNFS storage device address |
| 29655 |
information for the specified device ID. The client identifies the |
| 29656 |
device information to be returned by providing the gdia_device_id and |
| 29657 |
gdia_layout_type that uniquely identify the device. The client |
| 29658 |
provides gdia_maxcount to limit the number of bytes for the result. |
| 29659 |
This maximum size represents all of the data being returned within |
| 29660 |
the GETDEVICEINFO4resok structure and includes the XDR overhead. The |
| 29661 |
server may return less data. If the server is unable to return any |
| 29662 |
information within the gdia_maxcount limit, the error |
| 29663 |
NFS4ERR_TOOSMALL will be returned. However, if gdia_maxcount is |
| 29664 |
zero, NFS4ERR_TOOSMALL MUST NOT be returned. |
| 29665 |
|
| 29666 |
The da_layout_type field of the gdir_device_addr returned by the |
| 29667 |
server MUST be equal to the gdia_layout_type specified by the client. |
| 29668 |
If it is not equal, the client SHOULD ignore the response as invalid |
| 29669 |
and behave as if the server returned an error, even if the client |
| 29670 |
does have support for the layout type returned. |
| 29671 |
|
| 29672 |
|
| 29673 |
|
| 29674 |
|
| 29675 |
|
| 29676 |
<span class="grey">Shepler, et al. Standards Track [Page 530]</span></pre> |
| 29677 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-531" ></span> |
| 29678 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29679 |
|
| 29680 |
|
| 29681 |
The client also provides a notification bitmap, gdia_notify_types, |
| 29682 |
for the device ID mapping notification for which it is interested in |
| 29683 |
receiving; the server must support device ID notifications for the |
| 29684 |
notification request to have affect. The notification mask is |
| 29685 |
composed in the same manner as the bitmap for file attributes |
| 29686 |
(<a href="#section-3.3.7">Section 3.3.7</a>). The numbers of bit positions are listed in the |
| 29687 |
notify_device_type4 enumeration type (<a href="#section-20.12">Section 20.12</a>). Only two |
| 29688 |
enumerated values of notify_device_type4 currently apply to |
| 29689 |
GETDEVICEINFO: NOTIFY_DEVICEID4_CHANGE and NOTIFY_DEVICEID4_DELETE |
| 29690 |
(see <a href="#section-20.12">Section 20.12</a>). |
| 29691 |
|
| 29692 |
The notification bitmap applies only to the specified device ID. If |
| 29693 |
a client sends a GETDEVICEINFO operation on a deviceID multiple |
| 29694 |
times, the last notification bitmap is used by the server for |
| 29695 |
subsequent notifications. If the bitmap is zero or empty, then the |
| 29696 |
device ID's notifications are turned off. |
| 29697 |
|
| 29698 |
If the client wants to just update or turn off notifications, it MAY |
| 29699 |
send a GETDEVICEINFO operation with gdia_maxcount set to zero. In |
| 29700 |
that event, if the device ID is valid, the reply's da_addr_body field |
| 29701 |
of the gdir_device_addr field will be of zero length. |
| 29702 |
|
| 29703 |
If an unknown device ID is given in gdia_device_id, the server |
| 29704 |
returns NFS4ERR_NOENT. Otherwise, the device address information is |
| 29705 |
returned in gdir_device_addr. Finally, if the server supports |
| 29706 |
notifications for device ID mappings, the gdir_notification result |
| 29707 |
will contain a bitmap of which notifications it will actually send to |
| 29708 |
the client (via CB_NOTIFY_DEVICEID, see <a href="#section-20.12">Section 20.12</a>). |
| 29709 |
|
| 29710 |
If NFS4ERR_TOOSMALL is returned, the results also contain |
| 29711 |
gdir_mincount. The value of gdir_mincount represents the minimum |
| 29712 |
size necessary to obtain the device information. |
| 29713 |
|
| 29714 |
<span class="h4"><a class="selflink" id="section-18.40.4" href="#section-18.40.4">18.40.4</a>. IMPLEMENTATION</span> |
| 29715 |
|
| 29716 |
Aside from updating or turning off notifications, another use case |
| 29717 |
for gdia_maxcount being set to zero is to validate a device ID. |
| 29718 |
|
| 29719 |
The client SHOULD request a notification for changes or deletion of a |
| 29720 |
device ID to device address mapping so that the server can allow the |
| 29721 |
client gracefully use a new mapping, without having pending I/O fail |
| 29722 |
abruptly, or force layouts using the device ID to be recalled or |
| 29723 |
revoked. |
| 29724 |
|
| 29725 |
It is possible that GETDEVICEINFO (and GETDEVICELIST) will race with |
| 29726 |
CB_NOTIFY_DEVICEID, i.e., CB_NOTIFY_DEVICEID arrives before the |
| 29727 |
client gets and processes the response to GETDEVICEINFO or |
| 29728 |
|
| 29729 |
|
| 29730 |
|
| 29731 |
|
| 29732 |
<span class="grey">Shepler, et al. Standards Track [Page 531]</span></pre> |
| 29733 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-532" ></span> |
| 29734 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29735 |
|
| 29736 |
|
| 29737 |
GETDEVICELIST. The analysis of the race leverages the fact that the |
| 29738 |
server MUST NOT delete a device ID that is referred to by a layout |
| 29739 |
the client has. |
| 29740 |
|
| 29741 |
o CB_NOTIFY_DEVICEID deletes a device ID. If the client believes it |
| 29742 |
has layouts that refer to the device ID, then it is possible that |
| 29743 |
layouts referring to the deleted device ID have been revoked. The |
| 29744 |
client should send a TEST_STATEID request using the stateid for |
| 29745 |
each layout that might have been revoked. If TEST_STATEID |
| 29746 |
indicates that any layouts have been revoked, the client must |
| 29747 |
recover from layout revocation as described in <a href="#section-12.5.6">Section 12.5.6</a>. If |
| 29748 |
TEST_STATEID indicates that at least one layout has not been |
| 29749 |
revoked, the client should send a GETDEVICEINFO operation on the |
| 29750 |
supposedly deleted device ID to verify that the device ID has been |
| 29751 |
deleted. |
| 29752 |
|
| 29753 |
If GETDEVICEINFO indicates that the device ID does not exist, then |
| 29754 |
the client assumes the server is faulty and recovers by sending an |
| 29755 |
EXCHANGE_ID operation. If GETDEVICEINFO indicates that the device |
| 29756 |
ID does exist, then while the server is faulty for sending an |
| 29757 |
erroneous device ID deletion notification, the degree to which it |
| 29758 |
is faulty does not require the client to create a new client ID. |
| 29759 |
|
| 29760 |
If the client does not have layouts that refer to the device ID, |
| 29761 |
no harm is done. The client should mark the device ID as deleted, |
| 29762 |
and when GETDEVICEINFO or GETDEVICELIST results are received that |
| 29763 |
indicate that the device ID has been in fact deleted, the device |
| 29764 |
ID should be removed from the client's cache. |
| 29765 |
|
| 29766 |
o CB_NOTIFY_DEVICEID indicates that a device ID's device addressing |
| 29767 |
mappings have changed. The client should assume that the results |
| 29768 |
from the in-progress GETDEVICEINFO will be stale for the device ID |
| 29769 |
once received, and so it should send another GETDEVICEINFO on the |
| 29770 |
device ID. |
| 29771 |
|
| 29772 |
|
| 29773 |
|
| 29774 |
|
| 29775 |
|
| 29776 |
|
| 29777 |
|
| 29778 |
|
| 29779 |
|
| 29780 |
|
| 29781 |
|
| 29782 |
|
| 29783 |
|
| 29784 |
|
| 29785 |
|
| 29786 |
|
| 29787 |
|
| 29788 |
<span class="grey">Shepler, et al. Standards Track [Page 532]</span></pre> |
| 29789 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-533" ></span> |
| 29790 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29791 |
|
| 29792 |
|
| 29793 |
<span class="h3"><a class="selflink" id="section-18.41" href="#section-18.41">18.41</a>. Operation 48: GETDEVICELIST - Get All Device Mappings for a File</span> |
| 29794 |
<span class="h3"> System</span> |
| 29795 |
|
| 29796 |
<span class="h4"><a class="selflink" id="section-18.41.1" href="#section-18.41.1">18.41.1</a>. ARGUMENT</span> |
| 29797 |
|
| 29798 |
struct GETDEVICELIST4args { |
| 29799 |
/* CURRENT_FH: object belonging to the file system */ |
| 29800 |
layouttype4 gdla_layout_type; |
| 29801 |
|
| 29802 |
/* number of deviceIDs to return */ |
| 29803 |
count4 gdla_maxdevices; |
| 29804 |
|
| 29805 |
nfs_cookie4 gdla_cookie; |
| 29806 |
verifier4 gdla_cookieverf; |
| 29807 |
}; |
| 29808 |
|
| 29809 |
<span class="h4"><a class="selflink" id="section-18.41.2" href="#section-18.41.2">18.41.2</a>. RESULT</span> |
| 29810 |
|
| 29811 |
struct GETDEVICELIST4resok { |
| 29812 |
nfs_cookie4 gdlr_cookie; |
| 29813 |
verifier4 gdlr_cookieverf; |
| 29814 |
deviceid4 gdlr_deviceid_list<>; |
| 29815 |
bool gdlr_eof; |
| 29816 |
}; |
| 29817 |
|
| 29818 |
union GETDEVICELIST4res switch (nfsstat4 gdlr_status) { |
| 29819 |
case NFS4_OK: |
| 29820 |
GETDEVICELIST4resok gdlr_resok4; |
| 29821 |
default: |
| 29822 |
void; |
| 29823 |
}; |
| 29824 |
|
| 29825 |
<span class="h4"><a class="selflink" id="section-18.41.3" href="#section-18.41.3">18.41.3</a>. DESCRIPTION</span> |
| 29826 |
|
| 29827 |
This operation is used by the client to enumerate all of the device |
| 29828 |
IDs that a server's file system uses. |
| 29829 |
|
| 29830 |
The client provides a current filehandle of a file object that |
| 29831 |
belongs to the file system (i.e., all file objects sharing the same |
| 29832 |
fsid as that of the current filehandle) and the layout type in |
| 29833 |
gdia_layout_type. Since this operation might require multiple calls |
| 29834 |
to enumerate all the device IDs (and is thus similar to the READDIR |
| 29835 |
(<a href="#section-18.23">Section 18.23</a>) operation), the client also provides gdia_cookie and |
| 29836 |
gdia_cookieverf to specify the current cursor position in the list. |
| 29837 |
When the client wants to read from the beginning of the file system's |
| 29838 |
device mappings, it sets gdla_cookie to zero. The field |
| 29839 |
gdla_cookieverf MUST be ignored by the server when gdla_cookie is |
| 29840 |
|
| 29841 |
|
| 29842 |
|
| 29843 |
|
| 29844 |
<span class="grey">Shepler, et al. Standards Track [Page 533]</span></pre> |
| 29845 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-534" ></span> |
| 29846 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29847 |
|
| 29848 |
|
| 29849 |
zero. The client provides gdla_maxdevices to limit the number of |
| 29850 |
device IDs in the result. If gdla_maxdevices is zero, the server |
| 29851 |
MUST return NFS4ERR_INVAL. The server MAY return fewer device IDs. |
| 29852 |
|
| 29853 |
The successful response to the operation will contain the cookie, |
| 29854 |
gdlr_cookie, and the cookie verifier, gdlr_cookieverf, to be used on |
| 29855 |
the subsequent GETDEVICELIST. A gdlr_eof value of TRUE signifies |
| 29856 |
that there are no remaining entries in the server's device list. |
| 29857 |
Each element of gdlr_deviceid_list contains a device ID. |
| 29858 |
|
| 29859 |
<span class="h4"><a class="selflink" id="section-18.41.4" href="#section-18.41.4">18.41.4</a>. IMPLEMENTATION</span> |
| 29860 |
|
| 29861 |
An example of the use of this operation is for pNFS clients and |
| 29862 |
servers that use LAYOUT4_BLOCK_VOLUME layouts. In these environments |
| 29863 |
it may be helpful for a client to determine device accessibility upon |
| 29864 |
first file system access. |
| 29865 |
|
| 29866 |
<span class="h3"><a class="selflink" id="section-18.42" href="#section-18.42">18.42</a>. Operation 49: LAYOUTCOMMIT - Commit Writes Made Using a Layout</span> |
| 29867 |
|
| 29868 |
<span class="h4"><a class="selflink" id="section-18.42.1" href="#section-18.42.1">18.42.1</a>. ARGUMENT</span> |
| 29869 |
|
| 29870 |
union newtime4 switch (bool nt_timechanged) { |
| 29871 |
case TRUE: |
| 29872 |
nfstime4 nt_time; |
| 29873 |
case FALSE: |
| 29874 |
void; |
| 29875 |
}; |
| 29876 |
|
| 29877 |
union newoffset4 switch (bool no_newoffset) { |
| 29878 |
case TRUE: |
| 29879 |
offset4 no_offset; |
| 29880 |
case FALSE: |
| 29881 |
void; |
| 29882 |
}; |
| 29883 |
|
| 29884 |
struct LAYOUTCOMMIT4args { |
| 29885 |
/* CURRENT_FH: file */ |
| 29886 |
offset4 loca_offset; |
| 29887 |
length4 loca_length; |
| 29888 |
bool loca_reclaim; |
| 29889 |
stateid4 loca_stateid; |
| 29890 |
newoffset4 loca_last_write_offset; |
| 29891 |
newtime4 loca_time_modify; |
| 29892 |
layoutupdate4 loca_layoutupdate; |
| 29893 |
}; |
| 29894 |
|
| 29895 |
|
| 29896 |
|
| 29897 |
|
| 29898 |
|
| 29899 |
|
| 29900 |
<span class="grey">Shepler, et al. Standards Track [Page 534]</span></pre> |
| 29901 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-535" ></span> |
| 29902 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29903 |
|
| 29904 |
|
| 29905 |
<span class="h4"><a class="selflink" id="section-18.42.2" href="#section-18.42.2">18.42.2</a>. RESULT</span> |
| 29906 |
|
| 29907 |
union newsize4 switch (bool ns_sizechanged) { |
| 29908 |
case TRUE: |
| 29909 |
length4 ns_size; |
| 29910 |
case FALSE: |
| 29911 |
void; |
| 29912 |
}; |
| 29913 |
|
| 29914 |
struct LAYOUTCOMMIT4resok { |
| 29915 |
newsize4 locr_newsize; |
| 29916 |
}; |
| 29917 |
|
| 29918 |
union LAYOUTCOMMIT4res switch (nfsstat4 locr_status) { |
| 29919 |
case NFS4_OK: |
| 29920 |
LAYOUTCOMMIT4resok locr_resok4; |
| 29921 |
default: |
| 29922 |
void; |
| 29923 |
}; |
| 29924 |
|
| 29925 |
<span class="h4"><a class="selflink" id="section-18.42.3" href="#section-18.42.3">18.42.3</a>. DESCRIPTION</span> |
| 29926 |
|
| 29927 |
The LAYOUTCOMMIT operation commits changes in the layout represented |
| 29928 |
by the current filehandle, client ID (derived from the session ID in |
| 29929 |
the preceding SEQUENCE operation), byte-range, and stateid. Since |
| 29930 |
layouts are sub-dividable, a smaller portion of a layout, retrieved |
| 29931 |
via LAYOUTGET, can be committed. The byte-range being committed is |
| 29932 |
specified through the byte-range (loca_offset and loca_length). This |
| 29933 |
byte-range MUST overlap with one or more existing layouts previously |
| 29934 |
granted via LAYOUTGET (<a href="#section-18.43">Section 18.43</a>), each with an iomode of |
| 29935 |
LAYOUTIOMODE4_RW. In the case where the iomode of any held layout |
| 29936 |
segment is not LAYOUTIOMODE4_RW, the server should return the error |
| 29937 |
NFS4ERR_BAD_IOMODE. For the case where the client does not hold |
| 29938 |
matching layout segment(s) for the defined byte-range, the server |
| 29939 |
should return the error NFS4ERR_BAD_LAYOUT. |
| 29940 |
|
| 29941 |
The LAYOUTCOMMIT operation indicates that the client has completed |
| 29942 |
writes using a layout obtained by a previous LAYOUTGET. The client |
| 29943 |
may have only written a subset of the data range it previously |
| 29944 |
requested. LAYOUTCOMMIT allows it to commit or discard provisionally |
| 29945 |
allocated space and to update the server with a new end-of-file. The |
| 29946 |
layout referenced by LAYOUTCOMMIT is still valid after the operation |
| 29947 |
completes and can be continued to be referenced by the client ID, |
| 29948 |
filehandle, byte-range, layout type, and stateid. |
| 29949 |
|
| 29950 |
If the loca_reclaim field is set to TRUE, this indicates that the |
| 29951 |
client is attempting to commit changes to a layout after the restart |
| 29952 |
of the metadata server during the metadata server's recovery grace |
| 29953 |
|
| 29954 |
|
| 29955 |
|
| 29956 |
<span class="grey">Shepler, et al. Standards Track [Page 535]</span></pre> |
| 29957 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-536" ></span> |
| 29958 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 29959 |
|
| 29960 |
|
| 29961 |
period (see <a href="#section-12.7.4">Section 12.7.4</a>). This type of request may be necessary |
| 29962 |
when the client has uncommitted writes to provisionally allocated |
| 29963 |
byte-ranges of a file that were sent to the storage devices before |
| 29964 |
the restart of the metadata server. In this case, the layout |
| 29965 |
provided by the client MUST be a subset of a writable layout that the |
| 29966 |
client held immediately before the restart of the metadata server. |
| 29967 |
The value of the field loca_stateid MUST be a value that the metadata |
| 29968 |
server returned before it restarted. The metadata server is free to |
| 29969 |
accept or reject this request based on its own internal metadata |
| 29970 |
consistency checks. If the metadata server finds that the layout |
| 29971 |
provided by the client does not pass its consistency checks, it MUST |
| 29972 |
reject the request with the status NFS4ERR_RECLAIM_BAD. The |
| 29973 |
successful completion of the LAYOUTCOMMIT request with loca_reclaim |
| 29974 |
set to TRUE does NOT provide the client with a layout for the file. |
| 29975 |
It simply commits the changes to the layout specified in the |
| 29976 |
loca_layoutupdate field. To obtain a layout for the file, the client |
| 29977 |
must send a LAYOUTGET request to the server after the server's grace |
| 29978 |
period has expired. If the metadata server receives a LAYOUTCOMMIT |
| 29979 |
request with loca_reclaim set to TRUE when the metadata server is not |
| 29980 |
in its recovery grace period, it MUST reject the request with the |
| 29981 |
status NFS4ERR_NO_GRACE. |
| 29982 |
|
| 29983 |
Setting the loca_reclaim field to TRUE is required if and only if the |
| 29984 |
committed layout was acquired before the metadata server restart. If |
| 29985 |
the client is committing a layout that was acquired during the |
| 29986 |
metadata server's grace period, it MUST set the "reclaim" field to |
| 29987 |
FALSE. |
| 29988 |
|
| 29989 |
The loca_stateid is a layout stateid value as returned by previously |
| 29990 |
successful layout operations (see <a href="#section-12.5.3">Section 12.5.3</a>). |
| 29991 |
|
| 29992 |
The loca_last_write_offset field specifies the offset of the last |
| 29993 |
byte written by the client previous to the LAYOUTCOMMIT. Note that |
| 29994 |
this value is never equal to the file's size (at most it is one byte |
| 29995 |
less than the file's size) and MUST be less than or equal to |
| 29996 |
NFS4_MAXFILEOFF. Also, loca_last_write_offset MUST overlap the range |
| 29997 |
described by loca_offset and loca_length. The metadata server may |
| 29998 |
use this information to determine whether the file's size needs to be |
| 29999 |
updated. If the metadata server updates the file's size as the |
| 30000 |
result of the LAYOUTCOMMIT operation, it must return the new size |
| 30001 |
(locr_newsize.ns_size) as part of the results. |
| 30002 |
|
| 30003 |
The loca_time_modify field allows the client to suggest a |
| 30004 |
modification time it would like the metadata server to set. The |
| 30005 |
metadata server may use the suggestion or it may use the time of the |
| 30006 |
LAYOUTCOMMIT operation to set the modification time. If the metadata |
| 30007 |
server uses the client-provided modification time, it should ensure |
| 30008 |
that time does not flow backwards. If the client wants to force the |
| 30009 |
|
| 30010 |
|
| 30011 |
|
| 30012 |
<span class="grey">Shepler, et al. Standards Track [Page 536]</span></pre> |
| 30013 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-537" ></span> |
| 30014 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30015 |
|
| 30016 |
|
| 30017 |
metadata server to set an exact time, the client should use a SETATTR |
| 30018 |
operation in a COMPOUND right after LAYOUTCOMMIT. See <a href="#section-12.5.4">Section 12.5.4</a> |
| 30019 |
for more details. If the client desires the resultant modification |
| 30020 |
time, it should construct the COMPOUND so that a GETATTR follows the |
| 30021 |
LAYOUTCOMMIT. |
| 30022 |
|
| 30023 |
The loca_layoutupdate argument to LAYOUTCOMMIT provides a mechanism |
| 30024 |
for a client to provide layout-specific updates to the metadata |
| 30025 |
server. For example, the layout update can describe what byte-ranges |
| 30026 |
of the original layout have been used and what byte-ranges can be |
| 30027 |
deallocated. There is no NFSv4.1 file layout-specific layoutupdate4 |
| 30028 |
structure. |
| 30029 |
|
| 30030 |
The layout information is more verbose for block devices than for |
| 30031 |
objects and files because the latter two hide the details of block |
| 30032 |
allocation behind their storage protocols. At the minimum, the |
| 30033 |
client needs to communicate changes to the end-of-file location back |
| 30034 |
to the server, and, if desired, its view of the file's modification |
| 30035 |
time. For block/volume layouts, it needs to specify precisely which |
| 30036 |
blocks have been used. |
| 30037 |
|
| 30038 |
If the layout identified in the arguments does not exist, the error |
| 30039 |
NFS4ERR_BADLAYOUT is returned. The layout being committed may also |
| 30040 |
be rejected if it does not correspond to an existing layout with an |
| 30041 |
iomode of LAYOUTIOMODE4_RW. |
| 30042 |
|
| 30043 |
On success, the current filehandle retains its value and the current |
| 30044 |
stateid retains its value. |
| 30045 |
|
| 30046 |
<span class="h4"><a class="selflink" id="section-18.42.4" href="#section-18.42.4">18.42.4</a>. IMPLEMENTATION</span> |
| 30047 |
|
| 30048 |
The client MAY also use LAYOUTCOMMIT with the loca_reclaim field set |
| 30049 |
to TRUE to convey hints to modified file attributes or to report |
| 30050 |
layout-type specific information such as I/O errors for object-based |
| 30051 |
storage layouts, as normally done during normal operation. Doing so |
| 30052 |
may help the metadata server to recover files more efficiently after |
| 30053 |
restart. For example, some file system implementations may require |
| 30054 |
expansive recovery of file system objects if the metadata server does |
| 30055 |
not get a positive indication from all clients holding a |
| 30056 |
LAYOUTIOMODE4_RW layout that they have successfully completed all |
| 30057 |
their writes. Sending a LAYOUTCOMMIT (if required) and then |
| 30058 |
following with LAYOUTRETURN can provide such an indication and allow |
| 30059 |
for graceful and efficient recovery. |
| 30060 |
|
| 30061 |
|
| 30062 |
|
| 30063 |
|
| 30064 |
|
| 30065 |
|
| 30066 |
|
| 30067 |
|
| 30068 |
<span class="grey">Shepler, et al. Standards Track [Page 537]</span></pre> |
| 30069 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-538" ></span> |
| 30070 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30071 |
|
| 30072 |
|
| 30073 |
If loca_reclaim is TRUE, the metadata server is free to either |
| 30074 |
examine or ignore the value in the field loca_stateid. The metadata |
| 30075 |
server implementation might or might not encode in its layout stateid |
| 30076 |
information that allows the metadate server to perform a consistency |
| 30077 |
check on the LAYOUTCOMMIT request. |
| 30078 |
|
| 30079 |
<span class="h3"><a class="selflink" id="section-18.43" href="#section-18.43">18.43</a>. Operation 50: LAYOUTGET - Get Layout Information</span> |
| 30080 |
|
| 30081 |
<span class="h4"><a class="selflink" id="section-18.43.1" href="#section-18.43.1">18.43.1</a>. ARGUMENT</span> |
| 30082 |
|
| 30083 |
struct LAYOUTGET4args { |
| 30084 |
/* CURRENT_FH: file */ |
| 30085 |
bool loga_signal_layout_avail; |
| 30086 |
layouttype4 loga_layout_type; |
| 30087 |
layoutiomode4 loga_iomode; |
| 30088 |
offset4 loga_offset; |
| 30089 |
length4 loga_length; |
| 30090 |
length4 loga_minlength; |
| 30091 |
stateid4 loga_stateid; |
| 30092 |
count4 loga_maxcount; |
| 30093 |
}; |
| 30094 |
|
| 30095 |
<span class="h4"><a class="selflink" id="section-18.43.2" href="#section-18.43.2">18.43.2</a>. RESULT</span> |
| 30096 |
|
| 30097 |
struct LAYOUTGET4resok { |
| 30098 |
bool logr_return_on_close; |
| 30099 |
stateid4 logr_stateid; |
| 30100 |
layout4 logr_layout<>; |
| 30101 |
}; |
| 30102 |
|
| 30103 |
union LAYOUTGET4res switch (nfsstat4 logr_status) { |
| 30104 |
case NFS4_OK: |
| 30105 |
LAYOUTGET4resok logr_resok4; |
| 30106 |
case NFS4ERR_LAYOUTTRYLATER: |
| 30107 |
bool logr_will_signal_layout_avail; |
| 30108 |
default: |
| 30109 |
void; |
| 30110 |
}; |
| 30111 |
|
| 30112 |
<span class="h4"><a class="selflink" id="section-18.43.3" href="#section-18.43.3">18.43.3</a>. DESCRIPTION</span> |
| 30113 |
|
| 30114 |
The LAYOUTGET operation requests a layout from the metadata server |
| 30115 |
for reading or writing the file given by the filehandle at the byte- |
| 30116 |
range specified by offset and length. Layouts are identified by the |
| 30117 |
client ID (derived from the session ID in the preceding SEQUENCE |
| 30118 |
operation), current filehandle, layout type (loga_layout_type), and |
| 30119 |
|
| 30120 |
|
| 30121 |
|
| 30122 |
|
| 30123 |
|
| 30124 |
<span class="grey">Shepler, et al. Standards Track [Page 538]</span></pre> |
| 30125 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-539" ></span> |
| 30126 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30127 |
|
| 30128 |
|
| 30129 |
the layout stateid (loga_stateid). The use of the loga_iomode field |
| 30130 |
depends upon the layout type, but should reflect the client's data |
| 30131 |
access intent. |
| 30132 |
|
| 30133 |
If the metadata server is in a grace period, and does not persist |
| 30134 |
layouts and device ID to device address mappings, then it MUST return |
| 30135 |
NFS4ERR_GRACE (see <a href="#section-8.4.2.1">Section 8.4.2.1</a>). |
| 30136 |
|
| 30137 |
The LAYOUTGET operation returns layout information for the specified |
| 30138 |
byte-range: a layout. The client actually specifies two ranges, both |
| 30139 |
starting at the offset in the loga_offset field. The first range is |
| 30140 |
between loga_offset and loga_offset + loga_length - 1 inclusive. |
| 30141 |
This range indicates the desired range the client wants the layout to |
| 30142 |
cover. The second range is between loga_offset and loga_offset + |
| 30143 |
loga_minlength - 1 inclusive. This range indicates the required |
| 30144 |
range the client needs the layout to cover. Thus, loga_minlength |
| 30145 |
MUST be less than or equal to loga_length. |
| 30146 |
|
| 30147 |
When a length field is set to NFS4_UINT64_MAX, this indicates a |
| 30148 |
desire (when loga_length is NFS4_UINT64_MAX) or requirement (when |
| 30149 |
loga_minlength is NFS4_UINT64_MAX) to get a layout from loga_offset |
| 30150 |
through the end-of-file, regardless of the file's length. |
| 30151 |
|
| 30152 |
The following rules govern the relationships among, and the minima |
| 30153 |
of, loga_length, loga_minlength, and loga_offset. |
| 30154 |
|
| 30155 |
o If loga_length is less than loga_minlength, the metadata server |
| 30156 |
MUST return NFS4ERR_INVAL. |
| 30157 |
|
| 30158 |
o If loga_minlength is zero, this is an indication to the metadata |
| 30159 |
server that the client desires any layout at offset loga_offset or |
| 30160 |
less that the metadata server has "readily available". Readily is |
| 30161 |
subjective, and depends on the layout type and the pNFS server |
| 30162 |
implementation. For example, some metadata servers might have to |
| 30163 |
pre-allocate stable storage when they receive a request for a |
| 30164 |
range of a file that goes beyond the file's current length. If |
| 30165 |
loga_minlength is zero and loga_length is greater than zero, this |
| 30166 |
tells the metadata server what range of the layout the client |
| 30167 |
would prefer to have. If loga_length and loga_minlength are both |
| 30168 |
zero, then the client is indicating that it desires a layout of |
| 30169 |
any length with the ending offset of the range no less than the |
| 30170 |
value specified loga_offset, and the starting offset at or below |
| 30171 |
loga_offset. If the metadata server does not have a layout that |
| 30172 |
is readily available, then it MUST return NFS4ERR_LAYOUTTRYLATER. |
| 30173 |
|
| 30174 |
o If the sum of loga_offset and loga_minlength exceeds |
| 30175 |
NFS4_UINT64_MAX, and loga_minlength is not NFS4_UINT64_MAX, the |
| 30176 |
error NFS4ERR_INVAL MUST result. |
| 30177 |
|
| 30178 |
|
| 30179 |
|
| 30180 |
<span class="grey">Shepler, et al. Standards Track [Page 539]</span></pre> |
| 30181 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-540" ></span> |
| 30182 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30183 |
|
| 30184 |
|
| 30185 |
o If the sum of loga_offset and loga_length exceeds NFS4_UINT64_MAX, |
| 30186 |
and loga_length is not NFS4_UINT64_MAX, the error NFS4ERR_INVAL |
| 30187 |
MUST result. |
| 30188 |
|
| 30189 |
After the metadata server has performed the above checks on |
| 30190 |
loga_offset, loga_minlength, and loga_offset, the metadata server |
| 30191 |
MUST return a layout according to the rules in Table 13. |
| 30192 |
|
| 30193 |
Acceptable layouts based on loga_minlength. Note: u64m = |
| 30194 |
NFS4_UINT64_MAX; a_off = loga_offset; a_minlen = loga_minlength. |
| 30195 |
|
| 30196 |
+-----------+-----------+----------+----------+---------------------+ |
| 30197 |
| Layout | Layout | Layout | Layout | Layout length of | |
| 30198 |
| iomode of | a_minlen | iomode | offset | reply | |
| 30199 |
| request | of | of reply | of reply | | |
| 30200 |
| | request | | | | |
| 30201 |
+-----------+-----------+----------+----------+---------------------+ |
| 30202 |
| _READ | u64m | MAY be | MUST be | MUST be >= file | |
| 30203 |
| | | _READ | <= a_off | length - layout | |
| 30204 |
| | | | | offset | |
| 30205 |
| _READ | u64m | MAY be | MUST be | MUST be u64m | |
| 30206 |
| | | _RW | <= a_off | | |
| 30207 |
| _READ | > 0 and < | MAY be | MUST be | MUST be >= MIN(file | |
| 30208 |
| | u64m | _READ | <= a_off | length, a_minlen + | |
| 30209 |
| | | | | a_off) - layout | |
| 30210 |
| | | | | offset | |
| 30211 |
| _READ | > 0 and < | MAY be | MUST be | MUST be >= a_off - | |
| 30212 |
| | u64m | _RW | <= a_off | layout offset + | |
| 30213 |
| | | | | a_minlen | |
| 30214 |
| _READ | 0 | MAY be | MUST be | MUST be > 0 | |
| 30215 |
| | | _READ | <= a_off | | |
| 30216 |
| _READ | 0 | MAY be | MUST be | MUST be > 0 | |
| 30217 |
| | | _RW | <= a_off | | |
| 30218 |
| _RW | u64m | MUST be | MUST be | MUST be u64m | |
| 30219 |
| | | _RW | <= a_off | | |
| 30220 |
| _RW | > 0 and < | MUST be | MUST be | MUST be >= a_off - | |
| 30221 |
| | u64m | _RW | <= a_off | layout offset + | |
| 30222 |
| | | | | a_minlen | |
| 30223 |
| _RW | 0 | MUST be | MUST be | MUST be > 0 | |
| 30224 |
| | | _RW | <= a_off | | |
| 30225 |
+-----------+-----------+----------+----------+---------------------+ |
| 30226 |
|
| 30227 |
Table 13 |
| 30228 |
|
| 30229 |
If loga_minlength is not zero and the metadata server cannot return a |
| 30230 |
layout according to the rules in Table 13, then the metadata server |
| 30231 |
MUST return the error NFS4ERR_BADLAYOUT. If loga_minlength is zero |
| 30232 |
and the metadata server cannot or will not return a layout according |
| 30233 |
|
| 30234 |
|
| 30235 |
|
| 30236 |
<span class="grey">Shepler, et al. Standards Track [Page 540]</span></pre> |
| 30237 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-541" ></span> |
| 30238 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30239 |
|
| 30240 |
|
| 30241 |
to the rules in Table 13, then the metadata server MUST return the |
| 30242 |
error NFS4ERR_LAYOUTTRYLATER. Assuming that loga_length is greater |
| 30243 |
than loga_minlength or equal to zero, the metadata server SHOULD |
| 30244 |
return a layout according to the rules in Table 14. |
| 30245 |
|
| 30246 |
Desired layouts based on loga_length. The rules of Table 13 MUST be |
| 30247 |
applied first. Note: u64m = NFS4_UINT64_MAX; a_off = loga_offset; |
| 30248 |
a_len = loga_length. |
| 30249 |
|
| 30250 |
+------------+------------+-----------+-----------+-----------------+ |
| 30251 |
| Layout | Layout | Layout | Layout | Layout length | |
| 30252 |
| iomode of | a_len of | iomode of | offset of | of reply | |
| 30253 |
| request | request | reply | reply | | |
| 30254 |
+------------+------------+-----------+-----------+-----------------+ |
| 30255 |
| _READ | u64m | MAY be | MUST be | SHOULD be u64m | |
| 30256 |
| | | _READ | <= a_off | | |
| 30257 |
| _READ | u64m | MAY be | MUST be | SHOULD be u64m | |
| 30258 |
| | | _RW | <= a_off | | |
| 30259 |
| _READ | > 0 and < | MAY be | MUST be | SHOULD be >= | |
| 30260 |
| | u64m | _READ | <= a_off | a_off - layout | |
| 30261 |
| | | | | offset + a_len | |
| 30262 |
| _READ | > 0 and < | MAY be | MUST be | SHOULD be >= | |
| 30263 |
| | u64m | _RW | <= a_off | a_off - layout | |
| 30264 |
| | | | | offset + a_len | |
| 30265 |
| _READ | 0 | MAY be | MUST be | SHOULD be > | |
| 30266 |
| | | _READ | <= a_off | a_off - layout | |
| 30267 |
| | | | | offset | |
| 30268 |
| _READ | 0 | MAY be | MUST be | SHOULD be > | |
| 30269 |
| | | _READ | <= a_off | a_off - layout | |
| 30270 |
| | | | | offset | |
| 30271 |
| _RW | u64m | MUST be | MUST be | SHOULD be u64m | |
| 30272 |
| | | _RW | <= a_off | | |
| 30273 |
| _RW | > 0 and < | MUST be | MUST be | SHOULD be >= | |
| 30274 |
| | u64m | _RW | <= a_off | a_off - layout | |
| 30275 |
| | | | | offset + a_len | |
| 30276 |
| _RW | 0 | MUST be | MUST be | SHOULD be > | |
| 30277 |
| | | _RW | <= a_off | a_off - layout | |
| 30278 |
| | | | | offset | |
| 30279 |
+------------+------------+-----------+-----------+-----------------+ |
| 30280 |
|
| 30281 |
Table 14 |
| 30282 |
|
| 30283 |
The loga_stateid field specifies a valid stateid. If a layout is not |
| 30284 |
currently held by the client, the loga_stateid field represents a |
| 30285 |
stateid reflecting the correspondingly valid open, byte-range lock, |
| 30286 |
or delegation stateid. Once a layout is held on the file by the |
| 30287 |
|
| 30288 |
|
| 30289 |
|
| 30290 |
|
| 30291 |
|
| 30292 |
<span class="grey">Shepler, et al. Standards Track [Page 541]</span></pre> |
| 30293 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-542" ></span> |
| 30294 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30295 |
|
| 30296 |
|
| 30297 |
client, the loga_stateid field MUST be a stateid as returned from a |
| 30298 |
previous LAYOUTGET or LAYOUTRETURN operation or provided by a |
| 30299 |
CB_LAYOUTRECALL operation (see <a href="#section-12.5.3">Section 12.5.3</a>). |
| 30300 |
|
| 30301 |
The loga_maxcount field specifies the maximum layout size (in bytes) |
| 30302 |
that the client can handle. If the size of the layout structure |
| 30303 |
exceeds the size specified by maxcount, the metadata server will |
| 30304 |
return the NFS4ERR_TOOSMALL error. |
| 30305 |
|
| 30306 |
The returned layout is expressed as an array, logr_layout, with each |
| 30307 |
element of type layout4. If a file has a single striping pattern, |
| 30308 |
then logr_layout SHOULD contain just one entry. Otherwise, if the |
| 30309 |
requested range overlaps more than one striping pattern, logr_layout |
| 30310 |
will contain the required number of entries. The elements of |
| 30311 |
logr_layout MUST be sorted in ascending order of the value of the |
| 30312 |
lo_offset field of each element. There MUST be no gaps or overlaps |
| 30313 |
in the range between two successive elements of logr_layout. The |
| 30314 |
lo_iomode field in each element of logr_layout MUST be the same. |
| 30315 |
|
| 30316 |
Table 13 and Table 14 both refer to a returned layout iomode, offset, |
| 30317 |
and length. Because the returned layout is encoded in the |
| 30318 |
logr_layout array, more description is required. |
| 30319 |
|
| 30320 |
iomode |
| 30321 |
|
| 30322 |
The value of the returned layout iomode listed in Table 13 and |
| 30323 |
Table 14 is equal to the value of the lo_iomode field in each |
| 30324 |
element of logr_layout. As shown in Table 13 and Table 14, the |
| 30325 |
metadata server MAY return a layout with an lo_iomode different |
| 30326 |
from the requested iomode (field loga_iomode of the request). If |
| 30327 |
it does so, it MUST ensure that the lo_iomode is more permissive |
| 30328 |
than the loga_iomode requested. For example, this behavior allows |
| 30329 |
an implementation to upgrade LAYOUTIOMODE4_READ requests to |
| 30330 |
LAYOUTIOMODE4_RW requests at its discretion, within the limits of |
| 30331 |
the layout type specific protocol. A lo_iomode of either |
| 30332 |
LAYOUTIOMODE4_READ or LAYOUTIOMODE4_RW MUST be returned. |
| 30333 |
|
| 30334 |
offset |
| 30335 |
|
| 30336 |
The value of the returned layout offset listed in Table 13 and |
| 30337 |
Table 14 is always equal to the lo_offset field of the first |
| 30338 |
element logr_layout. |
| 30339 |
|
| 30340 |
length |
| 30341 |
|
| 30342 |
When setting the value of the returned layout length, the |
| 30343 |
situation is complicated by the possibility that the special |
| 30344 |
layout length value NFS4_UINT64_MAX is involved. For a |
| 30345 |
|
| 30346 |
|
| 30347 |
|
| 30348 |
<span class="grey">Shepler, et al. Standards Track [Page 542]</span></pre> |
| 30349 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-543" ></span> |
| 30350 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30351 |
|
| 30352 |
|
| 30353 |
logr_layout array of N elements, the lo_length field in the first |
| 30354 |
N-1 elements MUST NOT be NFS4_UINT64_MAX. The lo_length field of |
| 30355 |
the last element of logr_layout can be NFS4_UINT64_MAX under some |
| 30356 |
conditions as described in the following list. |
| 30357 |
|
| 30358 |
* If an applicable rule of Table 13 states that the metadata |
| 30359 |
server MUST return a layout of length NFS4_UINT64_MAX, then the |
| 30360 |
lo_length field of the last element of logr_layout MUST be |
| 30361 |
NFS4_UINT64_MAX. |
| 30362 |
|
| 30363 |
* If an applicable rule of Table 13 states that the metadata |
| 30364 |
server MUST NOT return a layout of length NFS4_UINT64_MAX, then |
| 30365 |
the lo_length field of the last element of logr_layout MUST NOT |
| 30366 |
be NFS4_UINT64_MAX. |
| 30367 |
|
| 30368 |
* If an applicable rule of Table 14 states that the metadata |
| 30369 |
server SHOULD return a layout of length NFS4_UINT64_MAX, then |
| 30370 |
the lo_length field of the last element of logr_layout SHOULD |
| 30371 |
be NFS4_UINT64_MAX. |
| 30372 |
|
| 30373 |
* When the value of the returned layout length of Table 13 and |
| 30374 |
Table 14 is not NFS4_UINT64_MAX, then the returned layout |
| 30375 |
length is equal to the sum of the lo_length fields of each |
| 30376 |
element of logr_layout. |
| 30377 |
|
| 30378 |
The logr_return_on_close result field is a directive to return the |
| 30379 |
layout before closing the file. When the metadata server sets this |
| 30380 |
return value to TRUE, it MUST be prepared to recall the layout in the |
| 30381 |
case in which the client fails to return the layout before close. |
| 30382 |
For the metadata server that knows a layout must be returned before a |
| 30383 |
close of the file, this return value can be used to communicate the |
| 30384 |
desired behavior to the client and thus remove one extra step from |
| 30385 |
the client's and metadata server's interaction. |
| 30386 |
|
| 30387 |
The logr_stateid stateid is returned to the client for use in |
| 30388 |
subsequent layout related operations. See Sections <a href="#section-8.2">8.2</a>, <a href="#section-12.5.3">12.5.3</a>, and |
| 30389 |
12.5.5.2 for a further discussion and requirements. |
| 30390 |
|
| 30391 |
The format of the returned layout (lo_content) is specific to the |
| 30392 |
layout type. The value of the layout type (lo_content.loc_type) for |
| 30393 |
each of the elements of the array of layouts returned by the metadata |
| 30394 |
server (logr_layout) MUST be equal to the loga_layout_type specified |
| 30395 |
by the client. If it is not equal, the client SHOULD ignore the |
| 30396 |
response as invalid and behave as if the metadata server returned an |
| 30397 |
error, even if the client does have support for the layout type |
| 30398 |
returned. |
| 30399 |
|
| 30400 |
|
| 30401 |
|
| 30402 |
|
| 30403 |
|
| 30404 |
<span class="grey">Shepler, et al. Standards Track [Page 543]</span></pre> |
| 30405 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-544" ></span> |
| 30406 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30407 |
|
| 30408 |
|
| 30409 |
If neither the requested file nor its containing file system support |
| 30410 |
layouts, the metadata server MUST return NFS4ERR_LAYOUTUNAVAILABLE. |
| 30411 |
If the layout type is not supported, the metadata server MUST return |
| 30412 |
NFS4ERR_UNKNOWN_LAYOUTTYPE. If layouts are supported but no layout |
| 30413 |
matches the client provided layout identification, the metadata |
| 30414 |
server MUST return NFS4ERR_BADLAYOUT. If an invalid loga_iomode is |
| 30415 |
specified, or a loga_iomode of LAYOUTIOMODE4_ANY is specified, the |
| 30416 |
metadata server MUST return NFS4ERR_BADIOMODE. |
| 30417 |
|
| 30418 |
If the layout for the file is unavailable due to transient |
| 30419 |
conditions, e.g., file sharing prohibits layouts, the metadata server |
| 30420 |
MUST return NFS4ERR_LAYOUTTRYLATER. |
| 30421 |
|
| 30422 |
If the layout request is rejected due to an overlapping layout |
| 30423 |
recall, the metadata server MUST return NFS4ERR_RECALLCONFLICT. See |
| 30424 |
<a href="#section-12.5.5.2">Section 12.5.5.2</a> for details. |
| 30425 |
|
| 30426 |
If the layout conflicts with a mandatory byte-range lock held on the |
| 30427 |
file, and if the storage devices have no method of enforcing |
| 30428 |
mandatory locks, other than through the restriction of layouts, the |
| 30429 |
metadata server SHOULD return NFS4ERR_LOCKED. |
| 30430 |
|
| 30431 |
If client sets loga_signal_layout_avail to TRUE, then it is |
| 30432 |
registering with the client a "want" for a layout in the event the |
| 30433 |
layout cannot be obtained due to resource exhaustion. If the |
| 30434 |
metadata server supports and will honor the "want", the results will |
| 30435 |
have logr_will_signal_layout_avail set to TRUE. If so, the client |
| 30436 |
should expect a CB_RECALLABLE_OBJ_AVAIL operation to indicate that a |
| 30437 |
layout is available. |
| 30438 |
|
| 30439 |
On success, the current filehandle retains its value and the current |
| 30440 |
stateid is updated to match the value as returned in the results. |
| 30441 |
|
| 30442 |
<span class="h4"><a class="selflink" id="section-18.43.4" href="#section-18.43.4">18.43.4</a>. IMPLEMENTATION</span> |
| 30443 |
|
| 30444 |
Typically, LAYOUTGET will be called as part of a COMPOUND request |
| 30445 |
after an OPEN operation and results in the client having location |
| 30446 |
information for the file. This requires that loga_stateid be set to |
| 30447 |
the special stateid that tells the metadata server to use the current |
| 30448 |
stateid, which is set by OPEN (see <a href="#section-16.2.3.1.2">Section 16.2.3.1.2</a>). A client may |
| 30449 |
also hold a layout across multiple OPENs. The client specifies a |
| 30450 |
layout type that limits what kind of layout the metadata server will |
| 30451 |
return. This prevents metadata servers from granting layouts that |
| 30452 |
are unusable by the client. |
| 30453 |
|
| 30454 |
|
| 30455 |
|
| 30456 |
|
| 30457 |
|
| 30458 |
|
| 30459 |
|
| 30460 |
<span class="grey">Shepler, et al. Standards Track [Page 544]</span></pre> |
| 30461 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-545" ></span> |
| 30462 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30463 |
|
| 30464 |
|
| 30465 |
As indicated by Table 13 and Table 14, the specification of LAYOUTGET |
| 30466 |
allows a pNFS client and server considerable flexibility. A pNFS |
| 30467 |
client can take several strategies for sending LAYOUTGET. Some |
| 30468 |
examples are as follows. |
| 30469 |
|
| 30470 |
o If LAYOUTGET is preceded by OPEN in the same COMPOUND request and |
| 30471 |
the OPEN requests OPEN4_SHARE_ACCESS_READ access, the client might |
| 30472 |
opt to request a _READ layout with loga_offset set to zero, |
| 30473 |
loga_minlength set to zero, and loga_length set to |
| 30474 |
NFS4_UINT64_MAX. If the file has space allocated to it, that |
| 30475 |
space is striped over one or more storage devices, and there is |
| 30476 |
either no conflicting layout or the concept of a conflicting |
| 30477 |
layout does not apply to the pNFS server's layout type or |
| 30478 |
implementation, then the metadata server might return a layout |
| 30479 |
with a starting offset of zero, and a length equal to the length |
| 30480 |
of the file, if not NFS4_UINT64_MAX. If the length of the file is |
| 30481 |
not a multiple of the pNFS server's stripe width (see <a href="#section-13.2">Section 13.2</a> |
| 30482 |
for a formal definition), the metadata server might round up the |
| 30483 |
returned layout's length. |
| 30484 |
|
| 30485 |
o If LAYOUTGET is preceded by OPEN in the same COMPOUND request, and |
| 30486 |
the OPEN requests OPEN4_SHARE_ACCESS_WRITE access and does not |
| 30487 |
truncate the file, the client might opt to request a _RW layout |
| 30488 |
with loga_offset set to zero, loga_minlength set to zero, and |
| 30489 |
loga_length set to the file's current length (if known), or |
| 30490 |
NFS4_UINT64_MAX. As with the previous case, under some conditions |
| 30491 |
the metadata server might return a layout that covers the entire |
| 30492 |
length of the file or beyond. |
| 30493 |
|
| 30494 |
o This strategy is as above, but the OPEN truncates the file. In |
| 30495 |
this case, the client might anticipate it will be writing to the |
| 30496 |
file from offset zero, and so loga_offset and loga_minlength are |
| 30497 |
set to zero, and loga_length is set to the value of |
| 30498 |
threshold4_write_iosize. The metadata server might return a |
| 30499 |
layout from offset zero with a length at least as long as |
| 30500 |
threshold4_write_iosize. |
| 30501 |
|
| 30502 |
o A process on the client invokes a request to read from offset |
| 30503 |
10000 for length 50000. The client is using buffered I/O, and has |
| 30504 |
buffer sizes of 4096 bytes. The client intends to map the request |
| 30505 |
of the process into a series of READ requests starting at offset |
| 30506 |
8192. The end offset needs to be higher than 10000 + 50000 = |
| 30507 |
60000, and the next offset that is a multiple of 4096 is 61440. |
| 30508 |
The difference between 61440 and that starting offset of the |
| 30509 |
layout is 53248 (which is the product of 4096 and 15). The value |
| 30510 |
of threshold4_read_iosize is less than 53248, so the client sends |
| 30511 |
a LAYOUTGET request with loga_offset set to 8192, loga_minlength |
| 30512 |
set to 53248, and loga_length set to the file's length (if known) |
| 30513 |
|
| 30514 |
|
| 30515 |
|
| 30516 |
<span class="grey">Shepler, et al. Standards Track [Page 545]</span></pre> |
| 30517 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-546" ></span> |
| 30518 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30519 |
|
| 30520 |
|
| 30521 |
minus 8192 or NFS4_UINT64_MAX (if the file's length is not known). |
| 30522 |
Since this LAYOUTGET request exceeds the metadata server's |
| 30523 |
threshold, it grants the layout, possibly with an initial offset |
| 30524 |
of zero, with an end offset of at least 8192 + 53248 - 1 = 61439, |
| 30525 |
but preferably a layout with an offset aligned on the stripe width |
| 30526 |
and a length that is a multiple of the stripe width. |
| 30527 |
|
| 30528 |
o This strategy is as above, but the client is not using buffered |
| 30529 |
I/O, and instead all internal I/O requests are sent directly to |
| 30530 |
the server. The LAYOUTGET request has loga_offset equal to 10000 |
| 30531 |
and loga_minlength set to 50000. The value of loga_length is set |
| 30532 |
to the length of the file. The metadata server is free to return |
| 30533 |
a layout that fully overlaps the requested range, with a starting |
| 30534 |
offset and length aligned on the stripe width. |
| 30535 |
|
| 30536 |
o Again, a process on the client invokes a request to read from |
| 30537 |
offset 10000 for length 50000 (i.e. a range with a starting offset |
| 30538 |
of 10000 and an ending offset of 69999), and buffered I/O is in |
| 30539 |
use. The client is expecting that the server might not be able to |
| 30540 |
return the layout for the full I/O range. The client intends to |
| 30541 |
map the request of the process into a series of thirteen READ |
| 30542 |
requests starting at offset 8192, each with length 4096, with a |
| 30543 |
total length of 53248 (which equals 13 * 4096), which fully |
| 30544 |
contains the range that client's process wants to read. Because |
| 30545 |
the value of threshold4_read_iosize is equal to 4096, it is |
| 30546 |
practical and reasonable for the client to use several LAYOUTGET |
| 30547 |
operations to complete the series of READs. The client sends a |
| 30548 |
LAYOUTGET request with loga_offset set to 8192, loga_minlength set |
| 30549 |
to 4096, and loga_length set to 53248 or higher. The server will |
| 30550 |
grant a layout possibly with an initial offset of zero, with an |
| 30551 |
end offset of at least 8192 + 4096 - 1 = 12287, but preferably a |
| 30552 |
layout with an offset aligned on the stripe width and a length |
| 30553 |
that is a multiple of the stripe width. This will allow the |
| 30554 |
client to make forward progress, possibly sending more LAYOUTGET |
| 30555 |
operations for the remainder of the range. |
| 30556 |
|
| 30557 |
o An NFS client detects a sequential read pattern, and so sends a |
| 30558 |
LAYOUTGET operation that goes well beyond any current or pending |
| 30559 |
read requests to the server. The server might likewise detect |
| 30560 |
this pattern, and grant the LAYOUTGET request. Once the client |
| 30561 |
reads from an offset of the file that represents 50% of the way |
| 30562 |
through the range of the last layout it received, in order to |
| 30563 |
avoid stalling I/O that would wait for a layout, the client sends |
| 30564 |
more operations from an offset of the file that represents 50% of |
| 30565 |
the way through the last layout it received. The client continues |
| 30566 |
to request layouts with byte-ranges that are well in advance of |
| 30567 |
the byte-ranges of recent and/or read requests of processes |
| 30568 |
running on the client. |
| 30569 |
|
| 30570 |
|
| 30571 |
|
| 30572 |
<span class="grey">Shepler, et al. Standards Track [Page 546]</span></pre> |
| 30573 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-547" ></span> |
| 30574 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30575 |
|
| 30576 |
|
| 30577 |
o This strategy is as above, but the client fails to detect the |
| 30578 |
pattern, but the server does. The next time the metadata server |
| 30579 |
gets a LAYOUTGET, it returns a layout with a length that is well |
| 30580 |
beyond loga_minlength. |
| 30581 |
|
| 30582 |
o A client is using buffered I/O, and has a long queue of write- |
| 30583 |
behinds to process and also detects a sequential write pattern. |
| 30584 |
It sends a LAYOUTGET for a layout that spans the range of the |
| 30585 |
queued write-behinds and well beyond, including ranges beyond the |
| 30586 |
filer's current length. The client continues to send LAYOUTGET |
| 30587 |
operations once the write-behind queue reaches 50% of the maximum |
| 30588 |
queue length. |
| 30589 |
|
| 30590 |
Once the client has obtained a layout referring to a particular |
| 30591 |
device ID, the metadata server MUST NOT delete the device ID until |
| 30592 |
the layout is returned or revoked. |
| 30593 |
|
| 30594 |
CB_NOTIFY_DEVICEID can race with LAYOUTGET. One race scenario is |
| 30595 |
that LAYOUTGET returns a device ID for which the client does not have |
| 30596 |
device address mappings, and the metadata server sends a |
| 30597 |
CB_NOTIFY_DEVICEID to add the device ID to the client's awareness and |
| 30598 |
meanwhile the client sends GETDEVICEINFO on the device ID. This |
| 30599 |
scenario is discussed in <a href="#section-18.40.4">Section 18.40.4</a>. Another scenario is that |
| 30600 |
the CB_NOTIFY_DEVICEID is processed by the client before it processes |
| 30601 |
the results from LAYOUTGET. The client will send a GETDEVICEINFO on |
| 30602 |
the device ID. If the results from GETDEVICEINFO are received before |
| 30603 |
the client gets results from LAYOUTGET, then there is no longer a |
| 30604 |
race. If the results from LAYOUTGET are received before the results |
| 30605 |
from GETDEVICEINFO, the client can either wait for results of |
| 30606 |
GETDEVICEINFO or send another one to get possibly more up-to-date |
| 30607 |
device address mappings for the device ID. |
| 30608 |
|
| 30609 |
<span class="h3"><a class="selflink" id="section-18.44" href="#section-18.44">18.44</a>. Operation 51: LAYOUTRETURN - Release Layout Information</span> |
| 30610 |
|
| 30611 |
<span class="h4"><a class="selflink" id="section-18.44.1" href="#section-18.44.1">18.44.1</a>. ARGUMENT</span> |
| 30612 |
|
| 30613 |
/* Constants used for LAYOUTRETURN and CB_LAYOUTRECALL */ |
| 30614 |
const LAYOUT4_RET_REC_FILE = 1; |
| 30615 |
const LAYOUT4_RET_REC_FSID = 2; |
| 30616 |
const LAYOUT4_RET_REC_ALL = 3; |
| 30617 |
|
| 30618 |
enum layoutreturn_type4 { |
| 30619 |
LAYOUTRETURN4_FILE = LAYOUT4_RET_REC_FILE, |
| 30620 |
LAYOUTRETURN4_FSID = LAYOUT4_RET_REC_FSID, |
| 30621 |
LAYOUTRETURN4_ALL = LAYOUT4_RET_REC_ALL |
| 30622 |
}; |
| 30623 |
|
| 30624 |
|
| 30625 |
|
| 30626 |
|
| 30627 |
|
| 30628 |
<span class="grey">Shepler, et al. Standards Track [Page 547]</span></pre> |
| 30629 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-548" ></span> |
| 30630 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30631 |
|
| 30632 |
|
| 30633 |
struct layoutreturn_file4 { |
| 30634 |
offset4 lrf_offset; |
| 30635 |
length4 lrf_length; |
| 30636 |
stateid4 lrf_stateid; |
| 30637 |
/* layouttype4 specific data */ |
| 30638 |
opaque lrf_body<>; |
| 30639 |
}; |
| 30640 |
|
| 30641 |
union layoutreturn4 switch(layoutreturn_type4 lr_returntype) { |
| 30642 |
case LAYOUTRETURN4_FILE: |
| 30643 |
layoutreturn_file4 lr_layout; |
| 30644 |
default: |
| 30645 |
void; |
| 30646 |
}; |
| 30647 |
|
| 30648 |
|
| 30649 |
struct LAYOUTRETURN4args { |
| 30650 |
/* CURRENT_FH: file */ |
| 30651 |
bool lora_reclaim; |
| 30652 |
layouttype4 lora_layout_type; |
| 30653 |
layoutiomode4 lora_iomode; |
| 30654 |
layoutreturn4 lora_layoutreturn; |
| 30655 |
}; |
| 30656 |
|
| 30657 |
<span class="h4"><a class="selflink" id="section-18.44.2" href="#section-18.44.2">18.44.2</a>. RESULT</span> |
| 30658 |
|
| 30659 |
union layoutreturn_stateid switch (bool lrs_present) { |
| 30660 |
case TRUE: |
| 30661 |
stateid4 lrs_stateid; |
| 30662 |
case FALSE: |
| 30663 |
void; |
| 30664 |
}; |
| 30665 |
|
| 30666 |
union LAYOUTRETURN4res switch (nfsstat4 lorr_status) { |
| 30667 |
case NFS4_OK: |
| 30668 |
layoutreturn_stateid lorr_stateid; |
| 30669 |
default: |
| 30670 |
void; |
| 30671 |
}; |
| 30672 |
|
| 30673 |
<span class="h4"><a class="selflink" id="section-18.44.3" href="#section-18.44.3">18.44.3</a>. DESCRIPTION</span> |
| 30674 |
|
| 30675 |
This operation returns from the client to the server one or more |
| 30676 |
layouts represented by the client ID (derived from the session ID in |
| 30677 |
the preceding SEQUENCE operation), lora_layout_type, and lora_iomode. |
| 30678 |
When lr_returntype is LAYOUTRETURN4_FILE, the returned layout is |
| 30679 |
further identified by the current filehandle, lrf_offset, lrf_length, |
| 30680 |
and lrf_stateid. If the lrf_length field is NFS4_UINT64_MAX, all |
| 30681 |
|
| 30682 |
|
| 30683 |
|
| 30684 |
<span class="grey">Shepler, et al. Standards Track [Page 548]</span></pre> |
| 30685 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-549" ></span> |
| 30686 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30687 |
|
| 30688 |
|
| 30689 |
bytes of the layout, starting at lrf_offset, are returned. When |
| 30690 |
lr_returntype is LAYOUTRETURN4_FSID, the current filehandle is used |
| 30691 |
to identify the file system and all layouts matching the client ID, |
| 30692 |
the fsid of the file system, lora_layout_type, and lora_iomode are |
| 30693 |
returned. When lr_returntype is LAYOUTRETURN4_ALL, all layouts |
| 30694 |
matching the client ID, lora_layout_type, and lora_iomode are |
| 30695 |
returned and the current filehandle is not used. After this call, |
| 30696 |
the client MUST NOT use the returned layout(s) and the associated |
| 30697 |
storage protocol to access the file data. |
| 30698 |
|
| 30699 |
If the set of layouts designated in the case of LAYOUTRETURN4_FSID or |
| 30700 |
LAYOUTRETURN4_ALL is empty, then no error results. In the case of |
| 30701 |
LAYOUTRETURN4_FILE, the byte-range specified is returned even if it |
| 30702 |
is a subdivision of a layout previously obtained with LAYOUTGET, a |
| 30703 |
combination of multiple layouts previously obtained with LAYOUTGET, |
| 30704 |
or a combination including some layouts previously obtained with |
| 30705 |
LAYOUTGET, and one or more subdivisions of such layouts. When the |
| 30706 |
byte-range does not designate any bytes for which a layout is held |
| 30707 |
for the specified file, client ID, layout type and mode, no error |
| 30708 |
results. See <a href="#section-12.5.5.2.1.5">Section 12.5.5.2.1.5</a> for considerations with "bulk" |
| 30709 |
return of layouts. |
| 30710 |
|
| 30711 |
The layout being returned may be a subset or superset of a layout |
| 30712 |
specified by CB_LAYOUTRECALL. However, if it is a subset, the recall |
| 30713 |
is not complete until the full recalled scope has been returned. |
| 30714 |
Recalled scope refers to the byte-range in the case of |
| 30715 |
LAYOUTRETURN4_FILE, the use of LAYOUTRETURN4_FSID, or the use of |
| 30716 |
LAYOUTRETURN4_ALL. There must be a LAYOUTRETURN with a matching |
| 30717 |
scope to complete the return even if all current layout ranges have |
| 30718 |
been previously individually returned. |
| 30719 |
|
| 30720 |
For all lr_returntype values, an iomode of LAYOUTIOMODE4_ANY |
| 30721 |
specifies that all layouts that match the other arguments to |
| 30722 |
LAYOUTRETURN (i.e., client ID, lora_layout_type, and one of current |
| 30723 |
filehandle and range; fsid derived from current filehandle; or |
| 30724 |
LAYOUTRETURN4_ALL) are being returned. |
| 30725 |
|
| 30726 |
In the case that lr_returntype is LAYOUTRETURN4_FILE, the lrf_stateid |
| 30727 |
provided by the client is a layout stateid as returned from previous |
| 30728 |
layout operations. Note that the "seqid" field of lrf_stateid MUST |
| 30729 |
NOT be zero. See Sections <a href="#section-8.2">8.2</a>, <a href="#section-12.5.3">12.5.3</a>, and <a href="#section-12.5.5.2">12.5.5.2</a> for a further |
| 30730 |
discussion and requirements. |
| 30731 |
|
| 30732 |
Return of a layout or all layouts does not invalidate the mapping of |
| 30733 |
storage device ID to a storage device address. The mapping remains |
| 30734 |
in effect until specifically changed or deleted via device ID |
| 30735 |
notification callbacks. Of course if there are no remaining layouts |
| 30736 |
|
| 30737 |
|
| 30738 |
|
| 30739 |
|
| 30740 |
<span class="grey">Shepler, et al. Standards Track [Page 549]</span></pre> |
| 30741 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-550" ></span> |
| 30742 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30743 |
|
| 30744 |
|
| 30745 |
that refer to a previously used device ID, the server is free to |
| 30746 |
delete a device ID without a notification callback, which will be the |
| 30747 |
case when notifications are not in effect. |
| 30748 |
|
| 30749 |
If the lora_reclaim field is set to TRUE, the client is attempting to |
| 30750 |
return a layout that was acquired before the restart of the metadata |
| 30751 |
server during the metadata server's grace period. When returning |
| 30752 |
layouts that were acquired during the metadata server's grace period, |
| 30753 |
the client MUST set the lora_reclaim field to FALSE. The |
| 30754 |
lora_reclaim field MUST be set to FALSE also when lr_layoutreturn is |
| 30755 |
LAYOUTRETURN4_FSID or LAYOUTRETURN4_ALL. See LAYOUTCOMMIT |
| 30756 |
(<a href="#section-18.42">Section 18.42</a>) for more details. |
| 30757 |
|
| 30758 |
Layouts may be returned when recalled or voluntarily (i.e., before |
| 30759 |
the server has recalled them). In either case, the client must |
| 30760 |
properly propagate state changed under the context of the layout to |
| 30761 |
the storage device(s) or to the metadata server before returning the |
| 30762 |
layout. |
| 30763 |
|
| 30764 |
If the client returns the layout in response to a CB_LAYOUTRECALL |
| 30765 |
where the lor_recalltype field of the clora_recall field was |
| 30766 |
LAYOUTRECALL4_FILE, the client should use the lor_stateid value from |
| 30767 |
CB_LAYOUTRECALL as the value for lrf_stateid. Otherwise, it should |
| 30768 |
use logr_stateid (from a previous LAYOUTGET result) or lorr_stateid |
| 30769 |
(from a previous LAYRETURN result). This is done to indicate the |
| 30770 |
point in time (in terms of layout stateid transitions) when the |
| 30771 |
recall was sent. The client uses the precise lora_recallstateid |
| 30772 |
value and MUST NOT set the stateid's seqid to zero; otherwise, |
| 30773 |
NFS4ERR_BAD_STATEID MUST be returned. NFS4ERR_OLD_STATEID can be |
| 30774 |
returned if the client is using an old seqid, and the server knows |
| 30775 |
the client should not be using the old seqid. For example, the |
| 30776 |
client uses the seqid on slot 1 of the session, receives the response |
| 30777 |
with the new seqid, and uses the slot to send another request with |
| 30778 |
the old seqid. |
| 30779 |
|
| 30780 |
If a client fails to return a layout in a timely manner, then the |
| 30781 |
metadata server SHOULD use its control protocol with the storage |
| 30782 |
devices to fence the client from accessing the data referenced by the |
| 30783 |
layout. See <a href="#section-12.5.5">Section 12.5.5</a> for more details. |
| 30784 |
|
| 30785 |
If the LAYOUTRETURN request sets the lora_reclaim field to TRUE after |
| 30786 |
the metadata server's grace period, NFS4ERR_NO_GRACE is returned. |
| 30787 |
|
| 30788 |
If the LAYOUTRETURN request sets the lora_reclaim field to TRUE and |
| 30789 |
lr_returntype is set to LAYOUTRETURN4_FSID or LAYOUTRETURN4_ALL, |
| 30790 |
NFS4ERR_INVAL is returned. |
| 30791 |
|
| 30792 |
|
| 30793 |
|
| 30794 |
|
| 30795 |
|
| 30796 |
<span class="grey">Shepler, et al. Standards Track [Page 550]</span></pre> |
| 30797 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-551" ></span> |
| 30798 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30799 |
|
| 30800 |
|
| 30801 |
If the client sets the lr_returntype field to LAYOUTRETURN4_FILE, |
| 30802 |
then the lrs_stateid field will represent the layout stateid as |
| 30803 |
updated for this operation's processing; the current stateid will |
| 30804 |
also be updated to match the returned value. If the last byte of any |
| 30805 |
layout for the current file, client ID, and layout type is being |
| 30806 |
returned and there are no remaining pending CB_LAYOUTRECALL |
| 30807 |
operations for which a LAYOUTRETURN operation must be done, |
| 30808 |
lrs_present MUST be FALSE, and no stateid will be returned. In |
| 30809 |
addition, the COMPOUND request's current stateid will be set to the |
| 30810 |
all-zeroes special stateid (see <a href="#section-16.2.3.1.2">Section 16.2.3.1.2</a>). The server MUST |
| 30811 |
reject with NFS4ERR_BAD_STATEID any further use of the current |
| 30812 |
stateid in that COMPOUND until the current stateid is re-established |
| 30813 |
by a later stateid-returning operation. |
| 30814 |
|
| 30815 |
On success, the current filehandle retains its value. |
| 30816 |
|
| 30817 |
If the EXCHGID4_FLAG_BIND_PRINC_STATEID capability is set on the |
| 30818 |
client ID (see <a href="#section-18.35">Section 18.35</a>), the server will require that the |
| 30819 |
principal, security flavor, and if applicable, the GSS mechanism, |
| 30820 |
combination that acquired the layout also be the one to send |
| 30821 |
LAYOUTRETURN. This might not be possible if credentials for the |
| 30822 |
principal are no longer available. The server will allow the machine |
| 30823 |
credential or SSV credential (see <a href="#section-18.35">Section 18.35</a>) to send LAYOUTRETURN |
| 30824 |
if LAYOUTRETURN's operation code was set in the spo_must_allow result |
| 30825 |
of EXCHANGE_ID. |
| 30826 |
|
| 30827 |
<span class="h4"><a class="selflink" id="section-18.44.4" href="#section-18.44.4">18.44.4</a>. IMPLEMENTATION</span> |
| 30828 |
|
| 30829 |
The final LAYOUTRETURN operation in response to a CB_LAYOUTRECALL |
| 30830 |
callback MUST be serialized with any outstanding, intersecting |
| 30831 |
LAYOUTRETURN operations. Note that it is possible that while a |
| 30832 |
client is returning the layout for some recalled range, the server |
| 30833 |
may recall a superset of that range (e.g., LAYOUTRECALL4_ALL); the |
| 30834 |
final return operation for the latter must block until the former |
| 30835 |
layout recall is done. |
| 30836 |
|
| 30837 |
Returning all layouts in a file system using LAYOUTRETURN4_FSID is |
| 30838 |
typically done in response to a CB_LAYOUTRECALL for that file system |
| 30839 |
as the final return operation. Similarly, LAYOUTRETURN4_ALL is used |
| 30840 |
in response to a recall callback for all layouts. It is possible |
| 30841 |
that the client already returned some outstanding layouts via |
| 30842 |
individual LAYOUTRETURN calls and the call for LAYOUTRETURN4_FSID or |
| 30843 |
LAYOUTRETURN4_ALL marks the end of the LAYOUTRETURN sequence. See |
| 30844 |
<a href="#section-12.5.5.1">Section 12.5.5.1</a> for more details. |
| 30845 |
|
| 30846 |
Once the client has returned all layouts referring to a particular |
| 30847 |
device ID, the server MAY delete the device ID. |
| 30848 |
|
| 30849 |
|
| 30850 |
|
| 30851 |
|
| 30852 |
<span class="grey">Shepler, et al. Standards Track [Page 551]</span></pre> |
| 30853 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-552" ></span> |
| 30854 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30855 |
|
| 30856 |
|
| 30857 |
<span class="h3"><a class="selflink" id="section-18.45" href="#section-18.45">18.45</a>. Operation 52: SECINFO_NO_NAME - Get Security on Unnamed Object</span> |
| 30858 |
|
| 30859 |
<span class="h4"><a class="selflink" id="section-18.45.1" href="#section-18.45.1">18.45.1</a>. ARGUMENT</span> |
| 30860 |
|
| 30861 |
enum secinfo_style4 { |
| 30862 |
SECINFO_STYLE4_CURRENT_FH = 0, |
| 30863 |
SECINFO_STYLE4_PARENT = 1 |
| 30864 |
}; |
| 30865 |
|
| 30866 |
/* CURRENT_FH: object or child directory */ |
| 30867 |
typedef secinfo_style4 SECINFO_NO_NAME4args; |
| 30868 |
|
| 30869 |
|
| 30870 |
<span class="h4"><a class="selflink" id="section-18.45.2" href="#section-18.45.2">18.45.2</a>. RESULT</span> |
| 30871 |
|
| 30872 |
/* CURRENTFH: consumed if status is NFS4_OK */ |
| 30873 |
typedef SECINFO4res SECINFO_NO_NAME4res; |
| 30874 |
|
| 30875 |
|
| 30876 |
<span class="h4"><a class="selflink" id="section-18.45.3" href="#section-18.45.3">18.45.3</a>. DESCRIPTION</span> |
| 30877 |
|
| 30878 |
Like the SECINFO operation, SECINFO_NO_NAME is used by the client to |
| 30879 |
obtain a list of valid RPC authentication flavors for a specific file |
| 30880 |
object. Unlike SECINFO, SECINFO_NO_NAME only works with objects that |
| 30881 |
are accessed by filehandle. |
| 30882 |
|
| 30883 |
There are two styles of SECINFO_NO_NAME, as determined by the value |
| 30884 |
of the secinfo_style4 enumeration. If SECINFO_STYLE4_CURRENT_FH is |
| 30885 |
passed, then SECINFO_NO_NAME is querying for the required security |
| 30886 |
for the current filehandle. If SECINFO_STYLE4_PARENT is passed, then |
| 30887 |
SECINFO_NO_NAME is querying for the required security of the current |
| 30888 |
filehandle's parent. If the style selected is SECINFO_STYLE4_PARENT, |
| 30889 |
then SECINFO should apply the same access methodology used for |
| 30890 |
LOOKUPP when evaluating the traversal to the parent directory. |
| 30891 |
Therefore, if the requester does not have the appropriate access to |
| 30892 |
LOOKUPP the parent, then SECINFO_NO_NAME must behave the same way and |
| 30893 |
return NFS4ERR_ACCESS. |
| 30894 |
|
| 30895 |
If PUTFH, PUTPUBFH, PUTROOTFH, or RESTOREFH returns NFS4ERR_WRONGSEC, |
| 30896 |
then the client resolves the situation by sending a COMPOUND request |
| 30897 |
that consists of PUTFH, PUTPUBFH, or PUTROOTFH immediately followed |
| 30898 |
by SECINFO_NO_NAME, style SECINFO_STYLE4_CURRENT_FH. See <a href="#section-2.6">Section 2.6</a> |
| 30899 |
for instructions on dealing with NFS4ERR_WRONGSEC error returns from |
| 30900 |
PUTFH, PUTROOTFH, PUTPUBFH, or RESTOREFH. |
| 30901 |
|
| 30902 |
If SECINFO_STYLE4_PARENT is specified and there is no parent |
| 30903 |
directory, SECINFO_NO_NAME MUST return NFS4ERR_NOENT. |
| 30904 |
|
| 30905 |
|
| 30906 |
|
| 30907 |
|
| 30908 |
<span class="grey">Shepler, et al. Standards Track [Page 552]</span></pre> |
| 30909 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-553" ></span> |
| 30910 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30911 |
|
| 30912 |
|
| 30913 |
On success, the current filehandle is consumed (see |
| 30914 |
<a href="#section-2.6.3.1.1.8">Section 2.6.3.1.1.8</a>), and if the next operation after SECINFO_NO_NAME |
| 30915 |
tries to use the current filehandle, that operation will fail with |
| 30916 |
the status NFS4ERR_NOFILEHANDLE. |
| 30917 |
|
| 30918 |
Everything else about SECINFO_NO_NAME is the same as SECINFO. See |
| 30919 |
the discussion on SECINFO (<a href="#section-18.29.3">Section 18.29.3</a>). |
| 30920 |
|
| 30921 |
<span class="h4"><a class="selflink" id="section-18.45.4" href="#section-18.45.4">18.45.4</a>. IMPLEMENTATION</span> |
| 30922 |
|
| 30923 |
See the discussion on SECINFO (<a href="#section-18.29.4">Section 18.29.4</a>). |
| 30924 |
|
| 30925 |
<span class="h3"><a class="selflink" id="section-18.46" href="#section-18.46">18.46</a>. Operation 53: SEQUENCE - Supply Per-Procedure Sequencing and</span> |
| 30926 |
<span class="h3"> Control</span> |
| 30927 |
|
| 30928 |
<span class="h4"><a class="selflink" id="section-18.46.1" href="#section-18.46.1">18.46.1</a>. ARGUMENT</span> |
| 30929 |
|
| 30930 |
struct SEQUENCE4args { |
| 30931 |
sessionid4 sa_sessionid; |
| 30932 |
sequenceid4 sa_sequenceid; |
| 30933 |
slotid4 sa_slotid; |
| 30934 |
slotid4 sa_highest_slotid; |
| 30935 |
bool sa_cachethis; |
| 30936 |
}; |
| 30937 |
|
| 30938 |
<span class="h4"><a class="selflink" id="section-18.46.2" href="#section-18.46.2">18.46.2</a>. RESULT</span> |
| 30939 |
|
| 30940 |
const SEQ4_STATUS_CB_PATH_DOWN = 0x00000001; |
| 30941 |
const SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRING = 0x00000002; |
| 30942 |
const SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRED = 0x00000004; |
| 30943 |
const SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED = 0x00000008; |
| 30944 |
const SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED = 0x00000010; |
| 30945 |
const SEQ4_STATUS_ADMIN_STATE_REVOKED = 0x00000020; |
| 30946 |
const SEQ4_STATUS_RECALLABLE_STATE_REVOKED = 0x00000040; |
| 30947 |
const SEQ4_STATUS_LEASE_MOVED = 0x00000080; |
| 30948 |
const SEQ4_STATUS_RESTART_RECLAIM_NEEDED = 0x00000100; |
| 30949 |
const SEQ4_STATUS_CB_PATH_DOWN_SESSION = 0x00000200; |
| 30950 |
const SEQ4_STATUS_BACKCHANNEL_FAULT = 0x00000400; |
| 30951 |
const SEQ4_STATUS_DEVID_CHANGED = 0x00000800; |
| 30952 |
const SEQ4_STATUS_DEVID_DELETED = 0x00001000; |
| 30953 |
|
| 30954 |
|
| 30955 |
|
| 30956 |
|
| 30957 |
|
| 30958 |
|
| 30959 |
|
| 30960 |
|
| 30961 |
|
| 30962 |
|
| 30963 |
|
| 30964 |
<span class="grey">Shepler, et al. Standards Track [Page 553]</span></pre> |
| 30965 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-554" ></span> |
| 30966 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 30967 |
|
| 30968 |
|
| 30969 |
struct SEQUENCE4resok { |
| 30970 |
sessionid4 sr_sessionid; |
| 30971 |
sequenceid4 sr_sequenceid; |
| 30972 |
slotid4 sr_slotid; |
| 30973 |
slotid4 sr_highest_slotid; |
| 30974 |
slotid4 sr_target_highest_slotid; |
| 30975 |
uint32_t sr_status_flags; |
| 30976 |
}; |
| 30977 |
|
| 30978 |
union SEQUENCE4res switch (nfsstat4 sr_status) { |
| 30979 |
case NFS4_OK: |
| 30980 |
SEQUENCE4resok sr_resok4; |
| 30981 |
default: |
| 30982 |
void; |
| 30983 |
}; |
| 30984 |
|
| 30985 |
<span class="h4"><a class="selflink" id="section-18.46.3" href="#section-18.46.3">18.46.3</a>. DESCRIPTION</span> |
| 30986 |
|
| 30987 |
The SEQUENCE operation is used by the server to implement session |
| 30988 |
request control and the reply cache semantics. |
| 30989 |
|
| 30990 |
SEQUENCE MUST appear as the first operation of any COMPOUND in which |
| 30991 |
it appears. The error NFS4ERR_SEQUENCE_POS will be returned when it |
| 30992 |
is found in any position in a COMPOUND beyond the first. Operations |
| 30993 |
other than SEQUENCE, BIND_CONN_TO_SESSION, EXCHANGE_ID, |
| 30994 |
CREATE_SESSION, and DESTROY_SESSION, MUST NOT appear as the first |
| 30995 |
operation in a COMPOUND. Such operations MUST yield the error |
| 30996 |
NFS4ERR_OP_NOT_IN_SESSION if they do appear at the start of a |
| 30997 |
COMPOUND. |
| 30998 |
|
| 30999 |
If SEQUENCE is received on a connection not associated with the |
| 31000 |
session via CREATE_SESSION or BIND_CONN_TO_SESSION, and connection |
| 31001 |
association enforcement is enabled (see <a href="#section-18.35">Section 18.35</a>), then the |
| 31002 |
server returns NFS4ERR_CONN_NOT_BOUND_TO_SESSION. |
| 31003 |
|
| 31004 |
The sa_sessionid argument identifies the session to which this |
| 31005 |
request applies. The sr_sessionid result MUST equal sa_sessionid. |
| 31006 |
|
| 31007 |
The sa_slotid argument is the index in the reply cache for the |
| 31008 |
request. The sa_sequenceid field is the sequence number of the |
| 31009 |
request for the reply cache entry (slot). The sr_slotid result MUST |
| 31010 |
equal sa_slotid. The sr_sequenceid result MUST equal sa_sequenceid. |
| 31011 |
|
| 31012 |
The sa_highest_slotid argument is the highest slot ID for which the |
| 31013 |
client has a request outstanding; it could be equal to sa_slotid. |
| 31014 |
The server returns two "highest_slotid" values: sr_highest_slotid and |
| 31015 |
sr_target_highest_slotid. The former is the highest slot ID the |
| 31016 |
server will accept in future SEQUENCE operation, and SHOULD NOT be |
| 31017 |
|
| 31018 |
|
| 31019 |
|
| 31020 |
<span class="grey">Shepler, et al. Standards Track [Page 554]</span></pre> |
| 31021 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-555" ></span> |
| 31022 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31023 |
|
| 31024 |
|
| 31025 |
less than the value of sa_highest_slotid (but see <a href="#section-2.10.6.1">Section 2.10.6.1</a> |
| 31026 |
for an exception). The latter is the highest slot ID the server |
| 31027 |
would prefer the client use on a future SEQUENCE operation. |
| 31028 |
|
| 31029 |
If sa_cachethis is TRUE, then the client is requesting that the |
| 31030 |
server cache the entire reply in the server's reply cache; therefore, |
| 31031 |
the server MUST cache the reply (see <a href="#section-2.10.6.1.3">Section 2.10.6.1.3</a>). The server |
| 31032 |
MAY cache the reply if sa_cachethis is FALSE. If the server does not |
| 31033 |
cache the entire reply, it MUST still record that it executed the |
| 31034 |
request at the specified slot and sequence ID. |
| 31035 |
|
| 31036 |
The response to the SEQUENCE operation contains a word of status |
| 31037 |
flags (sr_status_flags) that can provide to the client information |
| 31038 |
related to the status of the client's lock state and communications |
| 31039 |
paths. Note that any status bits relating to lock state MAY be reset |
| 31040 |
when lock state is lost due to a server restart (even if the session |
| 31041 |
is persistent across restarts; session persistence does not imply |
| 31042 |
lock state persistence) or the establishment of a new client |
| 31043 |
instance. |
| 31044 |
|
| 31045 |
SEQ4_STATUS_CB_PATH_DOWN |
| 31046 |
When set, indicates that the client has no operational backchannel |
| 31047 |
path for any session associated with the client ID, making it |
| 31048 |
necessary for the client to re-establish one. This bit remains |
| 31049 |
set on all SEQUENCE responses on all sessions associated with the |
| 31050 |
client ID until at least one backchannel is available on any |
| 31051 |
session associated with the client ID. If the client fails to re- |
| 31052 |
establish a backchannel for the client ID, it is subject to having |
| 31053 |
recallable state revoked. |
| 31054 |
|
| 31055 |
SEQ4_STATUS_CB_PATH_DOWN_SESSION |
| 31056 |
When set, indicates that the session has no operational |
| 31057 |
backchannel. There are two reasons why |
| 31058 |
SEQ4_STATUS_CB_PATH_DOWN_SESSION may be set and not |
| 31059 |
SEQ4_STATUS_CB_PATH_DOWN. First is that a callback operation that |
| 31060 |
applies specifically to the session (e.g., CB_RECALL_SLOT, see |
| 31061 |
<a href="#section-20.8">Section 20.8</a>) needs to be sent. Second is that the server did |
| 31062 |
send a callback operation, but the connection was lost before the |
| 31063 |
reply. The server cannot be sure whether or not the client |
| 31064 |
received the callback operation, and so, per rules on request |
| 31065 |
retry, the server MUST retry the callback operation over the same |
| 31066 |
session. The SEQ4_STATUS_CB_PATH_DOWN_SESSION bit is the |
| 31067 |
indication to the client that it needs to associate a connection |
| 31068 |
to the session's backchannel. This bit remains set on all |
| 31069 |
SEQUENCE responses of the session until a connection is associated |
| 31070 |
with the session's a backchannel. If the client fails to re- |
| 31071 |
establish a backchannel for the session, it is subject to having |
| 31072 |
recallable state revoked. |
| 31073 |
|
| 31074 |
|
| 31075 |
|
| 31076 |
<span class="grey">Shepler, et al. Standards Track [Page 555]</span></pre> |
| 31077 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-556" ></span> |
| 31078 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31079 |
|
| 31080 |
|
| 31081 |
SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRING |
| 31082 |
When set, indicates that all GSS contexts or RPCSEC_GSS handles |
| 31083 |
assigned to the session's backchannel will expire within a period |
| 31084 |
equal to the lease time. This bit remains set on all SEQUENCE |
| 31085 |
replies until at least one of the following are true: |
| 31086 |
|
| 31087 |
* All SSV RPCSEC_GSS handles on the session's backchannel have |
| 31088 |
been destroyed and all non-SSV GSS contexts have expired. |
| 31089 |
|
| 31090 |
* At least one more SSV RPCSEC_GSS handle has been added to the |
| 31091 |
backchannel. |
| 31092 |
|
| 31093 |
* The expiration time of at least one non-SSV GSS context of an |
| 31094 |
RPCSEC_GSS handle is beyond the lease period from the current |
| 31095 |
time (relative to the time of when a SEQUENCE response was |
| 31096 |
sent) |
| 31097 |
|
| 31098 |
SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRED |
| 31099 |
When set, indicates all non-SSV GSS contexts and all SSV |
| 31100 |
RPCSEC_GSS handles assigned to the session's backchannel have |
| 31101 |
expired or have been destroyed. This bit remains set on all |
| 31102 |
SEQUENCE replies until at least one non-expired non-SSV GSS |
| 31103 |
context for the session's backchannel has been established or at |
| 31104 |
least one SSV RPCSEC_GSS handle has been assigned to the |
| 31105 |
backchannel. |
| 31106 |
|
| 31107 |
SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED |
| 31108 |
When set, indicates that the lease has expired and as a result the |
| 31109 |
server released all of the client's locking state. This status |
| 31110 |
bit remains set on all SEQUENCE replies until the loss of all such |
| 31111 |
locks has been acknowledged by use of FREE_STATEID (see |
| 31112 |
<a href="#section-18.38">Section 18.38</a>), or by establishing a new client instance by |
| 31113 |
destroying all sessions (via DESTROY_SESSION), the client ID (via |
| 31114 |
DESTROY_CLIENTID), and then invoking EXCHANGE_ID and |
| 31115 |
CREATE_SESSION to establish a new client ID. |
| 31116 |
|
| 31117 |
SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED |
| 31118 |
When set, indicates that some subset of the client's locks have |
| 31119 |
been revoked due to expiration of the lease period followed by |
| 31120 |
another client's conflicting LOCK operation. This status bit |
| 31121 |
remains set on all SEQUENCE replies until the loss of all such |
| 31122 |
locks has been acknowledged by use of FREE_STATEID. |
| 31123 |
|
| 31124 |
|
| 31125 |
|
| 31126 |
|
| 31127 |
|
| 31128 |
|
| 31129 |
|
| 31130 |
|
| 31131 |
|
| 31132 |
<span class="grey">Shepler, et al. Standards Track [Page 556]</span></pre> |
| 31133 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-557" ></span> |
| 31134 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31135 |
|
| 31136 |
|
| 31137 |
SEQ4_STATUS_ADMIN_STATE_REVOKED |
| 31138 |
When set, indicates that one or more locks have been revoked |
| 31139 |
without expiration of the lease period, due to administrative |
| 31140 |
action. This status bit remains set on all SEQUENCE replies until |
| 31141 |
the loss of all such locks has been acknowledged by use of |
| 31142 |
FREE_STATEID. |
| 31143 |
|
| 31144 |
SEQ4_STATUS_RECALLABLE_STATE_REVOKED |
| 31145 |
When set, indicates that one or more recallable objects have been |
| 31146 |
revoked without expiration of the lease period, due to the |
| 31147 |
client's failure to return them when recalled, which may be a |
| 31148 |
consequence of there being no working backchannel and the client |
| 31149 |
failing to re-establish a backchannel per the |
| 31150 |
SEQ4_STATUS_CB_PATH_DOWN, SEQ4_STATUS_CB_PATH_DOWN_SESSION, or |
| 31151 |
SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRED status flags. This status bit |
| 31152 |
remains set on all SEQUENCE replies until the loss of all such |
| 31153 |
locks has been acknowledged by use of FREE_STATEID. |
| 31154 |
|
| 31155 |
SEQ4_STATUS_LEASE_MOVED |
| 31156 |
When set, indicates that responsibility for lease renewal has been |
| 31157 |
transferred to one or more new servers. This condition will |
| 31158 |
continue until the client receives an NFS4ERR_MOVED error and the |
| 31159 |
server receives the subsequent GETATTR for the fs_locations or |
| 31160 |
fs_locations_info attribute for an access to each file system for |
| 31161 |
which a lease has been moved to a new server. See |
| 31162 |
<a href="#section-11.7.7.1">Section 11.7.7.1</a>. |
| 31163 |
|
| 31164 |
SEQ4_STATUS_RESTART_RECLAIM_NEEDED |
| 31165 |
When set, indicates that due to server restart, the client must |
| 31166 |
reclaim locking state. Until the client sends a global |
| 31167 |
RECLAIM_COMPLETE (<a href="#section-18.51">Section 18.51</a>), every SEQUENCE operation will |
| 31168 |
return SEQ4_STATUS_RESTART_RECLAIM_NEEDED. |
| 31169 |
|
| 31170 |
SEQ4_STATUS_BACKCHANNEL_FAULT |
| 31171 |
The server has encountered an unrecoverable fault with the |
| 31172 |
backchannel (e.g., it has lost track of the sequence ID for a slot |
| 31173 |
in the backchannel). The client MUST stop sending more requests |
| 31174 |
on the session's fore channel, wait for all outstanding requests |
| 31175 |
to complete on the fore and back channel, and then destroy the |
| 31176 |
session. |
| 31177 |
|
| 31178 |
SEQ4_STATUS_DEVID_CHANGED |
| 31179 |
The client is using device ID notifications and the server has |
| 31180 |
changed a device ID mapping held by the client. This flag will |
| 31181 |
stay present until the client has obtained the new mapping with |
| 31182 |
GETDEVICEINFO. |
| 31183 |
|
| 31184 |
|
| 31185 |
|
| 31186 |
|
| 31187 |
|
| 31188 |
<span class="grey">Shepler, et al. Standards Track [Page 557]</span></pre> |
| 31189 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-558" ></span> |
| 31190 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31191 |
|
| 31192 |
|
| 31193 |
SEQ4_STATUS_DEVID_DELETED |
| 31194 |
The client is using device ID notifications and the server has |
| 31195 |
deleted a device ID mapping held by the client. This flag will |
| 31196 |
stay in effect until the client sends a GETDEVICEINFO on the |
| 31197 |
device ID with a null value in the argument gdia_notify_types. |
| 31198 |
|
| 31199 |
The value of the sa_sequenceid argument relative to the cached |
| 31200 |
sequence ID on the slot falls into one of three cases. |
| 31201 |
|
| 31202 |
o If the difference between sa_sequenceid and the server's cached |
| 31203 |
sequence ID at the slot ID is two (2) or more, or if sa_sequenceid |
| 31204 |
is less than the cached sequence ID (accounting for wraparound of |
| 31205 |
the unsigned sequence ID value), then the server MUST return |
| 31206 |
NFS4ERR_SEQ_MISORDERED. |
| 31207 |
|
| 31208 |
o If sa_sequenceid and the cached sequence ID are the same, this is |
| 31209 |
a retry, and the server replies with what is recorded in the reply |
| 31210 |
cache. The lease is possibly renewed as described below. |
| 31211 |
|
| 31212 |
o If sa_sequenceid is one greater (accounting for wraparound) than |
| 31213 |
the cached sequence ID, then this is a new request, and the slot's |
| 31214 |
sequence ID is incremented. The operations subsequent to |
| 31215 |
SEQUENCE, if any, are processed. If there are no other |
| 31216 |
operations, the only other effects are to cache the SEQUENCE reply |
| 31217 |
in the slot, maintain the session's activity, and possibly renew |
| 31218 |
the lease. |
| 31219 |
|
| 31220 |
If the client reuses a slot ID and sequence ID for a completely |
| 31221 |
different request, the server MAY treat the request as if it is a |
| 31222 |
retry of what it has already executed. The server MAY however detect |
| 31223 |
the client's illegal reuse and return NFS4ERR_SEQ_FALSE_RETRY. |
| 31224 |
|
| 31225 |
If SEQUENCE returns an error, then the state of the slot (sequence |
| 31226 |
ID, cached reply) MUST NOT change, and the associated lease MUST NOT |
| 31227 |
be renewed. |
| 31228 |
|
| 31229 |
If SEQUENCE returns NFS4_OK, then the associated lease MUST be |
| 31230 |
renewed (see <a href="#section-8.3">Section 8.3</a>), except if |
| 31231 |
SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED is returned in sr_status_flags. |
| 31232 |
|
| 31233 |
<span class="h4"><a class="selflink" id="section-18.46.4" href="#section-18.46.4">18.46.4</a>. IMPLEMENTATION</span> |
| 31234 |
|
| 31235 |
The server MUST maintain a mapping of session ID to client ID in |
| 31236 |
order to validate any operations that follow SEQUENCE that take a |
| 31237 |
stateid as an argument and/or result. |
| 31238 |
|
| 31239 |
|
| 31240 |
|
| 31241 |
|
| 31242 |
|
| 31243 |
|
| 31244 |
<span class="grey">Shepler, et al. Standards Track [Page 558]</span></pre> |
| 31245 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-559" ></span> |
| 31246 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31247 |
|
| 31248 |
|
| 31249 |
If the client establishes a persistent session, then a SEQUENCE |
| 31250 |
received after a server restart might encounter requests performed |
| 31251 |
and recorded in a persistent reply cache before the server restart. |
| 31252 |
In this case, SEQUENCE will be processed successfully, while requests |
| 31253 |
that were not previously performed and recorded are rejected with |
| 31254 |
NFS4ERR_DEADSESSION. |
| 31255 |
|
| 31256 |
Depending on which of the operations within the COMPOUND were |
| 31257 |
successfully performed before the server restart, these operations |
| 31258 |
will also have replies sent from the server reply cache. Note that |
| 31259 |
when these operations establish locking state, it is locking state |
| 31260 |
that applies to the previous server instance and to the previous |
| 31261 |
client ID, even though the server restart, which logically happened |
| 31262 |
after these operations, eliminated that state. In the case of a |
| 31263 |
partially executed COMPOUND, processing may reach an operation not |
| 31264 |
processed during the earlier server instance, making this operation a |
| 31265 |
new one and not performable on the existing session. In this case, |
| 31266 |
NFS4ERR_DEADSESSION will be returned from that operation. |
| 31267 |
|
| 31268 |
<span class="h3"><a class="selflink" id="section-18.47" href="#section-18.47">18.47</a>. Operation 54: SET_SSV - Update SSV for a Client ID</span> |
| 31269 |
|
| 31270 |
<span class="h4"><a class="selflink" id="section-18.47.1" href="#section-18.47.1">18.47.1</a>. ARGUMENT</span> |
| 31271 |
|
| 31272 |
struct ssa_digest_input4 { |
| 31273 |
SEQUENCE4args sdi_seqargs; |
| 31274 |
}; |
| 31275 |
|
| 31276 |
struct SET_SSV4args { |
| 31277 |
opaque ssa_ssv<>; |
| 31278 |
opaque ssa_digest<>; |
| 31279 |
}; |
| 31280 |
|
| 31281 |
<span class="h4"><a class="selflink" id="section-18.47.2" href="#section-18.47.2">18.47.2</a>. RESULT</span> |
| 31282 |
|
| 31283 |
struct ssr_digest_input4 { |
| 31284 |
SEQUENCE4res sdi_seqres; |
| 31285 |
}; |
| 31286 |
|
| 31287 |
struct SET_SSV4resok { |
| 31288 |
opaque ssr_digest<>; |
| 31289 |
}; |
| 31290 |
|
| 31291 |
union SET_SSV4res switch (nfsstat4 ssr_status) { |
| 31292 |
case NFS4_OK: |
| 31293 |
SET_SSV4resok ssr_resok4; |
| 31294 |
default: |
| 31295 |
void; |
| 31296 |
}; |
| 31297 |
|
| 31298 |
|
| 31299 |
|
| 31300 |
<span class="grey">Shepler, et al. Standards Track [Page 559]</span></pre> |
| 31301 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-560" ></span> |
| 31302 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31303 |
|
| 31304 |
|
| 31305 |
<span class="h4"><a class="selflink" id="section-18.47.3" href="#section-18.47.3">18.47.3</a>. DESCRIPTION</span> |
| 31306 |
|
| 31307 |
This operation is used to update the SSV for a client ID. Before |
| 31308 |
SET_SSV is called the first time on a client ID, the SSV is zero. |
| 31309 |
The SSV is the key used for the SSV GSS mechanism (<a href="#section-2.10.9">Section 2.10.9</a>) |
| 31310 |
|
| 31311 |
SET_SSV MUST be preceded by a SEQUENCE operation in the same |
| 31312 |
COMPOUND. It MUST NOT be used if the client did not opt for SP4_SSV |
| 31313 |
state protection when the client ID was created (see <a href="#section-18.35">Section 18.35</a>); |
| 31314 |
the server returns NFS4ERR_INVAL in that case. |
| 31315 |
|
| 31316 |
The field ssa_digest is computed as the output of the HMAC (<a href="./rfc2104">RFC 2104</a> |
| 31317 |
[<a href="#ref-11" title=""HMAC: Keyed-Hashing for Message Authentication"">11</a>]) using the subkey derived from the SSV4_SUBKEY_MIC_I2T and |
| 31318 |
current SSV as the key (see <a href="#section-2.10.9">Section 2.10.9</a> for a description of |
| 31319 |
subkeys), and an XDR encoded value of data type ssa_digest_input4. |
| 31320 |
The field sdi_seqargs is equal to the arguments of the SEQUENCE |
| 31321 |
operation for the COMPOUND procedure that SET_SSV is within. |
| 31322 |
|
| 31323 |
The argument ssa_ssv is XORed with the current SSV to produce the new |
| 31324 |
SSV. The argument ssa_ssv SHOULD be generated randomly. |
| 31325 |
|
| 31326 |
In the response, ssr_digest is the output of the HMAC using the |
| 31327 |
subkey derived from SSV4_SUBKEY_MIC_T2I and new SSV as the key, and |
| 31328 |
an XDR encoded value of data type ssr_digest_input4. The field |
| 31329 |
sdi_seqres is equal to the results of the SEQUENCE operation for the |
| 31330 |
COMPOUND procedure that SET_SSV is within. |
| 31331 |
|
| 31332 |
As noted in <a href="#section-18.35">Section 18.35</a>, the client and server can maintain |
| 31333 |
multiple concurrent versions of the SSV. The client and server each |
| 31334 |
MUST maintain an internal SSV version number, which is set to one the |
| 31335 |
first time SET_SSV executes on the server and the client receives the |
| 31336 |
first SET_SSV reply. Each subsequent SET_SSV increases the internal |
| 31337 |
SSV version number by one. The value of this version number |
| 31338 |
corresponds to the smpt_ssv_seq, smt_ssv_seq, sspt_ssv_seq, and |
| 31339 |
ssct_ssv_seq fields of the SSV GSS mechanism tokens (see |
| 31340 |
<a href="#section-2.10.9">Section 2.10.9</a>). |
| 31341 |
|
| 31342 |
<span class="h4"><a class="selflink" id="section-18.47.4" href="#section-18.47.4">18.47.4</a>. IMPLEMENTATION</span> |
| 31343 |
|
| 31344 |
When the server receives ssa_digest, it MUST verify the digest by |
| 31345 |
computing the digest the same way the client did and comparing it |
| 31346 |
with ssa_digest. If the server gets a different result, this is an |
| 31347 |
error, NFS4ERR_BAD_SESSION_DIGEST. This error might be the result of |
| 31348 |
another SET_SSV from the same client ID changing the SSV. If so, the |
| 31349 |
client recovers by sending a SET_SSV operation again with a |
| 31350 |
recomputed digest based on the subkey of the new SSV. If the |
| 31351 |
transport connection is dropped after the SET_SSV request is sent, |
| 31352 |
but before the SET_SSV reply is received, then there are special |
| 31353 |
|
| 31354 |
|
| 31355 |
|
| 31356 |
<span class="grey">Shepler, et al. Standards Track [Page 560]</span></pre> |
| 31357 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-561" ></span> |
| 31358 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31359 |
|
| 31360 |
|
| 31361 |
considerations for recovery if the client has no more connections |
| 31362 |
associated with sessions associated with the client ID of the SSV. |
| 31363 |
See <a href="#section-18.34.4">Section 18.34.4</a>. |
| 31364 |
|
| 31365 |
Clients SHOULD NOT send an ssa_ssv that is equal to a previous |
| 31366 |
ssa_ssv, nor equal to a previous or current SSV (including an ssa_ssv |
| 31367 |
equal to zero since the SSV is initialized to zero when the client ID |
| 31368 |
is created). |
| 31369 |
|
| 31370 |
Clients SHOULD send SET_SSV with RPCSEC_GSS privacy. Servers MUST |
| 31371 |
support RPCSEC_GSS with privacy for any COMPOUND that has { SEQUENCE, |
| 31372 |
SET_SSV }. |
| 31373 |
|
| 31374 |
A client SHOULD NOT send SET_SSV with the SSV GSS mechanism's |
| 31375 |
credential because the purpose of SET_SSV is to seed the SSV from |
| 31376 |
non-SSV credentials. Instead, SET_SSV SHOULD be sent with the |
| 31377 |
credential of a user that is accessing the client ID for the first |
| 31378 |
time (<a href="#section-2.10.8.3">Section 2.10.8.3</a>). However, if the client does send SET_SSV |
| 31379 |
with SSV credentials, the digest protecting the arguments uses the |
| 31380 |
value of the SSV before ssa_ssv is XORed in, and the digest |
| 31381 |
protecting the results uses the value of the SSV after the ssa_ssv is |
| 31382 |
XORed in. |
| 31383 |
|
| 31384 |
<span class="h3"><a class="selflink" id="section-18.48" href="#section-18.48">18.48</a>. Operation 55: TEST_STATEID - Test Stateids for Validity</span> |
| 31385 |
|
| 31386 |
<span class="h4"><a class="selflink" id="section-18.48.1" href="#section-18.48.1">18.48.1</a>. ARGUMENT</span> |
| 31387 |
|
| 31388 |
struct TEST_STATEID4args { |
| 31389 |
stateid4 ts_stateids<>; |
| 31390 |
}; |
| 31391 |
|
| 31392 |
<span class="h4"><a class="selflink" id="section-18.48.2" href="#section-18.48.2">18.48.2</a>. RESULT</span> |
| 31393 |
|
| 31394 |
struct TEST_STATEID4resok { |
| 31395 |
nfsstat4 tsr_status_codes<>; |
| 31396 |
}; |
| 31397 |
|
| 31398 |
union TEST_STATEID4res switch (nfsstat4 tsr_status) { |
| 31399 |
case NFS4_OK: |
| 31400 |
TEST_STATEID4resok tsr_resok4; |
| 31401 |
default: |
| 31402 |
void; |
| 31403 |
}; |
| 31404 |
|
| 31405 |
|
| 31406 |
|
| 31407 |
|
| 31408 |
|
| 31409 |
|
| 31410 |
|
| 31411 |
|
| 31412 |
<span class="grey">Shepler, et al. Standards Track [Page 561]</span></pre> |
| 31413 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-562" ></span> |
| 31414 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31415 |
|
| 31416 |
|
| 31417 |
<span class="h4"><a class="selflink" id="section-18.48.3" href="#section-18.48.3">18.48.3</a>. DESCRIPTION</span> |
| 31418 |
|
| 31419 |
The TEST_STATEID operation is used to check the validity of a set of |
| 31420 |
stateids. It can be used at any time, but the client should |
| 31421 |
definitely use it when it receives an indication that one or more of |
| 31422 |
its stateids have been invalidated due to lock revocation. This |
| 31423 |
occurs when the SEQUENCE operation returns with one of the following |
| 31424 |
sr_status_flags set: |
| 31425 |
|
| 31426 |
o SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED |
| 31427 |
|
| 31428 |
o SEQ4_STATUS_EXPIRED_ADMIN_STATE_REVOKED |
| 31429 |
|
| 31430 |
o SEQ4_STATUS_EXPIRED_RECALLABLE_STATE_REVOKED |
| 31431 |
|
| 31432 |
The client can use TEST_STATEID one or more times to test the |
| 31433 |
validity of its stateids. Each use of TEST_STATEID allows a large |
| 31434 |
set of such stateids to be tested and avoids problems with earlier |
| 31435 |
stateids in a COMPOUND request from interfering with the checking of |
| 31436 |
subsequent stateids, as would happen if individual stateids were |
| 31437 |
tested by a series of corresponding by operations in a COMPOUND |
| 31438 |
request. |
| 31439 |
|
| 31440 |
For each stateid, the server returns the status code that would be |
| 31441 |
returned if that stateid were to be used in normal operation. |
| 31442 |
Returning such a status indication is not an error and does not cause |
| 31443 |
COMPOUND processing to terminate. Checks for the validity of the |
| 31444 |
stateid proceed as they would for normal operations with a number of |
| 31445 |
exceptions: |
| 31446 |
|
| 31447 |
o There is no check for the type of stateid object, as would be the |
| 31448 |
case for normal use of a stateid. |
| 31449 |
|
| 31450 |
o There is no reference to the current filehandle. |
| 31451 |
|
| 31452 |
o Special stateids are always considered invalid (they result in the |
| 31453 |
error code NFS4ERR_BAD_STATEID). |
| 31454 |
|
| 31455 |
All stateids are interpreted as being associated with the client for |
| 31456 |
the current session. Any possible association with a previous |
| 31457 |
instance of the client (as stale stateids) is not considered. |
| 31458 |
|
| 31459 |
The valid status values in the returned status_code array are |
| 31460 |
NFS4ERR_OK, NFS4ERR_BAD_STATEID, NFS4ERR_OLD_STATEID, |
| 31461 |
NFS4ERR_EXPIRED, NFS4ERR_ADMIN_REVOKED, and NFS4ERR_DELEG_REVOKED. |
| 31462 |
|
| 31463 |
|
| 31464 |
|
| 31465 |
|
| 31466 |
|
| 31467 |
|
| 31468 |
<span class="grey">Shepler, et al. Standards Track [Page 562]</span></pre> |
| 31469 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-563" ></span> |
| 31470 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31471 |
|
| 31472 |
|
| 31473 |
<span class="h4"><a class="selflink" id="section-18.48.4" href="#section-18.48.4">18.48.4</a>. IMPLEMENTATION</span> |
| 31474 |
|
| 31475 |
See Sections <a href="#section-8.2.2">8.2.2</a> and <a href="#section-8.2.4">8.2.4</a> for a discussion of stateid structure, |
| 31476 |
lifetime, and validation. |
| 31477 |
|
| 31478 |
<span class="h3"><a class="selflink" id="section-18.49" href="#section-18.49">18.49</a>. Operation 56: WANT_DELEGATION - Request Delegation</span> |
| 31479 |
|
| 31480 |
<span class="h4"><a class="selflink" id="section-18.49.1" href="#section-18.49.1">18.49.1</a>. ARGUMENT</span> |
| 31481 |
|
| 31482 |
union deleg_claim4 switch (open_claim_type4 dc_claim) { |
| 31483 |
/* |
| 31484 |
* No special rights to object. Ordinary delegation |
| 31485 |
* request of the specified object. Object identified |
| 31486 |
* by filehandle. |
| 31487 |
*/ |
| 31488 |
case CLAIM_FH: /* new to v4.1 */ |
| 31489 |
/* CURRENT_FH: object being delegated */ |
| 31490 |
void; |
| 31491 |
|
| 31492 |
/* |
| 31493 |
* Right to file based on a delegation granted |
| 31494 |
* to a previous boot instance of the client. |
| 31495 |
* File is specified by filehandle. |
| 31496 |
*/ |
| 31497 |
case CLAIM_DELEG_PREV_FH: /* new to v4.1 */ |
| 31498 |
/* CURRENT_FH: object being delegated */ |
| 31499 |
void; |
| 31500 |
|
| 31501 |
/* |
| 31502 |
* Right to the file established by an open previous |
| 31503 |
* to server reboot. File identified by filehandle. |
| 31504 |
* Used during server reclaim grace period. |
| 31505 |
*/ |
| 31506 |
case CLAIM_PREVIOUS: |
| 31507 |
/* CURRENT_FH: object being reclaimed */ |
| 31508 |
open_delegation_type4 dc_delegate_type; |
| 31509 |
}; |
| 31510 |
|
| 31511 |
struct WANT_DELEGATION4args { |
| 31512 |
uint32_t wda_want; |
| 31513 |
deleg_claim4 wda_claim; |
| 31514 |
}; |
| 31515 |
|
| 31516 |
|
| 31517 |
|
| 31518 |
|
| 31519 |
|
| 31520 |
|
| 31521 |
|
| 31522 |
|
| 31523 |
|
| 31524 |
<span class="grey">Shepler, et al. Standards Track [Page 563]</span></pre> |
| 31525 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-564" ></span> |
| 31526 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31527 |
|
| 31528 |
|
| 31529 |
<span class="h4"><a class="selflink" id="section-18.49.2" href="#section-18.49.2">18.49.2</a>. RESULT</span> |
| 31530 |
|
| 31531 |
union WANT_DELEGATION4res switch (nfsstat4 wdr_status) { |
| 31532 |
case NFS4_OK: |
| 31533 |
open_delegation4 wdr_resok4; |
| 31534 |
default: |
| 31535 |
void; |
| 31536 |
}; |
| 31537 |
|
| 31538 |
<span class="h4"><a class="selflink" id="section-18.49.3" href="#section-18.49.3">18.49.3</a>. DESCRIPTION</span> |
| 31539 |
|
| 31540 |
Where this description mandates the return of a specific error code |
| 31541 |
for a specific condition, and where multiple conditions apply, the |
| 31542 |
server MAY return any of the mandated error codes. |
| 31543 |
|
| 31544 |
This operation allows a client to: |
| 31545 |
|
| 31546 |
o Get a delegation on all types of files except directories. |
| 31547 |
|
| 31548 |
o Register a "want" for a delegation for the specified file object, |
| 31549 |
and be notified via a callback when the delegation is available. |
| 31550 |
The server MAY support notifications of availability via |
| 31551 |
callbacks. If the server does not support registration of wants, |
| 31552 |
it MUST NOT return an error to indicate that, and instead MUST |
| 31553 |
return with ond_why set to WND4_CONTENTION or WND4_RESOURCE and |
| 31554 |
ond_server_will_push_deleg or ond_server_will_signal_avail set to |
| 31555 |
FALSE. When the server indicates that it will notify the client |
| 31556 |
by means of a callback, it will either provide the delegation |
| 31557 |
using a CB_PUSH_DELEG operation or cancel its promise by sending a |
| 31558 |
CB_WANTS_CANCELLED operation. |
| 31559 |
|
| 31560 |
o Cancel a want for a delegation. |
| 31561 |
|
| 31562 |
The client SHOULD NOT set OPEN4_SHARE_ACCESS_READ and SHOULD NOT set |
| 31563 |
OPEN4_SHARE_ACCESS_WRITE in wda_want. If it does, the server MUST |
| 31564 |
ignore them. |
| 31565 |
|
| 31566 |
The meanings of the following flags in wda_want are the same as they |
| 31567 |
are in OPEN, except as noted below. |
| 31568 |
|
| 31569 |
o OPEN4_SHARE_ACCESS_WANT_READ_DELEG |
| 31570 |
|
| 31571 |
o OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG |
| 31572 |
|
| 31573 |
o OPEN4_SHARE_ACCESS_WANT_ANY_DELEG |
| 31574 |
|
| 31575 |
|
| 31576 |
|
| 31577 |
|
| 31578 |
|
| 31579 |
|
| 31580 |
<span class="grey">Shepler, et al. Standards Track [Page 564]</span></pre> |
| 31581 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-565" ></span> |
| 31582 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31583 |
|
| 31584 |
|
| 31585 |
o OPEN4_SHARE_ACCESS_WANT_NO_DELEG. Unlike the OPEN operation, this |
| 31586 |
flag SHOULD NOT be set by the client in the arguments to |
| 31587 |
WANT_DELEGATION, and MUST be ignored by the server. |
| 31588 |
|
| 31589 |
o OPEN4_SHARE_ACCESS_WANT_CANCEL |
| 31590 |
|
| 31591 |
o OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL |
| 31592 |
|
| 31593 |
o OPEN4_SHARE_ACCESS_WANT_PUSH_DELEG_WHEN_UNCONTENDED |
| 31594 |
|
| 31595 |
The handling of the above flags in WANT_DELEGATION is the same as in |
| 31596 |
OPEN. Information about the delegation and/or the promises the |
| 31597 |
server is making regarding future callbacks are the same as those |
| 31598 |
described in the open_delegation4 structure. |
| 31599 |
|
| 31600 |
The successful results of WANT_DELEGATION are of data type |
| 31601 |
open_delegation4, which is the same data type as the "delegation" |
| 31602 |
field in the results of the OPEN operation (see <a href="#section-18.16.3">Section 18.16.3</a>). |
| 31603 |
The server constructs wdr_resok4 the same way it constructs OPEN's |
| 31604 |
"delegation" with one difference: WANT_DELEGATION MUST NOT return a |
| 31605 |
delegation type of OPEN_DELEGATE_NONE. |
| 31606 |
|
| 31607 |
If ((wda_want & OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) & |
| 31608 |
~OPEN4_SHARE_ACCESS_WANT_NO_DELEG) is zero, then the client is |
| 31609 |
indicating no explicit desire or non-desire for a delegation and the |
| 31610 |
server MUST return NFS4ERR_INVAL. |
| 31611 |
|
| 31612 |
The client uses the OPEN4_SHARE_ACCESS_WANT_CANCEL flag in the |
| 31613 |
WANT_DELEGATION operation to cancel a previously requested want for a |
| 31614 |
delegation. Note that if the server is in the process of sending the |
| 31615 |
delegation (via CB_PUSH_DELEG) at the time the client sends a |
| 31616 |
cancellation of the want, the delegation might still be pushed to the |
| 31617 |
client. |
| 31618 |
|
| 31619 |
If WANT_DELEGATION fails to return a delegation, and the server |
| 31620 |
returns NFS4_OK, the server MUST set the delegation type to |
| 31621 |
OPEN4_DELEGATE_NONE_EXT, and set od_whynone, as described in |
| 31622 |
<a href="#section-18.16">Section 18.16</a>. Write delegations are not available for file types |
| 31623 |
that are not writable. This includes file objects of types NF4BLK, |
| 31624 |
NF4CHR, NF4LNK, NF4SOCK, and NF4FIFO. If the client requests |
| 31625 |
OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG without |
| 31626 |
OPEN4_SHARE_ACCESS_WANT_READ_DELEG on an object with one of the |
| 31627 |
aforementioned file types, the server must set |
| 31628 |
wdr_resok4.od_whynone.ond_why to WND4_WRITE_DELEG_NOT_SUPP_FTYPE. |
| 31629 |
|
| 31630 |
|
| 31631 |
|
| 31632 |
|
| 31633 |
|
| 31634 |
|
| 31635 |
|
| 31636 |
<span class="grey">Shepler, et al. Standards Track [Page 565]</span></pre> |
| 31637 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-566" ></span> |
| 31638 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31639 |
|
| 31640 |
|
| 31641 |
<span class="h4"><a class="selflink" id="section-18.49.4" href="#section-18.49.4">18.49.4</a>. IMPLEMENTATION</span> |
| 31642 |
|
| 31643 |
A request for a conflicting delegation is not normally intended to |
| 31644 |
trigger the recall of the existing delegation. Servers may choose to |
| 31645 |
treat some clients as having higher priority such that their wants |
| 31646 |
will trigger recall of an existing delegation, although that is |
| 31647 |
expected to be an unusual situation. |
| 31648 |
|
| 31649 |
Servers will generally recall delegations assigned by WANT_DELEGATION |
| 31650 |
on the same basis as those assigned by OPEN. CB_RECALL will |
| 31651 |
generally be done only when other clients perform operations |
| 31652 |
inconsistent with the delegation. The normal response to aging of |
| 31653 |
delegations is to use CB_RECALL_ANY, in order to give the client the |
| 31654 |
opportunity to keep the delegations most useful from its point of |
| 31655 |
view. |
| 31656 |
|
| 31657 |
<span class="h3"><a class="selflink" id="section-18.50" href="#section-18.50">18.50</a>. Operation 57: DESTROY_CLIENTID - Destroy a Client ID</span> |
| 31658 |
|
| 31659 |
<span class="h4"><a class="selflink" id="section-18.50.1" href="#section-18.50.1">18.50.1</a>. ARGUMENT</span> |
| 31660 |
|
| 31661 |
struct DESTROY_CLIENTID4args { |
| 31662 |
clientid4 dca_clientid; |
| 31663 |
}; |
| 31664 |
|
| 31665 |
<span class="h4"><a class="selflink" id="section-18.50.2" href="#section-18.50.2">18.50.2</a>. RESULT</span> |
| 31666 |
|
| 31667 |
struct DESTROY_CLIENTID4res { |
| 31668 |
nfsstat4 dcr_status; |
| 31669 |
}; |
| 31670 |
|
| 31671 |
<span class="h4"><a class="selflink" id="section-18.50.3" href="#section-18.50.3">18.50.3</a>. DESCRIPTION</span> |
| 31672 |
|
| 31673 |
The DESTROY_CLIENTID operation destroys the client ID. If there are |
| 31674 |
sessions (both idle and non-idle), opens, locks, delegations, |
| 31675 |
layouts, and/or wants (<a href="#section-18.49">Section 18.49</a>) associated with the unexpired |
| 31676 |
lease of the client ID, the server MUST return NFS4ERR_CLIENTID_BUSY. |
| 31677 |
DESTROY_CLIENTID MAY be preceded with a SEQUENCE operation as long as |
| 31678 |
the client ID derived from the session ID of SEQUENCE is not the same |
| 31679 |
as the client ID to be destroyed. If the client IDs are the same, |
| 31680 |
then the server MUST return NFS4ERR_CLIENTID_BUSY. |
| 31681 |
|
| 31682 |
If DESTROY_CLIENTID is not prefixed by SEQUENCE, it MUST be the only |
| 31683 |
operation in the COMPOUND request (otherwise, the server MUST return |
| 31684 |
NFS4ERR_NOT_ONLY_OP). If the operation is sent without a SEQUENCE |
| 31685 |
preceding it, a client that retransmits the request may receive an |
| 31686 |
error in response, because the original request might have been |
| 31687 |
successfully executed. |
| 31688 |
|
| 31689 |
|
| 31690 |
|
| 31691 |
|
| 31692 |
<span class="grey">Shepler, et al. Standards Track [Page 566]</span></pre> |
| 31693 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-567" ></span> |
| 31694 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31695 |
|
| 31696 |
|
| 31697 |
<span class="h4"><a class="selflink" id="section-18.50.4" href="#section-18.50.4">18.50.4</a>. IMPLEMENTATION</span> |
| 31698 |
|
| 31699 |
DESTROY_CLIENTID allows a server to immediately reclaim the resources |
| 31700 |
consumed by an unused client ID, and also to forget that it ever |
| 31701 |
generated the client ID. By forgetting that it ever generated the |
| 31702 |
client ID, the server can safely reuse the client ID on a future |
| 31703 |
EXCHANGE_ID operation. |
| 31704 |
|
| 31705 |
<span class="h3"><a class="selflink" id="section-18.51" href="#section-18.51">18.51</a>. Operation 58: RECLAIM_COMPLETE - Indicates Reclaims Finished</span> |
| 31706 |
|
| 31707 |
<span class="h4"><a class="selflink" id="section-18.51.1" href="#section-18.51.1">18.51.1</a>. ARGUMENT</span> |
| 31708 |
|
| 31709 |
struct RECLAIM_COMPLETE4args { |
| 31710 |
/* |
| 31711 |
* If rca_one_fs TRUE, |
| 31712 |
* |
| 31713 |
* CURRENT_FH: object in |
| 31714 |
* file system reclaim is |
| 31715 |
* complete for. |
| 31716 |
*/ |
| 31717 |
bool rca_one_fs; |
| 31718 |
}; |
| 31719 |
|
| 31720 |
<span class="h4"><a class="selflink" id="section-18.51.2" href="#section-18.51.2">18.51.2</a>. RESULTS</span> |
| 31721 |
|
| 31722 |
struct RECLAIM_COMPLETE4res { |
| 31723 |
nfsstat4 rcr_status; |
| 31724 |
}; |
| 31725 |
|
| 31726 |
<span class="h4"><a class="selflink" id="section-18.51.3" href="#section-18.51.3">18.51.3</a>. DESCRIPTION</span> |
| 31727 |
|
| 31728 |
A RECLAIM_COMPLETE operation is used to indicate that the client has |
| 31729 |
reclaimed all of the locking state that it will recover, when it is |
| 31730 |
recovering state due to either a server restart or the transfer of a |
| 31731 |
file system to another server. There are two types of |
| 31732 |
RECLAIM_COMPLETE operations: |
| 31733 |
|
| 31734 |
o When rca_one_fs is FALSE, a global RECLAIM_COMPLETE is being done. |
| 31735 |
This indicates that recovery of all locks that the client held on |
| 31736 |
the previous server instance have been completed. |
| 31737 |
|
| 31738 |
o When rca_one_fs is TRUE, a file system-specific RECLAIM_COMPLETE |
| 31739 |
is being done. This indicates that recovery of locks for a single |
| 31740 |
fs (the one designated by the current filehandle) due to a file |
| 31741 |
system transition have been completed. Presence of a current |
| 31742 |
filehandle is only required when rca_one_fs is set to TRUE. |
| 31743 |
|
| 31744 |
|
| 31745 |
|
| 31746 |
|
| 31747 |
|
| 31748 |
<span class="grey">Shepler, et al. Standards Track [Page 567]</span></pre> |
| 31749 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-568" ></span> |
| 31750 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31751 |
|
| 31752 |
|
| 31753 |
Once a RECLAIM_COMPLETE is done, there can be no further reclaim |
| 31754 |
operations for locks whose scope is defined as having completed |
| 31755 |
recovery. Once the client sends RECLAIM_COMPLETE, the server will |
| 31756 |
not allow the client to do subsequent reclaims of locking state for |
| 31757 |
that scope and, if these are attempted, will return NFS4ERR_NO_GRACE. |
| 31758 |
|
| 31759 |
Whenever a client establishes a new client ID and before it does the |
| 31760 |
first non-reclaim operation that obtains a lock, it MUST send a |
| 31761 |
RECLAIM_COMPLETE with rca_one_fs set to FALSE, even if there are no |
| 31762 |
locks to reclaim. If non-reclaim locking operations are done before |
| 31763 |
the RECLAIM_COMPLETE, an NFS4ERR_GRACE error will be returned. |
| 31764 |
|
| 31765 |
Similarly, when the client accesses a file system on a new server, |
| 31766 |
before it sends the first non-reclaim operation that obtains a lock |
| 31767 |
on this new server, it MUST send a RECLAIM_COMPLETE with rca_one_fs |
| 31768 |
set to TRUE and current filehandle within that file system, even if |
| 31769 |
there are no locks to reclaim. If non-reclaim locking operations are |
| 31770 |
done on that file system before the RECLAIM_COMPLETE, an |
| 31771 |
NFS4ERR_GRACE error will be returned. |
| 31772 |
|
| 31773 |
Any locks not reclaimed at the point at which RECLAIM_COMPLETE is |
| 31774 |
done become non-reclaimable. The client MUST NOT attempt to reclaim |
| 31775 |
them, either during the current server instance or in any subsequent |
| 31776 |
server instance, or on another server to which responsibility for |
| 31777 |
that file system is transferred. If the client were to do so, it |
| 31778 |
would be violating the protocol by representing itself as owning |
| 31779 |
locks that it does not own, and so has no right to reclaim. See |
| 31780 |
<a href="#section-8.4.3">Section 8.4.3</a> for a discussion of edge conditions related to lock |
| 31781 |
reclaim. |
| 31782 |
|
| 31783 |
By sending a RECLAIM_COMPLETE, the client indicates readiness to |
| 31784 |
proceed to do normal non-reclaim locking operations. The client |
| 31785 |
should be aware that such operations may temporarily result in |
| 31786 |
NFS4ERR_GRACE errors until the server is ready to terminate its grace |
| 31787 |
period. |
| 31788 |
|
| 31789 |
<span class="h4"><a class="selflink" id="section-18.51.4" href="#section-18.51.4">18.51.4</a>. IMPLEMENTATION</span> |
| 31790 |
|
| 31791 |
Servers will typically use the information as to when reclaim |
| 31792 |
activity is complete to reduce the length of the grace period. When |
| 31793 |
the server maintains in persistent storage a list of clients that |
| 31794 |
might have had locks, it is in a position to use the fact that all |
| 31795 |
such clients have done a RECLAIM_COMPLETE to terminate the grace |
| 31796 |
period and begin normal operations (i.e., grant requests for new |
| 31797 |
locks) sooner than it might otherwise. |
| 31798 |
|
| 31799 |
|
| 31800 |
|
| 31801 |
|
| 31802 |
|
| 31803 |
|
| 31804 |
<span class="grey">Shepler, et al. Standards Track [Page 568]</span></pre> |
| 31805 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-569" ></span> |
| 31806 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31807 |
|
| 31808 |
|
| 31809 |
Latency can be minimized by doing a RECLAIM_COMPLETE as part of the |
| 31810 |
COMPOUND request in which the last lock-reclaiming operation is done. |
| 31811 |
When there are no reclaims to be done, RECLAIM_COMPLETE should be |
| 31812 |
done immediately in order to allow the grace period to end as soon as |
| 31813 |
possible. |
| 31814 |
|
| 31815 |
RECLAIM_COMPLETE should only be done once for each server instance or |
| 31816 |
occasion of the transition of a file system. If it is done a second |
| 31817 |
time, the error NFS4ERR_COMPLETE_ALREADY will result. Note that |
| 31818 |
because of the session feature's retry protection, retries of |
| 31819 |
COMPOUND requests containing RECLAIM_COMPLETE operation will not |
| 31820 |
result in this error. |
| 31821 |
|
| 31822 |
When a RECLAIM_COMPLETE is sent, the client effectively acknowledges |
| 31823 |
any locks not yet reclaimed as lost. This allows the server to re- |
| 31824 |
enable the client to recover locks if the occurrence of edge |
| 31825 |
conditions, as described in <a href="#section-8.4.3">Section 8.4.3</a>, had caused the server to |
| 31826 |
disable the client from recovering locks. |
| 31827 |
|
| 31828 |
<span class="h3"><a class="selflink" id="section-18.52" href="#section-18.52">18.52</a>. Operation 10044: ILLEGAL - Illegal Operation</span> |
| 31829 |
|
| 31830 |
<span class="h4"><a class="selflink" id="section-18.52.1" href="#section-18.52.1">18.52.1</a>. ARGUMENTS</span> |
| 31831 |
|
| 31832 |
void; |
| 31833 |
|
| 31834 |
<span class="h4"><a class="selflink" id="section-18.52.2" href="#section-18.52.2">18.52.2</a>. RESULTS</span> |
| 31835 |
|
| 31836 |
struct ILLEGAL4res { |
| 31837 |
nfsstat4 status; |
| 31838 |
}; |
| 31839 |
|
| 31840 |
<span class="h4"><a class="selflink" id="section-18.52.3" href="#section-18.52.3">18.52.3</a>. DESCRIPTION</span> |
| 31841 |
|
| 31842 |
This operation is a placeholder for encoding a result to handle the |
| 31843 |
case of the client sending an operation code within COMPOUND that is |
| 31844 |
not supported. See the COMPOUND procedure description for more |
| 31845 |
details. |
| 31846 |
|
| 31847 |
The status field of ILLEGAL4res MUST be set to NFS4ERR_OP_ILLEGAL. |
| 31848 |
|
| 31849 |
<span class="h4"><a class="selflink" id="section-18.52.4" href="#section-18.52.4">18.52.4</a>. IMPLEMENTATION</span> |
| 31850 |
|
| 31851 |
A client will probably not send an operation with code OP_ILLEGAL but |
| 31852 |
if it does, the response will be ILLEGAL4res just as it would be with |
| 31853 |
any other invalid operation code. Note that if the server gets an |
| 31854 |
|
| 31855 |
|
| 31856 |
|
| 31857 |
|
| 31858 |
|
| 31859 |
|
| 31860 |
<span class="grey">Shepler, et al. Standards Track [Page 569]</span></pre> |
| 31861 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-570" ></span> |
| 31862 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31863 |
|
| 31864 |
|
| 31865 |
illegal operation code that is not OP_ILLEGAL, and if the server |
| 31866 |
checks for legal operation codes during the XDR decode phase, then |
| 31867 |
the ILLEGAL4res would not be returned. |
| 31868 |
|
| 31869 |
<span class="h2"><a class="selflink" id="section-19" href="#section-19">19</a>. NFSv4.1 Callback Procedures</span> |
| 31870 |
|
| 31871 |
The procedures used for callbacks are defined in the following |
| 31872 |
sections. In the interest of clarity, the terms "client" and |
| 31873 |
"server" refer to NFS clients and servers, despite the fact that for |
| 31874 |
an individual callback RPC, the sense of these terms would be |
| 31875 |
precisely the opposite. |
| 31876 |
|
| 31877 |
Both procedures, CB_NULL and CB_COMPOUND, MUST be implemented. |
| 31878 |
|
| 31879 |
<span class="h3"><a class="selflink" id="section-19.1" href="#section-19.1">19.1</a>. Procedure 0: CB_NULL - No Operation</span> |
| 31880 |
|
| 31881 |
<span class="h4"><a class="selflink" id="section-19.1.1" href="#section-19.1.1">19.1.1</a>. ARGUMENTS</span> |
| 31882 |
|
| 31883 |
void; |
| 31884 |
|
| 31885 |
<span class="h4"><a class="selflink" id="section-19.1.2" href="#section-19.1.2">19.1.2</a>. RESULTS</span> |
| 31886 |
|
| 31887 |
void; |
| 31888 |
|
| 31889 |
<span class="h4"><a class="selflink" id="section-19.1.3" href="#section-19.1.3">19.1.3</a>. DESCRIPTION</span> |
| 31890 |
|
| 31891 |
CB_NULL is the standard ONC RPC NULL procedure, with the standard |
| 31892 |
void argument and void response. Even though there is no direct |
| 31893 |
functionality associated with this procedure, the server will use |
| 31894 |
CB_NULL to confirm the existence of a path for RPCs from the server |
| 31895 |
to client. |
| 31896 |
|
| 31897 |
<span class="h4"><a class="selflink" id="section-19.1.4" href="#section-19.1.4">19.1.4</a>. ERRORS</span> |
| 31898 |
|
| 31899 |
None. |
| 31900 |
|
| 31901 |
<span class="h3"><a class="selflink" id="section-19.2" href="#section-19.2">19.2</a>. Procedure 1: CB_COMPOUND - Compound Operations</span> |
| 31902 |
|
| 31903 |
|
| 31904 |
|
| 31905 |
|
| 31906 |
|
| 31907 |
|
| 31908 |
|
| 31909 |
|
| 31910 |
|
| 31911 |
|
| 31912 |
|
| 31913 |
|
| 31914 |
|
| 31915 |
|
| 31916 |
<span class="grey">Shepler, et al. Standards Track [Page 570]</span></pre> |
| 31917 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-571" ></span> |
| 31918 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31919 |
|
| 31920 |
|
| 31921 |
<span class="h4"><a class="selflink" id="section-19.2.1" href="#section-19.2.1">19.2.1</a>. ARGUMENTS</span> |
| 31922 |
|
| 31923 |
enum nfs_cb_opnum4 { |
| 31924 |
OP_CB_GETATTR = 3, |
| 31925 |
OP_CB_RECALL = 4, |
| 31926 |
/* Callback operations new to NFSv4.1 */ |
| 31927 |
OP_CB_LAYOUTRECALL = 5, |
| 31928 |
OP_CB_NOTIFY = 6, |
| 31929 |
OP_CB_PUSH_DELEG = 7, |
| 31930 |
OP_CB_RECALL_ANY = 8, |
| 31931 |
OP_CB_RECALLABLE_OBJ_AVAIL = 9, |
| 31932 |
OP_CB_RECALL_SLOT = 10, |
| 31933 |
OP_CB_SEQUENCE = 11, |
| 31934 |
OP_CB_WANTS_CANCELLED = 12, |
| 31935 |
OP_CB_NOTIFY_LOCK = 13, |
| 31936 |
OP_CB_NOTIFY_DEVICEID = 14, |
| 31937 |
|
| 31938 |
OP_CB_ILLEGAL = 10044 |
| 31939 |
}; |
| 31940 |
|
| 31941 |
union nfs_cb_argop4 switch (unsigned argop) { |
| 31942 |
case OP_CB_GETATTR: |
| 31943 |
CB_GETATTR4args opcbgetattr; |
| 31944 |
case OP_CB_RECALL: |
| 31945 |
CB_RECALL4args opcbrecall; |
| 31946 |
case OP_CB_LAYOUTRECALL: |
| 31947 |
CB_LAYOUTRECALL4args opcblayoutrecall; |
| 31948 |
case OP_CB_NOTIFY: |
| 31949 |
CB_NOTIFY4args opcbnotify; |
| 31950 |
case OP_CB_PUSH_DELEG: |
| 31951 |
CB_PUSH_DELEG4args opcbpush_deleg; |
| 31952 |
case OP_CB_RECALL_ANY: |
| 31953 |
CB_RECALL_ANY4args opcbrecall_any; |
| 31954 |
case OP_CB_RECALLABLE_OBJ_AVAIL: |
| 31955 |
CB_RECALLABLE_OBJ_AVAIL4args opcbrecallable_obj_avail; |
| 31956 |
case OP_CB_RECALL_SLOT: |
| 31957 |
CB_RECALL_SLOT4args opcbrecall_slot; |
| 31958 |
case OP_CB_SEQUENCE: |
| 31959 |
CB_SEQUENCE4args opcbsequence; |
| 31960 |
case OP_CB_WANTS_CANCELLED: |
| 31961 |
CB_WANTS_CANCELLED4args opcbwants_cancelled; |
| 31962 |
case OP_CB_NOTIFY_LOCK: |
| 31963 |
CB_NOTIFY_LOCK4args opcbnotify_lock; |
| 31964 |
case OP_CB_NOTIFY_DEVICEID: |
| 31965 |
CB_NOTIFY_DEVICEID4args opcbnotify_deviceid; |
| 31966 |
case OP_CB_ILLEGAL: void; |
| 31967 |
}; |
| 31968 |
|
| 31969 |
|
| 31970 |
|
| 31971 |
|
| 31972 |
<span class="grey">Shepler, et al. Standards Track [Page 571]</span></pre> |
| 31973 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-572" ></span> |
| 31974 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 31975 |
|
| 31976 |
|
| 31977 |
struct CB_COMPOUND4args { |
| 31978 |
utf8str_cs tag; |
| 31979 |
uint32_t minorversion; |
| 31980 |
uint32_t callback_ident; |
| 31981 |
nfs_cb_argop4 argarray<>; |
| 31982 |
}; |
| 31983 |
|
| 31984 |
<span class="h4"><a class="selflink" id="section-19.2.2" href="#section-19.2.2">19.2.2</a>. RESULTS</span> |
| 31985 |
|
| 31986 |
union nfs_cb_resop4 switch (unsigned resop) { |
| 31987 |
case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; |
| 31988 |
case OP_CB_RECALL: CB_RECALL4res opcbrecall; |
| 31989 |
|
| 31990 |
/* new NFSv4.1 operations */ |
| 31991 |
case OP_CB_LAYOUTRECALL: |
| 31992 |
CB_LAYOUTRECALL4res |
| 31993 |
opcblayoutrecall; |
| 31994 |
|
| 31995 |
case OP_CB_NOTIFY: CB_NOTIFY4res opcbnotify; |
| 31996 |
|
| 31997 |
case OP_CB_PUSH_DELEG: CB_PUSH_DELEG4res |
| 31998 |
opcbpush_deleg; |
| 31999 |
|
| 32000 |
case OP_CB_RECALL_ANY: CB_RECALL_ANY4res |
| 32001 |
opcbrecall_any; |
| 32002 |
|
| 32003 |
case OP_CB_RECALLABLE_OBJ_AVAIL: |
| 32004 |
CB_RECALLABLE_OBJ_AVAIL4res |
| 32005 |
opcbrecallable_obj_avail; |
| 32006 |
|
| 32007 |
case OP_CB_RECALL_SLOT: |
| 32008 |
CB_RECALL_SLOT4res |
| 32009 |
opcbrecall_slot; |
| 32010 |
|
| 32011 |
case OP_CB_SEQUENCE: CB_SEQUENCE4res opcbsequence; |
| 32012 |
|
| 32013 |
case OP_CB_WANTS_CANCELLED: |
| 32014 |
CB_WANTS_CANCELLED4res |
| 32015 |
opcbwants_cancelled; |
| 32016 |
|
| 32017 |
case OP_CB_NOTIFY_LOCK: |
| 32018 |
CB_NOTIFY_LOCK4res |
| 32019 |
opcbnotify_lock; |
| 32020 |
|
| 32021 |
case OP_CB_NOTIFY_DEVICEID: |
| 32022 |
CB_NOTIFY_DEVICEID4res |
| 32023 |
opcbnotify_deviceid; |
| 32024 |
|
| 32025 |
|
| 32026 |
|
| 32027 |
|
| 32028 |
<span class="grey">Shepler, et al. Standards Track [Page 572]</span></pre> |
| 32029 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-573" ></span> |
| 32030 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32031 |
|
| 32032 |
|
| 32033 |
/* Not new operation */ |
| 32034 |
case OP_CB_ILLEGAL: CB_ILLEGAL4res opcbillegal; |
| 32035 |
}; |
| 32036 |
|
| 32037 |
struct CB_COMPOUND4res { |
| 32038 |
nfsstat4 status; |
| 32039 |
utf8str_cs tag; |
| 32040 |
nfs_cb_resop4 resarray<>; |
| 32041 |
}; |
| 32042 |
|
| 32043 |
<span class="h4"><a class="selflink" id="section-19.2.3" href="#section-19.2.3">19.2.3</a>. DESCRIPTION</span> |
| 32044 |
|
| 32045 |
The CB_COMPOUND procedure is used to combine one or more of the |
| 32046 |
callback procedures into a single RPC request. The main callback RPC |
| 32047 |
program has two main procedures: CB_NULL and CB_COMPOUND. All other |
| 32048 |
operations use the CB_COMPOUND procedure as a wrapper. |
| 32049 |
|
| 32050 |
During the processing of the CB_COMPOUND procedure, the client may |
| 32051 |
find that it does not have the available resources to execute any or |
| 32052 |
all of the operations within the CB_COMPOUND sequence. Refer to |
| 32053 |
<a href="#section-2.10.6.4">Section 2.10.6.4</a> for details. |
| 32054 |
|
| 32055 |
The minorversion field of the arguments MUST be the same as the |
| 32056 |
minorversion of the COMPOUND procedure used to create the client ID |
| 32057 |
and session. For NFSv4.1, minorversion MUST be set to 1. |
| 32058 |
|
| 32059 |
Contained within the CB_COMPOUND results is a "status" field. This |
| 32060 |
status MUST be equal to the status of the last operation that was |
| 32061 |
executed within the CB_COMPOUND procedure. Therefore, if an |
| 32062 |
operation incurred an error, then the "status" value will be the same |
| 32063 |
error value as is being returned for the operation that failed. |
| 32064 |
|
| 32065 |
The "tag" field is handled the same way as that of the COMPOUND |
| 32066 |
procedure (see <a href="#section-16.2.3">Section 16.2.3</a>). |
| 32067 |
|
| 32068 |
Illegal operation codes are handled in the same way as they are |
| 32069 |
handled for the COMPOUND procedure. |
| 32070 |
|
| 32071 |
<span class="h4"><a class="selflink" id="section-19.2.4" href="#section-19.2.4">19.2.4</a>. IMPLEMENTATION</span> |
| 32072 |
|
| 32073 |
The CB_COMPOUND procedure is used to combine individual operations |
| 32074 |
into a single RPC request. The client interprets each of the |
| 32075 |
operations in turn. If an operation is executed by the client and |
| 32076 |
the status of that operation is NFS4_OK, then the next operation in |
| 32077 |
the CB_COMPOUND procedure is executed. The client continues this |
| 32078 |
process until there are no more operations to be executed or one of |
| 32079 |
the operations has a status value other than NFS4_OK. |
| 32080 |
|
| 32081 |
|
| 32082 |
|
| 32083 |
|
| 32084 |
<span class="grey">Shepler, et al. Standards Track [Page 573]</span></pre> |
| 32085 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-574" ></span> |
| 32086 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32087 |
|
| 32088 |
|
| 32089 |
<span class="h4"><a class="selflink" id="section-19.2.5" href="#section-19.2.5">19.2.5</a>. ERRORS</span> |
| 32090 |
|
| 32091 |
CB_COMPOUND will of course return every error that each operation on |
| 32092 |
the backchannel can return (see Table 7). However, if CB_COMPOUND |
| 32093 |
returns zero operations, obviously the error returned by COMPOUND has |
| 32094 |
nothing to do with an error returned by an operation. The list of |
| 32095 |
errors CB_COMPOUND will return if it processes zero operations |
| 32096 |
includes: |
| 32097 |
|
| 32098 |
CB_COMPOUND error returns |
| 32099 |
|
| 32100 |
+------------------------------+------------------------------------+ |
| 32101 |
| Error | Notes | |
| 32102 |
+------------------------------+------------------------------------+ |
| 32103 |
| NFS4ERR_BADCHAR | The tag argument has a character | |
| 32104 |
| | the replier does not support. | |
| 32105 |
| NFS4ERR_BADXDR | | |
| 32106 |
| NFS4ERR_DELAY | | |
| 32107 |
| NFS4ERR_INVAL | The tag argument is not in UTF-8 | |
| 32108 |
| | encoding. | |
| 32109 |
| NFS4ERR_MINOR_VERS_MISMATCH | | |
| 32110 |
| NFS4ERR_SERVERFAULT | | |
| 32111 |
| NFS4ERR_TOO_MANY_OPS | | |
| 32112 |
| NFS4ERR_REP_TOO_BIG | | |
| 32113 |
| NFS4ERR_REP_TOO_BIG_TO_CACHE | | |
| 32114 |
| NFS4ERR_REQ_TOO_BIG | | |
| 32115 |
+------------------------------+------------------------------------+ |
| 32116 |
|
| 32117 |
Table 15 |
| 32118 |
|
| 32119 |
<span class="h2"><a class="selflink" id="section-20" href="#section-20">20</a>. NFSv4.1 Callback Operations</span> |
| 32120 |
|
| 32121 |
<span class="h3"><a class="selflink" id="section-20.1" href="#section-20.1">20.1</a>. Operation 3: CB_GETATTR - Get Attributes</span> |
| 32122 |
|
| 32123 |
<span class="h4"><a class="selflink" id="section-20.1.1" href="#section-20.1.1">20.1.1</a>. ARGUMENT</span> |
| 32124 |
|
| 32125 |
struct CB_GETATTR4args { |
| 32126 |
nfs_fh4 fh; |
| 32127 |
bitmap4 attr_request; |
| 32128 |
}; |
| 32129 |
|
| 32130 |
|
| 32131 |
|
| 32132 |
|
| 32133 |
|
| 32134 |
|
| 32135 |
|
| 32136 |
|
| 32137 |
|
| 32138 |
|
| 32139 |
|
| 32140 |
<span class="grey">Shepler, et al. Standards Track [Page 574]</span></pre> |
| 32141 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-575" ></span> |
| 32142 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32143 |
|
| 32144 |
|
| 32145 |
<span class="h4"><a class="selflink" id="section-20.1.2" href="#section-20.1.2">20.1.2</a>. RESULT</span> |
| 32146 |
|
| 32147 |
struct CB_GETATTR4resok { |
| 32148 |
fattr4 obj_attributes; |
| 32149 |
}; |
| 32150 |
|
| 32151 |
union CB_GETATTR4res switch (nfsstat4 status) { |
| 32152 |
case NFS4_OK: |
| 32153 |
CB_GETATTR4resok resok4; |
| 32154 |
default: |
| 32155 |
void; |
| 32156 |
}; |
| 32157 |
|
| 32158 |
<span class="h4"><a class="selflink" id="section-20.1.3" href="#section-20.1.3">20.1.3</a>. DESCRIPTION</span> |
| 32159 |
|
| 32160 |
The CB_GETATTR operation is used by the server to obtain the current |
| 32161 |
modified state of a file that has been OPEN_DELEGATE_WRITE delegated. |
| 32162 |
The size and change attributes are the only ones guaranteed to be |
| 32163 |
serviced by the client. See <a href="#section-10.4.3">Section 10.4.3</a> for a full description of |
| 32164 |
how the client and server are to interact with the use of CB_GETATTR. |
| 32165 |
|
| 32166 |
If the filehandle specified is not one for which the client holds an |
| 32167 |
OPEN_DELEGATE_WRITE delegation, an NFS4ERR_BADHANDLE error is |
| 32168 |
returned. |
| 32169 |
|
| 32170 |
<span class="h4"><a class="selflink" id="section-20.1.4" href="#section-20.1.4">20.1.4</a>. IMPLEMENTATION</span> |
| 32171 |
|
| 32172 |
The client returns attrmask bits and the associated attribute values |
| 32173 |
only for the change attribute, and attributes that it may change |
| 32174 |
(time_modify, and size). |
| 32175 |
|
| 32176 |
<span class="h3"><a class="selflink" id="section-20.2" href="#section-20.2">20.2</a>. Operation 4: CB_RECALL - Recall a Delegation</span> |
| 32177 |
|
| 32178 |
<span class="h4"><a class="selflink" id="section-20.2.1" href="#section-20.2.1">20.2.1</a>. ARGUMENT</span> |
| 32179 |
|
| 32180 |
struct CB_RECALL4args { |
| 32181 |
stateid4 stateid; |
| 32182 |
bool truncate; |
| 32183 |
nfs_fh4 fh; |
| 32184 |
}; |
| 32185 |
|
| 32186 |
<span class="h4"><a class="selflink" id="section-20.2.2" href="#section-20.2.2">20.2.2</a>. RESULT</span> |
| 32187 |
|
| 32188 |
struct CB_RECALL4res { |
| 32189 |
nfsstat4 status; |
| 32190 |
}; |
| 32191 |
|
| 32192 |
|
| 32193 |
|
| 32194 |
|
| 32195 |
|
| 32196 |
<span class="grey">Shepler, et al. Standards Track [Page 575]</span></pre> |
| 32197 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-576" ></span> |
| 32198 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32199 |
|
| 32200 |
|
| 32201 |
<span class="h4"><a class="selflink" id="section-20.2.3" href="#section-20.2.3">20.2.3</a>. DESCRIPTION</span> |
| 32202 |
|
| 32203 |
The CB_RECALL operation is used to begin the process of recalling a |
| 32204 |
delegation and returning it to the server. |
| 32205 |
|
| 32206 |
The truncate flag is used to optimize recall for a file object that |
| 32207 |
is a regular file and is about to be truncated to zero. When it is |
| 32208 |
TRUE, the client is freed of the obligation to propagate modified |
| 32209 |
data for the file to the server, since this data is irrelevant. |
| 32210 |
|
| 32211 |
If the handle specified is not one for which the client holds a |
| 32212 |
delegation, an NFS4ERR_BADHANDLE error is returned. |
| 32213 |
|
| 32214 |
If the stateid specified is not one corresponding to an OPEN |
| 32215 |
delegation for the file specified by the filehandle, an |
| 32216 |
NFS4ERR_BAD_STATEID is returned. |
| 32217 |
|
| 32218 |
<span class="h4"><a class="selflink" id="section-20.2.4" href="#section-20.2.4">20.2.4</a>. IMPLEMENTATION</span> |
| 32219 |
|
| 32220 |
The client SHOULD reply to the callback immediately. Replying does |
| 32221 |
not complete the recall except when the value of the reply's status |
| 32222 |
field is neither NFS4ERR_DELAY nor NFS4_OK. The recall is not |
| 32223 |
complete until the delegation is returned using a DELEGRETURN |
| 32224 |
operation. |
| 32225 |
|
| 32226 |
<span class="h3"><a class="selflink" id="section-20.3" href="#section-20.3">20.3</a>. Operation 5: CB_LAYOUTRECALL - Recall Layout from Client</span> |
| 32227 |
|
| 32228 |
<span class="h4"><a class="selflink" id="section-20.3.1" href="#section-20.3.1">20.3.1</a>. ARGUMENT</span> |
| 32229 |
|
| 32230 |
/* |
| 32231 |
* NFSv4.1 callback arguments and results |
| 32232 |
*/ |
| 32233 |
|
| 32234 |
enum layoutrecall_type4 { |
| 32235 |
LAYOUTRECALL4_FILE = LAYOUT4_RET_REC_FILE, |
| 32236 |
LAYOUTRECALL4_FSID = LAYOUT4_RET_REC_FSID, |
| 32237 |
LAYOUTRECALL4_ALL = LAYOUT4_RET_REC_ALL |
| 32238 |
}; |
| 32239 |
|
| 32240 |
struct layoutrecall_file4 { |
| 32241 |
nfs_fh4 lor_fh; |
| 32242 |
offset4 lor_offset; |
| 32243 |
length4 lor_length; |
| 32244 |
stateid4 lor_stateid; |
| 32245 |
}; |
| 32246 |
|
| 32247 |
|
| 32248 |
|
| 32249 |
|
| 32250 |
|
| 32251 |
|
| 32252 |
<span class="grey">Shepler, et al. Standards Track [Page 576]</span></pre> |
| 32253 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-577" ></span> |
| 32254 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32255 |
|
| 32256 |
|
| 32257 |
union layoutrecall4 switch(layoutrecall_type4 lor_recalltype) { |
| 32258 |
case LAYOUTRECALL4_FILE: |
| 32259 |
layoutrecall_file4 lor_layout; |
| 32260 |
case LAYOUTRECALL4_FSID: |
| 32261 |
fsid4 lor_fsid; |
| 32262 |
case LAYOUTRECALL4_ALL: |
| 32263 |
void; |
| 32264 |
}; |
| 32265 |
|
| 32266 |
struct CB_LAYOUTRECALL4args { |
| 32267 |
layouttype4 clora_type; |
| 32268 |
layoutiomode4 clora_iomode; |
| 32269 |
bool clora_changed; |
| 32270 |
layoutrecall4 clora_recall; |
| 32271 |
}; |
| 32272 |
|
| 32273 |
<span class="h4"><a class="selflink" id="section-20.3.2" href="#section-20.3.2">20.3.2</a>. RESULT</span> |
| 32274 |
|
| 32275 |
struct CB_LAYOUTRECALL4res { |
| 32276 |
nfsstat4 clorr_status; |
| 32277 |
}; |
| 32278 |
|
| 32279 |
<span class="h4"><a class="selflink" id="section-20.3.3" href="#section-20.3.3">20.3.3</a>. DESCRIPTION</span> |
| 32280 |
|
| 32281 |
The CB_LAYOUTRECALL operation is used by the server to recall layouts |
| 32282 |
from the client; as a result, the client will begin the process of |
| 32283 |
returning layouts via LAYOUTRETURN. The CB_LAYOUTRECALL operation |
| 32284 |
specifies one of three forms of recall processing with the value of |
| 32285 |
layoutrecall_type4. The recall is for one of the following: a |
| 32286 |
specific layout of a specific file (LAYOUTRECALL4_FILE), an entire |
| 32287 |
file system ID (LAYOUTRECALL4_FSID), or all file systems |
| 32288 |
(LAYOUTRECALL4_ALL). |
| 32289 |
|
| 32290 |
The behavior of the operation varies based on the value of the |
| 32291 |
layoutrecall_type4. The value and behaviors are: |
| 32292 |
|
| 32293 |
LAYOUTRECALL4_FILE |
| 32294 |
|
| 32295 |
For a layout to match the recall request, the values of the |
| 32296 |
following fields must match those of the layout: clora_type, |
| 32297 |
clora_iomode, lor_fh, and the byte-range specified by lor_offset |
| 32298 |
and lor_length. The clora_iomode field may have a special value |
| 32299 |
of LAYOUTIOMODE4_ANY. The special value LAYOUTIOMODE4_ANY will |
| 32300 |
match any iomode originally returned in a layout; therefore, it |
| 32301 |
acts as a wild card. The other special value used is for |
| 32302 |
lor_length. If lor_length has a value of NFS4_UINT64_MAX, the |
| 32303 |
lor_length field means the maximum possible file size. If a |
| 32304 |
matching layout is found, it MUST be returned using the |
| 32305 |
|
| 32306 |
|
| 32307 |
|
| 32308 |
<span class="grey">Shepler, et al. Standards Track [Page 577]</span></pre> |
| 32309 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-578" ></span> |
| 32310 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32311 |
|
| 32312 |
|
| 32313 |
LAYOUTRETURN operation (see <a href="#section-18.44">Section 18.44</a>). An example of the |
| 32314 |
field's special value use is if clora_iomode is LAYOUTIOMODE4_ANY, |
| 32315 |
lor_offset is zero, and lor_length is NFS4_UINT64_MAX, then the |
| 32316 |
entire layout is to be returned. |
| 32317 |
|
| 32318 |
The NFS4ERR_NOMATCHING_LAYOUT error is only returned when the |
| 32319 |
client does not hold layouts for the file or if the client does |
| 32320 |
not have any overlapping layouts for the specification in the |
| 32321 |
layout recall. |
| 32322 |
|
| 32323 |
LAYOUTRECALL4_FSID and LAYOUTRECALL4_ALL |
| 32324 |
|
| 32325 |
If LAYOUTRECALL4_FSID is specified, the fsid specifies the file |
| 32326 |
system for which any outstanding layouts MUST be returned. If |
| 32327 |
LAYOUTRECALL4_ALL is specified, all outstanding layouts MUST be |
| 32328 |
returned. In addition, LAYOUTRECALL4_FSID and LAYOUTRECALL4_ALL |
| 32329 |
specify that all the storage device ID to storage device address |
| 32330 |
mappings in the affected file system(s) are also recalled. The |
| 32331 |
respective LAYOUTRETURN with either LAYOUTRETURN4_FSID or |
| 32332 |
LAYOUTRETURN4_ALL acknowledges to the server that the client |
| 32333 |
invalidated the said device mappings. See <a href="#section-12.5.5.2.1.5">Section 12.5.5.2.1.5</a> |
| 32334 |
for considerations with "bulk" recall of layouts. |
| 32335 |
|
| 32336 |
The NFS4ERR_NOMATCHING_LAYOUT error is only returned when the |
| 32337 |
client does not hold layouts and does not have valid deviceid |
| 32338 |
mappings. |
| 32339 |
|
| 32340 |
In processing the layout recall request, the client also varies its |
| 32341 |
behavior based on the value of the clora_changed field. This field |
| 32342 |
is used by the server to provide additional context for the reason |
| 32343 |
why the layout is being recalled. A FALSE value for clora_changed |
| 32344 |
indicates that no change in the layout is expected and the client may |
| 32345 |
write modified data to the storage devices involved; this must be |
| 32346 |
done prior to returning the layout via LAYOUTRETURN. A TRUE value |
| 32347 |
for clora_changed indicates that the server is changing the layout. |
| 32348 |
Examples of layout changes and reasons for a TRUE indication are the |
| 32349 |
following: the metadata server is restriping the file or a permanent |
| 32350 |
error has occurred on a storage device and the metadata server would |
| 32351 |
like to provide a new layout for the file. Therefore, a |
| 32352 |
clora_changed value of TRUE indicates some level of change for the |
| 32353 |
layout and the client SHOULD NOT write and commit modified data to |
| 32354 |
the storage devices. In this case, the client writes and commits |
| 32355 |
data through the metadata server. |
| 32356 |
|
| 32357 |
See <a href="#section-12.5.3">Section 12.5.3</a> for a description of how the lor_stateid field in |
| 32358 |
the arguments is to be constructed. Note that the "seqid" field of |
| 32359 |
lor_stateid MUST NOT be zero. See Sections <a href="#section-8.2">8.2</a>, <a href="#section-12.5.3">12.5.3</a>, and <a href="#section-12.5.5.2">12.5.5.2</a> |
| 32360 |
for a further discussion and requirements. |
| 32361 |
|
| 32362 |
|
| 32363 |
|
| 32364 |
<span class="grey">Shepler, et al. Standards Track [Page 578]</span></pre> |
| 32365 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-579" ></span> |
| 32366 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32367 |
|
| 32368 |
|
| 32369 |
<span class="h4"><a class="selflink" id="section-20.3.4" href="#section-20.3.4">20.3.4</a>. IMPLEMENTATION</span> |
| 32370 |
|
| 32371 |
The client's processing for CB_LAYOUTRECALL is similar to CB_RECALL |
| 32372 |
(recall of file delegations) in that the client responds to the |
| 32373 |
request before actually returning layouts via the LAYOUTRETURN |
| 32374 |
operation. While the client responds to the CB_LAYOUTRECALL |
| 32375 |
immediately, the operation is not considered complete (i.e., |
| 32376 |
considered pending) until all affected layouts are returned to the |
| 32377 |
server via the LAYOUTRETURN operation. |
| 32378 |
|
| 32379 |
Before returning the layout to the server via LAYOUTRETURN, the |
| 32380 |
client should wait for the response from in-process or in-flight |
| 32381 |
READ, WRITE, or COMMIT operations that use the recalled layout. |
| 32382 |
|
| 32383 |
If the client is holding modified data that is affected by a recalled |
| 32384 |
layout, the client has various options for writing the data to the |
| 32385 |
server. As always, the client may write the data through the |
| 32386 |
metadata server. In fact, the client may not have a choice other |
| 32387 |
than writing to the metadata server when the clora_changed argument |
| 32388 |
is TRUE and a new layout is unavailable from the server. However, |
| 32389 |
the client may be able to write the modified data to the storage |
| 32390 |
device if the clora_changed argument is FALSE; this needs to be done |
| 32391 |
before returning the layout via LAYOUTRETURN. If the client were to |
| 32392 |
obtain a new layout covering the modified data's byte-range, then |
| 32393 |
writing to the storage devices is an available alternative. Note |
| 32394 |
that before obtaining a new layout, the client must first return the |
| 32395 |
original layout. |
| 32396 |
|
| 32397 |
In the case of modified data being written while the layout is held, |
| 32398 |
the client must use LAYOUTCOMMIT operations at the appropriate time; |
| 32399 |
as required LAYOUTCOMMIT must be done before the LAYOUTRETURN. If a |
| 32400 |
large amount of modified data is outstanding, the client may send |
| 32401 |
LAYOUTRETURNs for portions of the recalled layout; this allows the |
| 32402 |
server to monitor the client's progress and adherence to the original |
| 32403 |
recall request. However, the last LAYOUTRETURN in a sequence of |
| 32404 |
returns MUST specify the full range being recalled (see |
| 32405 |
<a href="#section-12.5.5.1">Section 12.5.5.1</a> for details). |
| 32406 |
|
| 32407 |
If a server needs to delete a device ID and there are layouts |
| 32408 |
referring to the device ID, CB_LAYOUTRECALL MUST be invoked to cause |
| 32409 |
the client to return all layouts referring to the device ID before |
| 32410 |
the server can delete the device ID. If the client does not return |
| 32411 |
the affected layouts, the server MAY revoke the layouts. |
| 32412 |
|
| 32413 |
|
| 32414 |
|
| 32415 |
|
| 32416 |
|
| 32417 |
|
| 32418 |
|
| 32419 |
|
| 32420 |
<span class="grey">Shepler, et al. Standards Track [Page 579]</span></pre> |
| 32421 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-580" ></span> |
| 32422 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32423 |
|
| 32424 |
|
| 32425 |
<span class="h3"><a class="selflink" id="section-20.4" href="#section-20.4">20.4</a>. Operation 6: CB_NOTIFY - Notify Client of Directory Changes</span> |
| 32426 |
|
| 32427 |
<span class="h4"><a class="selflink" id="section-20.4.1" href="#section-20.4.1">20.4.1</a>. ARGUMENT</span> |
| 32428 |
|
| 32429 |
/* |
| 32430 |
* Directory notification types. |
| 32431 |
*/ |
| 32432 |
enum notify_type4 { |
| 32433 |
NOTIFY4_CHANGE_CHILD_ATTRS = 0, |
| 32434 |
NOTIFY4_CHANGE_DIR_ATTRS = 1, |
| 32435 |
NOTIFY4_REMOVE_ENTRY = 2, |
| 32436 |
NOTIFY4_ADD_ENTRY = 3, |
| 32437 |
NOTIFY4_RENAME_ENTRY = 4, |
| 32438 |
NOTIFY4_CHANGE_COOKIE_VERIFIER = 5 |
| 32439 |
}; |
| 32440 |
|
| 32441 |
/* Changed entry information. */ |
| 32442 |
struct notify_entry4 { |
| 32443 |
component4 ne_file; |
| 32444 |
fattr4 ne_attrs; |
| 32445 |
}; |
| 32446 |
|
| 32447 |
/* Previous entry information */ |
| 32448 |
struct prev_entry4 { |
| 32449 |
notify_entry4 pe_prev_entry; |
| 32450 |
/* what READDIR returned for this entry */ |
| 32451 |
nfs_cookie4 pe_prev_entry_cookie; |
| 32452 |
}; |
| 32453 |
|
| 32454 |
struct notify_remove4 { |
| 32455 |
notify_entry4 nrm_old_entry; |
| 32456 |
nfs_cookie4 nrm_old_entry_cookie; |
| 32457 |
}; |
| 32458 |
|
| 32459 |
struct notify_add4 { |
| 32460 |
/* |
| 32461 |
* Information on object |
| 32462 |
* possibly renamed over. |
| 32463 |
*/ |
| 32464 |
notify_remove4 nad_old_entry<1>; |
| 32465 |
notify_entry4 nad_new_entry; |
| 32466 |
/* what READDIR would have returned for this entry */ |
| 32467 |
nfs_cookie4 nad_new_entry_cookie<1>; |
| 32468 |
prev_entry4 nad_prev_entry<1>; |
| 32469 |
bool nad_last_entry; |
| 32470 |
}; |
| 32471 |
|
| 32472 |
|
| 32473 |
|
| 32474 |
|
| 32475 |
|
| 32476 |
<span class="grey">Shepler, et al. Standards Track [Page 580]</span></pre> |
| 32477 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-581" ></span> |
| 32478 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32479 |
|
| 32480 |
|
| 32481 |
struct notify_attr4 { |
| 32482 |
notify_entry4 na_changed_entry; |
| 32483 |
}; |
| 32484 |
|
| 32485 |
struct notify_rename4 { |
| 32486 |
notify_remove4 nrn_old_entry; |
| 32487 |
notify_add4 nrn_new_entry; |
| 32488 |
}; |
| 32489 |
|
| 32490 |
struct notify_verifier4 { |
| 32491 |
verifier4 nv_old_cookieverf; |
| 32492 |
verifier4 nv_new_cookieverf; |
| 32493 |
}; |
| 32494 |
|
| 32495 |
/* |
| 32496 |
* Objects of type notify_<>4 and |
| 32497 |
* notify_device_<>4 are encoded in this. |
| 32498 |
*/ |
| 32499 |
typedef opaque notifylist4<>; |
| 32500 |
|
| 32501 |
struct notify4 { |
| 32502 |
/* composed from notify_type4 or notify_deviceid_type4 */ |
| 32503 |
bitmap4 notify_mask; |
| 32504 |
notifylist4 notify_vals; |
| 32505 |
}; |
| 32506 |
|
| 32507 |
struct CB_NOTIFY4args { |
| 32508 |
stateid4 cna_stateid; |
| 32509 |
nfs_fh4 cna_fh; |
| 32510 |
notify4 cna_changes<>; |
| 32511 |
}; |
| 32512 |
|
| 32513 |
<span class="h4"><a class="selflink" id="section-20.4.2" href="#section-20.4.2">20.4.2</a>. RESULT</span> |
| 32514 |
|
| 32515 |
struct CB_NOTIFY4res { |
| 32516 |
nfsstat4 cnr_status; |
| 32517 |
}; |
| 32518 |
|
| 32519 |
<span class="h4"><a class="selflink" id="section-20.4.3" href="#section-20.4.3">20.4.3</a>. DESCRIPTION</span> |
| 32520 |
|
| 32521 |
The CB_NOTIFY operation is used by the server to send notifications |
| 32522 |
to clients about changes to delegated directories. The registration |
| 32523 |
of notifications for the directories occurs when the delegation is |
| 32524 |
established using GET_DIR_DELEGATION. These notifications are sent |
| 32525 |
over the backchannel. The notification is sent once the original |
| 32526 |
request has been processed on the server. The server will send an |
| 32527 |
array of notifications for changes that might have occurred in the |
| 32528 |
|
| 32529 |
|
| 32530 |
|
| 32531 |
|
| 32532 |
<span class="grey">Shepler, et al. Standards Track [Page 581]</span></pre> |
| 32533 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-582" ></span> |
| 32534 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32535 |
|
| 32536 |
|
| 32537 |
directory. The notifications are sent as list of pairs of bitmaps |
| 32538 |
and values. See <a href="#section-3.3.7">Section 3.3.7</a> for a description of how NFSv4.1 |
| 32539 |
bitmaps work. |
| 32540 |
|
| 32541 |
If the server has more notifications than can fit in the CB_COMPOUND |
| 32542 |
request, it SHOULD send a sequence of serial CB_COMPOUND requests so |
| 32543 |
that the client's view of the directory does not become confused. |
| 32544 |
For example, if the server indicates that a file named "foo" is added |
| 32545 |
and that the file "foo" is removed, the order in which the client |
| 32546 |
receives these notifications needs to be the same as the order in |
| 32547 |
which the corresponding operations occurred on the server. |
| 32548 |
|
| 32549 |
If the client holding the delegation makes any changes in the |
| 32550 |
directory that cause files or sub-directories to be added or removed, |
| 32551 |
the server will notify that client of the resulting change(s). If |
| 32552 |
the client holding the delegation is making attribute or cookie |
| 32553 |
verifier changes only, the server does not need to send notifications |
| 32554 |
to that client. The server will send the following information for |
| 32555 |
each operation: |
| 32556 |
|
| 32557 |
NOTIFY4_ADD_ENTRY |
| 32558 |
The server will send information about the new directory entry |
| 32559 |
being created along with the cookie for that entry. The entry |
| 32560 |
information (data type notify_add4) includes the component name of |
| 32561 |
the entry and attributes. The server will send this type of entry |
| 32562 |
when a file is actually being created, when an entry is being |
| 32563 |
added to a directory as a result of a rename across directories |
| 32564 |
(see below), and when a hard link is being created to an existing |
| 32565 |
file. If this entry is added to the end of the directory, the |
| 32566 |
server will set the nad_last_entry flag to TRUE. If the file is |
| 32567 |
added such that there is at least one entry before it, the server |
| 32568 |
will also return the previous entry information (nad_prev_entry, a |
| 32569 |
variable-length array of up to one element. If the array is of |
| 32570 |
zero length, there is no previous entry), along with its cookie. |
| 32571 |
This is to help clients find the right location in their file name |
| 32572 |
caches and directory caches where this entry should be cached. If |
| 32573 |
the new entry's cookie is available, it will be in the |
| 32574 |
nad_new_entry_cookie (another variable-length array of up to one |
| 32575 |
element) field. If the addition of the entry causes another entry |
| 32576 |
to be deleted (which can only happen in the rename case) |
| 32577 |
atomically with the addition, then information on this entry is |
| 32578 |
reported in nad_old_entry. |
| 32579 |
|
| 32580 |
NOTIFY4_REMOVE_ENTRY |
| 32581 |
The server will send information about the directory entry being |
| 32582 |
deleted. The server will also send the cookie value for the |
| 32583 |
deleted entry so that clients can get to the cached information |
| 32584 |
for this entry. |
| 32585 |
|
| 32586 |
|
| 32587 |
|
| 32588 |
<span class="grey">Shepler, et al. Standards Track [Page 582]</span></pre> |
| 32589 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-583" ></span> |
| 32590 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32591 |
|
| 32592 |
|
| 32593 |
NOTIFY4_RENAME_ENTRY |
| 32594 |
The server will send information about both the old entry and the |
| 32595 |
new entry. This includes the name and attributes for each entry. |
| 32596 |
In addition, if the rename causes the deletion of an entry (i.e., |
| 32597 |
the case of a file renamed over), then this is reported in |
| 32598 |
nrn_new_new_entry.nad_old_entry. This notification is only sent |
| 32599 |
if both entries are in the same directory. If the rename is |
| 32600 |
across directories, the server will send a remove notification to |
| 32601 |
one directory and an add notification to the other directory, |
| 32602 |
assuming both have a directory delegation. |
| 32603 |
|
| 32604 |
NOTIFY4_CHANGE_CHILD_ATTRS/NOTIFY4_CHANGE_DIR_ATTRS |
| 32605 |
The client will use the attribute mask to inform the server of |
| 32606 |
attributes for which it wants to receive notifications. This |
| 32607 |
change notification can be requested for changes to the attributes |
| 32608 |
of the directory as well as changes to any file's attributes in |
| 32609 |
the directory by using two separate attribute masks. The client |
| 32610 |
cannot ask for change attribute notification for a specific file. |
| 32611 |
One attribute mask covers all the files in the directory. Upon |
| 32612 |
any attribute change, the server will send back the values of |
| 32613 |
changed attributes. Notifications might not make sense for some |
| 32614 |
file system-wide attributes, and it is up to the server to decide |
| 32615 |
which subset it wants to support. The client can negotiate the |
| 32616 |
frequency of attribute notifications by letting the server know |
| 32617 |
how often it wants to be notified of an attribute change. The |
| 32618 |
server will return supported notification frequencies or an |
| 32619 |
indication that no notification is permitted for directory or |
| 32620 |
child attributes by setting the dir_notif_delay and |
| 32621 |
dir_entry_notif_delay attributes, respectively. |
| 32622 |
|
| 32623 |
NOTIFY4_CHANGE_COOKIE_VERIFIER |
| 32624 |
If the cookie verifier changes while a client is holding a |
| 32625 |
delegation, the server will notify the client so that it can |
| 32626 |
invalidate its cookies and re-send a READDIR to get the new set of |
| 32627 |
cookies. |
| 32628 |
|
| 32629 |
<span class="h3"><a class="selflink" id="section-20.5" href="#section-20.5">20.5</a>. Operation 7: CB_PUSH_DELEG - Offer Previously Requested</span> |
| 32630 |
<span class="h3"> Delegation to Client</span> |
| 32631 |
|
| 32632 |
<span class="h4"><a class="selflink" id="section-20.5.1" href="#section-20.5.1">20.5.1</a>. ARGUMENT</span> |
| 32633 |
|
| 32634 |
struct CB_PUSH_DELEG4args { |
| 32635 |
nfs_fh4 cpda_fh; |
| 32636 |
open_delegation4 cpda_delegation; |
| 32637 |
|
| 32638 |
}; |
| 32639 |
|
| 32640 |
|
| 32641 |
|
| 32642 |
|
| 32643 |
|
| 32644 |
<span class="grey">Shepler, et al. Standards Track [Page 583]</span></pre> |
| 32645 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-584" ></span> |
| 32646 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32647 |
|
| 32648 |
|
| 32649 |
<span class="h4"><a class="selflink" id="section-20.5.2" href="#section-20.5.2">20.5.2</a>. RESULT</span> |
| 32650 |
|
| 32651 |
struct CB_PUSH_DELEG4res { |
| 32652 |
nfsstat4 cpdr_status; |
| 32653 |
}; |
| 32654 |
|
| 32655 |
<span class="h4"><a class="selflink" id="section-20.5.3" href="#section-20.5.3">20.5.3</a>. DESCRIPTION</span> |
| 32656 |
|
| 32657 |
CB_PUSH_DELEG is used by the server both to signal to the client that |
| 32658 |
the delegation it wants (previously indicated via a want established |
| 32659 |
from an OPEN or WANT_DELEGATION operation) is available and to |
| 32660 |
simultaneously offer the delegation to the client. The client has |
| 32661 |
the choice of accepting the delegation by returning NFS4_OK to the |
| 32662 |
server, delaying the decision to accept the offered delegation by |
| 32663 |
returning NFS4ERR_DELAY, or permanently rejecting the offer of the |
| 32664 |
delegation by returning NFS4ERR_REJECT_DELEG. When a delegation is |
| 32665 |
rejected in this fashion, the want previously established is |
| 32666 |
permanently deleted and the delegation is subject to acquisition by |
| 32667 |
another client. |
| 32668 |
|
| 32669 |
<span class="h4"><a class="selflink" id="section-20.5.4" href="#section-20.5.4">20.5.4</a>. IMPLEMENTATION</span> |
| 32670 |
|
| 32671 |
If the client does return NFS4ERR_DELAY and there is a conflicting |
| 32672 |
delegation request, the server MAY process it at the expense of the |
| 32673 |
client that returned NFS4ERR_DELAY. The client's want will not be |
| 32674 |
cancelled, but MAY be processed behind other delegation requests or |
| 32675 |
registered wants. |
| 32676 |
|
| 32677 |
When a client returns a status other than NFS4_OK, NFS4ERR_DELAY, or |
| 32678 |
NFS4ERR_REJECT_DELAY, the want remains pending, although servers may |
| 32679 |
decide to cancel the want by sending a CB_WANTS_CANCELLED. |
| 32680 |
|
| 32681 |
<span class="h3"><a class="selflink" id="section-20.6" href="#section-20.6">20.6</a>. Operation 8: CB_RECALL_ANY - Keep Any N Recallable Objects</span> |
| 32682 |
|
| 32683 |
<span class="h4"><a class="selflink" id="section-20.6.1" href="#section-20.6.1">20.6.1</a>. ARGUMENT</span> |
| 32684 |
|
| 32685 |
const RCA4_TYPE_MASK_RDATA_DLG = 0; |
| 32686 |
const RCA4_TYPE_MASK_WDATA_DLG = 1; |
| 32687 |
const RCA4_TYPE_MASK_DIR_DLG = 2; |
| 32688 |
const RCA4_TYPE_MASK_FILE_LAYOUT = 3; |
| 32689 |
const RCA4_TYPE_MASK_BLK_LAYOUT = 4; |
| 32690 |
const RCA4_TYPE_MASK_OBJ_LAYOUT_MIN = 8; |
| 32691 |
const RCA4_TYPE_MASK_OBJ_LAYOUT_MAX = 9; |
| 32692 |
const RCA4_TYPE_MASK_OTHER_LAYOUT_MIN = 12; |
| 32693 |
const RCA4_TYPE_MASK_OTHER_LAYOUT_MAX = 15; |
| 32694 |
|
| 32695 |
|
| 32696 |
|
| 32697 |
|
| 32698 |
|
| 32699 |
|
| 32700 |
<span class="grey">Shepler, et al. Standards Track [Page 584]</span></pre> |
| 32701 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-585" ></span> |
| 32702 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32703 |
|
| 32704 |
|
| 32705 |
struct CB_RECALL_ANY4args { |
| 32706 |
uint32_t craa_objects_to_keep; |
| 32707 |
bitmap4 craa_type_mask; |
| 32708 |
}; |
| 32709 |
|
| 32710 |
<span class="h4"><a class="selflink" id="section-20.6.2" href="#section-20.6.2">20.6.2</a>. RESULT</span> |
| 32711 |
|
| 32712 |
struct CB_RECALL_ANY4res { |
| 32713 |
nfsstat4 crar_status; |
| 32714 |
}; |
| 32715 |
|
| 32716 |
<span class="h4"><a class="selflink" id="section-20.6.3" href="#section-20.6.3">20.6.3</a>. DESCRIPTION</span> |
| 32717 |
|
| 32718 |
The server may decide that it cannot hold all of the state for |
| 32719 |
recallable objects, such as delegations and layouts, without running |
| 32720 |
out of resources. In such a case, while not optimal, the server is |
| 32721 |
free to recall individual objects to reduce the load. |
| 32722 |
|
| 32723 |
Because the general purpose of such recallable objects as delegations |
| 32724 |
is to eliminate client interaction with the server, the server cannot |
| 32725 |
interpret lack of recent use as indicating that the object is no |
| 32726 |
longer useful. The absence of visible use is consistent with a |
| 32727 |
delegation keeping potential operations from being sent to the |
| 32728 |
server. In the case of layouts, while it is true that the usefulness |
| 32729 |
of a layout is indicated by the use of the layout when storage |
| 32730 |
devices receive I/O requests, because there is no mandate that a |
| 32731 |
storage device indicate to the metadata server any past or present |
| 32732 |
use of a layout, the metadata server is not likely to know which |
| 32733 |
layouts are good candidates to recall in response to low resources. |
| 32734 |
|
| 32735 |
In order to implement an effective reclaim scheme for such objects, |
| 32736 |
the server's knowledge of available resources must be used to |
| 32737 |
determine when objects must be recalled with the clients selecting |
| 32738 |
the actual objects to be returned. |
| 32739 |
|
| 32740 |
Server implementations may differ in their resource allocation |
| 32741 |
requirements. For example, one server may share resources among all |
| 32742 |
classes of recallable objects, whereas another may use separate |
| 32743 |
resource pools for layouts and for delegations, or further separate |
| 32744 |
resources by types of delegations. |
| 32745 |
|
| 32746 |
When a given resource pool is over-utilized, the server can send a |
| 32747 |
CB_RECALL_ANY to clients holding recallable objects of the types |
| 32748 |
involved, allowing it to keep a certain number of such objects and |
| 32749 |
return any excess. A mask specifies which types of objects are to be |
| 32750 |
limited. The client chooses, based on its own knowledge of current |
| 32751 |
usefulness, which of the objects in that class should be returned. |
| 32752 |
|
| 32753 |
|
| 32754 |
|
| 32755 |
|
| 32756 |
<span class="grey">Shepler, et al. Standards Track [Page 585]</span></pre> |
| 32757 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-586" ></span> |
| 32758 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32759 |
|
| 32760 |
|
| 32761 |
A number of bits are defined. For some of these, ranges are defined |
| 32762 |
and it is up to the definition of the storage protocol to specify how |
| 32763 |
these are to be used. There are ranges reserved for object-based |
| 32764 |
storage protocols and for other experimental storage protocols. An |
| 32765 |
RFC defining such a storage protocol needs to specify how particular |
| 32766 |
bits within its range are to be used. For example, it may specify a |
| 32767 |
mapping between attributes of the layout (read vs. write, size of |
| 32768 |
area) and the bit to be used, or it may define a field in the layout |
| 32769 |
where the associated bit position is made available by the server to |
| 32770 |
the client. |
| 32771 |
|
| 32772 |
RCA4_TYPE_MASK_RDATA_DLG |
| 32773 |
|
| 32774 |
The client is to return OPEN_DELEGATE_READ delegations on non- |
| 32775 |
directory file objects. |
| 32776 |
|
| 32777 |
RCA4_TYPE_MASK_WDATA_DLG |
| 32778 |
|
| 32779 |
The client is to return OPEN_DELEGATE_WRITE delegations on regular |
| 32780 |
file objects. |
| 32781 |
|
| 32782 |
RCA4_TYPE_MASK_DIR_DLG |
| 32783 |
|
| 32784 |
The client is to return directory delegations. |
| 32785 |
|
| 32786 |
RCA4_TYPE_MASK_FILE_LAYOUT |
| 32787 |
|
| 32788 |
The client is to return layouts of type LAYOUT4_NFSV4_1_FILES. |
| 32789 |
|
| 32790 |
RCA4_TYPE_MASK_BLK_LAYOUT |
| 32791 |
|
| 32792 |
See [<a href="#ref-41" title=""Parallel NFS (pNFS) Block/Volume Layout"">41</a>] for a description. |
| 32793 |
|
| 32794 |
RCA4_TYPE_MASK_OBJ_LAYOUT_MIN to RCA4_TYPE_MASK_OBJ_LAYOUT_MAX |
| 32795 |
|
| 32796 |
See [<a href="#ref-40" title=""Object-Based Parallel NFS (pNFS) Operations"">40</a>] for a description. |
| 32797 |
|
| 32798 |
RCA4_TYPE_MASK_OTHER_LAYOUT_MIN to RCA4_TYPE_MASK_OTHER_LAYOUT_MAX |
| 32799 |
|
| 32800 |
This range is reserved for telling the client to recall layouts of |
| 32801 |
experimental or site-specific layout types (see <a href="#section-3.3.13">Section 3.3.13</a>). |
| 32802 |
|
| 32803 |
When a bit is set in the type mask that corresponds to an undefined |
| 32804 |
type of recallable object, NFS4ERR_INVAL MUST be returned. When a |
| 32805 |
bit is set that corresponds to a defined type of object but the |
| 32806 |
client does not support an object of the type, NFS4ERR_INVAL MUST NOT |
| 32807 |
be returned. Future minor versions of NFSv4 may expand the set of |
| 32808 |
valid type mask bits. |
| 32809 |
|
| 32810 |
|
| 32811 |
|
| 32812 |
<span class="grey">Shepler, et al. Standards Track [Page 586]</span></pre> |
| 32813 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-587" ></span> |
| 32814 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32815 |
|
| 32816 |
|
| 32817 |
CB_RECALL_ANY specifies a count of objects that the client may keep |
| 32818 |
as opposed to a count that the client must return. This is to avoid |
| 32819 |
a potential race between a CB_RECALL_ANY that had a count of objects |
| 32820 |
to free with a set of client-originated operations to return layouts |
| 32821 |
or delegations. As a result of the race, the client and server would |
| 32822 |
have differing ideas as to how many objects to return. Hence, the |
| 32823 |
client could mistakenly free too many. |
| 32824 |
|
| 32825 |
If resource demands prompt it, the server may send another |
| 32826 |
CB_RECALL_ANY with a lower count, even if it has not yet received an |
| 32827 |
acknowledgment from the client for a previous CB_RECALL_ANY with the |
| 32828 |
same type mask. Although the possibility exists that these will be |
| 32829 |
received by the client in an order different from the order in which |
| 32830 |
they were sent, any such permutation of the callback stream is |
| 32831 |
harmless. It is the job of the client to bring down the size of the |
| 32832 |
recallable object set in line with each CB_RECALL_ANY received, and |
| 32833 |
until that obligation is met, it cannot be cancelled or modified by |
| 32834 |
any subsequent CB_RECALL_ANY for the same type mask. Thus, if the |
| 32835 |
server sends two CB_RECALL_ANYs, the effect will be the same as if |
| 32836 |
the lower count was sent, whatever the order of recall receipt. Note |
| 32837 |
that this means that a server may not cancel the effect of a |
| 32838 |
CB_RECALL_ANY by sending another recall with a higher count. When a |
| 32839 |
CB_RECALL_ANY is received and the count is already within the limit |
| 32840 |
set or is above a limit that the client is working to get down to, |
| 32841 |
that callback has no effect. |
| 32842 |
|
| 32843 |
Servers are generally free to deny recallable objects when |
| 32844 |
insufficient resources are available. Note that the effect of such a |
| 32845 |
policy is implicitly to give precedence to existing objects relative |
| 32846 |
to requested ones, with the result that resources might not be |
| 32847 |
optimally used. To prevent this, servers are well advised to make |
| 32848 |
the point at which they start sending CB_RECALL_ANY callbacks |
| 32849 |
somewhat below that at which they cease to give out new delegations |
| 32850 |
and layouts. This allows the client to purge its less-used objects |
| 32851 |
whenever appropriate and so continue to have its subsequent requests |
| 32852 |
given new resources freed up by object returns. |
| 32853 |
|
| 32854 |
<span class="h4"><a class="selflink" id="section-20.6.4" href="#section-20.6.4">20.6.4</a>. IMPLEMENTATION</span> |
| 32855 |
|
| 32856 |
The client can choose to return any type of object specified by the |
| 32857 |
mask. If a server wishes to limit the use of objects of a specific |
| 32858 |
type, it should only specify that type in the mask it sends. Should |
| 32859 |
the client fail to return requested objects, it is up to the server |
| 32860 |
to handle this situation, typically by sending specific recalls |
| 32861 |
(i.e., sending CB_RECALL operations) to properly limit resource |
| 32862 |
usage. The server should give the client enough time to return |
| 32863 |
objects before proceeding to specific recalls. This time should not |
| 32864 |
be less than the lease period. |
| 32865 |
|
| 32866 |
|
| 32867 |
|
| 32868 |
<span class="grey">Shepler, et al. Standards Track [Page 587]</span></pre> |
| 32869 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-588" ></span> |
| 32870 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32871 |
|
| 32872 |
|
| 32873 |
<span class="h3"><a class="selflink" id="section-20.7" href="#section-20.7">20.7</a>. Operation 9: CB_RECALLABLE_OBJ_AVAIL - Signal Resources for</span> |
| 32874 |
<span class="h3"> Recallable Objects</span> |
| 32875 |
|
| 32876 |
<span class="h4"><a class="selflink" id="section-20.7.1" href="#section-20.7.1">20.7.1</a>. ARGUMENT</span> |
| 32877 |
|
| 32878 |
typedef CB_RECALL_ANY4args CB_RECALLABLE_OBJ_AVAIL4args; |
| 32879 |
|
| 32880 |
|
| 32881 |
<span class="h4"><a class="selflink" id="section-20.7.2" href="#section-20.7.2">20.7.2</a>. RESULT</span> |
| 32882 |
|
| 32883 |
struct CB_RECALLABLE_OBJ_AVAIL4res { |
| 32884 |
nfsstat4 croa_status; |
| 32885 |
}; |
| 32886 |
|
| 32887 |
<span class="h4"><a class="selflink" id="section-20.7.3" href="#section-20.7.3">20.7.3</a>. DESCRIPTION</span> |
| 32888 |
|
| 32889 |
CB_RECALLABLE_OBJ_AVAIL is used by the server to signal the client |
| 32890 |
that the server has resources to grant recallable objects that might |
| 32891 |
previously have been denied by OPEN, WANT_DELEGATION, GET_DIR_DELEG, |
| 32892 |
or LAYOUTGET. |
| 32893 |
|
| 32894 |
The argument craa_objects_to_keep means the total number of |
| 32895 |
recallable objects of the types indicated in the argument type_mask |
| 32896 |
that the server believes it can allow the client to have, including |
| 32897 |
the number of such objects the client already has. A client that |
| 32898 |
tries to acquire more recallable objects than the server informs it |
| 32899 |
can have runs the risk of having objects recalled. |
| 32900 |
|
| 32901 |
The server is not obligated to reserve the difference between the |
| 32902 |
number of the objects the client currently has and the value of |
| 32903 |
craa_objects_to_keep, nor does delaying the reply to |
| 32904 |
CB_RECALLABLE_OBJ_AVAIL prevent the server from using the resources |
| 32905 |
of the recallable objects for another purpose. Indeed, if a client |
| 32906 |
responds slowly to CB_RECALLABLE_OBJ_AVAIL, the server might |
| 32907 |
interpret the client as having reduced capability to manage |
| 32908 |
recallable objects, and so cancel or reduce any reservation it is |
| 32909 |
maintaining on behalf of the client. Thus, if the client desires to |
| 32910 |
acquire more recallable objects, it needs to reply quickly to |
| 32911 |
CB_RECALLABLE_OBJ_AVAIL, and then send the appropriate operations to |
| 32912 |
acquire recallable objects. |
| 32913 |
|
| 32914 |
<span class="h3"><a class="selflink" id="section-20.8" href="#section-20.8">20.8</a>. Operation 10: CB_RECALL_SLOT - Change Flow Control Limits</span> |
| 32915 |
|
| 32916 |
<span class="h4"><a class="selflink" id="section-20.8.1" href="#section-20.8.1">20.8.1</a>. ARGUMENT</span> |
| 32917 |
|
| 32918 |
struct CB_RECALL_SLOT4args { |
| 32919 |
slotid4 rsa_target_highest_slotid; |
| 32920 |
}; |
| 32921 |
|
| 32922 |
|
| 32923 |
|
| 32924 |
<span class="grey">Shepler, et al. Standards Track [Page 588]</span></pre> |
| 32925 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-589" ></span> |
| 32926 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32927 |
|
| 32928 |
|
| 32929 |
<span class="h4"><a class="selflink" id="section-20.8.2" href="#section-20.8.2">20.8.2</a>. RESULT</span> |
| 32930 |
|
| 32931 |
struct CB_RECALL_SLOT4res { |
| 32932 |
nfsstat4 rsr_status; |
| 32933 |
}; |
| 32934 |
|
| 32935 |
<span class="h4"><a class="selflink" id="section-20.8.3" href="#section-20.8.3">20.8.3</a>. DESCRIPTION</span> |
| 32936 |
|
| 32937 |
The CB_RECALL_SLOT operation requests the client to return session |
| 32938 |
slots, and if applicable, transport credits (e.g., RDMA credits for |
| 32939 |
connections associated with the operations channel) of the session's |
| 32940 |
fore channel. CB_RECALL_SLOT specifies rsa_target_highest_slotid, |
| 32941 |
the value of the target highest slot ID the server wants for the |
| 32942 |
session. The client MUST then progress toward reducing the session's |
| 32943 |
highest slot ID to the target value. |
| 32944 |
|
| 32945 |
If the session has only non-RDMA connections associated with its |
| 32946 |
operations channel, then the client need only wait for all |
| 32947 |
outstanding requests with a slot ID > rsa_target_highest_slotid to |
| 32948 |
complete, then send a single COMPOUND consisting of a single SEQUENCE |
| 32949 |
operation, with the sa_highestslot field set to |
| 32950 |
rsa_target_highest_slotid. If there are RDMA-based connections |
| 32951 |
associated with operation channel, then the client needs to also send |
| 32952 |
enough zero-length "RDMA Send" messages to take the total RDMA credit |
| 32953 |
count to rsa_target_highest_slotid + 1 or below. |
| 32954 |
|
| 32955 |
<span class="h4"><a class="selflink" id="section-20.8.4" href="#section-20.8.4">20.8.4</a>. IMPLEMENTATION</span> |
| 32956 |
|
| 32957 |
If the client fails to reduce highest slot it has on the fore channel |
| 32958 |
to what the server requests, the server can force the issue by |
| 32959 |
asserting flow control on the receive side of all connections bound |
| 32960 |
to the fore channel, and then finish servicing all outstanding |
| 32961 |
requests that are in slots greater than rsa_target_highest_slotid. |
| 32962 |
Once that is done, the server can then open the flow control, and any |
| 32963 |
time the client sends a new request on a slot greater than |
| 32964 |
rsa_target_highest_slotid, the server can return NFS4ERR_BADSLOT. |
| 32965 |
|
| 32966 |
<span class="h3"><a class="selflink" id="section-20.9" href="#section-20.9">20.9</a>. Operation 11: CB_SEQUENCE - Supply Backchannel Sequencing and</span> |
| 32967 |
<span class="h3"> Control</span> |
| 32968 |
|
| 32969 |
<span class="h4"><a class="selflink" id="section-20.9.1" href="#section-20.9.1">20.9.1</a>. ARGUMENT</span> |
| 32970 |
|
| 32971 |
struct referring_call4 { |
| 32972 |
sequenceid4 rc_sequenceid; |
| 32973 |
slotid4 rc_slotid; |
| 32974 |
}; |
| 32975 |
|
| 32976 |
|
| 32977 |
|
| 32978 |
|
| 32979 |
|
| 32980 |
<span class="grey">Shepler, et al. Standards Track [Page 589]</span></pre> |
| 32981 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-590" ></span> |
| 32982 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 32983 |
|
| 32984 |
|
| 32985 |
struct referring_call_list4 { |
| 32986 |
sessionid4 rcl_sessionid; |
| 32987 |
referring_call4 rcl_referring_calls<>; |
| 32988 |
}; |
| 32989 |
|
| 32990 |
struct CB_SEQUENCE4args { |
| 32991 |
sessionid4 csa_sessionid; |
| 32992 |
sequenceid4 csa_sequenceid; |
| 32993 |
slotid4 csa_slotid; |
| 32994 |
slotid4 csa_highest_slotid; |
| 32995 |
bool csa_cachethis; |
| 32996 |
referring_call_list4 csa_referring_call_lists<>; |
| 32997 |
}; |
| 32998 |
|
| 32999 |
<span class="h4"><a class="selflink" id="section-20.9.2" href="#section-20.9.2">20.9.2</a>. RESULT</span> |
| 33000 |
|
| 33001 |
struct CB_SEQUENCE4resok { |
| 33002 |
sessionid4 csr_sessionid; |
| 33003 |
sequenceid4 csr_sequenceid; |
| 33004 |
slotid4 csr_slotid; |
| 33005 |
slotid4 csr_highest_slotid; |
| 33006 |
slotid4 csr_target_highest_slotid; |
| 33007 |
}; |
| 33008 |
|
| 33009 |
union CB_SEQUENCE4res switch (nfsstat4 csr_status) { |
| 33010 |
case NFS4_OK: |
| 33011 |
CB_SEQUENCE4resok csr_resok4; |
| 33012 |
default: |
| 33013 |
void; |
| 33014 |
}; |
| 33015 |
|
| 33016 |
<span class="h4"><a class="selflink" id="section-20.9.3" href="#section-20.9.3">20.9.3</a>. DESCRIPTION</span> |
| 33017 |
|
| 33018 |
The CB_SEQUENCE operation is used to manage operational accounting |
| 33019 |
for the backchannel of the session on which a request is sent. The |
| 33020 |
contents include the session ID to which this request belongs, the |
| 33021 |
slot ID and sequence ID used by the server to implement session |
| 33022 |
request control and exactly once semantics, and exchanged slot ID |
| 33023 |
maxima that are used to adjust the size of the reply cache. In each |
| 33024 |
CB_COMPOUND request, CB_SEQUENCE MUST appear once and MUST be the |
| 33025 |
first operation. The error NFS4ERR_SEQUENCE_POS MUST be returned |
| 33026 |
when CB_SEQUENCE is found in any position in a CB_COMPOUND beyond the |
| 33027 |
first. If any other operation is in the first position of |
| 33028 |
CB_COMPOUND, NFS4ERR_OP_NOT_IN_SESSION MUST be returned. |
| 33029 |
|
| 33030 |
See <a href="#section-18.46.3">Section 18.46.3</a> for a description of how slots are processed. |
| 33031 |
|
| 33032 |
|
| 33033 |
|
| 33034 |
|
| 33035 |
|
| 33036 |
<span class="grey">Shepler, et al. Standards Track [Page 590]</span></pre> |
| 33037 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-591" ></span> |
| 33038 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33039 |
|
| 33040 |
|
| 33041 |
If csa_cachethis is TRUE, then the server is requesting that the |
| 33042 |
client cache the reply in the callback reply cache. The client MUST |
| 33043 |
cache the reply (see <a href="#section-2.10.6.1.3">Section 2.10.6.1.3</a>). |
| 33044 |
|
| 33045 |
The csa_referring_call_lists array is the list of COMPOUND requests, |
| 33046 |
identified by session ID, slot ID, and sequence ID. These are |
| 33047 |
requests that the client previously sent to the server. These |
| 33048 |
previous requests created state that some operation(s) in the same |
| 33049 |
CB_COMPOUND as the csa_referring_call_lists are identifying. A |
| 33050 |
session ID is included because leased state is tied to a client ID, |
| 33051 |
and a client ID can have multiple sessions. See <a href="#section-2.10.6.3">Section 2.10.6.3</a>. |
| 33052 |
|
| 33053 |
The value of the csa_sequenceid argument relative to the cached |
| 33054 |
sequence ID on the slot falls into one of three cases. |
| 33055 |
|
| 33056 |
o If the difference between csa_sequenceid and the client's cached |
| 33057 |
sequence ID at the slot ID is two (2) or more, or if |
| 33058 |
csa_sequenceid is less than the cached sequence ID (accounting for |
| 33059 |
wraparound of the unsigned sequence ID value), then the client |
| 33060 |
MUST return NFS4ERR_SEQ_MISORDERED. |
| 33061 |
|
| 33062 |
o If csa_sequenceid and the cached sequence ID are the same, this is |
| 33063 |
a retry, and the client returns the CB_COMPOUND request's cached |
| 33064 |
reply. |
| 33065 |
|
| 33066 |
o If csa_sequenceid is one greater (accounting for wraparound) than |
| 33067 |
the cached sequence ID, then this is a new request, and the slot's |
| 33068 |
sequence ID is incremented. The operations subsequent to |
| 33069 |
CB_SEQUENCE, if any, are processed. If there are no other |
| 33070 |
operations, the only other effects are to cache the CB_SEQUENCE |
| 33071 |
reply in the slot, maintain the session's activity, and when the |
| 33072 |
server receives the CB_SEQUENCE reply, renew the lease of state |
| 33073 |
related to the client ID. |
| 33074 |
|
| 33075 |
If the server reuses a slot ID and sequence ID for a completely |
| 33076 |
different request, the client MAY treat the request as if it is a |
| 33077 |
retry of what it has already executed. The client MAY however detect |
| 33078 |
the server's illegal reuse and return NFS4ERR_SEQ_FALSE_RETRY. |
| 33079 |
|
| 33080 |
If CB_SEQUENCE returns an error, then the state of the slot (sequence |
| 33081 |
ID, cached reply) MUST NOT change. See <a href="#section-2.10.6.1.3">Section 2.10.6.1.3</a> for the |
| 33082 |
conditions when the error NFS4ERR_RETRY_UNCACHED_REP might be |
| 33083 |
returned. |
| 33084 |
|
| 33085 |
The client returns two "highest_slotid" values: csr_highest_slotid |
| 33086 |
and csr_target_highest_slotid. The former is the highest slot ID the |
| 33087 |
client will accept in a future CB_SEQUENCE operation, and SHOULD NOT |
| 33088 |
be less than the value of csa_highest_slotid (but see |
| 33089 |
|
| 33090 |
|
| 33091 |
|
| 33092 |
<span class="grey">Shepler, et al. Standards Track [Page 591]</span></pre> |
| 33093 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-592" ></span> |
| 33094 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33095 |
|
| 33096 |
|
| 33097 |
<a href="#section-2.10.6.1">Section 2.10.6.1</a> for an exception). The latter is the highest slot |
| 33098 |
ID the client would prefer the server use on a future CB_SEQUENCE |
| 33099 |
operation. |
| 33100 |
|
| 33101 |
<span class="h3"><a class="selflink" id="section-20.10" href="#section-20.10">20.10</a>. Operation 12: CB_WANTS_CANCELLED - Cancel Pending Delegation</span> |
| 33102 |
<span class="h3"> Wants</span> |
| 33103 |
|
| 33104 |
<span class="h4"><a class="selflink" id="section-20.10.1" href="#section-20.10.1">20.10.1</a>. ARGUMENT</span> |
| 33105 |
|
| 33106 |
struct CB_WANTS_CANCELLED4args { |
| 33107 |
bool cwca_contended_wants_cancelled; |
| 33108 |
bool cwca_resourced_wants_cancelled; |
| 33109 |
}; |
| 33110 |
|
| 33111 |
<span class="h4"><a class="selflink" id="section-20.10.2" href="#section-20.10.2">20.10.2</a>. RESULT</span> |
| 33112 |
|
| 33113 |
struct CB_WANTS_CANCELLED4res { |
| 33114 |
nfsstat4 cwcr_status; |
| 33115 |
}; |
| 33116 |
|
| 33117 |
<span class="h4"><a class="selflink" id="section-20.10.3" href="#section-20.10.3">20.10.3</a>. DESCRIPTION</span> |
| 33118 |
|
| 33119 |
The CB_WANTS_CANCELLED operation is used to notify the client that |
| 33120 |
some or all of the wants it registered for recallable delegations and |
| 33121 |
layouts have been cancelled. |
| 33122 |
|
| 33123 |
If cwca_contended_wants_cancelled is TRUE, this indicates that the |
| 33124 |
server will not be pushing to the client any delegations that become |
| 33125 |
available after contention passes. |
| 33126 |
|
| 33127 |
If cwca_resourced_wants_cancelled is TRUE, this indicates that the |
| 33128 |
server will not notify the client when there are resources on the |
| 33129 |
server to grant delegations or layouts. |
| 33130 |
|
| 33131 |
After receiving a CB_WANTS_CANCELLED operation, the client is free to |
| 33132 |
attempt to acquire the delegations or layouts it was waiting for, and |
| 33133 |
possibly re-register wants. |
| 33134 |
|
| 33135 |
<span class="h4"><a class="selflink" id="section-20.10.4" href="#section-20.10.4">20.10.4</a>. IMPLEMENTATION</span> |
| 33136 |
|
| 33137 |
When a client has an OPEN, WANT_DELEGATION, or GET_DIR_DELEGATION |
| 33138 |
request outstanding, when a CB_WANTS_CANCELLED is sent, the server |
| 33139 |
may need to make clear to the client whether a promise to signal |
| 33140 |
delegation availability happened before the CB_WANTS_CANCELLED and is |
| 33141 |
thus covered by it, or after the CB_WANTS_CANCELLED in which case it |
| 33142 |
was not covered by it. The server can make this distinction by |
| 33143 |
putting the appropriate requests into the list of referring calls in |
| 33144 |
the associated CB_SEQUENCE. |
| 33145 |
|
| 33146 |
|
| 33147 |
|
| 33148 |
<span class="grey">Shepler, et al. Standards Track [Page 592]</span></pre> |
| 33149 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-593" ></span> |
| 33150 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33151 |
|
| 33152 |
|
| 33153 |
<span class="h3"><a class="selflink" id="section-20.11" href="#section-20.11">20.11</a>. Operation 13: CB_NOTIFY_LOCK - Notify Client of Possible Lock</span> |
| 33154 |
<span class="h3"> Availability</span> |
| 33155 |
|
| 33156 |
<span class="h4"><a class="selflink" id="section-20.11.1" href="#section-20.11.1">20.11.1</a>. ARGUMENT</span> |
| 33157 |
|
| 33158 |
struct CB_NOTIFY_LOCK4args { |
| 33159 |
nfs_fh4 cnla_fh; |
| 33160 |
lock_owner4 cnla_lock_owner; |
| 33161 |
}; |
| 33162 |
|
| 33163 |
<span class="h4"><a class="selflink" id="section-20.11.2" href="#section-20.11.2">20.11.2</a>. RESULT</span> |
| 33164 |
|
| 33165 |
struct CB_NOTIFY_LOCK4res { |
| 33166 |
nfsstat4 cnlr_status; |
| 33167 |
}; |
| 33168 |
|
| 33169 |
<span class="h4"><a class="selflink" id="section-20.11.3" href="#section-20.11.3">20.11.3</a>. DESCRIPTION</span> |
| 33170 |
|
| 33171 |
The server can use this operation to indicate that a byte-range lock |
| 33172 |
for the given file and lock-owner, previously requested by the client |
| 33173 |
via an unsuccessful LOCK operation, might be available. |
| 33174 |
|
| 33175 |
This callback is meant to be used by servers to help reduce the |
| 33176 |
latency of blocking locks in the case where they recognize that a |
| 33177 |
client that has been polling for a blocking byte-range lock may now |
| 33178 |
be able to acquire the lock. If the server supports this callback |
| 33179 |
for a given file, it MUST set the OPEN4_RESULT_MAY_NOTIFY_LOCK flag |
| 33180 |
when responding to successful opens for that file. This does not |
| 33181 |
commit the server to the use of CB_NOTIFY_LOCK, but the client may |
| 33182 |
use this as a hint to decide how frequently to poll for locks derived |
| 33183 |
from that open. |
| 33184 |
|
| 33185 |
If an OPEN operation results in an upgrade, in which the stateid |
| 33186 |
returned has an "other" value matching that of a stateid already |
| 33187 |
allocated, with a new "seqid" indicating a change in the lock being |
| 33188 |
represented, then the value of the OPEN4_RESULT_MAY_NOTIFY_LOCK flag |
| 33189 |
when responding to that new OPEN controls handling from that point |
| 33190 |
going forward. When parallel OPENs are done on the same file and |
| 33191 |
open-owner, the ordering of the "seqid" fields of the returned |
| 33192 |
stateids (subject to wraparound) are to be used to select the |
| 33193 |
controlling value of the OPEN4_RESULT_MAY_NOTIFY_LOCK flag. |
| 33194 |
|
| 33195 |
|
| 33196 |
|
| 33197 |
|
| 33198 |
|
| 33199 |
|
| 33200 |
|
| 33201 |
|
| 33202 |
|
| 33203 |
|
| 33204 |
<span class="grey">Shepler, et al. Standards Track [Page 593]</span></pre> |
| 33205 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-594" ></span> |
| 33206 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33207 |
|
| 33208 |
|
| 33209 |
<span class="h4"><a class="selflink" id="section-20.11.4" href="#section-20.11.4">20.11.4</a>. IMPLEMENTATION</span> |
| 33210 |
|
| 33211 |
The server MUST NOT grant the byte-range lock to the client unless |
| 33212 |
and until it receives a LOCK operation from the client. Similarly, |
| 33213 |
the client receiving this callback cannot assume that it now has the |
| 33214 |
lock or that a subsequent LOCK operation for the lock will be |
| 33215 |
successful. |
| 33216 |
|
| 33217 |
The server is not required to implement this callback, and even if it |
| 33218 |
does, it is not required to use it in any particular case. |
| 33219 |
Therefore, the client must still rely on polling for blocking locks, |
| 33220 |
as described in <a href="#section-9.6">Section 9.6</a>. |
| 33221 |
|
| 33222 |
Similarly, the client is not required to implement this callback, and |
| 33223 |
even it does, is still free to ignore it. Therefore, the server MUST |
| 33224 |
NOT assume that the client will act based on the callback. |
| 33225 |
|
| 33226 |
<span class="h3"><a class="selflink" id="section-20.12" href="#section-20.12">20.12</a>. Operation 14: CB_NOTIFY_DEVICEID - Notify Client of Device ID</span> |
| 33227 |
<span class="h3"> Changes</span> |
| 33228 |
|
| 33229 |
<span class="h4"><a class="selflink" id="section-20.12.1" href="#section-20.12.1">20.12.1</a>. ARGUMENT</span> |
| 33230 |
|
| 33231 |
/* |
| 33232 |
* Device notification types. |
| 33233 |
*/ |
| 33234 |
enum notify_deviceid_type4 { |
| 33235 |
NOTIFY_DEVICEID4_CHANGE = 1, |
| 33236 |
NOTIFY_DEVICEID4_DELETE = 2 |
| 33237 |
}; |
| 33238 |
|
| 33239 |
/* For NOTIFY4_DEVICEID4_DELETE */ |
| 33240 |
struct notify_deviceid_delete4 { |
| 33241 |
layouttype4 ndd_layouttype; |
| 33242 |
deviceid4 ndd_deviceid; |
| 33243 |
}; |
| 33244 |
|
| 33245 |
/* For NOTIFY4_DEVICEID4_CHANGE */ |
| 33246 |
struct notify_deviceid_change4 { |
| 33247 |
layouttype4 ndc_layouttype; |
| 33248 |
deviceid4 ndc_deviceid; |
| 33249 |
bool ndc_immediate; |
| 33250 |
}; |
| 33251 |
|
| 33252 |
struct CB_NOTIFY_DEVICEID4args { |
| 33253 |
notify4 cnda_changes<>; |
| 33254 |
}; |
| 33255 |
|
| 33256 |
|
| 33257 |
|
| 33258 |
|
| 33259 |
|
| 33260 |
<span class="grey">Shepler, et al. Standards Track [Page 594]</span></pre> |
| 33261 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-595" ></span> |
| 33262 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33263 |
|
| 33264 |
|
| 33265 |
<span class="h4"><a class="selflink" id="section-20.12.2" href="#section-20.12.2">20.12.2</a>. RESULT</span> |
| 33266 |
|
| 33267 |
struct CB_NOTIFY_DEVICEID4res { |
| 33268 |
nfsstat4 cndr_status; |
| 33269 |
}; |
| 33270 |
|
| 33271 |
<span class="h4"><a class="selflink" id="section-20.12.3" href="#section-20.12.3">20.12.3</a>. DESCRIPTION</span> |
| 33272 |
|
| 33273 |
The CB_NOTIFY_DEVICEID operation is used by the server to send |
| 33274 |
notifications to clients about changes to pNFS device IDs. The |
| 33275 |
registration of device ID notifications is optional and is done via |
| 33276 |
GETDEVICEINFO. These notifications are sent over the backchannel |
| 33277 |
once the original request has been processed on the server. The |
| 33278 |
server will send an array of notifications, cnda_changes, as a list |
| 33279 |
of pairs of bitmaps and values. See <a href="#section-3.3.7">Section 3.3.7</a> for a description |
| 33280 |
of how NFSv4.1 bitmaps work. |
| 33281 |
|
| 33282 |
As with CB_NOTIFY (<a href="#section-20.4.3">Section 20.4.3</a>), it is possible the server has |
| 33283 |
more notifications than can fit in a CB_COMPOUND, thus requiring |
| 33284 |
multiple CB_COMPOUNDs. Unlike CB_NOTIFY, serialization is not an |
| 33285 |
issue because unlike directory entries, device IDs cannot be re-used |
| 33286 |
after being deleted (<a href="#section-12.2.10">Section 12.2.10</a>). |
| 33287 |
|
| 33288 |
All device ID notifications contain a device ID and a layout type. |
| 33289 |
The layout type is necessary because two different layout types can |
| 33290 |
share the same device ID, and the common device ID can have |
| 33291 |
completely different mappings for each layout type. |
| 33292 |
|
| 33293 |
The server will send the following notifications: |
| 33294 |
|
| 33295 |
NOTIFY_DEVICEID4_CHANGE |
| 33296 |
A previously provided device-ID-to-device-address mapping has |
| 33297 |
changed and the client uses GETDEVICEINFO to obtain the updated |
| 33298 |
mapping. The notification is encoded in a value of data type |
| 33299 |
notify_deviceid_change4. This data type also contains a boolean |
| 33300 |
field, ndc_immediate, which if TRUE indicates that the change will |
| 33301 |
be enforced immediately, and so the client might not be able to |
| 33302 |
complete any pending I/O to the device ID. If ndc_immediate is |
| 33303 |
FALSE, then for an indefinite time, the client can complete |
| 33304 |
pending I/O. After pending I/O is complete, the client SHOULD get |
| 33305 |
the new device-ID-to-device-address mappings before sending new |
| 33306 |
I/O requests to the storage devices addressed by the device ID. |
| 33307 |
|
| 33308 |
|
| 33309 |
|
| 33310 |
|
| 33311 |
|
| 33312 |
|
| 33313 |
|
| 33314 |
|
| 33315 |
|
| 33316 |
<span class="grey">Shepler, et al. Standards Track [Page 595]</span></pre> |
| 33317 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-596" ></span> |
| 33318 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33319 |
|
| 33320 |
|
| 33321 |
NOTIFY4_DEVICEID_DELETE |
| 33322 |
Deletes a device ID from the mappings. This notification MUST NOT |
| 33323 |
be sent if the client has a layout that refers to the device ID. |
| 33324 |
In other words, if the server is sending a delete device ID |
| 33325 |
notification, one of the following is true for layouts associated |
| 33326 |
with the layout type: |
| 33327 |
|
| 33328 |
* The client never had a layout referring to that device ID. |
| 33329 |
|
| 33330 |
* The client has returned all layouts referring to that device |
| 33331 |
ID. |
| 33332 |
|
| 33333 |
* The server has revoked all layouts referring to that device ID. |
| 33334 |
|
| 33335 |
The notification is encoded in a value of data type |
| 33336 |
notify_deviceid_delete4. After a server deletes a device ID, it |
| 33337 |
MUST NOT reuse that device ID for the same layout type until the |
| 33338 |
client ID is deleted. |
| 33339 |
|
| 33340 |
<span class="h3"><a class="selflink" id="section-20.13" href="#section-20.13">20.13</a>. Operation 10044: CB_ILLEGAL - Illegal Callback Operation</span> |
| 33341 |
|
| 33342 |
<span class="h4"><a class="selflink" id="section-20.13.1" href="#section-20.13.1">20.13.1</a>. ARGUMENT</span> |
| 33343 |
|
| 33344 |
void; |
| 33345 |
|
| 33346 |
<span class="h4"><a class="selflink" id="section-20.13.2" href="#section-20.13.2">20.13.2</a>. RESULT</span> |
| 33347 |
|
| 33348 |
/* |
| 33349 |
* CB_ILLEGAL: Response for illegal operation numbers |
| 33350 |
*/ |
| 33351 |
struct CB_ILLEGAL4res { |
| 33352 |
nfsstat4 status; |
| 33353 |
}; |
| 33354 |
|
| 33355 |
<span class="h4"><a class="selflink" id="section-20.13.3" href="#section-20.13.3">20.13.3</a>. DESCRIPTION</span> |
| 33356 |
|
| 33357 |
This operation is a placeholder for encoding a result to handle the |
| 33358 |
case of the server sending an operation code within CB_COMPOUND that |
| 33359 |
is not defined in the NFSv4.1 specification. See <a href="#section-19.2.3">Section 19.2.3</a> for |
| 33360 |
more details. |
| 33361 |
|
| 33362 |
The status field of CB_ILLEGAL4res MUST be set to NFS4ERR_OP_ILLEGAL. |
| 33363 |
|
| 33364 |
<span class="h4"><a class="selflink" id="section-20.13.4" href="#section-20.13.4">20.13.4</a>. IMPLEMENTATION</span> |
| 33365 |
|
| 33366 |
A server will probably not send an operation with code OP_CB_ILLEGAL, |
| 33367 |
but if it does, the response will be CB_ILLEGAL4res just as it would |
| 33368 |
be with any other invalid operation code. Note that if the client |
| 33369 |
|
| 33370 |
|
| 33371 |
|
| 33372 |
<span class="grey">Shepler, et al. Standards Track [Page 596]</span></pre> |
| 33373 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-597" ></span> |
| 33374 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33375 |
|
| 33376 |
|
| 33377 |
gets an illegal operation code that is not OP_ILLEGAL, and if the |
| 33378 |
client checks for legal operation codes during the XDR decode phase, |
| 33379 |
then an instance of data type CB_ILLEGAL4res will not be returned. |
| 33380 |
|
| 33381 |
<span class="h2"><a class="selflink" id="section-21" href="#section-21">21</a>. Security Considerations</span> |
| 33382 |
|
| 33383 |
Historically, the authentication model of NFS was based on the entire |
| 33384 |
machine being the NFS client, with the NFS server trusting the NFS |
| 33385 |
client to authenticate the end-user. The NFS server in turn shared |
| 33386 |
its files only to specific clients, as identified by the client's |
| 33387 |
source network address. Given this model, the AUTH_SYS RPC security |
| 33388 |
flavor simply identified the end-user using the client to the NFS |
| 33389 |
server. When processing NFS responses, the client ensured that the |
| 33390 |
responses came from the same network address and port number to which |
| 33391 |
the request was sent. While such a model is easy to implement and |
| 33392 |
simple to deploy and use, it is unsafe. Thus, NFSv4.1 |
| 33393 |
implementations are REQUIRED to support a security model that uses |
| 33394 |
end-to-end authentication, where an end-user on a client mutually |
| 33395 |
authenticates (via cryptographic schemes that do not expose passwords |
| 33396 |
or keys in the clear on the network) to a principal on an NFS server. |
| 33397 |
Consideration is also given to the integrity and privacy of NFS |
| 33398 |
requests and responses. The issues of end-to-end mutual |
| 33399 |
authentication, integrity, and privacy are discussed in |
| 33400 |
<a href="#section-2.2.1.1.1">Section 2.2.1.1.1</a>. There are specific considerations when using |
| 33401 |
Kerberos V5 as described in <a href="#section-2.2.1.1.1.2.1.1">Section 2.2.1.1.1.2.1.1</a>. |
| 33402 |
|
| 33403 |
Note that being REQUIRED to implement does not mean REQUIRED to use; |
| 33404 |
AUTH_SYS can be used by NFSv4.1 clients and servers. However, |
| 33405 |
AUTH_SYS is merely an OPTIONAL security flavor in NFSv4.1, and so |
| 33406 |
interoperability via AUTH_SYS is not assured. |
| 33407 |
|
| 33408 |
For reasons of reduced administration overhead, better performance, |
| 33409 |
and/or reduction of CPU utilization, users of NFSv4.1 implementations |
| 33410 |
might decline to use security mechanisms that enable integrity |
| 33411 |
protection on each remote procedure call and response. The use of |
| 33412 |
mechanisms without integrity leaves the user vulnerable to a man-in- |
| 33413 |
the-middle of the NFS client and server that modifies the RPC request |
| 33414 |
and/or the response. While implementations are free to provide the |
| 33415 |
option to use weaker security mechanisms, there are three operations |
| 33416 |
in particular that warrant the implementation overriding user |
| 33417 |
choices. |
| 33418 |
|
| 33419 |
o The first two such operations are SECINFO and SECINFO_NO_NAME. It |
| 33420 |
is RECOMMENDED that the client send both operations such that they |
| 33421 |
are protected with a security flavor that has integrity |
| 33422 |
protection, such as RPCSEC_GSS with either the |
| 33423 |
rpc_gss_svc_integrity or rpc_gss_svc_privacy service. Without |
| 33424 |
integrity protection encapsulating SECINFO and SECINFO_NO_NAME and |
| 33425 |
|
| 33426 |
|
| 33427 |
|
| 33428 |
<span class="grey">Shepler, et al. Standards Track [Page 597]</span></pre> |
| 33429 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-598" ></span> |
| 33430 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33431 |
|
| 33432 |
|
| 33433 |
their results, a man-in-the-middle could modify results such that |
| 33434 |
the client might select a weaker algorithm in the set allowed by |
| 33435 |
the server, making the client and/or server vulnerable to further |
| 33436 |
attacks. |
| 33437 |
|
| 33438 |
o The third operation that SHOULD use integrity protection is any |
| 33439 |
GETATTR for the fs_locations and fs_locations_info attributes, in |
| 33440 |
order to mitigate the severity of a man-in-the-middle attack. The |
| 33441 |
attack has two steps. First the attacker modifies the unprotected |
| 33442 |
results of some operation to return NFS4ERR_MOVED. Second, when |
| 33443 |
the client follows up with a GETATTR for the fs_locations or |
| 33444 |
fs_locations_info attributes, the attacker modifies the results to |
| 33445 |
cause the client to migrate its traffic to a server controlled by |
| 33446 |
the attacker. With integrity protection, this attack is |
| 33447 |
mitigated. |
| 33448 |
|
| 33449 |
Relative to previous NFS versions, NFSv4.1 has additional security |
| 33450 |
considerations for pNFS (see Sections <a href="#section-12.9">12.9</a> and <a href="#section-13.12">13.12</a>), locking and |
| 33451 |
session state (see <a href="#section-2.10.8.3">Section 2.10.8.3</a>), and state recovery during grace |
| 33452 |
period (see <a href="#section-8.4.2.1.1">Section 8.4.2.1.1</a>). With respect to locking and session |
| 33453 |
state, if SP4_SSV state protection is being used, <a href="#section-2.10.10">Section 2.10.10</a> has |
| 33454 |
specific security considerations for the NFSv4.1 client and server. |
| 33455 |
|
| 33456 |
<span class="h2"><a class="selflink" id="section-22" href="#section-22">22</a>. IANA Considerations</span> |
| 33457 |
|
| 33458 |
This section uses terms that are defined in [<a href="#ref-55" title="">55</a>]. |
| 33459 |
|
| 33460 |
<span class="h3"><a class="selflink" id="section-22.1" href="#section-22.1">22.1</a>. Named Attribute Definitions</span> |
| 33461 |
|
| 33462 |
IANA created a registry called the "NFSv4 Named Attribute Definitions |
| 33463 |
Registry". |
| 33464 |
|
| 33465 |
The NFSv4.1 protocol supports the association of a file with zero or |
| 33466 |
more named attributes. The namespace identifiers for these |
| 33467 |
attributes are defined as string names. The protocol does not define |
| 33468 |
the specific assignment of the namespace for these file attributes. |
| 33469 |
The IANA registry promotes interoperability where common interests |
| 33470 |
exist. While application developers are allowed to define and use |
| 33471 |
attributes as needed, they are encouraged to register the attributes |
| 33472 |
with IANA. |
| 33473 |
|
| 33474 |
Such registered named attributes are presumed to apply to all minor |
| 33475 |
versions of NFSv4, including those defined subsequently to the |
| 33476 |
registration. If the named attribute is intended to be limited to |
| 33477 |
specific minor versions, this will be clearly stated in the |
| 33478 |
registry's assignment. |
| 33479 |
|
| 33480 |
|
| 33481 |
|
| 33482 |
|
| 33483 |
|
| 33484 |
<span class="grey">Shepler, et al. Standards Track [Page 598]</span></pre> |
| 33485 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-599" ></span> |
| 33486 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33487 |
|
| 33488 |
|
| 33489 |
All assignments to the registry are made on a First Come First Served |
| 33490 |
basis, per Section 4.1 of [<a href="#ref-55" title="">55</a>]. The policy for each assignment is |
| 33491 |
Specification Required, per Section 4.1 of [<a href="#ref-55" title="">55</a>]. |
| 33492 |
|
| 33493 |
Under the NFSv4.1 specification, the name of a named attribute can in |
| 33494 |
theory be up to 2^32 - 1 bytes in length, but in practice NFSv4.1 |
| 33495 |
clients and servers will be unable to handle a string that long. |
| 33496 |
IANA should reject any assignment request with a named attribute that |
| 33497 |
exceeds 128 UTF-8 characters. To give the IESG the flexibility to |
| 33498 |
set up bases of assignment of Experimental Use and Standards Action, |
| 33499 |
the prefixes of "EXPE" and "STDS" are Reserved. The named attribute |
| 33500 |
with a zero-length name is Reserved. |
| 33501 |
|
| 33502 |
The prefix "PRIV" is designated for Private Use. A site that wants |
| 33503 |
to make use of unregistered named attributes without risk of |
| 33504 |
conflicting with an assignment in IANA's registry should use the |
| 33505 |
prefix "PRIV" in all of its named attributes. |
| 33506 |
|
| 33507 |
Because some NFSv4.1 clients and servers have case-insensitive |
| 33508 |
semantics, the fifteen additional lower case and mixed case |
| 33509 |
permutations of each of "EXPE", "PRIV", and "STDS" are Reserved |
| 33510 |
(e.g., "expe", "expE", "exPe", etc. are Reserved). Similarly, IANA |
| 33511 |
must not allow two assignments that would conflict if both named |
| 33512 |
attributes were converted to a common case. |
| 33513 |
|
| 33514 |
The registry of named attributes is a list of assignments, each |
| 33515 |
containing three fields for each assignment. |
| 33516 |
|
| 33517 |
1. A US-ASCII string name that is the actual name of the attribute. |
| 33518 |
This name must be unique. This string name can be 1 to 128 UTF-8 |
| 33519 |
characters long. |
| 33520 |
|
| 33521 |
2. A reference to the specification of the named attribute. The |
| 33522 |
reference can consume up to 256 bytes (or more if IANA permits). |
| 33523 |
|
| 33524 |
3. The point of contact of the registrant. The point of contact can |
| 33525 |
consume up to 256 bytes (or more if IANA permits). |
| 33526 |
|
| 33527 |
<span class="h4"><a class="selflink" id="section-22.1.1" href="#section-22.1.1">22.1.1</a>. Initial Registry</span> |
| 33528 |
|
| 33529 |
There is no initial registry. |
| 33530 |
|
| 33531 |
<span class="h4"><a class="selflink" id="section-22.1.2" href="#section-22.1.2">22.1.2</a>. Updating Registrations</span> |
| 33532 |
|
| 33533 |
The registrant is always permitted to update the point of contact |
| 33534 |
field. Any other change will require Expert Review or IESG Approval. |
| 33535 |
|
| 33536 |
|
| 33537 |
|
| 33538 |
|
| 33539 |
|
| 33540 |
<span class="grey">Shepler, et al. Standards Track [Page 599]</span></pre> |
| 33541 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-600" ></span> |
| 33542 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33543 |
|
| 33544 |
|
| 33545 |
<span class="h3"><a class="selflink" id="section-22.2" href="#section-22.2">22.2</a>. Device ID Notifications</span> |
| 33546 |
|
| 33547 |
IANA created a registry called the "NFSv4 Device ID Notifications |
| 33548 |
Registry". |
| 33549 |
|
| 33550 |
The potential exists for new notification types to be added to the |
| 33551 |
CB_NOTIFY_DEVICEID operation (see <a href="#section-20.12">Section 20.12</a>). This can be done |
| 33552 |
via changes to the operations that register notifications, or by |
| 33553 |
adding new operations to NFSv4. This requires a new minor version of |
| 33554 |
NFSv4, and requires a Standards Track document from the IETF. |
| 33555 |
Another way to add a notification is to specify a new layout type |
| 33556 |
(see <a href="#section-22.4">Section 22.4</a>). |
| 33557 |
|
| 33558 |
Hence, all assignments to the registry are made on a Standards Action |
| 33559 |
basis per Section 4.1 of [<a href="#ref-55" title="">55</a>], with Expert Review required. |
| 33560 |
|
| 33561 |
The registry is a list of assignments, each containing five fields |
| 33562 |
per assignment. |
| 33563 |
|
| 33564 |
1. The name of the notification type. This name must have the |
| 33565 |
prefix "NOTIFY_DEVICEID4_". This name must be unique. |
| 33566 |
|
| 33567 |
2. The value of the notification. IANA will assign this number, and |
| 33568 |
the request from the registrant will use TBD1 instead of an |
| 33569 |
actual value. IANA MUST use a whole number that can be no higher |
| 33570 |
than 2^32-1, and should be the next available value. The value |
| 33571 |
assigned must be unique. A Designated Expert must be used to |
| 33572 |
ensure that when the name of the notification type and its value |
| 33573 |
are added to the NFSv4.1 notify_deviceid_type4 enumerated data |
| 33574 |
type in the NFSv4.1 XDR description ([<a href="#ref-13" title=""Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description"">13</a>]), the result continues |
| 33575 |
to be a valid XDR description. |
| 33576 |
|
| 33577 |
3. The Standards Track RFC(s) that describe the notification. If |
| 33578 |
the RFC(s) have not yet been published, the registrant will use |
| 33579 |
RFCTBD2, RFCTBD3, etc. instead of an actual RFC number. |
| 33580 |
|
| 33581 |
4. How the RFC introduces the notification. This is indicated by a |
| 33582 |
single US-ASCII value. If the value is N, it means a minor |
| 33583 |
revision to the NFSv4 protocol. If the value is L, it means a |
| 33584 |
new pNFS layout type. Other values can be used with IESG |
| 33585 |
Approval. |
| 33586 |
|
| 33587 |
5. The minor versions of NFSv4 that are allowed to use the |
| 33588 |
notification. While these are numeric values, IANA will not |
| 33589 |
allocate and assign them; the author of the relevant RFCs with |
| 33590 |
IESG Approval assigns these numbers. Each time there is a new |
| 33591 |
minor version of NFSv4 approved, a Designated Expert should |
| 33592 |
review the registry to make recommended updates as needed. |
| 33593 |
|
| 33594 |
|
| 33595 |
|
| 33596 |
<span class="grey">Shepler, et al. Standards Track [Page 600]</span></pre> |
| 33597 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-601" ></span> |
| 33598 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33599 |
|
| 33600 |
|
| 33601 |
<span class="h4"><a class="selflink" id="section-22.2.1" href="#section-22.2.1">22.2.1</a>. Initial Registry</span> |
| 33602 |
|
| 33603 |
The initial registry is in Table 16. Note that the next available |
| 33604 |
value is zero. |
| 33605 |
|
| 33606 |
+-------------------------+-------+---------+-----+----------------+ |
| 33607 |
| Notification Name | Value | RFC | How | Minor Versions | |
| 33608 |
+-------------------------+-------+---------+-----+----------------+ |
| 33609 |
| NOTIFY_DEVICEID4_CHANGE | 1 | <a href="./rfc5661">RFC5661</a> | N | 1 | |
| 33610 |
| NOTIFY_DEVICEID4_DELETE | 2 | <a href="./rfc5661">RFC5661</a> | N | 1 | |
| 33611 |
+-------------------------+-------+---------+-----+----------------+ |
| 33612 |
|
| 33613 |
Table 16: Initial Device ID Notification Assignments |
| 33614 |
|
| 33615 |
<span class="h4"><a class="selflink" id="section-22.2.2" href="#section-22.2.2">22.2.2</a>. Updating Registrations</span> |
| 33616 |
|
| 33617 |
The update of a registration will require IESG Approval on the advice |
| 33618 |
of a Designated Expert. |
| 33619 |
|
| 33620 |
<span class="h3"><a class="selflink" id="section-22.3" href="#section-22.3">22.3</a>. Object Recall Types</span> |
| 33621 |
|
| 33622 |
IANA created a registry called the "NFSv4 Recallable Object Types |
| 33623 |
Registry". |
| 33624 |
|
| 33625 |
The potential exists for new object types to be added to the |
| 33626 |
CB_RECALL_ANY operation (see <a href="#section-20.6">Section 20.6</a>). This can be done via |
| 33627 |
changes to the operations that add recallable types, or by adding new |
| 33628 |
operations to NFSv4. This requires a new minor version of NFSv4, and |
| 33629 |
requires a Standards Track document from IETF. Another way to add a |
| 33630 |
new recallable object is to specify a new layout type (see |
| 33631 |
<a href="#section-22.4">Section 22.4</a>). |
| 33632 |
|
| 33633 |
All assignments to the registry are made on a Standards Action basis |
| 33634 |
per Section 4.1 of [<a href="#ref-55" title="">55</a>], with Expert Review required. |
| 33635 |
|
| 33636 |
Recallable object types are 32-bit unsigned numbers. There are no |
| 33637 |
Reserved values. Values in the range 12 through 15, inclusive, are |
| 33638 |
designated for Private Use. |
| 33639 |
|
| 33640 |
The registry is a list of assignments, each containing five fields |
| 33641 |
per assignment. |
| 33642 |
|
| 33643 |
1. The name of the recallable object type. This name must have the |
| 33644 |
prefix "RCA4_TYPE_MASK_". The name must be unique. |
| 33645 |
|
| 33646 |
2. The value of the recallable object type. IANA will assign this |
| 33647 |
number, and the request from the registrant will use TBD1 instead |
| 33648 |
of an actual value. IANA MUST use a whole number that can be no |
| 33649 |
|
| 33650 |
|
| 33651 |
|
| 33652 |
<span class="grey">Shepler, et al. Standards Track [Page 601]</span></pre> |
| 33653 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-602" ></span> |
| 33654 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33655 |
|
| 33656 |
|
| 33657 |
higher than 2^32-1, and should be the next available value. The |
| 33658 |
value must be unique. A Designated Expert must be used to ensure |
| 33659 |
that when the name of the recallable type and its value are added |
| 33660 |
to the NFSv4 XDR description [<a href="#ref-13" title=""Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description"">13</a>], the result continues to be a |
| 33661 |
valid XDR description. |
| 33662 |
|
| 33663 |
3. The Standards Track RFC(s) that describe the recallable object |
| 33664 |
type. If the RFC(s) have not yet been published, the registrant |
| 33665 |
will use RFCTBD2, RFCTBD3, etc. instead of an actual RFC number. |
| 33666 |
|
| 33667 |
4. How the RFC introduces the recallable object type. This is |
| 33668 |
indicated by a single US-ASCII value. If the value is N, it |
| 33669 |
means a minor revision to the NFSv4 protocol. If the value is L, |
| 33670 |
it means a new pNFS layout type. Other values can be used with |
| 33671 |
IESG Approval. |
| 33672 |
|
| 33673 |
5. The minor versions of NFSv4 that are allowed to use the |
| 33674 |
recallable object type. While these are numeric values, IANA |
| 33675 |
will not allocate and assign them; the author of the relevant |
| 33676 |
RFCs with IESG Approval assigns these numbers. Each time there |
| 33677 |
is a new minor version of NFSv4 approved, a Designated Expert |
| 33678 |
should review the registry to make recommended updates as needed. |
| 33679 |
|
| 33680 |
|
| 33681 |
|
| 33682 |
|
| 33683 |
|
| 33684 |
|
| 33685 |
|
| 33686 |
|
| 33687 |
|
| 33688 |
|
| 33689 |
|
| 33690 |
|
| 33691 |
|
| 33692 |
|
| 33693 |
|
| 33694 |
|
| 33695 |
|
| 33696 |
|
| 33697 |
|
| 33698 |
|
| 33699 |
|
| 33700 |
|
| 33701 |
|
| 33702 |
|
| 33703 |
|
| 33704 |
|
| 33705 |
|
| 33706 |
|
| 33707 |
|
| 33708 |
<span class="grey">Shepler, et al. Standards Track [Page 602]</span></pre> |
| 33709 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-603" ></span> |
| 33710 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33711 |
|
| 33712 |
|
| 33713 |
<span class="h4"><a class="selflink" id="section-22.3.1" href="#section-22.3.1">22.3.1</a>. Initial Registry</span> |
| 33714 |
|
| 33715 |
The initial registry is in Table 17. Note that the next available |
| 33716 |
value is five. |
| 33717 |
|
| 33718 |
+-------------------------------+-------+--------+-----+------------+ |
| 33719 |
| Recallable Object Type Name | Value | RFC | How | Minor | |
| 33720 |
| | | | | Versions | |
| 33721 |
+-------------------------------+-------+--------+-----+------------+ |
| 33722 |
| RCA4_TYPE_MASK_RDATA_DLG | 0 | RFC | N | 1 | |
| 33723 |
| | | 5661 | | | |
| 33724 |
| RCA4_TYPE_MASK_WDATA_DLG | 1 | RFC | N | 1 | |
| 33725 |
| | | 5661 | | | |
| 33726 |
| RCA4_TYPE_MASK_DIR_DLG | 2 | RFC | N | 1 | |
| 33727 |
| | | 5661 | | | |
| 33728 |
| RCA4_TYPE_MASK_FILE_LAYOUT | 3 | RFC | N | 1 | |
| 33729 |
| | | 5661 | | | |
| 33730 |
| RCA4_TYPE_MASK_BLK_LAYOUT | 4 | RFC | L | 1 | |
| 33731 |
| | | 5661 | | | |
| 33732 |
| RCA4_TYPE_MASK_OBJ_LAYOUT_MIN | 8 | RFC | L | 1 | |
| 33733 |
| | | 5661 | | | |
| 33734 |
| RCA4_TYPE_MASK_OBJ_LAYOUT_MAX | 9 | RFC | L | 1 | |
| 33735 |
| | | 5661 | | | |
| 33736 |
+-------------------------------+-------+--------+-----+------------+ |
| 33737 |
|
| 33738 |
Table 17: Initial Recallable Object Type Assignments |
| 33739 |
|
| 33740 |
<span class="h4"><a class="selflink" id="section-22.3.2" href="#section-22.3.2">22.3.2</a>. Updating Registrations</span> |
| 33741 |
|
| 33742 |
The update of a registration will require IESG Approval on the advice |
| 33743 |
of a Designated Expert. |
| 33744 |
|
| 33745 |
<span class="h3"><a class="selflink" id="section-22.4" href="#section-22.4">22.4</a>. Layout Types</span> |
| 33746 |
|
| 33747 |
IANA created a registry called the "pNFS Layout Types Registry". |
| 33748 |
|
| 33749 |
All assignments to the registry are made on a Standards Action basis, |
| 33750 |
with Expert Review required. |
| 33751 |
|
| 33752 |
Layout types are 32-bit numbers. The value zero is Reserved. Values |
| 33753 |
in the range 0x80000000 to 0xFFFFFFFF inclusive are designated for |
| 33754 |
Private Use. IANA will assign numbers from the range 0x00000001 to |
| 33755 |
0x7FFFFFFF inclusive. |
| 33756 |
|
| 33757 |
The registry is a list of assignments, each containing five fields. |
| 33758 |
|
| 33759 |
1. The name of the layout type. This name must have the prefix |
| 33760 |
"LAYOUT4_". The name must be unique. |
| 33761 |
|
| 33762 |
|
| 33763 |
|
| 33764 |
<span class="grey">Shepler, et al. Standards Track [Page 603]</span></pre> |
| 33765 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-604" ></span> |
| 33766 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33767 |
|
| 33768 |
|
| 33769 |
2. The value of the layout type. IANA will assign this number, and |
| 33770 |
the request from the registrant will use TBD1 instead of an |
| 33771 |
actual value. The value assigned must be unique. A Designated |
| 33772 |
Expert must be used to ensure that when the name of the layout |
| 33773 |
type and its value are added to the NFSv4.1 layouttype4 |
| 33774 |
enumerated data type in the NFSv4.1 XDR description ([<a href="#ref-13" title=""Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description"">13</a>]), the |
| 33775 |
result continues to be a valid XDR description. |
| 33776 |
|
| 33777 |
3. The Standards Track RFC(s) that describe the notification. If |
| 33778 |
the RFC(s) have not yet been published, the registrant will use |
| 33779 |
RFCTBD2, RFCTBD3, etc. instead of an actual RFC number. |
| 33780 |
Collectively, the RFC(s) must adhere to the guidelines listed in |
| 33781 |
<a href="#section-22.4.3">Section 22.4.3</a>. |
| 33782 |
|
| 33783 |
4. How the RFC introduces the layout type. This is indicated by a |
| 33784 |
single US-ASCII value. If the value is N, it means a minor |
| 33785 |
revision to the NFSv4 protocol. If the value is L, it means a |
| 33786 |
new pNFS layout type. Other values can be used with IESG |
| 33787 |
Approval. |
| 33788 |
|
| 33789 |
5. The minor versions of NFSv4 that are allowed to use the |
| 33790 |
notification. While these are numeric values, IANA will not |
| 33791 |
allocate and assign them; the author of the relevant RFCs with |
| 33792 |
IESG Approval assigns these numbers. Each time there is a new |
| 33793 |
minor version of NFSv4 approved, a Designated Expert should |
| 33794 |
review the registry to make recommended updates as needed. |
| 33795 |
|
| 33796 |
<span class="h4"><a class="selflink" id="section-22.4.1" href="#section-22.4.1">22.4.1</a>. Initial Registry</span> |
| 33797 |
|
| 33798 |
The initial registry is in Table 18. |
| 33799 |
|
| 33800 |
+-----------------------+-------+----------+-----+----------------+ |
| 33801 |
| Layout Type Name | Value | RFC | How | Minor Versions | |
| 33802 |
+-----------------------+-------+----------+-----+----------------+ |
| 33803 |
| LAYOUT4_NFSV4_1_FILES | 0x1 | <a href="./rfc5661">RFC 5661</a> | N | 1 | |
| 33804 |
| LAYOUT4_OSD2_OBJECTS | 0x2 | <a href="./rfc5664">RFC 5664</a> | L | 1 | |
| 33805 |
| LAYOUT4_BLOCK_VOLUME | 0x3 | <a href="./rfc5663">RFC 5663</a> | L | 1 | |
| 33806 |
+-----------------------+-------+----------+-----+----------------+ |
| 33807 |
|
| 33808 |
Table 18: Initial Layout Type Assignments |
| 33809 |
|
| 33810 |
<span class="h4"><a class="selflink" id="section-22.4.2" href="#section-22.4.2">22.4.2</a>. Updating Registrations</span> |
| 33811 |
|
| 33812 |
The update of a registration will require IESG Approval on the advice |
| 33813 |
of a Designated Expert. |
| 33814 |
|
| 33815 |
|
| 33816 |
|
| 33817 |
|
| 33818 |
|
| 33819 |
|
| 33820 |
<span class="grey">Shepler, et al. Standards Track [Page 604]</span></pre> |
| 33821 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-605" ></span> |
| 33822 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33823 |
|
| 33824 |
|
| 33825 |
<span class="h4"><a class="selflink" id="section-22.4.3" href="#section-22.4.3">22.4.3</a>. Guidelines for Writing Layout Type Specifications</span> |
| 33826 |
|
| 33827 |
The author of a new pNFS layout specification must follow these steps |
| 33828 |
to obtain acceptance of the layout type as a Standards Track RFC: |
| 33829 |
|
| 33830 |
1. The author devises the new layout specification. |
| 33831 |
|
| 33832 |
2. The new layout type specification MUST, at a minimum: |
| 33833 |
|
| 33834 |
* Define the contents of the layout-type-specific fields of the |
| 33835 |
following data types: |
| 33836 |
|
| 33837 |
+ the da_addr_body field of the device_addr4 data type; |
| 33838 |
|
| 33839 |
+ the loh_body field of the layouthint4 data type; |
| 33840 |
|
| 33841 |
+ the loc_body field of layout_content4 data type (which in |
| 33842 |
turn is the lo_content field of the layout4 data type); |
| 33843 |
|
| 33844 |
+ the lou_body field of the layoutupdate4 data type; |
| 33845 |
|
| 33846 |
* Describe or define the storage access protocol used to access |
| 33847 |
the storage devices. |
| 33848 |
|
| 33849 |
* Describe whether revocation of layouts is supported. |
| 33850 |
|
| 33851 |
* At a minimum, describe the methods of recovery from: |
| 33852 |
|
| 33853 |
1. Failure and restart for client, server, storage device. |
| 33854 |
|
| 33855 |
2. Lease expiration from perspective of the active client, |
| 33856 |
server, storage device. |
| 33857 |
|
| 33858 |
3. Loss of layout state resulting in fencing of client access |
| 33859 |
to storage devices (for an example, see <a href="#section-12.7.3">Section 12.7.3</a>). |
| 33860 |
|
| 33861 |
* Include an IANA considerations section, which will in turn |
| 33862 |
include: |
| 33863 |
|
| 33864 |
+ A request to IANA for a new layout type per <a href="#section-22.4">Section 22.4</a>. |
| 33865 |
|
| 33866 |
+ A list of requests to IANA for any new recallable object |
| 33867 |
types for CB_RECALL_ANY; each entry is to be presented in |
| 33868 |
the form described in <a href="#section-22.3">Section 22.3</a>. |
| 33869 |
|
| 33870 |
+ A list of requests to IANA for any new notification values |
| 33871 |
for CB_NOTIFY_DEVICEID; each entry is to be presented in |
| 33872 |
the form described in <a href="#section-22.2">Section 22.2</a>. |
| 33873 |
|
| 33874 |
|
| 33875 |
|
| 33876 |
<span class="grey">Shepler, et al. Standards Track [Page 605]</span></pre> |
| 33877 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-606" ></span> |
| 33878 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33879 |
|
| 33880 |
|
| 33881 |
* Include a security considerations section. This section MUST |
| 33882 |
explain how the NFSv4.1 authentication, authorization, and |
| 33883 |
access-control models are preserved. That is, if a metadata |
| 33884 |
server would restrict a READ or WRITE operation, how would |
| 33885 |
pNFS via the layout similarly restrict a corresponding input |
| 33886 |
or output operation? |
| 33887 |
|
| 33888 |
3. The author documents the new layout specification as an Internet- |
| 33889 |
Draft. |
| 33890 |
|
| 33891 |
4. The author submits the Internet-Draft for review through the IETF |
| 33892 |
standards process as defined in "The Internet Standards Process-- |
| 33893 |
Revision 3" (<a href="https://www.rfc-editor.org/bcp/bcp9">BCP 9</a>). The new layout specification will be |
| 33894 |
submitted for eventual publication as a Standards Track RFC. |
| 33895 |
|
| 33896 |
5. The layout specification progresses through the IETF standards |
| 33897 |
process. |
| 33898 |
|
| 33899 |
<span class="h3"><a class="selflink" id="section-22.5" href="#section-22.5">22.5</a>. Path Variable Definitions</span> |
| 33900 |
|
| 33901 |
This section deals with the IANA considerations associated with the |
| 33902 |
variable substitution feature for location names as described in |
| 33903 |
<a href="#section-11.10.3">Section 11.10.3</a>. As described there, variables subject to |
| 33904 |
substitution consist of a domain name and a specific name within that |
| 33905 |
domain, with the two separated by a colon. There are two sets of |
| 33906 |
IANA considerations here: |
| 33907 |
|
| 33908 |
1. The list of variable names. |
| 33909 |
|
| 33910 |
2. For each variable name, the list of possible values. |
| 33911 |
|
| 33912 |
Thus, there will be one registry for the list of variable names, and |
| 33913 |
possibly one registry for listing the values of each variable name. |
| 33914 |
|
| 33915 |
<span class="h4"><a class="selflink" id="section-22.5.1" href="#section-22.5.1">22.5.1</a>. Path Variables Registry</span> |
| 33916 |
|
| 33917 |
IANA created a registry called the "NFSv4 Path Variables Registry". |
| 33918 |
|
| 33919 |
<span class="h5"><a class="selflink" id="section-22.5.1.1" href="#section-22.5.1.1">22.5.1.1</a>. Path Variable Values</span> |
| 33920 |
|
| 33921 |
Variable names are of the form "${", followed by a domain name, |
| 33922 |
followed by a colon (":"), followed by a domain-specific portion of |
| 33923 |
the variable name, followed by "}". When the domain name is |
| 33924 |
"ietf.org", all variables names must be registered with IANA on a |
| 33925 |
Standards Action basis, with Expert Review required. Path variables |
| 33926 |
with registered domain names neither part of nor equal to ietf.org |
| 33927 |
are assigned on a Hierarchical Allocation basis (delegating to the |
| 33928 |
domain owner) and thus of no concern to IANA, unless the domain owner |
| 33929 |
|
| 33930 |
|
| 33931 |
|
| 33932 |
<span class="grey">Shepler, et al. Standards Track [Page 606]</span></pre> |
| 33933 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-607" ></span> |
| 33934 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33935 |
|
| 33936 |
|
| 33937 |
chooses to register a variable name from his domain. If the domain |
| 33938 |
owner chooses to do so, IANA will do so on a First Come First Serve |
| 33939 |
basis. To accommodate registrants who do not have their own domain, |
| 33940 |
IANA will accept requests to register variables with the prefix |
| 33941 |
"${FCFS.ietf.org:" on a First Come First Served basis. Assignments |
| 33942 |
on a First Come First Basis do not require Expert Review, unless the |
| 33943 |
registrant also wants IANA to establish a registry for the values of |
| 33944 |
the registered variable. |
| 33945 |
|
| 33946 |
The registry is a list of assignments, each containing three fields. |
| 33947 |
|
| 33948 |
1. The name of the variable. The name of this variable must start |
| 33949 |
with a "${" followed by a registered domain name, followed by |
| 33950 |
":", or it must start with "${FCFS.ietf.org". The name must be |
| 33951 |
no more than 64 UTF-8 characters long. The name must be unique. |
| 33952 |
|
| 33953 |
2. For assignments made on Standards Action basis, the Standards |
| 33954 |
Track RFC(s) that describe the variable. If the RFC(s) have not |
| 33955 |
yet been published, the registrant will use RFCTBD1, RFCTBD2, |
| 33956 |
etc. instead of an actual RFC number. Note that the RFCs do not |
| 33957 |
have to be a part of an NFS minor version. For assignments made |
| 33958 |
on a First Come First Serve basis, an explanation (consuming no |
| 33959 |
more than 1024 bytes, or more if IANA permits) of the purpose of |
| 33960 |
the variable. A reference to the explanation can be substituted. |
| 33961 |
|
| 33962 |
3. The point of contact, including an email address. The point of |
| 33963 |
contact can consume up to 256 bytes (or more if IANA permits). |
| 33964 |
For assignments made on a Standards Action basis, the point of |
| 33965 |
contact is always IESG. |
| 33966 |
|
| 33967 |
<span class="h6"><a class="selflink" id="section-22.5.1.1.1" href="#section-22.5.1.1.1">22.5.1.1.1</a>. Initial Registry</span> |
| 33968 |
|
| 33969 |
The initial registry is in Table 19. |
| 33970 |
|
| 33971 |
+------------------------+----------+------------------+ |
| 33972 |
| Variable Name | RFC | Point of Contact | |
| 33973 |
+------------------------+----------+------------------+ |
| 33974 |
| ${ietf.org:CPU_ARCH} | <a href="./rfc5661">RFC 5661</a> | IESG | |
| 33975 |
| ${ietf.org:OS_TYPE} | <a href="./rfc5661">RFC 5661</a> | IESG | |
| 33976 |
| ${ietf.org:OS_VERSION} | <a href="./rfc5661">RFC 5661</a> | IESG | |
| 33977 |
+------------------------+----------+------------------+ |
| 33978 |
|
| 33979 |
Table 19: Initial List of Path Variables |
| 33980 |
|
| 33981 |
IANA has created registries for the values of the variable names |
| 33982 |
${ietf.org:CPU_ARCH} and ${ietf.org:OS_TYPE}. See Sections <a href="#section-22.5.2">22.5.2</a> |
| 33983 |
and 22.5.3. |
| 33984 |
|
| 33985 |
|
| 33986 |
|
| 33987 |
|
| 33988 |
<span class="grey">Shepler, et al. Standards Track [Page 607]</span></pre> |
| 33989 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-608" ></span> |
| 33990 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 33991 |
|
| 33992 |
|
| 33993 |
For the values of the variable ${ietf.org:OS_VERSION}, no registry is |
| 33994 |
needed as the specifics of the values of the variable will vary with |
| 33995 |
the value of ${ietf.org:OS_TYPE}. Thus, values for ${ietf.org: |
| 33996 |
OS_VERSION} are on a Hierarchical Allocation basis and are of no |
| 33997 |
concern to IANA. |
| 33998 |
|
| 33999 |
<span class="h6"><a class="selflink" id="section-22.5.1.1.2" href="#section-22.5.1.1.2">22.5.1.1.2</a>. Updating Registrations</span> |
| 34000 |
|
| 34001 |
The update of an assignment made on a Standards Action basis will |
| 34002 |
require IESG Approval on the advice of a Designated Expert. |
| 34003 |
|
| 34004 |
The registrant can always update the point of contact of an |
| 34005 |
assignment made on a First Come First Serve basis. Any other update |
| 34006 |
will require Expert Review. |
| 34007 |
|
| 34008 |
<span class="h4"><a class="selflink" id="section-22.5.2" href="#section-22.5.2">22.5.2</a>. Values for the ${ietf.org:CPU_ARCH} Variable</span> |
| 34009 |
|
| 34010 |
IANA created a registry called the "NFSv4 ${ietf.org:CPU_ARCH} Value |
| 34011 |
Registry". |
| 34012 |
|
| 34013 |
Assignments to the registry are made on a First Come First Serve |
| 34014 |
basis. The zero-length value of ${ietf.org:CPU_ARCH} is Reserved. |
| 34015 |
Values with a prefix of "PRIV" are designated for Private Use. |
| 34016 |
|
| 34017 |
The registry is a list of assignments, each containing three fields. |
| 34018 |
|
| 34019 |
1. A value of the ${ietf.org:CPU_ARCH} variable. The value must be |
| 34020 |
1 to 32 UTF-8 characters long. The value must be unique. |
| 34021 |
|
| 34022 |
2. An explanation (consuming no more than 1024 bytes, or more if |
| 34023 |
IANA permits) of what CPU architecture the value denotes. A |
| 34024 |
reference to the explanation can be substituted. |
| 34025 |
|
| 34026 |
3. The point of contact, including an email address. The point of |
| 34027 |
contact can consume up to 256 bytes (or more if IANA permits). |
| 34028 |
|
| 34029 |
<span class="h5"><a class="selflink" id="section-22.5.2.1" href="#section-22.5.2.1">22.5.2.1</a>. Initial Registry</span> |
| 34030 |
|
| 34031 |
There is no initial registry. |
| 34032 |
|
| 34033 |
<span class="h5"><a class="selflink" id="section-22.5.2.2" href="#section-22.5.2.2">22.5.2.2</a>. Updating Registrations</span> |
| 34034 |
|
| 34035 |
The registrant is free to update the assignment, i.e., change the |
| 34036 |
explanation and/or point-of-contact fields. |
| 34037 |
|
| 34038 |
|
| 34039 |
|
| 34040 |
|
| 34041 |
|
| 34042 |
|
| 34043 |
|
| 34044 |
<span class="grey">Shepler, et al. Standards Track [Page 608]</span></pre> |
| 34045 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-609" ></span> |
| 34046 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 34047 |
|
| 34048 |
|
| 34049 |
<span class="h4"><a class="selflink" id="section-22.5.3" href="#section-22.5.3">22.5.3</a>. Values for the ${ietf.org:OS_TYPE} Variable</span> |
| 34050 |
|
| 34051 |
IANA created a registry called the "NFSv4 ${ietf.org:OS_TYPE} Value |
| 34052 |
Registry". |
| 34053 |
|
| 34054 |
Assignments to the registry are made on a First Come First Serve |
| 34055 |
basis. The zero-length value of ${ietf.org:OS_TYPE} is Reserved. |
| 34056 |
Values with a prefix of "PRIV" are designated for Private Use. |
| 34057 |
|
| 34058 |
The registry is a list of assignments, each containing three fields. |
| 34059 |
|
| 34060 |
1. A value of the ${ietf.org:OS_TYPE} variable. The value must be 1 |
| 34061 |
to 32 UTF-8 characters long. The value must be unique. |
| 34062 |
|
| 34063 |
2. An explanation (consuming no more than 1024 bytes, or more if |
| 34064 |
IANA permits) of what CPU architecture the value denotes. A |
| 34065 |
reference to the explanation can be substituted. |
| 34066 |
|
| 34067 |
3. The point of contact, including an email address. The point of |
| 34068 |
contact can consume up to 256 bytes (or more if IANA permits). |
| 34069 |
|
| 34070 |
<span class="h5"><a class="selflink" id="section-22.5.3.1" href="#section-22.5.3.1">22.5.3.1</a>. Initial Registry</span> |
| 34071 |
|
| 34072 |
There is no initial registry. |
| 34073 |
|
| 34074 |
<span class="h5"><a class="selflink" id="section-22.5.3.2" href="#section-22.5.3.2">22.5.3.2</a>. Updating Registrations</span> |
| 34075 |
|
| 34076 |
The registrant is free to update the assignment, i.e., change the |
| 34077 |
explanation and/or point of contact fields. |
| 34078 |
|
| 34079 |
<span class="h2"><a class="selflink" id="section-23" href="#section-23">23</a>. References</span> |
| 34080 |
|
| 34081 |
<span class="h3"><a class="selflink" id="section-23.1" href="#section-23.1">23.1</a>. Normative References</span> |
| 34082 |
|
| 34083 |
[<a id="ref-1">1</a>] Bradner, S., "Key words for use in RFCs to Indicate Requirement |
| 34084 |
Levels", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>, March 1997. |
| 34085 |
|
| 34086 |
[<a id="ref-2">2</a>] Eisler, M., Ed., "XDR: External Data Representation Standard", |
| 34087 |
STD 67, <a href="./rfc4506">RFC 4506</a>, May 2006. |
| 34088 |
|
| 34089 |
[<a id="ref-3">3</a>] Thurlow, R., "RPC: Remote Procedure Call Protocol Specification |
| 34090 |
Version 2", <a href="./rfc5531">RFC 5531</a>, May 2009. |
| 34091 |
|
| 34092 |
[<a id="ref-4">4</a>] Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol |
| 34093 |
Specification", <a href="./rfc2203">RFC 2203</a>, September 1997. |
| 34094 |
|
| 34095 |
|
| 34096 |
|
| 34097 |
|
| 34098 |
|
| 34099 |
|
| 34100 |
<span class="grey">Shepler, et al. Standards Track [Page 609]</span></pre> |
| 34101 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-610" ></span> |
| 34102 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 34103 |
|
| 34104 |
|
| 34105 |
[<a id="ref-5">5</a>] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos Version |
| 34106 |
5 Generic Security Service Application Program Interface (GSS- |
| 34107 |
API) Mechanism Version 2", <a href="./rfc4121">RFC 4121</a>, July 2005. |
| 34108 |
|
| 34109 |
[<a id="ref-6">6</a>] The Open Group, "<a href="#section-3.191">Section 3.191</a> of Chapter 3 of Base Definitions |
| 34110 |
of The Open Group Base Specifications Issue 6 IEEE Std 1003.1, |
| 34111 |
2004 Edition, HTML Version (www.opengroup.org), ISBN |
| 34112 |
1931624232", 2004. |
| 34113 |
|
| 34114 |
[<a id="ref-7">7</a>] Linn, J., "Generic Security Service Application Program |
| 34115 |
Interface Version 2, Update 1", <a href="./rfc2743">RFC 2743</a>, January 2000. |
| 34116 |
|
| 34117 |
[<a id="ref-8">8</a>] Talpey, T. and B. Callaghan, "Remote Direct Memory Access |
| 34118 |
Transport for Remote Procedure Call", <a href="./rfc5666">RFC 5666</a>, January 2010. |
| 34119 |
|
| 34120 |
[<a id="ref-9">9</a>] Talpey, T. and B. Callaghan, "Network File System (NFS) Direct |
| 34121 |
Data Placement", <a href="./rfc5667">RFC 5667</a>, January 2010. |
| 34122 |
|
| 34123 |
[<a id="ref-10">10</a>] Recio, R., Metzler, B., Culley, P., Hilland, J., and D. Garcia, |
| 34124 |
"A Remote Direct Memory Access Protocol Specification", |
| 34125 |
<a href="./rfc5040">RFC 5040</a>, October 2007. |
| 34126 |
|
| 34127 |
[<a id="ref-11">11</a>] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-Hashing |
| 34128 |
for Message Authentication", <a href="./rfc2104">RFC 2104</a>, February 1997. |
| 34129 |
|
| 34130 |
[<a id="ref-12">12</a>] Eisler, M., "RPCSEC_GSS Version 2", <a href="./rfc5403">RFC 5403</a>, February 2009. |
| 34131 |
|
| 34132 |
[<a id="ref-13">13</a>] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., "Network |
| 34133 |
File System (NFS) Version 4 Minor Version 1 External Data |
| 34134 |
Representation Standard (XDR) Description", <a href="./rfc5662">RFC 5662</a>, |
| 34135 |
January 2010. |
| 34136 |
|
| 34137 |
[<a id="ref-14">14</a>] The Open Group, "<a href="#section-3.372">Section 3.372</a> of Chapter 3 of Base Definitions |
| 34138 |
of The Open Group Base Specifications Issue 6 IEEE Std 1003.1, |
| 34139 |
2004 Edition, HTML Version (www.opengroup.org), ISBN |
| 34140 |
1931624232", 2004. |
| 34141 |
|
| 34142 |
[<a id="ref-15">15</a>] Eisler, M., "IANA Considerations for Remote Procedure Call |
| 34143 |
(RPC) Network Identifiers and Universal Address Formats", |
| 34144 |
<a href="./rfc5665">RFC 5665</a>, January 2010. |
| 34145 |
|
| 34146 |
[<a id="ref-16">16</a>] The Open Group, "Section 'read()' of System Interfaces of The |
| 34147 |
Open Group Base Specifications Issue 6 IEEE Std 1003.1, 2004 |
| 34148 |
Edition, HTML Version (www.opengroup.org), ISBN 1931624232", |
| 34149 |
2004. |
| 34150 |
|
| 34151 |
|
| 34152 |
|
| 34153 |
|
| 34154 |
|
| 34155 |
|
| 34156 |
<span class="grey">Shepler, et al. Standards Track [Page 610]</span></pre> |
| 34157 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-611" ></span> |
| 34158 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 34159 |
|
| 34160 |
|
| 34161 |
[<a id="ref-17">17</a>] The Open Group, "Section 'readdir()' of System Interfaces of |
| 34162 |
The Open Group Base Specifications Issue 6 IEEE Std 1003.1, |
| 34163 |
2004 Edition, HTML Version (www.opengroup.org), ISBN |
| 34164 |
1931624232", 2004. |
| 34165 |
|
| 34166 |
[<a id="ref-18">18</a>] The Open Group, "Section 'write()' of System Interfaces of The |
| 34167 |
Open Group Base Specifications Issue 6 IEEE Std 1003.1, 2004 |
| 34168 |
Edition, HTML Version (www.opengroup.org), ISBN 1931624232", |
| 34169 |
2004. |
| 34170 |
|
| 34171 |
[<a id="ref-19">19</a>] Hoffman, P. and M. Blanchet, "Preparation of Internationalized |
| 34172 |
Strings ("stringprep")", <a href="./rfc3454">RFC 3454</a>, December 2002. |
| 34173 |
|
| 34174 |
[<a id="ref-20">20</a>] The Open Group, "Section 'chmod()' of System Interfaces of The |
| 34175 |
Open Group Base Specifications Issue 6 IEEE Std 1003.1, 2004 |
| 34176 |
Edition, HTML Version (www.opengroup.org), ISBN 1931624232", |
| 34177 |
2004. |
| 34178 |
|
| 34179 |
[<a id="ref-21">21</a>] International Organization for Standardization, "Information |
| 34180 |
Technology - Universal Multiple-octet coded Character Set (UCS) |
| 34181 |
- Part 1: Architecture and Basic Multilingual Plane", |
| 34182 |
ISO Standard 10646-1, May 1993. |
| 34183 |
|
| 34184 |
[<a id="ref-22">22</a>] Alvestrand, H., "IETF Policy on Character Sets and Languages", |
| 34185 |
<a href="https://www.rfc-editor.org/bcp/bcp18">BCP 18</a>, <a href="./rfc2277">RFC 2277</a>, January 1998. |
| 34186 |
|
| 34187 |
[<a id="ref-23">23</a>] Hoffman, P. and M. Blanchet, "Nameprep: A Stringprep Profile |
| 34188 |
for Internationalized Domain Names (IDN)", <a href="./rfc3491">RFC 3491</a>, |
| 34189 |
March 2003. |
| 34190 |
|
| 34191 |
[<a id="ref-24">24</a>] The Open Group, "Section 'fcntl()' of System Interfaces of The |
| 34192 |
Open Group Base Specifications Issue 6 IEEE Std 1003.1, 2004 |
| 34193 |
Edition, HTML Version (www.opengroup.org), ISBN 1931624232", |
| 34194 |
2004. |
| 34195 |
|
| 34196 |
[<a id="ref-25">25</a>] The Open Group, "Section 'fsync()' of System Interfaces of The |
| 34197 |
Open Group Base Specifications Issue 6 IEEE Std 1003.1, 2004 |
| 34198 |
Edition, HTML Version (www.opengroup.org), ISBN 1931624232", |
| 34199 |
2004. |
| 34200 |
|
| 34201 |
[<a id="ref-26">26</a>] The Open Group, "Section 'getpwnam()' of System Interfaces of |
| 34202 |
The Open Group Base Specifications Issue 6 IEEE Std 1003.1, |
| 34203 |
2004 Edition, HTML Version (www.opengroup.org), ISBN |
| 34204 |
1931624232", 2004. |
| 34205 |
|
| 34206 |
|
| 34207 |
|
| 34208 |
|
| 34209 |
|
| 34210 |
|
| 34211 |
|
| 34212 |
<span class="grey">Shepler, et al. Standards Track [Page 611]</span></pre> |
| 34213 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-612" ></span> |
| 34214 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 34215 |
|
| 34216 |
|
| 34217 |
[<a id="ref-27">27</a>] The Open Group, "Section 'unlink()' of System Interfaces of The |
| 34218 |
Open Group Base Specifications Issue 6 IEEE Std 1003.1, 2004 |
| 34219 |
Edition, HTML Version (www.opengroup.org), ISBN 1931624232", |
| 34220 |
2004. |
| 34221 |
|
| 34222 |
[<a id="ref-28">28</a>] Schaad, J., Kaliski, B., and R. Housley, "Additional Algorithms |
| 34223 |
and Identifiers for RSA Cryptography for use in the Internet |
| 34224 |
X.509 Public Key Infrastructure Certificate and Certificate |
| 34225 |
Revocation List (CRL) Profile", <a href="./rfc4055">RFC 4055</a>, June 2005. |
| 34226 |
|
| 34227 |
[<a id="ref-29">29</a>] National Institute of Standards and Technology, "Cryptographic |
| 34228 |
Algorithm Object Registration", URL <a href="http://csrc.nist.gov/groups/ST/crypto_apps_infra/csor/algorithms.html">http://csrc.nist.gov/</a> |
| 34229 |
<a href="http://csrc.nist.gov/groups/ST/crypto_apps_infra/csor/algorithms.html">groups/ST/crypto_apps_infra/csor/algorithms.html</a>, |
| 34230 |
November 2007. |
| 34231 |
|
| 34232 |
<span class="h3"><a class="selflink" id="section-23.2" href="#section-23.2">23.2</a>. Informative References</span> |
| 34233 |
|
| 34234 |
[<a id="ref-30">30</a>] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame, |
| 34235 |
C., Eisler, M., and D. Noveck, "Network File System (NFS) |
| 34236 |
version 4 Protocol", <a href="./rfc3530">RFC 3530</a>, April 2003. |
| 34237 |
|
| 34238 |
[<a id="ref-31">31</a>] Callaghan, B., Pawlowski, B., and P. Staubach, "NFS Version 3 |
| 34239 |
Protocol Specification", <a href="./rfc1813">RFC 1813</a>, June 1995. |
| 34240 |
|
| 34241 |
[<a id="ref-32">32</a>] Eisler, M., "LIPKEY - A Low Infrastructure Public Key Mechanism |
| 34242 |
Using SPKM", <a href="./rfc2847">RFC 2847</a>, June 2000. |
| 34243 |
|
| 34244 |
[<a id="ref-33">33</a>] Eisler, M., "NFS Version 2 and Version 3 Security Issues and |
| 34245 |
the NFS Protocol's Use of RPCSEC_GSS and Kerberos V5", |
| 34246 |
<a href="./rfc2623">RFC 2623</a>, June 1999. |
| 34247 |
|
| 34248 |
[<a id="ref-34">34</a>] Juszczak, C., "Improving the Performance and Correctness of an |
| 34249 |
NFS Server", USENIX Conference Proceedings, June 1990. |
| 34250 |
|
| 34251 |
[<a id="ref-35">35</a>] Reynolds, J., Ed., "Assigned Numbers: <a href="./rfc1700">RFC 1700</a> is Replaced by |
| 34252 |
an On-line Database", <a href="./rfc3232">RFC 3232</a>, January 2002. |
| 34253 |
|
| 34254 |
[<a id="ref-36">36</a>] Srinivasan, R., "Binding Protocols for ONC RPC Version 2", |
| 34255 |
<a href="./rfc1833">RFC 1833</a>, August 1995. |
| 34256 |
|
| 34257 |
[<a id="ref-37">37</a>] Werme, R., "RPC XID Issues", USENIX Conference Proceedings, |
| 34258 |
February 1996. |
| 34259 |
|
| 34260 |
[<a id="ref-38">38</a>] Nowicki, B., "NFS: Network File System Protocol specification", |
| 34261 |
<a href="./rfc1094">RFC 1094</a>, March 1989. |
| 34262 |
|
| 34263 |
[<a id="ref-39">39</a>] Bhide, A., Elnozahy, E., and S. Morgan, "A Highly Available |
| 34264 |
Network Server", USENIX Conference Proceedings, January 1991. |
| 34265 |
|
| 34266 |
|
| 34267 |
|
| 34268 |
<span class="grey">Shepler, et al. Standards Track [Page 612]</span></pre> |
| 34269 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-613" ></span> |
| 34270 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 34271 |
|
| 34272 |
|
| 34273 |
[<a id="ref-40">40</a>] Halevy, B., Welch, B., and J. Zelenka, "Object-Based Parallel |
| 34274 |
NFS (pNFS) Operations", <a href="./rfc5664">RFC 5664</a>, January 2010. |
| 34275 |
|
| 34276 |
[<a id="ref-41">41</a>] Black, D., Glasgow, J., and S. Fridella, "Parallel NFS (pNFS) |
| 34277 |
Block/Volume Layout", <a href="./rfc5663">RFC 5663</a>, January 2010. |
| 34278 |
|
| 34279 |
[<a id="ref-42">42</a>] Callaghan, B., "WebNFS Client Specification", <a href="./rfc2054">RFC 2054</a>, |
| 34280 |
October 1996. |
| 34281 |
|
| 34282 |
[<a id="ref-43">43</a>] Callaghan, B., "WebNFS Server Specification", <a href="./rfc2055">RFC 2055</a>, |
| 34283 |
October 1996. |
| 34284 |
|
| 34285 |
[<a id="ref-44">44</a>] IESG, "IESG Processing of RFC Errata for the IETF Stream", |
| 34286 |
July 2008. |
| 34287 |
|
| 34288 |
[<a id="ref-45">45</a>] Shepler, S., "NFS Version 4 Design Considerations", <a href="./rfc2624">RFC 2624</a>, |
| 34289 |
June 1999. |
| 34290 |
|
| 34291 |
[<a id="ref-46">46</a>] The Open Group, "Protocols for Interworking: XNFS, Version 3W, |
| 34292 |
ISBN 1-85912-184-5", February 1998. |
| 34293 |
|
| 34294 |
[<a id="ref-47">47</a>] Floyd, S. and V. Jacobson, "The Synchronization of Periodic |
| 34295 |
Routing Messages", IEEE/ACM Transactions on Networking 2(2), |
| 34296 |
pp. 122-136, April 1994. |
| 34297 |
|
| 34298 |
[<a id="ref-48">48</a>] Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, M., and E. |
| 34299 |
Zeidner, "Internet Small Computer Systems Interface (iSCSI)", |
| 34300 |
<a href="./rfc3720">RFC 3720</a>, April 2004. |
| 34301 |
|
| 34302 |
[<a id="ref-49">49</a>] Snively, R., "Fibre Channel Protocol for SCSI, 2nd Version |
| 34303 |
(FCP-2)", ANSI/INCITS 350-2003, Oct 2003. |
| 34304 |
|
| 34305 |
[<a id="ref-50">50</a>] Weber, R., "Object-Based Storage Device Commands (OSD)", ANSI/ |
| 34306 |
INCITS 400-2004, July 2004, |
| 34307 |
<<a href="http://www.t10.org/ftp/t10/drafts/osd/osd-r10.pdf">http://www.t10.org/ftp/t10/drafts/osd/osd-r10.pdf</a>>. |
| 34308 |
|
| 34309 |
[<a id="ref-51">51</a>] Carns, P., Ligon III, W., Ross, R., and R. Thakur, "PVFS: A |
| 34310 |
Parallel File System for Linux Clusters.", Proceedings of the |
| 34311 |
4th Annual Linux Showcase and Conference, 2000. |
| 34312 |
|
| 34313 |
[<a id="ref-52">52</a>] The Open Group, "The Open Group Base Specifications Issue 6, |
| 34314 |
IEEE Std 1003.1, 2004 Edition", 2004. |
| 34315 |
|
| 34316 |
[<a id="ref-53">53</a>] Callaghan, B., "NFS URL Scheme", <a href="./rfc2224">RFC 2224</a>, October 1997. |
| 34317 |
|
| 34318 |
[<a id="ref-54">54</a>] Chiu, A., Eisler, M., and B. Callaghan, "Security Negotiation |
| 34319 |
for WebNFS", <a href="./rfc2755">RFC 2755</a>, January 2000. |
| 34320 |
|
| 34321 |
|
| 34322 |
|
| 34323 |
|
| 34324 |
<span class="grey">Shepler, et al. Standards Track [Page 613]</span></pre> |
| 34325 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-614" ></span> |
| 34326 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 34327 |
|
| 34328 |
|
| 34329 |
[<a id="ref-55">55</a>] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA |
| 34330 |
Considerations Section in RFCs", <a href="https://www.rfc-editor.org/bcp/bcp26">BCP 26</a>, <a href="./rfc5226">RFC 5226</a>, May 2008. |
| 34331 |
|
| 34332 |
|
| 34333 |
|
| 34334 |
|
| 34335 |
|
| 34336 |
|
| 34337 |
|
| 34338 |
|
| 34339 |
|
| 34340 |
|
| 34341 |
|
| 34342 |
|
| 34343 |
|
| 34344 |
|
| 34345 |
|
| 34346 |
|
| 34347 |
|
| 34348 |
|
| 34349 |
|
| 34350 |
|
| 34351 |
|
| 34352 |
|
| 34353 |
|
| 34354 |
|
| 34355 |
|
| 34356 |
|
| 34357 |
|
| 34358 |
|
| 34359 |
|
| 34360 |
|
| 34361 |
|
| 34362 |
|
| 34363 |
|
| 34364 |
|
| 34365 |
|
| 34366 |
|
| 34367 |
|
| 34368 |
|
| 34369 |
|
| 34370 |
|
| 34371 |
|
| 34372 |
|
| 34373 |
|
| 34374 |
|
| 34375 |
|
| 34376 |
|
| 34377 |
|
| 34378 |
|
| 34379 |
|
| 34380 |
<span class="grey">Shepler, et al. Standards Track [Page 614]</span></pre> |
| 34381 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-615" ></span> |
| 34382 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 34383 |
|
| 34384 |
|
| 34385 |
<span class="h2"><a class="selflink" id="appendix-A" href="#appendix-A">Appendix A</a>. Acknowledgments</span> |
| 34386 |
|
| 34387 |
The initial text for the SECINFO extensions were edited by Mike |
| 34388 |
Eisler with contributions from Peng Dai, Sergey Klyushin, and Carl |
| 34389 |
Burnett. |
| 34390 |
|
| 34391 |
The initial text for the SESSIONS extensions were edited by Tom |
| 34392 |
Talpey, Spencer Shepler, Jon Bauman with contributions from Charles |
| 34393 |
Antonelli, Brent Callaghan, Mike Eisler, John Howard, Chet Juszczak, |
| 34394 |
Trond Myklebust, Dave Noveck, John Scott, Mike Stolarchuk, and Mark |
| 34395 |
Wittle. |
| 34396 |
|
| 34397 |
Initial text relating to multi-server namespace features, including |
| 34398 |
the concept of referrals, were contributed by Dave Noveck, Carl |
| 34399 |
Burnett, and Charles Fan with contributions from Ted Anderson, Neil |
| 34400 |
Brown, and Jon Haswell. |
| 34401 |
|
| 34402 |
The initial text for the Directory Delegations support were |
| 34403 |
contributed by Saadia Khan with input from Dave Noveck, Mike Eisler, |
| 34404 |
Carl Burnett, Ted Anderson, and Tom Talpey. |
| 34405 |
|
| 34406 |
The initial text for the ACL explanations were contributed by Sam |
| 34407 |
Falkner and Lisa Week. |
| 34408 |
|
| 34409 |
The pNFS work was inspired by the NASD and OSD work done by Garth |
| 34410 |
Gibson. Gary Grider has also been a champion of high-performance |
| 34411 |
parallel I/O. Garth Gibson and Peter Corbett started the pNFS effort |
| 34412 |
with a problem statement document for the IETF that formed the basis |
| 34413 |
for the pNFS work in NFSv4.1. |
| 34414 |
|
| 34415 |
The initial text for the parallel NFS support was edited by Brent |
| 34416 |
Welch and Garth Goodson. Additional authors for those documents were |
| 34417 |
Benny Halevy, David Black, and Andy Adamson. Additional input came |
| 34418 |
from the informal group that contributed to the construction of the |
| 34419 |
initial pNFS drafts; specific acknowledgment goes to Gary Grider, |
| 34420 |
Peter Corbett, Dave Noveck, Peter Honeyman, and Stephen Fridella. |
| 34421 |
|
| 34422 |
Fredric Isaman found several errors in draft versions of the ONC RPC |
| 34423 |
XDR description of the NFSv4.1 protocol. |
| 34424 |
|
| 34425 |
Audrey Van Belleghem provided, in numerous ways, essential co- |
| 34426 |
ordination and management of the process of editing the specification |
| 34427 |
documents. |
| 34428 |
|
| 34429 |
Richard Jernigan gave feedback on the file layout's striping pattern |
| 34430 |
design. |
| 34431 |
|
| 34432 |
|
| 34433 |
|
| 34434 |
|
| 34435 |
|
| 34436 |
<span class="grey">Shepler, et al. Standards Track [Page 615]</span></pre> |
| 34437 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-616" ></span> |
| 34438 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 34439 |
|
| 34440 |
|
| 34441 |
Several formal inspection teams were formed to review various areas |
| 34442 |
of the protocol. All the inspections found significant errors and |
| 34443 |
room for improvement. NFSv4.1's inspection teams were: |
| 34444 |
|
| 34445 |
o ACLs, with the following inspectors: Sam Falkner, Bruce Fields, |
| 34446 |
Rahul Iyer, Saadia Khan, Dave Noveck, Lisa Week, Mario Wurzl, and |
| 34447 |
Alan Yoder. |
| 34448 |
|
| 34449 |
o Sessions, with the following inspectors: William Brown, Tom |
| 34450 |
Doeppner, Robert Gordon, Benny Halevy, Fredric Isaman, Rick |
| 34451 |
Macklem, Trond Myklebust, Dave Noveck, Karen Rochford, John Scott, |
| 34452 |
and Peter Shah. |
| 34453 |
|
| 34454 |
o Initial pNFS inspection, with the following inspectors: Andy |
| 34455 |
Adamson, David Black, Mike Eisler, Marc Eshel, Sam Falkner, Garth |
| 34456 |
Goodson, Benny Halevy, Rahul Iyer, Trond Myklebust, Spencer |
| 34457 |
Shepler, and Lisa Week. |
| 34458 |
|
| 34459 |
o Global namespace, with the following inspectors: Mike Eisler, Dan |
| 34460 |
Ellard, Craig Everhart, Fredric Isaman, Trond Myklebust, Dave |
| 34461 |
Noveck, Theresa Raj, Spencer Shepler, Renu Tewari, and Robert |
| 34462 |
Thurlow. |
| 34463 |
|
| 34464 |
o NFSv4.1 file layout type, with the following inspectors: Andy |
| 34465 |
Adamson, Marc Eshel, Sam Falkner, Garth Goodson, Rahul Iyer, Trond |
| 34466 |
Myklebust, and Lisa Week. |
| 34467 |
|
| 34468 |
o NFSv4.1 locking and directory delegations, with the following |
| 34469 |
inspectors: Mike Eisler, Pranoop Erasani, Robert Gordon, Saadia |
| 34470 |
Khan, Eric Kustarz, Dave Noveck, Spencer Shepler, and Amy Weaver. |
| 34471 |
|
| 34472 |
o EXCHANGE_ID and DESTROY_CLIENTID, with the following inspectors: |
| 34473 |
Mike Eisler, Pranoop Erasani, Robert Gordon, Benny Halevy, Fredric |
| 34474 |
Isaman, Saadia Khan, Ricardo Labiaga, Rick Macklem, Trond |
| 34475 |
Myklebust, Spencer Shepler, and Brent Welch. |
| 34476 |
|
| 34477 |
o Final pNFS inspection, with the following inspectors: Andy |
| 34478 |
Adamson, Mike Eisler, Mark Eshel, Sam Falkner, Jason Glasgow, |
| 34479 |
Garth Goodson, Robert Gordon, Benny Halevy, Dean Hildebrand, Rahul |
| 34480 |
Iyer, Suchit Kaura, Trond Myklebust, Anatoly Pinchuk, Spencer |
| 34481 |
Shepler, Renu Tewari, Lisa Week, and Brent Welch. |
| 34482 |
|
| 34483 |
A review team worked together to generate the tables of assignments |
| 34484 |
of error sets to operations and make sure that each such assignment |
| 34485 |
had two or more people validating it. Participating in the process |
| 34486 |
were Andy Adamson, Mike Eisler, Sam Falkner, Garth Goodson, Robert |
| 34487 |
Gordon, Trond Myklebust, Dave Noveck, Spencer Shepler, Tom Talpey, |
| 34488 |
Amy Weaver, and Lisa Week. |
| 34489 |
|
| 34490 |
|
| 34491 |
|
| 34492 |
<span class="grey">Shepler, et al. Standards Track [Page 616]</span></pre> |
| 34493 |
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-617" ></span> |
| 34494 |
<span class="grey"><a href="./rfc5661">RFC 5661</a> NFSv4.1 January 2010</span> |
| 34495 |
|
| 34496 |
|
| 34497 |
Jari Arkko, David Black, Scott Bradner, Lisa Dusseault, Lars Eggert, |
| 34498 |
Chris Newman, and Tim Polk provided valuable review and guidance. |
| 34499 |
|
| 34500 |
Olga Kornievskaia found several errors in the SSV specification. |
| 34501 |
|
| 34502 |
Ricardo Labiaga found several places where the use of RPCSEC_GSS was |
| 34503 |
underspecified. |
| 34504 |
|
| 34505 |
Those who provided miscellaneous comments include: Andy Adamson, |
| 34506 |
Sunil Bhargo, Alex Burlyga, Pranoop Erasani, Bruce Fields, Vadim |
| 34507 |
Finkelstein, Jason Goldschmidt, Vijay K. Gurbani, Sergey Klyushin, |
| 34508 |
Ricardo Labiaga, James Lentini, Anshul Madan, Daniel Muntz, Daniel |
| 34509 |
Picken, Archana Ramani, Jim Rees, Mahesh Siddheshwar, Tom Talpey, and |
| 34510 |
Peter Varga. |
| 34511 |
|
| 34512 |
Authors' Addresses |
| 34513 |
|
| 34514 |
Spencer Shepler (editor) |
| 34515 |
Storspeed, Inc. |
| 34516 |
7808 Moonflower Drive |
| 34517 |
Austin, TX 78750 |
| 34518 |
USA |
| 34519 |
|
| 34520 |
Phone: +1-512-402-5811 ext 8530 |
| 34521 |
EMail: [email protected] |
| 34522 |
|
| 34523 |
|
| 34524 |
Mike Eisler (editor) |
| 34525 |
NetApp |
| 34526 |
5765 Chase Point Circle |
| 34527 |
Colorado Springs, CO 80919 |
| 34528 |
USA |
| 34529 |
|
| 34530 |
Phone: +1-719-599-9026 |
| 34531 |
EMail: [email protected] |
| 34532 |
URI: <a href="http://www.eisler.com">http://www.eisler.com</a> |
| 34533 |
|
| 34534 |
|
| 34535 |
David Noveck (editor) |
| 34536 |
NetApp |
| 34537 |
1601 Trapelo Road, Suite 16 |
| 34538 |
Waltham, MA 02451 |
| 34539 |
USA |
| 34540 |
|
| 34541 |
Phone: +1-781-768-5347 |
| 34542 |
EMail: [email protected] |
| 34543 |
|
| 34544 |
|
| 34545 |
|
| 34546 |
|
| 34547 |
|
| 34548 |
Shepler, et al. Standards Track [Page 617] |
| 34549 |
</pre> |