Subject: [nfsv4] [PATCH 0/6] Updates for NSDB protocol draft

From: Chuck Lever <[email-masked]>
Date: Fri, 07 Sep 2012 15:56:18 -0400

Here are the first of some clean-up edits of the NSDB protocol draft.

---

Chuck Lever (6):
      Word smithing the NSDB protocol draft
      NIT: clean up NSDB example
      Remove "128-bit"
      NIT: Repair whitespace damage
      DNS SRV draft now has RFC number 6641
      Fix issues introduced by commit 4625c4b2

 nsdb-proto.xml                    |  141 +++++++++++++++++++++----------------
 references/reference.RFC.6641.xml |   19 +++++
 2 files changed, 98 insertions(+), 62 deletions(-)
 create mode 100644 references/reference.RFC.6641.xml

--
Chuck Lever

---

From: Chuck Lever <[email-masked]>
Date: Fri, 07 Sep 2012 15:56:27 -0400

o  Clean up the introduction to the section defining the NFS URI
     scheme

  o  Mention fs_locations entries that have multiple server names in
     the section that discusses how fileservers can mangle FSL data

  o  Add citations for IA5String syntax and matching rule

  o  The EQUALITY rule for a string should not be "IntegerMatch"

  o  Do not use SUP for IA5String, but pull the syntax by OID
---

 nsdb-proto.xml |   32 +++++++++++++++++++++++---------
 1 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 206d7ea..55e94b3 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -316,13 +316,13 @@
 
         <section anchor="nfs-uri" title="The NFS URI scheme">
 
