Subject: [nfsv4] [PATCH 0/6] Address Gen-ART comments in NSDB protocol draft

From: Chuck Lever <[email-masked]>
Date: Tue, 23 Oct 2012 14:18:20 -0400

Hi-

I propose the following changes to draft-ietf-nfsv4-federated-fs-procotol
to address comments made during IESG review.

---

Chuck Lever (6):
      Gen-ART review: Note where draft's title should be inserted
      Gen-ART review: Clarify sections related to Fileset Locations
      Gen-ART review: LDAP-related corrections
      Gen-ART review: Make glossary definitions consistent
      Gen-ART review: Spelling and grammar corrections
      Gen-ART review: Expand acronyms on first use

 glossary.xml   |   17 +++++-----
 nsdb-proto.xml |   92 ++++++++++++++++++++++++++++++++++++--------------------
 2 files changed, 67 insertions(+), 42 deletions(-)

-- 
Chuck Lever

---

From: Chuck Lever <[email-masked]>
Date: Tue, 23 Oct 2012 14:18:30 -0400

Section 2.7, NsdbName definition: expand NSDB to Namespace Database
as this is the first use of the term.

Section 2.12, 2nd paragraph, last sentence: expand NCE (NSDB
Container Entry) as this is the first use of the term.

Section 4.1, 1st paragraph, 3rd sentence: probably worth expanding
"DSE" to "DSA-specific entry" here.
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 71bbdb6..f873cd5 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -209,8 +209,8 @@
         <list style="hanging" hangIndent="6">
 
             <t hangText="   NsdbName:"> the network location of the
-            NSDB node that contains authoritative information for
-            this FSN. </t>
+            Namespace Database (NSDB) node that contains authoritative
+            information for this FSN. </t>
 
             <t hangText="   FsnUuid:"> a UUID
             (universally unique identifier), conforming to
@@ -714,8 +714,8 @@
         the name and port of an NSDB node, an FSN UUID must be unique
         only on a single NSDB node.  An FSN UUID collision can be
         detected immediately when an administrator attempts to publish
-        an FSN or FSL by storing it under a specific NCE on an
-        authoritative NSDB host.  </t>
+        an FSN or FSL by storing it under a specific NSDB Container Entry
+        (NCE) on an authoritative NSDB host.  </t>
 
         <t> Note that one NSDB node may store multiple NCEs, each under
         a different namingContext.  If an NSDB node must contain more
@@ -967,10 +967,12 @@
 
         <t> An NSDB is constructed using an LDAP Directory.
         This LDAP Directory MAY have multiple naming contexts.
-        For each naming context, the LDAP Directory's root DSE
-        will have a namingContext attribute. Each namingContext
-        attribute contains the DN of the naming context's root
-        entry. For each naming context that contains federation
+        The LDAP Directory's DSA-specific entry (its rootDSE)
+        has a multi-valued namingContext attribute.  Each value
+        of the namingContext attribute is the DN of a naming
+        context's root entry (see <xref target="RFC4512"/>). </t>
+
+        <t> For each naming context that contains federation
         entries (e.g., FSNs and FSLs): </t>
 
         <t>

---

From: Chuck Lever <[email-masked]>
Date: Tue, 23 Oct 2012 14:18:40 -0400

Section 2.8.1, 2nd sentence: "extention" -> "extension"

Section 2.8.3, 3rd paragraph after bullet items, 1st sentence:
"which" -> "that".  (Yeah, I know, grammar police.)

Section 2.9, 3rd paragraph, 2nd sentence: "admininistrative" ->
"administrative"

Section 4.2.1.8, 1st paragraph, 2nd sentence: bracket "Section 2.8.1"
in "(see" and ")" for readability.

Section 5.1.3.1, 1st paragraph after LDIF definition: "up to date" ->
"up-to-date"

Section 5.1.3.2, 2nd paragraph: "a" -> "an"

Section 5.1.3.2, table entry for "fedfsNfsVarSub": "substituion" ->
"substitution"

Section 8, 1st paragraph (definition of Administrator): "an" -> "a"
---

 glossary.xml   |    2 +-
 nsdb-proto.xml |   14 +++++++-------
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/glossary.xml b/glossary.xml
index dde9fc8..100d7ef 100644
--- a/glossary.xml
+++ b/glossary.xml
@@ -3,7 +3,7 @@
 <t>
 <list style="hanging">
 
