Subject: [nfsv4] spec language fixes

From: "J. Bruce Fields" <[email-masked]>
Date: Tue, 15 Jan 2008 15:58:51 -0500

I've been slowly reading through the spec and fixing up minor language
problems as I go just to keep myself entertained....  So here's a diff
below with some stuff I've found so far.

There should be no changes in meaning anywhere, just uncontraversial
fixes for style and grammar problems.  The one large-ish change is to
the  "Put Filehandle Operation + LOOKUP" section, where it seemed
possible to get across the same idea more clearly with dramatically less
text.  (More detailed justification here:

	http://git.linux-nfs.org/?p=bfields/nfsv41.git;a=commit;h=a24788454e236cfcd7cff8aa9c78dbf52361d2c5

And all changes are browsable individually with some explanation where
necessary, from:

	http://git.linux-nfs.org/?p=bfields/nfsv41.git;a=shortlog;h=proofreading

)

If you'd rather have this in some other form, let me know.

--b.

--- 

 nfsv41_middle_caching.xml             |    2 +-
 nfsv41_middle_core_infrastructure.xml |  151 +++++++++++++--------------------
 nfsv41_middle_introduction.xml        |    9 +-
 nfsv41_middle_state_mgmt.xml          |    2 +-
 4 files changed, 64 insertions(+), 100 deletions(-)

diff --git a/nfsv41_middle_caching.xml b/nfsv41_middle_caching.xml
index 0ddca03..6a2b546 100755
--- a/nfsv41_middle_caching.xml
+++ b/nfsv41_middle_caching.xml
@@ -648,7 +648,7 @@
       delegations.
     </t>
     <t>
-      When a client has a read open delegation, it is assured that no
+      When a client has a read open delegation, it is assured that
       neither the contents, nor the attributes, nor the names of any
       links to the file will change without its knowledge, so long as the
       delegation is held.  When a client has a write open delegation, it
diff --git a/nfsv41_middle_core_infrastructure.xml b/nfsv41_middle_core_infrastructure.xml
index ddc4eb8..dce9ed5 100755
--- a/nfsv41_middle_core_infrastructure.xml
+++ b/nfsv41_middle_core_infrastructure.xml
@@ -274,9 +274,9 @@
    with its own set of callback operations.
  </t>
  <t>
-   Addition of new server and callback operation within the 
+   Addition of new server and callback operations within the 
    COMPOUND and CB_COMPOUND request
-   framework provide means of extending the protocol in
+   framework provides a means of extending the protocol in
    subsequent minor versions.
  </t>
  <t>
@@ -298,7 +298,7 @@
   <t>
     Each distinct client instance is represented
     by a client ID.  A client ID is a 64-bit identifier
-    represents a specific client at a given time.
+    representing a specific client at a given time.
     The client ID is changed whenever the client re-initializes,
     and may change when the server re-initializes.
     Client IDs are used to support lock identification
@@ -374,7 +374,7 @@
         leased state abruptly and unexpectedly canceled.
       </t>
       <t> 
-        The string should be selected so the subsequent incarnations
+        The string should be selected so that subsequent incarnations
         (e.g. restarts) of the same client cause the client to present 
         the same string. The implementor 
         is cautioned from an approach that requires the string to 
@@ -384,12 +384,12 @@
       </t>
       <t>
         The string should be the same for each server network address that
-        the client accesses,
-        (note: the precise opposite was advised in the NFSv4.0
-        specification <xref target="RFC3530" />). 
+        the client accesses.
         This way, if a server has multiple interfaces, the client
         can trunk traffic over multiple network paths
         as described in <xref target="Trunking" />.
+        (Note: the precise opposite was advised in the NFSv4.0
+        specification <xref target="RFC3530" />). 
       </t>
       <t>
         The algorithm for generating the string should not
@@ -398,7 +398,7 @@
         is using statically assigned network addresses.
         This includes changes between client incarnations
         and even changes while the client is still running
