--- 1/draft-ietf-nfsv4-xattrs-02.txt 2016-09-07 17:15:56.907694752 -0700 +++ 2/draft-ietf-nfsv4-xattrs-03.txt 2016-09-07 17:15:56.963696183 -0700 @@ -1,30 +1,31 @@ NFSv4 Working Group M. Naik Internet Draft Nutanix Intended Status: Standards Track M. Eshel -Expires: September 8, 2016 IBM Almaden - March 7, 2016 +Expires: March 11, 2017 IBM Almaden + September 7, 2016 File System Extended Attributes in NFSv4 - draft-ietf-nfsv4-xattrs-02 + draft-ietf-nfsv4-xattrs-03 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 - operations to get and set xattrs on file system objects are provided. + This document proposes an OPTIONAL feature extending the NFSv4 + protocol which allows extended attributes (hereinafter also referred + to as xattrs) to be interrogated and 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 operations to get and set + xattrs on file system objects are provided. Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. @@ -52,82 +52,84 @@ 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 - 2. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 2. Current and Potential Uses of Extended Attributes . . . . . . 5 3. File System Support . . . . . . . . . . . . . . . . . . . . . 6 4. Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 5. Differences from Named Attributes . . . . . . . . . . . . . . 7 + 5. Relationship with Named Attributes . . . . . . . . . . . . . . 7 6. XDR Description . . . . . . . . . . . . . . . . . . . . . . . 8 - 6.1. Code Components Licensing Notice . . . . . . . . . . . . . 8 + 6.1. Code Components Licensing Notice . . . . . . . . . . . . . 9 + 6.2. XDR for Xattr Extension . . . . . . . . . . . . . . . . . 10 7. Protocol Extensions . . . . . . . . . . . . . . . . . . . . . 10 - 7.1. New definitions . . . . . . . . . . . . . . . . . . . . . 10 - 7.2. New Attribute . . . . . . . . . . . . . . . . . . . . . . 10 + 7.1. New definitions . . . . . . . . . . . . . . . . . . . . . 11 + 7.2. New Attribute . . . . . . . . . . . . . . . . . . . . . . 11 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.3. New Error Definitions . . . . . . . . . . . . . . . . . . 12 + 7.3.1. NFS4ERR_NOXATTR (Error Code 10095) . . . . . . . . . . 12 + 7.3.2. NFS4ERR_XATTR2BIG (Error Code 10096) . . . . . . . . . 12 + 7.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 12 + 7.4.1. GETXATTR - Get an extended attribute of a file . . . . 13 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 + 7.4.3. LISTXATTRS - List extended attributes of a file . . . 16 + 7.4.4. REMOVEXATTR - Remove an extended attribute of a file . 18 + 7.4.5. Valid Errors . . . . . . . . . . . . . . . . . . . . . 19 + 7.5. Modifications to Existing Operations . . . . . . . . . . . 20 + 7.6. Numeric Values Assigned to Protocol Extensions . . . . . . 22 + 7.7. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 23 + 7.8. Xattrs and File Locking . . . . . . . . . . . . . . . . . 25 + 7.9. pNFS Considerations . . . . . . . . . . . . . . . . . . . 25 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 the key/value pairs. + opaque metadata with file system objects, organized as 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 + 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 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. + inclusion in NFSv4 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 ignore application-specified xattrs. This state of affairs results - in data loss if one copies, over the NFS protocol, a file with xattrs - from one file system to another that also supports xattrs. + in data loss if one copies, over the NFSv4 protocol, a file with + xattrs from one file system to another that also supports xattrs. There is thus a need to provide a means by which such data loss can be avoided. This will involve exposing xattrs within the NFSv4 protocol, despite the lack of completely compatible file system implementations. This document discusses (in Section 5) the reasons that NFSv4 named attributes as currently standardized in [RFC7530], are unsuitable for representing xattrs. Instead, it proposes a separate protocol mechanism to support xattrs. As a consequence, xattrs and named @@ -137,21 +139,21 @@ 1.1. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. In this document, these words will appear with that interpretation only when in ALL CAPS. Lower case uses of these words are not to be interpreted as carrying RFC-2119 significance. -2. Use Cases +2. Current and Potential Uses of Extended Attributes Applications can store tracking information in extended attributes. Examples include storing metadata identifying the application that created the file, a tag to indicate when the file was last verified by a data integrity scrubber, or a tag to hold a checksum/crypto hash of the file contents along with the date of that signature. Xattrs can also be used for decorations or annotations. For example, a file downloaded from a web server can be tagged with the URL, which can be convenient if its source has to be determined in the future. Likewise, an email attachment, when saved, can be tagged with the @@ -171,21 +173,21 @@ knowledge. A better approach is to dispense with the custom database and store such metadata in extended attributes. This is easier to maintain, provides faster access, and is readily accessible by applications [Love]. Swift, the OpenStack distributed object store, uses xattrs to store an object's metadata along with all the data together in one file. Swift-on-File [Swift] transfers the responsibility of maintaining object durability and availability to the underlying file system. Today, this requires a native file system client to mount the - volumes. Xattr support in NFS would open up the possibility of + volumes. Xattr support in NFSv4 would open up the possibility of storing and consuming data from other storage systems, and facilitate the migration of data between different backend storage systems. Baloo, the file indexing and search framework for KDE, has moved to storing metadata such as tags, ratings and comments, in file system xattrs instead of a custom database for simplicity. Starting with KDE Plasma 5.1, NFS is no longer supported due to its lack of xattr support [KDE]. 3. File System Support @@ -198,26 +200,27 @@ 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 [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]. + Some file systems have facilities that are capable of storing both + extended attributes and named attributes. For discussion regarding + the relationship between these feature, see section 5. Solaris 9 and + later provides file "forks", logically represented as files within a + hidden directory that is associated with the target file [fsattr]. In + the NTFS file system, extended attributes may be stored within "file + streams" [NTFS]. Xattrs can be retrieved and set through system calls or shell 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 @@ -242,21 +245,21 @@ xattrs are considered application data just as the contents of named attributes, files, and symbolic links are. Servers have a responsibility to store whatever value the client specifies and to return it on demand. xattr keys and values MUST NOT be interpreted by the NFS clients and servers, as such behavior would lead to non- interoperable implementations. If there is a need to specify attributes that servers need to be act upon, the appropriate semantics need to be specified by adding a new attribute for the purpose as provided by [RFC7530] and [NFSv4-vers]. -5. Differences from Named Attributes +5. Relationship with Named Attributes [RFC7530] defines named attributes as opaque byte streams that are associated with a directory or file and referred to by a string name. Named attributes are intended to be used by client applications as a method to associate application-specific data with a regular file or directory. In that sense, xattrs are similar in concept and use to named attributes, but there are subtle differences. File systems typically define operations to get and set individual xatrrs as being atomic, although collectively they may be @@ -269,21 +272,24 @@ maximum size for requests. Named attributes, on the other hand, are unbounded data streams and do not impose atomicity requirements. Individual named attributes are analogous to files, and caching of the data for these needs to be handled just as data caching is for ordinary files following close-to-open semantics. Xattrs, on the other hand, impose caching requirements like other file attributes. Named attributes and xattrs have different semantics and belong to disjoint namespaces. As a result, mapping one to another is, at - best, a compromise. + best, a compromise. Despite these differences, the underlying file + system structure used to store named attributes is generally capable + of storing xattrs. However, the converse is typically not the case + because of the size limits applicable to xattrs. While it should be possible to write guidance about how a client can use the named attribute mechanism to act like xattrs, such as carving out some namespace and specifying locking primitives to enforce atomicity constraints on individual get/set operations, this is problematic. A client application trying to use xattrs through named attributes with a server that supported xattrs directly would get a lower level of service, and could fail to cooperate on a local application running on the server unless the server file system defined its own interoperability constraints. File systems that @@ -309,33 +315,53 @@ That is, if the above script is stored in a file called "extract.sh", and this document is in a file called "spec.txt", then the reader can do: sh extract.sh < spec.txt > xattr_prot.x The effect of the script is to remove leading white space from each line, plus a sentinel sequence of "///". - The embedded XDR file header follows. Subsequent XDR descriptions, - with the sentinel sequence are embedded throughout the document. + The initial section of the embedded XDR file header follows. + Subsequent XDR descriptions, with the sentinel sequence are embedded + throughout the document. Note that the XDR code contained in this document depends on types from the proposed NFSv4.2 nfs4_prot.x file [NFSv42-dot-x]. This - includes both nfs types that end with a 4, such as verifier4, count4, - etc., as well as more generic types such as opaque and bool. + includes both nfs types that end with a 4, such as nfs_cookie4, + count4, etc., as well as more generic types such as opaque and bool. + + To produce a compilable XDR file, following procedure is suggested: + + o Extract the file nfs4_prot.x as described in [NFSv42-dot-x]. + + o Extract xattr_prot.x from this document as described above. + + o Apply any changes required for other extensions to be included + together with the xattr extension. + + o Perform modifications to nfs4_prot.x as described by comments + within xattr_prot.x. + + o Extend the unions nfs_argop4 and nfs_resop4 to include cases for + the new operations defined in this document. + + o Combine the XDR files for the base v4.2 protocol, and all needed + extensions by either concatenating the relevant XDR files, or + using file inclusion. 6.1. Code Components Licensing Notice - Both the XDR description and the scripts used for extracting the XDR - description are Code Components as described in Section 4 of "Legal - Provisions Relating to IETF Documents" [LEGAL]. These Code + Both the XDR description and the scripts used for extracting the + XDR description are Code Components as described in Section 4 of + "Legal Provisions Relating to IETF Documents" [LEGAL]. These Code Components are licensed according to the terms of that document. /// /* /// * Copyright (c) 2012 IETF Trust and the persons identified /// * as authors of the code. All rights reserved. /// * /// * Redistribution and use in source and binary forms, with /// * or without modification, are permitted provided that the @@ -368,47 +394,61 @@ /// * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF /// * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, /// * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING /// * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF /// * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. /// * /// * This code was derived from RFCTBD10. /// * Please reproduce this note if possible. /// */ + + +6.2. XDR for Xattr Extension + + + /// /* /// * xattr_prot.x /// */ + /// /* /// * The following include statements are for example only. /// * The actual XDR definition files are generated separately /// * and independently and are likely to have a different name. - /// * %#include /// * %#include + /// * %#include /// */ 7. Protocol Extensions - This section documents extensions to the NFSv4 protocol operations to - allow xattrs to be queried and modified by clients. A new attribute - is added to allow clients to check if the server supports xattrs. - 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 + This section documents extensions to the NFSv4 protocol operations + to allow xattrs to be queried and modified by clients. A new + attribute is added to allow clients to determine if the file + system being accessed provides support for xattrs. New operations + are defined to allow xattr keys and values to be queried and set. + In addition, extension are made to existing operations and + attributes as follows: + + o The ACCESS operation is extended by adding new mask bits to + provide access information relating to xattrs. + + o The acl attribute is extended by adding new bits to the ACE access + mask field to separately control 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]). + 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 definitions /// typedef component4 xattrkey4; /// typedef opaque xattrvalue4<>; @@ -417,23 +457,26 @@ 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 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. + The per-fs read-only attribute described in Section 7.2.1 may be used + to determine if xattrs are supported. Servers need not support this + attribute and some NFSv4.2 servers may be unaware of its existence. + Before interrogating this attribute using GETATTR, a client should + determine whether it is a supported attribute by interrogating the + supported_attrs attribute. 7.2.1. xattr_support True, if the object's file system supports extended attributes. Since xattr_support is not a REQUIRED attribute, server need not support it. However, a client may reasonably assume that a server (or file system) that does not support the xattr_support attribute does not provide xattr support and act on that basis. @@ -495,27 +538,31 @@ o Given a file, return a list of all of the file's assigned extended 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, + This section introduces four new OPTIONAL operations, GETXATTR, 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. + xattrs respectively. A server MUST support all four operations when + they are directed to a file system which supports the xattr_support + attribute and returns TRUE when it is interrogated. For file systems + which either do not support the xattr_support attribute or which + returns FALSE when it is interrogated, all of these operations MUST + NOT be supported. 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.4.1. GETXATTR - Get an extended attribute of a file 7.4.1.1. ARGUMENTS /// struct GETXATTR4args { /// /* CURRENT_FH: file */ /// xattrkey4 gxa_name; @@ -650,32 +695,30 @@ 7.4.3. LISTXATTRS - List extended attributes of a file 7.4.3.1. ARGUMENTS /// struct LISTXATTRS4args { /// /* CURRENT_FH: file */ /// nfs_cookie4 lxa_cookie; - /// verifier4 lxa_cookieverf; /// count4 lxa_maxcount; /// }; 7.4.3.2. RESULTS /// struct LISTXATTRS4resok { /// nfs_cookie4 lxr_cookie; - /// verifier4 lxr_cookieverf; /// xattrkey4 lxr_names<>; /// bool lxr_eof; /// }; /// union LISTXATTRS4res switch (nfsstat4 lxr_status) { /// case NFS4_OK: /// LISTXATTRS4resok lxr_value; /// default: /// void; /// }; @@ -689,28 +732,20 @@ filehandle, along with information to allow the client to request additional attribute keys in a subsequent LISTXATTRS. The arguments contain a cookie value that represents where the 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 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 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 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 "lxr_eof" flag has a value of TRUE if there are no more keys for the object. @@ -719,27 +754,25 @@ "bookmark" for the xattr key. As mentioned, this cookie is used by 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. On success, the current filehandle retains its value. 7.4.3.4. IMPLEMENTATION - 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. + The handling of cookie is similar to that of the READDIR operation. + It should be a rare occurrence that a server is unable to continue + properly listing xattrs with the provided cookie. 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.4. REMOVEXATTR - Remove an extended attribute of a file 7.4.4.1. ARGUMENTS /// struct REMOVEXATTR4args { /// /* CURRENT_FH: file */ /// xattrkey4 rxa_name;