--- 1/draft-ietf-nfsv4-xattrs-01.txt 2016-03-08 09:16:09.449137336 -0800 +++ 2/draft-ietf-nfsv4-xattrs-02.txt 2016-03-08 09:16:09.505138712 -0800 @@ -1,18 +1,19 @@ NFSv4 Working Group M. Naik -Internet Draft M. Eshel -Intended Status: Standards Track IBM Almaden -Expires: February 19, 2016 August 18, 2015 +Internet Draft Nutanix +Intended Status: Standards Track M. Eshel +Expires: September 8, 2016 IBM Almaden + March 7, 2016 File System Extended Attributes in NFSv4 - draft-ietf-nfsv4-xattrs-01 + draft-ietf-nfsv4-xattrs-02 Abstract This document proposes extensions to the NFSv4 protocol which allow file extended attributes (hereinafter also referred to as xattrs) to be manipulated using NFSv4. An xattr is a file system feature that allows opaque metadata, not interpreted by the file system, to be associated with files and directories. Such support is present in many modern local file systems. New file attributes are proposed to allow clients to query the server for xattr support, and new @@ -34,84 +35,86 @@ material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/1id-abstracts.html The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html Copyright and License Notice - Copyright (c) 2015 IETF Trust and the persons identified as the + Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3. File System Support . . . . . . . . . . . . . . . . . . . . . 5 - 4. Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 5. Differences from Named Attributes . . . . . . . . . . . . . . 6 - 6. XDR Description . . . . . . . . . . . . . . . . . . . . . . . 7 - 6.1. Code Components Licensing Notice . . . . . . . . . . . . . 7 - 7. Protocol Extensions . . . . . . . . . . . . . . . . . . . . . 9 - 7.1. New definition . . . . . . . . . . . . . . . . . . . . . . 9 - 7.1.1. xattr4 . . . . . . . . . . . . . . . . . . . . . . . . 9 + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 + 2. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 3. File System Support . . . . . . . . . . . . . . . . . . . . . 6 + 4. Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 5. Differences from Named Attributes . . . . . . . . . . . . . . 7 + 6. XDR Description . . . . . . . . . . . . . . . . . . . . . . . 8 + 6.1. Code Components Licensing Notice . . . . . . . . . . . . . 8 + 7. Protocol Extensions . . . . . . . . . . . . . . . . . . . . . 10 + 7.1. New definitions . . . . . . . . . . . . . . . . . . . . . 10 7.2. New Attribute . . . . . . . . . . . . . . . . . . . . . . 10 - 7.2.1. xattr_support . . . . . . . . . . . . . . . . . . . . 10 - 7.3. New Operations . . . . . . . . . . . . . . . . . . . . . . 10 - 7.3.1. GETXATTR - Get an extended attribute of a file . . . . 11 - 7.3.2. SETXATTR - Set an extended attribute of a file . . . . 12 - 7.3.3. LISTXATTR - List extended attributes of a file . . . . 14 - 7.3.4. REMOVEXATTR - Remove an extended attribute of a file . 16 - 7.3.5. Valid Errors . . . . . . . . . . . . . . . . . . . . . 17 - 7.4. Modifications to Existing Operations . . . . . . . . . . . 18 - 7.5. Numeric Values Assigned to Protocol Extensions . . . . . . 20 - 7.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 21 - 7.7. Xattrs and File Locking . . . . . . . . . . . . . . . . . 22 - 7.8. pNFS Considerations . . . . . . . . . . . . . . . . . . . 23 - 8. Security Considerations . . . . . . . . . . . . . . . . . . . 23 - 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 - 10.1. Normative References . . . . . . . . . . . . . . . . . . 24 - 10.2. Informative References . . . . . . . . . . . . . . . . . 24 - Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 25 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 26 + 7.2.1. xattr_support . . . . . . . . . . . . . . . . . . . . 11 + 7.3. New Error Definitions . . . . . . . . . . . . . . . . . . 11 + 7.3.1. NFS4ERR_NOXATTR (Error Code 10095) . . . . . . . . . . 11 + 7.3.2. NFS4ERR_XATTR2BIG (Error Code 10096) . . . . . . . . . 11 + 7.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 11 + 7.4.1. GETXATTR - Get an extended attribute of a file . . . . 12 + 7.4.2. SETXATTR - Set an extended attribute of a file . . . . 14 + 7.4.3. LISTXATTRS - List extended attributes of a file . . . 15 + 7.4.4. REMOVEXATTR - Remove an extended attribute of a file . 17 + 7.4.5. Valid Errors . . . . . . . . . . . . . . . . . . . . . 18 + 7.5. Modifications to Existing Operations . . . . . . . . . . . 19 + 7.6. Numeric Values Assigned to Protocol Extensions . . . . . . 21 + 7.7. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 22 + 7.8. Xattrs and File Locking . . . . . . . . . . . . . . . . . 24 + 7.9. pNFS Considerations . . . . . . . . . . . . . . . . . . . 24 + 8. Security Considerations . . . . . . . . . . . . . . . . . . . 25 + 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 26 + 10.2. Informative References . . . . . . . . . . . . . . . . . 26 + Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 27 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 28 1. Introduction Extended attributes, also called xattrs, are a means to associate opaque metadata with file system objects, typically organized in key/value pairs. They are especially useful when they add information that is not, or cannot be, present in the associated object itself. User-space applications can arbitrarily create, - interrogate, and modify to the key/value pairs. + interrogate, and modify the key/value pairs. Extended attributes are file system-agnostic; applications use an interface not specific to any file system to manipulate them. Applications do not need to be concerned about how the key/value pairs are stored internally within the underlying file system. All major operating systems provide various flavors of extended attributes. Many user space tools allow xattrs to be included in - attributes that need to be preserved when objects are updated, moved - or copied. + regular attributes that need to be preserved when objects are + updated, moved or copied. Extended attributes have previously been considered unsuitable for portable use because some aspects of their handling are not precisely defined and they are not formally documented by any standard (such as POSIX). Nevertheless, it appears that xattrs are widely deployed and their support in modern disk-based file systems is nearly universal. There is no clear specification of how xattrs could be mapped to any existing file attributes defined in the NFSv4 protocol ([RFC7530], [RFC5661], [NFSv42]). As a result, most NFSv4 client implementations @@ -188,39 +191,40 @@ 3. File System Support Extended attributes are supported by most modern file systems. In Linux, ext3, ext4, JFS, XFS, Btrfs, among other file systems, support extended attributes. The getfattr and setfattr utilities can be used to retrieve and set xattrs. The names of the extended attributes must be prefixed by the name of the category and a dot; hence these categories are generally qualified as name spaces. Currently, four namespaces exist: user, trusted, security and system - [Love]. Recommendations on how they should be used have been + [Linux]. Recommendations on how they should be used have been published [freedesktop]. FreeBSD supports extended attributes in two universal namespaces - user and system, although individual file systems are allowed to implement additional namespaces [FreeBSD]. Solaris 9 and later allows files to have extended attributes, but implements them as "forks", logically represented as files within a hidden directory that is associated with the target file [fsattr]. In the NTFS file system, extended attributes are one of several supported "file streams" [NTFS]. Xattrs can be retrieved and set through system calls or shell - commands and generally supported by user-space tools that preserve - other file attributes. For example, the "rsync" remote copy program - will correctly preserve user extended attributes between Linux/ext4 - and OSX/hfs by stripping off the Linux-specific "user." prefix. + commands and are generally supported by user-space tools that + preserve other file attributes. For example, the "rsync" remote copy + program will correctly preserve user extended attributes between + Linux/ext4 and OSX/hfs by stripping off the Linux-specific "user." + prefix. 4. Namespaces Operating systems may define multiple "namespaces" in which xattrs can be set. Namespaces are more than organizational classes; the operating system may enforce different access policies and allow different capabilities depending on the namespace. Linux, for example, defines "security", "system", "trusted" and "user" namespaces, the first three being specific to Linux [freedesktop]. @@ -392,47 +396,38 @@ New operations are defined to allow xattr keys and values to be queried and set. In addition, new bitmask constants are added to the ACE access mask field to validate permissions to query and modify xattrs. These changes follow applicable guidelines for valid NFSv4 protocol extension, whether the extensions occur in a minor version (as specified in [RFC5661]) or as an extension to an existing minor version (as specified in [NFSv4-vers]). -7.1. New definition - -7.1.1. xattr4 - - The NFSv4 xattr4 structure is defined as follows: +7.1. New definitions - /// typedef component4 xattrname4; + /// typedef component4 xattrkey4; /// typedef opaque xattrvalue4<>; - /// struct xattr4 { - /// xattrname4 xa_name; - /// xattrvalue4 xa_value; - /// }; - - Each xattr, defined by xattr4, is a key/value pair. An xattr4 - consists of an xattrname4 which is a string denoting the xattr key - name, and an attrvalue4 which is a variable-length string that - identifies the value of the xattr. The handling of xattrname4 with - regard to internationalization-related issues is the same as that for - NFSv4 file names and named attribute names, as described in - [RFC7530]. Any regular file or directory may have set of extended + Each xattr is a key/value pair. xattrkey4 is a string denoting the + xattr key name, and an attrvalue4 which is a variable-length string + that identifies the value of the xattr. The handling of xattrkey4 + with regard to internationalization-related issues is the same as + that for NFSv4 file names and named attribute names, as described in + [RFC7530]. Any regular file or directory may have a set of extended attributes, each consisting of a key and associated value. The NFS - client or server MUST NOT interpret the contents of xattr4. + client or server MUST NOT interpret the contents of xattrkey4 or + xattrvalue4. 7.2. New Attribute The following RECOMMENDED per-fs read-only attribute is proposed for use. A client can query the server to determine if xattrs are supported by setting the xattr_support bit in the GETATTR request. 7.2.1. xattr_support True, if the object's file system supports extended attributes. @@ -443,21 +438,43 @@ does not provide xattr support and act on that basis. Note that the protocol does not enforce any limits on the number of keys, the length of a key or the size of a value, or the total size of xattrs that are allowed for a file. The server file system MAY impose additional limits. In addition, a single xattr key or value exchanged between the client and server for get/set operations is limited by the channel's negotiated maximum size for requests and responses. -7.3. New Operations +7.3. New Error Definitions + + + + /// /* Following lines are to be added to enum nfsstat4 */ + /// /* + /// NFS4ERR_NOXATTR = 10095 /* xattr does not exist */ + /// NFS4ERR_XATTR2BIG = 10096 /* xattr value is too big */ + /// */ + + + +7.3.1. NFS4ERR_NOXATTR (Error Code 10095) + + The specified xattr does not exist or the server is unable to + retrieve it. + +7.3.2. NFS4ERR_XATTR2BIG (Error Code 10096) + + The size of the xattr value as part of a SETXATTR operation is bigger + than that supported by the underlying file system. + +7.4. New Operations Individual xattrs generally represent separate items of metadata. For various reasons, combining them into a single attribute results in clumsy implementations with significant functional deficits. In consequence, adding a new attribute to represent the set of xattrs for an object is not an appropriate way to provide support for xattrs. For example, obtaining the value of a single xattr using the bitmap would require a client implementation to read all the xattrs of the @@ -479,314 +496,304 @@ attribute keys. o Given a file and a key, return the corresponding value. o Given a file, a key, and a value, assign that value to the key. o Given a file and a key, remove that extended attribute from the file. This section introduces four new RECOMMENDED operations, GETXATTR, - SETXATTR, LISTXATTR and REMOVEXATTR, to query, set, list and remove - xattrs respectively. GETXATTR allows obtaining the value of an xattr - key, SETXATTR allows creating or replacing an xattr key with a value, - LISTXATTR enumerates all the xattrs names, and REMOVEXATTR allows - deleting a single xattr. + SETXATTR, LISTXATTRS and REMOVEXATTR, to query, set, list and remove + xattrs respectively. A server MUST support all four operations if it + supports the xattr_support attribute. GETXATTR allows obtaining the + value of an xattr key, SETXATTR allows creating or replacing an xattr + key with a value, LISTXATTRS enumerates all the xattrs names, and + REMOVEXATTR allows deleting a single xattr. -7.3.1. GETXATTR - Get an extended attribute of a file +7.4.1. GETXATTR - Get an extended attribute of a file -7.3.1.1. ARGUMENTS +7.4.1.1. ARGUMENTS /// struct GETXATTR4args { /// /* CURRENT_FH: file */ - /// xattrname4 ga_name; + /// xattrkey4 gxa_name; /// }; -7.3.1.2. RESULTS +7.4.1.2. RESULTS - /// union GETXATTR4res switch (nfsstat4 gr_status) { + /// union GETXATTR4res switch (nfsstat4 gxr_status) { /// case NFS4_OK: - /// xattrvalue4 gr_value; + /// xattrvalue4 gxr_value; /// default: /// void; /// }; -7.3.1.3. DESCRIPTION +7.4.1.3. DESCRIPTION The GETXATTR operation will obtain the value for the given extended attribute key for the file system object specified by the current filehandle. The server will fetch the xattr value for the key that the client requests if xattrs are supported by the server for the target file system. If the server does not support xattrs on the target file - system, then it MUST NOT return a value and MUST return an error. - The server also MUST return an error if it supports xattrs on the - target but cannot obtain the requested data. In that case, no value - will be returned. If the xattr value contained in the server - response is such as to cause the channel's negotiated maximum - response size to be exceeded, then the server MUST return - NFS4ERR_REP_TOO_BIG in gr_status. + system, then it MUST NOT return a value and MUST return the + NFS4ERR_NOTSUPP error. The server also MUST return NFS4ERR_NOXATTR + if it supports xattrs on the target but cannot obtain the requested + data. If the xattr value contained in the server response is such as + to cause the channel's negotiated maximum response size to be + exceeded, then the server MUST return NFS4ERR_REP_TOO_BIG in + gxr_status. -7.3.1.4. IMPLEMENTATION +7.4.1.4. IMPLEMENTATION Clients that have cached an xattr may avoid the need to do a GETXATTR by determining if the change attribute is the same as it was when the xattr was fetched. If the client does not hold a delegation for the file in question, it can do so with a GETATTR request to obtain the change attribute and comparing its value to the change attribute value fetched when the xattr value was obtained. This handling is similar to how a client would revalidate other file attributes such as ACLs. When responding to such a GETATTR, the server will, if there is an OPEN_DELEGATE_WRITE delegation held by another client for the file in question, either obtain the actual current value of these attributes from the client holding the delegation by using the CB_GETATTR callback, or revoke the delegation. See Section 18.7.4 of [RFC5661] for details. -7.3.2. SETXATTR - Set an extended attribute of a file +7.4.2. SETXATTR - Set an extended attribute of a file -7.3.2.1. ARGUMENTS +7.4.2.1. ARGUMENTS - /// enum setxattr_type4 { - /// SETXATTR4_CREATE = 0, - /// SETXATTR4_REPLACE = 1, + /// enum setxattr_option4 { + /// SETXATTR4_NONE = 0, + /// SETXATTR4_CREATE = 1, + /// SETXATTR4_REPLACE = 2, /// }; + /// struct SETXATTR4args { /// /* CURRENT_FH: file */ - /// setxattr_type4 sa_type; - /// xattr4 sa_xattr; + /// setxattr_option4 sxa_option; + /// xattrkey4 sxa_key; + /// xattrvalue4 sxa_value; /// }; -7.3.2.2. RESULTS +7.4.2.2. RESULTS - /// struct SETXATTR4res switch (nfsstat4 sr_status) { + /// struct SETXATTR4res switch (nfsstat4 sxr_status) { /// case NFS4_OK: - /// change_info4 sr_info; + /// change_info4 sxr_info; /// default: /// void; /// }; -7.3.2.3. DESCRIPTION +7.4.2.3. DESCRIPTION The SETXATTR operation changes one extended attribute of a file - system object. The change desired is specified by sa_type. + system object. The change desired is specified by sxa_option. SETXATTR4_CREATE is used to associate the given value with the given extended attribute key for the file system object specified by the - current filehandle. The server MUST return an error if the attribute - key already exists. SETXATTR4_REPLACE is also used to set an xattr, - but the server MUST return an error if the attribute key does not - exist. + current filehandle. The server MUST return NFS4ERR_EXIST if the + attribute key already exists. SETXATTR4_REPLACE is also used to set + an xattr, but the server MUST return NFS4ERR_NOXATTR if the attribute + key does not exist. By default (SETXATTR4_NONE), the extended + attribute will be created if need be, or its value will be replaced + if the attribute exists. If the xattr key and value contained in the client request are such that the request would exceed the channel's negotiated maximum request size, then the server MUST return NFS4ERR_REQ_TOO_BIG in - sr_status. If the server file system imposes additional limits on - the size of key name or value, it MAY return NFS4ERR_NAMETOOLONG. + sxr_status. If the server file system imposes additional limits on + the size of key name or value, it MAY return NFS4ERR_XATTR2BIG. - A successful SETXATTR MUST change the file time_modify and change + A successful SETXATTR MUST change the file time_metadata and change attributes if the xattr is created or the value assigned to xattr changes. However, these attributes SHOULD NOT be changed if this causes no actual change in the xattr value. On success, the server returns the change_info4 information in - sr_info. With the atomic field of the change_info4 data type, the + sxr_info. With the atomic field of the change_info4 data type, the server will indicate if the before and after change attributes were obtained atomically with respect to the SETXATTR operation. This allows the client to determine if its cached xattrs are still valid after the operation. See Section 7.6 for a discussion on xattr caching. -7.3.2.4. IMPLEMENTATION +7.4.2.4. IMPLEMENTATION If the object whose xattr is being changed has a file delegation that is held by a client other than the one doing the SETXATTR, the delegation(s) must be recalled, and the operation cannot proceed to actually change the xattr until each such delegation is returned or revoked. In all cases in which delegations are recalled, the server is likely to return one or more NFS4ERR_DELAY errors while the delegation(s) remains outstanding, although it might not do that if the delegations are returned quickly. -7.3.3. LISTXATTR - List extended attributes of a file +7.4.3. LISTXATTRS - List extended attributes of a file -7.3.3.1. ARGUMENTS +7.4.3.1. ARGUMENTS - /// struct LISTXATTR4args { + /// struct LISTXATTRS4args { /// /* CURRENT_FH: file */ - /// nfs_cookie4 la_cookie; - /// verifier4 la_cookieverf; - /// count4 la_maxcount; + /// nfs_cookie4 lxa_cookie; + /// verifier4 lxa_cookieverf; + /// count4 lxa_maxcount; /// }; -7.3.3.2. RESULTS - +7.4.3.2. RESULTS - /// struct LISTXATTR4resok ( - /// nfs_cookie4 lr_cookie; - /// verifier4 lr_cookieverf; - /// bool lr_eof; - /// xattrname4 lr_names<>; + /// struct LISTXATTRS4resok { + /// nfs_cookie4 lxr_cookie; + /// verifier4 lxr_cookieverf; + /// xattrkey4 lxr_names<>; + /// bool lxr_eof; /// }; - /// union LISTXATTR4res switch (nfsstat4 lr_status) { + /// union LISTXATTRS4res switch (nfsstat4 lxr_status) { /// case NFS4_OK: - /// LISTXATTR4resok lr_value; + /// LISTXATTRS4resok lxr_value; /// default: /// void; /// }; -7.3.3.3. DESCRIPTION +7.4.3.3. DESCRIPTION - The LISTXATTR operation retrieves a variable number of extended + The LISTXATTRS operation retrieves a variable number of extended attribute keys from the file system object specified by the current filehandle, along with information to allow the client to request - additional attribute keys in a subsequent LISTXATTR. + additional attribute keys in a subsequent LISTXATTRS. The arguments contain a cookie value that represents where the - LISTXATTR should start within the list of xattrs. A value of 0 - (zero) for la_cookie is used to start reading at the beginning of the - list. For subsequent LISTXATTR requests, the client specifies a - cookie value that is provided by the server on a previous LISTXATTR + LISTXATTRS should start within the list of xattrs. A value of 0 + (zero) for lxa_cookie is used to start reading at the beginning of + the list. For subsequent LISTXATTRS requests, the client specifies a + cookie value that is provided by the server on a previous LISTXATTRS request. - The la_cookieverf value should be set to 0 (zero) when the la_cookie - value is 0 (zero) (first xattr read). On subsequent requests, it - should be lr_cookieverf as returned by the server. The la_cookieverf - must match that returned by the LISTXATTR in which the cookie was - acquired. If the server determines that the la_cookieverf is no - longer valid for the directory, the error NFS4ERR_NOT_SAME must be - returned. + The lxa_cookieverf value should be set to 0 (zero) when the + lxa_cookie value is 0 (zero) (first xattr read). On subsequent + requests, it should be lxr_cookieverf as returned by the server. The + lxa_cookieverf must match that returned by the LISTXATTRS in which + the cookie was acquired. If the server determines that the + lxa_cookieverf is no longer valid for the list, the error + NFS4ERR_NOT_SAME must be returned. - The la_maxcount value of the argument is the maximum number of bytes + The lxa_maxcount value of the argument is the maximum number of bytes for the result. This maximum size represents all of the data being - returned within the LISTXATTR4resok structure and includes the XDR + returned within the LISTXATTRS4resok structure and includes the XDR overhead. The server may return less data. If the server is unable to return a single xattr name within the maxcount limit, the error NFS4ERR_TOOSMALL will be returned to the client. On successful return, the server's response will provide a list of - extended attribute keys. The "lr_eof" flag has a value of TRUE if + extended attribute keys. The "lxr_eof" flag has a value of TRUE if there are no more keys for the object. The cookie value is only meaningful to the server and is used as a "bookmark" for the xattr key. As mentioned, this cookie is used by - the client for subsequent LISTXATTR operations so that it may + the client for subsequent LISTXATTRS operations so that it may continue listing keys. The cookie is similar in concept to a READDIR cookie or the READ offset but should not be interpreted as such by - the client. Ideally, the cookie value should not change if the - object xattr values is modified since the client may be caching these - values. + the client. On success, the current filehandle retains its value. -7.3.3.4. IMPLEMENTATION - - The handling of ls_cookie and ls_cookieverf is similar to that of the - READDIR operation. The cookieverf may be used by the server to help - manage cookie values that may become stale. It should be a rare - occurrence that a server is unable to continue properly listing - xattrs with the provided cookie/cookieverf pair. The server should - make every effort to avoid this condition since the application at - the client may not be able to properly handle this type of failure. +7.4.3.4. IMPLEMENTATION - The use of the ls_cookieverf will also protect the client from using - LISTXATTR cookie values that may be stale. For example, if the file - system has been migrated, the server may or may not be able to use - the same cookie values to service LISTXATTR as the previous server - used. With the client providing the ls_cookieverf, the server is - able to provide the appropriate response to the client. This - prevents the case where the server may accept a cookie value but the - underlying object xattrs have changed and the response is invalid - from the client's context of its previous LISTXATTR. + The handling of cookie/verifier is similar to that of the READDIR + operation. The verifier may be used by the server to help manage + cookie values that may become stale. It should be a rare occurrence + that a server is unable to continue properly listing xattrs with the + provided cookie/verifier pair. The server should make every effort + to avoid this condition since the application at the client may not + be able to properly handle this type of failure. -7.3.4. REMOVEXATTR - Remove an extended attribute of a file +7.4.4. REMOVEXATTR - Remove an extended attribute of a file -7.3.4.1. ARGUMENTS +7.4.4.1. ARGUMENTS /// struct REMOVEXATTR4args { /// /* CURRENT_FH: file */ - /// xattrname4 ra_name; + /// xattrkey4 rxa_name; /// }; -7.3.4.2. RESULTS +7.4.4.2. RESULTS - /// struct REMOVEXATTR4res switch (nfsstat4 rr_status) { + /// struct REMOVEXATTR4res switch (nfsstat4 rxr_status) { /// case NFS4_OK: - /// change_info4 rr_info; + /// change_info4 rxr_info; /// default: /// void; /// }; -7.3.4.3. DESCRIPTION +7.4.4.3. DESCRIPTION The REMOVEXATTR operation deletes one extended attribute of a file - system object specified by ra_name. The server MUST return an error - if the attribute key does not exist. If the xattr key contained in - the client request exceeds the channel's negotiated maximum request - size, then the server MUST return NFS4ERR_REQ_TOO_BIG in rr_status. + system object specified by rxa_name. The server MUST return + NFS4ERR_NOXATTR if the attribute key does not exist. - A successful REMOVEXATTR SHOULD change the file time_modify and - change attributes. However, these attributes SHOULD NOT be changed - unless the xattr is not removed. + A successful REMOVEXATTR SHOULD change the file time_metadata and + change attributes. Similar to SETXATTR, the server communicates the value of the change attribute immediately prior to, and immediately following, a - successful REMOVEXATTR operation in rr_info. This allows the client + successful REMOVEXATTR operation in rxr_info. This allows the client to determine if its cached xattrs are still valid after the operation. See Section 7.6 for a discussion on xattr caching. -7.3.4.4. IMPLEMENTATION +7.4.4.4. IMPLEMENTATION If the object whose xattr is being removed has a file delegation that is held by a client other than the one doing the REMOVEXATTR, the delegation(s) must be recalled, and the operation cannot proceed to delete the xattr until each such delegation is returned or revoked. In all cases in which delegations are recalled, the server is likely to return one or more NFS4ERR_DELAY errors while the delegation(s) remains outstanding, although it might not do that if the delegations are returned quickly. -7.3.5. Valid Errors +7.4.5. Valid Errors This section contains a table that gives the valid error returns for each new protocol operation. The error code NFS4_OK (indicating no error) is not listed but should be understood to be returnable by all new operations. The error values for all other operations are defined in Section 13.2 of [RFC7530]. Valid Error Returns for Each New Protocol Operation +----------------------+--------------------------------------------+ @@ -810,21 +817,21 @@ | | NFS4ERR_EXIST, NFS4ERR_FHEXPIRED, | | | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | | | NFS4ERR_NAMETOOLONG, NFS4ERR_NOFILEHANDLE, | | | NFS4ERR_NOSPC, NFS4ERR_OP_NOT_IN_SESSION, | | | NFS4ERR_PERM, NFS4ERR_REP_TOO_BIG, | | | NFS4ERR_REP_TOO_BIG_TO_CACHE, | | | NFS4ERR_REQ_TOO_BIG, | | | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | | | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE | - | LISTXATTR | NFS4ERR_ACCESS, NFS4ERR_DEADSESSION, | + | LISTXATTRS | NFS4ERR_ACCESS, NFS4ERR_DEADSESSION, | | | NFS4ERR_DELAY, NFS4ERR_INVAL, NFS4ERR_IO, | | | NFS4ERR_MOVED, NFS4ERR_NAMETOOLONG, | | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOTSUPP, | | | NFS4ERR_OP_NOT_IN_SESSION, | | | NFS4ERR_PERM, NFS4ERR_REP_TOO_BIG, | | | NFS4ERR_REP_TOO_BIG_TO_CACHE, | | | NFS4ERR_REQ_TOO_BIG, | | | NFS4ERR_RETRY_UNCACHED_REP, | | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | | | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE | @@ -835,93 +842,106 @@ | | NFS4ERR_LOCKED, NFS4ERR_MOVED, | | | NFS4ERR_NAMETOOLONG, NFS4ERR_NOFILEHANDLE, | | | NFS4ERR_NOSPC, NFS4ERR_OLD_STATEID, | | | NFS4ERR_OPENMODE, | | | NFS4ERR_OP_NOT_IN_SESSION, NFS4ERR_PERM, | | | NFS4ERR_RETRY_UNCACHED_REP, NFS4ERR_ROFS, | | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | | | NFS4ERR_TOO_MANY_OPS, NFS4ERR_WRONG_TYPE | +----------------------+--------------------------------------------+ -7.4. Modifications to Existing Operations +7.5. Modifications to Existing Operations In order to provide fine-grained access control to query or modify extended attributes, additions are proposed to the set of access rights that can be checked to determine if the client is permitted to perform the xattr operation. Note that in general, as explained in Section 18.1.4 of [RFC5661], a client cannot reliably perform an access check with only current file attributes and must verify access with the server. This section extends the semantics of the ACCESS operation documented - in Section 18.1 of [RFC5661]. Two new access permissions can be + in Section 18.1 of [RFC5661]. Three new access permissions can be requested: - ACCESS4_XAREAD Query a file or directory for its xattr key and/or - value. + ACCESS4_XAREAD Query a file or directory for its xattr value + given a key. ACCESS4_XAWRITE Modify xattr keys and/or values of a file or directory. + ACCESS4_XALIST Query a file or directory to list its xattr keys. + As with the existing access permissions, the results of ACCESS are advisory in nature, with no implication that such access will be allowed or denied in the future. In addition, two new bitmask constants used for the access mask field are added: ACE4_READ_XATTRS Permission to interrogate the extended attributes - of a file with GETXATTR or LISTXATTR. + of a file with GETXATTR. ACE4_WRITE_XATTRS Permission to change the extended attributes of a file with SETXATTR or REMOVEXATTR. + ACE4_LIST_XATTRS Permission to list the extended attributes of a + file with LISTXATTRS. + The rules for the client and server follow: o If the client is sending ACCESS in order to determine if the user - can read an xattr of the file with GETXATTR or list the xattr keys - of the file with LISTXATTR, the client SHOULD set ACCESS4_XAREAD - in the request's access field. + can read an xattr of the file with GETXATTR, the client SHOULD set + ACCESS4_XAREAD in the request's access field. o If the client is sending ACCESS in order to determine if the user can modify an xattr of the file with SETXATTR or REMOVEXATTR, the client SHOULD set ACCESS4_XAWRITE in the request's access field. - o If the server supports ACE4_READ_XATTRS permission bit, it MUST - only check for it in the mode, acl, and dacl attributes when it - receives an ACCESS request with ACCESS4_XAREAD set in the access - field. + o If the client is sending ACCESS in order to determine if the user + can list the xattr keys of the file with LISTXATTRS, the client + SHOULD set ACCESS4_XALIST in the request's access field. - o If the server supports ACE4_WRITE_XATTRS permission bit, it MUST - only check for it in the mode, acl, and dacl attributes when it - receives an ACCESS request with ACCESS4_XAWRITE set in the access - field. + o If the server supports the ACE4_READ_XATTRS permission bit, it + MUST only check for it in the mode, acl, and dacl attributes when + it receives an ACCESS request with ACCESS4_XAREAD set in the + access field. + + o If the server supports the ACE4_WRITE_XATTRS permission bit, it + MUST only check for it in the mode, acl, and dacl attributes when + it receives an ACCESS request with ACCESS4_XAWRITE set in the + access field. + + o If the server supports the ACE4_LIST_XATTRS permission bit, it + MUST only check for it in the mode, acl, and dacl attributes when + it receives an ACCESS request with ACCESS4_XALIST set in the + access field. Server implementations need not provide the granularity of control that is implied by this list of masks. For example, POSIX-based systems might not distinguish ACE4_XAREAD from ACE4_READ_ATTRIBUTES (or ACE4_READ_DATA); both masks would be tied to a single "stat" (or "read") permission. When such a server returns attributes to the client, it would show both ACE4_READ_ATTRIBUTES (or ACE4_READ_DATA) and ACE4_XAREAD if and only if the stat (or read) permission is enabled. If a server receives a SETXATTR request that it cannot accurately implement, it should err in the direction of more restricted access. - For example, suppose a server cannot distinguish modifying attributes - from updating xattr. If a client submits an ALLOW ACE where - ACE4_WRITE_ATTRIBUTES is set but ACE4_WRITE_XATTR is not (or vice - versa), the server should either turn off ACE4_WRITE_ATTRIBUTES or - reject the request with NFS4ERR_ATTRNOTSUPP. + For example, suppose a server supports xattrs, but cannot distinguish + modifying attributes from updating xattr. If a client submits an + ALLOW ACE where ACE4_WRITE_ATTRIBUTES is set but ACE4_WRITE_XATTR is + not (or vice versa), the server should either turn off + ACE4_WRITE_ATTRIBUTES or reject the request with NFS4ERR_ATTRNOTSUPP. -7.5. Numeric Values Assigned to Protocol Extensions +7.6. Numeric Values Assigned to Protocol Extensions This section lists the numeric values assigned new attributes and operations to implement the xattr feature. To avoid inconsistent assignments, these have been checked against the most recent protocol version [RFC5661], the current minor version [NFSv42], and all extensions currently approved as working group documents. Development of interoperable prototypes should be possible using these values, although it is possible that these values may be modified before eventual publication as a standard-track document. @@ -919,32 +939,33 @@ This section lists the numeric values assigned new attributes and operations to implement the xattr feature. To avoid inconsistent assignments, these have been checked against the most recent protocol version [RFC5661], the current minor version [NFSv42], and all extensions currently approved as working group documents. Development of interoperable prototypes should be possible using these values, although it is possible that these values may be modified before eventual publication as a standard-track document. - /// /* /// * ACCESS - Check Access Rights /// */ /// const ACCESS4_XAREAD = 0x00000040; /// const ACCESS4_XAWRITE = 0x00000080; + /// const ACCESS4_XALIST = 0x00000100; /// /* - /// * ACE flag values + /// * ACE mask values /// */ /// const ACE4_READ_XATTRS = 0x00200000; /// const ACE4_WRITE_XATTRS = 0x00400000; + /// const ACE4_LIST_XATTRS = 0x00800000; /// /* /// * New NFSv4 attribute /// */ /// typedef bool fattr4_xattr_support; /// /* /// * New RECOMMENDED Attribute /// */ /// const FATTR4_XATTR_SUPPORT = 81; @@ -941,34 +962,35 @@ /// /* /// * New NFSv4 attribute /// */ /// typedef bool fattr4_xattr_support; /// /* /// * New RECOMMENDED Attribute /// */ /// const FATTR4_XATTR_SUPPORT = 81; + /// /* /// * New NFSv4 operations /// */ /// /* Following lines are to be added to enum nfs_opnum4 */ /// /* /// OP_GETXATTR = 72, /// OP_SETXATTR = 73, - /// OP_LISTXATTR = 74, + /// OP_LISTXATTRS = 74, /// OP_REMOVEXATTR = 75, /// */ -7.6. Caching +7.7. Caching The caching behavior for extended attributes is similar to other file attributes such as ACLs and is affected by whether OPEN delegation has been granted to a client or not. Xattrs obtained from, or sent to, the server may be cached and clients can use them to avoid subsequent GETXATTR requests, provided that the client can ensure that the cached value has not been subsequently modified by another client. Such assurance can depend on the client holding a delegation for the file in question or the @@ -1034,40 +1056,40 @@ values atomically with respect to the xattr update operation, the server must indicate that fact in the change_info4 return value. When the information is not atomically reported, the client should not assume that other clients have not changed the xattrs. The protocol does not provide support for write-back caching of xattrs. As such, all modifications to xattrs should be done by requests to the server. The server should perform such updates synchronously. -7.7. Xattrs and File Locking +7.8. Xattrs and File Locking Xattr operations, for the most part, function independent of operations related to file locking state. For example, xattrs can be interrogated and modified without a corresponding OPEN operation. The server does not need to check for locks that conflict with xattr access or modify operations. For example, another OPEN specified with OPEN4_SHARE_DENY_READ or OPEN4_SHARE_DENY_BOTH does not prevent access to or modification of xattrs. Note that the server MUST still verify that the client is allowed to perform the xattr operation on the basis of ACE access permissions. However, the presence of delegations may dictate how xattr operations interact with the state-related logic. Xattrs cannot be modified when a delegation for the corresponding file is held by another client. On the other hand, xattrs can be interrogated despite the holding of a write delegation by another client since updates are write-through to the server. -7.8. pNFS Considerations +7.9. pNFS Considerations All xattr operations are sent to the metadata server, which is responsible for fetching data from and effecting necessary changes to persistent storage. 8. Security Considerations Since xattrs are application data, security issues are exactly the same as those relating to the storing of file data and named attributes. These are all various sorts of application data and the @@ -1110,45 +1132,48 @@ "Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description", RFC 5662, DOI 10.17487/RFC5662, January 2010, . [RFC7530] Haynes, T. and D. Noveck, "Network File System (NFS) Version 4 Protocol", RFC 7530, March 2015. 10.2. Informative References - [NFSv42] Haynes, T., Ed., "NFS Version 4 Minor Version 2", April - 2015, . + [NFSv42] Haynes, T., Ed., "NFS Version 4 Minor Version 2", January + 2016, . Work in progress. [NFSv42-dot-x] Haynes, T., Ed., "NFS Version 4 Minor Version 2 Protocol External Data Representation Standard (XDR) Description", - April 2015, . + January 2016, . Work in progress. [NFSv4-vers] - Haynes, T. and D. Noveck, "NFSv4 Version Management", July - 2015, . + D. Noveck, "NFSv4 Version Management", January 2016, + . Work in progress. [freedesktop] "Guidelines for extended attributes", . + [Linux] "Linux Programmer's Manual: xattr(7)", + . + [Love] Love, R., "Linux System Programming: Talking Directly to the Kernel and C Library", O'Reilly Media, Inc., 2007. [FreeBSD] "FreeBSD Man Pages - extattr", . [fsattr] "Oracle Man Pages - fsattr", . [NTFS] "File Streams", . Appendix A. Acknowledgements This draft has attempted to capture the discussion on adding xattrs to the NFSv4 protocol from many participants on the IETF NFSv4 mailing list. Those who provided valuable input and comments on earlier revisions of this draft include: Tom Haynes, Christoph - Hellwig and Nico Williams. Dave Noveck provided a comprehensive - review of the previous revision of this draft. + Hellwig, Nico Williams, Dave Noveck, Benny Halevy and Andreas + Gruenbacher. Authors' Addresses Manoj Naik - IBM Almaden - 650 Harry Rd - San Jose, CA 95120 - - Phone: +1 408-927-1707 - Email: mnaik@us.ibm.com + Nutanix + 1740 Technology Drive, Suite 150, + San Jose, CA 95110 + Email: manoj.naik@nutanix.com Marc Eshel IBM Almaden 650 Harry Rd San Jose, CA 95120 - Phone: +1 408-927-1894 Email: eshel@us.ibm.com