-        in its current incarnation.  This means that if the
+        in its current incarnation.  If the
         client includes just the client's network address
         in the co_ownerid string, there is a real risk,
         with dynamic address assignment, that after the
@@ -438,8 +438,8 @@
           </t>
           <t>
             A true random number. However since this number ought to be the same
-            between client incarnations, this shares the same problem as that of
-            the using the timestamp of the software installation.
+            between client incarnations.  This shares the same problem as that of
+            using the timestamp of the software installation.
           </t>
         </list>
       </t>
@@ -488,14 +488,12 @@
     client will re-establish communication using the
     existing session after the restart.  This session
     will be associated with the existing client ID but
-    no new operations can be performed on it.  Operations
-    that were previously sent but for which no reply had
-    been received may be re-sent to determine whether they
-    had been performed before the server reboot.  The 
-    session in this situation is referred to as "dead" and
-    when an operation that has not been performed previously,
-    i.e. it is not satisfied from the replay cache, the
-    error NFS4ERR_DEADSESSION is returned.  In this situation,
+    may only be used to retransmit operations that the
+    client previously transmitted and did not see replies
+    to.  Operations that the server previously performed
+    will be replied to using the reply cache, while
+    NFS4ERR_DEADSESSION will be returned to others.
+    Such a session is referred to as "dead".  In this situation,
     in order to perform new operations, the client must 
     establish a new session.  If an attempt is made to 
     establish this new session with the existing client ID,
@@ -579,7 +577,7 @@
    <section title="Resolving Client Owner Conflicts" anchor="cowner_conflicts">
    <t>
      When the server gets an EXCHANGE_ID for a client owner that
-     currently has no state, or if it has state, but the lease has expired,
+     currently has no state, or that has state, but the lease has expired,
      the server MUST allow the
      EXCHANGE_ID, and confirm the new client ID if followed by the
      appropriate CREATE_SESSION.
@@ -618,7 +616,7 @@
      </t>
      <t>
        The client ID was established with SP4_SSV
-       protection.  Because the SSV might not be persisted
+       protection.  Because the SSV might not persist
        across client and server restart, and because
        the first time a client sends EXCHANGE_ID to
        a server it does not have an SSV, the client
@@ -640,7 +638,7 @@
      If the server accepts the principal and
      co_ownerid as matching that which created the client
      ID, it deletes state (upon a
-     a CREATE_SESSION confirming the client id) if
+     CREATE_SESSION confirming the client id) if
      the co_verifier in the EXCHANGE_ID differs from
      the co_verifier used when the client ID was created.
      If the co_verifier values are the same, then the client is
@@ -805,57 +803,25 @@
    <t>
     In this situation, the client is potentially crossing
     a security policy boundary, and the set of security tuples
-    the parent directory supports differ from those of
+    the parent directory supports may differ from those of
     the child.
-    The server implementation may decide whether to impose
-    any restrictions on security policy administration.
-    There are at least three approaches (sec_policy_child is
-    the tuple set of the child export, sec_policy_parent is
-    that of the parent).
-   </t>
-   <t>
-   <list style="hanging">
-   <t hangText="  a)">
-    sec_policy_child &lt;= sec_policy_parent (&lt;= for subset).
-    This means that the set of security tuples specified on the
-    security policy of a child directory is always a subset
-    of that of its parent directory.
-   </t>
-   <t hangText="  b)">
-    sec_policy_child ^ sec_policy_parent != {} (^ for intersection, {} for the empty set). This means that the security tuples specified on the security
-    policy of a child directory always has a non empty intersection
-    with that of the parent.
-   </t>
-   <t hangText="  c)">
-    sec_policy_child ^ sec_policy_parent == {}. This means that the
-    set of tuples specified on the security policy of a child directory
-    may not intersect with that of the parent. In other words, there
-    are no restrictions on how the system administrator may
-    set up these tuples.
-   </t>
-   </list>
    </t>
    <t>
