Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7530

Network File System (NFS) Version 4 Protocol

Pages: 323
Proposed Standard
Errata
Obsoletes:  3530
Updated by:  79318587
Part 3 of 14 – Pages 30 to 54
First   Prev   Next

Top   ToC   RFC7530 - Page 30   prevText

4. Filehandles

The filehandle in the NFS protocol is a per-server unique identifier for a file system object. The contents of the filehandle are opaque to the client. Therefore, the server is responsible for translating the filehandle to an internal representation of the file system object.

4.1. Obtaining the First Filehandle

The operations of the NFS protocol are defined in terms of one or more filehandles. Therefore, the client needs a filehandle to initiate communication with the server. With the NFSv2 protocol [RFC1094] and the NFSv3 protocol [RFC1813], there exists an ancillary protocol to obtain this first filehandle. The MOUNT protocol, RPC program number 100005, provides the mechanism of translating a string-based file system pathname to a filehandle that can then be used by the NFS protocols. The MOUNT protocol has deficiencies in the area of security and use via firewalls. This is one reason that the use of the public filehandle was introduced in [RFC2054] and [RFC2055]. With the use of the public filehandle in combination with the LOOKUP operation in
Top   ToC   RFC7530 - Page 31
   the NFSv2 and NFSv3 protocols, it has been demonstrated that the
   MOUNT protocol is unnecessary for viable interaction between the NFS
   client and server.

   Therefore, the NFSv4 protocol will not use an ancillary protocol for
   translation from string-based pathnames to a filehandle.  Two special
   filehandles will be used as starting points for the NFS client.

4.1.1. Root Filehandle

The first of the special filehandles is the root filehandle. The root filehandle is the "conceptual" root of the file system namespace at the NFS server. The client uses or starts with the root filehandle by employing the PUTROOTFH operation. The PUTROOTFH operation instructs the server to set the current filehandle to the root of the server's file tree. Once this PUTROOTFH operation is used, the client can then traverse the entirety of the server's file tree with the LOOKUP operation. A complete discussion of the server namespace is in Section 7.

4.1.2. Public Filehandle

The second special filehandle is the public filehandle. Unlike the root filehandle, the public filehandle may be bound or represent an arbitrary file system object at the server. The server is responsible for this binding. It may be that the public filehandle and the root filehandle refer to the same file system object. However, it is up to the administrative software at the server and the policies of the server administrator to define the binding of the public filehandle and server file system object. The client may not make any assumptions about this binding. The client uses the public filehandle via the PUTPUBFH operation.

4.2. Filehandle Types

In the NFSv2 and NFSv3 protocols, there was one type of filehandle with a single set of semantics, of which the primary one was that it was persistent across a server reboot. As such, this type of filehandle is termed "persistent" in NFSv4. The semantics of a persistent filehandle remain the same as before. A new type of filehandle introduced in NFSv4 is the volatile filehandle, which attempts to accommodate certain server environments. The volatile filehandle type was introduced to address server functionality or implementation issues that make correct implementation of a persistent filehandle infeasible. Some server environments do not provide a file system level invariant that can be used to construct a persistent filehandle. The underlying server
Top   ToC   RFC7530 - Page 32
   file system may not provide the invariant, or the server's file
   system programming interfaces may not provide access to the needed
   invariant.  Volatile filehandles may ease the implementation of
   server functionality, such as hierarchical storage management or file
   system reorganization or migration.  However, the volatile filehandle
   increases the implementation burden for the client.

   Since the client will need to handle persistent and volatile
   filehandles differently, a file attribute is defined that may be used
   by the client to determine the filehandle types being returned by the
   server.

4.2.1. General Properties of a Filehandle

The filehandle contains all the information the server needs to distinguish an individual file. To the client, the filehandle is opaque. The client stores filehandles for use in a later request and can compare two filehandles from the same server for equality by doing a byte-by-byte comparison. However, the client MUST NOT otherwise interpret the contents of filehandles. If two filehandles from the same server are equal, they MUST refer to the same file. However, it is not required that two different filehandles refer to different file system objects. Servers SHOULD try to maintain a one-to-one correspondence between filehandles and file system objects but there may be situations in which the mapping is not one-to-one. Clients MUST use filehandle comparisons only to improve performance, not for correct behavior. All clients need to be prepared for situations in which it cannot be determined whether two different filehandles denote the same object and in such cases need to avoid assuming that objects denoted are different, as this might cause incorrect behavior. Further discussion of filehandle and attribute comparison in the context of data caching is presented in Section 10.3.4. As an example, in the case that two different pathnames when traversed at the server terminate at the same file system object, the server SHOULD return the same filehandle for each path. This can occur if a hard link is used to create two filenames that refer to the same underlying file object and associated data. For example, if paths /a/b/c and /a/d/c refer to the same file, the server SHOULD return the same filehandle for both pathname traversals.

4.2.2. Persistent Filehandle

A persistent filehandle is defined as having a fixed value for the lifetime of the file system object to which it refers. Once the server creates the filehandle for a file system object, the server MUST accept the same filehandle for the object for the lifetime of
Top   ToC   RFC7530 - Page 33
   the object.  If the server restarts or reboots, the NFS server must
   honor the same filehandle value as it did in the server's previous
   instantiation.  Similarly, if the file system is migrated, the new
   NFS server must honor the same filehandle as the old NFS server.

   The persistent filehandle will become stale or invalid when the file
   system object is removed.  When the server is presented with a
   persistent filehandle that refers to a deleted object, it MUST return
   an error of NFS4ERR_STALE.  A filehandle may become stale when the
   file system containing the object is no longer available.  The file
   system may become unavailable if it exists on removable media and the
   media is no longer available at the server, or if the file system in
   whole has been destroyed, or if the file system has simply been
   removed from the server's namespace (i.e., unmounted in a UNIX
   environment).

