NFSv4 Working Group                                           J. Lentini
Internet-Draft                                               C. Everhart
Intended status: Standards Track                                  NetApp
Expires: August 24, 2009 January 11, 2010                                      D. Ellard
                                                        BBN Technologies
                                                               R. Tewari
                                                                 M. Naik
                                                             IBM Almaden
                                                       February 20,
                                                           July 10, 2009

                NSDB Protocol for Federated Filesystems
               draft-ietf-nfsv4-federated-fs-protocol-01
               draft-ietf-nfsv4-federated-fs-protocol-02

Status of this Memo

   This Internet-Draft is submitted to IETF in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on August 24, 2009. January 11, 2010.

Copyright Notice

   Copyright (c) 2009 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document. document (http://trustee.ietf.org/license-info).
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.

Abstract

   This document describes a file system filesystem 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 filesystems physically hosted on and exported by the constituent
   fileservers.

Requirements Language

   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 [RFC2119].

Table of Contents

   1.  Requirements notation  . . . . . . . . . . . . . . . . . . . .  4
   2.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  5
     2.1.  Protocol Goals . . . . . . . . . . . . . . . . . . . . . .  5
   3.  4
   2.  Overview of Features and Concepts  . . . . . . . . . . . . . .  7
     3.1.  4
     2.1.  Namespace  . . . . . . . . . . . . . . . . . . . . . . . .  7
     3.2.  5
     2.2.  Fileset and Fileset Name (FSN) . . . . . . . . . . . . . .  7
     3.3.  5
     2.3.  Fileset Location (FSL) . . . . . . . . . . . . . . . . . .  8
       3.3.1.  6
       2.3.1.  Mutual Consistency across Fileset Locations  . . . . .  7
       2.3.2.  Caching of Fileset Locations . . . . . . . . . . . . .  8
     3.4.
     2.4.  Namespace Database (NSDB)  . . . . . . . . . . . . . . . .  9
     3.5.  8
     2.5.  Mount Points, Junctions and Referrals  . . . . . . . . . . 10
     3.6.  9
     2.6.  Unified Namespace and the Root Fileset . . . . . . . . . . 10
     3.7.
     2.7.  Fileservers  . . . . . . . . . . . . . . . . . . . . . . . 11
     3.8. 10
     2.8.  File-access Clients  . . . . . . . . . . . . . . . . . . . 11
   4.  Interaction with client protocols  . . . . . . . . . . . . . . 12
     4.1.  Interaction with NFSv4 and NFSv4.1 . . . . . . . . . . . . 12
     4.2.  Interaction with other distributed file system
           protocols  . . . . . . . . . . . . . . . . . . . . . . . . 12
   5. 10
   3.  Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
     5.1.  Create 10
     3.1.  Creating a Fileset and its FSL(s)  . . . . . . . . . . . . . 13
       5.1.1. 11
       3.1.1.  Creating a Fileset and an FSN  . . . . . . . . . . . . 13
       5.1.2. 11
       3.1.2.  Adding a Replica of a Fileset  . . . . . . . . . . . . 14
     5.2. 12
     3.2.  Junction Resolution  . . . . . . . . . . . . . . . . . . . 14
     5.3. 12
     3.3.  Example use case Use Case for fileset annotations Fileset Annotations . . . . . . . . . 15
   6. 12
   4.  Mapping the NSDB onto LDAP . . . . . . . . . . . . . . . . . . 16
     6.1. 13
     4.1.  Basic LDAP Configuration . . . . . . . . . . . . . . . . . 16
     6.2. 13
     4.2.  LDAP Attributes  . Schema  . . . . . . . . . . . . . . . . . . . . 16
       6.2.1.  fedfsUuid  . . . . . . 14
       4.2.1.  LDAP Attributes  . . . . . . . . . . . . . . . . 16
       6.2.2.  fedfsNetAddr . . . 14
       4.2.2.  LDAP Objects . . . . . . . . . . . . . . . . . . 17
       6.2.3.  fsnUuid . . . 21
   5.  NSDB Operations  . . . . . . . . . . . . . . . . . . . . 17
       6.2.4.  nsdbName . . . 24
     5.1.  NSDB Operations for Administrators . . . . . . . . . . . . . . . . . . . . 18
       6.2.5.  fslHost  . . . . . . . . . . . . . . . . . . . . . . . 18
       6.2.6.  fslPath  . . . . . . . . . . . . . 24
       5.1.1.  Create an FSN  . . . . . . . . . . 18
       6.2.7.  fslUuid . . . . . . . . . . 25
       5.1.2.  Delete an FSN  . . . . . . . . . . . . . 19
       6.2.8.  type . . . . . . . 26
       5.1.3.  Create an FSL  . . . . . . . . . . . . . . . . . . 19
       6.2.9.  currency . . 26
       5.1.4.  Delete an FSL  . . . . . . . . . . . . . . . . . . . . 27
       5.1.5.  Update an FSL  . 19
       6.2.10. info . . . . . . . . . . . . . . . . . . . 27
     5.2.  NSDB Operations for Fileservers  . . . . . . 20
       6.2.11. annotation . . . . . . . 28
       5.2.1.  Lookup FSLs for an FSN . . . . . . . . . . . . . . . 20
       6.2.12. childFsnUuid . 28
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 29
   7.  IANA Considerations  . 20
       6.2.13. childNsdbName . . . . . . . . . . . . . . . . . . . . 21
     6.3. 29
     7.1.  LDAP Objects . Descriptor Registration . . . . . . . . . . . . . . . . . . . . . . 21
       6.3.1.  FsnObject  . . . . . . . . . . . . . . . . . . . . . . 21
       6.3.2.  FslObject  . 30
   8.  Glossary . . . . . . . . . . . . . . . . . . . . . 22
   7.  NSDB Protocol Operations . . . . . . 31
   9.  References . . . . . . . . . . . . . 23
     7.1.  Administrative NSDB Operations . . . . . . . . . . . . . 33
     9.1.  Normative References . 23
       7.1.1.  Creating an FSN . . . . . . . . . . . . . . . . . . 33
     9.2.  Informational References . 24
       7.1.2.  Deleting an FSN . . . . . . . . . . . . . . . . 34
   Appendix A.  Acknowledgments . . . 25
       7.1.3.  Create an FSL . . . . . . . . . . . . . . . . 35
   Authors' Addresses . . . . 25
       7.1.4.  Delete an FSL . . . . . . . . . . . . . . . . . . . . 26
       7.1.5.  Update 35

1.  Introduction

   A federated filesystem enables file access and namespace traversal in
   a uniform, secure and consistent manner across multiple independent
   fileservers within an FSL  . . . . . . . . . . . . . . . . . . . . 26
     7.2.  Fileserver enterprise or across multiple enterprises.

   This document specifies a set of protocols that allow fileservers,
   possibly from different vendors and with different administrators, to NSDB Operations  . . . . . . . . . . . . . . 27
       7.2.1.  Looking up FSLs for an FSN . . . . . . . . . . . . . . 27
   8.  Security Considerations  . . . . . . . . . . . . . . . . . . . 28
   9.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 29
   10. Conclusions  . . . . . . . . . . . . . . . . . . . . . . . . . 30
   11. Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
   12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34
     12.1. Normative References . . . . . . . . . . . . . . . . . . . 34
     12.2. Informational References . . . . . . . . . . . . . . . . . 35
   Appendix A.  Acknowledgments . . . . . . . . . . . . . . . . . . . 36
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 37

1.  Requirements notation

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
   cooperatively form a federation containing one or more federated
   filesystems.  Each federated filesystem's namespace is composed of
   the filesystems physically hosted on and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

2.  Introduction exported by the federation's
   fileservers.  A federated filesystem enables file access federation MAY contain a common namespace across all
   its fileservers.  A federation MAY project multiple namespaces and
   enable clients to traverse each one.  A federation MAY contain an
   arbitrary number of namespace traversal in repositories, each belonging to a uniform, secure
   different administrative entity, and consistent manner across multiple independent
   fileservers within each rendering a part of the
   namespace.  A federation MAY also have an enterprise (and possibly across multiple
   enterprises) with reasonably good performance. 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 filesystems.  Relying  However, relying
   on vendor-
   proprietary vendor-proprietary tools does not work in larger enterprises or
   when collaborating across enterprises because it is likely that the system
   will contain fileservers running are
   likely to be from multiple vendors or use different software, software
   versions, each with their own namespace protocols, with no common protocol
   mechanism to manage the namespace or exchange namespace information.

   The federated filesystem federation protocol described below allows fileservers
   from different vendors and/or with different administrators protocols in this document define how to
   cooperatively build
   construct a namespace.

   The scope of the filesystem federation protocol is currently limited
   to namespace accessible by an NFSv4 [RFC3530] or NFSv4.1
   [NFSv4.1] capable fileservers.  The
   federation protocols client and have been designed to accommodate other file
   access protocols in the future.

   The requirements for federated namespaces filesystems are described in
   [FEDFS-REQTS].

2.1.  Protocol Goals

   The objective of this draft is to specify a set of protocols by which
   fileservers, possibly with different administrators, can form a
   fileserver federation that provides a namespace composed of the
   filesystems physically hosted on and exported by the fileservers of
   the federation.  It should be possible, using systems that implement
   the federation protocols, to share a common namespace across all the
   fileservers in the federation.  It should also be possible  A protocol for the
   federation to project multiple namespaces and enable clients to
   traverse each one.  Such administering a federation may contain an arbitrary number
   of fileserver's namespace repositories, each belonging to a different
   administrative entity, and each rendering a part of the namespace.
   Such a federation may also have an arbitrary number of administrative
   entities responsible for administering disjoint subsets of the
   fileservers.
   is described in [FEDFS-ADMIN].  In the rest of the document document, the term
   fileserver implies denotes a fileserver that is part of the a federation.

3.

2.  Overview of Features and Concepts

3.1.

2.1.  Namespace

   The goal of a unified namespace is to make all managed data available
   to all clients via the same path in a common filesystem-like
   namespace.  This should be achieved with minimal or zero client
   configuration.  In particular, updates to the common namespace should
   not require configuration changes at the client.  Filesets, which are
   the unit of data management, are a set of files and directories.
   From the perspective of the 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 definitions, fileset identifiers, the location of each
   fileset in the namespace, and the physical location of the
   implementation(s) of each fileset, 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.

3.2.

2.2.  Fileset and Fileset Name (FSN)

   A fileset is defined to be a container of data and is the basic unit
   of data management.  Depending on the implementation, they may be
   anything between an individual directory of an exported filesystem to
   an entire exported filesystem at a fileserver.  A fileset is uniquely
   represented by its fileset name (FSN).  An FSN is considered unique
   across the federation.  An FSN contains information sufficient to
   locate the namespace database (NSDB) that holds authoritative
   information about it and an identifier, called the FsnUuid, that
   identifies it on that NSDB.  After an FSN is created, it is
   associated with a fileset location (FSL) on a fileserver.  A fileset
   can be implemented by one or more FSLs.  The attributes of an FSN
   are:

      NsdbName:  the fully qualified domain name of an NSDB location
         that contains authoritative information for this FSN.

      FsnUuid:  a 128-bit UUID (universally unique identifier),
         conforming to [RFC4122], that is used to uniquely identify an
         FSN.  To minimize the probability of two UUIDs colliding, a
         consistent procedure for generating UUIDs SHOULD be used
         throughout the federation.  Within the federation, UUIDs SHOULD
         be generated using the procedure described for version 1 of the
         UUID variant specified in [RFC4122].  An NSDB SHOULD ensure
         that no two FSNs it stores have the same FsnUuid.

3.3.

2.3.  Fileset Location (FSL)

   An FSL represents the location where the fileset data resides.  Each
   FSL contains a host:path pair on a file server.  An the host addresses of the fileserver storing the FSL may also have
   additional attributes. and
   protocol specific information for accessing the FSL.  Each location
   has an associated type that determines the protocol(s) that may be
   used to access its data.  Type information can be used to decide the
   list of locations that will be returned to the client.  Other attributes associated with an FSL are
   based on the NFSv4.1 fs_locations_info attribute [NFSv4.1].

   Each FSL consists of:

   FslHost:

      FslUuid:  a 128-bit UUID, conforming to [RFC4122], that is used to
         uniquely identify an FSL.  To minimize the probability of two
         UUIDs colliding, a consistent procedure for generating UUIDs
         SHOULD be used throughout the federation.  Within the
         federation, UUIDs SHOULD be generated using the procedure
         described for version 1 of the UUID variant specified in
         [RFC4122].  An NSDB SHOULD ensure that no two FSLs it stores
         have the same FslUuid.

      FsnUuid:  the 128-bit UUID of the FSL's FSN.

      NsdbName:  the fully qualified domain name of an NSDB location
         that contains authoritative information for this FSL.

      FSL Host:  the fully qualified domain name of the host fileserver
         storing the physical data

   FslPathname:

      FSL TTL:  the time in seconds during which the FSL may be cached

      Annotations:  optional 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.

      Descriptions:  optional text descriptions.  The semantics of this
         field are not defined by this document.

   In addition, an NFS FSL contains information suitable for an NFSv4
   fs_locations [RFC3530] or NFSv4.1 fs_locations_info attribute
   [NFSv4.1]:

      Pathname:  the exported pathname at that host fileserver

   FslUuid:  the 128-bit UUID of

      Major Version:  the FSL

   Type: NFS protocol major version (e.g. 4 for
         NFSv4.1)
      Minor Version:  the NFS protocol that should be used to access this FSL minor version (e.g.
      NFSv4 or 1 for
         NFSv4.1)

      Currency:  the time lag of this FSL represented as the number of
         time units it lags the latest version as defined by the NFSv4.1
         fs_locations_server's fls_currency field.  A currency value of
         0 represents the latest version.  Currency values are less than
         or equal to zero

      Info:  as defined in by the NFSv4.1 fs_locations_info attribute

   Annotations:  a list of name/value pairs that can fl_locations_server's fls_info
         field.

      Flags:  as defined by the NFSv4.1 fs_locations_info's fli_flags
         field.

      Valid For:  as defined by the NFSv4.1 fs_locations_info's
         fli_valid_for field.

   A fileset MAY be interpreted accessible by protocols other than NFS.  For each
   such protocol, a
      fileserver and used to generate a referral. corresponding FSL subtype SHOULD be defined.  The semantics
   contents and format of the
      name/value pair is such FSL subtypes are not defined by in this protocol and is intended to
      be used by higher-level protocols.  This field MAY be used to
      store the NFSv4.1 fl_locations_server's fls_info values

3.3.1.
   document.

2.3.1.  Mutual Consistency across Fileset Locations

   All of the FSLs that have the same FSN (thereby reference the same
   fileset) are equivalent from the point of view of client access; the
   different locations of a fileset represent the same data, though
   potentially at different points in time.  Fileset locations are
   equivalent but not identical.  Locations may either be read-only or
   read-write.  Typically, multiple read-write locations are backed by a
   clustered filesystem while read-only locations are replicas created
   by a federation-initiated or external replication.  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, all locations exist at the same mount point
   in the namespace and, thus, one client may be referred to one
   location while another is directed to a different location.  Since
   updates to each fileset location are not controlled by the federation
   protocol, it is the responsibility of administrators to guarantee guarantee the
   functional equivalence of the data.

   The federation protocol does not guarantee that the different
   locations are mutually consistent in terms of the currency of the
   data.  It relies on the client file-access protocol (i.e., NFSv4) to
   contain sufficient information to help the clients determine the
   currency of the data at each location in order to ensure that the
   clients do not revert back in time when switching locations.

2.3.2.  Caching of Fileset Locations

   To resolve an FSN to a set of FSL records, the fileserver queries the
   appropriate NSDB for the FSL records.  A fileserver MAY cache these
   FSL records for a limited period of time.  The period of time, if
   any, during which FSL records are cached is indicated by the FSL's
   TTL field.

   The combination of FSL caching and FSL migration presents a
   challenge.  For example, suppose there are three fileservers named A,
   B, and C and fileserver A contains a junction to fileset X stored on
   fileserver B. Now suppose that fileset X is migrated from fileserver
   B to fileserver C and the corresponding FSL information for fileset X
   in the appropriate NSDB is updated.  If fileserver A has a cached FSL
   for fileset X, a user traversing the junction on fileserver A will be
   referred to fileserver B even though fileset X has migrated to
   fileserver C. If fileserver A was not caching FSL records, it would
   have obtained the correct location of fileset X from the NSDB.

   Administrators are advised to be aware of FSL caching when performing
   a migration.  When migrating a fileset, administrators SHOULD create
   a junction at the fileset's old location referring back to the NSDB
   entry for the fileset.  This junction will redirect any users who
   follow stale FSL information to the
   functional equivalence of correct location.  Thus, in the data.

   The federation protocol does
   above example, fileserver A would direct clients to fileserver B, but
   fileserver B would in turn direct clients to fileserver C.

   Such supplemental junctions (on fileserver B in the example) would
   not guarantee that be required to be in place forever.  They need to stay in place
   only until cached FSL entries for the different
   locations target fileset are mutually consistent invalidated.
   Each FSL contains a TTL field, a count in terms seconds of the currency of time
   interval which is an upper bound for the
   data.  It relies on lifetime of the client file-access protocol (i.e., NFSv4) to
   contain sufficient cached
   information to help the clients determine and a lower bound for the
   currency lifetime of the data at each location in order to ensure that supplemental
   junctions.  For example, suppose this field contains the
   clients do not revert back value 3600
   seconds (one hour).  In such a case, administrators MUST keep the
   supplemental junctions in time when switching locations.

3.4. place for at least one hour after the
   fileset move has taken place, and FSL data MUST NOT be cached by a
   referring fileserver for more than one hour without a refresh.

2.4.  Namespace Database (NSDB)

   The NSDB service is a federation-wide service that provides
   interfaces to define, update, and query FSN information and FSN to
   FSL mapping information.  An individual repository of namespace
   information is called an NSDB location.  Each NSDB location is
   managed by a single administrative entity.  A single admin entity can
   manage multiple NSDB locations.

   The difference between the NSDB service and an NSDB location is
   analogous to that between the DNS service and a particular DNS
   server.

   Each NSDB location 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 location is authoritative for the filesets
   that it defines.  An NSDB location can cache information from a peer
   NSDB location.  The fileserver can always contact a local NSDB
   location (if it has been defined) or directly contact any NSDB
   location to resolve a junction.  Each NSDB location supports an LDAP
   [RFC4510] interface and can be accessed by an LDAP client.

   An NSDB MAY be replicated throughout the federation.  If an NSDB is
   replicated, the NSDB MUST exhibit loose, converging consistency as
   defined in [RFC3254].  The mechanism by which this is achieved is
   outside the scope of this document.  Many LDAP implementations
   support replication.  These features MAY be used to replicate the
   NSDB.

3.5.

2.5.  Mount Points, Junctions and Referrals

   A mount point is a directory in a parent fileset where a target
   fileset may be attached.  If a client traverses the path leading from
   the root of the namespace to the mount point of a target fileset it
   should be able to access the data in that target fileset (assuming
   appropriate permissions).

   The directory where a fileset is mounted is represented by a junction
   in the underlying filesystem.  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 that is interpreted by the fileserver as a
   mount point, or by some other mechanism in the underlying file
   system. filesystem.

   What data is used by the underlying file system filesystem to represent the
   junction is not defined by this protocol.  The essential property is
   that the server must be able to find, given the junction, the FSN for
   the target fileset.  The mechanism by which the server maps a
   junction to an FSN is outside the scope of this document.  The FSN
   (as described earlier) contains both the the authoritative NSDB
   location and the FsnUuid (a UUID for the fileset).

   When a client traversal reaches a junction, the client is referred to
   a list of FSLs associated with the FSN that was the target of the
   junction.  The client can then redirect its connection to one of the
   FSLs.  This act is called a referral.  For NFSv4 and NFSv4.1 clients,
   the FSL information is returned in the fs_locations or and
   fs_locations_info
   attributes. attributes respectively.

   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.

3.6.

2.6.  Unified Namespace and the Root 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 client mounts the root
   fileset from any of these designated fileservers it can view a common
   federation-wide namespace.  The properties and schema definition of
   the root fileset and the protocol details that describe how to
   configure and replicate the root fileset are available not defined in a companion
   draft [To be Published].

3.7. this
   document.

2.7.  Fileservers

   Fileservers are NFSv4 or NFSv4.1 servers that store the physical fileset data or fileservers that refer
   the client to other fileservers.  A fileserver can be implemented in
   a number of different ways, including a single system, a cluster of
   systems, or some other configuration.

3.8.  File-access Clients

   File access clients are standard off-the-shelf NAS clients that  A fileserver access file data using the NFSv4 protocol, the NFSv4.1 protocol, or
   some other protocol.

4.  Interaction with client protocols

4.1.  Interaction with NFSv4 and NFSv4.1

   The federation protocol is compatible with the requirements of NFSv4
   referral mechanisms as defined in [RFC3530] and the NFSv4.1 referral
   mechanisms as defined in [NFSv4.1].

4.2.  Interaction with other distributed file system protocols

   The federation protocol does not mandate a specific format for
   pathnames.  Therefore it is possible to store the pathnames used by a
   variety of distributed
   federated filesystem via NFSv4, NFSv4.1, or some other protocol.

2.8.  File-access Clients

   File access clients are standard off-the-shelf NAS clients that
   access file systems, including CIFS.

5. data using the NFSv4 protocol, the NFSv4.1 protocol, or
   some other protocol.

3.  Examples

   In this section we provide examples and discussion of the basic
   operations facilitated by the federated file system filesystem protocol: creating
   a fileset, adding a replica of a fileset, resolving a junction, and
   creating a junction.

5.1.  Create

3.1.  Creating a Fileset and its FSL(s)

   A fileset is the abstraction of a set of files and their containing
   directory tree.  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(s) of the implementation of the fileset as FSL(s).

   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.

5.1.1.

3.1.1.  Creating a Fileset and an FSN

   1.  Choose the NSDB node that will keep track of the FSL(s) and
       related information for the fileset.

   2.  Request that the NSDB node register a new FSN for the fileset.

       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.

   3.  Send the FSN, the hostname, the export path, the type, the
       currency, info, and annotations for the fileset to the NSDB node.

       The NSDB node records this info and creates the initial FSL for
       the fileset.

5.1.2.

3.1.2.  Adding a Replica of a Fileset

   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 do not include methods for
   creating or managing replicas: this is assumed to be a platform-
   dependent operation (at least at this time).  The only interface
   required is the ability to register or remove the registration of
   replicas for a fileset.

5.2.

3.2.  Junction Resolution

   A fileset may contain references to other filesets.  These references
   are represented by junctions.  If a client requests access to a
   fileset object that is a junction, the server resolves the junction
   to discover the FSL(s) that implements the referenced fileset.

   There are many possible variations to this procedure, depending on
   how the junctions are represented and how the information necessary
   to perform resolution is represented by the server.

   Step 4 is the only step that interacts directly with the federation
   protocols.  The rest of the steps may use platform-specific
   interfaces.

   1.  The server determines that the object being accessed is a
       junction.

   2.  The server does a local lookup to find the FSN of the target
       fileset.

   3.  Using the FSN, the server finds the NSDB node responsible for the
       target object.

   4.  The server contacts that NSDB node and asks for the set of FSLs
       that implement the target FSN.  The NSDB node responds with a set
       of FSLs.

5.3.

3.3.  Example use case Use Case for fileset annotations Fileset Annotations

   The 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
   snapshot or a weekly snapshot.  The different snapshots are mounted
   at different locations in the namespace.  The daily snapshots are
   considered as a different fileset from the weekly ones but both are
   related to the source fileset.  For this 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 AFS 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. read-write volume [AFS].

   The federation protocol does not control or manage the relationship
   among filesets.  It merely enables annotating the filesets with user-
   defined relationships.

6.

4.  Mapping the NSDB onto LDAP

   This section describes the LDAP schema used to define the LDAP
   implementation of the how an NSDB service.  The first part of the section is constructed using an LDAP
   Version 3 [RFC4510] Directory.  Section 4.1 describes the basic
   properties of the LDAP configuration that MUST be used in order to
   ensure compatibility between different implementations.  The second section  Section 4.2
   defines the new LDAP attribute
   types and the subsequent sections describe types, the new object types types, and
   specify
   specifies how the distinguished name (DN) of each object instance
   MUST be constructed.

6.1.

4.1.  Basic LDAP Configuration

   The base name (or suffix) for all DNs used by of the NSDB schema directory information tree
   (DIT) is
   "dc=fed-fs,dc=com". "o=fedfs".

   The DN of the privileged LDAP user is, by convention,
   "cn=admin,dc=fed-fs,dc=com".
   "cn=admin,o=fedfs".  This user is able to modify the contents of the
   LDAP database.  It is permitted to use a different DN (or add
   additional privileged users) but if a different DN is used then every
   admin entity that needs to modify the contents of the database or
   view privileged information must be made aware of the new DN.

   It MUST be possible for the anonymous (unauthenticated) user to
   perform LDAP queries that access the NSDB data.

   All implementations SHOULD use the same schema, or, at minimum, a
   schema that includes all of the objects, with each of the attributes,
   named in the following sections.

6.2.

4.2.  LDAP Schema

   The schema definitions provided in this document use the LDAP schema
   syntax defined in [RFC4512].  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:

           <CODE BEGINS>

           #!/bin/sh
           grep '^ *///' | sed 's?^ */// ??' | sed 's?^ *///$??'

           <CODE ENDS>

   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:

           <CODE BEGINS>

           sh extract.sh < spec.txt > fedfs.schema

           <CODE ENDS>

   The effect of the script is to remove leading white space from each
   line, plus a sentinel sequence of "///".

4.2.1.  LDAP Attributes

   This section describes the required attributes of the NSDB LDAP
   schema.

6.2.1.

4.2.1.1.  fedfsUuid

   A fedfsUuid is the base type for all of the universally unique
   identifiers (UUIDs) used by the federated file system filesystem protocols.

   This SHOULD be defined in terms of the text representation of the
   standard UUID (as defined in [RFC4122]).

   It MAY also be useful, for purposes of debugging or annotation, to
   permit a fedfsUuid to include members of a more general class of
   strings.

   A fedfsUuid is a single-valued LDAP attribute.  It is formally
   defined as follows:

           ///
           /// attributetype (
           ///     1.3.6.1.4.1.31103.1.1 NAME 'fedfsUuid'
           ///     DESC 'a 'A UUID used by NSDB'
           ///     SUP name
           ///     SINGLE-VALUE
           ///     )

6.2.2.
           ///

4.2.1.2.  fedfsNetAddr

   A fedfsNetAddr is the locative name of a network service.  It MUST be
   a UTF-8 string and represent a network location in either IPv4, IPv6,
   or DNS host name notation.  The format is the same as that specified
   for an fs_location4's server array elements in section 11.9 of
   [NFSv4.1].

   This attribute is single-valued.  It is formally defined as follows:

           ///
           /// attributetype (
           ///     1.3.6.1.4.1.31103.1.2 NAME 'fedfsNetAddr'
           ///     DESC 'a 'The network name of a host or service'
           ///     SUP name
           ///     SINGLE-VALUE
           ///     )

6.2.3.
           ///

4.2.1.3.  fsnUuid

   A fsnUuid represents the fsnUuid component of an FSN.

   The fsnUuid is a subclass of fedfsUuid.

   This attribute is single-valued.

           ///
           /// attributetype (
           ///     1.3.6.1.4.1.31103.1.3 NAME 'fsnUuid'
           ///     DESC 'the 'The FSN UUID component of an FSN'
           ///     SUP fedfsUuid
           ///     SINGLE-VALUE
           ///     )

6.2.4.
           ///

4.2.1.4.  nsdbName

   An nsdbName is the NSDB component of an FSN.

   The nsdbName attribute is a subclass of fedfsNetAddr.

   This attribute is single-valued.

           ///
           /// attributetype (
           ///     1.3.6.1.4.1.31103.1.4 NAME 'nsdbName'
           ///     DESC 'the 'The NSDB location component of an FSN'
           ///     SUP fedfsNetAddr
           ///     SINGLE-VALUE
           ///     )
           ///

4.2.1.5.  fslUuid

   Each FSL must have a UUID associated with it, which serves as part of
   its DN.

   The fslUuid attribute is a subclass of fedfsUuid.

   This attribute is single-valued.

           ///
           /// attributetype (
           ///     1.3.6.1.4.1.31103.1.5 NAME 'fslUuid'
           ///     DESC 'UUID of an FSL'
           ///     SUP fedfsUuid
           ///     SINGLE-VALUE
           ///     )

6.2.5.
           ///

4.2.1.6.  fslHost

   An fslHost is the hostname/port component of an FSL.

   The fslHost attribute is a subclass of fedfsNetAddr. subclass of fedfsNetAddr.

   This attribute is single-valued.

           ///
           /// attributetype (
           ///     1.3.6.1.4.1.31103.1.6 NAME 'fslHost'
           ///     DESC 'Service location for a fileserver'
           ///     SUP fedfsNetAddr
           ///     SINGLE-VALUE
           ///     )
           ///

4.2.1.7.  fslTTL

   An fslTTL is the amount of time in seconds an FSL SHOULD be cached by
   a fileserver.  The numeric fslTTL value should be converted to a
   string and encoded as a UTF-8 string.

   This attribute is single-valued.

           ///
           /// attributetype (
                           1.3.6.1.4.1.31103.1.5
           ///     1.3.6.1.4.1.31103.1.7 NAME 'fslHost' 'fslTTL'
           ///     DESC 'service location for a fileset server' 'Time to live of an FSL'
           ///     SUP fedfsNetAddr name
           ///     SINGLE-VALUE
           ///     )

6.2.6.  fslPath
           ///

4.2.1.8.  fslNfsPath

   The path component of an FSL. FSL encoded as a UTF-8 string.

   This attribute is single-valued.

           ///
           /// attributetype (
                           1.3.6.1.4.1.31103.1.6
           ///     1.3.6.1.4.1.31103.1.8 NAME 'fslPath' 'fslNfsPath'
           ///     DESC 'server-local 'Server-local path to a fileset'
           ///     SUP name
           ///     SINGLE-VALUE
           ///     )

6.2.7.  fslUuid

   Each FSL must have a UUID associated with it, which serves as part
           ///

4.2.1.9.  fslNfsMajorVer

   The NFS major version of
   its DN. the associated NFS FSL.  The fslUuid attribute is numeric fslTTL
   value should be converted to a subclass string and encoded as a UTF-8 string.

   For example if the FSL was exported via NFS 4.1, the contents of fedfsUuid. this
   attribute would be the value 4.

   This attribute is single-valued.

           ///
           /// attributetype (
                           1.3.6.1.4.1.31103.1.7
           ///     1.3.6.1.4.1.31103.1.9 NAME 'fslUuid' 'fslNfsMajorVer'
           ///     DESC 'UUID of an FSL' 'NFS major version'
           ///     SUP fedfsUuid name
           ///     SINGLE-VALUE
           ///     )

6.2.8.  type
           ///

4.2.1.10.  fslNfsMinorVer

   The type NFS minor version of an FSL.

   This attribute is used to specify the distribute file system protocol
   that can be used to access an associated NFS FSL.  The following values are defined
   for this field:

   nfsv4 : numeric fslTTL
   value should be converted to a string and encoded as a UTF-8 string.

   For example if the FSL is accessible was exported via NFS 4.1, the NFSv4 protocol.

   Values for other protocols may contents of this
   attribute would be defined at a later time. the value 1.

   This attribute is single-valued.

           ///
           /// attributetype (
                           1.3.6.1.4.1.31103.1.8
           ///     1.3.6.1.4.1.31103.1.10 NAME 'type' 'fslNfsMinorVer'
           ///     DESC 'CIFS, NFS, etc' 'NFS minor version'
           ///     SUP name
           ///     SINGLE-VALUE
           ///     )

6.2.9.  currency
           ///

4.2.1.11.  fslNfsCurrency

   The currency of an FSL.  The signed 32-bit numeric value should be
   converted to a string encoded as a UTF-8 string.

   This attribute is used to populate the NFSv4.1 fs_locations_info's fs_locations_server's
   currency field.

   This attribute is single-valued.

           ///
           /// attributetype (
                           1.3.6.1.4.1.31103.1.9
           ///     1.3.6.1.4.1.31103.1.11 NAME 'currency' 'fslNfsCurrency'
           ///     DESC 'up-to-date measure of the data'
           ///     SUP name
           ///     SINGLE-VALUE
           ///     )

6.2.10.  info
           ///

4.2.1.12.  fslNfsInfo

   Information about the FSL.  The variable sized array of octets is
   stored directly in this attribute.

   This attribute is used to populate the NFSv4.1 fs_locations_info's fs_locations_server's
   info field.

   This attribute is single-valued.

           ///
           /// attributetype (
           ///     1.3.6.1.4.1.31103.1.12 NAME 'fslNfsInfo'
           ///     DESC 'Information about the FSL'
           ///     EQUALITY octetStringMatch
           ///     SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
           ///     SINGLE-VALUE
           ///     )
           ///

   1.3.6.1.4.1.1466.115.121.1.40 refers to the Octet String syntax
   [RFC4517].

4.2.1.13.  fslNfsFlags

   An NFS FSL's flags.  The unsigned 32-bit numeric value should be
   converted to a string encoded as a UTF-8 string.

   This attribute is used to populate the NFSv4.1 fs_locations_info's
   fli_flags field.

   This attribute is single-valued.

           ///
           /// attributetype (
           ///     1.3.6.1.4.1.31103.1.13 NAME 'fslNfsFlags'
           ///     DESC 'Flags'
           ///     SUP name
           ///     SINGLE-VALUE
           ///     )
           ///

4.2.1.14.  fslNfsValidFor

   An NFS FSL's "valid for" flag.  The signed 32-bit numeric value
   should be converted to a string encoded as a UTF-8 string.

   This attribute is used to populate the NFSv4.1 fs_locations_info's
   fli_valid_for field.

   This attribute is single-valued.

           ///
           /// attributetype (
                           1.3.6.1.4.1.31103.1.10
           ///     1.3.6.1.4.1.31103.1.14 NAME 'info' 'fslNfsValidFor'
           ///     DESC 'information about the file system' 'Valid for time'
           ///     SUP name
           ///     SINGLE-VALUE
           ///     )

6.2.11.
           ///

4.2.1.15.  annotation

   An annotation of an NSDB object.

   This attribute is multi-valued; an object type that permits
   annotations may have any number of annotations per instance.

           ///
           /// attributetype (
                           1.3.6.1.4.1.31103.1.11
           ///     1.3.6.1.4.1.31103.1.15 NAME 'annotation'
           ///     DESC 'annotation 'Annotation of an NSDB object'
           ///     SUP name
           ///     )

6.2.12.  childFsnUuid
           ///

   An annotation attribute MUST be an UTF-8 string formatted as follows:

   "KEY" = "VAL"

   White space, defined as space, form-feed ('\f'), newline ('\n'),
   carriage return ('\r'), horizontal tab ('\t'), and vertical tab
   ('\v') characters, is ignored.

   KEY and VAL MAY may contain any UTF-8 characters.  The fsnUuid following
   escape sequences are allowed:

                     +-----------------+-------------+
                     | escape sequence | replacement |
                     +-----------------+-------------+
                     |        \\       |      \      |
                     |        \"       |      "      |
                     +-----------------+-------------+

   An annotation attribute that does not adhere to this format SHOULD be
   ignored.

   The following are examples of valid annotation attributes:

            "key1" = "foo"
            "another key" = "x=3"
            "key-2" = "A string with \" and \\ characters."

   which correspond to the target of a junction.

   The childFsnUuid following key/value pairs:

            +-------------+-----------------------------------+
            |     key     |               value               |
            +-------------+-----------------------------------+
            |     key1    |                foo                |
            | another key |                x=3                |
            |    key-2    | A string with " and \ characters. |
            +-------------+-----------------------------------+

4.2.1.16.  descr

   This attribute is used to store an object's description encoded as a subclass of fsnUuid.
   UTF-8 string.

   This attribute is single-valued. multi-valued which permits any number of
   descriptions per entry.

           ///
           /// attributetype (
                           1.3.6.1.4.1.31103.1.12
           ///     1.3.6.1.4.1.31103.1.16 NAME 'childFsnUuid' 'descr'
           ///     DESC 'the fsnUuid 'Description of a Junction's target' an object'
           ///     SUP fsnUuid
                           SINGLE-VALUE name
           ///     )

6.2.13.  childNsdbName
           ///

4.2.2.  LDAP Objects

4.2.2.1.  fedfsFsn

   A fedfsFsn represents an FSN.

   The required attributes of a fedfsFsn are an nsdbName and fsnUuid.

   A fedfsFsn's annotation and descr attributes are OPTIONAL.

   The DN of an FSN is REQUIRED to take the target following form:
   "fsnUuid=FSNUUID,o=fedfs", where FSNUUID is the UUID of the FSN.
   Since LDAP requires a junction.

   The childNsdbName attribute is DN to be unique, this ensures that each FSN
   entry has a subclass unique UUID value within the LDAP directory.

   A fedfsFsn MAY also have additional attributes, but these attributes
   MUST NOT be referenced by any part of nsdbName.

   This attribute is single-valued.

                   attributetype this document.

           ///
           /// objectclass (
                           1.3.6.1.4.1.31103.1.13
           ///     1.3.6.1.4.1.31103.1.1001 NAME 'childNsdbName' 'fedfsFsn'
           ///     DESC 'the nsdbName of 'Represents a Junction's target' fileset'
           ///     SUP top STRUCTURAL
           ///     MUST (
           ///             fsnUuid
           ///             $ nsdbName
                           SINGLE-VALUE
           ///     )

6.3.  LDAP Objects

6.3.1.  FsnObject

   An FsnObject
           ///     MAY (
           ///             annotation
           ///             $ descr
           ///     ))
           ///

4.2.2.2.  fedfsFsl

   The fedfsFsl object class represents an FSN.

   The FSL.

   A fedfsFsl's required attributes of an FsnObject are an nsdbName fslUuid, fsnUuid, nsdbName,
   fslHost, and fsnUuid. fslTTL.

   A fedfsFsl's annotation and descr attributes are OPTIONAL.

   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 below is used to record an NFS FSL's
   location.  Other subtypes MAY be defined for other protocols (e.g.
   CIFS).

   The DN of an FSN FSL is assumed REQUIRED to take the following form:
   "fsnUuid=FSNUUID,dc=fed-fs,dc=com",
   "fslUuid=FSLUUID,fsnUuid=FSNUUID,o=fedfs" where fsnUuid is FSLUUID and FSNUUID
   are the UUID UUIDs of the
   FSN.

   An FsnObject MAY also have additional attributes, but these
   attributes MUST NOT FSL and its FSN respectively.  Since LDAP
   requires a DN to be referenced by any part of unique, this draft. ensures that each FSL entry has a
   unique UUID value within the LDAP directory.

           ///
           /// objectclass (
                           1.3.6.1.4.1.31103.1.1001
           ///     1.3.6.1.4.1.31103.1.1002 NAME 'FsnObject' 'fedfsFsl'
           ///     DESC 'Representing 'A physical location of a Fed-fs Fileset' fileset'
           ///     SUP top STRUCTURAL ABSTRACT
           ///     MUST (
           ///             fslUuid
           ///             $ fsnUuid
           ///             $ nsdbName
           ///             $ fslHost
           ///             $ fslTTL
           ///     )
           ///     MAY (
                                   descr
                                   $
           ///             annotation
           ///             $ descr
           ///     ))

6.3.2.  FslObject

   An FslObject represents
           ///

4.2.2.3.  fedfsNfsFsl

   A fedfsNfsFsl is used to represent an NFS FSL.  The required fedfsNfsFsl
   inherits all of the attributes of an FslObject are an nsdbName, fsnUuid,
   fslHost, fslPath, fslUuid, type, currency, info, and annotations.

   An FslObject's currency the fedfsFsl and annotations attributes MAY be null. extends the
   fedfsFsl with information specific to the NFS protocol.

   The DN of an NFS FSL is required REQUIRED to take the following form:
   "fslUuid=UUID,fsnUuid=FSNUUID,dc=fed-fs,dc=com".

   To find all the FSLs that match a given FSN, query for
   "fslUuid=FSLUUID,fsnUuid=FSNUUID,o=fedfs" where FSLUUID and FSNUUID
   are the children UUIDs of the object with DN "fsnUuid=FSNUUID,dc=fed-fs,dc=com" with FSL and its FSN respectively.  Since LDAP
   requires a
   filter for "objectType = fslObject".  (If you want DN to be doubly
   careful, you can also filter by unique, this ensures that each NFS FSL entry has
   a unique UUID value within the nsdbName.) LDAP directory.

           ///
           /// objectclass (
                           1.3.6.1.4.1.31103.1.1002
           ///     1.3.6.1.4.1.31103.1.1003 NAME 'FslObject' 'fedfsNfsFsl'
           ///     DESC 'A physical instance NFS location of a fileset'
           ///     SUP fsnObject fedfsFsl STRUCTURAL
           ///     MUST (
                                   fsnUuid
           ///             fslNfsPath
           ///             $ nsdbName fslNfsMajorVer
           ///             $ fslHost fslNfsMinorVer
           ///             $ fslPath fslNfsCurrency
           ///             $ fslUuid
                           )
                           MAY (
                                   descr fslNfsInfo
           ///             $ annotation fslNfsFlags
           ///             $ fslNfsValidFor
           ///     ))

7.
           ///

5.  NSDB Protocol Operations

   The operations defined by the protocol can be described as several
   sub-protocols that are used by entities within the federation to
   perform different roles.

   The first of these sub-protocols defines how the state of an NSDB
   location 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 location in order to perform resolution (or to find other
   information about the information data stored within that NSDB location) and the
   responses returned by the NSDB location.  The primary use of this
   sub-protocol is by a fileset server 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
   location 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 location implement a complete
   LDAP service, and therefore we define in these sections the minimum
   level of LDAP functionality required to implement an NSDB location.

   The NSDB sub-protocols are defined in the next two sub-sections.

   The third sub-protocol defines the queries or and other requests that
   are sent to a fileset server fileserver in order to get information from it or to
   modify the state of the fileset server 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 fileset or discover related
   information about a particular fileset server. fileserver.

   The third sub-protocol is defined as an ONC RPC operations. protocols.  The
   reason for using a different ONC RPC mechanism (instead instead of mapping these
   operations onto LDAP) LDAP is to minimize the changes required to the
   fileset that all fileservers
   support ONC RPC but some do not support an LDAP Directory server.

   The ONC RPC administration protocol is defined in [FEDFS-ADMIN].

7.1.  Administrative

5.1.  NSDB Operations for Administrators

   The admin entity initiates and controls the commands to manage
   fileset and namespace information.  The admin entity, however, is
   stateless.  All state is maintained at the NSDB locations or at the
   fileserver.

   We require that each NSDB location be able to act as an LDAP server
   and that the protocol used for communicating between the admin entity
   and each NSDB location is LDAP.

   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.

   In the description of the LDAP messages and LDIF, we use the
   following notation: constant strings and literal names are specified
   in lower or mixed case, while variables or values are specified in
   uppercase.  One important exception to this rule is that the names of
   the error codes follow the convention (used widely in other
   protocols, including NFS) of having names that are entirely
   uppercase.

7.1.1.  Creating

5.1.1.  Create an FSN

   The administrator uses this operation to create a new FSN by
   requesting the NSDB to create a new FsnObject fedfsFsn in its LDAP database
   with an fsnUuid value of FSNUUID and an NsdbName value of NSDB. NSDBNAME.

   The NSDB location that receives the request SHOULD check that the
   NSDB
   NSDBNAME matches its own value and return an error if it does not.
   This is to ensure that an FSN is always created by the NSDB location
   encoded within the FSN as its owner.

   The NSDB location that receives the request SHOULD check all of the
   attributes for validity and consistency, but this is not generally
   possible for LDAP servers because the consistency requirements cannot
   be expressed in the LDAP schema (although many LDAP servers can be
   extended, via plug-ins or other mechanisms, to add functionality
   beyond the strict definition of LDAP).

7.1.1.1.

5.1.1.1.  LDAP Request

   The admin chooses the fsnUuid and NsdbName of the FSN.  The fsnUuid
   is a UUID and should be chosen via a standard process for creating a
   UUID (described in [RFC4122]).  The NsdbName is the name of the NSDB
   location that will serve as the source of definitive information
   about an FSN for the life of that FSN.  In the example below, the
   admin server chooses a fsnUuid of FSNUUID and the NsdbName of NSDB
   NSDBNAME and then sends an LDAP ADD request, described by the LDIF
   below, to the NSDB location NSDB. NSDBNAME.  This will create a new FsnObject
   fedfsFsn on that NSDB location with the given attributes in the LDAP
   database.

           dn: fsnUuid=FSNUUID,dc=fed-fs,dc=com fsnUuid=FSNUUID,o=fedfs
           changeType: add
           objectClass: FsnObject fedfsFsn
           fsnUuid: FSNUUID
           nsdbName: NSDB

7.1.2.  Deleting NSDBNAME

5.1.2.  Delete an FSN

   Deletes

   This operation deletes the given fileset name.  This assumes that all  If the FSLs
   related to that FSN have already been deleted.  If entry
   being deleted has child FSL records for
   this FSN still exist in the database of the NSDB that receives this
   request, then 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 [RFC4511] defines the LDAP delete operation to
   only be capable of removing leaf entries.

   Note that the FSN delete function only removes the fileset from the
   namespace (by removing the records for that FSN from the NSDB
   location 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 client tries to resolve the target of a junction
   that refers to the deleted FSN and the NSDB returns an error.

7.1.2.1.

5.1.2.1.  LDAP Request

   The admin sends an LDAP DELETE request to the NSDB server to remove
   the FsnObject fedfsFsn from the NSDB server.  An example LDIF for the delete
   request is shown below.

           dn: fsnUuid=FSNUUID,dc=fed-fs,dc=com fsnUuid=FSNUUID,o=fedfs
           changeType: delete

7.1.3.

5.1.3.  Create an FSL

   Creates

   This operations creates a new Fileset location at the given location
   denoted by HOST and PATH for the given FSN.  Normally an FSL is
   identified by the HOST:PATH pair.  A UUID is an optional way to
   identify an FSL if it is recovered to a different HOST:PATH after a
   backup/restore.

   The FSL create command will result in the admin server sending an
   LDAP ADD request to create a new FslObject fedfsFsl at the NSDB maintaining the
   given FSN.  The example LDIF is shown below.  The PATH is the
   pathname where the fileset is located on that host.

7.1.3.1. the fileserver HOST.

5.1.3.1.  LDAP Request

   The admin sends an LDAP ADD request to the NSDB server to add the
   FLS.

           dn:fslUuid=UUID,fsnUuid=FSNUUID,dc=fed-fs,dc=com
   FSL.  An example LDIF for adding an NFS FSL is shown below.

           dn:fslUuid=UUID,fsnUuid=FSNUUID,o=fedfs
           changeType: add
           objectClass: FslObject fedfsNfsFsl
           fslUuid: UUID
           fsnUuid: FSNUUID
           nsdbName: NSDB
           fslUuid: UUID NSDBNAME
           fslHost: HOST
           fslPath:
           fslTTL: TTL
           fslNfsPath: PATH
           type: file access protocol type (e.g. nfs4)
           currency:
           fslNfsMajorVer: MAJOR
           fslNfsMinorVer: MINOR
           fslNfsCurrency: CURRENCY
           info:
           fslNfsInfo: INFO
           fslNfsFlags: FLAGS
           fslNfsValidFor: TIME
           annotation: ANNOTATION

7.1.4.
           descr: DESCR

5.1.4.  Delete an FSL

   Deletes

   This operation deletes the given Fileset location.  The admin
   requests the NSDB location storing the FslObject fedfsFsl to delete it from its
   database.  This operation does not result in the fileset location's
   data being deleted at the fileserver.

7.1.4.1.

5.1.4.1.  LDAP Request

   The admin sends an LDAP DELETE request to the NSDB server to remove
   the FLS. FSL.

           dn: fslUuid=UUID,fsnUuid=FSNUUID,dc=fed-fs,dc=com fslUuid=UUID,fsnUuid=FSNUUID,o=fedfs
           changeType: delete

7.1.5.

5.1.5.  Update an FSL

   Update

   This operation updates the attributes of a given FSL.  This command
   results in a change in the attributes of the FslObject fedfsFsl at the NSDB
   server maintaining this FSL.  The attributes that must not change are
   the fslUuid and the fsnUuid of the fileset this FSL implements.

7.1.5.1.

5.1.5.1.  LDAP Request

   The admin sends an LDAP MODIFY request to the NSDB server to update
   the FLS. FSL.

           dn: fslUuid=UUID,fsnUuid=FSNUUID,dc=fed-fs,dc=com fslUuid=UUID,fsnUuid=FSNUUID,o=fedfs
           changeType: modify
           replace: ATTRIBUTE-TYPE

7.2.  Fileserver to

5.2.  NSDB Operations

7.2.1.  Looking up for Fileservers

5.2.1.  Lookup FSLs for an FSN

   This operation returns

   Using an LDAP search, the list fileserver can obtain all of the FSLs for the a
   given FSN.  The FSN's fsnUuid is used as the search key.  The fileserver will convert the  To obtain a
   list of FSLs to all FSLs, the NFSv4 fs_locations or NFSv4.1 fs_locations_info.

   The following search can be used:

           LDAP Request
           Search base: fsnUuid=FSNUUID, o=fedfs
           Search scope: onelevel
           Search filter:  (objectClass=fedfsFsl)

   This search is for the children of the object with DN
   "fsnUuid=FSNUUID,o=fedfs" with a filter may for "objectClass = fedfsFsl".
   (If you want to be doubly careful, you can also specify filter by the type of protocol (v4, v4.1), or type
   of data access (ro, rw).

                   <figure>
                   <artwork>
   nsdbName.)

   The following search can be used to obtain only the NFS FSLs:

           LDAP Request
           Search base: fsnUuid=FSNUUID, dc=fed-fs, dc=com o=fedfs
           Search scope: onelevel
           Search filter:  (objectClass=FslObject)  (objectClass=fedfsNfsFsl)

   This also searches for the children of the object with DN
   "fsnUuid=FSNUUID,o=fedfs", but the filter for "objectClass =
   fedfsNfsFsl" restricts the results to only NFS FSLs.  (If you want to
   be doubly careful, you can also filter by the nsdbName.)

   The server fileserver can scan through present the search results and find results whose type
   corresponds in a format useful to
   the type of the client on whose behalf the server fileserver is performing
   the request, extracting request.  For an NFS client, the fslHost and fslPath (and
   possibly additional attributes) and using them fileserver can use the search
   results to create construct an NFSv4 fs_locations list or NFSv4.1
   fs_locations_info list that the client can use.

8. list.

6.  Security Considerations

   Both LDAP and NFSv4/NFSv4.1 provide security mechanisms.  When used
   in conjunction with the federated file system filesystem protocols described in
   this document, the use of these mechanisms is RECOMMENDED.
   Specifically, the use of RPCSEC_GSS [RFC2203] [RFC2743] is
   RECOMMENDED on all connections between a client and fileserver.  For
   all LDAP connections established by the federated file system filesystem
   protocols, TLS [RFC5246] [RFC4513] is RECOMMENDED.

   Within a federation, there are two components that an attacker may be
   able to compromise: a fileserver and an NSDB.  If an attacker
   compromises a fileserver, the attacker can interfere with the
   client's file system filesystem I/O operations (e.g. by returning fictitious data
   in the response to a read request) or fabricating a referral.  The attackers
   attacker's abilities are the same regardless of whether or not the
   federation protocols are in use.  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 which query it.

   It should be noted that the federation protocols do not directly
   provide access to file system filesystem data.  The federation protocols only
   provide a mechanism for building a namespace.  All data transfers are
   occur between a client and server 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 file server to act as a proxy for a client.

