accessible via normal namespace operations (e.g., LOOKUP). In this case, the file system is said to be "present" at that position in the namespace, and clients will typically use it, reserving use of additional locations specified via the location-related attributes to situations in which the principal location is no longer available. When there is no actual file system at the namespace location in question, the file system is said to be "absent". An absent file system contains no files or directories other than the root. Any reference to it, except to access a small set of attributes useful in determining alternative locations, will result in an error, NFS4ERR_MOVED. Note that if the server ever returns the error NFS4ERR_MOVED, it MUST support the fs_locations attribute. While the error name suggests that we have a case of a file system that once was present, and has only become absent later, this is only one possibility. A position in the namespace may be permanently absent with the set of file system(s) designated by the location attributes being the only realization. The name NFS4ERR_MOVED reflects an earlier, more limited conception of its function, but this error will be returned whenever the referenced file system is absent, whether it has moved or simply never existed. Except in the case of GETATTR-type operations (to be discussed later), when the current filehandle at the start of an operation is within an absent file system, that operation is not performed and the error NFS4ERR_MOVED is returned, to indicate that the file system is absent on the current server. Because a GETFH cannot succeed if the current filehandle is within an absent file system, filehandles within an absent file system cannot be transferred to the client. When a client does have filehandles within an absent file system, it is the result of obtaining them when the file system was present, and having the file system become absent subsequently. It should be noted that because the check for the current filehandle being within an absent file system happens at the start of every operation, operations that change the current filehandle so that it is within an absent file system will not result in an error. This allows such combinations as PUTFH-GETATTR and LOOKUP-GETATTR to be used to get attribute information, particularly location attribute information, as discussed below.
Handling of VERIFY/NVERIFY is similar to GETATTR in that if the attribute mask does not include fs_locations the error NFS4ERR_MOVED will result. It differs in that any appearance in the attribute mask of an attribute not supported for an absent file system (and note that this will include some normally REQUIRED attributes) will also cause an NFS4ERR_MOVED result.
When a file system is present, these attributes can provide alternative locations, to be used to access the same data, in the event of server failures, communications problems, or other difficulties that make continued access to the current file system impossible or otherwise impractical. Under some circumstances, multiple alternative locations may be used simultaneously to provide higher-performance access to the file system in question. Provision of such alternative locations is referred to as "replication", although there are cases in which replicated sets of data are not in fact present and the replicas are instead different paths to the same data. When a file system is present and subsequently becomes absent, clients can be given the opportunity to have continued access to their data, at an alternative location. Transfer of the file system contents to the new location is referred to as "migration". See Section 8.4.2 for details. Alternative locations may be physical replicas of the file system data or alternative communication paths to the same server or, in the case of various forms of server clustering, another server providing access to the same physical file system. The client's responsibilities in dealing with this transition depend on the specific nature of the new access path as well as how and whether data was in fact migrated. These issues will be discussed in detail below. Where a file system was not previously present, specification of file system location provides a means by which file systems located on one server can be associated with a namespace defined by another server, thus allowing a general multi-server namespace facility. A designation of such a location, in place of an absent file system, is called a "referral". Because client support for location-related attributes is OPTIONAL, a server may (but is not required to) take action to hide migration and referral events from such clients, by acting as a proxy, for example.
In the event that server failures, communications problems, or other difficulties make continued access to the current file system impossible or otherwise impractical, the client can use the alternative locations as a way to get continued access to its data. Multiple locations may be used simultaneously, to provide higher performance through the exploitation of multiple paths between client and target file system. Multiple server addresses, whether they are derived from a single entry with a DNS name representing a set of IP addresses or from multiple entries each with its own server address, may correspond to the same actual server.
located on multiple servers. Some likely uses of this include establishment of site-wide or organization-wide namespaces, or even knitting such together into a truly global namespace. Referrals occur when a client determines, upon first referencing a position in the current namespace, that it is part of a new file system and that the file system is absent. When this occurs, typically by receiving the error NFS4ERR_MOVED, the actual location or locations of the file system can be determined by fetching the fs_locations attribute. The location-related attribute may designate a single file system location or multiple file system locations, to be selected based on the needs of the client. Use of multi-server namespaces is enabled by NFSv4 but is not required. The use of multi-server namespaces and their scope will depend on the applications used and system administration preferences. Multi-server namespaces can be established by a single server providing a large set of referrals to all of the included file systems. Alternatively, a single multi-server namespace may be administratively segmented with separate referral file systems (on separate servers) for each separately administered portion of the namespace. The top-level referral file system or any segment may use replicated referral file systems for higher availability. Generally, multi-server namespaces are for the most part uniform, in that the same data made available to one client at a given location in the namespace is made available to all clients at that location.
If a single location entry designates multiple server IP addresses, the client should choose a single one to use. When two server addresses are designated by a single location entry and they correspond to different servers, this normally indicates some sort of misconfiguration, and so the client should avoid using such location entries when alternatives are available. When they are not, clients should pick one of the IP addresses and use it, without using others that are not directed to the same server.
A server MAY decline to migrate state associated with open-owners that span multiple file systems. In cases in which the server chooses not to migrate such state, the server MUST return NFS4ERR_BAD_STATEID when the client uses those stateids on the new server. The server MUST return NFS4ERR_STALE_STATEID when the client uses those stateids on the old server, regardless of whether migration has occurred or not.
o PUTROOTFH o LOOKUP "this" o LOOKUP "is" o LOOKUP "the" o LOOKUP "path" o GETFH o GETATTR(fsid, fileid, size, time_modify) Under the given circumstances, the following will be the result: o PUTROOTFH --> NFS_OK. The current fh is now the root of the pseudo-fs. o LOOKUP "this" --> NFS_OK. The current fh is for /this and is within the pseudo-fs. o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is within the pseudo-fs. o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and is within the pseudo-fs. o LOOKUP "path" --> NFS_OK. The current fh is for /this/is/the/path and is within a new, absent file system, but ... the client will never see the value of that fh. o GETFH --> NFS4ERR_MOVED. Fails, because the current fh is in an absent file system at the start of the operation and the specification makes no exception for GETFH. o GETATTR(fsid, fileid, size, time_modify). Not executed, because the failure of the GETFH stops the processing of the COMPOUND. Given the failure of the GETFH, the client has the job of determining the root of the absent file system and where to find that file system, i.e., the server and path relative to that server's root fh. Note here that in this example, the client did not obtain filehandles and attribute information (e.g., fsid) for the intermediate directories, so that it would not be sure where the absent file system starts. It could be the case, for example, that /this/is/the is the root of the moved file system and that the reason that the lookup of "path" succeeded is that the file system was not absent on
that operation but was moved between the last LOOKUP and the GETFH (since COMPOUND is not atomic). Even if we had the fsids for all of the intermediate directories, we could have no way of knowing that /this/is/the/path was the root of a new file system, since we don't yet have its fsid. In order to get the necessary information, let us re-send the chain of LOOKUPs with GETFHs and GETATTRs to at least get the fsids so we can be sure where the appropriate file system boundaries are. The client could choose to get fs_locations at the same time, but in most cases the client will have a good guess as to where the file system boundaries are (because of where NFS4ERR_MOVED was, and was not, received), making the fetching of fs_locations unnecessary. OP01: PUTROOTFH --> NFS_OK - The current fh is at the root of the pseudo-fs. OP02: GETATTR(fsid) --> NFS_OK - Just for completeness. Normally, clients will know the fsid of the pseudo-fs as soon as they establish communication with a server. OP03: LOOKUP "this" --> NFS_OK OP04: GETATTR(fsid) --> NFS_OK - Get the current fsid to see where the file system boundaries are. The fsid will be that for the pseudo-fs in this example, so no boundary. OP05: GETFH --> NFS_OK - The current fh is for /this and is within the pseudo-fs. OP06: LOOKUP "is" --> NFS_OK - The current fh is for /this/is and is within the pseudo-fs. OP07: GETATTR(fsid) --> NFS_OK - Get the current fsid to see where the file system boundaries are. The fsid will be that for the pseudo-fs in this example, so no boundary.
OP08: GETFH --> NFS_OK - The current fh is for /this/is and is within the pseudo-fs. OP09: LOOKUP "the" --> NFS_OK - The current fh is for /this/is/the and is within the pseudo-fs. OP10: GETATTR(fsid) --> NFS_OK - Get the current fsid to see where the file system boundaries are. The fsid will be that for the pseudo-fs in this example, so no boundary. OP11: GETFH --> NFS_OK - The current fh is for /this/is/the and is within the pseudo-fs. OP12: LOOKUP "path" --> NFS_OK - The current fh is for /this/is/the/path and is within a new, absent file system, but ... - The client will never see the value of that fh. OP13: GETATTR(fsid, fs_locations) --> NFS_OK - We are getting the fsid to know where the file system boundaries are. In this operation, the fsid will be different than that of the parent directory (which in turn was retrieved in OP10). Note that the fsid we are given will not necessarily be preserved at the new location. That fsid might be different, and in fact the fsid we have for this file system might be a valid fsid of a different file system on that new server. - In this particular case, we are pretty sure anyway that what has moved is /this/is/the/path rather than /this/is/the since we have the fsid of the latter and it is that of the pseudo-fs, which presumably cannot move. However, in other examples, we might not have this kind of information to rely on (e.g., /this/is/the might be a non-pseudo-file system separate from /this/is/the/path), so we need to have other reliable source information on the boundary of the file system that is moved. If, for example, the file system /this/is had moved, we would have a case of migration rather than referral, and once the boundaries of the migrated file system were clear we could fetch fs_locations.
- We are fetching fs_locations because the fact that we got an NFS4ERR_MOVED at this point means that this is most likely a referral and we need the destination. Even if it is the case that /this/is/the is a file system that has migrated, we will still need the location information for that file system. OP14: GETFH --> NFS4ERR_MOVED - Fails because current fh is in an absent file system at the start of the operation, and the specification makes no exception for GETFH. Note that this means the server will never send the client a filehandle from within an absent file system. Given the above, the client knows where the root of the absent file system is (/this/is/the/path) by noting where the change of fsid occurred (between "the" and "path"). The fs_locations attribute also gives the client the actual location of the absent file system so that the referral can proceed. The server gives the client the bare minimum of information about the absent file system so that there will be very little scope for problems of conflict between information sent by the referring server and information of the file system's home. No filehandles and very few attributes are present on the referring server, and the client can treat those it receives as transient information with the function of enabling the referral.
In this case, because rdattr_error is not requested, fs_locations is not requested, and some of the attributes cannot be provided, the result will be an NFS4ERR_MOVED error on the READDIR, with the detailed results as follows: o PUTROOTFH --> NFS_OK. The current fh is at the root of the pseudo-fs. o LOOKUP "this" --> NFS_OK. The current fh is for /this and is within the pseudo-fs. o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is within the pseudo-fs. o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and is within the pseudo-fs. o READDIR(fsid, size, time_modify, mounted_on_fileid) --> NFS4ERR_MOVED. Note that the same error would have been returned if /this/is/the had migrated, but it is returned because the directory contains the root of an absent file system. So now suppose that we re-send with rdattr_error: o PUTROOTFH o LOOKUP "this" o LOOKUP "is" o LOOKUP "the" o READDIR(rdattr_error, fsid, size, time_modify, mounted_on_fileid) The results will be: o PUTROOTFH --> NFS_OK. The current fh is at the root of the pseudo-fs. o LOOKUP "this" --> NFS_OK. The current fh is for /this and is within the pseudo-fs. o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is within the pseudo-fs. o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and is within the pseudo-fs.
o READDIR(rdattr_error, fsid, size, time_modify, mounted_on_fileid) --> NFS_OK. The attributes for the directory entry with the component named "path" will only contain rdattr_error with the value NFS4ERR_MOVED, together with an fsid value and a value for mounted_on_fileid. So suppose we do another READDIR to get fs_locations (although we could have used a GETATTR directly, as in Section 8.7.1): o PUTROOTFH o LOOKUP "this" o LOOKUP "is" o LOOKUP "the" o READDIR(rdattr_error, fs_locations, mounted_on_fileid, fsid, size, time_modify) The results would be: o PUTROOTFH --> NFS_OK. The current fh is at the root of the pseudo-fs. o LOOKUP "this" --> NFS_OK. The current fh is for /this and is within the pseudo-fs. o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is within the pseudo-fs. o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and is within the pseudo-fs. o READDIR(rdattr_error, fs_locations, mounted_on_fileid, fsid, size, time_modify) --> NFS_OK. The attributes will be as shown below. The attributes for the directory entry with the component named "path" will only contain: o rdattr_error (value: NFS_OK) o fs_locations o mounted_on_fileid (value: unique fileid within referring file system) o fsid (value: unique value within referring server)
The attributes for entry "path" will not contain size or time_modify, because these attributes are not available within an absent file system. Section 2.2.6) and fs_locations4 (Section 2.2.7). It is used to represent the location of a file system by providing a server name and the path to the root of the file system within that server's namespace. When a set of servers have corresponding file systems at the same path within their namespaces, an array of server names may be provided. An entry in the server array is a UTF-8 string and represents one of a traditional DNS host name, IPv4 address, IPv6 address, or a zero-length string. A zero-length string SHOULD be used to indicate the current address being used for the RPC. It is not a requirement that all servers that share the same rootpath be listed in one fs_location4 instance. The array of server names is provided for convenience. Servers that share the same rootpath may also be listed in separate fs_location4 entries in the fs_locations attribute. The fs_locations4 data type and fs_locations attribute contain an array of such locations. Since the namespace of each server may be constructed differently, the fs_root field is provided. The path represented by the fs_root represents the location of the file system in the current server's namespace, i.e., that of the server from which the fs_locations attribute was obtained. The fs_root path is meant to aid the client by clearly referencing the root of the file system whose locations are being reported, no matter what object within the current file system the current filehandle designates. The fs_root is simply the pathname the client used to reach the object on the current server (i.e., the object to which the fs_locations attribute applies). When the fs_locations attribute is interrogated and there are no alternative file system locations, the server SHOULD return a zero-length array of fs_location4 structures, together with a valid fs_root. As an example, suppose there is a replicated file system located at two servers (servA and servB). At servA, the file system is located at path /a/b/c. At servB, the file system is located at path /x/y/z. If the client were to obtain the fs_locations value for the directory at /a/b/c/d, it might not necessarily know that the file system's root is located in servA's namespace at /a/b/c. When the client switches to servB, it will need to determine that the directory it first referenced at servA is now represented by the path /x/y/z/d
on servB. To facilitate this, the fs_locations attribute provided by servA would have an fs_root value of /a/b/c and two entries in fs_locations. One entry in fs_locations will be for itself (servA), and the other will be for servB with a path of /x/y/z. With this information, the client is able to substitute /x/y/z for /a/b/c at the beginning of its access path and construct /x/y/z/d to use for the new server. Note that there is no requirement that the number of components in each rootpath be the same; there is no relation between the number of components in the rootpath or fs_root, and none of the components in each rootpath and fs_root have to be the same. In the above example, we could have had a third element in the locations array, with server equal to "servC" and rootpath equal to "/I/II", and a fourth element in the locations array, with server equal to "servD" and rootpath equal to "/aleph/beth/gimel/daleth/he". The relationship between an fs_root and a rootpath is that the client replaces the pathname indicated in the fs_root for the current server for the substitute indicated in the rootpath for the new server. For an example of a referred or migrated file system, suppose there is a file system located at serv1. At serv1, the file system is located at /az/buky/vedi/glagoli. The client finds that the object at glagoli has migrated (or is a referral). The client gets the fs_locations attribute, which contains an fs_root of /az/buky/vedi/ glagoli, and one element in the locations array, with server equal to serv2, and rootpath equal to /izhitsa/fita. The client replaces /az/buky/vedi/glagoli with /izhitsa/fita and uses the latter pathname on serv2. Thus, the server MUST return an fs_root that is equal to the path the client used to reach the object to which the fs_locations attribute applies. Otherwise, the client cannot determine the new path to use on the new server.