Subject: [Netconf] WG Last Call for draft-ietf-netconf-rfc4742bis-05.txt

From: "Bert (IETF) Wijnen" <[email-masked]>
Date: Tue, 21 Dec 2010 13:19:29 +0100

WG participants,

This is a 2,5 week (holiday season) WG Last Call for this draft.
The idea is to only check if the agreed upon edits have been made
properly/correctly and if they do not have any unforeseen side
effects/impacts.

The WG LC ends on Jan 7th, 2011. Please carefully check/review and
send us any comments you may have BEFORE Jan 7th 2011.

Bert and Mehmet
(Mehmet is the document shepherd)

Background:

We have been discussing (on this WG mailing list) a set of changes
to the rfc4742bis draft. This to try and get proper/reasonable framing.

The WG chairs concluded we do have more or less FULL consensus on
the proposed edits. And so we asked Margaret to make those edits
to the Internet Draft. She did so and the I-D (revision 05) has
been posted.

-------- Original Message --------
Subject: 	[Netconf] I-D Action:draft-ietf-netconf-rfc4742bis-05.txt
Date: 	Mon, 20 Dec 2010 14:00:01 -0800
From: 	[email-masked]
To: 	[email-masked]
CC: 	[email-masked]

A New Internet-Draft is available from the on-line Internet-Drafts directories.
This draft is a work item of the Network Configuration Working Group of the IETF.

	Title           : Using the NETCONF Configuration Protocol over Secure Shell (SSH)
	Author(s)       : M. Wasserman, T. Goddard
	Filename        : draft-ietf-netconf-rfc4742bis-05.txt
	Pages           : 13
	Date            : 2010-12-20

This document describes a method for invoking and running the NETCONF
protocol within a Secure Shell (SSH) session as an SSH subsystem.

A URL for this Internet-Draft is:
http://www.ietf.org/internet-drafts/draft-ietf-netconf-rfc4742bis-05.txt

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

Below is the data which will enable a MIME compliant mail reader
implementation to automatically retrieve the ASCII version of the
Internet-Draft.

---

From: "Bert (IETF) Wijnen" <[email-masked]>
Date: Tue, 21 Dec 2010 13:55:25 +0100

My review comments:

4.1.  Framing protocol

    The previous version of this document defined the character sequence
    "]]<]]>" as a message separator, under the assumption that it could
  ======  I think that < should be a >, so "]]>]]>"

    not be found in well-formed XML documents.  However, this assumption
    is not correct.  It can legally appear in XML attributes, comments,
    and processing instructions.  In order to solve this problem, and at
    the same time be compatible with existing implementations, this
    document defines the following framing protocol.

    The <hello> message MUST be followed by the character sequence
    ]]>]]>.  Upon reception of the <hello> message, the receiving peer's
    SSH Transport layer conceptually passes the <hello> message to the
    Messages layer.  If the :base:1.1 capability is advertised by both
    peers, the chunked transfer mechanism (see Section 4.1.1) is used for
                                                                                =======  4.2?
    the remainder of the NETCONF session.  Otherwise, the old end-of-
    message based mechanism (see Section 4.1.2) is used.
                                                                ====== 4.3?

The sections are actually 4.2 and 4.3 in the document. So that needs
to be synced up

Bert

On 12/21/10 1:19 PM, Bert (IETF) Wijnen wrote:
> _______________________________________________
> Netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf
>

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 21 Dec 2010 14:25:42 +0100 (CET)

Hi,

I have reviewed the changes in -05 and have some comments:

In section 4, the last example seems to belong to the new section 4.3,
but it should probably be move to section 4.2, since 4.3. talks about
the old EOM, but the example shows the new framing protocol.  I.e. the
text that starts with:

   To continue the example given above, a NETCONF over SSH session to
   retrieve a set of configuration information might look like this:
   ...

should be moved.

In section 5, you removed some empty lines as suggested by Juergen,
but you forgot to modify the chunk-length number, so:

OLD:

   C:
   C: #141
   C: <?xml version="1.0" encoding="UTF-8"?>
   C: <rpc message-id="106"
   C:      xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   C:   <close-session/>
   C: </rpc>
   C: ##

   S:
   S: #140
   S: <?xml version="1.0" encoding="UTF-8"?>
   S: <rpc-reply id="106"
   S:            xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   S:   <ok/>
   S: </rpc-reply>
   S: ##

NEW:

   C:
   C: #140
   C: <?xml version="1.0" encoding="UTF-8"?>
   C: <rpc message-id="106"
   C:      xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   C:   <close-session/>
   C: </rpc>
   C: ##

   S:
   S: #139
   S: <?xml version="1.0" encoding="UTF-8"?>
   S: <rpc-reply id="106"
   S:            xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   S:   <ok/>
   S: </rpc-reply>
   S: ##

/martin

---

From: "Ersue, Mehmet (NSN - DE/Munich)" <[email-masked]>
Date: Mon, 27 Dec 2010 13:23:20 +0100

Why can't we keep the old example from -04 as it is in section 4.3 and
change in 4.3?

OLD:
   To continue the example given above, a NETCONF over SSH session to
   retrieve a set of configuration information might look like this:
NEW:
   To continue the example from Section 3.1, a NETCONF over SSH session
using the EOM 
   framing mechanism to retrieve a set of configuration information
might look like this:

Cheers,
Mehmet

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On
> Behalf Of ext Martin Bjorklund
> Sent: Tuesday, December 21, 2010 2:26 PM
> To: [email-masked]
> Cc: [email-masked]
> Subject: Re: [Netconf] WG Last Call for draft-ietf-netconf-rfc4742bis-
> 05.txt
> 
> Hi,
>

