Subject: [Netconf] capability URI issues

From: Andy Bierman <[email-masked]>
Date: Thu, 01 Apr 2010 10:14:03 -0700

Hi,

Here's a capability issue list roundup.
Let's try to finish this ASAP.
Sorry if not all possible solutions are enumerated.

1) identifying the I-D or RFC
   Can we get rid of all version identifiers in capability URIs
   and use revision=yyyy-mm-dd instead?  That means we should drop
   all the stuff about :DRAFT-XX and :RFCXXXX from every YANG module
   draft, and the YANG usage guidelines draft.

   a) leave version in XML namespace and therefore change the
      YANG module XML namespace every time a new I-D or RFC
      is published.  (YANG draft says this field MUST NOT change.)
   b) remove version from XML namespace and follow
      the rule already in the YANG spec.  The module XML
      namespace will not change from release.  The revision date
      will be updated instead.

2) Base part of the URI

   A standard NETCONF protocol capability has this base part:

       urn:ietf:params:netconf:capability

   A version identifier is appropriate because there is revision parameter.

   Examples:
       urn:ietf:params:netconf:capability:candidate:1.0
       urn:ietf:params:netconf:capability:base:1.0
       urn:ietf:params:netconf:capability:base:1.1

   A standard YANG module capability has this base part:

       urn:ietf:params:xml:ns:yang

   Examples:
       urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults
       urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring

   Is there any confusion or disagreement about these standard
   capability URI base parts?
   a) yes
   b) no

3) capability for ietf-netconf.yang
   Since this is YANG module, it MUST follow the YANG module
   formula, which is <namespace>?module=modname&revision=revdate

urn:ietf:params:xml:ns:netconf:base:1.0?module=ietf-netconf&revision=2019-02-04

   An alternative is to define a YANG extension statement
   that allows YANG authors to override the YANG module
   capability and insert a different string as the base
   part, instead of the XML namespace.

   Should the standard YANG module capability URI encoding be
   used, or should the 'capability' extension be added to
   replace the base part of the YANG module capability URI?
   a) use standard encoding
   b) add new capability extension

4) advertising features for ietf-netconf.yang
   This is a special case no matter what, because the
   protocol capabilities (like candidate:1.0) will still
   be advertised to support 1.0 clients. The :url and
   :with-defaults URIs have parameters, and can never be
   replaced by YANG features in the <hello> encoding.

   Clients still need to deal with the capability URIs
   and switching to features is not realistic.  Duplication
   is not helpful.  What if the feature set does not match
   the capability set from the same server? (Server bug I guess
   but it still complicates the client -- all pain and no gain.)

   Should a 4741bis server advertise the ietf-netconf module?
   a) yes
   b) no

5) What will 4741bis clients and servers advertise in their <hello>
   capabilities?

   a) base 1.0 + base 1.1
   b) base 1.0 + ietf-netconf YANG module URI
   c) base 1.0 + base 1.1 + ietf-netconf YANG module URI

6)  Should the new capability-changed error be controlled within
    the initial capability exchange?

   Parameter:  capability-change='true'|'false'
   default: false
   If 'true' then the server will return capability-changed errors
   to this session after a capability change.  The client must request
   a new <hello> (encoded in an <rpc-reply> of course), to clear this
condition.

   Which URI should have this parameter added?
     a) base 1.1
     b) ietf-netconf

7) Splitting with-defaults capability into 2 capabilities

   It seems to me that the with-default 'basic-mode' and 'also-supported'
   parameters are related to the protocol, not the YANG module.
   The 'module' and 'revision' parameters really apply only to
   the typedef and augment statements (because that is the scope of YANG).

   Should the YANG module capability be kept separate from
   NETCONF protocol capabilities?
     a) yes
     b) no

   If yes, should the with-defaults capability be split into 2 capabilities,
   one for the protocol behavior and 1 for the YANG module?
    a) yes
    b) no

  If yes, should a server be allowed to advertise the protocol capability
  but not support the YANG module capability?  This would allow a server
  to simply announce its basic behavior, and not support the retrieval
  of 'report-all'.
    a) yes
    b) no

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 06 Apr 2010 10:39:53 +0200 (CEST)

Hi,

>    draft, and the YANG usage guidelines draft.

Yes!

>       namespace will not change from release.  The revision date

b

>    capability URI base parts?

b

>    b) add new capability extension

b (only for backwards compatibility reasons; if we did a new netconf
v2 we could do without such an extension)

>    Should a 4741bis server advertise the ietf-netconf module?

b

>    c) base 1.0 + base 1.1 + ietf-netconf YANG module URI

a

but shouldn't base 1.0 be optional?  i.e. isn't it ok for a new server
to advertise 1.1 only?

>     the initial capability exchange?

Yes.

>    Which URI should have this parameter added?

a

>    the typedef and augment statements (because that is the scope of YANG).

I'm not sure it is useful to make this distinction.  I think one
capability is enough.

>    NETCONF protocol capabilities?

b

>   to simply announce its basic behavior, and not support the retrieval

