Subject: [nfsv4] [PATCH 00/16] Address IESG review items for NSDB/ADMIN protocol

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:45:49 -0400

Let me propose the following changes to the NSDB and ADMIN protocol
drafts to address recent IESG DISCUSS and COMMENT items.  There are
unresolved issues with Section 7 of the NSDB protocol draft, so it
is not updated in this change set.

---

Chuck Lever (16):
      Resolve Barry Leiba's IESG COMMENT item (ADMIN sections 5.8.2 and others)
      Resolve Barry Leiba's IESG COMMENT item (ADMIN sections 5.[234567].2)
      Resolve Barry Leiba's IESG COMMENT item (ADMIN sections 5.5.2 and 5.6.2)
      Resolve Barry Leiba's IESG COMMENT item (ADMIN sections 5.[234567].2)
      Resolve Barry Leiba's IESG COMMENT item (NSDB sections 4.2.1.10ff)
      Resolve Barry Leiba's IESG COMMENT item (NSDB section 4.2.1.6)
      Resolve Barry Leiba's IESG COMMENT item (NSDB section 4.2)
      Resolve Barry Leiba's IESG COMMENT item (NSDB section 4.1)
      Resolve Barry Leiba's IESG COMMENT item (NSDB section 3.3)
      Resolve Barry Leiba's IESG COMMENT item (NSDB section 2.12)
      Resolve Barry Leiba's IESG COMMENT item (NSDB section 2.11)
      Resolve Barry Leiba's IESG COMMENT item (NSDB section 2.8.3)
      Resolve Barry Leiba's IESG COMMENT item (NSDB section 2.8.1)
      Resolve Barry Leiba's IESG COMMENT item (NSDB section 1)
      Resolve Barry Leiba's IESG DISCUSS item (NSDB section 4.2.1.24)
      Resolve Barry Leiba's IESG DISCUSS item (NSDB section 2.7 and 4.2.1.3)

 admin-proto.xml |  126 ++++++++++++++++++----------------
 nsdb-proto.xml  |  203 ++++++++++++++++++++++++++-----------------------------
 2 files changed, 162 insertions(+), 167 deletions(-)

-- 
Chuck Lever

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:45:58 -0400

-- Sections 2.7 and 2.8.3 --

 ...

 First, is the text in 2.7 meant to refer to the "FsnTTL" item that was
 just defined?  Why aren't the normative requirements for its use defined
 there?

 In Section 2.8.3, the MAY in the first paragraph looked inappropriate,
 but I wasn't positive until I read the MUST NOT in the second.  There's
 also a SHOULD NOT in the second paragraph of the section that conflicts
 with that MUST NOT.  You're saying the same stuff too often, in too many
 places, inconsistently.  This information needs to be clearly specified
 normatively in one place, and cited from elsewhere without extra 2119
 language that will confuse things.

 -- Section 2.8.3 --

 There are two places where you use "FSN TTL", which was defined in
 Section 2.7 as "FsnTTL".  It's probably better to use "FsnTTL"
 consistently.

 -- Section 4.2.1.3 --

 This is related to the stuff above: You've previously said that caching
 MAY be done, and now you're saying SHOULD.  You've previously specified
 FsnTTL as the *maximum* cache time, and now you're describing it as the
 *only* cache time.  I suggest that you take the 2119 language out of this
 and use a citation to Section 2.7 here, making sure that 2.7 says what
 you want.
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 8e13726..19ff98e 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -194,7 +194,7 @@
 
     </section>
 
-    <section title="Fileset Name (FSN)">
+    <section title="Fileset Name (FSN)" anchor="fileset_name">
 
         <t> A fileset is uniquely represented by its fileset name
         (FSN).  An FSN is considered unique across a federation.
@@ -217,8 +217,11 @@
             <xref target="RFC4122"/>, that is used to uniquely
             identify an FSN. </t>
 
-            <t hangText="   FsnTTL:"> the time in seconds during
-            which the FSN's FSL information may be cached. </t>
+            <t hangText="   FsnTTL:"> the time-to-live of the FSN's
+            FSL information, in seconds.  Fileservers MUST NOT use
+            cached FSL records after the parent FSN's FsnTTL has expired.
+            An FsnTTL value of zero indicates that fileservers MUST NOT
+            cache the results of resolving this FSN.</t>
         </list>
         </t>
 
