[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
last call comments on the mapping documents
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 netconf-request@ops.ietf.org with
the word 'unsubscribe' in a single line as the message text body.
archive: <http://ops.ietf.org/lists/netconf/>