Subject: last call comments on the mapping documents

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 20 Jan 2005 00:27:29 +0100

I finally managed to write down my last call review comments for 
the NETCONF mappings documents.

The documents seem to be of different quality and it looks like
almost nobody is reading them because there are rather obvious things
to report (at least in some of the mapping documents) and I have not
seen anything on the WG mailing list. Perhaps the WG has lost interest 
in some of these documents after the decision to require SSH had been 
taken? I guess the chair will have a hard time to determine support 
for these documents to going forward if there is just silence...

draft-ietf-netconf-ssh-02.txt:

1) The abstracts says:

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

   I suggest to remove the word "simple" as it does not add value and
   the IETF has some history to label rather complex protocols as
   "simple".

2) I think sections 2, 3, and 4 stress too much the interactive start
   of the ssh subsystem. I would prefer that the text really just
   explains how NETCONF runs over ssh. In other words, I suggest to
   show the capability exchange currently shown in section 2 in
   section 3 where it is discussed. All the material specific to
   typical ssh clients should IMHO go into section 5.

   If people prefer to keep the command line to start an ssh
   conversation in the document, then it should at least be changed
   to accomodate the netconf specific port since I understand that
   NETCONF over ssh uses a new well-known port to be assigned by
   IANA.

3) I personally prefer the more traditional notation for message
   exchanges where lines are prefixed with C: and S:. So I would write
   down the capabilities exchange in the following notation:

   S: <?xml version="1.0" encoding="UTF-8"?>
   S: <hello>
   S:   <capabilities>
   S:    <capability>urn:ietf:params:xml:ns:netconf:base:1.0</capability>
   S:    <capability>urn:ietf:params:xml:ns:netconf:base:1.0#lock</capability>
   S:   </capabilities>
   S: </hello>
   S: ]]>]]>

   C: <?xml version="1.0" encoding="UTF-8"?>
   C: <hello>
   C:   <capabilities>
   C:    <capability>urn:ietf:params:xml:ns:netconf:base:1.0</capability>
   C:   </capabilities>
   C: </hello>
   C: ]]>]]>

   I think this format is easier to read and it works for all the
   mapping documents in the same way. (But if the editors feel
   strongly about the XML-stylish way of writing examples down, I am
   not going to make a big deal out of this.)

4) Section 2.1: replace "user's expect script" with "user's script".

5) Section 2.1: replace $lt; with @lt; in the XML source of the ID.

6) Section 4: some typos in the following text:

    An agend will processed RPC messages from the manager in the order in
    which the are received.  When the agent processes a <close-session>
    command is, the agent shall respond, terminate the SSH session, and
    close the TCP connection.

   Replace with:

    An agent will process RPC messages from the manager in the order in
    which the are received.  When the agent processes a <close-session>
    operation, the agent shall respond, terminate the SSH session, and
    close the TCP connection.

7) Section 4:

    <!-- The NETCONF program exits, returning the user to the SSH prompt.
    The user then types 'exit' to exit the SSH shell and return to the
    local shell. -->

    [user@server]$ exit
    [user@client]$

   I don't think that this part of the example is really needed.

8) Section 5:

    The techniques described in this document could be used to access the
    NETCONF protocol over the SSH shell session, or from other shell
    types such as a console session or a Telnet [RFC0854] connection.

   I do not really understand what this sentence tries to tell me.
   Why are "other shell types" or "telnet" relevent in this document?
   This is the NETCONF over SSH mapping, no more no less.

9) Section 6:

   I think some nouns in the last sentence should be put into plural
   form, i.e. configurations and subsystems.

Despite the notes listed above (and which can be easily addressed), I
think this document looks very reasonable.

draft-ietf-netconf-beep-03.txt:

a) This document uses the "application protocol" terminology which I
   dislike (see also my comments on the NETCONF protocol definition).

b) Section 1.1:

            This "bidirectionality" allows for either side to play
    the role of the manager with no protocol changes.  Either side can
    open a channel. Either size could initiate an RPC.

   I think the text confuses BEEP's capability to initiate a session
   from either side with the manager/agent roles actually being used.
   Perhaps the text simply wanted to say:

            This "bidirectionality" allows for either side to 
    open a channel.

   The rationale here is that NETCONF clearly assumes manager/agent
   roles and it is rather clear who initiates NETCONF transactions.