@@ -228,11 +231,11 @@
         and is indeed authenticated in cases where TLS security
         is in effect. </t>
 
-        <t> An FSN record also contains a cache time-to-live attribute.
-        The FsnUuid and NsdbName values never change during an FSN's
+        <t> The FsnUuid and NsdbName values never change during an FSN's
         lifetime.  However, an FSN's FSL information can change over
         time, and is typically cached on fileservers for performance.
-        More detail is provided in <xref target="fsl_caching"/>. </t>
+        More detail on FSL caching is provided in
+        <xref target="fsl_caching"/>. </t>
 
         <t> An FSN record may also contain: </t>
 
@@ -466,14 +469,10 @@
 
         <t> To resolve an FSN to a set of FSL records, a
         fileserver queries the NSDB node named in the FSN
-        for FSL records associated with this FSN. </t>
-
-        <t> The period of time during which these FSL records MAY
-        be cached is indicated by the parent FSN's TTL attribute.
-        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>
+        for FSL records associated with this FSN.  The parent
+        FSN's FsnTTL attribute (see <xref target="fileset_name"/>)
+        specifies the period of time during which a fileserver may
+        cache these FSL records. </t>
 
         <t> The combination of FSL caching and FSL migration presents
         a challenge. For example, suppose there are three fileservers
@@ -531,22 +530,21 @@
         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 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
-        the lifetime of redirecting junctions.  </t>
+        <t> The FsnTTL field in the FSL's parent FSN (see
+        <xref target="fileset_name"/>) specifies an upper bound for
+        the lifetime of cached FSL information, and thus can act
+        as a lower bound for the lifetime of redirecting junctions. </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> For example, suppose the FsnTTL field contains the value
+        3600 seconds (one hour).  In such a case, administrators
+        SHOULD keep the redirection in place for at least one hour
+        after a fileset migration has taken place, because a referring
+        fileserver might cache the FSL data during that time before
+        refreshing it. </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
+        FsnTTL field of the migrated fileset to a low number or
         zero before migration begins.  It can be reset to a
         more reasonable number at a later point.  </t>
 
@@ -1242,10 +1240,13 @@
 
         <section title="fedfsFsnTTL">
 
-            <t> A fedfsFsnTTL is the amount of time in seconds an FSN's
-            TTL and its children FSL records SHOULD be cached by a
-            fileserver.  A fedfsFsnTTL MUST be encoded as an Integer
-            syntax value <xref target="RFC4517"/>.  </t>
+            <t> A fedfsFsnTTL is the time-to-live in seconds of a
+            cached FSN and its child FSL records.  It corresponds to
+            the FsnTTL as defined in <xref target="fileset_name"/>.
+            See also Section <xref target="fsl_caching"/> for
+            information about caching FSLs.  A fedfsFsnTTL MUST be
+            encoded as an Integer syntax value
+            <xref target="RFC4517"/>.  </t>
 
             <t> This attribute is single-valued.  </t>

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:46:07 -0400