-        <t> We extend the NFS URL scheme specified in
-        <xref target="RFC2224"/> (which is defined only for NFS
-        versions 2 and 3, to use it for locating NFS version 4
-        filesets.  This extention follows rules set out for Uniform
-        Resource Identifier schemes in <xref target="RFC3986"/>.
-        In the following text, we refer to this extended NFS URL
-        as an NFS URI. </t>
+        <t> To capture the location of an NFS fileset, we extend the
+        NFS URL scheme specified in <xref target="RFC2224"/> (which
+        is defined only for NFS versions 2 and 3) to use it for
+        locating NFSv4 filesets.  This extention follows rules set
+        out for Uniform Resource Identifier schemes in
+        <xref target="RFC3986"/>.  In the following text, we refer
+        to this extended NFS URL scheme as an NFS URI. </t>
 
         <t> The network location of an NFS fileset is stored in an
         FSL record encoded as an NFS URI.  An NFS URI uses the
@@ -521,6 +521,14 @@
         attribute's locations list based on the rank and order
         values.  </t>
 
+        <t> Another example:  A single NFS FSL record contains
+        the hostname of one fileserver.  A single fs_locations
+        attribute can contain a list of fileserver names.  An NFS
+        fileserver MAY combine two or more FSL records into a
+        single entry in an fs_locations or fs_locations_info array
+        only if each FSL record contains the same pathname and
+        extended filesystem information. </t>
+
         <t> Refer to the NFSv4.1 protocol specification
         <xref target="RFC5661"/>, sections 11.9 and 11.10,
         for further details.  </t>
@@ -1085,6 +1093,8 @@
 
             <t> The DN syntax (1.3.6.1.4.1.1466.115.121.1.12) described in <xref target="RFC4517"/>.  </t>
 
+            <t> The IA5String syntax (1.3.6.1.4.1.1466.115.121.1.26) described in <xref target="RFC4517"/>.  </t>
+
             </list>
         </t>
 
@@ -1330,8 +1340,9 @@
         /// attributetype (
         ///     1.3.6.1.4.1.31103.1.120 NAME 'fedfsNfsURI'
         ///     DESC 'Location of fileset'
-        ///     EQUALITY integerMatch
-        ///     SUP IA5String
+        ///     EQUALITY caseIgnoreIA5Match
+        ///     SUBSTR caseIgnoreSubstringsIA5Match
+        ///     SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
         ///     SINGLE-VALUE
         ///     )
         ///
@@ -1339,6 +1350,9 @@
 
             <t> &lt;CODE ENDS> </t>
 
+            <t> OID 1.3.6.1.4.1.1466.115.121.1.26 is the IA5String
+            syntax <xref target="RFC4517"/>.  </t>
+
         </section>
 
         <section title="fedfsNfsCurrency">

---

From: Chuck Lever <[email-masked]>
Date: Fri, 07 Sep 2012 15:56:36 -0400

---

 nsdb-proto.xml                    |    6 +++---
 references/reference.RFC.6641.xml |   19 +++++++++++++++++++
 2 files changed, 22 insertions(+), 3 deletions(-)
 create mode 100644 references/reference.RFC.6641.xml

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 55e94b3..f65836a 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -102,8 +102,8 @@
     <t> The requirements for federated filesystems are described
     in <xref target="RFC5716"/>. A protocol for administering
     a fileserver's namespace is described in <xref target="FEDFS-ADMIN"/>.
-    The mechanism for discovering the root of an NFSv4 namespace is
-    described in <xref target="FEDFS-DNS-SRV"/>. </t>
+    The mechanism for discovering the root of a federated namespace is
+    described in <xref target="RFC6641"/>. </t>
 
     <t> In the rest of the document, the term fileserver denotes a
     fileserver that is part of a federation. </t>
@@ -3129,7 +3129,7 @@
         <?rfc include="references/reference.AFS.xml"?>
         <?rfc include="references/reference.RFC.5716.xml"?>
         <?rfc include="references/reference.I-D.ietf-nfsv4-federated-fs-admin.xml"?>
-        <?rfc include="references/reference.I-D.ietf-nfsv4-federated-fs-dns-srv-namespace.xml"?>
+        <?rfc include="references/reference.RFC.6641.xml"?>
         <?rfc include="references/reference.RFC.5662.xml"?>
         <?rfc include="references/reference.MS-SMB.xml"?>
         <?rfc include="references/reference.MS-SMB2.xml"?>
diff --git a/references/reference.RFC.6641.xml b/references/reference.RFC.6641.xml
new file mode 100644
index 0000000..a57c9c4
--- /dev/null
+++ b/references/reference.RFC.6641.xml
@@ -0,0 +1,19 @@
+<?xml version='1.0' encoding='UTF-8'?>
+
+<reference anchor='RFC6641'>
+
+<front>
+<title>Using DNS SRV to Specify a Global File Namespace with NFS Version 4</title>
+<author initials='C.' surname='Everhart' fullname='C. Everhart'>
+<organization /></author>
+<author initials='W.' surname='Adamson' fullname='W. Adamson'>
+<organization /></author>
+<author initials='J.' surname='Zhang' fullname='J. Zhang'>
+<organization /></author>
+<date year='2012' month='June' />
+<abstract>
+<t>The NFS version 4 (NFSv4) protocol provides a mechanism for a collection of NFS file servers to collaborate in providing an organization-wide file namespace.  The DNS SRV Resource Record (RR) allows a simple way for an organization to publish the root of its file system namespace, even to clients that might not be intimately associated with such an organization.  The DNS SRV RR can be used to join these organization-wide file namespaces together to allow construction of a global, uniform NFS file namespace. [STANDARDS-TRACK]</t></abstract></front>
+
+<seriesInfo name='RFC' value='6641' />
+<format type='TXT' octets='24047' target='http://www.rfc-editor.org/rfc/rfc6641.txt' />
+</reference>

---

From: Chuck Lever <[email-masked]>
Date: Fri, 07 Sep 2012 15:56:45 -0400

---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index f65836a..ce51842 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -423,9 +423,9 @@
         the currency of the data at each location in order
         to ensure that the clients do not revert back in
         time when switching locations. NFSv4.1 provides
-    guidance on how replication can be handled in such a
-    manner, in particular see Section 11.7 of
-    <xref target='RFC5661' />.   </t>
+        guidance on how replication can be handled in such a
+        manner, in particular see Section 11.7 of
+        <xref target='RFC5661' />.   </t>
 
         </section>
 
@@ -672,9 +672,9 @@
 
         <t> In addition, version 1 UUIDs depend on the notion that a
         hardware MAC address is unique across machines.  As virtual
-      machines do not depend on unique physical MAC addresses and
-      in any event an administrator can modify the physical MAC
-      address, version 1 UUIDs are no longer considered sufficient.  </t>
+        machines do not depend on unique physical MAC addresses and
+        in any event an administrator can modify the physical MAC
+        address, version 1 UUIDs are no longer considered sufficient.  </t>
 
         <t> To minimize the probability of UUIDs colliding, a
         consistent procedure for generating UUIDs should be used
@@ -731,7 +731,7 @@
                 track of the FSL(s) and related
                 information for the fileset. </t>
 
-                <t> Create an FSN in the NSDB node.
+            <t> Create an FSN in the NSDB node.
 
                 <vspace blankLines="1" />
 
@@ -2648,7 +2648,7 @@
     Thus the contents and distinguished names of FSN and FSL records are
     required to be readable by anyone who can bind anonymously to an NSDB
     service. <xref target="sec:uuid" /> presents the security considerations
-  in the choice of the type of UUID used in these records. </t>
+    in the choice of the type of UUID used in these records. </t>
 
     <t> It should be noted that the federation protocols do not directly
     provide access to filesystem data. The federation protocols only

---

From: Chuck Lever <[email-masked]>
Date: Fri, 07 Sep 2012 15:56:53 -0400

RFC 4122 specifies that all UUIDs are comprised of 16 octets.  Thus
additionally specifying "128-bit" in the NSDB protocol document is
redundant.
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index ce51842..1113d5e 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -207,7 +207,7 @@
             NSDB node that contains authoritative information for
             this FSN. </t>
 
-            <t hangText="   FsnUuid:"> a 128-bit UUID
+            <t hangText="   FsnUuid:"> a UUID
             (universally unique identifier), conforming to
             <xref target="RFC4122"/>, that is used to uniquely
             identify an FSN. </t>
@@ -267,11 +267,11 @@
         <t>
         <list style="hanging" hangIndent="6">
 
-            <t hangText="   FslUuid:"> a 128-bit UUID, conforming to
+            <t hangText="   FslUuid:"> a UUID, conforming to
             <xref target="RFC4122"/>, that is used to uniquely
             identify an FSL. </t>
 
-            <t hangText="   FsnUuid:"> the 128-bit UUID of the
+            <t hangText="   FsnUuid:"> the UUID of the
             FSL's FSN. </t>
 
             <t hangText="   NsdbName:"> the network location of the

---

From: Chuck Lever <[email-masked]>
Date: Fri, 07 Sep 2012 15:57:01 -0400

Cite RFC 4516 in example that uses an LDAP URL, and stick with
"nsdb.example.com" throughout.
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 1113d5e..2d305c1 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -2474,19 +2474,19 @@
 
         <section title="NSDB Container Entry (NCE) Enumeration">
 
-        <t> To find the NCEs for the NSDB foo.example.com, a fileserver would do
+        <t> To find the NCEs for the NSDB nsdb.example.com, a fileserver would do
         the following: </t>
 
             <figure><artwork><![CDATA[
         nce_list = empty
-        connect to the LDAP directory at foo.example.com
+        connect to the LDAP directory at nsdb.example.com
         for each namingContext value $BAR in the root DSE
             /* $BAR is a DN */
             query for a fedfsNceDN value at $BAR
             /*
-             * The LDAP URL for this search would be
+             * The RFC 4516 LDAP URL for this search would be
              *
-             *  ldap://foo.example.com:389/$BAR?fedfsNceDN??
+             *  ldap://nsdb.example.com:389/$BAR?fedfsNceDN??
              *                      (objectClass=fedfsNsdbContainerInfo)
              *
              */

---

From: Chuck Lever <[email-masked]>
Date: Fri, 07 Sep 2012 15:57:10 -0400

Correct punctuation and grammar errors.  Break up a few long
paragraphs.
---

 nsdb-proto.xml |   73 +++++++++++++++++++++++++++++---------------------------
 1 files changed, 38 insertions(+), 35 deletions(-)

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 2d305c1..c7f4b0e 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -192,9 +192,9 @@
     <section title="Fileset Name (FSN)">
 
         <t> A fileset is uniquely represented by its fileset name
-        (FSN).  An FSN is considered unique across the federation.
+        (FSN).  An FSN is considered unique across a federation.
         After an FSN is created, it is associated with one or more
-        fileset locations (FSLs) on a fileserver. </t>
+        fileset locations (FSLs) on one or more fileservers. </t>
 
         <t> An FSN consists of: </t>
 
@@ -406,20 +406,19 @@
         consistency of a read-only location if the
         read-write location is changing.  </t>
 
-        <t> 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 the functional
-        equivalence of the data.  </t>
+        <t> Regardless of the type, one file-access client may
+        be referred to a location described by one FSL while
+        another client chooses to use a location described by
+        another FSL.  Since updates to each fileset location
+        are not controlled by the federation protocol, it is the
+        responsibility of administrators to guarantee the
+        functional equivalence of the data.  </t>
 
         <t> 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 to contain
-        sufficient information to help the clients determine
+        file-access protocol to contain
+        sufficient information to help 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. NFSv4.1 provides
@@ -623,8 +622,9 @@
         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 root fileset could be implemented either as an exported
+        fileservers it can view a common federation-wide namespace.  </t>
+
+        <t> The root fileset could be implemented either as an exported
         NFS file system or as data in the NSDB itself. The properties
         and schema definition of an NSDB-based root fileset and
         the protocol details that describe how to configure and replicate
@@ -764,7 +764,7 @@
         node and the FSN are already known.  The only
         remaining step is to add another FSL. </t>
 
-        <t> Note that the federation protocols only provide
+        <t> Note that the federation protocols provide only
         the mechanisms to register and unregister replicas
         of a fileset. Fileserver-to-fileserver replication
         protocols are not defined. </t>
@@ -832,11 +832,13 @@
         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
+        (say, a daily or 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
+        in the namespace. </t>
+
+        <t> The daily snapshots are considered as
+        different filesets from the weekly ones, but both are
+        related to the source fileset.  We can define
         an annotation labeling the filesets as source and
         replica.  The replication protocol can use this
         information to copy data from one or more FSLs of the
@@ -854,14 +856,16 @@
         annotating the filesets with user-defined relationships.
         </t>
 
-        <t>  Another potential use for annotations is recording
+        <t> Another potential use for annotations is recording
         references to an FSN. A single annotation containing
-        the number of references could be defined or multiple
+        the number of references could be defined; or multiple
         annotations, one per reference, could be used to store
         detailed information on the location of each reference.
-        As with the replication annotation described above, the
+        </t>
+
+        <t> As with the replication annotation described above, the
         maintenance of reference information would not be controlled
-        by the federation protocol. The information would mostly
+        by the federation protocol. The information would most
         likely be non-authoritative because the ability to
         create a junction does not require the authority to
         update the FSN record. In any event, such annotations
@@ -898,9 +902,9 @@
 
         <t> There MUST be an LDAP entry that is superior
             to all of the naming context's federation entries in
-            the Directory Information Tree (DIT) This entry is
+            the Directory Information Tree (DIT). This entry is
             termed the NSDB Container Entry (NCE). The NCE's
-            children are FSNs. An FSNs children are FSLs.
+            children are FSNs. An FSN's children are FSLs.
             </t>
 
         <t> The naming context's root entry MUST include
@@ -2042,7 +2046,7 @@
 
     <t> 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.  </t>
+    a federation to perform different roles.  </t>
 
     <t> The first of these sub-protocols defines how the state
     of an NSDB node can be initialized and updated.  The
@@ -2078,7 +2082,7 @@
     For example, a variable named FOO would be specified as $FOO. </t>
 
     <t> This document uses the term NSDB client to refer to an LDAP
-    client that uses either of the NSDB sub-protocols</t>
+    client that uses either of the NSDB sub-protocols.</t>
 
     <t> The third sub-protocol defines the queries and
     other requests that are sent to a fileserver in order to
@@ -2088,7 +2092,7 @@
     an administrator to create or delete a junction or discover
     related information about a particular fileserver. </t>
 
-    <t> The third sub-protocol is defined as an ONC RPC protocols.
+    <t> The third sub-protocol is defined as an ONC RPC protocol.
     The reason for using ONC RPC instead of LDAP is that all
     fileservers support ONC RPC but some do not support an LDAP
     Directory server.  </t>
@@ -2176,9 +2180,9 @@
         of <xref target="RFC4511"/> defines the LDAP delete operation
         to only be capable of removing leaf entries.  </t>
 
-        <t> Note that the FSN delete function only removes
-        the fileset from the namespace (by removing the
-        records for that FSN from the NSDB node that
+        <t> Note that the FSN delete function removes the
+        fileset only from a federation namespace (by removing
+        the records for that FSN from the NSDB node that
         receives this request).  The fileset and its data
         are not deleted.  Any junction that has this FSN as
         its target may continue to point to this
@@ -2388,11 +2392,10 @@
 
         <section title="Delete an FSL">
 
-        <t> This operation deletes the given Fileset location.  The
-        admin requests the NSDB node storing the fedfsFsl to
+        <t> This operation deletes a Fileset location record.
+        The admin requests the NSDB node storing the fedfsFsl to
         delete it from its database.  This operation does
-        not result in the fileset location's data being
-        deleted at the fileserver.  </t>
+        not result in fileset data being deleted on any fileserver. </t>
 
         <section title="LDAP Request">