9.

7.  IANA Considerations

   This document has no actions for IANA.

10.  Conclusions

   The federated filesystem protocol manages multiple independently
   administered fileservers to share namespace LDAP attributes and referral information object classes defined in this document are
   assigned object identifier (OID) values from the 1.3.6.1.4.1.31103.x
   range.  This is an Internet Private Enterprise Numbers range and was
   assigned to enable clients the authors using the process described in [RFC2578].

   In accordance with Section 3.4 and Section 4 of [RFC4520], the object
   identifier descriptors defined in this document (listed below) will
   be registered via the Expert Review process.

7.1.  LDAP Descriptor Registration

   Subject:  Request for LDAP Descriptor Registration
   Person & email address to traverse seamlessly across them.

11. contact for further information:  See
      "Author/Change Controller"
   Specification:  draft-ietf-nfsv4-federated-fs-protocol
   Author/Change Controller:  [document authors]

   Object Identifier:  1.3.6.1.4.1.31103.1.1
   Descriptor (short name):  fedfsUuid

   Object Identifier:  1.3.6.1.4.1.31103.1.2
   Descriptor (short name):  fedfsNetAddr

   Object Identifier:  1.3.6.1.4.1.31103.1.3
   Descriptor (short name):  fsnUuid

   Object Identifier:  1.3.6.1.4.1.31103.1.4
   Descriptor (short name):  nsdbName

   Object Identifier:  1.3.6.1.4.1.31103.1.5
   Descriptor (short name):  fslUuid

   Object Identifier:  1.3.6.1.4.1.31103.1.6
   Descriptor (short name):  fslHost

   Object Identifier:  1.3.6.1.4.1.31103.1.7
   Descriptor (short name):  fslTTL

   Object Identifier:  1.3.6.1.4.1.31103.1.8
   Descriptor (short name):  fslNfsPath

   Object Identifier:  1.3.6.1.4.1.31103.1.9
   Descriptor (short name):  fslNfsMajorVer

   Object Identifier:  1.3.6.1.4.1.31103.1.10
   Descriptor (short name):  fslNfsMinorVer

   Object Identifier:  1.3.6.1.4.1.31103.1.11
   Descriptor (short name):  fslNfsCurrency

   Object Identifier:  1.3.6.1.4.1.31103.1.12
   Descriptor (short name):  fslNfsInfo
   Object Identifier:  1.3.6.1.4.1.31103.1.13
   Descriptor (short name):  fslNfsFlags

   Object Identifier:  1.3.6.1.4.1.31103.1.14
   Descriptor (short name):  fslNfsValidFor

   Object Identifier:  1.3.6.1.4.1.31103.1.15
   Descriptor (short name):  annotation

   Object Identifier:  1.3.6.1.4.1.31103.1.16
   Descriptor (short name):  descr

   Object Identifier:  1.3.6.1.4.1.31103.1.1001
   Descriptor (short name):  fedfsFsn

   Object Identifier:  1.3.6.1.4.1.31103.1.1002
   Descriptor (short name):  fedfsFsl

   Object Identifier:  1.3.6.1.4.1.31103.1.1003
   Descriptor (short name):  fedfsNfsFsl