-    For a server to support approach (b) (when client
-    chooses a flavor that is not a member of
-    sec_policy_parent) and (c), the put filehandle operation must NOT return
-    NFS4ERR_WRONGSEC when there is a security tuple mismatch.
-    Instead, it should be returned from the LOOKUP (or OPEN
-    by component name) that follows.
+    The server implementation may reduce the likelihood of such problems
+    by requiring that the parent permit all the security tuples
+    permitted on the child.
    </t>
    <t>
-    Since the above guideline does not contradict approach
-    (a), it should be followed in general. Even if approach
-    (a) is implemented, it is possible for the security
-    tuple used to be acceptable for the target of LOOKUP
-    but not for the filehandles used in the put filehandle operation. The 
-    put filehandle operation
-    could be a PUTROOTFH or PUTPUBFH, where the
-    client cannot know the security tuples for the root
-    or public filehandle. Or the security policy for the
-    filehandle used by the put filehandle operation
-    could have changed since the
-    time the filehandle was obtained.
+    However, even if it restricts security policy adminstration in such
+    a way, it is still possible for the security tuple used to be
+    acceptable for the target of LOOKUP but not for the filehandles used
+    in the put filehandle operation.  For example, if the operation is
+    PUTROOTFH or PUTPUBFH, and if the server does not support
+    SECINFO_NO_NAME, the client may have no way short of exhaustive
+    trial-and-error to discover the correct security tuple for the root
+    or public filehandle.  Or the security policy
+    for the filehandle operation could have changed since the time
+    the filehandle was obtained.
    </t>
    <t>
     Therefore, an NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC
@@ -869,18 +835,18 @@
    <t>
     Since SECINFO only works its way down, there is no way LOOKUPP can
     return NFS4ERR_WRONGSEC without SECINFO_NO_NAME. SECINFO_NO_NAME
-    solves this send because via style
-    SECINFO_STYLE4_PARENT, it works in the opposite direction as SECINFO.
-    As with <xref target="PUTFH + LOOKUP" />, the put filehandle operation
-    must not return NFS4ERR_WRONGSEC
-    whenever it is followed by LOOKUPP.
+    solves this issue via style
+    SECINFO_STYLE4_PARENT, which works in the opposite direction as SECINFO.
+    As with <xref target="PUTFH + LOOKUP" />, a put filehandle operation
+    that is followed by a LOOKUPP
+    must not return NFS4ERR_WRONGSEC.
     If the server does not support SECINFO_NO_NAME, the client's
     only recourse is to send the put filehandle operation,
     LOOKUPP, GETFH sequence
     of operations with every security tuple it supports.
    </t>
    <t>
-    Regardless whether SECINFO_NO_NAME is supported, an
+    Regardless of whether SECINFO_NO_NAME is supported, an
     NFSv4.1 server  MUST NOT return NFS4ERR_WRONGSEC in
     response to a put filehandle operation if the
     operation is immediately followed by a LOOKUPP.
@@ -894,9 +860,9 @@
     a strong security tuple when querying a server to
     determine a file object's permitted security tuples.
     The security tuple chosen by the client does not have
