Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 5661

Network File System (NFS) Version 4 Minor Version 1 Protocol

Pages: 617
Obsoleted by:  8881
Updated by:  81788434
Part 5 of 20 – Pages 97 to 126
First   Prev   Next

Top   ToC   RFC5661 - Page 97   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.
Top   ToC   RFC5661 - Page 98

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 NFSv3 protocol (RFC 1813 [31]), 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, which 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 RFC 2054 [42] and RFC 2055 [43]. With the use of the public filehandle in combination with the LOOKUP operation in the NFSv3 protocol, it has been demonstrated that the MOUNT protocol is unnecessary for viable interaction between NFS client and server. Therefore, the NFSv4.1 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.
Top   ToC   RFC5661 - Page 99

4.2. Filehandle Types

In the NFSv3 protocol, there was one type of filehandle with a single set of semantics. This type of filehandle is termed "persistent" in NFSv4.1. The semantics of a persistent filehandle remain the same as before. A new type of filehandle introduced in NFSv4.1 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 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. Servers SHOULD try to maintain a one-to-one correspondence between filehandles and files, but this is not required. 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 filehandles denote the same object and in such cases, avoid making invalid assumptions that 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
Top   ToC   RFC5661 - Page 100
   occur if a hard link (see [6]) is used to create two file names 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 pathnames'
   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 the object. If the server restarts, 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 be 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 the file system in whole has been destroyed or 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:
Top   ToC   RFC5661 - Page 101
   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_NO_EXPIRE_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.

   FH4_VOL_MIGRATION  The filehandle will expire as a result of a file
      system transition (migration or replication), in those cases in
      which the continuity of filehandle use is not specified by handle
      class information within the fs_locations_info attribute.  When
      this bit is set, clients without access to fs_locations_info
      information should assume that filehandles will expire on file
      system transitions.

   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_VOL_ANY is set, FH4_VOL_RENAME is redundant.

   Servers that provide volatile filehandles that can expire while open
   require special care as regards handling of RENAMEs and REMOVEs.
   This situation can arise if FH4_VOL_MIGRATION or FH4_VOL_RENAME is
   set, if FH4_VOLATILE_ANY is set and FH4_NOEXPIRE_WITH_OPEN is not
   set, or if a non-read-only file system has a transition target in a
   different handle class.  In these cases, the server 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, in order
   to make sure that reclaims of files where filehandles may have
   expired do not do a reclaim for the wrong file.

   Volatile filehandles are especially suitable for implementation of
   the pseudo file systems used to bridge exports.  See Section 7.5 for
   a discussion of this.

4.3. 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]
Top   ToC   RFC5661 - Page 102
   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 restarts, the table is gone (it is volatile).

   If the volatile bit is 0, then it is a persistent filehandle with a
   different structure following it.

4.4. 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 procedure to construct a series of operations like:
Top   ToC   RFC5661 - Page 103
             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. File 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 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.1 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.1 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 2.7 for further discussion. Named attributes are accessed by the new 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 | +----------+-----------+---------------------------------+
Top   ToC   RFC5661 - Page 104
   Named attributes are intended for data needed by applications rather
   than by an NFS client implementation.  NFS implementors 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 but, 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.

   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 MUST be supported by every NFSv4.1 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 may be impaired or limited in some ways. A client may ask for any of these attributes to be returned by setting a bit in the GETATTR request, and the server MUST return their value.

5.2. RECOMMENDED Attributes

These attributes are understood well enough to warrant support in the NFSv4.1 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 should be either an accurate time or should not be
Top   ToC   RFC5661 - Page 105
   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 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 and the named attribute directory might be the target of delegations (in the case of the named attribute directory, these will be directory delegations). However, since granting delegations is at the server's discretion, a server need not support delegations on named attributes or the named attribute directory. 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.
Top   ToC   RFC5661 - Page 106
   In NFSv4.1, 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 NFS4ERR_WRONG_TYPE.

   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 22.1 for further
   discussion.

5.4. Classification of Attributes