8.  Glossary

   Administrator:  user with the necessary authority to initiate
      administrative tasks on one or more servers.

   Admin entity:  A server or agent that administers a collection of
      fileservers and persistently stores the namespace information.

   Client:  Any client that accesses the fileserver data using a
      supported filesystem access protocol.

   Federation:  A set of server collections and singleton servers that
      use a common set of interfaces and protocols in order to provide
      to their clients a federated namespace accessible through a
      filesystem access protocol.

   Fileserver:  A server exporting a filesystem via a network filesystem
      access protocol.

   Fileset:  The abstraction of a set of files and their containing
      directory tree.  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 filesystems.

   Filesystem:  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 filesystem, nor at the export
      point for the filesystem.

      A single filesystem MAY implement more than one fileset, if the
      client protocol and the fileserver permit this.

   Filesystem access protocol:  A network filesystem access protocol
      such as NFSv2 [RFC1094], NFSv3 [RFC1813], NFSv4 [RFC3530], or
      CIFS.

   FSL (Fileset location):  The location of the implementation of a
      fileset at a particular moment in time.  A FSL MUST be something
      that can be translated into a protocol-specific description of a
      resource that a client can access directly, such as a fs_location
      (for NFSv4), or share name (for CIFS).  Note that not all FSLs
      need to be explicitly exported as long as they are contained
      within an exported path on the fileserver.

   FSN (Fileset name):  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.

   Junction:  A filesystem 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.

   Namespace:  A filename/directory tree that a sufficiently-authorized
      client can observe.

   NSDB (Namespace Database Service):  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.

   NSDB Node:  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 info) that implement a given partition of the FSNs.

   Referral:  A server response to a 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.

   Replica:  A replica is 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, and 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.

   Server Collection:  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.

   Singleton Server:  A server collection containing only one server; a
      stand-alone fileserver.

