Debian Codegraph @

rfc5661.html

raw
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&nbsp;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="&quot;Network File System (NFS) version 4 Protocol&quot;">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="&quot;Key words for use in RFCs to Indicate Requirement Levels&quot;">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="&quot;NFS Version 3 Protocol Specification&quot;">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="&quot;XDR: External Data Representation Standard&quot;">2</a>] and [<a href="#ref-3" title="&quot;RPC: Remote Procedure Call Protocol Specification Version 2&quot;">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="&quot;XDR: External Data Representation Standard&quot;">2</a>] and [<a href="#ref-3" title="&quot;RPC: Remote Procedure Call Protocol Specification Version 2&quot;">3</a>]. To meet end-to-end
717 security requirements, the RPCSEC_GSS framework [<a href="#ref-4" title="&quot;RPCSEC_GSS Protocol Specification&quot;">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="&quot;The Kerberos Version 5 Generic Security Service Application Program Interface (GSS- API) Mechanism Version 2&quot;">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="&quot;NFS Version 3 Protocol Specification&quot;">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="&quot;LIPKEY - A Low Infrastructure Public Key Mechanism Using SPKM&quot;">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="&quot;RPC: Remote Procedure Call Protocol Specification Version 2&quot;">3</a>] and [<a href="#ref-2" title="&quot;XDR: External Data Representation Standard&quot;">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="&quot;RPC: Remote Procedure Call Protocol Specification Version 2&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">4</a>] uses the functionality of GSS-API [<a href="#ref-7" title="&quot;Generic Security Service Application Program Interface Version 2, Update 1&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">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="&quot;The Kerberos Version 5 Generic Security Service Application Program Interface (GSS- API) Mechanism Version 2&quot;">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="&quot;NFS Version 2 and Version 3 Security Issues and the NFS Protocol's Use of RPCSEC_GSS and Kerberos V5&quot;">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&lt;NFS4_OPAQUE_LIMIT&gt;;
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="&quot;Network File System (NFS) version 4 Protocol&quot;">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="&quot;Network File System (NFS) version 4 Protocol&quot;">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&lt;NFS4_OPAQUE_LIMIT&gt;;
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 &lt;= sec_policy_parent (&lt;= 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="&quot;Network File System (NFS) version 4 Protocol&quot;">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="&quot;Improving the Performance and Correctness of an NFS Server&quot;">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="&quot;RPC: Remote Procedure Call Protocol Specification Version 2&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">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="&quot;Assigned Numbers: RFC 1700 is Replaced by an On-line Database&quot;">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="&quot;Binding Protocols for ONC RPC Version 2&quot;">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="&quot;RPC XID Issues&quot;">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="&quot;Improving the Performance and Correctness of an NFS Server&quot;">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="&quot;Remote Direct Memory Access Transport for Remote Procedure Call&quot;">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="&quot;NFS: Network File System Protocol specification&quot;">38</a>] is described in
3592 [<a href="#ref-39" title="&quot;A Highly Available Network Server&quot;">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="&quot;Remote Direct Memory Access Transport for Remote Procedure Call&quot;">8</a>]. A discussion of the operation of NFSv4,
3598 including NFSv4.1, over RDMA is in [<a href="#ref-9" title="&quot;Network File System (NFS) Direct Data Placement&quot;">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="&quot;Remote Direct Memory Access Transport for Remote Procedure Call&quot;">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="&quot;Remote Direct Memory Access Transport for Remote Procedure Call&quot;">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| -&gt; |User data...|
3714 \------+----------------------/ \
3715 \ \
3716 \ Receiver scatter: \-----------+- ...
3717 /-----+----------------\ \ \
3718 |RPC Request|Pad|Length| -&gt; |FS buffer|-&gt;|FS buffer|-&gt;...
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="&quot;A Remote Direct Memory Access Protocol Specification&quot;">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="&quot;Network File System (NFS) version 4 Protocol&quot;">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="&quot;HMAC: Keyed-Hashing for Message Authentication&quot;">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&lt;&gt;;
4113 };
4114
4115
4116 /* SSV GSS PerMsgToken token */
4117 struct ssv_mic_tkn4 {
4118 uint32_t smt_ssv_seq;
4119 opaque smt_hmac&lt;&gt;;
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="&quot;Generic Security Service Application Program Interface Version 2, Update 1&quot;">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&lt;&gt;;
4164 uint32_t sspt_ssv_seq;
4165 opaque sspt_orig_plain&lt;&gt;;
4166 opaque sspt_pad&lt;&gt;;
4167 };
4168
4169
4170 /* SSV GSS SealedMessage token */
4171 struct ssv_seal_cipher_tkn4 {
4172 uint32_t ssct_ssv_seq;
4173 opaque ssct_iv&lt;&gt;;
4174 opaque ssct_encr_data&lt;&gt;;
4175 opaque ssct_hmac&lt;&gt;;
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="&quot;Generic Security Service Application Program Interface Version 2, Update 1&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">4</a>] and [<a href="#ref-12" title="&quot;RPCSEC_GSS Version 2&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">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="&quot;XDR: External Data Representation Standard&quot;">2</a>] and RPC <a href="./rfc5531">RFC 5531</a> [<a href="#ref-3" title="&quot;RPC: Remote Procedure Call Protocol Specification Version 2&quot;">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="&quot;Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description&quot;">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&lt;&gt;; |
4841 | | Used for file/directory attributes. |
4842 | bitmap4 | typedef uint32_t bitmap4&lt;&gt;; |
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&lt;NFS4_FHSIZE&gt;; |
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&lt;&gt;; |
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="&quot;Generic Security Service Application Program Interface Version 2, Update 1&quot;">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&lt;&gt;; |
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&lt;&gt;; |
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&lt;&gt;; /* network id */
5064 string na_r_addr&lt;&gt;; /* 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="&quot;IANA Considerations for Remote Procedure Call (RPC) Network Identifiers and Universal Address Formats&quot;">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="&quot;IANA Considerations for Remote Procedure Call (RPC) Network Identifiers and Universal Address Formats&quot;">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&lt;NFS4_OPAQUE_LIMIT&gt;;
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="&quot;Object-Based Parallel NFS (pNFS) Operations&quot;">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="&quot;Parallel NFS (pNFS) Block/Volume Layout&quot;">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&lt;&gt;;
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&lt;&gt;;
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&lt;&gt;;
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&lt;&gt;;
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&lt;&gt;;
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&lt;&gt;;
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="&quot;NFS Version 3 Protocol Specification&quot;">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="&quot;WebNFS Client Specification&quot;">42</a>] and <a href="./rfc2055">RFC 2055</a> [<a href="#ref-43" title="&quot;WebNFS Server Specification&quot;">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="&quot;Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description&quot;">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="&quot;Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description&quot;">13</a>]. See [<a href="#ref-44" title="&quot;IESG Processing of RFC Errata for the IETF Stream&quot;">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&lt;&gt; | 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&lt;&gt; | 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&lt;&gt; | 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&nbsp;6.1 of RFC 2624</a> [<a href="#ref-45" title="&quot;NFS Version 4 Design Considerations&quot;">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&nbsp;B.2 of RFC 3454</a> [<a href="#ref-19" title="&quot;Preparation of Internationalized Strings (&quot;">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&lt;1&gt;;
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&lt;1&gt;;
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&lt;&gt;;
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="&quot;Protocols for Interworking: XNFS, Version 3W, ISBN 1-85912-184-5&quot;">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="&quot;The Synchronization of Periodic Routing Messages&quot;">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 &amp; file_state.deny)) ||
10667 (request.deny &amp; 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 &gt;= 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 --&gt; NFS_OK. The current fh is now the root of the
14083 pseudo-fs.
14084
14085 o LOOKUP "this" --&gt; NFS_OK. The current fh is for /this and is
14086 within the pseudo-fs.
14087
14088 o LOOKUP "is" --&gt; NFS_OK. The current fh is for /this/is and is
14089 within the pseudo-fs.
14090
14091 o LOOKUP "the" --&gt; NFS_OK. The current fh is for /this/is/the and
14092 is within the pseudo-fs.
14093
14094 o LOOKUP "path" --&gt; 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 --&gt; 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 --&gt; NFS_OK
14136
14137 - Current fh is root of pseudo-fs.
14138
14139 OP02: GETATTR(fsid) --&gt; 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" --&gt; NFS_OK
14146
14147 OP04: GETATTR(fsid) --&gt; 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 --&gt; NFS_OK
14154
14155 - Current fh is for /this and is within pseudo-fs.
14156
14157 OP06: LOOKUP "is" --&gt; 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) --&gt; 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 --&gt; NFS_OK
14176
14177 - Current fh is for /this/is and is within pseudo-fs.
14178
14179 OP09: LOOKUP "the" --&gt; NFS_OK
14180
14181 - Current fh is for /this/is/the and is within pseudo-fs.
14182
14183 OP10: GETATTR(fsid) --&gt; 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 --&gt; NFS_OK
14190
14191 - Current fh is for /this/is/the and is within pseudo-fs.
14192
14193 OP12: LOOKUP "path" --&gt; 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) --&gt; 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 --&gt; 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 --&gt; NFS_OK. The current fh is at the root of the
14287 pseudo-fs.
14288
14289 o LOOKUP "this" --&gt; NFS_OK. The current fh is for /this and is
14290 within the pseudo-fs.
14291
14292 o LOOKUP "is" --&gt; NFS_OK. The current fh is for /this/is and is
14293 within the pseudo-fs.
14294
14295 o LOOKUP "the" --&gt; 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) --&gt;
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 --&gt; NFS_OK. The current fh is at the root of the
14318 pseudo-fs.
14319
14320 o LOOKUP "this" --&gt; NFS_OK. The current fh is for /this and is
14321 within the pseudo-fs.
14322
14323 o LOOKUP "is" --&gt; NFS_OK. The current fh is for /this/is and is
14324 within the pseudo-fs.
14325
14326 o LOOKUP "the" --&gt; 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 --&gt; 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 --&gt; NFS_OK. The current fh is at the root of the
14360 pseudo-fs.
14361
14362 o LOOKUP "this" --&gt; NFS_OK. The current fh is for /this and is
14363 within the pseudo-fs.
14364
14365 o LOOKUP "is" --&gt; NFS_OK. The current fh is for /this/is and is
14366 within the pseudo-fs.
14367
14368 o LOOKUP "the" --&gt; 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) --&gt; 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&lt;&gt;;
14406 pathname4 rootpath;
14407 };
14408
14409
14410 struct fs_locations4 {
14411 pathname4 fs_root;
14412 fs_location4 locations&lt;&gt;;
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="&quot;IANA Considerations for Remote Procedure Call (RPC) Network Identifiers and Universal Address Formats&quot;">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&lt;&gt;;
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&lt;&gt;;
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&lt;&gt;;
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 |&lt;------------------------------&gt;| 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="&quot;Internet Small Computer Systems Interface (iSCSI)&quot;">48</a>] and FCP
15636 [<a href="#ref-49" title="&quot;Fibre Channel Protocol for SCSI, 2nd Version (FCP-2)&quot;">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="&quot;Parallel NFS (pNFS) Block/Volume Layout&quot;">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="&quot;Object-Based Storage Device Commands (OSD)&quot;">50</a>].
15644 See [<a href="#ref-40" title="&quot;Object-Based Parallel NFS (pNFS) Operations&quot;">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="&quot;PVFS: A Parallel File System for Linux Clusters.&quot;">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="&quot;Parallel NFS (pNFS) Block/Volume Layout&quot;">41</a>], object [<a href="#ref-40" title="&quot;Object-Based Parallel NFS (pNFS) Operations&quot;">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 &lt;device ID, block number, block count&gt; 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 &lt;device ID, object ID&gt;
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 &lt;client ID, filehandle, layout type, iomode, range&gt;,
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 &lt;client ID, layout type&gt;. 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="&quot;Object-Based Storage Device Commands (OSD)&quot;">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 &lt;loca_offset, loca_length&gt;. 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 &lt;loca_offset, loca_length&gt; 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="&quot;Parallel NFS (pNFS) Block/Volume Layout&quot;">41</a>], and objects layout [<a href="#ref-40" title="&quot;Object-Based Parallel NFS (pNFS) Operations&quot;">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 &amp; NFL4_UFLG_DENSE
17511 ("&amp;" 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 &amp; 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 &amp;
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&lt;&gt;;
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&lt;&gt;;
17552 multipath_list4 nflda_multipath_ds_list&lt;&gt;;
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&lt;&gt;;
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&lt;&gt; = { 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&lt;&gt; = { 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&lt;&gt; = { 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&lt;&gt; = { 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 &amp; 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 &amp; 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 &amp; 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 &amp;
18346 NFL4_UFLG_COMMIT_THRU_MDS is FALSE, sending a COMMIT to the metadata
18347 server might have no effect. If nfl_util &amp; 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="&quot;Information Technology - Universal Multiple-octet coded Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane&quot;">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="&quot;IETF Policy on Character Sets and Languages&quot;">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="&quot;Preparation of Internationalized Strings (&quot;">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="&quot;Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)&quot;">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&lt;&gt;;
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&lt;&gt;;
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 - -&gt; {fh1, (0, 0)}
22463 READ (sid1), 0, 1024 {fh1, (0, 0)} -&gt; {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 - -&gt; {fh1, (0, 0)}
22475 OPEN "compA" {fh1, (0, 0)} -&gt; {fh2, (sid1)}
22476 READ (1, 0), 0, 1024 {fh2, (sid1)} -&gt; {fh2, (sid1)}
22477 CLOSE (1, 0) {fh2, (sid1)} -&gt; {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 - -&gt; {fh1, (0, 0)}
22491 LOCK 0, 1024, (sid1) {fh1, (sid1)} -&gt; {fh1, (sid2)}
22492 READ (1, 0), 0, 1024 {fh1, (sid2)} -&gt; {fh1, (sid2)}
22493 LOCKU 0, 1024, (1, 0) {fh1, (sid2)} -&gt; {fh1, (sid3)}
22494 SAVEFH {fh1, (sid3)} -&gt; {fh1, (sid3)}
22495
22496 PUTFH fh2 {fh1, (sid3)} -&gt; {fh2, (0, 0)}
22497 WRITE (1, 0), 0, 1024 {fh2, (0, 0)} -&gt; {fh2, (0, 0)}
22498
22499 RESTOREFH {fh2, (0, 0)} -&gt; {fh1, (sid3)}
22500 READ (1, 0), 1024, 1024 {fh1, (sid3)} -&gt; {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 - -&gt; {fh1, (0, 0)}
22519 READ (1, 0), 0, 1024 {fh1, (0, 0)} -&gt; 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="&quot;The Open Group Base Specifications Issue 6, IEEE Std 1003.1, 2004 Edition&quot;">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 &amp; 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 &amp;
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&lt;unique value&gt;" 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 &amp;
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="&quot;WebNFS Client Specification&quot;">42</a>], <a href="./rfc2055">RFC 2055</a> [<a href="#ref-43" title="&quot;WebNFS Server Specification&quot;">43</a>], and <a href="./rfc2224">RFC 2224</a> [<a href="#ref-53" title="&quot;NFS URL Scheme&quot;">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="&quot;NFS URL Scheme&quot;">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="&quot;NFS URL Scheme&quot;">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="&quot;Security Negotiation for WebNFS&quot;">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&lt;&gt;;
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&lt;&gt;;
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="&quot;RPC: Remote Procedure Call Protocol Specification Version 2&quot;">3</a>]), or RPCSEC_GSS (as defined in
26842 <a href="./rfc2203">RFC 2203</a> [<a href="#ref-4" title="&quot;RPCSEC_GSS Protocol Specification&quot;">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="&quot;Generic Security Service Application Program Interface Version 2, Update 1&quot;">7</a>]), the quality of
26850 protection (as defined in <a href="./rfc2743">RFC 2743</a> [<a href="#ref-7" title="&quot;Generic Security Service Application Program Interface Version 2, Update 1&quot;">7</a>]), and the service type (as
26851 defined in <a href="./rfc2203">RFC 2203</a> [<a href="#ref-4" title="&quot;RPCSEC_GSS Protocol Specification&quot;">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&lt;&gt;;
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&lt;&gt;;
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&lt;&gt;;
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&lt;&gt;;
27729 sec_oid4 ssp_encr_algs&lt;&gt;;
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&lt;1&gt;;
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&lt;&gt;;
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&lt;NFS4_OPAQUE_LIMIT&gt;;
27793 nfs_impl_id4 eir_server_impl_id&lt;1&gt;;
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 &lt;= 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 &lt;= 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&nbsp;3 of RFC2104</a> [<a href="#ref-11" title="&quot;HMAC: Keyed-Hashing for Message Authentication&quot;">11</a>]).
27958
27959 + key length SHOULD be &lt;= SSV length. This is a transitive
27960 result of the above two invariants.
27961
27962 + key length SHOULD be &gt;= 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&nbsp;4
27966 of RFC2104</a> [<a href="#ref-11" title="&quot;HMAC: Keyed-Hashing for Message Authentication&quot;">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="&quot;Additional Algorithms and Identifiers for RSA Cryptography for use in the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile&quot;">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="&quot;Cryptographic Algorithm Object Registration&quot;">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&nbsp;5.2.3.1 of RFC2203</a> [<a href="#ref-4" title="&quot;RPCSEC_GSS Protocol Specification&quot;">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&lt;1&gt;;
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&lt;&gt;;
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="&quot;Remote Direct Memory Access Transport for Remote Procedure Call&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">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&nbsp;5.2.3.1 of RFC2203</a> [<a href="#ref-4" title="&quot;RPCSEC_GSS Protocol Specification&quot;">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="&quot;RPCSEC_GSS Protocol Specification&quot;">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&lt;&gt;;
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&lt;&gt;;
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 &gt;= file |
30203 | | | _READ | &lt;= a_off | length - layout |
30204 | | | | | offset |
30205 | _READ | u64m | MAY be | MUST be | MUST be u64m |
30206 | | | _RW | &lt;= a_off | |
30207 | _READ | &gt; 0 and &lt; | MAY be | MUST be | MUST be &gt;= MIN(file |
30208 | | u64m | _READ | &lt;= a_off | length, a_minlen + |
30209 | | | | | a_off) - layout |
30210 | | | | | offset |
30211 | _READ | &gt; 0 and &lt; | MAY be | MUST be | MUST be &gt;= a_off - |
30212 | | u64m | _RW | &lt;= a_off | layout offset + |
30213 | | | | | a_minlen |
30214 | _READ | 0 | MAY be | MUST be | MUST be &gt; 0 |
30215 | | | _READ | &lt;= a_off | |
30216 | _READ | 0 | MAY be | MUST be | MUST be &gt; 0 |
30217 | | | _RW | &lt;= a_off | |
30218 | _RW | u64m | MUST be | MUST be | MUST be u64m |
30219 | | | _RW | &lt;= a_off | |
30220 | _RW | &gt; 0 and &lt; | MUST be | MUST be | MUST be &gt;= a_off - |
30221 | | u64m | _RW | &lt;= a_off | layout offset + |
30222 | | | | | a_minlen |
30223 | _RW | 0 | MUST be | MUST be | MUST be &gt; 0 |
30224 | | | _RW | &lt;= 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 | &lt;= a_off | |
30257 | _READ | u64m | MAY be | MUST be | SHOULD be u64m |
30258 | | | _RW | &lt;= a_off | |
30259 | _READ | &gt; 0 and &lt; | MAY be | MUST be | SHOULD be &gt;= |
30260 | | u64m | _READ | &lt;= a_off | a_off - layout |
30261 | | | | | offset + a_len |
30262 | _READ | &gt; 0 and &lt; | MAY be | MUST be | SHOULD be &gt;= |
30263 | | u64m | _RW | &lt;= a_off | a_off - layout |
30264 | | | | | offset + a_len |
30265 | _READ | 0 | MAY be | MUST be | SHOULD be &gt; |
30266 | | | _READ | &lt;= a_off | a_off - layout |
30267 | | | | | offset |
30268 | _READ | 0 | MAY be | MUST be | SHOULD be &gt; |
30269 | | | _READ | &lt;= a_off | a_off - layout |
30270 | | | | | offset |
30271 | _RW | u64m | MUST be | MUST be | SHOULD be u64m |
30272 | | | _RW | &lt;= a_off | |
30273 | _RW | &gt; 0 and &lt; | MUST be | MUST be | SHOULD be &gt;= |
30274 | | u64m | _RW | &lt;= a_off | a_off - layout |
30275 | | | | | offset + a_len |
30276 | _RW | 0 | MUST be | MUST be | SHOULD be &gt; |
30277 | | | _RW | &lt;= 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&lt;&gt;;
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&lt;&gt;;
31278 opaque ssa_digest&lt;&gt;;
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&lt;&gt;;
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="&quot;HMAC: Keyed-Hashing for Message Authentication&quot;">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&lt;&gt;;
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&lt;&gt;;
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 &amp; OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) &amp;
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&lt;&gt;;
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&lt;&gt;;
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&lt;1&gt;;
32465 notify_entry4 nad_new_entry;
32466 /* what READDIR would have returned for this entry */
32467 nfs_cookie4 nad_new_entry_cookie&lt;1&gt;;
32468 prev_entry4 nad_prev_entry&lt;1&gt;;
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_&lt;&gt;4 and
32497 * notify_device_&lt;&gt;4 are encoded in this.
32498 */
32499 typedef opaque notifylist4&lt;&gt;;
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&lt;&gt;;
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="&quot;Parallel NFS (pNFS) Block/Volume Layout&quot;">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="&quot;Object-Based Parallel NFS (pNFS) Operations&quot;">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 &gt; 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&lt;&gt;;
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&lt;&gt;;
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&lt;&gt;;
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="&quot;Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description&quot;">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="&quot;Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description&quot;">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="&quot;Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description&quot;">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 &lt;<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>&gt;.
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>