-- Section 4.2.1.24 --

   A fedfsNfsVarSub stores the value of an FSL's NFSv4.1 FSLI4F_VAR_SUB
   bit [RFC5661].

 This should be "FSLI4IF_VAR_SUB" (it's missing an "I").
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 19ff98e..0769443 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -1905,7 +1905,7 @@
         <section title="fedfsNfsVarSub">
 
             <t> A fedfsNfsVarSub stores the
-            value of an FSL's NFSv4.1 FSLI4F_VAR_SUB bit
+            value of an FSL's NFSv4.1 FSLI4IF_VAR_SUB bit
             <xref target="RFC5661"/>. A value of "TRUE"
             indicates the bit is true. A value of
             "FALSE" indicates the bit is false. </t>

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:46:15 -0400

-- Section 1 --

 All the "MAY"s in the second paragraph are inappropriate, and should be
 "may" (or "might", of you prefer).  That's all non-normative explanation
 of how this is all meant to fit together, not normative text about
 interoperability choices.
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 0769443..48dfaee 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -69,12 +69,12 @@
     containing one or more federated filesystems. Each federated
     filesystem's namespace is composed of the filesystems physically
     hosted on and exported by the federation's fileservers. A
-    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
+    federation comprises a common namespace across all its
+    fileservers. A federation can project multiple namespaces and
+    enable clients to traverse each one. A federation can contain
     an arbitrary number of namespace repositories, each belonging
     to a different administrative entity, and each rendering a part
-    of the namespace. A federation MAY also have an arbitrary number
+    of the namespace. A federation might also have an arbitrary number
     of administrative entities responsible for administering disjoint
     subsets of the fileservers. </t>

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:46:23 -0400

-- Section 2.8.1.1 --

 It's probably not a good idea to repeat normative information from
 elsewhere without citation.

 -- Section 2.8.1.2 --

 Again, none of the encoding stuff is new.  I'd really like it if you made
 it clear that this is all just in conformance with normal RFC 3986 rules.
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 48dfaee..79f6a39 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -349,7 +349,8 @@
             <t> An NFS URI MAY contain a port subcomponent as
             described in section 3.2.3 of <xref target="RFC3986"/>.
             If this subcomponent is missing, a port value of 2049
-            is assumed. </t>
+            is assumed, as specified in <xref target="3530bis"/>,
+            Section 3.1. </t>
 
             </section>
 
@@ -383,14 +384,13 @@
             characters following an NFS URI's authority component.
             </t>
 
-            <t> The component4 elements of an NFS pathname SHOULD be
-            prepared using the component4 rules defined in Chapter 12
-            "Internationalization" of <xref target="3530bis"/> prior to
-            encoding the path component of an NFS URI.  Because a URI
-            is a US-ASCII string, any non-ASCII UTF-8 code point in a
-            component4 element MUST be represented by URI percent
-            encoding.  URI-reserved characters such as the slash ("/")
-            character contained in a component4 element MUST be
+            <t> The component4 elements of an NFSv4 pathname SHOULD
+            be prepared using the component4 rules defined in Chapter
+            12 "Internationalization" of <xref target="3530bis"/>
+            prior to encoding the path component of an NFS URI.
+            As specified in [RFC3986], any non-ASCII UTF-8 code points
+            and any URI-reserved characters, such as the slash ("/")
+            character, contained in a component4 element MUST be
             represented by URI percent encoding. </t>
 
             </section>

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:46:32 -0400

-- Section 2.8.3 --

 I also suggest adding a forward reference to Section 2.10 the first time
 "junction" is mentioned.
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 79f6a39..785b5d7 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -477,7 +477,8 @@
         <t> The combination of FSL caching and FSL migration presents
         a challenge. For example, suppose there are three fileservers
         named A, B, and C.  Suppose further that fileserver A
-        contains a junction J to fileset X stored on fileserver B.
+        contains a junction J to fileset X stored on fileserver B
+        (see <xref target="junctions"/> for a description of junctions).
         </t>
 
         <t> Now suppose that fileset X is migrated from fileserver B
@@ -650,7 +651,7 @@
 
     </section>
 
-    <section title="Junctions and Referrals">
+    <section title="Junctions and Referrals" anchor="junctions">
 
         <t> A junction is a point in a particular fileset namespace
         where a specific target fileset may be attached.  If a

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:46:41 -0400

-- Section 2.11 --

 Is there a document where [root filesets] are or will be defined, which
 you can cite?  If so, please do; if not, it might be better to say why
 they're not defined here ("...are implementation dependent and are not
 in scope for this document," or whatever is appropriate).
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 785b5d7..8e64781 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -693,12 +693,6 @@
         designated 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
-        the root fileset are not defined in this document.  </t>
-
     </section>
 
     <section anchor="sec:uuid" title="UUID Considerations">

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:46:49 -0400

-- Section 2.12 --

  Of course, there is no way to guard against UUID re-use, but that is
  highly unlikely provided that UUIDs are constructed carefully.

 Is "carefully" the right word?  Or maybe, "properly, according to
 [RFC4122]." ?
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 8e64781..28d5494 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -719,10 +719,6 @@
         for just a single FSN.  As with FSNs, as soon as an FSL is
         published, its uniqueness is guaranteed.  </t>
 
-        <t> Of course, there is no way to guard against UUID re-use,
-        but that is highly unlikely provided that UUIDs are constructed
-        carefully.  </t>
-
         <t> A fileserver performs the operations described in
         <xref target="nsdb-ops-fileservers"/> as an unauthenticated user.
         Thus distinguished names of FSN and FSL records, as well as

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:46:58 -0400

-- Section 3.3 --

   Fileset annotations MAY be used to convey additional attributes of a
   fileset

 Apart from a missing full stop at the end, here's another inappropriate
 "MAY", which should be "may" or "can".  This isn't describing a protocol
 choice that affects interoperability.  It's telling us what fileset
 annotations are used for.
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 28d5494..a5d5d8a 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -887,12 +887,10 @@
 
     <section title="Example Use Cases for Fileset Annotations">
 
-        <t> Fileset annotations MAY be used to convey additional
-        attributes of a fileset </t>
-
-        <t> For example, fileset annotations can be used to define
-        relationships between filesets that can be used by an
-        auxiliary replication protocol.  Consider the scenario
+        <t> Fileset annotations can convey additional attributes of
+        a fileset.  For example, fileset annotations can be used to
+        define relationships between filesets that can be used by
+        an auxiliary replication protocol.  Consider the scenario
         where a fileset is created and mounted at some point in
         the namespace.  A snapshot of the read-write FSL of that
         fileset is taken periodically at different frequencies

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:47:08 -0400

-- Section 4.1 --

   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.

 The "SHOULD" and "at minimum" have an unclear relationship.

 --

   Given the above configuration guidelines, an NSDB SHOULD be
   constructed using a dedicated LDAP directory.  Separate LDAP
   directories are RECOMMENDED for other purposes, such as storing user
   account information.

 Again, the relationship of the second sentence to the SHOULD in the first
 is unclear.
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index a5d5d8a..eeb93b1 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -1028,14 +1028,33 @@
         fileserver performs the operations described in
         <xref target="nsdb-ops-fileservers"/> as an unprivileged user. </t>
 
-        <t> 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. </t>
-
-        <t> Given the above configuration guidelines, an NSDB SHOULD be
-        constructed using a dedicated LDAP directory. Separate LDAP
-        directories are RECOMMENDED for other purposes, such as storing
-        user account information. By using an LDAP directory dedicated
+        <t> All implementations SHOULD use the same schema.  At minimum,
+        each MUST use a schema that includes all objects named in the
+        following sections, with all associated attributes.  If it is
+        necessary for an implementation to extend the schema defined
+        here, consider using one of the following ways to extend the
+        schema: </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>
+
+        <t> Given the above configuration guidelines, an NSDB SHOULD
+        be constructed using a dedicated LDAP server.  If LDAP
+        directories are needed for other purposes, such as to store
+        user account information, use of a separate LDAP server
+        for those is RECOMMENDED.  By using an LDAP server dedicated
         to storing NSDB records, there is no need to disturb the
         configuration of any other LDAP directories that store
         information unrelated to an NSDB. </t>
@@ -2132,28 +2151,6 @@
 
     </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">

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:47:17 -0400

-- Section 4.2 --

   As stated above, code components extracted from this document must
   include the following license:

 As stated "above" where?  Maybe say "in the Copyright Notice at the
 beginning of this document," or just leave that off and start with "Code
 components...."
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index eeb93b1..d5af65b 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -1095,8 +1095,8 @@
         <t> The effect of the script is to remove leading white space from each
             line, plus a sentinel sequence of "///". </t>
 
-        <t> As stated above, code components extracted from this
-            document must include the following license: </t>
+        <t> Code components extracted from this document must include the
+            following license: </t>
 
             <t> &lt;CODE BEGINS> </t>

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:47:26 -0400

-- Section 4.2.1.6 --

   A fedfsAnnotation value SHOULD be processed as follows:

 Why?  Is this talking about interoperability, or imposing an
 implementation?  What happens if I reverse those two steps in my
 implementation?  Is there a difference?

   A fedfsAnnotation attribute that does not adhere to this format
   SHOULD be ignored.

 What other options are there?  What else could I possibly do with it?

 You might also include an example that doesn't have the optional SPACE
 characters around the EQUALS:

   "key1"="foo"
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index d5af65b..5c4b883 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -1372,7 +1372,7 @@
                 <c>" </c>
             </texttable>
 
-            <t> A fedfsAnnotation value SHOULD be processed as follows: </t>
+            <t> A fedfsAnnotation value might be processed as follows: </t>
 
                 <t><list style="numbers">
             <t> Parse the attribute value according to the ANNOTATION rule,
@@ -1381,8 +1381,9 @@
                 escape sequences above. </t>
                 </list></t>
 
-            <t> A fedfsAnnotation attribute that does not adhere to this format SHOULD
-            be ignored. </t>
+            <t> A fedfsAnnotation attribute that does not adhere to this
+            format SHOULD be ignored in its entirety.  It MUST NOT prevent
+            further processing of its containing entry. </t>
 
             <t> The following are examples of valid fedfsAnnotation attributes: </t>
 
@@ -1390,6 +1391,7 @@
          "key1" = "foo"
          "another key" = "x=3"
          "key-2" = "A string with \" and \\ characters."
+         "key3"="bar"
             ]]></artwork></figure>
 
             <t> which correspond to the following key/value pairs: </t>
