Subject: Re: [Gen-art] LC Review Assignment: draft-ietf-netconf-prot-10

From: Andy Bierman <[email-masked]>
Date: Mon, 09 Jan 2006 08:30:27 -0800

Joel M. Halpern wrote:

> I was selected as General Area Review Team reviewer for this 
> specification
> (for background on Gen-ART, please see
> http://www.alvestrand.no/ietf/gen/art/gen-art-FAQ.html).

Thanks Joel.   These are really good comments.
Now we will try to understand the edits.
(Maybe I'll work with Rob offline on most of them, which might
involve moving and/or clarifying some text.)

There is one significant issue that jumps out at me.
Does the :startup capability imply that the <startup> config
can be the target of an <edit-config> operation? 

I think your comment is referring to this snippet from the <edit-config>
text describing the target parameter:

   target:

         Configuration datastore being edited, such as <running/> or
         <candidate/>.

Unfortunately, the set of operations is not consistent across all 
configurations.
This reflects operational reality more than anything else.

It should be made clear (in the #startup capability section) that
if :startup is advertised:
  -  <edit-config> and <delete-config> MAY be supported
  -  <get-config>, <copy-config>, <lock> and <unlock> MUST be supported
  -  <validate> MUST be supported (if :validate is also advertised)

thanks,
Andy

>
> This document is nearly ready for publication as a proposed standard.  
> It has some issues that should be considered.
>
> moderate:
>     I can not find an actual description of the content of a <config> 
> element.  I am not refering to the question of what data elements are 
> to be used (that is for the data model I believe.)  Rather, I am 
> referring to the absence of a description of how the <config> element 
> actually selects an element to configure, and what attributes are 
> legal on config elements.  Reading between the lines, it appears that 
> <config> parallels <filter> except that it can have the operation 
> attribute, which is not matched with the underlying data model.  And 
> for merge / replace operations <config> seems to assume that the 
> engine has a keying model which will allow it to determine which 
> elements are keys and which elements are replacement values to go with 
> the keys.  Such knowledge is not unreasoanble.  But it does not appear 
> to be stated anywhere.
>
>
> minor:
>     I believe the more recent XML RFCs have deprecated the distinction 
> between URI and URN.   If so, the second sentence of 3.1 about "MUST 
> be URIs, and SHOULD be URNs" may not be particularly helpful.
>
>    The NETCONF document sometimes uses the phrase "application 
> protocol" for the transport protocol (SSH, TLS, BEEP, ...)  This is 
> used for example in 2.1 and 2.2.  In other places (including 4.3) 
> "application level" is used to mean the application running over the 
> NETCONF protocol.  There, "transport" is used for the supporting 
> protocol.
>
>    The filtering description starts using a path (file or XPATH like) 
> terminology without providing any explanation of what "path" exactly 
> means.  6.1 talks about the conceptual tree.  While 6.2.2 talks about 
> the "absolute path".  Some descriptive text would be helpful.  (I am 
> guessing this is a reference to the applicable portion of the XPATH 
> terminology, but the text does not seem to say.)
>
>    <config-text> is introduced in the example of getting a 
> configuration in a given format.  <config-text> appears to be used  to 
> hold the requisite xmlns parameter.  I suspect that the intent is that 
> the xmlns parameter can be put on whatever the known top level element 
> (document element) is of the configuration.  If so, a little more 
> wording before the example would be helpful.  (If something else is 
> intended, then significantly more wording is required.)
>
>     The description of <edit-config> at the beginning of 7.2 states 
> that this operation "allows the new configuration to be expressing 
> several ways, such as using a local file, a remote file, or inline."  
> However, there is no explanation in the parameters or related text of 
> how one would specify a local file or a remote file.  That should not 
> be left purely to the schema.  (I note that there is text about this 
> in the <copy-config> section 7.3.  Either similar text should be in 
> 7.2, or the wording in the intro of 7.2 should be removed.)
>
>    It probably would be helpful to explain in 8.3.4.1 the difference 
> between a <copy-config> from candidate to running as compared to a 
> <commit> operation.  A simple forward reference to the Confirmed 
> Commit capability may suffice.
>
>    It is odd (not wrong, just odd) that in describing :candidate, the 
> ability to use candidate as a source or target is described in the 
> text, not in the modifications to operations section.  But the 
> modifications to lock and unlock, which use the <target> element are 
> described in the modifications section (6.2.5.1.)
>
>     It is unclear whether the support of the :startup capabilities 
> implies the ability to perform an <edit-confi> on the <startup/> 
> configuration.  As written, the text implies that such is not 
> permitted.  However, it would be better if this were stated 
> explicitly.  (And if this is not the intent, then more words are 
> clearly required.
>
>    In section 8.8 describing the :url capability, there is reference 
> to various protocols being supported.  I suspect that what is intended 
> is actually support for different url schemes (after all, file: is not 
> a protocol.)
>
>     Down in appendix D (D.1.2, etc.) there is an assumption that the 
> support of the :url capability implies support for named files.  
> Probably, what is need here is that the sentence reference the :url 
> capability should refer to the :url scheme with the file scheme 
> supported.
>
>
> editorial:
> In the initial description of capabilities in 1.2, it says
>     The capability definition may name one or more dependent 
> capabilities.
>     To support a capability, the server MUST support any capabilities 
> upon which it depends.
> I presume that the first sentence is trying to say that a capability 
> definition may name one or more capabilities upon which it depends, or 
> upon which it is dependent.  The common usage for "dependent 
> capabilites" would mean that it names the capabilities which depend 
> upon it, making extension difficult.
>
> ------
> OAM NETCONF Configuration Protocol
>     draft-ietf-netconf-prot-10.txt
>
> AD: Bert Wijnen
> Reviewer: Joel M. Halpern
>
>
>
>

--
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/>