4.2.3. Volatile Filehandle

A volatile filehandle does not share the same longevity characteristics of a persistent filehandle. The server may determine that a volatile filehandle is no longer valid at many different points in time. If the server can definitively determine that a volatile filehandle refers to an object that has been removed, the server should return NFS4ERR_STALE to the client (as is the case for persistent filehandles). In all other cases where the server determines that a volatile filehandle can no longer be used, it should return an error of NFS4ERR_FHEXPIRED. The REQUIRED attribute "fh_expire_type" is used by the client to determine what type of filehandle the server is providing for a particular file system. This attribute is a bitmask with the following values: FH4_PERSISTENT: The value of FH4_PERSISTENT is used to indicate a persistent filehandle, which is valid until the object is removed from the file system. The server will not return NFS4ERR_FHEXPIRED for this filehandle. FH4_PERSISTENT is defined as a value in which none of the bits specified below are set. FH4_VOLATILE_ANY: The filehandle may expire at any time, except as specifically excluded (i.e., FH4_NOEXPIRE_WITH_OPEN). FH4_NOEXPIRE_WITH_OPEN: May only be set when FH4_VOLATILE_ANY is set. If this bit is set, then the meaning of FH4_VOLATILE_ANY is qualified to exclude any expiration of the filehandle when it is open.
Top   ToC   RFC7530 - Page 34
   FH4_VOL_MIGRATION:  The filehandle will expire as a result of
      migration.  If FH4_VOLATILE_ANY is set, FH4_VOL_MIGRATION is
      redundant.

   FH4_VOL_RENAME:  The filehandle will expire during rename.  This
      includes a rename by the requesting client or a rename by any
      other client.  If FH4_VOLATILE_ANY is set, FH4_VOL_RENAME is
      redundant.

   Servers that provide volatile filehandles that may expire while open
   (i.e., if FH4_VOL_MIGRATION or FH4_VOL_RENAME is set or if
   FH4_VOLATILE_ANY is set and FH4_NOEXPIRE_WITH_OPEN is not set) should
   deny a RENAME or REMOVE that would affect an OPEN file of any of the
   components leading to the OPEN file.  In addition, the server SHOULD
   deny all RENAME or REMOVE requests during the grace period upon
   server restart.

   Note that the bits FH4_VOL_MIGRATION and FH4_VOL_RENAME allow the
   client to determine that expiration has occurred whenever a specific
   event occurs, without an explicit filehandle expiration error from
   the server.  FH4_VOLATILE_ANY does not provide this form of
   information.  In situations where the server will expire many, but
   not all, filehandles upon migration (e.g., all but those that are
   open), FH4_VOLATILE_ANY (in this case, with FH4_NOEXPIRE_WITH_OPEN)
   is a better choice since the client may not assume that all
   filehandles will expire when migration occurs, and it is likely that
   additional expirations will occur (as a result of file CLOSE) that
   are separated in time from the migration event itself.

4.2.4. One Method of Constructing a Volatile Filehandle

A volatile filehandle, while opaque to the client, could contain: [volatile bit = 1 | server boot time | slot | generation number] o slot is an index in the server volatile filehandle table o generation number is the generation number for the table entry/slot When the client presents a volatile filehandle, the server makes the following checks, which assume that the check for the volatile bit has passed. If the server boot time is less than the current server boot time, return NFS4ERR_FHEXPIRED. If slot is out of range, return NFS4ERR_BADHANDLE. If the generation number does not match, return NFS4ERR_FHEXPIRED. When the server reboots, the table is gone (it is volatile).
Top   ToC   RFC7530 - Page 35
   If the volatile bit is 0, then it is a persistent filehandle with a
   different structure following it.

4.3. Client Recovery from Filehandle Expiration

If possible, the client should recover from the receipt of an NFS4ERR_FHEXPIRED error. The client must take on additional responsibility so that it may prepare itself to recover from the expiration of a volatile filehandle. If the server returns persistent filehandles, the client does not need these additional steps. For volatile filehandles, most commonly the client will need to store the component names leading up to and including the file system object in question. With these names, the client should be able to recover by finding a filehandle in the namespace that is still available or by starting at the root of the server's file system namespace. If the expired filehandle refers to an object that has been removed from the file system, obviously the client will not be able to recover from the expired filehandle. It is also possible that the expired filehandle refers to a file that has been renamed. If the file was renamed by another client, again it is possible that the original client will not be able to recover. However, in the case that the client itself is renaming the file and the file is open, it is possible that the client may be able to recover. The client can determine the new pathname based on the processing of the rename request. The client can then regenerate the new filehandle based on the new pathname. The client could also use the COMPOUND operation mechanism to construct a set of operations like: RENAME A B LOOKUP B GETFH Note that the COMPOUND procedure does not provide atomicity. This example only reduces the overhead of recovering from an expired filehandle.

5. Attributes

