8.  Multi-Server Namespace

   NFSv4 supports attributes that allow a namespace to extend beyond the
   boundaries of a single server.  It is RECOMMENDED that clients and
   servers support construction of such multi-server namespaces.  Use of
   such multi-server namespaces is optional, however, and for many
   purposes, single-server namespaces are perfectly acceptable.  Use of
   multi-server namespaces can provide many advantages, however, by
   separating a file system's logical position in a namespace from the
   (possibly changing) logistical and administrative considerations that
   result in particular file systems being located on particular
   servers.

8.1.  Location Attributes

   NFSv4 contains RECOMMENDED attributes that allow file systems on one
   server to be associated with one or more instances of that file
   system on other servers.  These attributes specify such file system
   instances by specifying a server address target (as either a DNS name
   representing one or more IP addresses, or a literal IP address),
   together with the path of that file system within the associated
   single-server namespace.

   The fs_locations RECOMMENDED attribute allows specification of the
   file system locations where the data corresponding to a given file
   system may be found.

8.2.  File System Presence or Absence

   A given location in an NFSv4 namespace (typically but not necessarily
   a multi-server namespace) can have a number of file system instance
   locations associated with it via the fs_locations attribute.  There
   may also be an actual current file system at that location,

   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.

8.3.  Getting Attributes for an Absent File System

   When a file system is absent, most attributes are not available, but
   it is necessary to allow the client access to the small set of
   attributes that are available, and most particularly that which gives
   information about the correct current locations for this file system,
   fs_locations.

8.3.1.  GETATTR within an Absent File System

   As mentioned above, an exception is made for GETATTR in that
   attributes may be obtained for a filehandle within an absent file
   system.  This exception only applies if the attribute mask contains
   at least the fs_locations attribute bit, which indicates that the
   client is interested in a result regarding an absent file system.  If
   it is not requested, GETATTR will result in an NFS4ERR_MOVED error.

   When a GETATTR is done on an absent file system, the set of supported
   attributes is very limited.  Many attributes, including those that
   are normally REQUIRED, will not be available on an absent file
   system.  In addition to the fs_locations attribute, the following
   attributes SHOULD be available on absent file systems.  In the case
   of RECOMMENDED attributes, they should be available at least to the
   same degree that they are available on present file systems.

   fsid:  This attribute should be provided so that the client can
      determine file system boundaries, including, in particular, the
      boundary between present and absent file systems.  This value must
      be different from any other fsid on the current server and need
      have no particular relationship to fsids on any particular
      destination to which the client might be directed.

   mounted_on_fileid:  For objects at the top of an absent file system,
      this attribute needs to be available.  Since the fileid is within
      the present parent file system, there should be no need to
      reference the absent file system to provide this information.

   Other attributes SHOULD NOT be made available for absent file
   systems, even when it is possible to provide them.  The server should
   not assume that more information is always better and should avoid
   gratuitously providing additional information.

   When a GETATTR operation includes a bitmask for the attribute
   fs_locations, but where the bitmask includes attributes that are not
   supported, GETATTR will not return an error but will return the mask
   of the actual attributes supported with the results.

   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.

8.3.2.  READDIR and Absent File Systems

   A READDIR performed when the current filehandle is within an absent
   file system will result in an NFS4ERR_MOVED error, since, unlike the
   case of GETATTR, no such exception is made for READDIR.

   Attributes for an absent file system may be fetched via a READDIR for
   a directory in a present file system, when that directory contains
   the root directories of one or more absent file systems.  In this
   case, the handling is as follows:

   o  If the attribute set requested includes fs_locations, then the
      fetching of attributes proceeds normally, and no NFS4ERR_MOVED
      indication is returned even when the rdattr_error attribute is
      requested.

   o  If the attribute set requested does not include fs_locations, then
      if the rdattr_error attribute is requested, each directory entry
      for the root of an absent file system will report NFS4ERR_MOVED as
      the value of the rdattr_error attribute.

   o  If the attribute set requested does not include either of the
      attributes fs_locations or rdattr_error, then the occurrence of
      the root of an absent file system within the directory will result
      in the READDIR failing with an NFS4ERR_MOVED error.

   o  The unavailability of an attribute because of a file system's
      absence, even one that is ordinarily REQUIRED, does not result in
      any error indication.  The set of attributes returned for the root
      directory of the absent file system in that case is simply
      restricted to those actually available.

8.4.  Uses of Location Information

   The location-bearing attribute of fs_locations provides, together
   with the possibility of absent file systems, a number of important
   facilities in providing reliable, manageable, and scalable data
   access.

   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.

8.4.1.  File System Replication

   The fs_locations attribute provides alternative locations, to be used
   to access data in place of, or in addition to, the current file
   system instance.  On first access to a file system, the client should
   obtain the value of the set of alternative locations by interrogating
   the fs_locations attribute.

   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.