-    to be included in the tuple list of the security policy
-    of the either parent directory indicated in the put filehandle operation, or
-    the child file object indicated in SECINFO (or any parent directory
+    to be included in the permitted tuples either of
+    the parent directory indicated in the put filehandle operation, or
+    of the child file object indicated in SECINFO (or any parent directory
     indicated in SECINFO_NO_NAME). Of course
     the server has to be configured for whatever security
     tuple the client selects, otherwise the request will
@@ -913,8 +879,8 @@
    </t>
    <t>
     The NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC to a
-    put filehandle operation whenever
-    it is immediately followed by SECINFO or SECINFO_NO_NAME.
+    put filehandle operation that
+    is immediately followed by SECINFO or SECINFO_NO_NAME.
     The NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC from SECINFO or
     SECINFO_NO_NAME.
    </t>
@@ -960,13 +926,13 @@
      error to return when security tuple of the request is not allowed
      for the operation that uses the current filehandle.
      For example, suppose a client sends a COMPOUND procedure
-     containing this series of operations SEQUENCE, PUTFH,
+     containing the series of operations SEQUENCE, PUTFH,
      SECINFO_NONAME, READ, and suppose the security tuple
      used does not match that required for the target
-     file. By rule (see <xref target="PUTFH+SECINFO"/>),
+     file. By the rule of <xref target="PUTFH+SECINFO"/>,
      neither PUTFH nor SECINFO_NO_NAME can
-     return NFS4ERR_WRONGSEC. By rule (see <xref
-     target="PUTFH+AnythingElse"/>), READ cannot return
+     return NFS4ERR_WRONGSEC. By the rule of <xref
+     target="PUTFH+AnythingElse"/>, READ cannot return
      NFS4ERR_WRONGSEC. The issue is resolved by the fact
      that SECINFO and SECINFO_NO_NAME consume the current
      filehandle. This leaves no current filehandle for
@@ -1161,7 +1127,7 @@
    Principals with appropriate access rights can modify the
    authorization on a file object via the SETATTR
    (<xref target="OP_SETATTR" />) operation.  Attributes that affect
-   access rights include: mode owner owner_group, acl, dacl, and
+   access rights include: mode, owner, owner_group, acl, dacl, and
    sacl. See <xref target="file_attributes" />.
    </t>
   </section> <!-- Authorization -->
@@ -1227,7 +1193,7 @@
   <t>
    It is permissible for a connectionless transport to
    be used under NFSv4.1, however reliable and in-order
-   delivery of data by the connectionless transport are
+   delivery of data by the connectionless transport is
    still required. NFSv4.1 assumes that a client transport
    address and server transport address used to send data
    over a transport together constitute a connection,
@@ -1587,7 +1553,7 @@
     that transported the CREATE_SESSION request is
     automatically associated with the fore channel, and
     optionally the backchannel. If the client specifies no
-    state protection (<xref target="OP_EXCHANGE_ID" />).
+    state protection (<xref target="OP_EXCHANGE_ID" />)
     when the session is created, then when SEQUENCE is
     transmitted on a different connection, the connection
     is automatically associated with the fore channel of
@@ -1782,7 +1748,7 @@
       fails.  Even if the server mistakenly or maliciously
       accepts the connection association attempt, the
       RPCSEC_GSS verifier it computes in the response
-      will not be verified by the client, the client will
+      will not be verified by the client, so the client will
       know it cannot use the connection for trunking the
       specified session.  <vspace blankLines='1' /> If the
       client specified SP4_MACH_CRED state protection, the
@@ -1826,7 +1792,7 @@
       claim by issuing a CREATE_SESSION to the second
       destination address, protected with RPCSEC_GSS integrity
       using an RPCSEC_GSS handle returned by the second
-      EXCHANGE_ID. If the server accept the CREATE_SESSION
+      EXCHANGE_ID. If the server accepts the CREATE_SESSION
       request, and if the client verifies the RPCSEC_GSS
       verifier and integrity codes, then the client has
       proof the second server knows the SSV, and thus
@@ -1848,13 +1814,12 @@
    Each COMPOUND or CB_COMPOUND request that is sent
    with a leading SEQUENCE or CB_SEQUENCE operation MUST
    be executed by the receiver exactly once. This requirement
-   is regardless whether the request is sent with reply
+   holds regardless of whether the request is sent with reply
    caching specified (see <xref target="optional_reply_caching" />).
    The requirement holds even if the requester is issuing the
    request over a session created between a pNFS data client
-   and pNFS data server. The rationale for this requirement
-   is understood by categorizing requests into three
-   classifications:
+   and pNFS data server.  To help understand this requirement, divide
+   requests into three categories:
    <list style='symbols'>
    <t>
     Nonidempotent requests.
@@ -1878,7 +1843,7 @@
     a COMPOUND request containing a WRITE operation.
     Repeated execution of the same WRITE
     has the same effect as execution of that write once.
-    Nevertheless, putting enforcing EOS for WRITEs and other idempotent
+    Nevertheless, enforcing EOS for WRITEs and other idempotent
     modifying requests is necessary
     to avoid data corruption.
    </t>
@@ -1972,7 +1937,7 @@
     </t>
     <t>
      A slot contains a sequence id and the cached reply corresponding to
-     the request send with that sequence id. The sequence id is a 32
+     the request sent with that sequence id. The sequence id is a 32
      bit unsigned value, and is therefore in the range 0..0xFFFFFFFF (2^32 - 1).
      The first time a slot is used, the requester must specify
      a sequence id of one (1) (<xref target="OP_CREATE_SESSION" />).
diff --git a/nfsv41_middle_introduction.xml b/nfsv41_middle_introduction.xml
index de6d5b7..3e939a4 100755
--- a/nfsv41_middle_introduction.xml
+++ b/nfsv41_middle_introduction.xml
@@ -70,9 +70,8 @@
       defined already by NFSv3
       <xref target="RFC1813" />.  It retains
       the essential characteristics of previous versions: design for easy
-      recovery, independent of transport protocols, operating systems and
-      file systems, simplicity, and good performance.  NFSv4 has the following goals:
-
+      recovery; independence of transport protocols, operating systems and
+      file systems; simplicity; and good performance.  NFSv4 has the following goals:
       <list style='symbols'>
         <t>
           Improved access and good performance on the Internet.
@@ -295,7 +294,7 @@
         </t>
         <t>
           These attributes may be used together with the concept
-          of absent file system which provide specifications
+          of absent file systems, which provide specifications
           for additional locations but no actual file system 
           content.  This allows a number of important facilities:
           <list style="symbols">
@@ -447,7 +446,7 @@
           the same server (the server namespace is the
           same via each connection), and assumes and
           lock state is sharable across both connections. When each peer
-          both the same major and minor identifier, the client assumes
+          has both the same major and minor identifier, the client assumes
           each connection might be associatable with the same session.
         </t>
         <t hangText="Stable Storage">
diff --git a/nfsv41_middle_state_mgmt.xml b/nfsv41_middle_state_mgmt.xml
index e97e801..da544f2 100755
--- a/nfsv41_middle_state_mgmt.xml
+++ b/nfsv41_middle_state_mgmt.xml
@@ -764,7 +764,7 @@
         When a SEQUENCE (most common) or other operation on a
         persistent session returns NFS4ERR_DEADSESSION, this indicates
         that a session is no longer usable for new, i.e. not satisfied
-        from the replay cache, operations.  Once all pending operations
+        from the reply cache, operations.  Once all pending operations
         are determined to be either performed before the retry or not
         performed, the client sends a CREATE_SESSION request with the
 	client ID to re-establish the session. If

_______________________________________________
nfsv4 mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/nfsv4

---

From: Mike Eisler <[email-masked]>
Date: Tue, 15 Jan 2008 21:29:19 -0800 (PST)

I've checked in most of your changes, with the big exception being:

> The one large-ish change is to

The text that was there was arrived at several years ago when folks
were having issues interpreting the SECINFO spec. What is there seems
to remove all ambiguity. I'm fearful a dramatic cut in volume will lead

to more problems.

Thanks for the updates.

> -    sec_policy_child ^ sec_policy_parent != {} (^ for intersection,
> {} for the empty set). This means that the security tuples specified
> on the security

---

From: "J. Bruce Fields" <[email-masked]>
Date: Wed, 16 Jan 2008 19:02:54 -0500

On Tue, Jan 15, 2008 at 09:29:19PM -0800, Mike Eisler wrote:
> I've checked in most of your changes,

Thanks!

> with the big exception being:
> 

OK.  I'll take another look and see if I can at least split out the
obvious fixes.

--b.