draft-ietf-nfsv4-xattrs-02.txt   draft-ietf-nfsv4-xattrs-03.txt 
NFSv4 Working Group M. Naik NFSv4 Working Group M. Naik
Internet Draft Nutanix Internet Draft Nutanix
Intended Status: Standards Track M. Eshel Intended Status: Standards Track M. Eshel
Expires: September 8, 2016 IBM Almaden Expires: March 11, 2017 IBM Almaden
March 7, 2016 September 7, 2016
File System Extended Attributes in NFSv4 File System Extended Attributes in NFSv4
draft-ietf-nfsv4-xattrs-02 draft-ietf-nfsv4-xattrs-03
Abstract Abstract
This document proposes extensions to the NFSv4 protocol which allow This document proposes an OPTIONAL feature extending the NFSv4
file extended attributes (hereinafter also referred to as xattrs) to protocol which allows extended attributes (hereinafter also referred
be manipulated using NFSv4. An xattr is a file system feature that to as xattrs) to be interrogated and manipulated using NFSv4. An
allows opaque metadata, not interpreted by the file system, to be xattr is a file system feature that allows opaque metadata, not
associated with files and directories. Such support is present in interpreted by the file system, to be associated with files and
many modern local file systems. New file attributes are proposed to directories. Such support is present in many modern local file
allow clients to query the server for xattr support, and new systems. New file attributes are proposed to allow clients to query
operations to get and set xattrs on file system objects are provided. the server for xattr support, and new operations to get and set
xattrs on file system objects are provided.
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as other groups may also distribute working documents as
Internet-Drafts. Internet-Drafts.
skipping to change at page 2, line 20 skipping to change at page 2, line 21
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Current and Potential Uses of Extended Attributes . . . . . . 5
3. File System Support . . . . . . . . . . . . . . . . . . . . . 6 3. File System Support . . . . . . . . . . . . . . . . . . . . . 6
4. Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5. Differences from Named Attributes . . . . . . . . . . . . . . 7 5. Relationship with Named Attributes . . . . . . . . . . . . . . 7
6. XDR Description . . . . . . . . . . . . . . . . . . . . . . . 8 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. Protocol Extensions . . . . . . . . . . . . . . . . . . . . . 10
7.1. New definitions . . . . . . . . . . . . . . . . . . . . . 10 7.1. New definitions . . . . . . . . . . . . . . . . . . . . . 11
7.2. New Attribute . . . . . . . . . . . . . . . . . . . . . . 10 7.2. New Attribute . . . . . . . . . . . . . . . . . . . . . . 11
7.2.1. xattr_support . . . . . . . . . . . . . . . . . . . . 11 7.2.1. xattr_support . . . . . . . . . . . . . . . . . . . . 11
7.3. New Error Definitions . . . . . . . . . . . . . . . . . . 11 7.3. New Error Definitions . . . . . . . . . . . . . . . . . . 12
7.3.1. NFS4ERR_NOXATTR (Error Code 10095) . . . . . . . . . . 11 7.3.1. NFS4ERR_NOXATTR (Error Code 10095) . . . . . . . . . . 12
7.3.2. NFS4ERR_XATTR2BIG (Error Code 10096) . . . . . . . . . 11 7.3.2. NFS4ERR_XATTR2BIG (Error Code 10096) . . . . . . . . . 12
7.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 11 7.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 12
7.4.1. GETXATTR - Get an extended attribute of a file . . . . 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.2. SETXATTR - Set an extended attribute of a file . . . . 14
7.4.3. LISTXATTRS - List extended attributes of a file . . . 15 7.4.3. LISTXATTRS - List extended attributes of a file . . . 16
7.4.4. REMOVEXATTR - Remove an extended attribute of a file . 17 7.4.4. REMOVEXATTR - Remove an extended attribute of a file . 18
7.4.5. Valid Errors . . . . . . . . . . . . . . . . . . . . . 18 7.4.5. Valid Errors . . . . . . . . . . . . . . . . . . . . . 19
7.5. Modifications to Existing Operations . . . . . . . . . . . 19 7.5. Modifications to Existing Operations . . . . . . . . . . . 20
7.6. Numeric Values Assigned to Protocol Extensions . . . . . . 21 7.6. Numeric Values Assigned to Protocol Extensions . . . . . . 22
7.7. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 22 7.7. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.8. Xattrs and File Locking . . . . . . . . . . . . . . . . . 24 7.8. Xattrs and File Locking . . . . . . . . . . . . . . . . . 25
7.9. pNFS Considerations . . . . . . . . . . . . . . . . . . . 24 7.9. pNFS Considerations . . . . . . . . . . . . . . . . . . . 25
8. Security Considerations . . . . . . . . . . . . . . . . . . . 25 8. Security Considerations . . . . . . . . . . . . . . . . . . . 25
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 26
10.1. Normative References . . . . . . . . . . . . . . . . . . 26 10.1. Normative References . . . . . . . . . . . . . . . . . . 26
10.2. Informative References . . . . . . . . . . . . . . . . . 26 10.2. Informative References . . . . . . . . . . . . . . . . . 26
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 27 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 27
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 28 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 28
1. Introduction 1. Introduction
Extended attributes, also called xattrs, are a means to associate Extended attributes, also called xattrs, are a means to associate
opaque metadata with file system objects, typically organized in opaque metadata with file system objects, organized as key/value
key/value pairs. They are especially useful when they add pairs. They are especially useful when they add information that is
information that is not, or cannot be, present in the associated not, or cannot be, present in the associated object itself. User-
object itself. User-space applications can arbitrarily create, space applications can arbitrarily create, interrogate, and modify
interrogate, and modify the key/value pairs. the key/value pairs.
Extended attributes are file system-agnostic; applications use an Extended attributes are file system-agnostic; applications use an
interface not specific to any file system to manipulate them. interface not specific to any file system to manipulate them.
Applications do not need to be concerned about how the key/value Applications do not need to be concerned about how the key/value
pairs are stored internally within the underlying file system. All pairs are stored internally within the underlying file system. All
major operating systems provide various flavors of extended major operating systems provide various flavors of extended
attributes. Many user space tools allow xattrs to be included in attributes. Many user space tools allow xattrs to be included in
regular attributes that need to be preserved when objects are regular attributes that need to be preserved when objects are
updated, moved or copied. updated, moved or copied.
Extended attributes have previously been considered unsuitable for Extended attributes have previously been considered unsuitable for
portable use because some aspects of their handling are not precisely inclusion in NFSv4 because some aspects of their handling are not
defined and they are not formally documented by any standard (such as precisely defined and they are not formally documented by any
POSIX). Nevertheless, it appears that xattrs are widely deployed and standard (such as POSIX). Nevertheless, it appears that xattrs are
their support in modern disk-based file systems is nearly universal. 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 There is no clear specification of how xattrs could be mapped to any
existing file attributes defined in the NFSv4 protocol ([RFC7530], existing file attributes defined in the NFSv4 protocol ([RFC7530],
[RFC5661], [NFSv42]). As a result, most NFSv4 client implementations [RFC5661], [NFSv42]). As a result, most NFSv4 client implementations
ignore application-specified xattrs. This state of affairs results ignore application-specified xattrs. This state of affairs results
in data loss if one copies, over the NFS protocol, a file with xattrs in data loss if one copies, over the NFSv4 protocol, a file with
from one file system to another that also supports xattrs. 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 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 be avoided. This will involve exposing xattrs within the NFSv4
protocol, despite the lack of completely compatible file system protocol, despite the lack of completely compatible file system
implementations. implementations.
This document discusses (in Section 5) the reasons that NFSv4 named This document discusses (in Section 5) the reasons that NFSv4 named
attributes as currently standardized in [RFC7530], are unsuitable for attributes as currently standardized in [RFC7530], are unsuitable for
representing xattrs. Instead, it proposes a separate protocol representing xattrs. Instead, it proposes a separate protocol
mechanism to support xattrs. As a consequence, xattrs and named mechanism to support xattrs. As a consequence, xattrs and named
skipping to change at page 5, line 9 skipping to change at page 5, line 10
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
In this document, these words will appear with that interpretation 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 only when in ALL CAPS. Lower case uses of these words are not to be
interpreted as carrying RFC-2119 significance. 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. Applications can store tracking information in extended attributes.
Examples include storing metadata identifying the application that Examples include storing metadata identifying the application that
created the file, a tag to indicate when the file was last verified 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 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 of the file contents along with the date of that signature. Xattrs
can also be used for decorations or annotations. For example, a file 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 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. convenient if its source has to be determined in the future.
Likewise, an email attachment, when saved, can be tagged with the Likewise, an email attachment, when saved, can be tagged with the
skipping to change at page 5, line 43 skipping to change at page 5, line 44
knowledge. A better approach is to dispense with the custom database knowledge. A better approach is to dispense with the custom database
and store such metadata in extended attributes. This is easier to and store such metadata in extended attributes. This is easier to
maintain, provides faster access, and is readily accessible by maintain, provides faster access, and is readily accessible by
applications [Love]. applications [Love].
Swift, the OpenStack distributed object store, uses xattrs to store Swift, the OpenStack distributed object store, uses xattrs to store
an object's metadata along with all the data together in one file. an object's metadata along with all the data together in one file.
Swift-on-File [Swift] transfers the responsibility of maintaining Swift-on-File [Swift] transfers the responsibility of maintaining
object durability and availability to the underlying file system. object durability and availability to the underlying file system.
Today, this requires a native file system client to mount the 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 storing and consuming data from other storage systems, and facilitate
the migration of data between different backend storage systems. the migration of data between different backend storage systems.
Baloo, the file indexing and search framework for KDE, has moved to Baloo, the file indexing and search framework for KDE, has moved to
storing metadata such as tags, ratings and comments, in file system storing metadata such as tags, ratings and comments, in file system
xattrs instead of a custom database for simplicity. Starting with 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 KDE Plasma 5.1, NFS is no longer supported due to its lack of xattr
support [KDE]. support [KDE].
3. File System Support 3. File System Support
skipping to change at page 6, line 22 skipping to change at page 6, line 23
attributes must be prefixed by the name of the category and a dot; attributes must be prefixed by the name of the category and a dot;
hence these categories are generally qualified as name spaces. hence these categories are generally qualified as name spaces.
Currently, four namespaces exist: user, trusted, security and system Currently, four namespaces exist: user, trusted, security and system
[Linux]. Recommendations on how they should be used have been [Linux]. Recommendations on how they should be used have been
published [freedesktop]. published [freedesktop].
FreeBSD supports extended attributes in two universal namespaces - FreeBSD supports extended attributes in two universal namespaces -
user and system, although individual file systems are allowed to user and system, although individual file systems are allowed to
implement additional namespaces [FreeBSD]. implement additional namespaces [FreeBSD].
Solaris 9 and later allows files to have extended attributes, but Some file systems have facilities that are capable of storing both
implements them as "forks", logically represented as files within a extended attributes and named attributes. For discussion regarding
hidden directory that is associated with the target file [fsattr]. the relationship between these feature, see section 5. Solaris 9 and
later provides file "forks", logically represented as files within a
In the NTFS file system, extended attributes are one of several hidden directory that is associated with the target file [fsattr]. In
supported "file streams" [NTFS]. the NTFS file system, extended attributes may be stored within "file
streams" [NTFS].
Xattrs can be retrieved and set through system calls or shell Xattrs can be retrieved and set through system calls or shell
commands and are generally supported by user-space tools that commands and are generally supported by user-space tools that
preserve other file attributes. For example, the "rsync" remote copy preserve other file attributes. For example, the "rsync" remote copy
program will correctly preserve user extended attributes between program will correctly preserve user extended attributes between
Linux/ext4 and OSX/hfs by stripping off the Linux-specific "user." Linux/ext4 and OSX/hfs by stripping off the Linux-specific "user."
prefix. prefix.
4. Namespaces 4. Namespaces
skipping to change at page 7, line 18 skipping to change at page 7, line 20
xattrs are considered application data just as the contents of named xattrs are considered application data just as the contents of named
attributes, files, and symbolic links are. Servers have a attributes, files, and symbolic links are. Servers have a
responsibility to store whatever value the client specifies and to responsibility to store whatever value the client specifies and to
return it on demand. xattr keys and values MUST NOT be interpreted by 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- the NFS clients and servers, as such behavior would lead to non-
interoperable implementations. If there is a need to specify interoperable implementations. If there is a need to specify
attributes that servers need to be act upon, the appropriate attributes that servers need to be act upon, the appropriate
semantics need to be specified by adding a new attribute for the semantics need to be specified by adding a new attribute for the
purpose as provided by [RFC7530] and [NFSv4-vers]. 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 [RFC7530] defines named attributes as opaque byte streams that are
associated with a directory or file and referred to by a string name. 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 Named attributes are intended to be used by client applications as a
method to associate application-specific data with a regular file or method to associate application-specific data with a regular file or
directory. In that sense, xattrs are similar in concept and use to directory. In that sense, xattrs are similar in concept and use to
named attributes, but there are subtle differences. named attributes, but there are subtle differences.
File systems typically define operations to get and set individual File systems typically define operations to get and set individual
xatrrs as being atomic, although collectively they may be xatrrs as being atomic, although collectively they may be
skipping to change at page 7, line 45 skipping to change at page 7, line 47
maximum size for requests. Named attributes, on the other hand, are maximum size for requests. Named attributes, on the other hand, are
unbounded data streams and do not impose atomicity requirements. unbounded data streams and do not impose atomicity requirements.
Individual named attributes are analogous to files, and caching of Individual named attributes are analogous to files, and caching of
the data for these needs to be handled just as data caching is for the data for these needs to be handled just as data caching is for
ordinary files following close-to-open semantics. Xattrs, on the ordinary files following close-to-open semantics. Xattrs, on the
other hand, impose caching requirements like other file attributes. other hand, impose caching requirements like other file attributes.
Named attributes and xattrs have different semantics and belong to Named attributes and xattrs have different semantics and belong to
disjoint namespaces. As a result, mapping one to another is, at 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 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 use the named attribute mechanism to act like xattrs, such as carving
out some namespace and specifying locking primitives to enforce out some namespace and specifying locking primitives to enforce
atomicity constraints on individual get/set operations, this is atomicity constraints on individual get/set operations, this is
problematic. A client application trying to use xattrs through named problematic. A client application trying to use xattrs through named
attributes with a server that supported xattrs directly would get a attributes with a server that supported xattrs directly would get a
lower level of service, and could fail to cooperate on a local lower level of service, and could fail to cooperate on a local
application running on the server unless the server file system application running on the server unless the server file system
defined its own interoperability constraints. File systems that defined its own interoperability constraints. File systems that
skipping to change at page 8, line 36 skipping to change at page 8, line 43
That is, if the above script is stored in a file called "extract.sh", 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 and this document is in a file called "spec.txt", then the reader can
do: do:
sh extract.sh < spec.txt > xattr_prot.x sh extract.sh < spec.txt > xattr_prot.x
The effect of the script is to remove leading white space from each The effect of the script is to remove leading white space from each
line, plus a sentinel sequence of "///". line, plus a sentinel sequence of "///".
The embedded XDR file header follows. Subsequent XDR descriptions, The initial section of the embedded XDR file header follows.
with the sentinel sequence are embedded throughout the document. Subsequent XDR descriptions, with the sentinel sequence are embedded
throughout the document.
Note that the XDR code contained in this document depends on types 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 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, includes both nfs types that end with a 4, such as nfs_cookie4,
etc., as well as more generic types such as opaque and bool. 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 6.1. Code Components Licensing Notice
Both the XDR description and the scripts used for extracting the XDR Both the XDR description and the scripts used for extracting the
description are Code Components as described in Section 4 of "Legal XDR description are Code Components as described in Section 4 of
Provisions Relating to IETF Documents" [LEGAL]. These Code "Legal Provisions Relating to IETF Documents" [LEGAL]. These Code
Components are licensed according to the terms of that document. Components are licensed according to the terms of that document.
<CODE BEGINS> <CODE BEGINS>
/// /* /// /*
/// * Copyright (c) 2012 IETF Trust and the persons identified /// * Copyright (c) 2012 IETF Trust and the persons identified
/// * as authors of the code. All rights reserved. /// * as authors of the code. All rights reserved.
/// * /// *
/// * Redistribution and use in source and binary forms, with /// * Redistribution and use in source and binary forms, with
/// * or without modification, are permitted provided that the /// * or without modification, are permitted provided that the
/// * following conditions are met: /// * following conditions are met:
/// * /// *
/// * o Redistributions of source code must retain the above /// * o Redistributions of source code must retain the above
/// * copyright notice, this list of conditions and the /// * copyright notice, this list of conditions and the
/// * following disclaimer. /// * following disclaimer.
/// * /// *
/// * o Redistributions in binary form must reproduce the above /// * o Redistributions in binary form must reproduce the above
/// * copyright notice, this list of conditions and the /// * copyright notice, this list of conditions and the
/// * following disclaimer in the documentation and/or other /// * following disclaimer in the documentation and/or other
/// * materials provided with the distribution. /// * materials provided with the distribution.
/// * /// *
/// * o Neither the name of Internet Society, IETF or IETF /// * o Neither the name of Internet Society, IETF or IETF
/// * Trust, nor the names of specific contributors, may be /// * Trust, nor the names of specific contributors, may be
/// * used to endorse or promote products derived from this /// * used to endorse or promote products derived from this
/// * software without specific prior written permission. /// * software without specific prior written permission.
/// * /// *
/// * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS /// * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS
/// * AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED /// * AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
/// * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE /// * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
/// * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS /// * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
/// * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO /// * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
/// * EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE /// * EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
/// * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, /// * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
/// * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT /// * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
/// * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR /// * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
/// * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS /// * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
/// * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF /// * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
/// * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, /// * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
/// * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING /// * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
/// * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF /// * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
/// * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. /// * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
/// * /// *
/// * This code was derived from RFCTBD10. /// * This code was derived from RFCTBD10.
/// * Please reproduce this note if possible. /// * Please reproduce this note if possible.
/// */ /// */
/// /* <CODE ENDS>
/// * 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 <nfsv42.x>
/// * %#include <rpc_prot.x>
/// */
<CODE ENDS> 6.2. XDR for Xattr Extension
<CODE BEGINS>
/// /*
/// * 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 <rpc_prot.x>
/// * %#include <nfsv42.x>
/// */
<CODE ENDS>
7. Protocol Extensions 7. Protocol Extensions
This section documents extensions to the NFSv4 protocol operations to This section documents extensions to the NFSv4 protocol operations
allow xattrs to be queried and modified by clients. A new attribute to allow xattrs to be queried and modified by clients. A new
is added to allow clients to check if the server supports xattrs. attribute is added to allow clients to determine if the file
New operations are defined to allow xattr keys and values to be system being accessed provides support for xattrs. New operations
queried and set. In addition, new bitmask constants are added to the are defined to allow xattr keys and values to be queried and set.
ACE access mask field to validate permissions to query and modify In addition, extension are made to existing operations and
xattrs. attributes as follows:
These changes follow applicable guidelines for valid NFSv4 protocol o The ACCESS operation is extended by adding new mask bits to
extension, whether the extensions occur in a minor version (as provide access information relating to xattrs.
specified in [RFC5661]) or as an extension to an existing minor
version (as specified in [NFSv4-vers]). 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]).
7.1. New definitions 7.1. New definitions
<CODE BEGINS> <CODE BEGINS>
/// typedef component4 xattrkey4; /// typedef component4 xattrkey4;
/// typedef opaque xattrvalue4<>; /// typedef opaque xattrvalue4<>;
<CODE ENDS> <CODE ENDS>
Each xattr is a key/value pair. xattrkey4 is a string denoting the 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 xattr key name, and an attrvalue4 which is a variable-length string
that identifies the value of the xattr. The handling of xattrkey4 that identifies the value of the xattr. The handling of xattrkey4
with regard to internationalization-related issues is the same as with regard to internationalization-related issues is the same as
that for NFSv4 file names and named attribute names, as described in that for NFSv4 file names and named attribute names, as described in
[RFC7530]. Any regular file or directory may have a set of extended [RFC7530]. Any regular file or directory may have a set of extended
attributes, each consisting of a key and associated value. The NFS attributes, each consisting of a key and associated value. The NFS
client or server MUST NOT interpret the contents of xattrkey4 or client or server MUST NOT interpret the contents of xattrkey4 or
xattrvalue4. xattrvalue4.
7.2. New Attribute 7.2. New Attribute
The following RECOMMENDED per-fs read-only attribute is proposed for The per-fs read-only attribute described in Section 7.2.1 may be used
use. A client can query the server to determine if xattrs are to determine if xattrs are supported. Servers need not support this
supported by setting the xattr_support bit in the GETATTR request. 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 7.2.1. xattr_support
True, if the object's file system supports extended attributes. True, if the object's file system supports extended attributes.
Since xattr_support is not a REQUIRED attribute, server need not Since xattr_support is not a REQUIRED attribute, server need not
support it. However, a client may reasonably assume that a server support it. However, a client may reasonably assume that a server
(or file system) that does not support the xattr_support attribute (or file system) that does not support the xattr_support attribute
does not provide xattr support and act on that basis. does not provide xattr support and act on that basis.
skipping to change at page 12, line 32 skipping to change at page 13, line 24
o Given a file, return a list of all of the file's assigned extended o Given a file, return a list of all of the file's assigned extended
attribute keys. attribute keys.
o Given a file and a key, return the corresponding value. 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, a key, and a value, assign that value to the key.
o Given a file and a key, remove that extended attribute from the o Given a file and a key, remove that extended attribute from the
file. 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 SETXATTR, LISTXATTRS and REMOVEXATTR, to query, set, list and remove
xattrs respectively. A server MUST support all four operations if it xattrs respectively. A server MUST support all four operations when
supports the xattr_support attribute. GETXATTR allows obtaining the they are directed to a file system which supports the xattr_support
value of an xattr key, SETXATTR allows creating or replacing an xattr attribute and returns TRUE when it is interrogated. For file systems
key with a value, LISTXATTRS enumerates all the xattrs names, and which either do not support the xattr_support attribute or which
REMOVEXATTR allows deleting a single xattr. 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. GETXATTR - Get an extended attribute of a file
7.4.1.1. ARGUMENTS 7.4.1.1. ARGUMENTS
<CODE BEGINS> <CODE BEGINS>
/// struct GETXATTR4args { /// struct GETXATTR4args {
/// /* CURRENT_FH: file */ /// /* CURRENT_FH: file */
/// xattrkey4 gxa_name; /// xattrkey4 gxa_name;
skipping to change at page 15, line 42 skipping to change at page 16, line 40
7.4.3. LISTXATTRS - List extended attributes of a file 7.4.3. LISTXATTRS - List extended attributes of a file
7.4.3.1. ARGUMENTS 7.4.3.1. ARGUMENTS
<CODE BEGINS> <CODE BEGINS>
/// struct LISTXATTRS4args { /// struct LISTXATTRS4args {
/// /* CURRENT_FH: file */ /// /* CURRENT_FH: file */
/// nfs_cookie4 lxa_cookie; /// nfs_cookie4 lxa_cookie;
/// verifier4 lxa_cookieverf;
/// count4 lxa_maxcount; /// count4 lxa_maxcount;
/// }; /// };
<CODE ENDS> <CODE ENDS>
7.4.3.2. RESULTS 7.4.3.2. RESULTS
<CODE BEGINS> <CODE BEGINS>
/// struct LISTXATTRS4resok { /// struct LISTXATTRS4resok {
/// nfs_cookie4 lxr_cookie; /// nfs_cookie4 lxr_cookie;
/// verifier4 lxr_cookieverf;
/// xattrkey4 lxr_names<>; /// xattrkey4 lxr_names<>;
/// bool lxr_eof; /// bool lxr_eof;
/// }; /// };
/// union LISTXATTRS4res switch (nfsstat4 lxr_status) { /// union LISTXATTRS4res switch (nfsstat4 lxr_status) {
/// case NFS4_OK: /// case NFS4_OK:
/// LISTXATTRS4resok lxr_value; /// LISTXATTRS4resok lxr_value;
/// default: /// default:
/// void; /// void;
/// }; /// };
skipping to change at page 16, line 36 skipping to change at page 17, line 35
filehandle, along with information to allow the client to request filehandle, along with information to allow the client to request
additional attribute keys in a subsequent LISTXATTRS. additional attribute keys in a subsequent LISTXATTRS.
The arguments contain a cookie value that represents where the The arguments contain a cookie value that represents where the
LISTXATTRS should start within the list of xattrs. A value of 0 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 (zero) for lxa_cookie is used to start reading at the beginning of
the list. For subsequent LISTXATTRS requests, the client specifies a the list. For subsequent LISTXATTRS requests, the client specifies a
cookie value that is provided by the server on a previous LISTXATTRS cookie value that is provided by the server on a previous LISTXATTRS
request. 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 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 for the result. This maximum size represents all of the data being
returned within the LISTXATTRS4resok 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 overhead. The server may return less data. If the server is unable
to return a single xattr name within the maxcount limit, the error to return a single xattr name within the maxcount limit, the error
NFS4ERR_TOOSMALL will be returned to the client. NFS4ERR_TOOSMALL will be returned to the client.
On successful return, the server's response will provide a list of 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 extended attribute keys. The "lxr_eof" flag has a value of TRUE if
there are no more keys for the object. there are no more keys for the object.
skipping to change at page 17, line 18 skipping to change at page 18, line 9
"bookmark" for the xattr key. As mentioned, this cookie is used by "bookmark" for the xattr key. As mentioned, this cookie is used by
the client for subsequent LISTXATTRS 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 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 cookie or the READ offset but should not be interpreted as such by
the client. the client.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
7.4.3.4. IMPLEMENTATION 7.4.3.4. IMPLEMENTATION
The handling of cookie/verifier is similar to that of the READDIR The handling of cookie is similar to that of the READDIR operation.
operation. The verifier may be used by the server to help manage It should be a rare occurrence that a server is unable to continue
cookie values that may become stale. It should be a rare occurrence properly listing xattrs with the provided cookie. The server should
that a server is unable to continue properly listing xattrs with the make every effort to avoid this condition since the application at
provided cookie/verifier pair. The server should make every effort the client may not be able to properly handle this type of failure.
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. REMOVEXATTR - Remove an extended attribute of a file
7.4.4.1. ARGUMENTS 7.4.4.1. ARGUMENTS
<CODE BEGINS> <CODE BEGINS>
/// struct REMOVEXATTR4args { /// struct REMOVEXATTR4args {
/// /* CURRENT_FH: file */ /// /* CURRENT_FH: file */
/// xattrkey4 rxa_name; /// xattrkey4 rxa_name;
 End of changes. 36 change blocks. 
152 lines changed or deleted 188 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/