@@ -1403,6 +1405,8 @@
                 <c>x=3</c>
                 <c>key-2</c>
                 <c>A string with " and \ characters.</c>
+                <c>key3</c>
+                <c>bar</c>
             </texttable>

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:47:34 -0400

-- Section 4.2.1.10 --

   A fedfsNfsGenFlagWritable stores the value of an FSL's NFSv4.1
   FSLI4GF_WRITABLE bit [RFC5661].  A value of "TRUE" indicates the bit
   is true.  A value of "FALSE" indicates the bit is false.

 RFC 5661 never uses "true" or "false" to refer to that bit.  It uses
 "set" and "on".  I suggest this:
 NEW
   A fedfsNfsGenFlagWritable stores the value of an FSL's NFSv4.1
   FSLI4GF_WRITABLE bit [RFC5661].  A value of "TRUE" indicates the bit
   is set.  A value of "FALSE" indicates the bit is not set.

I suggest the same change for Sections 4.2.1.11, 12, and 13.
---

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

diff --git a/nsdb-proto.xml b/nsdb-proto.xml
index 5c4b883..5ef83f6 100644
--- a/nsdb-proto.xml
+++ b/nsdb-proto.xml
@@ -1512,8 +1512,8 @@
             <t> A fedfsNfsGenFlagWritable stores the
             value of an FSL's NFSv4.1 FSLI4GF_WRITABLE bit
             <xref target="RFC5661"/>. A value of "TRUE"