Each of the REQUIRED and RECOMMENDED attributes can be classified in one of three categories: per server (i.e., the value of the attribute will be the same for all file objects that share the same server owner; see Section 2.5 for a definition of server owner), per file system (i.e., the value of the attribute will be the same for some or all file objects that share the same fsid attribute (Section 5.8.1.9) and server owner), or per file system object. Note that it is possible that some per file system attributes may vary within the file system, depending on the value of the "homogeneous" (Section 5.8.2.16) attribute. 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. o The per-server attribute is: lease_time
Top   ToC   RFC5661 - Page 107
   o  The per-file system attributes are:

         supported_attrs, suppattr_exclcreat, 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,
         time_delta, change_policy, fs_status, fs_layout_type,
         fs_locations_info, fs_charset_cap

   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, mounted_on_fileid, dir_notif_delay,
         dirent_notif_delay, dacl, sacl, layout_type, layout_hint,
         layout_blksize, layout_alignment, mdsthreshold, retention_get,
         retention_set, retentevt_get, retentevt_set, retention_hold,
         mode_set_masked

   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 attributes, the server MUST return NFS4ERR_INVAL.

5.6. REQUIRED Attributes - List and Definition References

The list of REQUIRED attributes appears in Table 2. The meaning 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 [13], the latter is likely authoritative, but should be resolved with Errata to this document and/or [13]. See [44] for the Errata process. o Data Type: The XDR data type of the attribute.
Top   ToC   RFC5661 - Page 108
   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  | uint64_t   | 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 | enum       | R   | Section 5.8.1.12 |
     | filehandle         | 19 | nfs_fh4    | R   | Section 5.8.1.13 |
     | suppattr_exclcreat | 75 | bitmap4    | R   | Section 5.8.1.14 |
     +--------------------+----+------------+-----+------------------+

                                  Table 2

5.7. RECOMMENDED Attributes - List and Definition References

The RECOMMENDED attributes are defined in Table 3. The meanings of the column headers are the same as Table 2; see Section 5.6 for the meanings.
Top   ToC   RFC5661 - Page 109
   +--------------------+----+----------------+-----+------------------+
   | 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  |
   | change_policy      | 60 | chg_policy4    | R   | Section 5.8.2.5  |
   | chown_restricted   | 18 | bool           | R   | Section 5.8.2.6  |
   | dacl               | 58 | nfsacl41       | R W | Section 6.2.2    |
   | dir_notif_delay    | 56 | nfstime4       | R   | Section 5.11.1   |
   | dirent_notif_delay | 57 | nfstime4       | R   | Section 5.11.2   |
   | fileid             | 20 | uint64_t       | R   | Section 5.8.2.7  |
   | files_avail        | 21 | uint64_t       | R   | Section 5.8.2.8  |
   | files_free         | 22 | uint64_t       | R   | Section 5.8.2.9  |
   | files_total        | 23 | uint64_t       | R   | Section 5.8.2.10 |
   | fs_charset_cap     | 76 | uint32_t       | R   | Section 5.8.2.11 |
   | fs_layout_type     | 62 | layouttype4<>  | R   | Section 5.12.1   |
   | fs_locations       | 24 | fs_locations   | R   | Section 5.8.2.12 |
   | fs_locations_info  | 67 | *              | R   | Section 5.8.2.13 |
   | fs_status          | 61 | fs4_status     | R   | Section 5.8.2.14 |
   | hidden             | 25 | bool           | R W | Section 5.8.2.15 |
   | homogeneous        | 26 | bool           | R   | Section 5.8.2.16 |
   | layout_alignment   | 66 | uint32_t       | R   | Section 5.12.2   |
   | layout_blksize     | 65 | uint32_t       | R   | Section 5.12.3   |
   | layout_hint        | 63 | layouthint4    |   W | Section 5.12.4   |
   | layout_type        | 64 | layouttype4<>  | R   | Section 5.12.5   |
   | maxfilesize        | 27 | uint64_t       | R   | Section 5.8.2.17 |
   | maxlink            | 28 | uint32_t       | R   | Section 5.8.2.18 |
   | maxname            | 29 | uint32_t       | R   | Section 5.8.2.19 |
   | maxread            | 30 | uint64_t       | R   | Section 5.8.2.20 |
   | maxwrite           | 31 | uint64_t       | R   | Section 5.8.2.21 |
   | mdsthreshold       | 68 | mdsthreshold4  | R   | Section 5.12.6   |
   | mimetype           | 32 | utf8str_cs     | R W | Section 5.8.2.22 |
   | mode               | 33 | mode4          | R W | Section 6.2.4    |
   | mode_set_masked    | 74 | mode_masked4   |   W | Section 6.2.5    |
   | mounted_on_fileid  | 55 | uint64_t       | R   | Section 5.8.2.23 |
   | no_trunc           | 34 | bool           | R   | Section 5.8.2.24 |
   | numlinks           | 35 | uint32_t       | R   | Section 5.8.2.25 |
   | owner              | 36 | utf8str_mixed  | R W | Section 5.8.2.26 |
   | owner_group        | 37 | utf8str_mixed  | R W | Section 5.8.2.27 |
   | quota_avail_hard   | 38 | uint64_t       | R   | Section 5.8.2.28 |
   | quota_avail_soft   | 39 | uint64_t       | R   | Section 5.8.2.29 |
   | quota_used         | 40 | uint64_t       | R   | Section 5.8.2.30 |
   | rawdev             | 41 | specdata4      | R   | Section 5.8.2.31 |
   | retentevt_get      | 71 | retention_get4 | R   | Section 5.13.3   |