To meet the requirements of extensibility and increased interoperability with non-UNIX platforms, attributes need to be handled in a flexible manner. The NFSv3 fattr3 structure contains a fixed list of attributes that not all clients and servers are able to
Top   ToC   RFC7530 - Page 36
   support or care about.  The fattr3 structure cannot be extended as
   new needs arise, and it provides no way to indicate non-support.
   With the NFSv4.0 protocol, the client is able to query what
   attributes the server supports and construct requests with only those
   supported attributes (or a subset thereof).

   To this end, attributes are divided into three groups: REQUIRED,
   RECOMMENDED, and named.  Both REQUIRED and RECOMMENDED attributes are
   supported in the NFSv4.0 protocol by a specific and well-defined
   encoding and are identified by number.  They are requested by setting
   a bit in the bit vector sent in the GETATTR request; the server
   response includes a bit vector to list what attributes were returned
   in the response.  New REQUIRED or RECOMMENDED attributes may be added
   to the NFSv4 protocol as part of a new minor version by publishing a
   Standards Track RFC that allocates a new attribute number value and
   defines the encoding for the attribute.  See Section 11 for further
   discussion.

   Named attributes are accessed by the OPENATTR operation, which
   accesses a hidden directory of attributes associated with a file
   system object.  OPENATTR takes a filehandle for the object and
   returns the filehandle for the attribute hierarchy.  The filehandle
   for the named attributes is a directory object accessible by LOOKUP
   or READDIR and contains files whose names represent the named
   attributes and whose data bytes are the value of the attribute.  For
   example:

        +----------+-----------+---------------------------------+
        | LOOKUP   | "foo"     | ; look up file                  |
        | GETATTR  | attrbits  |                                 |
        | OPENATTR |           | ; access foo's named attributes |
        | LOOKUP   | "x11icon" | ; look up specific attribute    |
        | READ     | 0,4096    | ; read stream of bytes          |
        +----------+-----------+---------------------------------+

   Named attributes are intended for data needed by applications rather
   than by an NFS client implementation.  NFS implementers are strongly
   encouraged to define their new attributes as RECOMMENDED attributes
   by bringing them to the IETF Standards Track process.

   The set of attributes that are classified as REQUIRED is deliberately
   small since servers need to do whatever it takes to support them.  A
   server should support as many of the RECOMMENDED attributes as
   possible; however, by their definition, the server is not required to
   support all of them.  Attributes are deemed REQUIRED if the data is
   both needed by a large number of clients and is not otherwise
   reasonably computable by the client when support is not provided on
   the server.
Top   ToC   RFC7530 - Page 37
   Note that the hidden directory returned by OPENATTR is a convenience
   for protocol processing.  The client should not make any assumptions
   about the server's implementation of named attributes and whether or
   not the underlying file system at the server has a named attribute
   directory.  Therefore, operations such as SETATTR and GETATTR on the
   named attribute directory are undefined.

5.1. REQUIRED Attributes

These attributes MUST be supported by every NFSv4.0 client and server in order to ensure a minimum level of interoperability. The server MUST store and return these attributes, and the client MUST be able to function with an attribute set limited to these attributes. With just the REQUIRED attributes, some client functionality can be impaired or limited in some ways. A client can ask for any of these attributes to be returned by setting a bit in the GETATTR request. For each such bit set, the server MUST return the corresponding attribute value.

5.2. RECOMMENDED Attributes

These attributes are understood well enough to warrant support in the NFSv4.0 protocol. However, they may not be supported on all clients and servers. A client MAY ask for any of these attributes to be returned by setting a bit in the GETATTR request but MUST handle the case where the server does not return them. A client MAY ask for the set of attributes the server supports and SHOULD NOT request attributes the server does not support. A server should be tolerant of requests for unsupported attributes and simply not return them, rather than considering the request an error. It is expected that servers will support all attributes they comfortably can and only fail to support attributes that are difficult to support in their operating environments. A server should provide attributes whenever they don't have to "tell lies" to the client. For example, a file modification time either should be an accurate time or should not be supported by the server. At times this will be difficult for clients, but a client is better positioned to decide whether and how to fabricate or construct an attribute or whether to do without the attribute.

5.3. Named Attributes

These attributes are not supported by direct encoding in the NFSv4 protocol but are accessed by string names rather than numbers and correspond to an uninterpreted stream of bytes that are stored with the file system object. The namespace for these attributes may be accessed by using the OPENATTR operation. The OPENATTR operation returns a filehandle for a virtual "named attribute directory", and
Top   ToC   RFC7530 - Page 38
   further perusal and modification of the namespace may be done using
   operations that work on more typical directories.  In particular,
   READDIR may be used to get a list of such named attributes, and
   LOOKUP and OPEN may select a particular attribute.  Creation of a new
   named attribute may be the result of an OPEN specifying file
   creation.

   Once an OPEN is done, named attributes may be examined and changed by
   normal READ and WRITE operations using the filehandles and stateids
   returned by OPEN.

   Named attributes and the named attribute directory may have their own
   (non-named) attributes.  Each of these objects must have all of the
   REQUIRED attributes and may have additional RECOMMENDED attributes.
   However, the set of attributes for named attributes and the named
   attribute directory need not be, and typically will not be, as large
   as that for other objects in that file system.

   Named attributes might be the target of delegations.  However, since
   granting of delegations is at the server's discretion, a server need
   not support delegations on named attributes.

   It is RECOMMENDED that servers support arbitrary named attributes.
   A client should not depend on the ability to store any named
   attributes in the server's file system.  If a server does support
   named attributes, a client that is also able to handle them should be
   able to copy a file's data and metadata with complete transparency
   from one location to another; this would imply that names allowed for
   regular directory entries are valid for named attribute names
   as well.

   In NFSv4.0, the structure of named attribute directories is
   restricted in a number of ways, in order to prevent the development
   of non-interoperable implementations in which some servers support a
   fully general hierarchical directory structure for named attributes
   while others support a limited but adequate structure for named
   attributes.  In such an environment, clients or applications might
   come to depend on non-portable extensions.  The restrictions are:

   o  CREATE is not allowed in a named attribute directory.  Thus, such
      objects as symbolic links and special files are not allowed to be
      named attributes.  Further, directories may not be created in a
      named attribute directory, so no hierarchical structure of named
      attributes for a single object is allowed.

   o  If OPENATTR is done on a named attribute directory or on a named
      attribute, the server MUST return an error.
