Subject: [nfsv4] [PATCH 1/5] Clarify introduction to "NSDB Operations for Administrators"

From: Chuck Lever <[email-masked]>
Date: Tue, 11 Sep 2012 13:48:27 -0400

I believe the assertion that "administrative entities are stateless"
is not true.  For example, doesn't an admin entity have to remember
the names of NSDB nodes, and what NCE to use on each?

Also, instead of "We require that," use language compliant with RFC
2119.
---

 nsdb-proto.xml |   12 ++++--------
 1 files changed, 4 insertions(+), 8 deletions(-)

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index d5a80bb..87651d0 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -2112,14 +2112,10 @@
     <section title="NSDB Operations for Administrators" anchor="nsdb-ops-admins">
 
         <t> 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 nodes or at the fileserver.  </t>
-
-        <t> We require that each NSDB node be able to act as
-        an LDAP server and that the protocol used for
-        communicating between the admin entity and each NSDB
-        node is LDAP.  </t>
+        to manage fileset and namespace information.  The protocol
+        used for communicating between the admin entity and each
+        NSDB node MUST be the LDAPv3 <xref target="RFC2849"/>
+        protocol.  </t>
 
         <t> The names we assign to these operations are entirely
         for the purpose of exposition in this document, and are

---

From: Chuck Lever <[email-masked]>
Date: Tue, 11 Sep 2012 13:48:38 -0400

I don't see the value in having separate definitions for "junction"
and "mount point."

According to the paragraph that defines mount points, these two
appear to be functionally the same thing.  This paragraph also
seems to imply that mount operations that construct the federated
namespace are performed by fileservers.

Finally, not all fileserver implementations use a "specially
marked directory" to implement a junction.  A symbolic link, for
example, can be used.
---

 nsdb-proto.xml |   44 ++++++++++++++++++--------------------------
 1 files changed, 18 insertions(+), 26 deletions(-)

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 87651d0..3cc7b70 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -578,32 +578,24 @@
 
     </section>
 
-    <section title="Mount Points, Junctions and Referrals">
-
-        <t> A mount point is a directory in a parent fileset
-        where a target fileset may be attached.  If a file-access
-        client traverses the path leading from the root of the
-        namespace to the mount point of a target fileset, it
-        should be able to mount and access the data in that
-        target fileset (assuming appropriate permissions).  </t>
-
-        <t> 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 filesystem.  </t>
-
-        <t> What data is used by the underlying 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 the authoritative
-        NSDB node, and the FsnUuid (a UUID for the fileset).  </t>
+    <section title="Junctions and Referrals">
+
+        <t> 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.  </t>
+
+        <t> A junction can be implemented as a special marker on a
+        directory, or by some other mechanism in the fileserver's
+        underlying filesystem.  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.  </t>
 
         <t> When a file-access client reaches a junction, the
         fileserver refers the client to a list of FSLs associated

---

From: Chuck Lever <[email-masked]>
Date: Tue, 11 Sep 2012 13:48:49 -0400

---

 nsdb-proto.xml |    8 +++-----
 1 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 3cc7b70..c266a6d 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -172,11 +172,9 @@
         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 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. </t>
+        of fileset names and locations, is stored in a set of
+        namespace repositories, each managed by an administrative
+        entity. </t>
 
         <t> The namespace schema defines the model used for populating,
         modifying, and querying the namespace repositories.  It is not

---

From: Chuck Lever <[email-masked]>
Date: Tue, 11 Sep 2012 13:49:00 -0400

In my opinion, the default NCE DN has a bearing on interoperability,
especially since there is an NCE hunting mechanism.

What's more, the specified default NCE DN requires that a new
namingContext be set up on the NSDB, which is an additional
(perhaps minor) administrative burden for some LDAP servers.

We should leave the default NCE DN as an implementation choice.
---

 nsdb-proto.xml |   16 ++++++++--------
 1 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index c266a6d..b429ea9 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -1904,10 +1904,10 @@
 
             <t> 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