Top   ToC   RFC5661 - Page 110
   | retentevt_set      | 72 | retention_set4 |   W | Section 5.13.4   |
   | retention_get      | 69 | retention_get4 | R   | Section 5.13.1   |
   | retention_hold     | 73 | uint64_t       | R W | Section 5.13.5   |
   | retention_set      | 70 | retention_set4 |   W | Section 5.13.2   |
   | sacl               | 59 | nfsacl41       | R W | Section 6.2.3    |
   | space_avail        | 42 | uint64_t       | R   | Section 5.8.2.32 |
   | space_free         | 43 | uint64_t       | R   | Section 5.8.2.33 |
   | space_total        | 44 | uint64_t       | R   | Section 5.8.2.34 |
   | space_used         | 45 | uint64_t       | R   | Section 5.8.2.35 |
   | system             | 46 | bool           | R W | Section 5.8.2.36 |
   | time_access        | 47 | nfstime4       | R   | Section 5.8.2.37 |
   | time_access_set    | 48 | settime4       |   W | Section 5.8.2.38 |
   | time_backup        | 49 | nfstime4       | R W | Section 5.8.2.39 |
   | time_create        | 50 | nfstime4       | R W | Section 5.8.2.40 |
   | time_delta         | 51 | nfstime4       | R   | Section 5.8.2.41 |
   | time_metadata      | 52 | nfstime4       | R   | Section 5.8.2.42 |
   | time_modify        | 53 | nfstime4       | R   | Section 5.8.2.43 |
   | time_modify_set    | 54 | settime4       |   W | Section 5.8.2.44 |
   +--------------------+----+----------------+-----+------------------+

                                  Table 3

   * fs_locations_info4

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.
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.
Top   ToC   RFC5661 - Page 111
   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 phrases "is an ordinary file" and "is a regular file" mean
      that the object's type attribute is NF4REG or NF4NAMEDATTR.

5.8.1.3. Attribute 2: fh_expire_type
Server uses this to specify filehandle expiration behavior to the client. See Section 4 for additional description.
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.
Top   ToC   RFC5661 - Page 112
5.8.1.8. Attribute 7: named_attr
TRUE, if this object has named attributes. In other words, 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 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).
5.8.1.14. Attribute 75: suppattr_exclcreat
The bit vector that would set all REQUIRED and RECOMMENDED attributes that are supported by the EXCLUSIVE4_1 method of file creation via the OPEN operation. The scope of this attribute applies to all objects with a matching fsid.

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 last modification (deprecated in favor of time_backup).
Top   ToC   RFC5661 - Page 113
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 file name comparisons on this file system are case insensitive.
5.8.2.4. Attribute 17: case_preserving
TRUE, if file name case on this file system is preserved.
5.8.2.5. Attribute 60: change_policy
A value created by the server that the client can use to determine if some server policy related to the current file system has been subject to change. If the value remains the same, then the client can be sure that the values of the attributes related to fs location and the fss_type field of the fs_status attribute have not changed. On the other hand, a change in this value does necessarily imply a change in policy. It is up to the client to interrogate the server to determine if some policy relevant to it has changed. See Section 3.3.6 for details. This attribute MUST change when the value returned by the fs_locations or fs_locations_info attribute changes, when a file system goes from read-only to writable or vice versa, or when the allowable set of security flavors for the file system or any part thereof is changed.
5.8.2.6. 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, in Windows 2000, the "Take Ownership" privilege).
5.8.2.7. Attribute 20: fileid
A number uniquely identifying the file within the file system.
5.8.2.8. 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   RFC5661 - Page 114
5.8.2.9. Attribute 22: files_free
Free file slots on the file system containing this object -- this should be the smallest relevant limit.
5.8.2.10. Attribute 23: files_total
Total file slots on the file system containing this object.
5.8.2.11. Attribute 76: fs_charset_cap
Character set capabilities for this file system. See Section 14.4.
5.8.2.12. 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. See Section 11.9 for more details.
5.8.2.13. Attribute 67: fs_locations_info
Full function file system location. See Section 11.10 for more details.
5.8.2.14. Attribute 61: fs_status
Generic file system type information. See Section 11.11 for more details.
5.8.2.15. Attribute 25: hidden
TRUE, if the file is considered hidden with respect to the Windows API.
5.8.2.16. 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.17. Attribute 27: maxfilesize
Maximum supported file size for the file system of this object.
5.8.2.18. Attribute 28: maxlink
Maximum number of links for this object.
Top   ToC   RFC5661 - Page 115
5.8.2.19. Attribute 29: maxname
Maximum file name size supported for this object.
5.8.2.20. Attribute 30: maxread
Maximum amount of data the READ operation will return for this object.
5.8.2.21. 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.22. Attribute 32: mimetype
MIME body type/subtype of this object.
5.8.2.23. 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 like readdir(), 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() 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.1 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.
Top   ToC   RFC5661 - Page 116
   While the NFSv4.1 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.

   If the server detects that there is no mounted point at 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.24. Attribute 34: no_trunc