Top   ToC   RFC7530 - Page 39
   o  Doing a RENAME of a named attribute to a different named attribute
      directory or to an ordinary (i.e., non-named-attribute) directory
      is not allowed.

   o  Creating hard links between named attribute directories or between
      named attribute directories and ordinary directories is not
      allowed.

   Names of attributes will not be controlled by this document or other
   IETF Standards Track documents.  See Section 20 for further
   discussion.

5.4. Classification of Attributes

Each of the attributes accessed using SETATTR and GETATTR (i.e., REQUIRED and RECOMMENDED attributes) can be classified in one of three categories: 1. per-server attributes for which the value of the attribute will be the same for all file objects that share the same server. 2. per-file system attributes for which the value of the attribute will be the same for some or all file objects that share the same server and fsid attribute (Section 5.8.1.9). See below for details regarding when such sharing is in effect. 3. per-file system object attributes. The handling of per-file system attributes depends on the particular attribute and the setting of the homogeneous (Section 5.8.2.12) attribute. The following rules apply: 1. The values of the attributes supported_attrs, fsid, homogeneous, link_support, and symlink_support are always common to all objects within the given file system. 2. For other attributes, different values may be returned for different file system objects if the attribute homogeneous is supported within the file system in question and has the value false. The classification of attributes is as follows. Note that the attributes time_access_set and time_modify_set are not listed in this section, because they are write-only attributes corresponding to time_access and time_modify and are used in a special instance of SETATTR.
Top   ToC   RFC7530 - Page 40
   o  The per-server attribute is:

         lease_time

   o  The per-file system attributes are:

         supported_attrs, fh_expire_type, link_support, symlink_support,
         unique_handles, aclsupport, cansettime, case_insensitive,
         case_preserving, chown_restricted, files_avail, files_free,
         files_total, fs_locations, homogeneous, maxfilesize, maxname,
         maxread, maxwrite, no_trunc, space_avail, space_free,
         space_total, and time_delta

   o  The per-file system object attributes are:

         type, change, size, named_attr, fsid, rdattr_error, filehandle,
         acl, archive, fileid, hidden, maxlink, mimetype, mode,
         numlinks, owner, owner_group, rawdev, space_used, system,
         time_access, time_backup, time_create, time_metadata,
         time_modify, and mounted_on_fileid

   For quota_avail_hard, quota_avail_soft, and quota_used, see their
   definitions below for the appropriate classification.

5.5. Set-Only and Get-Only Attributes

Some REQUIRED and RECOMMENDED attributes are set-only; i.e., they can be set via SETATTR but not retrieved via GETATTR. Similarly, some REQUIRED and RECOMMENDED attributes are get-only; i.e., they can be retrieved via GETATTR but not set via SETATTR. If a client attempts to set a get-only attribute or get a set-only attribute, the server MUST return NFS4ERR_INVAL.

5.6. REQUIRED Attributes - List and Definition References

The list of REQUIRED attributes appears in Table 3. The meanings of the columns of the table are: o Name: The name of the attribute. o ID: The number assigned to the attribute. In the event of conflicts between the assigned number and [RFC7531], the latter is authoritative, but in such an event, it should be resolved with errata to this document and/or [RFC7531]. See [IESG_ERRATA] for the errata process. o Data Type: The XDR data type of the attribute.
Top   ToC   RFC7530 - Page 41
   o  Acc: Access allowed to the attribute.  R means read-only (GETATTR
      may retrieve, SETATTR may not set).  W means write-only (SETATTR
      may set, GETATTR may not retrieve).  R W means read/write (GETATTR
      may retrieve, SETATTR may set).

   o  Defined in: The section of this specification that describes the
      attribute.

      +-----------------+----+------------+-----+-------------------+
      | Name            | ID | Data Type  | Acc | Defined in        |
      +-----------------+----+------------+-----+-------------------+
      | supported_attrs | 0  | bitmap4    | R   | Section 5.8.1.1   |
      | type            | 1  | nfs_ftype4 | R   | Section 5.8.1.2   |
      | fh_expire_type  | 2  | uint32_t   | R   | Section 5.8.1.3   |
      | change          | 3  | changeid4  | R   | Section 5.8.1.4   |
      | size            | 4  | uint64_t   | R W | Section 5.8.1.5   |
      | link_support    | 5  | bool       | R   | Section 5.8.1.6   |
      | symlink_support | 6  | bool       | R   | Section 5.8.1.7   |
      | named_attr      | 7  | bool       | R   | Section 5.8.1.8   |
      | fsid            | 8  | fsid4      | R   | Section 5.8.1.9   |
      | unique_handles  | 9  | bool       | R   | Section 5.8.1.10  |
      | lease_time      | 10 | nfs_lease4 | R   | Section 5.8.1.11  |
      | rdattr_error    | 11 | nfsstat4   | R   | Section 5.8.1.12  |
      | filehandle      | 19 | nfs_fh4    | R   | Section 5.8.1.13  |
      +-----------------+----+------------+-----+-------------------+

                       Table 3: REQUIRED Attributes

5.7. RECOMMENDED Attributes - List and Definition References

