idnits 2.17.1 draft-naik-nfsv4-xattrs-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 : ---------------------------------------------------------------------------- ** There are 10 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 231 has weird spacing: '...lthough colle...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: This document does not propose any language to restrict the key names of extended attributes. Future versions, or other related IETF documents, may include additional text to enforce namespace prefix to key names, formalize names of some well-defined xattrs, or impose additional restrictions on the allowed namespaces to user-managed metadata only, in order to prevent the development of non-interoperable implementations. This document, however, does require that the attribute key/value MUST not be interpreted by the NFS clients and servers. -- The document date (July 18, 2014) is 3570 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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: '3' is defined on line 661, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5661 (ref. '2') (Obsoleted by RFC 8881) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NFSv4 Working Group M. Naik 3 Internet Draft M. Eshel 4 Intended Status: Standards Track IBM Almaden 5 Expires: January 19, 2015 July 18, 2014 7 Support for File System Extended Attributes in NFSv4 8 draft-naik-nfsv4-xattrs-01 10 Abstract 12 This document proposes extensions to existing NFSv4 operations to 13 allow file extended attributes (here forth also referred to as 14 xattrs) to be manipulated in the protocol. An xattr is a file system 15 feature that allows opaque metadata, not interpreted by the file 16 system, to be associated with files and directories and are supported 17 by many modern file systems. New file attributes are proposed to 18 allow clients to query the server for xattr support, and new 19 operations to get and set xattrs on file system objects. 21 Status of this Memo 23 This Internet-Draft is submitted to IETF in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF), its areas, and its working groups. Note that 28 other groups may also distribute working documents as 29 Internet-Drafts. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 The list of current Internet-Drafts can be accessed at 37 http://www.ietf.org/1id-abstracts.html 39 The list of Internet-Draft Shadow Directories can be accessed at 40 http://www.ietf.org/shadow.html 42 Copyright and License Notice 44 Copyright (c) 2014 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2 Uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 3 Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 4 Differences with Named Attributes . . . . . . . . . . . . . . . 5 64 5 Protocol Enhancements . . . . . . . . . . . . . . . . . . . . . 6 65 5.1 New Attributes . . . . . . . . . . . . . . . . . . . . . . 6 66 5.1.1 Attribute 82: maxxattrsize . . . . . . . . . . . . . . 7 67 5.1.2 Attribute 83: xattrsize . . . . . . . . . . . . . . . . 7 68 5.2 New Operations . . . . . . . . . . . . . . . . . . . . . . 7 69 5.2.1 New definitions . . . . . . . . . . . . . . . . . . . . 8 70 5.2.2 Caching . . . . . . . . . . . . . . . . . . . . . . . . 9 71 5.2.3 GETXATTR - Get extended attributes of a file . . . . . 9 72 5.2.4 SETXATTR - Set extended attributes for a file . . . . . 11 73 5.2.5 Valid Errors . . . . . . . . . . . . . . . . . . . . . 13 74 5.3 Extensions to ACE Access Mask Attributes . . . . . . . . . 14 75 5.4 pNFS Considerations . . . . . . . . . . . . . . . . . . . . 14 76 6 Security Considerations . . . . . . . . . . . . . . . . . . . . 14 77 7 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 14 78 8 References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 79 8.1 Normative References . . . . . . . . . . . . . . . . . . . 15 80 8.2 Informative References . . . . . . . . . . . . . . . . . . 15 81 9 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 84 1 Introduction 86 Extended attributes, also called xattrs, are a means to associate 87 opaque metadata with file system objects, typically organized in 88 key/value pairs. They are especially useful when they add information 89 that is not, or cannot be, present in the associated object itself. 90 User-space applications can arbitrarily create, read from, and write 91 to the key/value pairs. 93 Extended attributes are file system-agnostic; applications use an 94 interface not specific to any file system to manipulate them. 95 Applications do not need to be concerned about how the key/value 96 pairs are stored internally on the underlying file system. All major 97 operating systems provide various flavors of extended attributes. 98 Many user space tools allow xattrs to be included in attributes that 99 need to be preserved when objects are updated, moved or copied. 101 Extended attributes have long been considered unsuitable for 102 portability because they are inadequately defined and not formally 103 documented by any standard (such as POSIX). However, evidence 104 suggests that xattrs are widely deployed and their support in modern 105 disk-based file systems is fairly universal. 107 There are no clear indications on how xattrs can be mapped to any 108 existing recommended or optional file attributes defined in RFC 5661 109 [2]; thereby most NFS client implementations ignore application- 110 specified xattrs. This results in data loss if one copies, over the 111 NFS protocol, a file with xattrs from one file system to another that 112 also supports xattrs. 114 There is a relatively strong interest in the community in exposing 115 xattrs over NFS despite the shortcomings. 117 This document discusses why the current NFSv4 named attributes as 118 currently standardized in [2], are unsuitable for representing 119 xattrs, and proposes alternate language, adjustment and protocol 120 mechanisms to support them. 122 1.1 Terminology 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 126 document are to be interpreted as described in RFC 2119 [1]. 128 In this document, these words will appear with that interpretation 129 only when in ALL CAPS. Lower case uses of these words are not to be 130 interpreted as carrying RFC-2119 significance. 132 2 Uses 134 Applications can store tracking information in extended attributes. 135 Examples include storing metadata identifying the application that 136 created the file, a tag to indicate when the file was last verified 137 by a data integrity scrubber, or a tag to hold a checksum/crypto hash 138 of the file contents along with the date of that signature. Xattrs 139 can also be used for decorations or annotations. For example, a file 140 downloaded from a web server can be tagged with the URL, which can be 141 convenient if its source has to be determined in the future. 142 Likewise, an email attachment, when saved, can be tagged with the 143 message-id of the email, making it possible to trace the original 144 message. 146 Applications may need to behave differently when handling files of 147 varying types. For example, file managers, such as GNOME's, offer 148 unique icons, different click behavior, and special lists of 149 operations to perform depending on the file format. This can be 150 achieved by looking at the file extension (Windows), or interpret the 151 type by inspecting it (Unix MIME type). Some file managers generate 152 this information on the fly; others generate the information once and 153 then cache it. Those that cache the information tend to put it in a 154 custom database. The file manager must work to keep this database in 155 sync with the files, which can change without the file manager's 156 knowledge. A better approach is to jettison the custom database and 157 store such metadata in extended attributes: these are easier to 158 maintain, faster to access, and readily accessible by any application 159 [5]. 161 On Mac OSX, applications such as Dropbox, Skydrive (Onedrive), and 162 Google Drive use the extended attribute interface to assign specific 163 tags to folders. 165 Xattrs can be retrieved and set through system calls or shell 166 commands and generally supported by user-space tools (such as copy 167 tools) that preserve other file attributes. 169 Extended attributes are supported by many file systems. 171 In Linux, ext3, ext4, JFS, XFS, Btrfs, among other file systems 172 support extended attributes. The getfattr and setfattr utilities can 173 be used to retrieve and set xattrs. The names of the extended 174 attributes must be prefixed by the name of the category and a dot; 175 hence these categories are generally qualified as name spaces. 176 Currently, four namespaces exist: user, trusted, security and system 177 [5]. Recommendations on how they should be used are published by 178 freedesktop.org [4]. 180 FreeBSD supports extended attributes in two universal namespaces - 181 user and system, although individual file systems are allowed to 182 implement additional namespaces [6]. 184 Solaris 9 and later allows files to have extended attributes, but 185 implements them as "forks", logically represented as files within a 186 hidden directory that is associated with the target file [7]. 188 In the NTFS file system, extended attributes are one of several 189 supported "file streams" [8]. 191 3 Namespaces 193 Operating systems may define multiple "namespaces" in which xattrs 194 can be set. Namespaces are more than organizational classes; the 195 operating system may enforce different access policies and allow 196 different capabilities depending on the namespace. Linux, for 197 example, defines "security", "system", "trusted" and "user" 198 namespaces, the first three being specific to Linux [4]. 200 Implementations generally agree on the semantics of a "user" 201 namespace, that allows applications to store arbitrary user attribute 202 data with file system objects. Access to this namespace is controlled 203 via the normal file system attributes. As such, getting and setting 204 xattrs from the user namespace can be considered interoperable across 205 platforms and vendor implementations. Attributes from other 206 namespaces are typically platform-specific, but some of them may be 207 generalized into well-defined set of names that promote interoperable 208 implementations. Similarly, attaching the namespace to the attribute 209 key can avoid conflicting use of attributes. 211 This document does not propose any language to restrict the key names 212 of extended attributes. Future versions, or other related IETF 213 documents, may include additional text to enforce namespace prefix to 214 key names, formalize names of some well-defined xattrs, or impose 215 additional restrictions on the allowed namespaces to user-managed 216 metadata only, in order to prevent the development of non- 217 interoperable implementations. This document, however, does require 218 that the attribute key/value MUST not be interpreted by the NFS 219 clients and servers. 221 4 Differences with Named Attributes 223 RFC5661 defines named attributes as opaque byte streams that are 224 associated with a directory or file and referred to by a string name 225 [2]. Named attributes are intended to be used by client applications 226 as a method to associate application-specific data with a regular 227 file or directory. In that sense, xattrs are similar in concept and 228 use to named attributes, but there are subtle differences. 230 File systems typically define individual xattrs "get" and "set" 231 operations as being atomic, although collectively they may be 232 independent. Xattrs generally have size limits ranging from a few 233 bytes to several kilobytes; the maximum supported size is not 234 universally defined and is usually restricted by the file system. 235 Similar to ACLs, the amount of xattr data exchanged between the 236 client and server for get/set operations can be considered to fit in 237 a single COMPOUND request, bounded by the channel's negotiated 238 maximum size for requests. Named attributes, on the other hand, are 239 unbounded data streams and do not impose atomicity requirements. 241 Individual named attributes are analogous to files, and caching of 242 the data for these needs to be handled just as data caching is for 243 ordinary files following close-to-open semantics. Xattrs, on the 244 other hand, impose caching requirements like other file attributes. 246 Named attributes and xattrs have different semantics and belong to 247 disjoint namespaces. As a result, mapping one to another is, at best, 248 a compromise. 250 While it should be possible to write guidance about how a client can 251 use the named attribute mechanism to act like xattrs, such as carving 252 out some namespace and specifying locking primitives to enforce 253 atomicity constraints on individual get/set operations, this is 254 problematic. A client application trying to use xattrs through named 255 attributes with a server that supported xattrs directly would get a 256 lower level of service, and could fail to cooperate on a local 257 application running on the server unless the server file system 258 defined its own interoperability constraints. File systems that 259 already implement xattrs and named attributes natively would need 260 additional guidance such as reserving named attribute namespace 261 specifically for implementation purposes. 263 5 Protocol Enhancements 265 This section proposes extensions to the NFSv4 protocol operations to 266 allow xattrs to be queried and set by clients. New attributes are 267 added to bitmap4 data type to allow xattr support to be queried. This 268 follows the guidelines specified in [2] with respect to minor 269 versioning. In addition, new operations, namely GETXATTR and 270 SETXATTR, are defined to allow xattr key/value to be queried and 271 set. 273 5.1 New Attributes 275 The following RECOMMENDED attributes are proposed for use with 276 GETATTR. A client can query the server to determine if xattrs are 277 supported, the maximum size of the xattrs that are allowed for a file 278 system object, and the total current size of all the xattrs for a 279 given file system object. 281 A client may ask for any of these attributes to be returned by 282 setting a bit in the GETATTR request but MUST handle the case where 283 the server does not return them. A client may ask for the set of 284 attributes the server supports and SHOULD NOT request attributes the 285 server does not support. 287 +------------------+----+-------------------+-----+----------------+ 288 |Name | Id | Data Type | Acc | Defined in | 289 +------------------+----+-------------------+-----+----------------+ 290 | maxxattrsize | 82 | uint32_t | R | Section 5.1.1 | 291 | xattrsize | 83 | uint32_t | R | Section 5.1.2 | 292 +------------------+----+-------------------+-----+----------------+ 294 5.1.1 Attribute 82: maxxattrsize 296 Maximum size in bytes of all the extended attributes per object that 297 the object's file system supports. If maxxattrsize is 0, the server 298 does not support extended attributes. The protocol does not enforce 299 any limits on the number of keys, the length of a key or the size of 300 a value, that are allowed for a file, as long as the total size is 301 contained by maxxattrsize. The server file system MAY impose 302 additional limits. In addition, the total size of xattrs exchanged 303 between the client and server for get/set operations is limited by 304 the channel's negotiated maximum size for requests and responses. 306 5.1.2 Attribute 83: xattrsize 308 The total size of all the extended attributes of this object in 309 bytes. This MUST be less than or equal to maxxattrsize. 311 5.2 New Operations 313 Unlike other file system attributes, xattrs can represent disparate 314 metadata most file systems allow disparate metadata to be associated 315 with an object through one or more xattrs, and combining them into a 316 single attribute is unwieldy. As such, adding new attributes to 317 bitmap4 for use in GETATTR and SETATTR is inappropriate to support 318 xattr operations. For example, obtaining the value of a single xattr 319 using the bitmap would require a client implementation to read all 320 the xattrs of the file and find a match for the one requested. 321 Similarly, replacing or deleting a single xattr while keeping the 322 others intact would require a client to read the xattrs first, 323 replacing the existing list with a modified list that excludes the 324 one to be deleted, and writing out the remaining xattrs. Moreover, 325 distinguishing between creating new and replacing existing xattrs on 326 an object is not possible with the existing bitmap. 328 Applications need to perform the following operations on a given 329 file's extended attributes [5]: 331 o Given a file, return a list of all of the file's assigned extended 332 attribute keys. 334 o Given a file and a key, return the corresponding value. 336 o Given a file, a key, and a value, assign that value to the key. 338 o Given a file and a key, remove that extended attribute from the 339 file. 341 This section introduces two new operations, GETXATTR and SETXATTR, to 342 query and set xattrs. GETXATTR allows listing all the xattrs names, 343 names with values, or querying the value of a single name. SETXATTR 344 allows deleting a single xattr or replacing a few without modifying 345 the rest. 347 5.2.1 New definitions 349 The NFS xattr structure is defined as follows: 351 typedef utf8str_cis xattrname4; 352 typedef opaque xattrvalue4<>; 354 struct xattr4 { 355 xattrname4 xa_name; 356 xattrvalue4 xa_value; 357 }; 359 Each xattr, defined by xattr4, is a key/value pair. xattrname4 is a 360 UTF-8 string denoting the xattr key name, xattrvalue4 is a variable 361 length string that identifies the values of a specified xattr. The 362 size of the xattr is a combination of the size of its name 363 represented by xattrname4, and its value represented by xattrvalue4. 364 Any regular file or directory may have an array of xattr4, each 365 consisting of a key and associated value. The NFS client or server 366 MUST NOT interpret the contents of xattr4. Similar to ACLs, the 367 client can use the OPEN or ACCESS operations to check access without 368 modifying or reading data or metadata. 370 Future versions of this document or other related IETF documents may 371 define specific values for xattr key names, or mechanisms for 372 encoding namespace in xattrname4. 374 5.2.2 Caching 376 The caching behavior for extended attributes is similar to other file 377 attributes such as ACLs and is affected by whether OPEN delegation 378 has been granted to a client or not. 380 When a delegation is in effect, an operation by a second client to a 381 delegated file will cause the server to recall the delegation through 382 a callback. For individual operations, we will describe, under 383 IMPLEMENTATION, when such operations are required to effect a recall. 384 For GETXATTR, see Section 5.2.3.4. For SETXATTR, see Section 5.2.4.4. 386 When the client does not hold a delegation on the file, xattrs 387 obtained from the server may be cached and clients can use them to 388 avoid subsequent GETXATTR requests. Such caching is write through in 389 that modification to xattrs is always done by means of requests to 390 the server and should not be only done locally. Due to the relative 391 infrequency of xattr updates, it is suggested that all changes be 392 propagated synchronously. The client MUST NOT maintain a cache of 393 modified xattrs. 395 The result of local caching is that the xattrs maintained on 396 individual clients may not be coherent. Changes made in one order on 397 the server may be seen in a different order on one client and in a 398 third order on another client. In order to manage the incoherency 399 caused by separate operations to obtain xattrs and other file 400 attributes, a client should treat xattrs just like other file 401 attributes with respect to caching as detailed in section 10.6 of RFC 402 5661 [2]. A client may validate its cached version of xattrs for a 403 file by fetching both the change and time_access attributes and 404 assuming that if the change attribute has the same value as it did 405 when the attributes were cached, then xattrs have not changed. 407 5.2.3 GETXATTR - Get extended attributes of a file 409 5.2.3.1 ARGUMENTS 411 enum getxattr_type4 { 412 GETXATTR4_LIST = 0, 413 GETXATTR4_ONE = 1, 414 GETXATTR4_ALL = 2 415 }; 416 union getxattr_args4 switch (getxattr_type4 ga_type) { 417 case GETXATTR4_ONE: 418 xattrname4 ga_name; 419 default: 420 void; 421 }; 423 struct GETXATTR4args { 424 /* CURRENT_FH: file */ 425 getxattr_type4 ga_type; 426 getxattr_args4 ga_args; 427 }; 429 5.2.3.2 RESULTS 431 union getxattr_res4 switch (getxattr_type4 gr_type) { 432 case GETXATTR4_LIST: 433 xattrname4 gr_names<>; 434 case GETXATTR4_ONE: 435 xattrvalue4 gr_value; 436 case GETXATTR4_ALL: 437 xattr4 gr_xattrs<>; 438 }; 440 union GETXATTR4res switch (nfsstat4 gr_status) { 441 case NFS4_OK: 442 getxattr_res4 gr_resok4; 443 default: 444 void; 445 }; 447 5.2.3.3 DESCRIPTION 449 The GETXATTR operation will obtain extended attributes for the file 450 system object specified by the current filehandle. The client 451 specifies what kind of xattr information it would like the server to 452 return through the ga_type argument. GETXATTR4_LIST is used to 453 enumerate the set of extended attribute keys assigned to the file. 454 GETXATTR4_ONE returns the value of an extended attribute from the 455 file, given the key. GETXATTR4_ALL returns the key/value pairs for 456 the set of extended attributes assigned to the file. 458 The server MUST return the xattr key and/or value that the client 459 requests if xattrs are supported by the server for the target file 460 system. If the server does not support xattrs on the target file 461 system, then it MUST NOT return key and/or value and MUST return an 462 error. The server also MUST return an error if it supports xattrs on 463 the target but cannot obtain the requested data. In that case, no 464 key/value will be returned. If the xattr keys and/or values contained 465 in the server response will exceed the channel's negotiated maximum 466 response size, then the server MUST return NFS4ERR_REP_TOO_BIG in 467 gr_status. 469 5.2.3.4 IMPLEMENTATION 471 If there is an OPEN_DELEGATE_WRITE delegation held by another client 472 for the file in question, and size and/or change are among the set of 473 attributes being interrogated in GETATTR, the server can either 474 obtain the actual current value of these attributes from the client 475 holding the delegation by using the CB_GETATTR callback, or revoke 476 the delegation. See Section 18.7.4 of RFC 5661 for details [2]. 477 Consequently, if a client needs to verify the list of extended 478 attributes with the server, it must also query the change attribute 479 of the file with GETATTR. This handling is similar to how a client 480 would revalidate other file attributes such as ACLs. 482 5.2.4 SETXATTR - Set extended attributes for a file 484 5.2.4.1 ARGUMENTS 486 enum setxattr_type4 { 487 SETXATTR4_CREATE = 0, 488 SETXATTR4_REPLACE = 1, 489 SETXATTR4_DELETE = 2, 490 SETXATTR4_REPLACE_ALL = 3, 491 SETXATTR4_DELETE_ALL = 4 492 }; 494 union setxattr_args4 switch (setxattr_type4 sa_type) { 495 case SETXATTR4_CREATE: 496 case SETXATTR4_REPLACE: 497 case SETXATTR4_REPLACE_ALL: 498 xattr4 sa_xattrs<>; 499 case SETXATTR4_DELETE: 500 xattrname4 sa_xattrnames<>; 501 case SETXATTR4_DELETE_ALL: 502 void; 503 }; 505 struct SETXATTR4args { 506 /* CURRENT_FH: file */ 507 setxattr_args4 sa_args; 508 }; 510 5.2.4.2 RESULTS 512 union setxattr_res4 switch (setxattr_type4 sr_type) { 513 case SETXATTR4_CREATE: 514 case SETXATTR4_REPLACE: 515 case SETXATTR4_DELETE: 516 nfsstat4 sr_res<>; 517 case SETXATTR4_REPLACE_ALL: 518 case SETXATTR4_DELETE_ALL: 519 void; 520 }; 522 union SETXATTR4res switch (nfsstat4 sr_status) { 523 case NFS4_OK: 524 void; 525 default: 526 setxattr_res4 sr_array; 527 }; 529 5.2.4.3 DESCRIPTION 531 The SETXATTR operation changes one or more of the extended attributes 532 of a file system object. The change desired is specified by sr_type. 533 SETXATTR4_CREATE is used to associate the specified values with the 534 extended attribute keys for the file system object specified by the 535 current filehandle. The server MUST return an error if the attribute 536 key already exists. SETXATTR4_REPLACE is also used to set an xattr, 537 but the server MUST return an error if the attribute key does not 538 exist. An application can delete all existing xattrs for a file and 539 replace them with a new set by using SETXATTR4_REPLACE_ALL. 540 SETXATTR4_DELETE can be used to remove the specified xattr keys, if 541 they exist. SETXATTR4_DELETE_ALL removes all the xattr keys for the 542 file. 544 While the SETXATTR request MAY contain multiple attribute keys and/or 545 values to be changed for a file, this does not impose any atomicity 546 considerations on the server implementation. If the server cannot 547 update all the attributes for the file atomically, it MUST set them 548 in the order specified. In such cases, it is possible that some keys 549 are changed successfully while others encounter errors. To handle 550 this, contained within the SETXATTR results is a "status" field. If 551 any of the change operations incur an error, then the "status" value 552 MUST NOT be NFS4_OK. In this case, the status of the individual 553 change operations is returned in sr_array. If the xattr keys and/or 554 values contained in the client request exceeds the channel's 555 negotiated maximum request size, then the server MUST return 556 NFS4ERR_REQ_TOO_BIG in sr_status. 558 A successful SETXATTR SHOULD change the file time_modify and change 559 attributes. However, these attributes SHOULD NOT be changed unless 560 the xattrs are changed. 562 5.2.4.4 IMPLEMENTATION 564 If the object whose xattrs are being changed has a file delegation 565 that is held by a client other than the one doing the SETXATTR, the 566 delegation(s) must be recalled, and the operation cannot proceed to 567 actually change the xattrs until each such delegation is returned or 568 revoked. In all cases in which delegations are recalled, the server 569 is likely to return one or more NFS4ERR_DELAY errors while the 570 delegation(s) remains outstanding, although it might not do that if 571 the delegations are returned quickly. 573 5.2.5 Valid Errors 575 This section contains a table that gives the valid error returns for 576 each new protocol operation. The error code NFS4_OK (indicating no 577 error) is not listed but should be understood to be returnable by all 578 new operations. The error values for all other operations are 579 defined in Section 15.2 of RFC 5661 [2]. 581 Valid Error Returns for Each New Protocol Operation 583 +----------------------+--------------------------------------------+ 584 | Operation | Errors | 585 +----------------------+--------------------------------------------+ 586 | GETXATTR | NFS4ERR_ACCESS, NFS4ERR_BADXDR, | 587 | | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | 588 | | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | 589 | | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_ISDIR, | 590 | | NFS4ERR_MOVED, NFS4ERR_NAMETOOLONG, | 591 | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTSUPP, | 592 | | NFS4ERR_OP_NOT_IN_SESSION, NFS4ERR_NOTDIR, | 593 | | NFS4ERR_PERM, NFS4ERR_REP_TOO_BIG, | 594 | | NFS4ERR_REP_TOO_BIG_TO_CACHE, | 595 | | NFS4ERR_REQ_TOO_BIG, | 596 | | NFS4ERR_RETRY_UNCACHED_REP, | 597 | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | 598 | | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE | 599 | SETXATTR | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | 600 | | NFS4ERR_ATTRNOTSUPP, NFS4ERR_BADCHAR, | 601 | | NFS4ERR_BADOWNER, NFS4ERR_BAD_RANGE, | 602 | | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, | 603 | | NFS4ERR_DEADSESSION, NFS4ERR_DELAY, | 604 | | NFS4ERR_DELEG_REVOKED, NFS4ERR_DQUOT, | 605 | | NFS4ERR_EXIST, NFS4ERR_EXPIRED, | 606 | | NFS4ERR_FBIG, NFS4ERR_FHEXPIRED, | 607 | | NFS4ERR_GRACE, NFS4ERR_INVAL, NFS4ERR_IO, | 608 | | NFS4ERR_LOCKED, NFS4ERR_MOVED, | 609 | | NFS4ERR_NAMETOOLONG, NFS4ERR_NOFILEHANDLE, | 610 | | NFS4ERR_NOSPC, NFS4ERR_NOTDIR, | 611 | | NFS4ERR_OLD_STATEID, NFS4ERR_OPENMODE, | 612 | | NFS4ERR_OP_NOT_IN_SESSION, NFS4ERR_PERM, | 613 | | NFS4ERR_REP_TOO_BIG, | 614 | | NFS4ERR_REP_TOO_BIG_TO_CACHE, | 615 | | NFS4ERR_REQ_TOO_BIG, | 616 | | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | 617 | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | 618 | | NFS4ERR_TOO_MANY_OPS, | 619 | | NFS4ERR_UNKNOWN_LAYOUTTYPE, | 620 | | NFS4ERR_WRONG_TYPE | 621 +----------------------+--------------------------------------------+ 623 5.3 Extensions to ACE Access Mask Attributes 625 Two new bitmask constants are proposed for the access mask field: 627 const ACE4_GET_XATTRS = 0x00200000; 628 const ACE4_SET_XATTRS = 0x00400000; 630 Permission to get and set the extended attributes of a file. The 631 affected operations are GETXATTR and SETXATTR respectively. No 632 additional granularity of control is implied by these constants for 633 server implementations. 635 5.4 pNFS Considerations 637 Both GETXATTR and SETXATTR are sent to the metadata server, which is 638 responsible for coordinating the changes onto the storage devices. 640 6 Security Considerations 642 The additions to the NFS protocol for supporting extended attributes 643 do not alter the security considerations of the NFSv4.1 protocol [2]. 645 7 IANA Considerations 647 There are no IANA considerations in this document. All NFSv4.1 IANA 648 considerations are covered in [2]. 650 8 References 652 8.1 Normative References 654 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 655 Levels", BCP 14, RFC 2119, March 1997. 657 [2] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., "Network 658 File System (NFS) Version 4 Minor Version 1 Protocol", RFC 5661, 659 January 2010. 661 [3] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., "Network 662 File System (NFS) Version 4 Minor Version 1 External Data 663 Representation Standard (XDR) Description", RFC 5662, January 664 2010. 666 8.2 Informative References 668 [4] http://www.freedesktop.org/wiki/CommonExtendedAttributes, 669 "Guidelines for extended attributes". 671 [5] Love, R., "Linux System Programming: Talking Directly to the 672 Kernel and C Library", O'Reilly Media, Inc., 2007. 674 [6] http://www.freebsd.org/cgi/man.cgi?query=extattr&sektion=9, 675 "FreeBSD Man Pages - extattr" 677 [7] http://docs.oracle.com/cd/E19253-01/816-5175/6mbba7f02, 678 "Oracle Man Pages - fsattr" 680 [8] http://msdn.microsoft.com/en- 681 us/library/windows/desktop/aa364404(v=vs.85).aspx, "File 682 Streams" 684 9 Acknowledgements 686 This draft has attempted to capture the discussion on adding 687 xattrs to the NFSv4 protocol from many participants on the IETF 688 NFSv4 mailing list. Valuable input and advice was received from 689 Tom Haynes on the first revision of this draft. 691 Authors' Addresses 693 Manoj Naik 694 IBM Almaden 695 650 Harry Rd 696 San Jose, CA 95120 698 Phone: +1 408-927-1707 699 Email: mnaik@us.ibm.com 701 Marc Eshel 702 IBM Almaden 703 650 Harry Rd 704 San Jose, CA 95120 706 Phone: +1 408-927-1894 707 Email: eshel@us.ibm.com