idnits 2.17.1 draft-rmacklem-nfsv4-new-attributes-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (15 January 2022) is 831 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC8881' is defined on line 317, but no explicit reference was found in the text Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network File System Version 4 R. Macklem 3 Internet-Draft FreeBSD 4 Intended status: Standards Track 15 January 2022 5 Expires: 19 July 2022 7 New Attributes for Network File System Version 4, Minor Version 2 8 draft-rmacklem-nfsv4-new-attributes-01 10 Abstract 12 This document proposes several new recommended attributes that extend 13 the Network File System Version 4, Minor Version 2 protocol 14 (NFSv4.2). All of these new attributes would be read-only, per file 15 system attributes. 17 Note 19 This note is to be removed before publishing as an RFC. 21 Discussion of this draft occurs on the NFSv4 working group mailing 22 list (nfsv4@ietf.org), archived at 23 https://mailarchive.ietf.org/arch/browse/nfsv4/. Working Group 24 information is available at https://datatracker.ietf.org/wg/nfsv4/ 25 about/. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on 19 July 2022. 44 Copyright Notice 46 Copyright (c) 2022 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 51 license-info) in effect on the date of publication of this document. 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. Code Components 54 extracted from this document must include Revised BSD License text as 55 described in Section 4.e of the Trust Legal Provisions and are 56 provided without warranty as described in the Revised BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 2 62 3. Protocol Extension Considerations . . . . . . . . . . . . . . 3 63 4. OPTIONAL New Attributes - List and Definition References . . 3 64 4.1. Definitions of new recommended attributes . . . . . . . . 4 65 4.1.1. Attribute 83: supported_ops . . . . . . . . . . . . . 4 66 4.1.2. Attribute 84: dir_cookie_rising . . . . . . . . . . . 4 67 4.1.3. Attribute 85: seek_granularity . . . . . . . . . . . 5 68 4.1.4. Attribute 86: mandatory_br_locks . . . . . . . . . . 5 69 4.1.5. Attribute 87: max_xattr_len . . . . . . . . . . . . . 6 70 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 6 71 5.1. FreeBSD NFS server and client . . . . . . . . . . . . . . 6 72 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 73 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 74 6.2. Informational References . . . . . . . . . . . . . . . . 7 75 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 8 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 78 1. Introduction 80 Implementation experience with NFSv4.2 has identified that some 81 additional attributes providing per file system information to 82 clients are useful. This document identifies an important set of 83 additional recommended attributes. 85 2. Requirements Language 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 89 "OPTIONAL" in this document are to be interpreted as described in 90 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 91 capitals, as shown here. 93 3. Protocol Extension Considerations 95 This document presents an extension to minor version 2 of the NFSv4 96 protocol as described in [RFC8178]. It describes new OPTIONAL 97 features. NFSv4.2 servers and clients implemented without knowledge 98 of this extension will continue to interoperate with clients and 99 servers that are aware of the extension (whether or not they support 100 it). 102 Note that [RFC7862] does not define NFSv4.2 as non-extensible, so 103 [RFC8178] treats it as an extensible minor version. This Standards 104 Track RFC extends NFSv4.2 but does not update [RFC7862] or [RFC8178]. 106 4. OPTIONAL New Attributes - List and Definition References 108 The list of New OPTIONAL attributes appears in Table 1. The meaning 109 of the columns of the table are: 111 Name: The name of the attribute. 113 Id: The number assigned to the attribute. 115 Data Type: The XDR data type of the attribute. 117 Acc: Access allowed to the attribute. R means read-only. 119 Defined in: The section of this specification that describes the 120 attribute. 122 +====================+====+===========+=====+===============+ 123 | Name | Id | Data Type | Acc | Defined in: | 124 +====================+====+===========+=====+===============+ 125 | supported_ops | 83 | bitmap4 | R | Section 4.1.1 | 126 +--------------------+----+-----------+-----+---------------+ 127 | dir_cookie_rising | 84 | bool | R | Section 4.1.2 | 128 +--------------------+----+-----------+-----+---------------+ 129 | seek_granularity | 85 | uint64_t | R | Section 4.1.3 | 130 +--------------------+----+-----------+-----+---------------+ 131 | mandatory_br_locks | 86 | bool | R | Section 4.1.4 | 132 +--------------------+----+-----------+-----+---------------+ 133 | max_xattr_len | 87 | uint64_t | R | Section 4.1.5 | 134 +--------------------+----+-----------+-----+---------------+ 136 Table 1 138 4.1. Definitions of new recommended attributes 140 4.1.1. Attribute 83: supported_ops 142 This bit vector indicates which operations are supported for objects 143 (of the appropriate type) with an fsid matching that of the specified 144 object. 146 The bit vector is a counted array of 32-bit integers used to contain 147 bit values. The position of the integer in the array that contains 148 the bit corresponding to operation n can be computed from the 149 expression (n / 32), and its bit within that integer is (n mod 32), 150 where n is the operation number. 152 4.1.1.1. Rationale 154 Without this attribute, an NFSv4.2 client must attempt an optional 155 operation to determine if the server supports it. This attribute 156 allows the NFSv4.2 client to avoid attempting an optional operation 157 when it is not supported for the file object's file system on the 158 server. 160 This attribute is likely to be particularly helpful in dealing with 161 OPTIONAL attributes whose support is likely to be different for 162 different file systems. 164 4.1.2. Attribute 84: dir_cookie_rising 166 TRUE, if performing the READDIR operation on directories with a 167 matching fsid always returns monotonically increasing directory 168 offset cookies. This includes, if named attributes are supported, 169 directories returned by OPENATTR. 171 4.1.2.1. Rationale 173 If the NFSv4.2 client knows that directory offset cookies in READDIR 174 replies are monotonically increasing, it might make it feasible to 175 implement client side support for directory delegation. As an 176 example, implementing client side directory delegation support is 177 much easier when the directory offset cookies are monotonically 178 increasing, so they can be used to order directory entries. Further, 179 the client needs to know that the directory offset cookies are 180 monotonically increasing before reading a directory, so that 181 acquisition and use of a directory delegation may be done. Client 182 side directory caching may also benefit from monotonically increasing 183 directory offset cookies. For example, the Linux NFSv4.2 client uses 184 a different caching algorithm when directory offset cookies are 185 monotonically increasing. 187 4.1.3. Attribute 85: seek_granularity 189 This attribute indicates the granularity of unallocated regions for 190 data objects with an fsid matching that of the specified object. 191 Data objects include regular files and, when named attributes are 192 supported, named attributes. 194 0, if the SEEK operation will not return unallocated regions (holes). 196 1, if the SEEK operation will return unallocated regions (holes), but 197 of no fixed granularity 199 > 1, if the SEEK operation will return unallocated regions (holes), 200 which are an exact multiple of this attribute in length. 202 If this attribute is supported for a file system that does not 203 support the SEEK operation, a value of 0 MUST be returned. 205 4.1.3.1. Rationale 207 A NFSv4.2 client can avoid performing RPCs doing the SEEK operation 208 when this attribute is equal 0 or whenever the client can determine 209 that holes greater or equal to the value of this attribute do not 210 exist in the file. 212 4.1.4. Attribute 86: mandatory_br_locks 214 TRUE, if byte range locks obtained on data objects with an fsid 215 matching that of the specified object have mandatory semantics 216 potentially affecting IO operations done on overlapping areas. Data 217 objects include regular files and, when named attributes are 218 supported, named attributes. 220 4.1.4.1. Rationale 222 Applications that work with advisory byte range locks will fail with 223 mandatory byte range locks and vice versa. Given that both forms are 224 allowed yet incompatible, it is necessary to provide a way, other 225 than trial-and-error, to determine which form is supported. 227 Further, if a client is doing read/write caching of data blocks using 228 a write back caching policy, the caching requires locking if 229 mandatory byte range locking is being enforced by the server. For 230 this case, the client needs to acquire an exclusive byte range lock 231 for each byte range being cached. If it does not do so, a write-back 232 may fail, due to a conflicting lock having been acquired by a 233 different client. Therefore, a client doing this kind of data block 234 caching needs to know if the server is implementing mandatory byte 235 range locking. 237 4.1.5. Attribute 87: max_xattr_len 239 The maximum length, in bytes, of the extended attribute that can be 240 set by the SETXATTR operation for file system objects with an fsid 241 matching that of the specified object. The SETXATTR operation is 242 described in the [RFC8276] extension to NFSv4.2. 244 If this attribute is supported for a file system that does not 245 support the SETXATTR operation, a value of 0 MUST be returned. 247 4.1.5.1. Rationale 249 This attribute allows a NFSv4.2 client to avoid attempting a SETXATTR 250 operation when the length of the extended attribute is greater than 251 the maximum specified by this attribute. 253 5. Implementation Status 255 This section is to be removed before publishing as an RFC. 257 This section records the status of known implementations of the 258 protocol defined by this specification at the time of posting of this 259 Internet-Draft. The description of implementations in this section 260 is intended to assist the IETF in its decision processes in 261 progressing drafts to RFCs. 263 Please note that the listing of any individual implementation here 264 does not imply endorsement by the IETF. Furthermore, no effort has 265 been spent to verify the information presented here that was supplied 266 by IETF contributors. This is not intended as, and must not be 267 construed to be, a catalog of available implementations or their 268 features. Readers are advised to note that other implementations may 269 exist. 271 5.1. FreeBSD NFS server and client 273 Organization: FreeBSD Project 274 URL: https://www.freebsd.org 276 Maturity: Prototype software based on the current document. 278 Coverage: The bulk of this specification is implemented. 280 Licensing: BSD 282 Implementation experience: The implementation of these attributes 283 have allowed the NFSv4.2 client to avoid unnecessary RPCs 284 against the server. The current client implementation 285 does not include support for directory delegations nor 286 makes use of the dir_cookie_rising attribute. The current 287 client implementation does not support mandatory byte 288 range locking. 290 6. References 292 6.1. Normative References 294 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 295 Requirement Levels", BCP 14, RFC 2119, 296 DOI 10.17487/RFC2119, March 1997, 297 . 299 [RFC7862] Haynes, T., "Network File System (NFS) Version 4 Minor 300 Version 2 Protocol", RFC 7862, DOI 10.17487/RFC7862, 301 November 2016, . 303 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 304 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 305 May 2017, . 307 [RFC8178] Noveck, D., "Rules for NFSv4 Extensions and Minor 308 Versions", RFC 8178, DOI 10.17487/RFC8178, July 2017, 309 . 311 [RFC8276] Naik, M. and M. Eshel, "File System Extended Attributes in 312 NFSv4", RFC 8276, DOI 10.17487/RFC8276, December 2017, 313 . 315 6.2. Informational References 317 [RFC8881] Noveck, D., Ed. and C. Lever, "Network File System (NFS) 318 Version 4 Minor Version 1 Protocol", RFC 8881, 319 DOI 10.17487/RFC8881, August 2020, 320 . 322 Acknowledgments 324 Thanks go to David Noveck for his suggestions for improving the 325 draft. 327 Author's Address 329 Rick Macklem 330 FreeBSD Project 331 Canada 333 Email: rmacklem@uoguelph.ca