RFC 7530
Network File System (NFS) Version 4 Protocol
Pages: 323
Proposed Standard
→ Errata
Obsoletes: 3530
Updated by: 7931 8587
Proposed Standard
→ Errata
Obsoletes: 3530
Updated by: 7931 8587
Part 3 of 14 – Pages 30 to 54
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
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
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
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.
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).
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
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.
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
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.
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.
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.
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 |
| 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 Attributes5.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. 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.
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).
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.
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.
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.
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.
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.
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.
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
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
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.
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)