-            indicates the bit is true. A value of
-            "FALSE" indicates the bit is false. </t>
+            indicates the bit is set. A value of
+            "FALSE" indicates the bit is not set. </t>

@@ -1541,8 +1541,8 @@
             <t> A fedfsNfsGenFlagGoing stores the
             value of an FSL's NFSv4.1 FSLI4GF_GOING bit
             <xref target="RFC5661"/>. A value of "TRUE"
-            indicates the bit is true. A value of
-            "FALSE" indicates the bit is false. </t>
+            indicates the bit is set. A value of
+            "FALSE" indicates the bit is not set. </t>

@@ -1570,8 +1570,8 @@
             <t> A fedfsNfsGenFlagSplit stores the
             value of an FSL's NFSv4.1 FSLI4GF_SPLIT bit
             <xref target="RFC5661"/>. A value of "TRUE"
-            indicates the bit is true. A value of
-            "FALSE" indicates the bit is false. </t>
+            indicates the bit is set. A value of
+            "FALSE" indicates the bit is not set. </t>

@@ -1599,8 +1599,8 @@
             <t> A fedfsNfsTransFlagRdma stores the
             value of an FSL's NFSv4.1 FSLI4TF_RDMA bit
             <xref target="RFC5661"/>. A value of "TRUE"
-            indicates the bit is true. A value of
-            "FALSE" indicates the bit is false. </t>
+            indicates the bit is set. A value of
+            "FALSE" indicates the bit is not set. </t>

@@ -1919,8 +1919,8 @@
             <t> A fedfsNfsVarSub stores the
             value of an FSL's NFSv4.1 FSLI4IF_VAR_SUB bit
             <xref target="RFC5661"/>. A value of "TRUE"