If this attribute is TRUE, then if the client uses a file name longer than name_max, an error will be returned instead of the name being truncated.
5.8.2.25. Attribute 35: numlinks
Number of hard links to this object.
5.8.2.26. Attribute 36: owner
The string name of the owner of this object.
5.8.2.27. Attribute 37: owner_group
The string name of the group ownership of this object.
Top   ToC   RFC5661 - Page 117
5.8.2.28. 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.
5.8.2.29. 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 is a rule as to which other files or directories.
5.8.2.30. 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.31. 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, the value returned SHOULD NOT be considered useful.
5.8.2.32. 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.
Top   ToC   RFC5661 - Page 118
5.8.2.33. 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.34. Attribute 44: space_total
Total disk space in bytes on the file system containing this object.
5.8.2.35. Attribute 45: space_used
Number of file system bytes allocated to this object.
5.8.2.36. Attribute 46: system
This attribute is TRUE if this file is a "system" file with respect to the Windows operating environment.
5.8.2.37. Attribute 47: time_access
The time_access attribute 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 [16], [17], [18]. 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.38. Attribute 48: time_access_set
Sets the time of last access to the object. SETATTR use only.
5.8.2.39. Attribute 49: time_backup
The time of last backup of the object.
Top   ToC   RFC5661 - Page 119
5.8.2.40. 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" or "change time".
5.8.2.41. Attribute 51: time_delta
Smallest useful server time granularity.
5.8.2.42. Attribute 52: time_metadata
The time of last metadata modification of the object.
5.8.2.43. Attribute 53: time_modify
The time of last modification to the object.
5.8.2.44. 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 within the "acl" attribute) are represented in terms of a UTF-8 string. To avoid a representation that is tied to a particular underlying implementation at the client or server, the use of the UTF-8 string has been chosen. Note that Section 6.1 of RFC 2624 [45] provides additional rationale. It is expected that the client and server will have their own local representation of owner and owner_group that is used for local storage or presentation to the end user. Therefore, it is expected that when these attributes are transferred between the client and server, the local representation is translated to a syntax of the form "user@dns_domain". This will allow for a client and server that do not use the same local representation the ability to translate to 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.
Top   ToC   RFC5661 - Page 120
   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
   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 the
   owner and owner_group attributes 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,
   owner_group, or acl attributes.  When a server does accept an owner
   or owner_group value as valid on a SETATTR (and similarly for the
   owner and group strings in an acl), it is promising to return that
   same string when a corresponding GETATTR is done.  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
   ownership 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.

   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
   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.
Top   ToC   RFC5661 - Page 121
   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 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 is not
   obligated to accept such a string, but may return an NFS4ERR_BADOWNER
   instead.  To avoid this mechanism being used to subvert user and
   group translation, so that a client might pass all of the owners and
   groups in numeric form, a 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 name@domain string and not the special form for
   compatibility.

   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.
   Users and implementations of NFSv4.1 SHOULD NOT use "nobody" to
   designate a real user whose access is not anonymous.

5.10. Character Case Attributes

With respect to the case_insensitive and case_preserving attributes, each UCS-4 character (which UTF-8 encodes) can be mapped according to Appendix B.2 of RFC 3454 [19]. For general character handling and internationalization issues, see Section 14.

5.11. Directory Notification Attributes