c) Section 1.1:

    This is
    particularly important to support operational models that involve
    small devices connecting to a manager, and those devices that must
    reverse the management connection in the face of firewalls and NATs.

   I suggest to remove the work "small" as it does not really add
   value - I might actually have a big device that prefers to take the
   initiative (and how decides what small is anyway?).

d) Section 1.1:

    The SASL profile used by BEEP allows for a simple and direct mapping
    to the existing security model for CLI, while TLS provides a strong
    well tested encryption mechanism with either server or server and
    client-side authentication.

   I learned in the ISMS WG that SASL over TLS is not necessarily
   secure. Has beep fixed this problem or do we better explain the
   issue here and/or in the security considerations section?

e) Section 2.1: Is the "should" in this section actually a SHOULD?

f) Section 2.2:

    The manager now establishes an NETCONF a new channel.

   Replace with:

    The manager now establishes a new channel.

g) Section 2.3:

   I suggest to write NETCONF XML elements exactly as defined in the
   NETCONF specification. Thus, <RPC> should be written in lowercase
   as <rpc>.

h) Section 2.3:

   There is an odd line break in the last sentence of this section.

i) Section 2.5:

    There are two commands in the BEEP profile.  <rpc> and <rpc-reply>.

   I am not a BEEP expert, but I am wondering how the <hello> messages
   are mapped to BEEP. Should the DTD not specify something for them?
   Note that I did not check the DTD as I am not a BEEP expert. Perhaps 
   /mtr should take a look at it. Note that there are some minor
   indentation oddities in the DTD part.

j) What is really missing in the whole document is an example. Ideally,
   one would simply use the example contained in the ssh mapping 
   document and show the same example in the BEEP mapping. This would
   add quite much clarity and allows people to better understand how
   NETCONF over BEEP messages will actually look like on the wire.

k) Section 4:

   I think it is important to tell IANA precisely that a port number
   for NETCONF over BEEP/TCP is requested. Or do we assume that all
   NETCONF over xxxx/TCP mappings share the same port number?

In summary, I think the BEEP mapping document still needs some work.
Especially an example is missing in my view and the DTD stuff probably
needs a bit more work and proof checking.

draft-ietf-netconf-soap-03.txt:

!) Abstract:

        Herein, we describe SOAP over HTTP and SOAP over
    BEEP bindings that yield application protocols sufficient for
    NETCONF.

   I suggest to reduce this to the following:

        Herein, we describe SOAP over HTTP and SOAP over
    BEEP bindings for NETCONF.

@) Introduction:

    In general, SOAP is a natural application protocol for NETCONF,
    essentially because of the remote procedure call character of both.

   This is plain wrong since SOAP is not an RPC protocol. To quote
   from the W3C SOAP 1.2 primer section 1.1:

       SOAP is fundamentally a stateless, one-way message exchange
       paradigm, but applications can create more complex interaction
       patterns (e.g., request/response, request/multiple responses,
       etc.) by combining such one-way exchanges with features
       provided by an underlying protocol and/or application-specific
       information.

   Note that section 2 of the mapping document more precisely says
   that "SOAP is fundamentally an XML messaging scheme" which I can
   live with.

#) Introduction:

    In some sense, the most important part of the document is the
    brief WSDL document presented in the Appendix.

   I agree with this statement and hence I propose to move the WSDL
   definition from the appendix into the main document (like we have
   the DTD definition for the BEEP mapping in the main document).

$) The writing style in some places seems more appropriate for a white
   paper instead of a technical specifications. I think the document
   should not try to "sell" the mapping but rather try to explain
   concisely how the mapping works.

%) Section 2.1:

   This section talks about "the great innovation found with many
   XML-based definition languages" but it leaves it totally unclear
   whether it tries to tell IANA to put schema and/or WSDL definitions
   into a prominent place or not or whether this is just a discussion
   of a nice idea which can be safely ignored.

^) Section 2.4:

   This section discusses several ways to deal with HTTP caches when
   one uses NETCONF over SOAP over HTTP. It does not say which one
   is the suggested mechanism to actually deploy. From a specification,
   I would expect that it gives clear guidance to implementors. So
   SHOULD/MUST HTTP cache control mechanisms be used for NETCONF over
   SOAP over HTTP?

   In a similar vein, the discussion on port numbers explains how
   flexible WSDL is but it does not clearly say that a special
   well-know port should be used nor are there any IANA considerations
   to this effect.

&) Section 2.5:

   Like in the previous section, there is quite some discussion about
   how to use persistent connections and perhaps HTTP chunking with
   SOAP over HTTP. I again miss a clear conclusion and concrete hints
   for implementors what they should/must do.

