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. Section 7.
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. 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.
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).
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.
If the volatile bit is 0, then it is a persistent filehandle with a different structure following it.
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.
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. Section 18.104.22.168). 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 22.214.171.124) 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. 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 126.96.36.199 | | type | 1 | nfs_ftype4 | R | Section 188.8.131.52 | | fh_expire_type | 2 | uint32_t | R | Section 184.108.40.206 | | change | 3 | changeid4 | R | Section 220.127.116.11 | | size | 4 | uint64_t | R W | Section 18.104.22.168 | | link_support | 5 | bool | R | Section 22.214.171.124 | | symlink_support | 6 | bool | R | Section 126.96.36.199 | | named_attr | 7 | bool | R | Section 188.8.131.52 | | fsid | 8 | fsid4 | R | Section 184.108.40.206 | | unique_handles | 9 | bool | R | Section 220.127.116.11 | | lease_time | 10 | nfs_lease4 | R | Section 18.104.22.168 | | rdattr_error | 11 | nfsstat4 | R | Section 22.214.171.124 | | filehandle | 19 | nfs_fh4 | R | Section 126.96.36.199 | +-----------------+----+------------+-----+-------------------+ Table 3: REQUIRED Attributes 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 188.8.131.52 | | archive | 14 | bool | R W | Section 184.108.40.206 | | cansettime | 15 | bool | R | Section 220.127.116.11 | | case_insensitive | 16 | bool | R | Section 18.104.22.168 | | case_preserving | 17 | bool | R | Section 22.214.171.124 | | chown_restricted | 18 | bool | R | Section 126.96.36.199 | | fileid | 20 | uint64_t | R | Section 188.8.131.52 | | files_avail | 21 | uint64_t | R | Section 184.108.40.206 | | files_free | 22 | uint64_t | R | Section 220.127.116.11 | | files_total | 23 | uint64_t | R | Section 18.104.22.168 |
| fs_locations | 24 | fs_locations4 | R | Section 22.214.171.124 | | hidden | 25 | bool | R W | Section 126.96.36.199 | | homogeneous | 26 | bool | R | Section 188.8.131.52 | | maxfilesize | 27 | uint64_t | R | Section 184.108.40.206 | | maxlink | 28 | uint32_t | R | Section 220.127.116.11 | | maxname | 29 | uint32_t | R | Section 18.104.22.168 | | maxread | 30 | uint64_t | R | Section 22.214.171.124 | | maxwrite | 31 | uint64_t | R | Section 126.96.36.199 | | mimetype | 32 | ascii_ | R W | Section 188.8.131.52 | | | | REQUIRED4<> | | | | mode | 33 | mode4 | R W | Section 6.2.2 | | mounted_on_fileid | 55 | uint64_t | R | Section 184.108.40.206 | | no_trunc | 34 | bool | R | Section 220.127.116.11 | | numlinks | 35 | uint32_t | R | Section 18.104.22.168 | | owner | 36 | utf8str_mixed | R W | Section 22.214.171.124 | | owner_group | 37 | utf8str_mixed | R W | Section 126.96.36.199 | | quota_avail_hard | 38 | uint64_t | R | Section 188.8.131.52 | | quota_avail_soft | 39 | uint64_t | R | Section 184.108.40.206 | | quota_used | 40 | uint64_t | R | Section 220.127.116.11 | | rawdev | 41 | specdata4 | R | Section 18.104.22.168 | | space_avail | 42 | uint64_t | R | Section 22.214.171.124 | | space_free | 43 | uint64_t | R | Section 126.96.36.199 | | space_total | 44 | uint64_t | R | Section 188.8.131.52 | | space_used | 45 | uint64_t | R | Section 184.108.40.206 | | system | 46 | bool | R W | Section 220.127.116.11 | | time_access | 47 | nfstime4 | R | Section 18.104.22.168 | | time_access_set | 48 | settime4 | W | Section 22.214.171.124 | | time_backup | 49 | nfstime4 | R W | Section 126.96.36.199 | | time_create | 50 | nfstime4 | R W | Section 188.8.131.52 | | time_delta | 51 | nfstime4 | R | Section 184.108.40.206 | | time_metadata | 52 | nfstime4 | R | Section 220.127.116.11 | | time_modify | 53 | nfstime4 | R | Section 18.104.22.168 | | time_modify_set | 54 | settime4 | W | Section 22.214.171.124 | +-------------------+----+-----------------+-----+------------------+ Table 4: RECOMMENDED Attributes
Section 4 for additional description.
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.
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.
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, "firstname.lastname@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. 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/>).