8.4.2.  File System Migration

   When a file system is present and becomes absent, clients can be
   given the opportunity to have continued access to their data, at an
   alternative location, as specified by the fs_locations attribute.
   Typically, a client will be accessing the file system in question,
   get an NFS4ERR_MOVED error, and then use the fs_locations attribute
   to determine the new location of the data.

   Such migration can be helpful in providing load balancing or general
   resource reallocation.  The protocol does not specify how the file
   system will be moved between servers.  It is anticipated that a
   number of different server-to-server transfer mechanisms might be
   used, with the choice left to the server implementer.  The NFSv4
   protocol specifies the method used to communicate the migration event
   between client and server.

   When an alternative location is designated as the target for
   migration, it must designate the same data.  Where file systems are
   writable, a change made on the original file system must be visible
   on all migration targets.  Where a file system is not writable but
   represents a read-only copy (possibly periodically updated) of a
   writable file system, similar requirements apply to the propagation
   of updates.  Any change visible in the original file system must
   already be effected on all migration targets, to avoid any
   possibility that a client, in effecting a transition to the migration
   target, will see any reversion in file system state.

8.4.3.  Referrals

   Referrals provide a way of placing a file system in a location within
   the namespace essentially without respect to its physical location on
   a given server.  This allows a single server or a set of servers to
   present a multi-server namespace that encompasses file systems

   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.

8.5.  Location Entries and Server Identity

   As mentioned above, a single location entry may have a server address
   target in the form of a DNS name that may represent multiple IP
   addresses, while multiple location entries may have their own server
   address targets that reference the same server.

   When multiple addresses for the same server exist, the client may
   assume that for each file system in the namespace of a given server
   network address, there exist file systems at corresponding namespace
   locations for each of the other server network addresses.  It may do
   this even in the absence of explicit listing in fs_locations.  Such
   corresponding file system locations can be used as alternative
   locations, just as those explicitly specified via the fs_locations
   attribute.

   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.

8.6.  Additional Client-Side Considerations

   When clients make use of servers that implement referrals,
   replication, and migration, care should be taken that a user who
   mounts a given file system that includes a referral or a relocated
   file system continues to see a coherent picture of that user-side
   file system despite the fact that it contains a number of server-side
   file systems that may be on different servers.

   One important issue is upward navigation from the root of a
   server-side file system to its parent (specified as ".." in UNIX), in
   the case in which it transitions to that file system as a result of
   referral, migration, or a transition as a result of replication.
   When the client is at such a point, and it needs to ascend to the
   parent, it must go back to the parent as seen within the multi-server
   namespace rather than sending a LOOKUPP operation to the server,
   which would result in the parent within that server's single-server
   namespace.  In order to do this, the client needs to remember the
   filehandles that represent such file system roots and use these
   instead of issuing a LOOKUPP operation to the current server.  This
   will allow the client to present to applications a consistent
   namespace, where upward navigation and downward navigation are
   consistent.

   Another issue concerns refresh of referral locations.  When referrals
   are used extensively, they may change as server configurations
   change.  It is expected that clients will cache information related
   to traversing referrals so that future client-side requests are
   resolved locally without server communication.  This is usually
   rooted in client-side name lookup caching.  Clients should
   periodically purge this data for referral points in order to detect
   changes in location information.

   A potential problem exists if a client were to allow an open-owner to
   have state on multiple file systems on a server, in that it is
   unclear how the sequence numbers associated with open-owners are to
   be dealt with, in the event of transparent state migration.  A client
   can avoid such a situation if it ensures that any use of an
   open-owner is confined to a single file system.

   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.

8.7.  Effecting File System Referrals

   Referrals are effected when an absent file system is encountered and
   one or more alternative locations are made available by the
   fs_locations attribute.  The client will typically get an
   NFS4ERR_MOVED error, fetch the appropriate location information, and
   proceed to access the file system on a different server, even though
   it retains its logical position within the original namespace.
   Referrals differ from migration events in that they happen only when
   the client has not previously referenced the file system in question
   (so there is nothing to transition).  Referrals can only come into
   effect when an absent file system is encountered at its root.

   The examples given in the sections below are somewhat artificial in
   that an actual client will not typically do a multi-component lookup
   but will have cached information regarding the upper levels of the
   name hierarchy.  However, these example are chosen to make the
   required behavior clear and easy to put within the scope of a small
   number of requests, without getting unduly into details of how
   specific clients might choose to cache things.

8.7.1.  Referral Example (LOOKUP)

   Let us suppose that the following COMPOUND is sent in an environment
   in which /this/is/the/path is absent from the target server.  This
   may be for a number of reasons.  It may be the case that the file
   system has moved, or it may be the case that the target server is
   functioning mainly, or solely, to refer clients to the servers on
   which various file systems are located.

   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.

8.7.2.  Referral Example (READDIR)

   Another context in which a client may encounter referrals is when it
   does a READDIR on a directory in which some of the subdirectories are
   the roots of absent file systems.

   Suppose such a directory is read as follows:

   o  PUTROOTFH

   o  LOOKUP "this"

   o  LOOKUP "is"

   o  LOOKUP "the"

   o  READDIR(fsid, size, time_modify, mounted_on_fileid)

   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.

8.8.  The Attribute fs_locations

   The fs_locations attribute is defined by both fs_location4
   (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.