-<t hangText="Administrator:"> An user with the necessary authority to
+<t hangText="Administrator:"> A user with the necessary authority to
     initiate administrative tasks on one or more servers.  </t>
 
 <t hangText="Admin Entity:"> A server or agent that administers a
diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index f873cd5..7127bac 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -322,8 +322,8 @@
 
         <t> To capture the location of an NFSv4 fileset, we extend
         the NFS URL scheme specified in <xref target="RFC2224"/>.
-        This extention follows rules for defining Uniform Resource
-        Identifier schemes in <xref target="RFC3986"/>.  In the
+        This extension follows rules for defining Uniform Resource
+        Identifier schemes (see <xref target="RFC3986"/>).  In the
         following text, we refer to this extended NFS URL scheme as
         an NFS URI. </t>
 
@@ -532,7 +532,7 @@
         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
+        <t> An FSL's parent FSN contains a TTL field containing
         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
@@ -630,7 +630,7 @@
         DNS service and a particular DNS server.  </t>
 
         <t> Each NSDB node is managed by a single administrative
-        entity.  A single admininistrative entity can manage
+        entity.  A single administrative entity can manage
         multiple NSDB nodes.  </t>
 
         <t> Each NSDB node stores the definition of the FSNs
@@ -2372,7 +2372,7 @@
             <t> For example, if the $FSNUUID is "e8c4761c-eb3b-4307-86fc-f702da197966",
             the $FSLUUID is "ba89a802-41a9-44cf-8447-dda367590eb3",
             the $HOST is "server.example.com", $PORT is "2049",
