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
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
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
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
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
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
FH4_VOL_MIGRATION: The filehandle will expire as a result of
migration. If FH4_VOLATILE_ANY is set, FH4_VOL_MIGRATION is
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
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
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
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
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
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
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
RENAME A B
Note that the COMPOUND procedure does not provide atomicity. This
example only reduces the overhead of recovering from an expired
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
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
| 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
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
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
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
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
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
Names of attributes will not be controlled by this document or other
IETF Standards Track documents. See Section 20 for further
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
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 126.96.36.199). 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 188.8.131.52)
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
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
o The per-server attribute is:
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.
184.108.40.206. Attribute 1: type
Designates the type of an object in terms of one of a number of
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.
220.127.116.11. Attribute 2: fh_expire_type
The server uses this to specify filehandle expiration behavior to the
client. See Section 4 for additional description.
18.104.22.168. 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.
22.214.171.124. Attribute 32: mimetype
MIME media type/subtype of this object.
126.96.36.199. 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
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.
188.8.131.52. 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
184.108.40.206. Attribute 35: numlinks
Number of hard links to this object.
220.127.116.11. Attribute 36: owner
The string name of the owner of this object.
18.104.22.168. Attribute 37: owner_group
The string name of the group ownership of this object.
22.214.171.124. 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.
126.96.36.199. 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.
188.8.131.52. 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".
184.108.40.206. 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.
220.127.116.11. 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.
18.104.22.168. Attribute 43: space_free
Free disk space in bytes on the file system containing this object --
this should be the smallest relevant limit.
22.214.171.124. Attribute 44: space_total
Total disk space in bytes on the file system containing this object.
126.96.36.199. Attribute 45: space_used
Number of file system bytes allocated to this object.
188.8.131.52. Attribute 46: system
TRUE, if this file is a "system" file with respect to the Windows
184.108.40.206. 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
220.127.116.11. Attribute 48: time_access_set
Sets the time of last access to the object. SETATTR use only.
18.104.22.168. Attribute 49: time_backup
The time of last backup of the object.
22.214.171.124. 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"
126.96.36.199. Attribute 51: time_delta
Smallest useful server time granularity.
188.8.131.52. Attribute 52: time_metadata
The time of last metadata modification of the object.
184.108.40.206. Attribute 53: time_modify
The time of last modification to the object.
220.127.116.11. 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, "email@example.com". 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
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
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
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
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