Namespace Database (NSDB) Protocol for Federated File Systems
NetApp
1601 Trapelo Rd, Suite 16WalthamMA02451United States+1 781-768-5359jlentini@netapp.com
IBM Almaden
650 Harry RdSan JoseCA95120United Statestewarir@us.ibm.com
Oracle Corporation
1015 Granger AvenueAnn ArborMI48104United States+1 248-614-5091chuck.lever@oracle.com
Internet
NFSv4 Working Group Federated File Systems This document describes a file system federation
protocol that enables file access and namespace traversal
across collections of independently administered
fileservers. The protocol specifies a set of interfaces by
which fileservers with different administrators can form
a fileserver federation that provides a namespace composed
of the file systems physically hosted on and exported by the
constituent fileservers. A federated file system enables file access and namespace
traversal in a uniform, secure, and consistent manner across
multiple independent fileservers within an enterprise or
across multiple enterprises. This document specifies a set of protocols that allow
fileservers, possibly from different vendors and with
different administrators, to cooperatively form a federation
containing one or more federated file systems. Each federated
file system's namespace is composed of the file systems physically
hosted on and exported by the federation's fileservers. A
federation comprises a common namespace across all its
fileservers. A federation can project multiple namespaces and
enable clients to traverse each one. A federation can contain
an arbitrary number of namespace repositories, each belonging
to a different administrative entity and each rendering a part
of the namespace. A federation might also have an arbitrary number
of administrative entities responsible for administering disjoint
subsets of the fileservers. Traditionally, building a namespace that spans
multiple fileservers has been difficult for two reasons.
First, the fileservers that export pieces of the namespace
are often not in the same administrative domain. Second, there
is no standard mechanism for the fileservers to cooperatively
present the namespace. Fileservers may provide proprietary
management tools, and in some cases, an administrator may be
able to use the proprietary tools to build a shared
namespace out of the exported file systems. However, relying on
vendor-specific proprietary tools does not work in larger enterprises
or when collaborating across enterprises because the fileservers
are likely to be from multiple vendors or use different software
versions, each with their own namespace protocols, with no common
mechanism to manage the namespace or exchange namespace information. The federated file system protocols in this document define
how to construct a namespace accessible by an Network File System (NFS)
version 4.0
, NFSv4.1 , or newer
client and have been designed to accommodate other file-access
protocols in the future. The requirements for federated file systems are described
in . A protocol for administering
a fileserver's namespace is described in .
The mechanism for discovering the root of a federated namespace is
described in . In the rest of the document, the term "fileserver" denotes a
fileserver that is part of a federation. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be
interpreted as described in .
A file-access protocol is a network protocol for
accessing data. The NFSv4.0 protocol
is an example of a file-access protocol. File-access clients are standard, off-the-shelf network-attached
storage (NAS) clients that communicate with
fileservers using a standard file-access protocol. Fileservers are servers that store physical fileset
data or refer file-access clients to other fileservers.
A fileserver provides access to its shared file system
data via a file-access protocol. A fileserver may be
implemented in a number of different ways, including a
single system, a cluster of systems, or some other
configuration. A referral is a mechanism by which a fileserver
redirects a file-access client to a different
fileserver or export. The exact information contained in a
referral varies from one file-access protocol to another.
The NFSv4.0 protocol, for example, defines the fs_locations
attribute for returning referral information to NFSv4.0
clients. The NFSv4.1 protocol introduces the
fs_locations_info attribute that can return richer referral
information to its clients. NFSv4.1 fileservers may use
either attribute during a referral. Both attributes are
defined in . The goal of a unified namespace is to make all
managed data available to any file-access client via the
same path in a common file system namespace. This should
be achieved with minimal or zero configuration on file-access
clients. In particular, updates to the common namespace
should not require configuration changes to any file-access
client. Filesets, which are the units of data management, are
a set of files and directories. From the perspective of
file-access clients, the common namespace is constructed by
mounting filesets that are physically located on different
fileservers. The namespace, which is defined in terms
of fileset names and locations, is stored in a set of
namespace repositories, each managed by an administrative
entity. The namespace schema defines the model used for populating,
modifying, and querying the namespace repositories. It is not
required by the federation that the namespace be common
across all fileservers. It should be possible to have
several independently rooted namespaces. A fileset is loosely defined as a set of files and the
directory tree that contains them. The fileset abstraction
is the basic unit of data management. Depending on the
configuration, a fileset may be anything from an individual
directory of an exported file system to an entire exported
file system on a fileserver. A fileset is uniquely represented by its fileset name
(FSN). An FSN is considered unique across a federation.
After an FSN is created, it is associated with one or more
fileset locations (FSLs) on one or more fileservers. An FSN consists of: the network location of the
Namespace Database (NSDB) node that contains authoritative
information for this FSN. a UUID
(universally unique identifier), conforming to
, that is used to uniquely
identify an FSN. the time-to-live of the FSN's
FSL information, in seconds. Fileservers MUST NOT use
cached FSL records after the parent FSN's FsnTTL has expired.
An FsnTTL value of zero indicates that fileservers MUST NOT
cache the results of resolving this FSN. The NsdbName is not physically stored as an attribute
of the record. The NsdbName is obvious to any client that
accesses an NSDB and is indeed authenticated in cases where
Transport Layer Security (TLS) is in effect. The FsnUuid and NsdbName values never change during an FSN's
lifetime. However, an FSN's FSL information can change over
time and is typically cached on fileservers for performance.
More detail on FSL caching is provided in
. An FSN record may also contain: name/value pairs
that can be interpreted by a fileserver. The semantics
of this field are not defined by this document. These
tuples are intended to be used by higher-level
protocols. text
descriptions. The semantics of this field are
not defined by this document. An FSL describes one physical location where a complete
copy of the fileset's data resides. An FSL contains generic
and type-specific information that together describe how to
access the fileset data at this location. An FSL's attributes
can be used by a fileserver to decide which locations it will
return to a file-access client. An FSL consists of: a UUID, conforming to
, that is used to uniquely
identify an FSL. the UUID of the
FSL's FSN. the network location of the
NSDB node that contains authoritative information for
this FSL. The NsdbName is not stored as an attribute of an FSL
record for the same reason it is not stored in FSN records. An FSL record may also contain: name/value pairs
that can be interpreted by a fileserver. The semantics
of this field are not defined by this document. These
tuples are intended to be used by higher-level
protocols. text
descriptions. The semantics of this field are
not defined by this document. In addition to the attributes defined above, an FSL
record contains attributes that allow a fileserver to
construct referrals. For each file-access protocol, a
corresponding FSL record subtype is defined. This document defines an FSL subtype for NFS. An NFS
FSL contains information suitable for use in one of the
NFSv4 referral attributes (e.g., fs_locations or
fs_locations_info, described in ).
describes the contents of an
NFS FSL record. A fileset may also be accessible by file-access
protocols other than NFS. The contents and format of
such FSL subtypes are not defined in this document. To capture the location of an NFSv4 fileset, we extend
the NFS URL scheme specified in .
This extension follows rules for defining Uniform Resource
Identifier schemes (see ). In the
following text, we refer to this extended NFS URL scheme as
an NFS URI. An NFS URI MUST contain both an authority and a path
component. It MUST NOT contain a query component or a
fragment component. Use of the familiar "nfs" scheme name
is retained. The rules for encoding the authority component of a
generic URI are specified in section 3.2 of
. The authority component of
an NFS URI MUST contain the host subcomponent. For
globally scoped NFS URIs, a hostname used in such URIs
SHOULD be a fully qualified domain name. See section
3.2.2 of for rules on
encoding non-ASCII characters in hostnames. An NFS URI MAY contain a port subcomponent as
described in section 3.2.3 of .
If this subcomponent is missing, a port value of 2049
is assumed, as specified in ,
Section 3.1. The rules for encoding the path component of a
generic URI are specified in Section 3.3 of
. According to Sections 5 and 6 of
, NFS URLs specify a pathname
relative to an NFS fileserver's public filehandle.
However, NFSv4 fileservers do not expose a public
filehandle. Instead, NFSv4 pathnames contained in an
NFS URI are evaluated relative to the pseudoroot of the
fileserver identified in the URI's authority component.
Each component of an NFSv4 pathname is represented
as a component4 string (see Section 3.2, "Basic Data
Types", of ). The component4
elements of an NFSv4 pathname are encoded as path
segments in an NFS URI. NFSv4 pathnames MUST be
expressed in an NFS URI as an absolute path.
An NFS URI path component MUST NOT be empty.
The NFS URI path component starts with a slash ("/")
character, followed by one or more path segments
that each start with a slash ("/") character
. Therefore, a double slash always follows the
authority component of an NFS URI. For example, the
NFSv4 pathname "/" is represented by two slash ("/")
characters following an NFS URI's authority component.
The component names of an NFSv4 pathname MUST be prepared using
the component name rules defined in Section
12 ("Internationalization") of
prior to encoding the path component of an NFS URI.
As specified in , any non-ASCII characters
and any URI-reserved characters, such as the slash ("/")
character, contained in a component4 element MUST be
represented by URI percent encoding. The path component of an NFS URI encodes the
rootpath field of the NFSv4 fs_location4 data type or
the "fli_rootpath" of the NFSv4 fs_locations_item4 data
type (see ). In its server field, the NFSv4 fs_location4 data type
contains a list of universal addresses and DNS labels.
Each may optionally include a port number. The exact
encoding requirements for this information is found in
Section 12.6 of . The NFSv4
fs_locations_item4 data type encodes the same data in its
fli_entries field (see ). This
information is encoded in the authority component of an
NFS URI. The server and fli_entries fields can encode
multiple server hostnames that share the same pathname.
An NFS URI, and hence an FSL record, represents only a
single hostname and pathname pair. An NFS fileserver
MUST NOT combine a set of FSL records into a single
fs_location4 or fs_locations_item4 unless each FSL
record in the set contains the same rootpath value and
extended file system information. All of the FSLs that have the same FSN (and thereby
reference the same fileset) are equivalent from the
point of view of access by a file-access client. Different
fileset locations for an FSN represent the same data,
though potentially at different points in time.
Fileset locations are equivalent but not identical.
Locations may be either read-only or read-write.
Typically, multiple read-write locations are backed
by a clustered file system while read-only locations
are replicas created by a federation-initiated or
external replication operation. Read-only locations may
represent consistent point-in-time copies of a
read-write location. The federation protocols,
however, cannot prevent subsequent changes to a
read-only location nor guarantee point-in-time
consistency of a read-only location if the
read-write location is changing. Regardless of the type, one file-access client may
be referred to a location described by one FSL while
another client chooses to use a location described by
another FSL. Since updates to each fileset location
are not controlled by the federation protocol, it is the
responsibility of administrators to guarantee the
functional equivalence of the data. The federation protocols do not guarantee that
different fileset locations are mutually consistent in
terms of the currency of their data. However, they provide
a means to publish currency information so that all
fileservers in a federation can convey the same information
to file-access clients during referrals. Clients use this
information to ensure they do not revert to an out-of-date
version of a fileset's data when switching between fileset
locations. NFSv4.1 provides guidance on how replication can
be handled in such a manner. In particular, see Section 11.7
of . To resolve an FSN to a set of FSL records, a
fileserver queries the NSDB node named in the FSN
for FSL records associated with this FSN. The parent
FSN's FsnTTL attribute (see )
specifies the period of time during which a fileserver may
cache these FSL records. The combination of FSL caching and FSL migration presents
a challenge. For example, suppose there are three fileservers
named A, B, and C. Suppose further that fileserver A
contains a junction J to fileset X stored on fileserver B
(see for a description of junctions).
Now suppose that fileset X is migrated from fileserver B
to fileserver C, and the corresponding FSL information for
fileset X in the authoritative NSDB is updated. If fileserver A has cached FSLs for fileset X, a
file-access client traversing junction J on fileserver A
will be referred to fileserver B, even though fileset X has
migrated to fileserver C. If fileserver A had not cached the
FSL records, it would have queried the NSDB and obtained the
correct location of fileset X. Typically, the process of fileset migration leaves a
redirection on the source fileserver in place of a migrated
fileset (without such a redirection, file-access clients
would find an empty space where the migrated fileset was,
which defeats the purpose of a managed migration). This redirection might be a new junction that targets
the same FSN as other junctions referring to the migrated
fileset, or it might be some other kind of directive,
depending on the fileserver implementation, that simply
refers file-access clients to the new location of the
migrated fileset. Back to our example. Suppose, as part of the migration
process, a junction replaces fileset X on fileserver B.
Later, either:
New file-access clients are referred to fileserver
B by stale FSL information cached on fileserver A, or File-access clients continue to access fileserver
B because they cache stale location data for fileset X. In either case, thanks to the redirection, file-access
clients are informed by fileserver B that fileset X has
moved to fileserver C. Such redirecting junctions (here, on fileserver B)
would not be required to be in place forever. They need to
stay in place at least until FSL entries cached on
fileservers and locations cached on file-access clients
for the target fileset are invalidated. The FsnTTL field in the FSL's parent FSN (see
) specifies an upper bound for
the lifetime of cached FSL information and thus can act
as a lower bound for the lifetime of redirecting junctions. For example, suppose the FsnTTL field contains the value
3600 seconds (one hour). In such a case, administrators
SHOULD keep the redirection in place for at least one hour
after a fileset migration has taken place because a referring
fileserver might cache the FSL data during that time before
refreshing it. To get file-access clients to access the destination
fileserver more quickly, administrators SHOULD set the
FsnTTL field of the migrated fileset to a low number or
zero before migration begins. It can be reset to a
more reasonable number at a later point. Note that some file-access protocols do not communicate
location cache expiry information to file-access clients.
In some cases, it may be difficult to determine an
appropriate lifetime for redirecting junctions because
file-access clients may cache location information
indefinitely. After resolving an FSN to a set of FSL records, the
fileserver generates a referral to redirect a file-access
client to one or more of the FSN's FSLs. The fileserver
converts the FSL records to a referral format understood
by a particular file-access client, such as an NFSv4
fs_locations or fs_locations_info attribute. To give file-access clients as many options as
possible, the fileserver SHOULD include the maximum
possible number of FSL records in a referral. However,
the fileserver MAY omit some of the FSL records
from the referral. For example, the fileserver might
omit an FSL record because of limitations in the file-access
protocol's referral format. For a given FSL record, the fileserver MAY
convert or reduce the FSL record's contents in a manner
appropriate to the referral format. For example,
an NFS FSL record contains all the data necessary to
construct an fs_locations_info attribute,
but an fs_locations_info attribute contains
several pieces of information that are not found
in the simpler fs_locations attribute. A fileserver
constructs entries in an fs_locations attribute using
the relevant contents of an NFS FSL record. Whenever the fileserver converts or reduces
FSL data, the fileserver SHOULD attempt to maintain
the original meaning where possible. For example, an
NFS FSL record contains the rank and order information
that is included in an fs_locations_info attribute
(see NFSv4.1's FSLI4BX_READRANK, FSLI4BX_READORDER,
FSLI4BX_WRITERANK, and FSLI4BX_WRITEORDER). While
this rank and order information is not explicitly
expressible in an fs_locations attribute, the
fileserver can arrange the fs_locations
attribute's locations list based on the rank and order
values. Another example: A single NFS FSL record contains
the hostname of one fileserver. A single fs_locations
attribute can contain a list of fileserver names. An NFS
fileserver MAY combine two or more FSL records into a
single entry in an fs_locations or fs_locations_info array
only if each FSL record contains the same pathname and
extended file system information. Refer to Sections 11.9 and 11.10 of the NFSv4.1 protocol specification
for further details. The NSDB service is a federation-wide service that
provides interfaces to define, update, and query FSN
information, FSL information, and FSN-to-FSL mapping
information. An individual repository of namespace information
is called an NSDB node. The difference between the NSDB
service and an NSDB node is analogous to that between the
DNS service and a particular DNS server. Each NSDB node is managed by a single administrative
entity. A single administrative entity can manage
multiple NSDB nodes. Each NSDB node stores the definition of the FSNs
for which it is authoritative. It also stores the
definitions of the FSLs associated with those FSNs. An
NSDB node is authoritative for the filesets that it
defines. An NSDB MAY be replicated throughout the federation.
If an NSDB is replicated, the NSDB MUST exhibit loose,
converging consistency as defined in .
The mechanism by which this is achieved is outside the
scope of this document. Many Lightweight Directory Access Protocol (LDAP) implementations support
replication. These features MAY be used to replicate
the NSDB. Each NSDB node supports an LDAP
interface. An NSDB client
is software that uses the LDAP protocol to access or
update namespace information stored on an NSDB node.
A domain's administrative entity uses NSDB client
software to manage information stored on NSDB nodes. Details of
these transactions are discussed in . Fileservers act as an NSDB client when contacting a
particular NSDB node to resolve an FSN to a set of FSL
records. The resulting location information is then
transferred to file-access clients via referrals.
Therefore, file-access clients never need to access
NSDBs directly. These transactions are described in . A junction is a point in a particular fileset namespace
where a specific target fileset may be attached. If a
file-access client traverses the path leading from the root
of a federated namespace to the junction referring to a
target fileset, it should be able to mount and access the
data in that target fileset (assuming appropriate
permissions). In other words, a junction can be viewed as a
reference from a directory in one fileset to the root of the
target fileset. A junction can be implemented as a special marker on a
directory or by some other mechanism in the fileserver's
underlying file system. What data is used by the fileserver
to represent junctions is not defined by this document. The
essential property is that given a junction, a fileserver
must be able to find the FSN for the target fileset. When a file-access client reaches a junction, the
fileserver refers the client to a list of FSLs associated
with the FSN targeted by the junction. The client can then
mount one of the associated FSLs. The federation protocols do not limit where and
how many times a fileset is mounted in the namespace.
Filesets can be nested; a fileset can be mounted under
another fileset. The root fileset, when defined, is the top-level fileset
of the federation-wide namespace. The root of the unified
namespace is the top level directory of this fileset. A set of
designated fileservers in the federation can export the root
fileset to render the federation-wide unified namespace. When
a file-access client mounts the root fileset from any of these
designated fileservers, it can view a common federation-wide
namespace. To ensure FSN and FSL records are unique across a domain,
Federated File System (FedFS) employs UUIDs conforming to to
form the distinguished names of LDAP records containing FedFS
data (see ). Because junctions store a tuple containing an FSN UUID and
the name and port of an NSDB node, an FSN UUID must be unique
only on a single NSDB node. An FSN UUID collision can be
detected immediately when an administrator attempts to publish
an FSN or FSL by storing it under a specific NSDB Container Entry
(NCE) on an authoritative NSDB host. Note that one NSDB node may store multiple NCEs, each under
a different namingContext. If an NSDB node must contain more
than one NCE, the federation's admin entity SHOULD provide a
robust method for preventing FSN UUID collisions between FSNs
that reside on the same NSDB node but under different NCEs. Because FSLs are children of FSNs, FSL UUIDs must be unique
for just a single FSN. As with FSNs, as soon as an FSL is
published, its uniqueness is guaranteed. A fileserver performs the operations described in
as an unauthenticated user.
Thus, distinguished names of FSN and FSL records, as well as
the FSN and FSL records themselves, are required to be readable
by anyone who can bind anonymously to an NSDB node. Therefore,
FSN and FSL UUIDs should be considered public information. Version 1 UUIDs contain a host's Media Access Control (MAC) address and a timestamp
in the clear. This gives provenance to each UUID, but attackers
can use such details to guess information about the host where the
UUID was generated. Security-sensitive installations should be
aware that on externally facing NSDBs, UUIDs can reveal
information about the hosts where they are generated. In addition, version 1 UUIDs depend on the notion that a
hardware MAC address is unique across machines. As virtual
machines do not depend on unique physical MAC addresses and,
in any event, an administrator can modify the physical MAC
address, version 1 UUIDs are no longer considered sufficient. To minimize the probability of UUIDs colliding, a
consistent procedure for generating UUIDs should be used
throughout a federation. Within a federation, UUIDs SHOULD be
generated using the procedure described for version 4 of the
UUID variant specified in . In this section we provide examples and discussion of
the basic operations facilitated by the federated
file system protocol: creating a fileset, adding a replica of a
fileset, resolving a junction, and creating a junction. A fileset is the abstraction of a set of files and
the directory tree that contains them. The fileset
abstraction is the fundamental unit of data management
in the federation. This abstraction is implemented by
an actual directory tree whose root location is
specified by a fileset location (FSL). In this section, we describe the basic requirements
for starting with a directory tree and creating a
fileset that can be used in the federation protocols.
Note that we do not assume that the process of creating
a fileset requires any transformation of the files or
the directory hierarchy. The only thing that is
required by this process is assigning the fileset a
fileset name (FSN) and expressing the location of the
implementation of the fileset as an FSL. There are many possible variations to this
procedure, depending on how the FSN that binds the FSL
is created and whether other replicas of the fileset
exist, are known to the federation, and need to be bound
to the same FSN. It is easiest to describe this in terms of how to
create the initial implementation of the fileset and
then describe how to add replicas. The following administrative steps create
an FSN, which is used to track all
replicas of a single physical dataset. Choose the NSDB node that will keep
track of the FSL(s) and related
information for the fileset. Create an FSN in the NSDB node.
The FSN UUID is chosen by the administrator
or generated automatically by administration software.
The former case is used if the fileset is being
restored, perhaps as part of disaster
recovery, and the administrator wishes to
specify the FSN UUID in order to permit
existing junctions that reference that
FSN to work again.
At this point, the FSN exists, but its
fileset locations are unspecified. For the FSN created above, create an
FSL in the NSDB node that describes the
physical location of the fileset data. Adding a replica is straightforward: the NSDB
node and the FSN are already known. The only
remaining step is to add another FSL. Note that the federation protocols provide only
the mechanisms to register and unregister replicas
of a fileset. Fileserver-to-fileserver replication
protocols are not defined. A fileset may contain references to other filesets.
These references are represented by junctions. If a
file-access client requests access to a fileset object that
is a junction, the fileserver resolves the junction to
discover one or more FSLs that implement the referenced
fileset. There are many possible variations to this
procedure, depending on how the junctions are
represented by the fileserver and how the fileserver
performs junction resolution. Step 4 is the only step that interacts directly with
the federation protocols. The rest of the steps may
use platform-specific interfaces. The fileserver determines that the object being
accessed is a junction. The fileserver does a local lookup to find the
FSN of the target fileset. Using the FSN, the fileserver finds the NSDB
node responsible for the target FSN. The fileserver contacts that NSDB node and
asks for the set of FSLs that implement the target
FSN. The NSDB node responds with a (possibly
empty) set of FSLs. The fileserver converts one or more of the FSLs to
the location type used by the file-access client (e.g.,
an NFSv4 fs_locations attribute as described in
). The fileserver redirects (in whatever manner is
appropriate for the client) the client to the
location(s). Fileset annotations can convey additional attributes of
a fileset. For example, fileset annotations can be used to
define relationships between filesets that can be used by
an auxiliary replication protocol. Consider the scenario
where a fileset is created and mounted at some point in
the namespace. A snapshot of the read-write FSL of that
fileset is taken periodically at different frequencies
(say, a daily or weekly snapshot). The
different snapshots are mounted at different locations
in the namespace. The daily snapshots are considered as
different filesets from the weekly ones, but both are
related to the source fileset. We can define
an annotation labeling the filesets as source and
replica. The replication protocol can use this
information to copy data from one or more FSLs of the
source fileset to all the FSLs of the replica fileset.
The replica filesets are read-only while the source
fileset is read-write. This follows the traditional Andrew File System (AFS)
model of mounting the read-only volume at a path in the
namespace different from that of the read-write volume
. The federation protocol does not control or manage
the relationship among filesets. It merely enables
annotating the filesets with user-defined relationships.
Another potential use for annotations is recording
references to an FSN. A single annotation containing
the number of references could be defined, or multiple
annotations, one per reference, could be used to store
detailed information on the location of each reference.
As with the replication annotation described above, the
maintenance of reference information would not be controlled
by the federation protocol. The information would most
likely be non-authoritative because the ability to
create a junction does not require the authority to
update the FSN record. In any event, such annotations
could be useful to administrators for determining if an
FSN is referenced by a junction. This section describes how an NSDB is constructed using
an LDAP Version 3 directory.
describes the basic properties of
the LDAP configuration that MUST be used in order to ensure
compatibility between different implementations.
defines the new LDAP
attribute types and the new object types; it also specifies how the
distinguished name (DN) of each object instance MUST be
constructed. An NSDB is constructed using an LDAP directory.
This LDAP directory MAY have multiple naming contexts.
The LDAP directory's entry specific to Digital Signature Algorithm (DSA) (its rootDSE)
has a multi-valued namingContext attribute. Each value
of the namingContext attribute is the DN of a naming
context's root entry (see ). For each naming context that contains federation
entries (e.g., FSNs and FSLs): There MUST be an LDAP entry that is superior
to all of the naming context's federation entries in
the Directory Information Tree (DIT). This entry is
termed the NSDB Container Entry (NCE). The NCE's
children are FSNs. An FSN's children are FSLs.
The naming context's root entry MUST include
"fedfsNsdbContainerInfo" (defined in
)
as one of its object classes. The
fedfsNsdbContainerInfo's fedfsNceDN
attribute is used to locate the naming context's
NCE.
If a naming context does not contain federation entries,
it will not contain an NCE, and its root entry will not include
a "fedfsNsdbContainerInfo" as one of its object classes. A fedfsNsdbContainerInfo's fedfsNceDN attribute
contains the distinguished name (DN) of the NSDB Container
Entry residing under this naming context. The fedfsNceDN
attribute MUST NOT be empty. For example, an LDAP directory might have the following
entries: In this case, the "o=fedfs" namingContext has an NSDB
Container Entry at "o=fedfs", the "dc=example,dc=com" namingContext
has an NSDB Container Entry at "ou=fedfs,ou=corp-it,dc=example,dc=com",
and the "ou=system" namingContext has no NSDB Container Entry. The NSDB SHOULD be configured with one or more privileged
LDAP users. These users are able to modify the contents of the
LDAP database. An administrator that performs the operations
described in SHOULD authenticate
using the DN of a privileged LDAP user. It MUST be possible for an unprivileged (unauthenticated)
user to perform LDAP queries that access the NSDB data. A
fileserver performs the operations described in
as an unprivileged user. All implementations SHOULD use the same schema. At minimum,
each MUST use a schema that includes all objects named in the
following sections, with all associated attributes. If it is
necessary for an implementation to extend the schema defined
here, consider using one of the following ways to extend the
schema: Define a fedfsAnnotation key and values (see ). Register the new key and
values with IANA (see ).
Define additional attribute types and object classes,
then have entries inherit from a class defined in this
document and from the implementation-defined ones. Given the above configuration guidelines, an NSDB SHOULD
be constructed using a dedicated LDAP server. If LDAP
directories are needed for other purposes, such as to store
user account information, use of a separate LDAP server
for those is RECOMMENDED. By using an LDAP server dedicated
to storing NSDB records, there is no need to disturb the
configuration of any other LDAP directories that store
information unrelated to an NSDB. The schema definitions provided in this document use the LDAP schema
syntax defined in . The definitions are
formatted to allow the reader to easily extract them from the document.
The reader can use the following shell script to extract the definitions:
#!/bin/sh
grep '^ *///' | sed 's?^ */// ??' | sed 's?^ *///$??'
]]> If the above script is stored in a file called "extract.sh", and
this document is in a file called "spec.txt", then the reader can do:
sh extract.sh < spec.txt > fedfs.schema
]]> The effect of the script is to remove leading white space from each
line, plus a sentinel sequence of "///". Code components extracted from this document must include the
following license: <CODE BEGINS> <CODE ENDS> The following definitions are used in this document: The name attribute described in . The Integer syntax (1.3.6.1.4.1.1466.115.121.1.27) described in . The integerMatch rule described in . The Octet String syntax (1.3.6.1.4.1.1466.115.121.1.40) described in . The octetStringMatch rule described in . The Boolean syntax (1.3.6.1.4.1.1466.115.121.1.7) described in . The booleanMatch rule described in . The distinguishedNameMatch rule described in . The DN syntax (1.3.6.1.4.1.1466.115.121.1.12) described in . The labeledURI attribute described in . The UUID syntax (1.3.6.1.1.16.1) described in . The UuidMatch rule described in . The UuidOrderingMatch rule described in . A fedfsUuid is the base type for all of the
universally unique identifiers (UUIDs) used by the
federated file system protocols. The fedfsUuid type is based on rules and syntax
defined in . A fedfsUuid is a single-valued LDAP attribute. <CODE BEGINS> <CODE ENDS> A fedfsFsnUuid represents the UUID component of an FSN.
An NSDB SHOULD ensure that no two FSNs it stores have the same
fedfsFsnUuid. This attribute is single-valued. <CODE BEGINS> <CODE ENDS> A fedfsFsnTTL is the time-to-live in seconds of a
cached FSN and its child FSL records. It corresponds to
the FsnTTL as defined in .
See also for
information about caching FSLs. A fedfsFsnTTL MUST be
encoded as an Integer syntax value
in the range [0, 4294967295]. This attribute is single-valued. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . A fedfsNceDN stores a distinguished name (DN). This attribute is single-valued. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.12 is the DN
syntax . A fedfsFslUuid represents the UUID of an FSL.
An NSDB SHOULD ensure that no two FSLs it stores have the same
fedfsFslUuid. This attribute is single-valued. <CODE BEGINS> <CODE ENDS> A fedfsAnnotation contains an object annotation
formatted as a key/value pair. This attribute is multi-valued; an object type that
permits annotations may have any number of annotations
per instance. A fedfsAnnotation attribute is a human-readable
sequence of UTF-8 characters with no non-terminal NUL
characters. The value MUST be formatted according to
the following ABNF rules:
ANNOTATION = KEY "=" VALUE
KEY = ITEM
VALUE = ITEM
ITEM = *WSP DQUOTE UTF8-octets DQUOTE *WSP
DQUOTE and WSP are defined in ,
and UTF8-octets is defined in . The following escape sequences are allowed: escape sequencereplacement\\\ \"" A fedfsAnnotation value might be processed as follows: Parse the attribute value according to the ANNOTATION rule,
ignoring the escape sequences above. Scan through results of the previous step and replace the
escape sequences above. A fedfsAnnotation attribute that does not adhere to this
format SHOULD be ignored in its entirety. It MUST NOT prevent
further processing of its containing entry. The following are examples of valid fedfsAnnotation attributes: These correspond to the following key/value pairs: keyvaluekey1fooanother keyx=3key-2A string with " and \ characters.key3bar <CODE BEGINS> <CODE ENDS> A fedfsDescr stores an object description.
The description MUST be encoded as a UTF-8 string. This attribute is multi-valued, which permits
any number of descriptions per entry. <CODE BEGINS> <CODE ENDS> A fedfsNfsURI stores the host and pathname components
of an FSL. A fedfsNfsURI MUST be encoded as an NFS URI
(see ). The fedfsNfsURI is a subtype of the labeledURI type
, with the same encoding rules. This attribute is single-valued. <CODE BEGINS> <CODE ENDS> A fedfsNfsCurrency stores the NFSv4.1 fs_locations_server's
fls_currency value . A fedfsNfsCurrency
MUST be encoded as an Integer syntax value
in the range [-2147483648, 2147483647]. This attribute is single-valued. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . A fedfsNfsGenFlagWritable stores the
value of an FSL's NFSv4.1 FSLI4GF_WRITABLE bit
. A value of "TRUE"
indicates the bit is set. A value of
"FALSE" indicates the bit is not set. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean
syntax . A fedfsNfsGenFlagGoing stores the
value of an FSL's NFSv4.1 FSLI4GF_GOING bit
. A value of "TRUE"
indicates the bit is set. A value of
"FALSE" indicates the bit is not set. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean
syntax . A fedfsNfsGenFlagSplit stores the
value of an FSL's NFSv4.1 FSLI4GF_SPLIT bit
. A value of "TRUE"
indicates the bit is set. A value of
"FALSE" indicates the bit is not set. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean
syntax . A fedfsNfsTransFlagRdma stores the
value of an FSL's NFSv4.1 FSLI4TF_RDMA bit
. A value of "TRUE"
indicates the bit is set. A value of
"FALSE" indicates the bit is not set. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean
syntax . A fedfsNfsClassSimul contains the FSL's NFSv4.1
FSLI4BX_CLSIMUL value. A
fedfsNfsClassSimul MUST be encoded as an Integer
syntax value in the
range [0, 255]. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . A fedfsNfsClassHandle contains the FSL's NFSv4.1
FSLI4BX_CLHANDLE value. A
fedfsNfsClassHandle MUST be encoded as an Integer
syntax value in the
range [0, 255]. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . A fedfsNfsClassFileid contains the FSL's NFSv4.1
FSLI4BX_CLFILEID value. A
fedfsNfsClassFileid MUST be encoded as an Integer
syntax value in the
range [0, 255]. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . A fedfsNfsClassWritever contains the FSL's NFSv4.1
FSLI4BX_CLWRITEVER value. A
fedfsNfsClassWritever MUST be encoded as an Integer
syntax value in the
range [0, 255]. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . A fedfsNfsClassChange contains the FSL's NFSv4.1
FSLI4BX_CLCHANGE value. A
fedfsNfsClassChange MUST be encoded as an Integer
syntax value in the
range [0, 255]. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . A fedfsNfsClassReaddir contains the FSL's NFSv4.1
FSLI4BX_CLREADDIR value. A
fedfsNfsClassReaddir MUST be encoded as an Integer
syntax value in the
range [0, 255]. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . A fedfsNfsReadRank contains the FSL's NFSv4.1
FSLI4BX_READRANK value. A
fedfsNfsReadRank MUST be encoded as an Integer
syntax value in the
range [0, 255]. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . A fedfsNfsReadOrder contains the FSL's NFSv4.1
FSLI4BX_READORDER value. A
fedfsNfsReadOrder MUST be encoded as an Integer
syntax value in the
range [0, 255]. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . A fedfsNfsWriteRank contains the FSL's
FSLI4BX_WRITERANK value. A
fedfsNfsWriteRank MUST be encoded as an Integer
syntax value in the
range [0, 255]. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . A fedfsNfsWriteOrder contains the FSL's
FSLI4BX_WRITEORDER value. A
fedfsNfsWriteOrder MUST be encoded as an Integer
syntax value in the
range [0, 255]. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . A fedfsNfsVarSub stores the
value of an FSL's NFSv4.1 FSLI4IF_VAR_SUB bit
. A value of "TRUE"
indicates the bit is set. A value of
"FALSE" indicates the bit is not set. <CODE BEGINS> <CODE ENDS> OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean
syntax . A fedfsNfsValidFor stores an FSL's NFSv4.1 fs_locations_info
fli_valid_for value . A fedfsNfsValidFor
MUST be encoded as an Integer syntax value
in the range [-2147483648, 2147483647]. An FSL's parent's fedfsFsnTTL value and its fedfsNfsValidFor
value MAY be different. This attribute is single-valued. <CODE BEGINS> OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer
syntax . <CODE ENDS> A fedfsNsdbContainerInfo describes the location of
the NCE. A fedfsNsdbContainerInfo's fedfsNceDN attribute is
REQUIRED. A fedfsNsdbContainerInfo's fedfsAnnotation and
fedfsDescr attributes are OPTIONAL. <CODE BEGINS> <CODE ENDS> A fedfsFsn represents an FSN. A fedfsFsn's fedfsFsnUuid and fedfsFsnTTL attributes
are REQUIRED. A fedfsFsn's fedfsAnnotation and
fedfsDescr attributes are OPTIONAL. The DN of an FSN is REQUIRED to take the following
form: "fedfsFsnUuid=$FSNUUID,$NCE", where $FSNUUID
is the UUID of the FSN and $NCE is the DN of the NCE.
Since LDAP requires a DN to be unique, this ensures that
each FSN entry has a unique UUID value within the LDAP
directory. <CODE BEGINS> <CODE ENDS> The fedfsFsl object class represents an FSL. The fedfsFsl is an abstract object class. Protocol-specific
subtypes of this object class are used to
store FSL information. The fedfsNfsFsl object
class defined in
is used to record an NFS FSL's
location. Other subtypes MAY be defined for other
protocols (e.g., Common Internet File System (CIFS)). A fedfsFsl's fedfsFslUuid and fedfsFsnUuid
attributes are REQUIRED. A fedfsFsl's fedfsAnnotation and fedfsDescr
attributes are OPTIONAL. The DN of an FSL is REQUIRED to take the following
form: "fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE",
where $FSLUUID is the FSL's UUID, $FSNUUID is the FSN's
UUID, and $NCE is the DN of the NCE. Since LDAP
requires a DN to be unique, this ensures that each
FSL entry has a unique UUID value within the LDAP
directory. <CODE BEGINS> <CODE ENDS> A fedfsNfsFsl is used to represent an
NFS FSL. The fedfsNfsFsl inherits all of the
attributes of the fedfsFsl and extends the
fedfsFsl with information specific to the
NFS protocol. The DN of an NFS FSL is REQUIRED to take the following
form: "fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE",
where $FSLUUID is the FSL's UUID, $FSNUUID is the FSN's
UUID, and $NCE is the DN of the NCE. Since LDAP
requires a DN to be unique, this ensures that each
NFS FSL entry has a unique UUID value within the LDAP
directory. <CODE BEGINS> <CODE ENDS> The operations defined by the protocol can be described
as several sub-protocols that are used by entities within
a federation to perform different roles. The first of these sub-protocols defines how the state
of an NSDB node can be initialized and updated. The
primary use of this sub-protocol is by an administrator to
add, edit, or delete filesets, their properties, and their
fileset locations. The second of these sub-protocols defines the queries
that are sent to an NSDB node in order to perform
resolution (or to find other information about the data
stored within that NSDB node) and the responses returned
by the NSDB node. The primary use of this sub-protocol
is by a fileserver in order to perform resolution, but
it may also be used by an administrator to query the state
of the system. The first and second sub-protocols are defined as LDAP
operations, using the schema defined in the previous section.
If each NSDB node is a standard LDAP server, then, in
theory, it is unnecessary to describe the LDAP operations in
detail because the operations are ordinary LDAP operations
to query and update records. However, we do not require
that an NSDB node implement a complete LDAP service.
Therefore, we define the minimum level of
LDAP functionality required to implement an NSDB node. The NSDB sub-protocols are defined in
and
.
The descriptions of LDAP messages in these
sections use the LDAP Data Interchange Format (LDIF)
. In order to differentiate constant
and variable strings in the LDIF specifications, variables
are prefixed by a $ character and use all uppercase characters.
For example, a variable named FOO would be specified as $FOO. This document uses the term "NSDB client" to refer to an LDAP
client that uses either of the NSDB sub-protocols. The third sub-protocol defines the queries and
other requests that are sent to a fileserver in order to
get information from it or to modify the state of the
fileserver in a manner related to the federation
protocols. The primary purpose of this protocol is for
an administrator to create or delete a junction or discover
related information about a particular fileserver. The third sub-protocol is defined as an Open Network Computing (ONC)
Remote Procedure Call (RPC) protocol.
The reason for using ONC RPC instead of LDAP is that all
fileservers support ONC RPC, but some do not support an LDAP
directory server. The ONC RPC administration protocol is defined in
. The admin entity initiates and controls the commands
to manage fileset and namespace information. The protocol
used for communicating between the admin entity and each
NSDB node MUST be the LDAPv3
protocol. The names we assign to these operations are entirely
for the purpose of exposition in this document and are
not part of the LDAP dialogs. This operation creates a new FSN in
the NSDB by adding a new fedfsFsn entry in the
NSDB's LDAP directory. A fedfsFsn entry contains a fedfsFsnUuid.
The administrator chooses the fedfsFsnUuid by the
process described in .
A fedfsFsn entry also contains a fedfsFsnTTL.
The fedfsFsnTTL is chosen by the administrator
as described in . This operation is implemented using the LDAP ADD
request described by the LDIF below. For example, if $FSNUUID is
"e8c4761c-eb3b-4307-86fc-f702da197966", $TTL
is "300" seconds, and $NCE is "o=fedfs", the
operation would be: This operation deletes an FSN by removing a
fedfsFsn entry in the NSDB's LDAP directory. If the FSN entry being deleted has child FSL entries,
this function MUST return an error. This ensures that the
NSDB will not contain any orphaned FSL entries. A compliant LDAP
implementation will meet this requirement since Section 4.8
of defines the LDAP delete operation
to only be capable of removing leaf entries. Note that the FSN delete function removes the
fileset only from a federation namespace (by removing
the records for that FSN from the NSDB node that
receives this request). The fileset and its data
are not deleted. Any junction that has this FSN as
its target may continue to point to this
non-existent FSN. A dangling reference may be
detected when a fileserver tries to resolve a junction
that refers to the deleted FSN. This operation is implemented using the LDAP
DELETE request described by the LDIF below. For example, if $FSNUUID is
"e8c4761c-eb3b-4307-86fc-f702da197966" and $NCE
is "o=fedfs", the operation would be: This operation creates a new FSL for the
given FSN by adding a new fedfsFsl entry in the
NSDB's LDAP directory. A fedfsFsl entry contains a fedfsFslUuid and
fedfsFsnUuid. The
administrator chooses the fedfsFslUuid. The process
for choosing the fedfsFslUuid is described in
. The fedfsFsnUuid is
the UUID of the FSL's FSN. The administrator will also set additional
attributes depending on the FSL type. This operation is implemented using the LDAP
ADD request described by the LDIF below (Note:
the LDIF shows the creation of an NFS FSL.) For example, if $FSNUUID is "e8c4761c-eb3b-4307-86fc-f702da197966",
$FSLUUID is "ba89a802-41a9-44cf-8447-dda367590eb3",
$HOST is "server.example.com", $PORT is "20049",
$PATH is stored in the file "/tmp/fsl_path", $CURRENCY is "0" (an up-to-date
copy), the FSL is writable, but not going, split, or accessible
via Remote Direct Memory Access (RDMA),
the simultaneous-use class is "1", the handle class is "0", the fileid class is
"1", the write-verifier class is "1", the change class is "1", the readdir class is
"9", the read rank is "7", the read order is "8", the write rank is "5", the
write order is "6", variable substitution is false, $TIME is "300"
seconds, $ANNOTATION is ""foo" = "bar"", $DESC is "This is a description.",
and $NCE is "o=fedfs", the operation would be (for readability, the DN is
split into two lines): The fedfsNfsFSl object class is used to describe
NFSv4-accessible filesets. For the reasons described
in , administrators SHOULD
choose reasonable values for all LDAP attributes of an
NFSv4-accessible fedfsNfsFsl even though some of these LDAP
attributes are not explicitly contained in an NFSv4
fs_locations attribute. When the administrator is unable to choose reasonable
values for the LDAP attributes not explicitly contained
in an NFSv4 fs_locations attribute, the values in the
following table are RECOMMENDED. LDAP attributeLDAP valueNotesfedfsNfsCurrencynegative valueIndicates that the server does not know the currency (see
Section 11.10.1 of ).fedfsNfsGenFlagWritableFALSELeaving unset is not harmful (see Section 11.10.1 of ).fedfsNfsGenFlagGoingFALSENFS client will detect a migration event if the FSL becomes unavailable.fedfsNfsGenFlagSplitTRUESafe to assume that the FSL is split.fedfsNfsTransFlagRdmaTRUENFS client will detect if RDMA access is available.fedfsNfsClassSimul00 is treated as non-matching (see Section 11.10.1 of ).fedfsNfsClassHandle0See fedfsNfsClassSimul note.fedfsNfsClassFileid0See fedfsNfsClassSimul note.fedfsNfsClassWritever0See fedfsNfsClassSimul note.fedfsNfsClassChange0See fedfsNfsClassSimul note.fedfsNfsClassReaddir0See fedfsNfsClassSimul note.fedfsNfsReadRank0Highest value ensures FSL will be tried.fedfsNfsReadOrder0See fedfsNfsReadRank note.fedfsNfsWriteRank0See fedfsNfsReadRank note.fedfsNfsWriteOrder0See fedfsNfsReadRank note.fedfsNfsVarSubFALSENFSv4 does not define variable substitution in paths.fedfsNfsValidFor0Indicates no appropriate refetch interval (see Section 11.10.2 of ). This operation deletes an FSL record.
The admin requests the NSDB node storing the fedfsFsl to
delete it from its database. This operation does
not result in fileset data being deleted on any fileserver. The admin sends an LDAP DELETE request to the NSDB node
to remove the FSL. For example, if $FSNUUID is "e8c4761c-eb3b-4307-86fc-f702da197966",
$FSLUUID is "ba89a802-41a9-44cf-8447-dda367590eb3", and $NCE is
"o=fedfs", the operation would be (for readability, the DN is split into
two lines): This operation updates the attributes of a given FSL.
This command results in a change in the attributes of the
fedfsFsl at the NSDB node maintaining this FSL.
The values of the fedfsFslUuid and fedfsFsnUuid attributes
MUST NOT change during an FSL update.
The admin sends an LDAP MODIFY request to the NSDB node
to update the FSL. For example, if $FSNUUID is "e8c4761c-eb3b-4307-86fc-f702da197966",
$FSLUUID is "ba89a802-41a9-44cf-8447-dda367590eb3", $NCE is "o=fedfs",
and the administrator wished to change the NFS read rank to 10, the operation
would be (for readability, the DN is split into two lines): To find the NCEs for the NSDB nsdb.example.com, a fileserver would do
the following: Using an LDAP search, the fileserver can obtain
all of the FSLs for a given FSN. The FSN's fedfsFsnUuid
is used as the search key. The following examples use
the LDAP Uniform Resource Identifier (URI) format defined
in . To obtain a list of all FSLs for $FSNUUID on the NSDB
named $NSDBNAME, the following search can be used
(for readability, the URI is split into two lines): This search is for the children of the object with DN
"fedfsFsnUuid=$FSNUUID,$NCE" with a filter for
"objectClass=fedfsFsl". The scope value of "one" restricts
the search to the entry's children (rather than the entire
subtree below the entry), and the filter ensures that only
FSL entries are returned. For example, if $NSDBNAME is "nsdb.example.com", $FSNUUID
is "e8c4761c-eb3b-4307-86fc-f702da197966", and $NCE is
"o=fedfs", the search would be (for readability, the URI is split
into three lines): The following search can be used to obtain
only the NFS FSLs for $FSNUUID on the NSDB named
$NSDBNAME (for readability, the URI is split into two lines): This also searches for the children of the object with DN
"fedfsFsnUuid=$FSNUUID,$NCE", but the filter for
"objectClass = fedfsNfsFsl" restricts the results to only
NFS FSLs. For example, if $NSDBNAME is nsdb.example.com, $FSNUUID
is "e8c4761c-eb3b-4307-86fc-f702da197966", and $NCE is
"o=fedfs", the search would be (for readability, the URI is split
into three lines): The fileserver will generate a referral based on the
set of FSLs returned by these queries using the process
described in . The LDAPv3 protocol defines an LDAP referral mechanism
that allows an LDAP server to redirect an LDAP client. LDAPv3
defines two types of LDAP referrals: the Referral type defined
in Section 4.1.10 of and the
SearchResultReference type defined in Section 4.5.3 of
. In both cases, the LDAP referral
lists one or more URIs for services that can be used to
complete the operation. In the remainder of this document,
the term "LDAP referral" is used to indicate either of these
types. If an NSDB operation results in an LDAP referral, the
NSDB client MAY follow the LDAP referral. An NSDB client's
decision to follow an LDAP referral is implementation and
configuration dependent. For example, an NSDB client might
be configured to follow only those LDAP referrals that were
received over a secure channel or only those that target an
NSDB that supports encrypted communication. If an NSDB client
chooses to follow an LDAP referral, the NSDB client MUST
process the LDAP referral and prevent looping as described in
Section 4.1.10 of . Both the NFSv4 and LDAPv3 protocols provide security mechanisms. When used in
conjunction with the federated file system protocols described in
this document, the use of these mechanisms is RECOMMENDED. Specifically,
the use of RPCSEC_GSS , which is built on the
Generic Security Service Application Program Interface (GSS-API) , is RECOMMENDED on all NFS connections
between a file-access client and fileserver. The security considerations
sections of the NFSv4.0 and NFSv4.1
specifications contain special considerations for the handling of GETATTR
operations for the fs_locations and fs_locations_info attributes. NSDB nodes and NSDB clients MUST implement support for TLS
, as described in .
For all LDAP connections established by the federated file system
protocols, the use of TLS is RECOMMENDED. If an NSDB client chooses to follow an LDAP referral, the NSDB
client SHOULD authenticate the LDAP referral's target NSDB using the
target NSDB's credentials (not the credentials of the NSDB that
generated the LDAP referral). The NSDB client SHOULD NOT follow an
LDAP referral that targets an NSDB for which it does not know the
NSDB's credentials. Within a federation, there are two types of components an attacker
may compromise: a fileserver and an NSDB. If an attacker compromises a fileserver, the attacker can interfere
with a file-access client's file system input/output (I/O) operations
(e.g., by returning fictitious data in the response to a read request) or
can fabricate a referral.
The attacker's abilities are the same regardless of whether or not the
federation protocols are in use. While the federation protocols do not
give the attacker additional capabilities, they are additional targets for
attack. The LDAP protocol described in
SHOULD be secured using the methods described above to defeat attacks
on a fileserver via this channel. If an attacker compromises an NSDB, the attacker will be able to
forge FSL information and thus poison the fileserver's referral
information. Therefore, an NSDB should be as secure as the fileservers
that query it. The LDAP operations described in
SHOULD be secured using the methods described above to defeat attacks
on an NSDB via this channel. A fileserver binds anonymously when performing NSDB operations.
Thus, the contents and distinguished names of FSN and FSL records are
required to be readable by anyone who can bind anonymously to an NSDB
service. presents the security considerations
in the choice of the type of UUID used in these records. It should be noted that the federation protocols do not directly
provide access to file system data. The federation protocols only
provide a mechanism for building a namespace. All data transfers
occur between a file-access client and fileserver just as they would if
the federation protocols were not in use. As a result, the federation
protocols do not require new user authentication and authorization
mechanisms or require a fileserver to act as a proxy for a client. This document defines the fedfsAnnotation key in
. The fedfsAnnotation key namespace
is managed by IANA. IANA has created and now maintains a new
registry entitled "FedFS Annotation Keys". The location of this
registry is under a new heading called "Federated File System
(FedFS) Parameters". The URL address is
<http://www.iana.org/assignments/fedfs-parameters>. Future registrations are to be administered by IANA using the
"First Come First Served" policy defined in .
Registration requests MUST include the key (a valid UTF-8 string of
any length), a brief description of the key's purpose, and an email
contact for the registration. For viewing, the registry should be
sorted lexicographically by key. There are no initial assignments
for this registry. Using the process described in , one of
the authors was assigned the Internet Private Enterprise
Numbers range 1.3.6.1.4.1.31103.x. Within this range, the subrange
1.3.6.1.4.1.31103.1.x is permanently dedicated for use by the
federated file system protocols. Unassigned OIDs in this range
MAY be used for Private Use or Experimental Use as defined in
. New permanent FedFS OID assignments
MUST NOT be made using OIDs in this range. IANA has created and now maintains a new registry entitled "FedFS
Object Identifiers" for the purpose of recording the allocations of
FedFS Object Identifiers (OIDs) specified by this document. No
future allocations in this registry are allowed. The location of this registry is under the heading
"Federated File System (FedFS) Parameters", created in
. The URL address is
<http://www.iana.org/assignments/fedfs-parameters>. For viewing, the registry has been sorted numerically by OID
value. The contents of the "FedFS Object Identifiers" registry are
given in . Note: A descriptor designated below as "historic" reserves an OID
used in a past version of the NSDB protocol. Registering such OIDs
retains compatibility among existing implementations of the NSDB
protocol. This document does not otherwise refer to historic OIDs. OIDDescriptionReference 1.3.6.1.4.1.31103.1.1 fedfsUuid RFC 7532 1.3.6.1.4.1.31103.1.2 fedfsNetAddr historic 1.3.6.1.4.1.31103.1.3 fedfsNetPort historic 1.3.6.1.4.1.31103.1.4 fedfsFsnUuid RFC 7532 1.3.6.1.4.1.31103.1.5 fedfsNsdbName historic 1.3.6.1.4.1.31103.1.6 fedfsNsdbPort historic 1.3.6.1.4.1.31103.1.7 fedfsNcePrefix historic 1.3.6.1.4.1.31103.1.8 fedfsFslUuid RFC 7532 1.3.6.1.4.1.31103.1.9 fedfsFslHost historic 1.3.6.1.4.1.31103.1.10 fedfsFslPort historic 1.3.6.1.4.1.31103.1.11 fedfsFslTTL historic 1.3.6.1.4.1.31103.1.12 fedfsAnnotation RFC 7532 1.3.6.1.4.1.31103.1.13 fedfsDescr RFC 7532 1.3.6.1.4.1.31103.1.14 fedfsNceDN RFC 7532 1.3.6.1.4.1.31103.1.15 fedfsFsnTTL RFC 7532 1.3.6.1.4.1.31103.1.100 fedfsNfsPath historic 1.3.6.1.4.1.31103.1.101 fedfsNfsMajorVer historic 1.3.6.1.4.1.31103.1.102 fedfsNfsMinorVer historic 1.3.6.1.4.1.31103.1.103 fedfsNfsCurrency RFC 7532 1.3.6.1.4.1.31103.1.104 fedfsNfsGenFlagWritable RFC 7532 1.3.6.1.4.1.31103.1.105 fedfsNfsGenFlagGoing RFC 7532 1.3.6.1.4.1.31103.1.106 fedfsNfsGenFlagSplit RFC 7532 1.3.6.1.4.1.31103.1.107 fedfsNfsTransFlagRdma RFC 7532 1.3.6.1.4.1.31103.1.108 fedfsNfsClassSimul RFC 7532 1.3.6.1.4.1.31103.1.109 fedfsNfsClassHandle RFC 7532 1.3.6.1.4.1.31103.1.110 fedfsNfsClassFileid RFC 7532 1.3.6.1.4.1.31103.1.111 fedfsNfsClassWritever RFC 7532 1.3.6.1.4.1.31103.1.112 fedfsNfsClassChange RFC 7532 1.3.6.1.4.1.31103.1.113 fedfsNfsClassReaddir RFC 7532 1.3.6.1.4.1.31103.1.114 fedfsNfsReadRank RFC 7532 1.3.6.1.4.1.31103.1.115 fedfsNfsReadOrder RFC 7532 1.3.6.1.4.1.31103.1.116 fedfsNfsWriteRank RFC 7532 1.3.6.1.4.1.31103.1.117 fedfsNfsWriteOrder RFC 7532 1.3.6.1.4.1.31103.1.118 fedfsNfsVarSub RFC 7532 1.3.6.1.4.1.31103.1.119 fedfsNfsValidFor RFC 7532 1.3.6.1.4.1.31103.1.120 fedfsNfsURI RFC 7532 1.3.6.1.4.1.31103.1.1001 fedfsNsdbContainerInfo RFC 7532 1.3.6.1.4.1.31103.1.1002 fedfsFsn RFC 7532 1.3.6.1.4.1.31103.1.1003 fedfsFsl RFC 7532 1.3.6.1.4.1.31103.1.1004 fedfsNfsFsl RFC 7532 In accordance with Sections 3.4 and 4 of ,
the object identifier descriptors defined in this document (listed below) have
been registered via the Expert Review process. Request for LDAP Descriptor Registration
See "Author/Change Controller" RFC 7532 IESG (iesg@ietf.org) 1.3.6.1.4.1.31103.1.1 fedfsUuid attribute type 1.3.6.1.4.1.31103.1.2 fedfsNetAddr attribute type (historic) 1.3.6.1.4.1.31103.1.3 fedfsNetPort attribute type (historic) 1.3.6.1.4.1.31103.1.4 fedfsFsnUuid attribute type 1.3.6.1.4.1.31103.1.5 fedfsNsdbName attribute type (historic) 1.3.6.1.4.1.31103.1.6 fedfsNsdbPort attribute type (historic) 1.3.6.1.4.1.31103.1.7 fedfsNcePrefix attribute type (historic) 1.3.6.1.4.1.31103.1.8 fedfsFslUuid attribute type 1.3.6.1.4.1.31103.1.9 fedfsFslHost attribute type (historic) 1.3.6.1.4.1.31103.1.10 fedfsFslPort attribute type (historic) 1.3.6.1.4.1.31103.1.11 fedfsFslTTL attribute type (historic) 1.3.6.1.4.1.31103.1.12 fedfsAnnotation attribute type 1.3.6.1.4.1.31103.1.13 fedfsDescr attribute type 1.3.6.1.4.1.31103.1.14 fedfsNceDN attribute type 1.3.6.1.4.1.31103.1.15 fedfsFsnTTL attribute type 1.3.6.1.4.1.31103.1.100 fedfsNfsPath attribute type (historic) 1.3.6.1.4.1.31103.1.101 fedfsNfsMajorVer attribute type (historic) 1.3.6.1.4.1.31103.1.102 fedfsNfsMinorVer attribute type (historic) 1.3.6.1.4.1.31103.1.103 fedfsNfsCurrency attribute type 1.3.6.1.4.1.31103.1.104 fedfsNfsGenFlagWritable attribute type 1.3.6.1.4.1.31103.1.105 fedfsNfsGenFlagGoing attribute type 1.3.6.1.4.1.31103.1.106 fedfsNfsGenFlagSplit attribute type 1.3.6.1.4.1.31103.1.107 fedfsNfsTransFlagRdma attribute type 1.3.6.1.4.1.31103.1.108 fedfsNfsClassSimul attribute type 1.3.6.1.4.1.31103.1.109 fedfsNfsClassHandle attribute type 1.3.6.1.4.1.31103.1.110 fedfsNfsClassFileid attribute type 1.3.6.1.4.1.31103.1.111 fedfsNfsClassWritever attribute type 1.3.6.1.4.1.31103.1.112 fedfsNfsClassChange attribute type 1.3.6.1.4.1.31103.1.113 fedfsNfsClassReaddir attribute type 1.3.6.1.4.1.31103.1.114 fedfsNfsReadRank attribute type 1.3.6.1.4.1.31103.1.115 fedfsNfsReadOrder attribute type 1.3.6.1.4.1.31103.1.116 fedfsNfsWriteRank attribute type 1.3.6.1.4.1.31103.1.117 fedfsNfsWriteOrder attribute type 1.3.6.1.4.1.31103.1.118 fedfsNfsVarSub attribute type 1.3.6.1.4.1.31103.1.119 fedfsNfsValidFor attribute type 1.3.6.1.4.1.31103.1.120 fedfsNfsURI attribute type 1.3.6.1.4.1.31103.1.1001 fedfsNsdbContainerInfo object class 1.3.6.1.4.1.31103.1.1002 fedfsFsn object class 1.3.6.1.4.1.31103.1.1003 fedfsFsl object class 1.3.6.1.4.1.31103.1.1004 fedfsNfsFsl object class A user with the necessary authority to
initiate administrative tasks on one or more servers. A server or agent that administers a
collection of fileservers and persistently stores the namespace
information. Standard off-the-shelf, network-attached
storage (NAS) client software that communicates with
fileservers using a standard file-access protocol. A set of fileserver collections and
singleton fileservers that use a common set of interfaces and
protocols in order to provide to file-access clients a federated
namespace accessible through a file system access protocol. A server that stores physical fileset data
or refers file-access clients to other fileservers. A fileserver
provides access to its shared file system data via a file-access
protocol. The abstraction of a set of files and the
directory tree that contains them. A fileset is the
fundamental unit of data management in the federation.
Note that all files within a fileset are descendants of one
directory and that filesets do not span file systems. A self-contained unit of export for a
fileserver and the mechanism used to implement filesets. The
fileset does not need to be rooted at the root of the file system,
nor at the export point for the file system.
A single file system MAY implement more than one fileset, if the
file-access protocol and the fileserver permit this. A network file system access
protocol such as NFSv3 , NFSv4 , or
CIFS (Common Internet File System) . The location of the
implementation of a fileset at a particular moment in time. An FSL
MUST be something that can be translated into a protocol-specific
description of a resource that a file-access client can access directly,
such as an fs_locations attribute (for NFSv4) or a share name (for
CIFS). A platform-independent and globally
unique name for a fileset. Two FSLs that implement replicas of
the same fileset MUST have the same FSN, and if a fileset is
migrated from one location to another, the FSN of that fileset
MUST remain the same. A file system object used to link a directory
name in the current fileset with an object within another fileset.
The server-side "link" from a leaf node in one fileset to the root
of another fileset. A filename/directory tree that a
sufficiently authorized file-access client can observe. A service that maps
FSNs to FSLs. The NSDB may also be used to store other
information, such as annotations for these mappings and their
components. The name or location of a server that
implements part of the NSDB service and is responsible for keeping
track of the FSLs (and related information) that implement a given
partition of the FSNs. A server response to a file-access client
access that directs the client to evaluate the current object as a
reference to an object at a different location (specified by an FSL)
in another fileset and possibly hosted on another fileserver. The
client re-attempts the access to the object at the new location.
A redundant implementation of a
fileset. Each replica shares the same FSN but has a different
FSL.
Replicas may be used to increase availability or performance.
Updates to replicas of the same fileset MUST appear to occur in
the same order; therefore, each replica is self-consistent at
any moment.
We do not assume that updates to each replica occur simultaneously.
If a replica is offline or unreachable, the other replicas may be
updated. A set of fileservers administered as
a unit. A server collection may be administered with
vendor-specific software.
The namespace provided by a server collection could be part of the
federated namespace. A server collection containing only one server; a
stand-alone fileserver. Network File System (NFS) Version 4 ProtocolAn Overview of the Andrew File SystemAdministration Protocol for Federated File SystemsServer Message Block (SMB) Protocol SpecificationMicrosoft Corporation
Server Message Block (SMB) Version 2 Protocol SpecificationMicrosoft Corporation
Common Internet File System (CIFS) Protocol SpecificationMicrosoft Corporation
Daniel Ellard contributed significant parts of this document.
The authors and editor would like to thank Craig Everhart and
Manoj Naik, who were co-authors of an earlier draft version of this
document. In addition, we would like to thank Andy Adamson,
Paul Lemahieu, Mario Wurzl, and Robert Thurlow for helping to
author this document.
We would like to thank George Amvrosiadis, Trond Myklebust,
Howard Chu, and Nicolas Williams for their comments and review.
The editor gratefully acknowledges the IESG reviewers,
whose constructive comments helped make this a much stronger
document.
Finally, we would like to thank Andy Adamson, Rob Thurlow,
and Tom Haynes for helping to get this document out the door.
The extract.sh shell script and formatting conventions were
first described by the authors of the NFSv4.1 XDR specification
.