/martin

---

From: Andy Bierman <[email-masked]>
Date: Tue, 06 Apr 2010 02:10:53 -0700

Martin Bjorklund wrote:
> Hi
...

> I'm not sure it is useful to make this distinction.  I think one

The problem is that the YANG capability text does not include
arbitrary parameters stuffed in the URI.  It defines 4 specific
parameters in a specific order.

So IMO the YANG spec needs to be revised to account for
arbitrary parameters, or they must not appear in the YANG
module capability URI.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 7 Apr 2010 12:50:27 +0200

>       namespace will not change from release.  The revision date

b)

>    capability URI base parts?

b)

>    b) add new capability extension

a) and c ;-) - I think it makes sense to make a distinction between
the rpc layer of the NETCONF protocol and the set of operations (aka
rpcs) now defined in ietf-netconf-yang.

>    Should a 4741bis server advertise the ietf-netconf module?

a) And I tend to argue that we should either rewrite with-defaults so
that it uses proper features (means we need to define a longer list of
features) or we should consider allowing parameterized features in
YANG. It seems to me a warning sign that we do have concrete
operations in place where the YANG feature mechanism might not be used
or appropriate (depending on how you look at it) and we should IMHO
try to resolve this before we cast things into stone.

>    c) base 1.0 + base 1.1 + ietf-netconf YANG module URI

c) and d), which is c) without base 1.0.

>    Which URI should have this parameter added?

Please no more special cases with capability formats...

>   to simply announce its basic behavior, and not support the retrieval

I am undecided. The with-defaults IMHO really belongs into
ietf-netconf.yang since it is about behaviour of get-config etc., we
do it as an extension in a separate document for process and other
reasons. If we could roll with-defaults into base 1.1, things would
be simpler I guess...

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1, 28759 Bremen, Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Andy Bierman <[email-masked]>
Date: Wed, 07 Apr 2010 09:25:14 -0700

>>       namespace will not change from release.  The revision date

agreed  (now 3 to 0)

> rpcs) now defined in ietf-netconf-yang.

not sure what C means.
We do make a distinction.
The <create-subscription> and <partial-lock> operations
are in different namespaces already.

> try to resolve this before we cast things into stone.

I disagree that we should use YANG features as if they were identityref leafs.
A YANG feature represents a subset of the module contents.  They are additive,
not a choice between feature A, B, or C.  If we start using features
as parameter values, they will be too confusing.

YANG features should be used like SMIv2 GROUPs, except YANG
tags the group members in-line instead of at the end of the module.

> c) and d), which is c) without base 1.0.

agreed.

I like your distinction between the protocol messages <rpc>, etc.
and the operations.

Advertising ietf-netconf.yang says what version of the protocol operations
is supported.  We could decide later there is a bug in ietf-netconf.yang
and update the revision date without changing base:1.1.

The set of operations is going to be changing uncomfortably fast.
The days of peek and poke are over, and that means the operation set
will be constantly growing.  We should establish a framework now
for dealing with that (and option c & d works).

> Please no more special cases with capability formats...

right -- but IMO it is clearly 'a' because this is a protocol capability,
since it involves new error-tag values.

> reasons. If we could roll with-defaults into base 1.1, things would

The extra capability URI parameters (e.g., basic-mode and also-supported)
need to be dealt with somehow.

The YANG spec (sec. 5.6.4) can be changed to account for extra parameters.
Currently it does not allow for servers to add extra parameters.
It would just be a hack anyway -- it is not standards-worthy without semantics.

IMO, it is better not to mix protocol and module capabilities.
YANG does not support NETCONF protocol capabilities.
I tried to get a capability-stmt added but the WG decided
that the YANG feature-stmt was good enough and nothing else was needed.

Since NETCONF protocol capabilities cannot be documented with YANG at all,
there is no point pretending that they are somehow part of the YANG content.
Adding undocumented parameters to YANG module capabilities is not very robust.
IMO, it is better to keep the whole undocumented mess outside of YANG,
and use 2 capability URIs in this case.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 8 Apr 2010 13:20:44 +0200

> as parameter values, they will be too confusing.

It was not my intention to suggest any of this...
 
> tags the group members in-line instead of at the end of the module.

I was thinking that instead of announcing basic-mode=report-all (which
can't be done with the current version of YANG and thus requires a
hand-crafted capability), we could try to find alternatives:

a) Add multiple feature definitions that can be announced as
   'basic-mode-report-all' and 'also-supported-trim' etc. and thus
   would work with the current version of YANG. 

b) Or we change YANG such that features can have a parameter, e.g.

   feature basic-mode {
     type with-defaults-mode;
   }

   so that we get the "basic-mode=report-all" encoding in the URI.

I believe it is a feature if we manage to describe all NETCONF
operations completely in YANG and make YANG versioning mechanisms to
work from 1.1 onwards for all operations. Being able to describe the
NETCONF operations in YANG is kind of a proof that we got things right
and I am concerned if there are things we can't express or where we
need to introduce special cases.

/js