As described in Section 18.39, the client can request a minimum delay for notifications of changes to attributes, but the server is free to ignore what the client requests. The client can determine in advance what notification delays the server will accept by sending a GETATTR operation for either or both of two directory notification attributes. When the client calls the GET_DIR_DELEGATION operation and asks for attribute change notifications, it should request notification delays that are no less than the values in the server- provided attributes.

5.11.1. Attribute 56: dir_notif_delay

The dir_notif_delay attribute is the minimum number of seconds the server will delay before notifying the client of a change to the directory's attributes.
Top   ToC   RFC5661 - Page 122

5.11.2. Attribute 57: dirent_notif_delay

The dirent_notif_delay attribute is the minimum number of seconds the server will delay before notifying the client of a change to a file object that has an entry in the directory.

5.12. pNFS Attribute Definitions

5.12.1. Attribute 62: fs_layout_type

The fs_layout_type attribute (see Section 3.3.13) applies to a file system and indicates what layout types are supported by the file system. When the client encounters a new fsid, the client SHOULD obtain the value for the fs_layout_type attribute associated with the new file system. This attribute is used by the client to determine if the layout types supported by the server match any of the client's supported layout types.

5.12.2. Attribute 66: layout_alignment

When a client holds layouts on files of a file system, the layout_alignment attribute indicates the preferred alignment for I/O to files on that file system. Where possible, the client should send READ and WRITE operations with offsets that are whole multiples of the layout_alignment attribute.

5.12.3. Attribute 65: layout_blksize

When a client holds layouts on files of a file system, the layout_blksize attribute indicates the preferred block size for I/O to files on that file system. Where possible, the client should send READ operations with a count argument that is a whole multiple of layout_blksize, and WRITE operations with a data argument of size that is a whole multiple of layout_blksize.

5.12.4. Attribute 63: layout_hint

The layout_hint attribute (see Section 3.3.19) may be set on newly created files to influence the metadata server's choice for the file's layout. If possible, this attribute is one of those set in the initial attributes within the OPEN operation. The metadata server may choose to ignore this attribute. The layout_hint attribute is a subset of the layout structure returned by LAYOUTGET. For example, instead of specifying particular devices, this would be used to suggest the stripe width of a file. The server implementation determines which fields within the layout will be used.
Top   ToC   RFC5661 - Page 123

5.12.5. Attribute 64: layout_type

This attribute lists the layout type(s) available for a file. The value returned by the server is for informational purposes only. The client will use the LAYOUTGET operation to obtain the information needed in order to perform I/O, for example, the specific device information for the file and its layout.

5.12.6. Attribute 68: mdsthreshold

This attribute is a server-provided hint used to communicate to the client when it is more efficient to send READ and WRITE operations to the metadata server or the data server. The two types of thresholds described are file size thresholds and I/O size thresholds. If a file's size is smaller than the file size threshold, data accesses SHOULD be sent to the metadata server. If an I/O request has a length that is below the I/O size threshold, the I/O SHOULD be sent to the metadata server. Each threshold type is specified separately for read and write. The server MAY provide both types of thresholds for a file. If both file size and I/O size are provided, the client SHOULD reach or exceed both thresholds before sending its read or write requests to the data server. Alternatively, if only one of the specified thresholds is reached or exceeded, the I/O requests are sent to the metadata server. For each threshold type, a value of zero indicates no READ or WRITE should be sent to the metadata server, while a value of all ones indicates that all READs or WRITEs should be sent to the metadata server. The attribute is available on a per-filehandle basis. If the current filehandle refers to a non-pNFS file or directory, the metadata server should return an attribute that is representative of the filehandle's file system. It is suggested that this attribute is queried as part of the OPEN operation. Due to dynamic system changes, the client should not assume that the attribute will remain constant for any specific time period; thus, it should be periodically refreshed.

5.13. Retention Attributes

Retention is a concept whereby a file object can be placed in an immutable, undeletable, unrenamable state for a fixed or infinite duration of time. Once in this "retained" state, the file cannot be moved out of the state until the duration of retention has been reached.
Top   ToC   RFC5661 - Page 124
   When retention is enabled, retention MUST extend to the data of the
   file, and the name of file.  The server MAY extend retention to any
   other property of the file, including any subset of REQUIRED,
   RECOMMENDED, and named attributes, with the exceptions noted in this
   section.

   Servers MAY support or not support retention on any file object type.

   The five retention attributes are explained in the next subsections.

5.13.1. Attribute 69: retention_get