-            ("o=fedfs" by default). Since LDAP requires a DN to be
-            unique, this ensures that each FSN entry has a unique
-            UUID value within the LDAP directory.  </t>
+            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.  </t>
 
             <t> A fedfsFsn MAY also have additional attributes, but
             these attributes MUST NOT be referenced by any part of
@@ -1956,8 +1956,8 @@
             <t> 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 ("o=fedfs" by default).
-            Since LDAP requires a DN to be unique, this ensures that each
+            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.  </t>
 
@@ -1995,8 +1995,8 @@
             <t> 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 ("o=fedfs" by default).
-            Since LDAP requires a DN to be unique, this ensures that each
+            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.  </t>

---

From: Chuck Lever <[email-masked]>
Date: Tue, 11 Sep 2012 13:49:10 -0400

Fileservers can cache fileset location information.  We have a shiny
new FSN TTL field to control how long.

However, file-access clients can also cache fileset location
information, sometimes indefinitely.  This needs appropriate
discussion in the section that discusses fileset location caching.

Also, update the implementation advice for fileserver developers
based on recent implementation experience.

Lastly, as part of this update, break up the example in this section
to make it easier to understand.
---

 nsdb-proto.xml |  108 ++++++++++++++++++++++++++++++++++++++++----------------
 1 files changed, 78 insertions(+), 30 deletions(-)

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index b429ea9..06aa0eb 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -449,38 +449,86 @@
 
         <t> 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 had not cached  the FSL record, it would have queried the NSDB
-        and obtained the correct location of fileset X. </t>
-
-        <t> 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 correct location.
-        Thus, in the above example, fileserver A would direct file-access
-        clients to fileserver B, but fileserver B would direct file-access
-        clients to fileserver C. </t>
-
-        <t> Such supplemental junctions (on fileserver B in the example)
-        would not be required to be in place forever. They need to stay
-        in place only until cached FSL entries for the target fileset
-        are invalidated. An FSL's parent FSN contains a TTL field, a count in
-        seconds of the time interval the FSL MAY be cached. This is an upper
-        bound for the lifetime of the cached information and a lower bound for the
-        lifetime of the supplemental junctions. For example, suppose this
-        field contains the value 3600 seconds (one hour). In such a case,
-        administrators SHOULD keep the supplemental junctions in 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
+        named A, B, and C.  Suppose further that fileserver A
+        contains a junction J to fileset X stored on fileserver B.
+        </t>
+
+        <t> 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.  </t>
+
+        <t> 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.  </t>
+
+        <t> 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).  </t>
+
+        <t> 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.  </t>
+
+        <t> Back to our example.  Suppose, as part of the migration
+        process, a junction replaces fileset X on fileserver B.
+        Later, either:
+
+        <list style="symbols">
+
+        <t> New file-access clients are referred to fileserver
+        B by stale FSL information cached on fileserver A, or </t>
+
+        <t> File-access clients continue to access fileserver
+        B because they cache stale location data for fileset X. </t>
+
+        </list>
+
+        </t>
+
+        <t> In either case, thanks to the redirection, file-access
+        clients are informed by fileserver B that fileset X has
+        moved to fileserver C.  </t>
+
+        <t> 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.  </t>
+
+        <t> An FSL's parent FSN contains a TTL field which contains
+        a count in seconds of the time interval the FSL MAY be
+        cached. This is an upper bound for the lifetime of the
+        cached information, and thus can act as a lower bound for
+        the lifetime of redirecting junctions.  </t>
+
+        <t> For example, suppose this 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, and FSL data MUST NOT be
+        cached by a referring fileserver for more than one hour
         without a refresh. </t>
 
+        <t> To get file-access clients to access the destination
+        fileserver more quickly, administrators SHOULD set the
+        FSN TTL 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.  </t>
+
+        <t> 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.  </t>
+
         </section>
 
         <section title="Generating A Referral from Fileset Locations" anchor="fsl_referral">