12.

9.  References

12.1.

9.1.  Normative References

   [FEDFS-ADMIN]
              J.
              Lentini, et al., J., Everhart, C., Ellard, D., Tewari, R., and M.
              Naik, "Administration Protocol for Federated
              Filesystems Filesystems",
              draft-ietf-nfsv4-federated-fs-admin (Work In Progress)",
              draft-ietf-nfsv4-federated-fs-admin , Progress),
              2008.

   [FEDFS-REQTS]
              J.
              Lentini, et al., J., Everhart, C., Ellard, D., Tewari, R., and M.
              Naik, "Requirements for Federated File
              Systems Systems",
              draft-ietf-nfsv4-federated-fs-reqts (Work In Progress)",
              draft-ietf-nfsv4-federated-fs-reqts , Progress),
              2008.

   [NFSv4.1]  S.  Shepler, et al., S. and M. Eisler, "NFS Version 4 Minor Version 1
              1", draft-ietf-nfsv4-minorversion1 (Work In Progress)", draft-ietf-nfsv4-minorversion1 , Progress),
              2008.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2203]  Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol
              Specification", RFC 2203, September 1997.

   [RFC2578]  McCloghrie, K., Ed., Perkins, D., Ed., and J.
              Schoenwaelder, Ed., "Structure of Management Information
              Version 2 (SMIv2)", STD 58, RFC 2578, April 1999.

   [RFC2743]  Linn, J., "Generic Security Service Application Program
              Interface Version 2, Update 1", RFC 2743, January 2000.

   [RFC3530]  Shepler, S., Callaghan, B., Robinson, D., Thurlow, R.,
              Beame, C., Eisler, M., and D. Noveck, "Network File System
              (NFS) version 4 Protocol", RFC 3530, April 2003.

   [RFC4122]  Leach, P., Mealling, M., and R. Salz, "A Universally
              Unique IDentifier (UUID) URN Namespace", RFC 4122,
              July 2005.

   [RFC4510]  Zeilenga, K., "Lightweight Directory Access Protocol
              (LDAP): Technical Specification Road Map", RFC 4510,
              June 2006.

   [RFC4511]  Sermersheim, J., "Lightweight Directory Access Protocol
              (LDAP): The Protocol", RFC 4511, June 2006.

   [RFC4512]  Zeilenga, K., "Lightweight Directory Access Protocol
              (LDAP): Directory Information Models", RFC 4512,
              June 2006.

   [RFC4513]  Harrison, R., "Lightweight Directory Access Protocol
              (LDAP): Authentication Methods and Security Mechanisms",
              RFC 4513, June 2006.

   [RFC4517]  Legg, S., "Lightweight Directory Access Protocol (LDAP):
              Syntaxes and Matching Rules", RFC 4517, June 2006.

   [RFC4520]  Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
              Considerations for the Lightweight Directory Access
              Protocol (LDAP)", BCP 64, RFC 4520, June 2006.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246, August 2008.