If retention is enabled for the associated file, this attribute's value represents the retention begin time of the file object. This attribute's value is only readable with the GETATTR operation and MUST NOT be modified by the SETATTR operation (Section 5.5). The value of the attribute consists of: const RET4_DURATION_INFINITE = 0xffffffffffffffff; struct retention_get4 { uint64_t rg_duration; nfstime4 rg_begin_time<1>; }; The field rg_duration is the duration in seconds indicating how long the file will be retained once retention is enabled. The field rg_begin_time is an array of up to one absolute time value. If the array is zero length, no beginning retention time has been established, and retention is not enabled. If rg_duration is equal to RET4_DURATION_INFINITE, the file, once retention is enabled, will be retained for an infinite duration. If (as soon as) rg_duration is zero, then rg_begin_time will be of zero length, and again, retention is not (no longer) enabled.

5.13.2. Attribute 70: retention_set

This attribute is used to set the retention duration and optionally enable retention for the associated file object. This attribute is only modifiable via the SETATTR operation and MUST NOT be retrieved by the GETATTR operation (Section 5.5). This attribute corresponds to retention_get. The value of the attribute consists of: struct retention_set4 { bool rs_enable; uint64_t rs_duration<1>; };
Top   ToC   RFC5661 - Page 125
   If the client sets rs_enable to TRUE, then it is enabling retention
   on the file object with the begin time of retention starting from the
   server's current time and date.  The duration of the retention can
   also be provided if the rs_duration array is of length one.  The
   duration is the time in seconds from the begin time of retention, and
   if set to RET4_DURATION_INFINITE, the file is to be retained forever.
   If retention is enabled, with no duration specified in either this
   SETATTR or a previous SETATTR, the duration defaults to zero seconds.
   The server MAY restrict the enabling of retention or the duration of
   retention on the basis of the ACE4_WRITE_RETENTION ACL permission.

   The enabling of retention MUST NOT prevent the enabling of event-
   based retention or the modification of the retention_hold attribute.

   The following rules apply to both the retention_set and retentevt_set
   attributes.

   o  As long as retention is not enabled, the client is permitted to
      decrease the duration.

   o  The duration can always be set to an equal or higher value, even
      if retention is enabled.  Note that once retention is enabled, the
      actual duration (as returned by the retention_get or retentevt_get
      attributes; see Section 5.13.1 or Section 5.13.3) is constantly
      counting down to zero (one unit per second), unless the duration
      was set to RET4_DURATION_INFINITE.  Thus, it will not be possible
      for the client to precisely extend the duration on a file that has
      retention enabled.

   o  While retention is enabled, attempts to disable retention or
      decrease the retention's duration MUST fail with the error
      NFS4ERR_INVAL.

   o  If the principal attempting to change retention_set or
      retentevt_set does not have ACE4_WRITE_RETENTION permissions, the
      attempt MUST fail with NFS4ERR_ACCESS.

5.13.3. Attribute 71: retentevt_get

Gets the event-based retention duration, and if enabled, the event- based retention begin time of the file object. This attribute is like retention_get, but refers to event-based retention. The event that triggers event-based retention is not defined by the NFSv4.1 specification.
Top   ToC   RFC5661 - Page 126

5.13.4. Attribute 72: retentevt_set

Sets the event-based retention duration, and optionally enables event-based retention on the file object. This attribute corresponds to retentevt_get and is like retention_set, but refers to event-based retention. When event-based retention is set, the file MUST be retained even if non-event-based retention has been set, and the duration of non-event-based retention has been reached. Conversely, when non-event-based retention has been set, the file MUST be retained even if event-based retention has been set, and the duration of event-based retention has been reached. The server MAY restrict the enabling of event-based retention or the duration of event-based retention on the basis of the ACE4_WRITE_RETENTION ACL permission. The enabling of event-based retention MUST NOT prevent the enabling of non-event-based retention or the modification of the retention_hold attribute.

5.13.5. Attribute 73: retention_hold

Gets or sets administrative retention holds, one hold per bit position. This attribute allows one to 64 administrative holds, one hold per bit on the attribute. If retention_hold is not zero, then the file MUST NOT be deleted, renamed, or modified, even if the duration on enabled event or non-event-based retention has been reached. The server MAY restrict the modification of retention_hold on the basis of the ACE4_WRITE_RETENTION_HOLD ACL permission. The enabling of administration retention holds does not prevent the enabling of event-based or non-event-based retention. If the principal attempting to change retention_hold does not have ACE4_WRITE_RETENTION_HOLD permissions, the attempt MUST fail with NFS4ERR_ACCESS.


(page 126 continued on part 6)

Next Section