The RECOMMENDED attributes are defined in Table 4. The meanings of the column headers are the same as Table 3; see Section 5.6 for the meanings. +-------------------+----+-----------------+-----+------------------+ | Name | ID | Data Type | Acc | Defined in | +-------------------+----+-----------------+-----+------------------+ | acl | 12 | nfsace4<> | R W | Section 6.2.1 | | aclsupport | 13 | uint32_t | R | Section 6.2.1.2 | | archive | 14 | bool | R W | Section 5.8.2.1 | | cansettime | 15 | bool | R | Section 5.8.2.2 | | case_insensitive | 16 | bool | R | Section 5.8.2.3 | | case_preserving | 17 | bool | R | Section 5.8.2.4 | | chown_restricted | 18 | bool | R | Section 5.8.2.5 | | fileid | 20 | uint64_t | R | Section 5.8.2.6 | | files_avail | 21 | uint64_t | R | Section 5.8.2.7 | | files_free | 22 | uint64_t | R | Section 5.8.2.8 | | files_total | 23 | uint64_t | R | Section 5.8.2.9 |
Top   ToC   RFC7530 - Page 42
   | fs_locations      | 24 | fs_locations4   | R   | Section 5.8.2.10 |
   | hidden            | 25 | bool            | R W | Section 5.8.2.11 |
   | homogeneous       | 26 | bool            | R   | Section 5.8.2.12 |
   | maxfilesize       | 27 | uint64_t        | R   | Section 5.8.2.13 |
   | maxlink           | 28 | uint32_t        | R   | Section 5.8.2.14 |
   | maxname           | 29 | uint32_t        | R   | Section 5.8.2.15 |
   | maxread           | 30 | uint64_t        | R   | Section 5.8.2.16 |
   | maxwrite          | 31 | uint64_t        | R   | Section 5.8.2.17 |
   | mimetype          | 32 | ascii_          | R W | Section 5.8.2.18 |
   |                   |    |   REQUIRED4<>   |     |                  |
   | mode              | 33 | mode4           | R W | Section 6.2.2    |
   | mounted_on_fileid | 55 | uint64_t        | R   | Section 5.8.2.19 |
   | no_trunc          | 34 | bool            | R   | Section 5.8.2.20 |
   | numlinks          | 35 | uint32_t        | R   | Section 5.8.2.21 |
   | owner             | 36 | utf8str_mixed   | R W | Section 5.8.2.22 |
   | owner_group       | 37 | utf8str_mixed   | R W | Section 5.8.2.23 |
   | quota_avail_hard  | 38 | uint64_t        | R   | Section 5.8.2.24 |
   | quota_avail_soft  | 39 | uint64_t        | R   | Section 5.8.2.25 |
   | quota_used        | 40 | uint64_t        | R   | Section 5.8.2.26 |
   | rawdev            | 41 | specdata4       | R   | Section 5.8.2.27 |
   | space_avail       | 42 | uint64_t        | R   | Section 5.8.2.28 |
   | space_free        | 43 | uint64_t        | R   | Section 5.8.2.29 |
   | space_total       | 44 | uint64_t        | R   | Section 5.8.2.30 |
   | space_used        | 45 | uint64_t        | R   | Section 5.8.2.31 |
   | system            | 46 | bool            | R W | Section 5.8.2.32 |
   | time_access       | 47 | nfstime4        | R   | Section 5.8.2.33 |
   | time_access_set   | 48 | settime4        | W   | Section 5.8.2.34 |
   | time_backup       | 49 | nfstime4        | R W | Section 5.8.2.35 |
   | time_create       | 50 | nfstime4        | R W | Section 5.8.2.36 |
   | time_delta        | 51 | nfstime4        | R   | Section 5.8.2.37 |
   | time_metadata     | 52 | nfstime4        | R   | Section 5.8.2.38 |
   | time_modify       | 53 | nfstime4        | R   | Section 5.8.2.39 |
   | time_modify_set   | 54 | settime4        | W   | Section 5.8.2.40 |
   +-------------------+----+-----------------+-----+------------------+

                      Table 4: RECOMMENDED Attributes

5.8. Attribute Definitions

5.8.1. Definitions of REQUIRED Attributes

5.8.1.1. Attribute 0: supported_attrs
The bit vector that would retrieve all REQUIRED and RECOMMENDED attributes that are supported for this object. The scope of this attribute applies to all objects with a matching fsid.
Top   ToC   RFC7530 - Page 43
5.8.1.2. Attribute 1: type
Designates the type of an object in terms of one of a number of special constants: o NF4REG designates a regular file. o NF4DIR designates a directory. o NF4BLK designates a block device special file. o NF4CHR designates a character device special file. o NF4LNK designates a symbolic link. o NF4SOCK designates a named socket special file. o NF4FIFO designates a fifo special file. o NF4ATTRDIR designates a named attribute directory. o NF4NAMEDATTR designates a named attribute. Within the explanatory text and operation descriptions, the following phrases will be used with the meanings given below: o The phrase "is a directory" means that the object's type attribute is NF4DIR or NF4ATTRDIR. o The phrase "is a special file" means that the object's type attribute is NF4BLK, NF4CHR, NF4SOCK, or NF4FIFO. o The phrase "is a regular file" means that the object's type attribute is NF4REG or NF4NAMEDATTR. o The phrase "is a symbolic link" means that the object's type attribute is NF4LNK.
5.8.1.3. Attribute 2: fh_expire_type
The server uses this to specify filehandle expiration behavior to the client. See Section 4 for additional description.
Top   ToC   RFC7530 - Page 44
5.8.1.4. Attribute 3: change
A value created by the server that the client can use to determine if file data, directory contents, or attributes of the object have been modified. The server MAY return the object's time_metadata attribute for this attribute's value but only if the file system object cannot be updated more frequently than the resolution of time_metadata.
5.8.1.5. Attribute 4: size
The size of the object in bytes.
5.8.1.6. Attribute 5: link_support
TRUE, if the object's file system supports hard links.
5.8.1.7. Attribute 6: symlink_support
TRUE, if the object's file system supports symbolic links.
5.8.1.8. Attribute 7: named_attr
TRUE, if this object has named attributes. In other words, this object has a non-empty named attribute directory.
5.8.1.9. Attribute 8: fsid
Unique file system identifier for the file system holding this object. The fsid attribute has major and minor components, each of which are of data type uint64_t.
5.8.1.10. Attribute 9: unique_handles
TRUE, if two distinct filehandles are guaranteed to refer to two different file system objects.
5.8.1.11. Attribute 10: lease_time
Duration of the lease at the server in seconds.
5.8.1.12. Attribute 11: rdattr_error
Error returned from an attempt to retrieve attributes during a READDIR operation.
5.8.1.13. Attribute 19: filehandle
The filehandle of this object (primarily for READDIR requests).
Top   ToC   RFC7530 - Page 45