12.2.

9.2.  Informational References

   [AFS]      Howard, J., "An Overview of the Andrew File System",
              Proceeding of the USENIX Winter Technical Conference ,
              1988.

   [RFC1094]  Nowicki, B., "NFS: Network File System Protocol
              specification", RFC 1094, March 1989.

   [RFC1813]  Callaghan, B., Pawlowski, B., and P. Staubach, "NFS
              Version 3 Protocol Specification", RFC 1813, June 1995.

   [RFC3254]  Alvestrand, H., "Definitions for talking about
              directories", RFC 3254, April 2002.

Appendix A.  Acknowledgments

   We would like to thank Andy Adamson of NetApp, Paul Lemahieu of EMC,
   Robert Thurlow of Sun Microsystems, and Mario Wurzl of EMC for
   helping to author this document.

   We would also like to thank George Amvrosiadis for pointing out that
   several LDAP attributes were missing the SINGLE-VALUE keyword in a
   draft version of this document.

Authors' Addresses

   James Lentini
   NetApp
   1601 Trapelo Rd, Suite 16
   Waltham, MA  02451
   US

   Phone: +1 781-768-5359
   Email: jlentini@netapp.com

   Craig Everhart
   NetApp
   7301 Kit Creek Rd
   Research Triangle Park, NC  27709
   US

   Phone: +1 919-476-5320
   Email: everhart@netapp.com
   Daniel Ellard
   BBN Technologies
   10 Moulton Street
   Cambridge, MA  02138
   US

   Phone: +1 617-873-8000
   Email: dellard@bbn.com

   Renu Tewari
   IBM Almaden
   650 Harry Rd
   San Jose, CA  95120
   US

   Email: tewarir@us.ibm.com

   Manoj Naik
   IBM Almaden
   650 Harry Rd
   San Jose, CA  95120
   US

   Email: manoj@almaden.ibm.com