tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 7530

 
 
 

Network File System (NFS) Version 4 Protocol

Part 3 of 14, p. 30 to 54
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 30 
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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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 RFC Part