-            the $PATH is stored in the file "/tmp/fsl_path", $CURRENCY is "0" (an up to date
+            the $PATH is stored in the file "/tmp/fsl_path", $CURRENCY is "0" (an up-to-date
             copy), the FSL is writable, but not going, split, or accessible via RDMA,
             the simultaneous-use class is "1", the handle class is "0", the fileid class is
             "1", the write-verifier class is "1", the change class is "1", the readdir class is
@@ -2427,7 +2427,7 @@
 
             <t> When the administrator is unable to choose reasonable
             values for the LDAP attributes not explicitly contained
-            in a NFSv4 fs_locations attribute, the values in the
+            in an NFSv4 fs_locations attribute, the values in the
             following table are RECOMMENDED. </t>
 
             <texttable>
@@ -2481,7 +2481,7 @@
                 <c>See fedfsNfsReadRank note.</c>
                 <c>fedfsNfsVarSub</c>
                 <c>FALSE</c>
-                <c>NFSv4 does not define variable substituion in paths.</c>
+                <c>NFSv4 does not define variable substitution in paths.</c>
                 <c>fedfsNfsValidFor</c>
                 <c>0</c>
                 <c>Indicates no appropriate refetch interval (see 11.10.2 of <xref target="RFC5661"/>).</c>

---

From: Chuck Lever <[email-masked]>
Date: Tue, 23 Oct 2012 14:18:49 -0400

Section 8, 3rd paragraph (definition of Client): "filesystem
access" -> "file-access" for consistency of usage with the rest of
the document.

Section 8, 5th paragraph (definition of Fileserver): rather than
discussing "a filesystem", should this be "one or more filesystems"?
Or is a fileserver limited to exporting one filesystem?

Section 8, 8th paragraph (definition of Filesystem Access Protocol):
following up on the 3rd paragraph, should this be "File-access
Protocol" for consistency?

This follows up on commit 8cd92fc1 'Use the term "file-access client"
consistently'.
---

 glossary.xml |   10 +++++-----
 1 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/glossary.xml b/glossary.xml
index 100d7ef..fbb48df 100644
--- a/glossary.xml
+++ b/glossary.xml
@@ -10,16 +10,16 @@
     collection of fileservers and persistently stores the namespace
     information.  </t>
 
-<t hangText="Client:"> Any client that accesses the fileserver data
-    using a supported filesystem access protocol.  </t>
+<t hangText="Client:"> Any client that accesses fileserver data
+    using a supported file-access protocol.  </t>
 
 <t hangText="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.  </t>
 
-<t hangText="Fileserver:"> A server exporting a filesystem via a
-    network filesystem access protocol.  </t>
+<t hangText="Fileserver:"> A server exporting one or more filesystems
+    via a file-access protocol.  </t>
 
 <t hangText="Fileset:"> The abstraction of a set of files and the
     directory tree that contains them. A fileset is the 
@@ -40,7 +40,7 @@
     A single filesystem MAY implement more than one fileset, if the
     client protocol and the fileserver permit this. </t>
 
-<t hangText="Filesystem Access Protocol:"> A network filesystem access
+<t hangText="File-access Protocol:"> A network filesystem access
     protocol such as NFSv3 <xref
     target="RFC1813"/>, NFSv4 <xref target="3530bis"/>, or
     CIFS (Common Internet File System) <xref target="MS-SMB"/>

---

From: Chuck Lever <[email-masked]>
Date: Tue, 23 Oct 2012 14:18:59 -0400

Section 4.2.2: "LDAP Objects" -> "LDAP Object Classes" seems
appropriate.

Section 4.2.2.1, 2nd and 3rd sentences: replace "fedfsFsn" with
"fedfsNsdbContainerInfo"

Section 4.2.2.2, 5th paragraph: how is the prohibition on
referencing other attributes in the fedfsFsn object class supposed
to work if this document is the defining document for that object
class?

Section 5.1.3.1, 1st paragraph after LDIF definition: a port number
of 2049 is given.  Since this is already the default value, why not
use a different value?  Otherwise, there would be no practical need
to include that port number in the FSL creation request.
---

 nsdb-proto.xml |   42 +++++++++++++++++++++++++++++++-----------
 1 files changed, 31 insertions(+), 11 deletions(-)

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 7127bac..eb78fb0 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -1965,17 +1965,18 @@
 
         </section> <!-- LDAP Attributes -->
 
-        <section title="LDAP Objects">
+        <section title="LDAP Object Classes">
 
         <section title="fedfsNsdbContainerInfo">
 
             <t> A fedfsNsdbContainerInfo describes the location of
             the NCE.  </t>
 
-            <t> A fedfsFsn's fedfsNceDN attribute is REQUIRED.  </t>
+            <t> A fedfsNsdbContainerInfo's fedfsNceDN attribute is
+            REQUIRED.  </t>
 
-            <t> A fedfsFsn's fedfsAnnotation and fedfsDescr attributes
-            are OPTIONAL.  </t>
+            <t> A fedfsNsdbContainerInfo's fedfsAnnotation and
+            fedfsDescr attributes are OPTIONAL.  </t>
 
             <t> &lt;CODE BEGINS> </t>
 
@@ -2016,10 +2017,6 @@
             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
-            this document.  </t>
-
             <t> &lt;CODE BEGINS> </t>
 
             <figure><artwork><![CDATA[
@@ -2146,6 +2143,28 @@
 
     </section> <!-- LDAP Schema -->
 
+    <section title="LDAP Schema Extensibility">
+
+    <t> To maintain interoperability, the authors recommend avoiding
+    changes to the base schema specified in this document.  Instead,
+    consider using one of the following ways to extend the schema: </t>
+
+    <t>
+        <list style="symbols">
+
+        <t> Define a fedfsAnnotation key and values (see <xref
+        target="fedfsAnnotation"/>).  Register the new key and
+        values with IANA (see <xref target="annotation-registry"/>). </t>
+
+        <t> Define additional attribute types and object classes, then
+        have entries inherit from a class defined in this document and
+        from the implementation-defined ones. </t>
+
+        </list>
+    </t>
+
+    </section> <!-- LDAP Schema Extensibility -->
+
     </section> <!-- Mapping the NSDB onto LDAP -->
 
     <section title="NSDB Operations" anchor="nsdb-ops">
@@ -2371,7 +2390,7 @@
 
             <t> For example, if the $FSNUUID is "e8c4761c-eb3b-4307-86fc-f702da197966",
             the $FSLUUID is "ba89a802-41a9-44cf-8447-dda367590eb3",
-            the $HOST is "server.example.com", $PORT is "2049",
+            the $HOST is "server.example.com", $PORT is "20049",
             the $PATH is stored in the file "/tmp/fsl_path", $CURRENCY is "0" (an up-to-date
             copy), the FSL is writable, but not going, split, or accessible via RDMA,
             the simultaneous-use class is "1", the handle class is "0", the fileid class is
@@ -2390,7 +2409,7 @@
         objectClass: fedfsNfsFsl
         fedfsFslUuid: ba89a802-41a9-44cf-8447-dda367590eb3
         fedfsFsnUuid: e8c4761c-eb3b-4307-86fc-f702da197966
-        fedfsNfsURI: nfs://server.example.com//tmp/fsl_path
+        fedfsNfsURI: nfs://server.example.com:20049//tmp/fsl_path
         fedfsNfsCurrency: 0
         fedfsNfsGenFlagWritable: TRUE
         fedfsNfsGenFlagGoing: FALSE
@@ -2766,7 +2785,8 @@
 
     <section title="IANA Considerations">
 
-        <section title="Registry for the fedfsAnnotation Key Namespace">
+        <section title="Registry for the fedfsAnnotation Key Namespace"
+                 anchor="annotation-registry">
 
     <t> This document defines the fedfsAnnotation key in <xref target="fedfsAnnotation"/>.
     The fedfsAnnotation key namespace is to be managed by IANA. IANA is to create

---

From: Chuck Lever <[email-masked]>
Date: Tue, 23 Oct 2012 14:19:08 -0400

Section 2.8.3, 2nd paragraph, last sentence: in addition to checking
for added FSL records, shouldn't the fileserver also be checking for
deleted or migrated FSLs?  And why would the fileserver do this at
the expiration of the FSN TTL instead of waiting for the next access
to the that FSN?  Otherwise the fileserver could be generating
unnecessary traffic, although there is a tradeoff to be made vs.
performance.

Section 3.2, item #5: "fs_location" -> "fs_locations"

Section 5.1.4, 1st paragraph, 1st sentence: "a Fileset location" ->
"an FSL"

Section 8, 9th paragraph (definition of FSL), 2nd sentence:
"fs_location" -> "fs_locations".
---

 glossary.xml   |    5 ++---
 nsdb-proto.xml |   13 ++++++-------
 2 files changed, 8 insertions(+), 10 deletions(-)

diff --git a/glossary.xml b/glossary.xml
index fbb48df..b3610da 100644
--- a/glossary.xml
+++ b/glossary.xml
@@ -50,9 +50,8 @@
     implementation of a fileset at a particular moment in time.  An FSL
     MUST be something that can be translated into a protocol-specific
     description of a resource that a client can access directly, such
-    as an 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.  </t>
+    as an fs_locations attribute (for NFSv4), or a share name (for
+    CIFS). </t>
 
 <t hangText="FSN (Fileset Name):"> A platform-independent and globally
     unique name for a fileset.  Two FSLs that implement replicas of
diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index eb78fb0..94cc0db 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -470,11 +470,10 @@
 
         <t> The period of time during which these FSL records MAY
         be cached is indicated by the parent FSN's TTL attribute.
-        A value of zero indicates that the results of resolving this
-        FSN SHOULD NOT be cached.  In addition, a fileserver SHOULD
-        check back with the NSDB node after the FSN TTL has expired
-        to discover if any new FSL records have been added for this
-        FSN. </t>
+        Fileservers MUST NOT use cached FSL records after the
+        parent FSN's TTL has expired.  An FSN TTL value of zero
+        indicates that fileservers MUST NOT cache the results of
+        resolving this FSN.</t>
 
         <t> The combination of FSL caching and FSL migration presents
         a challenge. For example, suppose there are three fileservers
@@ -885,7 +884,7 @@
 
             <t> The fileserver converts one or more of the FSLs to
             the location type used by the file-access client (e.g.,
-            an NFSv4 fs_location attribute as described in
+            an NFSv4 fs_locations attribute as described in
             <xref target="RFC5661"/>).  </t>
 
             <t> The fileserver redirects (in whatever manner is
@@ -2512,7 +2511,7 @@
 
         <section title="Delete an FSL">
 
-        <t> This operation deletes a Fileset location record.
+        <t> This operation deletes an FSL record.
         The admin requests the NSDB node storing the fedfsFsl to
         delete it from its database.  This operation does
         not result in fileset data being deleted on any fileserver. </t>

---

From: Chuck Lever <[email-masked]>
Date: Tue, 23 Oct 2012 14:19:18 -0400

Section 7.3, 2nd paragraph, "Specification" value: presumably this
will be changed to the RFC number when issued?
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 94cc0db..f1c4eb9 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -2874,6 +2874,11 @@
     the object identifier descriptors defined in this document (listed below) will
     be registered via the Expert Review process. </t>
 
+    <t><cref>
+    RFC Editor: please replace "draft-ietf-nfsv4-federated-fs-protocol"
+    with this specification's RFC number and title.
+    </cref></t>
+
 <?rfc subcompact="yes" ?>
     <t>
         <list style="hanging">