Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7530

Network File System (NFS) Version 4 Protocol

Pages: 323
Proposed Standard
Errata
Obsoletes:  3530
Updated by:  79318587
Part 5 of 14 – Pages 81 to 97
First   Prev   Next

Top   ToC   RFC7530 - Page 81   prevText

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,
Top   ToC   RFC7530 - Page 82
   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.
Top   ToC   RFC7530 - Page 83

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.
Top   ToC   RFC7530 - Page 84
   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.
Top   ToC   RFC7530 - Page 85
   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.
Top   ToC   RFC7530 - Page 86
   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
Top   ToC   RFC7530 - Page 87
   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.
Top   ToC   RFC7530 - Page 88
   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.
Top   ToC   RFC7530 - Page 89
   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.
Top   ToC   RFC7530 - Page 90
   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
Top   ToC   RFC7530 - Page 91
   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.
Top   ToC   RFC7530 - Page 92
   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.
Top   ToC   RFC7530 - Page 93
   -  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)
Top   ToC   RFC7530 - Page 94
   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.
Top   ToC   RFC7530 - Page 95
   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)
Top   ToC   RFC7530 - Page 96
   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
Top   ToC   RFC7530 - Page 97
   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.


(next page on part 6)

Next Section