5.8.2. Definitions of Uncategorized RECOMMENDED Attributes

The definitions of most of the RECOMMENDED attributes follow. Collections that share a common category are defined in other sections.
5.8.2.1. Attribute 14: archive
TRUE, if this file has been archived since the time of the last modification (deprecated in favor of time_backup).
5.8.2.2. Attribute 15: cansettime
TRUE, if the server is able to change the times for a file system object as specified in a SETATTR operation.
5.8.2.3. Attribute 16: case_insensitive
TRUE, if filename comparisons on this file system are case insensitive. This refers only to comparisons, and not to the case in which filenames are stored.
5.8.2.4. Attribute 17: case_preserving
TRUE, if the filename case on this file system is preserved. This refers only to how filenames are stored, and not to how they are compared. Filenames stored in mixed case might be compared using either case-insensitive or case-sensitive comparisons.
5.8.2.5. Attribute 18: chown_restricted
If TRUE, the server will reject any request to change either the owner or the group associated with a file if the caller is not a privileged user (for example, "root" in UNIX operating environments or the "Take Ownership" privilege in Windows 2000).
5.8.2.6. Attribute 20: fileid
A number uniquely identifying the file within the file system.
5.8.2.7. Attribute 21: files_avail
File slots available to this user on the file system containing this object -- this should be the smallest relevant limit.
Top   ToC   RFC7530 - Page 46
5.8.2.8. Attribute 22: files_free
Free file slots on the file system containing this object -- this should be the smallest relevant limit.
5.8.2.9. Attribute 23: files_total
Total file slots on the file system containing this object.
5.8.2.10. Attribute 24: fs_locations
Locations where this file system may be found. If the server returns NFS4ERR_MOVED as an error, this attribute MUST be supported. The server specifies the rootpath for a given server by returning a path consisting of zero path components.
5.8.2.11. Attribute 25: hidden
TRUE, if the file is considered hidden with respect to the Windows API.
5.8.2.12. Attribute 26: homogeneous
TRUE, if this object's file system is homogeneous, i.e., all objects in the file system (all objects on the server with the same fsid) have common values for all per-file system attributes.
5.8.2.13. Attribute 27: maxfilesize
Maximum supported file size for the file system of this object.
5.8.2.14. Attribute 28: maxlink
Maximum number of hard links for this object.
5.8.2.15. Attribute 29: maxname
Maximum filename size supported for this object.
5.8.2.16. Attribute 30: maxread
Maximum amount of data the READ operation will return for this object.
Top   ToC   RFC7530 - Page 47
5.8.2.17. Attribute 31: maxwrite
Maximum amount of data the WRITE operation will accept for this object. This attribute SHOULD be supported if the file is writable. Lack of this attribute can lead to the client either wasting bandwidth or not receiving the best performance.
5.8.2.18. Attribute 32: mimetype
MIME media type/subtype of this object.
5.8.2.19. Attribute 55: mounted_on_fileid
Like fileid, but if the target filehandle is the root of a file system, this attribute represents the fileid of the underlying directory. UNIX-based operating environments connect a file system into the namespace by connecting (mounting) the file system onto the existing file object (the mount point, usually a directory) of an existing file system. When the mount point's parent directory is read via an API such as readdir() [readdir_api], the return results are directory entries, each with a component name and a fileid. The fileid of the mount point's directory entry will be different from the fileid that the stat() [stat] system call returns. The stat() system call is returning the fileid of the root of the mounted file system, whereas readdir() is returning the fileid that stat() would have returned before any file systems were mounted on the mount point. Unlike NFSv3, NFSv4.0 allows a client's LOOKUP request to cross other file systems. The client detects the file system crossing whenever the filehandle argument of LOOKUP has an fsid attribute different from that of the filehandle returned by LOOKUP. A UNIX-based client will consider this a "mount point crossing". UNIX has a legacy scheme for allowing a process to determine its current working directory. This relies on readdir() of a mount point's parent and stat() of the mount point returning fileids as previously described. The mounted_on_fileid attribute corresponds to the fileid that readdir() would have returned, as described previously. While the NFSv4.0 client could simply fabricate a fileid corresponding to what mounted_on_fileid provides (and if the server does not support mounted_on_fileid, the client has no choice), there is a risk that the client will generate a fileid that conflicts with one that is already assigned to another object in the file system. Instead, if the server can provide the mounted_on_fileid, the potential for client operational problems in this area is eliminated.
Top   ToC   RFC7530 - Page 48
   If the server detects that there is nothing mounted on top of the
   target file object, then the value for mounted_on_fileid that it
   returns is the same as that of the fileid attribute.

   The mounted_on_fileid attribute is RECOMMENDED, so the server SHOULD
   provide it if possible, and for a UNIX-based server, this is
   straightforward.  Usually, mounted_on_fileid will be requested during
   a READDIR operation, in which case it is trivial (at least for
   UNIX-based servers) to return mounted_on_fileid since it is equal to
   the fileid of a directory entry returned by readdir().  If
   mounted_on_fileid is requested in a GETATTR operation, the server
   should obey an invariant that has it returning a value that is equal
   to the file object's entry in the object's parent directory, i.e.,
   what readdir() would have returned.  Some operating environments
   allow a series of two or more file systems to be mounted onto a
   single mount point.  In this case, for the server to obey the
   aforementioned invariant, it will need to find the base mount point,
   and not the intermediate mount points.