---

From: Wes Hardaker <[email-masked]>
Date: Tue, 28 Dec 2010 08:12:10 -0800

>>>>> On Tue, 21 Dec 2010 13:19:29 +0100, "Bert (IETF) Wijnen" <[email-masked]> said:

B(W> This is a 2,5 week (holiday season) WG Last Call for this draft.
B(W> The idea is to only check if the agreed upon edits have been made
B(W> properly/correctly and if they do not have any unforeseen side
B(W> effects/impacts.

Comments (take and leave what you want):

* I noted that the section reference was incorrect as well.  Specifically
  in 4.1: s/4.1.1/4.2/ and s/4.1.2/4.3/

* I'm not sure that deciding on the capability based on "base:1.1" is a
  good idea.  Not because it doesn't work, but because it's not
  future-proof.  Wouldn't it be better to say one of:

    + ":base:1.1 or later", which has the downside of version
      comparisons.

    + "any other base capability besides the ':base:1.0' one", which is
      probably easier to implement.  It would still leave problems in
      the future if we ever needed to change the framing again, but
      that's not gonna happen, right? right? right?

* I didn't follow the whole line-feed discussion, but it appears that
  the starting examples don't have a preceding line-feed to match the
  ABNF that says the chunk must *start* with a LF.  Thus I'd expect the
  example to be:

  ----- starting -----

  #4
  <rpc
  #18
  ...

  Right now the #4 starts with the standard "single line break spacing
  above it for document readability purposes".  I think the only ways
  around this would be to:

    + put in start of message markers (like the "----- starting -----"
      line above)

    + put 2 line feeds before the initial start

    + prepend the example hello message suffix

      ...                (actually insert these)
      </hello>
      #4

    + Use the C: markings like everywhere else does, possibly in
      combination with the above </hello> suggestion.

      (I think this is the easiest and cleanest)

    + ignore me and assume people get the first chunking implemented
      correctly without help.  (later chunkings are more obvious as the
      linefeed will always follow a RPC message; it's the first that I
      think is mildly confusing.

* Similarily, I don't understand this sentence:

       Note that there is no newline character after the 'rpc' end tag,
       so there is no blank line generated before the '##' line.

  Who's doing the "generation" in that sentence?  I just read it for the
  4th time while pasting it and got it.  I'd suggest the following is
  more clear (because there *is* a newline in it and it's sort of
  "generated" by the rules):

       Note that there is no newline character after the 'rpc' end tag
       in this message, so there is no otherwise-empty blank line before
       the '##' line.  The LF required by the start of the end-of-chunks
       block immediately follows the last '>' character in the message.

* for the backwards-compatibility issue, the following paragraph has a
  similar problem:

	This mechanism exists for backwards compatibility with
        implementations of previous versions of this document. It is
        only used when the remote peer does not advertise the :base:1.1
        capability.

  IE, if :base:1.1 goes away in the future, then this document needs to
  be rewritten even if no other changes are required.  Only if
  advertising the ":base:1.0" would be  a better way of checking:

  NEW:
	This mechanism exists for backwards compatibility with
        implementations of previous versions of this document. It is
        only used when the remote peer advertises only the :base:1.0
        capability.

* In section 4.3 the examples were changed away from the "]]>]]>"
  version to the chunked version, but 4.3 is actually discussing the old
  version!  Thus, the chunking needs to be reverted.

  Additionally, I wouldn't use the phrase "to continue the example given
  above" since the above is using the chunked framework.  How about "

        A NETCONF over SSH session, using the backwards-compatible
        end-of-message framing, to retrieve a set of configuration
        information might look like this:

* In section 5 (similar continuation problems)

  OLD:

     To continue the example used in previous sections, an existing	
     NETCONF subsystem session could be closed as follows:

  NEW:

     To continue the example used in section 4.2, an existing	
     NETCONF subsystem session could be closed as follows:

* This is very late (IE, too late), but one thought that occurred to me
  is that maybe the framing should have used direct XML comments to
  store the framing data to keep it "XMLish".  IE:

    #4

  could have been (with *VERY* strict encoding):

    <!-- #4 -->

  But, as I said, this is late and it doesn't seem like many people
  actually cared about the #4 itself being "not XMLish".

-- 
Wes Hardaker
Cobham Analytic Solutions

---

From: "t.petch" <[email-masked]>
Date: Tue, 28 Dec 2010 17:04:38 +0100

Wes

I largely agree, but do object to 'newline' since the ABNF uses
exclusively LF so

OLD
newline
NEW
Line Feed

And I think that the only way to make chunking clear is to make the Line Feed
visible
so I have edited 4.2 to look like (and will keep this whatever the WG decides)

"   As an example, the message:

       <rpc message-id="102"
            xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
         <close-session/>
       </rpc>

   could be encoded as, using } as a visible representation of the Line Feed
character:

       }
       #4}
       <rpc}
       #18}
        message-id="102"}                 <!--  17+LF -->

       }
       #79}
            xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">}  <!-- 53+LF -->
         <close-session/>}                   <!--    18+LF -->
       </rpc>}                                    <!--      6 -->
       ##}

Note that } represents Line Feed, as per the ABNF above, and not
Carriage Return Line Feed, even though it is the latter sequence
that is used to terminate lines in the generation of this memo.
The XML comments are included to make the arithmetic clear
and neither they, nor the intervening spaces, appear on the wire.

Tom Petch