*) Section 2.7.1 uses the old term "substrate" - whatever we end up
   using, we should try to be consistent in all documents.

:) Section 7.3 explains how <rpc-error> elements are mapped to SOAP
   faults. Note that there is a pending issue on the protocol document
   whether it allows multiple <rpc-error> responses or even embedded
   <rpc-error> elements. Depending on the resolution of this issue in
   the protocol specification, this mapping may or may not work.

;) The example shown in section 7.3 does not match the current NETCONF
   protocol specification.

') Section 3.3 says the following:

    Capabilities exchange, if defined through a NETCONF RPC operation,
    can easily be accommodated in the SOAP binding.

   This is plain wrong. See section 8.1 in the NETCONF specification.
   Mapping the <hello> capabilities exchange to SOAP/HTTP might
   actually not be trivial.

,) Section 3.5 probably needs to discuss the <close-session> operation
   and how it maps to SOAP/HTTP and SOAP/BEEP.

.) I like the example in section 3.6. Like I said before, I would
   prefer a notation using C: and S: for all the mapping documents.

-) The examples shown in section 3.6 and not consistent with the
   current definition of the NETCONF protocol. The namespace URIs
   have changed and the <format> element has been removed from
   <get-config>. Also the response does not seem to be inline
   with the current protocol definition.

+) The example shown in section 3.6 does not use the Content-Length
   HTTP header so the end of the message must be indicated by closing
   the connection. This is probably not a good example since section
   2.5 explains to some detail why you want to use persistent
   connections.

?) Section 4.1 talks about security options and lists a couple of them
   without saying which must be implemented. Without a strong
   recommendation, I fail to see how one can reach interoperability.

=) As noted before, the document needs to have an IANA considerations
   section.

Summary: The SOAP/HTTP and SOAP/BEEP mapping document has not been 
updated for a while and misses necessary recommendation what to 
implement in order to achieve interoperability. 

/js

-- 
Juergen Schoenwaelder		    International University Bremen
<http://www.eecs.iu-bremen.de/>	    P.O. Box 750 561, 28725 Bremen, Germany

--
to unsubscribe send a message to [email-masked] with
the word 'unsubscribe' in a single line as the message text body.
archive: <http://ops.ietf.org/lists/netconf/>

---

From: Wes Hardaker <[email-masked]>
Date: Fri, 21 Jan 2005 14:19:15 -0800

Juergen> I finally managed to write down my last call review comments
Juergen> for the NETCONF mappings documents.

Can we get an official chair response on comments about the documents
which are now after last call?  Being beyond last call means that
comments are supposed to be ignored.  But if this is not the case, I'd
like to write some down as well.
-- 
"In the bathtub of history the truth is harder to hold than the soap,
 and much more difficult to find."  -- Terry Pratchett

---

From: Andy Bierman <[email-masked]>
Date: Fri, 21 Jan 2005 14:43:00 -0800

>like to write some down as well.

I don't think we should ignore relevant comments.
They will likely come up during IETF Last Call
if they don't get addressed now.

Andy

---

From: "Randy Presuhn" <[email-masked]>
Date: Fri, 21 Jan 2005 15:25:21 -0800

Hi -

> From: "Wes Hardaker" <[email-masked]>
> To: <[email-masked]>
> Sent: Friday, January 21, 2005 2:19 PM
> Subject: Re: last call comments on the mapping documents
...
> like to write some down as well.
...

If something is truly broken, beyond beyond last call would be a rather
poor reason for failing to fix it.

Randy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 22 Jan 2005 08:33:00 +0100

> like to write some down as well.

Any wrote on Mon, 13 Dec 2004 20:13:09 -0800:

: The first WG Last Call for the NETCONF Configuration Protocol
: document is now concluded.  I'd like to thank the numerous WG
: members who reviewed the document and sent comments to the mailing
: list.  The WGLC for the application mappings documents will
: remain open a bit longer since they have not been widely reviewed
: yet.

I have not seen an official announcement that the WGLC for the 
mappings document has been closed. You might have noticed that
my comments on the protocol document came in just before the
deadline and I actually removed the the mapping documents from
my agenda. It was the message above which put the review of 
the mapping documents back on my agenda again.

If we talk about formal things here, then I would be more concerned 
about the lack of comments rather the timing of the comments. As you 
know, documents going to the IESG need to demonstrate a significant 
level of community interest. So I can only encourage people to provide 
feedback if they want all these mapping documents to move forward.

/js