5.8.2.20. Attribute 34: no_trunc
If this attribute is TRUE, then if the client uses a filename longer than name_max, an error will be returned instead of the name being truncated.
5.8.2.21. Attribute 35: numlinks
Number of hard links to this object.
5.8.2.22. Attribute 36: owner
The string name of the owner of this object.
5.8.2.23. Attribute 37: owner_group
The string name of the group ownership of this object.
5.8.2.24. Attribute 38: quota_avail_hard
The value in bytes that represents the amount of additional disk space beyond the current allocation that can be allocated to this file or directory before further allocations will be refused. It is understood that this space may be consumed by allocations to other files or directories.
Top   ToC   RFC7530 - Page 49
5.8.2.25. Attribute 39: quota_avail_soft
The value in bytes that represents the amount of additional disk space that can be allocated to this file or directory before the user may reasonably be warned. It is understood that this space may be consumed by allocations to other files or directories, though there may exist server-side rules as to which other files or directories.
5.8.2.26. Attribute 40: quota_used
The value in bytes that represents the amount of disk space used by this file or directory and possibly a number of other similar files or directories, where the set of "similar" meets at least the criterion that allocating space to any file or directory in the set will reduce the "quota_avail_hard" of every other file or directory in the set. Note that there may be a number of distinct but overlapping sets of files or directories for which a quota_used value is maintained, e.g., "all files with a given owner", "all files with a given group owner", etc. The server is at liberty to choose any of those sets when providing the content of the quota_used attribute but should do so in a repeatable way. The rule may be configured per file system or may be "choose the set with the smallest quota".
5.8.2.27. Attribute 41: rawdev
Raw device number of file of type NF4BLK or NF4CHR. The device number is split into major and minor numbers. If the file's type attribute is not NF4BLK or NF4CHR, this attribute SHOULD NOT be returned, and any value returned SHOULD NOT be considered useful.
5.8.2.28. Attribute 42: space_avail
Disk space in bytes available to this user on the file system containing this object -- this should be the smallest relevant limit.
5.8.2.29. Attribute 43: space_free
Free disk space in bytes on the file system containing this object -- this should be the smallest relevant limit.
5.8.2.30. Attribute 44: space_total
Total disk space in bytes on the file system containing this object.
Top   ToC   RFC7530 - Page 50
5.8.2.31. Attribute 45: space_used
Number of file system bytes allocated to this object.
5.8.2.32. Attribute 46: system
TRUE, if this file is a "system" file with respect to the Windows operating environment.
5.8.2.33. Attribute 47: time_access
Represents the time of last access to the object by a READ operation sent to the server. The notion of what is an "access" depends on the server's operating environment and/or the server's file system semantics. For example, for servers obeying Portable Operating System Interface (POSIX) semantics, time_access would be updated only by the READ and READDIR operations and not any of the operations that modify the content of the object [read_api], [readdir_api], [write_api]. Of course, setting the corresponding time_access_set attribute is another way to modify the time_access attribute. Whenever the file object resides on a writable file system, the server should make its best efforts to record time_access into stable storage. However, to mitigate the performance effects of doing so, and most especially whenever the server is satisfying the read of the object's content from its cache, the server MAY cache access time updates and lazily write them to stable storage. It is also acceptable to give administrators of the server the option to disable time_access updates.
5.8.2.34. Attribute 48: time_access_set
Sets the time of last access to the object. SETATTR use only.
5.8.2.35. Attribute 49: time_backup
The time of last backup of the object.
5.8.2.36. Attribute 50: time_create
The time of creation of the object. This attribute does not have any relation to the traditional UNIX file attribute "ctime" ("change time").
5.8.2.37. Attribute 51: time_delta
Smallest useful server time granularity.
Top   ToC   RFC7530 - Page 51
5.8.2.38. Attribute 52: time_metadata
The time of last metadata modification of the object.
5.8.2.39. Attribute 53: time_modify
The time of last modification to the object.
5.8.2.40. Attribute 54: time_modify_set
Sets the time of last modification to the object. SETATTR use only.

5.9. Interpreting owner and owner_group