-            indicates the bit is true. A value of
-            "FALSE" indicates the bit is false. </t>
+            indicates the bit is set. A value of
+            "FALSE" indicates the bit is not set. </t>
             <t> &lt;CODE BEGINS> </t>
 
             <figure><artwork><![CDATA[

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:47:43 -0400

-- Section 5.2.2 --

   If the path contains an invalid UTF-8 character, then status
   FEDFS_ERR_BADCHAR MUST be returned.

 What characters are valid?  When I look at the definition of
 FEDFS_ERR_BADCHAR, I think you mean "unsupported", rather than
 "invalid"... yes?  [I'm picking on this because the IDNA specs actually
 *do* define valid and invalid characters, and you probably don't want to
 try to mess with that. :-) ]

 This also appears in Sections 5.3.2, 5.4.2, 5.5.2, 5.6.2, and 5.7.2.
---

 admin-proto.xml |   26 +++++++++++++-------------
 1 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/admin-proto.xml b/admin-proto.xml
index 165dc94..2949e17 100644
--- a/admin-proto.xml
+++ b/admin-proto.xml
@@ -889,8 +889,8 @@
           </t>
 
           <t>
-            If the path contains an invalid UTF-8 character,
-            then status FEDFS_ERR_BADCHAR MUST be returned.
+            If the path contains a character that is not supported by
+            the server, then status FEDFS_ERR_BADCHAR MUST be returned.
           </t>
 
           <t>
@@ -1027,8 +1027,8 @@
           </t>
 
           <t>
-            If the path contains an invalid UTF-8 character,
-            then status FEDFS_ERR_BADCHAR MUST be returned.
+            If the path contains a character that is not supported by
+            the server, then status FEDFS_ERR_BADCHAR MUST be returned.
           </t>
 
           <t>
@@ -1155,8 +1155,8 @@
           </t>
 
           <t>
-            If the path contains an invalid UTF-8 character,
-            then status FEDFS_ERR_BADCHAR MUST be returned.
+            If the path contains a character that is not supported by
+            the server, then status FEDFS_ERR_BADCHAR MUST be returned.
           </t>
 
           <t>
@@ -1405,8 +1405,8 @@
           </t>
 
           <t>
-            If the path contains an invalid UTF-8 character,
-            then status FEDFS_ERR_BADCHAR MUST be returned.
+            If the path contains a character that is not supported by
+            the server, then status FEDFS_ERR_BADCHAR MUST be returned.
           </t>
 
           <t>
@@ -1505,8 +1505,8 @@
           </t>
 
           <t>
-            If the path contains an invalid UTF-8 character,
-            then status FEDFS_ERR_BADCHAR MUST be returned.
+            If the path contains a character that is not supported by
+            the server, then status FEDFS_ERR_BADCHAR MUST be returned.
           </t>
 
           <t>
@@ -1577,9 +1577,9 @@
           </t>
 
           <t>
-            If the path contains an invalid UTF-8
-            character, then status FEDFS_ERR_BADCHAR
-            MUST be returned.
+            If the path contains a character that is not
+            supported by the server, then status
+            FEDFS_ERR_BADCHAR MUST be returned.
           </t>
 
           <t>

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:47:51 -0400

-- Section 5.5.2 --

   The server SHOULD permit this operation even on read-only filesets,
   but MAY return FEDFS_ERR_ROFS if this is not possible.

 You might mean exactly this, in which case it's fine, but this is a
 SHOULD/MAY construct that's often wrong, so I'm checking.  "SHOULD do X
 but MAY do Y" is correct if Y is *always* optional.  But more often, this
 is what's really intended:

   The server SHOULD permit this operation even on read-only filesets,
   but MUST return FEDFS_ERR_ROFS if this is not possible.

 Is that the case here?
 This also appears in Section 5.6.2.
---

 admin-proto.xml |    4 ++--

diff --git a/admin-proto.xml b/admin-proto.xml
index 2949e17..dba4df0 100644
--- a/admin-proto.xml
+++ b/admin-proto.xml
@@ -1400,7 +1400,7 @@
 
           <t>
             The server SHOULD permit this operation even
-            on read-only filesets, but MAY return
+            on read-only filesets, but MUST return
             FEDFS_ERR_ROFS if this is not possible.
           </t>
 
@@ -1500,7 +1500,7 @@
 
           <t>
             The server SHOULD permit this operation even on
-            read-only filesets, but MAY return FEDFS_ERR_ROFS
+            read-only filesets, but MUST return FEDFS_ERR_ROFS
             if this is not possible.
           </t>

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:48:08 -0400

-- Section 5.9.2 --

   On failure, an error value indicating the type of error is returned.
   This operation MAY return FEDFS_ERR_NSDB_PARAMS to indicate that
   there are no connection parameters on record for the given NSDB.  The
   operation MAY return FEDFS_ERR_ACCESS if the operation's associated
   user does not have sufficient permissions to view NSDB connection
   parameters.

 This is similar to some of the others.  If you mean to say that using
 those error codes is entirely optional, even under the conditions
 specified, then this is fine.  But if you mean to say that certain error
 codes are definitely the ones to use in these situations, then the MAYs
 are wrong, and you should re-word this.

 There are similar situations at the ends of Sections 5.8.2 and 5.10.2.
---

 admin-proto.xml |   24 ++++++++++++------------
 1 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/admin-proto.xml b/admin-proto.xml
index 9daee94..e1da182 100644
--- a/admin-proto.xml
+++ b/admin-proto.xml
@@ -1712,11 +1712,11 @@
 
           <t>
             On failure, an error value indicating the
-            type of error is returned. The operation
-            MAY return FEDFS_ERR_ACCESS if the operation's
+            type of error is returned.  If the operation's
             associated user does not have sufficient
             permissions to create/modify NSDB connection
-            parameters.
+            parameters, the operation MUST return
+            FEDFS_ERR_ACCESS.
           </t>
         </section>
 
@@ -1783,13 +1783,13 @@
 
           <t>
             On failure, an error value indicating the
-            type of error is returned. This operation MAY
+            type of error is returned. This operation MUST
             return FEDFS_ERR_NSDB_PARAMS to indicate that
             there are no connection parameters on record for
-            the given NSDB. The operation MAY return
-            FEDFS_ERR_ACCESS if the operation's associated
-            user does not have sufficient permissions to
-            view NSDB connection parameters.
+            the given NSDB. If the operation's associated
+            user does not have sufficient permissions to view
+            NSDB connection parameters, the operation MUST
+            return FEDFS_ERR_ACCESS.
           </t>
         </section>
 
@@ -1877,14 +1877,14 @@
 
           <t>
             On failure, an error value indicating the
-            type of error is returned. This operation MAY
+            type of error is returned. This operation MUST
             return FEDFS_ERR_NSDB_PARAMS to indicate that
             there are no connection parameters on record for
-            the given NSDB. The operation MAY return
-            FEDFS_ERR_ACCESS if the operation's associated
+            the given NSDB. If the operation's associated
             user does not have sufficient permissions to
             view the subset of NSDB connection parameters
-            returned by this procedure.
+            returned by this procedure, the operation MUST
+            return FEDFS_ERR_ACCESS.
           </t>
         </section>

---

From: Chuck Lever <[email-masked]>
Date: Thu, 01 Nov 2012 16:48:00 -0400

This one is related:
   The server MAY enforce the local permissions on the path, including
   the final component.  If the path cannot be traversed because of
   insufficient permissions, or the final component is an unexecutable
   or unwritable directory, then the operation MAY fail with status
   FEDFS_ERR_ACCESS.

 If you mean this, then the phrasing above is correct:
 1. The server MAY enforce local permissions.
 2. If it does, then it MAY use FEDFS_ERR_ACCESS to convey failures (but
 that's entirely optional, and it could use some other code instead).

 But if you mean this, then you should re-phrase:
 1. The server MAY enforce local permissions.
 2. If it does, then it MUST use FEDFS_ERR_ACCESS to convey failures.

 This also appears in Sections 5.2.2, 5.3.2, 5.4.2, 5.6.2, and 5.7.2.
---

 admin-proto.xml |   72 +++++++++++++++++++++++++++++--------------------------
 1 files changed, 38 insertions(+), 34 deletions(-)

diff --git a/admin-proto.xml b/admin-proto.xml
index dba4df0..9daee94 100644
--- a/admin-proto.xml
+++ b/admin-proto.xml
@@ -916,11 +916,12 @@
 
           <t>
             The server MAY enforce the local permissions on
-            the path, including the final component.  If the
-            path cannot be traversed because of insufficient
-            permissions, or the final component is an
-            unexecutable or unwritable directory, then the
-            operation MAY fail with status FEDFS_ERR_ACCESS.
+            the path, including the final component.  If a
+            server wishes to report that a path cannot be
+            traversed because of insufficient permissions,
+            or the final component is an unexecutable or
+            unwritable directory, then the operation MUST
+            fail with status FEDFS_ERR_ACCESS.
           </t>
 
           <t>
@@ -1057,12 +1058,12 @@
 
           <t>
             The server MAY enforce the local permissions on
-            the path, including the final component.  If the
-            path cannot be traversed because of insufficient
-            permissions, or the parent directory of the
-            junction is an unexecutable or unwritable directory,
-            then the operation MAY fail with status
-            FEDFS_ERR_ACCESS.
+            the path, including the final component.  If a
+            server wishes to report that a path cannot be
+            traversed because of insufficient permissions,
+            or the final component is an unexecutable or
+            unwritable directory, then the operation MUST
+            fail with status FEDFS_ERR_ACCESS.
           </t>
 
           <t>
@@ -1184,12 +1185,12 @@
 
           <t>
             The server MAY enforce the local permissions on
-            the path, including the final component.  If the
-            path cannot be traversed because of insufficient
-            permissions, or the parent directory of the
-            junction is an unexecutable or unwritable directory,
-            then the operation MAY fail with status
-            FEDFS_ERR_ACCESS.
+            the path, including the final component.  If a
+            server wishes to report that a path cannot be
+            traversed because of insufficient permissions,
+            or the final component is an unexecutable or
+            unwritable directory, then the operation MUST
+            fail with status FEDFS_ERR_ACCESS.
           </t>
 
           <t>
@@ -1422,11 +1423,12 @@
 
           <t>
             The server MAY enforce the local permissions on
-            the path, including the final component.  If the
-            path cannot be traversed because of insufficient
-            permissions, or the final component is an
-            unexecutable or unwritable directory, then the
-            operation MAY fail with status FEDFS_ERR_ACCESS.
+            the path, including the final component.  If a
+            server wishes to report that a path cannot be
+            traversed because of insufficient permissions,
+            or the final component is an unexecutable or
+            unwritable directory, then the operation MUST
+            fail with status FEDFS_ERR_ACCESS.
           </t>
 
           <t>
@@ -1519,12 +1521,14 @@
 
           <t>
             The server MAY enforce the local permissions on
-            the path, including the final component. If the
-            path cannot be traversed because of insufficient
-            permissions, or the parent directory of the junction
-            unexecutable or unwritable directory, then the
-            operation MAY fail with status FEDFS_ERR_ACCESS.
+            the path, including the final component.  If a
+            server wishes to report that a path cannot be
+            traversed because of insufficient permissions,
+            or the final component is an unexecutable or
+            unwritable directory, then the operation MUST
+            fail with status FEDFS_ERR_ACCESS.
           </t>
+
         </section>
 
         <section title="Errors">
@@ -1591,13 +1595,13 @@
           </t>
 
           <t>
-            The server MAY enforce the local permissions
-            on the path, including the final component.  If
-            the path cannot be traversed because of
-            insufficient permissions, or the parent directory
-            of the junction is an unexecutable or unwritable
-            directory, then the operation MAY fail with status
-            FEDFS_ERR_ACCESS.
+            The server MAY enforce the local permissions on
+            the path, including the final component.  If a
+            server wishes to report that a path cannot be
+            traversed because of insufficient permissions,
+            or the final component is an unexecutable or
+            unwritable directory, then the operation MUST
+            fail with status FEDFS_ERR_ACCESS.
           </t>
 
           <t>

---

From: "Haynes, Tom" <[email-masked]>
Date: Thu, 1 Nov 2012 21:16:51 +0000

All of the documents have been updated.