The RECOMMENDED attributes "owner" and "owner_group" (and also users and groups used as values of the who field within nfs4ace structures used in the acl attribute) are represented in the form of UTF-8 strings. This format avoids the use of a representation that is tied to a particular underlying implementation at the client or server. Note that Section 6.1 of [RFC2624] provides additional rationale. It is expected that the client and server will have their own local representation of owners and groups that is used for local storage or presentation to the application via APIs that expect such a representation. Therefore, the protocol requires that when these attributes are transferred between the client and server, the local representation is translated to a string of the form "identifier@dns_domain". This allows clients and servers that do not use the same local representation to effectively interoperate since they both use a common syntax that can be interpreted by both. Similarly, security principals may be represented in different ways by different security mechanisms. Servers normally translate these representations into a common format, generally that used by local storage, to serve as a means of identifying the users corresponding to these security principals. When these local identifiers are translated to the form of the owner attribute, associated with files created by such principals, they identify, in a common format, the users associated with each corresponding set of security principals. The translation used to interpret owner and group strings is not specified as part of the protocol. This allows various solutions to be employed. For example, a local translation table may be consulted that maps a numeric identifier to the user@dns_domain syntax. A name service may also be used to accomplish the translation. A server may provide a more general service, not limited by any particular translation (which would only translate a limited set of possible strings) by storing the owner and owner_group attributes in local storage without any translation, or it may augment a translation
Top   ToC   RFC7530 - Page 52
   method by storing the entire string for attributes for which no
   translation is available while using the local representation for
   those cases in which a translation is available.

   Servers that do not provide support for all possible values of user
   and group strings SHOULD return an error (NFS4ERR_BADOWNER) when a
   string is presented that has no translation, as the value to be set
   for a SETATTR of the owner or owner_group attributes or as part of
   the value of the acl attribute.  When a server does accept a user or
   group string as valid on a SETATTR, it is promising to return that
   same string (see below) when a corresponding GETATTR is done, as long
   as there has been no further change in the corresponding attribute
   before the GETATTR.  For some internationalization-related exceptions
   where this is not possible, see below.  Configuration changes
   (including changes from the mapping of the string to the local
   representation) and ill-constructed name translations (those that
   contain aliasing) may make that promise impossible to honor.  Servers
   should make appropriate efforts to avoid a situation in which these
   attributes have their values changed when no real change to either
   ownership or acls has occurred.

   The "dns_domain" portion of the owner string is meant to be a DNS
   domain name -- for example, "user@example.org".  Servers should
   accept as valid a set of users for at least one domain.  A server may
   treat other domains as having no valid translations.  A more general
   service is provided when a server is capable of accepting users for
   multiple domains, or for all domains, subject to security
   constraints.

   As an implementation guide, both clients and servers may provide a
   means to configure the "dns_domain" portion of the owner string.  For
   example, the DNS domain name of the host running the NFS server might
   be "lab.example.org", but the user names are defined in
   "example.org".  In the absence of such a configuration, or as a
   default, the current DNS domain name of the server should be the
   value used for the "dns_domain".

   As mentioned above, it is desirable that a server, when accepting a
   string of the form "user@domain" or "group@domain" in an attribute,
   return this same string when that corresponding attribute is fetched.
   Internationalization issues make this impossible under certain
   circumstances, and the client needs to take note of these.  See
   Section 12 for a detailed discussion of these issues.

   In the case where there is no translation available to the client or
   server, the attribute value will be constructed without the "@".
   Therefore, the absence of the "@" from the owner or owner_group
   attribute signifies that no translation was available at the sender
Top   ToC   RFC7530 - Page 53
   and that the receiver of the attribute should not use that string as
   a basis for translation into its own internal format.  Even though
   the attribute value cannot be translated, it may still be useful.  In
   the case of a client, the attribute string may be used for local
   display of ownership.

   To provide a greater degree of compatibility with NFSv3, which
   identified users and groups by 32-bit unsigned user identifiers and
   group identifiers, owner and group strings that consist of ASCII-
   encoded decimal numeric values with no leading zeros can be given a
   special interpretation by clients and servers that choose to provide
   such support.  The receiver may treat such a user or group string as
   representing the same user as would be represented by an NFSv3 uid or
   gid having the corresponding numeric value.

   A server SHOULD reject such a numeric value if the security mechanism
   is using Kerberos.  That is, in such a scenario, the client will
   already need to form "user@domain" strings.  For any other security
   mechanism, the server SHOULD accept such numeric values.  As an
   implementation note, the server could make such an acceptance be
   configurable.  If the server does not support numeric values or if it
   is configured off, then it MUST return an NFS4ERR_BADOWNER error.  If
   the security mechanism is using Kerberos and the client attempts to
   use the special form, then the server SHOULD return an
   NFS4ERR_BADOWNER error when there is a valid translation for the user
   or owner designated in this way.  In that case, the client must use
   the appropriate user@domain string and not the special form for
   compatibility.

   The client MUST always accept numeric values if the security
   mechanism is not RPCSEC_GSS.  A client can determine if a server
   supports numeric identifiers by first attempting to provide a numeric
   identifier.  If this attempt is rejected with an NFS4ERR_BADOWNER
   error, then the client should only use named identifiers of the form
   "user@dns_domain".

   The owner string "nobody" may be used to designate an anonymous user,
   which will be associated with a file created by a security principal
   that cannot be mapped through normal means to the owner attribute.

5.10. Character Case Attributes

With respect to the case_insensitive and case_preserving attributes, case-insensitive comparisons of Unicode characters SHOULD use Unicode Default Case Folding as defined in Chapter 3 of the Unicode Standard [UNICODE] and MAY override that behavior for specific selected characters with the case folding defined in the SpecialCasing.txt [SPECIALCASING] file; see Section 3.13 of the Unicode Standard.
Top   ToC   RFC7530 - Page 54
   The SpecialCasing.txt file replaces the Default Case Folding with
   locale- and context-dependent case folding for specific situations.
   An example of locale- and context-dependent case folding is that
   LATIN CAPITAL LETTER I ("I", U+0049) is default case folded to LATIN
   SMALL LETTER I ("i", U+0069).  However, several languages (e.g.,
   Turkish) treat an "I" character with a dot as a different letter than
   an "I" character without a dot; therefore, in such languages, unless
   an I is before a dot_above, the "I" (U+0049) character should be case
   folded to a different character, LATIN SMALL LETTER DOTLESS I
   (U+0131).

   The [UNICODE] and [SPECIALCASING] references in this RFC are for
   version 7.0.0 of the Unicode standard, as that was the latest version
   of Unicode when this RFC was published.  Implementations SHOULD
   always use the latest version of Unicode
   (<http://www.unicode.org/versions/latest/>).



(page 54 continued on part 4)

Next Section