Subject: [netmod] wg chair review of draft-ietf-netmod-routing-cfg-13

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 19 May 2014 18:20:23 +0200

Lada,

while producing the writeup, I re-read the I-D and found a couple of
nits that I propose to fix before we send the document forward.  Most
of them are rather trivial but I think it is best we fix them now so
that we do not have to track them.

/js

a) The three modules do not compile cleanly with pyang 1.3 using the
   --ietf option because of missing description statements:

   ietf-routing: container next-hop-list is missing a description
                substatement

  ietf-ipv4-unicast-routing: container next-hop-list is missing a
                             description substatement

  ietf-ipv6-unicast-routing: container next-hop-list is missing a
                             description substatement

b) OLD

      (read-write) and "ro" means state data (read-only).

   NEW

      (read-write), and "ro" means state data (read-only).

   The RFC editor prefers a comma before and.

c) Page 21 second bullet lists some paths and the text talks about
   state data. I think the paths are incorrect and should point into
   the /rt:routing-state subtree.

d) In all three modules, replace David Kessens with Tom Nadeau as
   co-chair.

e) In all three modules, change the copyright year to 2014.

f) The leaf cur-hop-limit in the state tree has a default statement
   and also this sentence:

              The default SHOULD be set to the value specified in IANA
              Assigned Numbers that was in effect at the time of
              implementation.

   First, a default in the state tree is not really that useful.  This
   text seems to imply that there should be no default at all since
   the value can change. I think this SHOULD text should also be moved
   to the corresponding object in the configuration subtree.

g) The leaf default-lifetime in the state tree has this text:

              If this parameter is not configured, a value of 3 *
              max-rtr-adv-interval SHOULD be used.

   This text seems more appropriate for the corresponding
   configuration leaf and should perhaps be moved there.

h) There is this text in the description of ipv6-router-advertisements
   in the configuration subtree:

            See the corresponding parameters under /rt:routing-state for
            detailed descriptions and references.

   Perhaps it is easier to move the few sentence that are specific for
   the configuration objects right into the configuration object's
   description clauses (and then to remove this sentence)?

i) Please replace [YANG-IF] with [RFC7223] and update the references.

j) I did compile the example-rip module. Of course, it is and example
   and not intended to be complete. But perhaps it makes sense to add
   the missing description clauses just to make sure people always see
   descriptions clauses in RFCs (and perhaps add a comment that the
   statements for module meta information has been left out for
   brevity).

k) Have you validated the example instance document in appendix D
   against the YANG modules?

l) In the security considerations, add a sentence at the end of the
   first paragraph that points to the access control model. See
   Section 7 in RFC 7223 as an example. You also need to add an
   informative reference to RFC 6536 which this sentence refers to.

m) In the security considerations, I suggest to place a color ':'
   after the path:

   OLD

   /routing/routing-instance/interfaces/interface  This list assigns a
      network layer interface to a routing instance and may also specify
      interface parameters related to routing.

   /routing/routing-instance/routing-protocols/routing-protocol  This
      list specifies the routing protocols configured on a device.

   /routing/route-filters/route-filter  This list specifies the
      configured route filters which represent administrative policies
      for redistributing and modifying routing information.

   /routing/ribs/rib  This list specifies the RIBs configured for the
      device.

   NEW

   /routing/routing-instance/interfaces/interface:  This list assigns a
      network layer interface to a routing instance and may also specify
      interface parameters related to routing.

   /routing/routing-instance/routing-protocols/routing-protocol:  This
      list specifies the routing protocols configured on a device.

   /routing/route-filters/route-filter:  This list specifies the
      configured route filters which represent administrative policies
      for redistributing and modifying routing information.

   /routing/ribs/rib:  This list specifies the RIBs configured for the
      device.

/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: Ladislav Lhotka <[email-masked]>
Date: Wed, 21 May 2014 13:05:51 +0200

Hi Jürgen,

thanks for the review, please see my responses inline.

>   ietf-ipv6-unicast-routing: container next-hop-list is missing a

Done.

>    The RFC editor prefers a comma before and.

Done.

>    the /rt:routing-state subtree.

The second path is an RPC and it is actually correct, so I corrected the first path and removed "as state data".

> d) In all three modules, replace David Kessens with Tom Nadeau as

Done.

> e) In all three modules, change the copyright year to 2014.

Done.

>    to the corresponding object in the configuration subtree.

I agree the default should be probably removed, but then the text is an information for the server implementor about how to choose the operational default. One option would be to make cur-hop-limit mandatory instead - so a server implementor chooses an operational default value but the server has to report it.  

>    configuration leaf and should perhaps be moved there.

This one is really a dynamic default so it is up to the server to compute the value if nothing is configured.

>    description clauses (and then to remove this sentence)?

I copied some sentences from descriptions in state to config, but then there are two other types of information that I am not sure about:

- Instructions for choosing operational defaults - see above, I am inclined to leave it in state data.

- References to RFC: I think they needn't be twice in the module, and I slightly prefer to leave them with state data because this is where the constraints really matter.  

> i) Please replace [YANG-IF] with [RFC7223] and update the references.

Done.

>    statements for module meta information has been left out for

I am not sure what's better. The example is short and it's useful that the reader can easily see the structure of the entire module. Note that RFC 7223 also has the examples sans descriptions.

>    against the YANG modules?

Yes, the example validates. However, before including it in the text, I have to insert a few extra line breaks in order to keep the prescribed line length. It affects only the dates-and-times, I believe. 

>    informative reference to RFC 6536 which this sentence refers to.

Done.

>    /routing/ribs/rib:  This list specifies the RIBs configured for the

Done.

Thanks, Lada

-- 
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: E74E8C0C

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 21 May 2014 14:18:32 +0200

> thanks for the review, please see my responses inline.

Removing everything marked Done...

> I agree the default should be probably removed, but then the text is an information for the server implementor about how to choose the operational default. One option would be to make cur-hop-limit…

Now I see your point - you want to not report cur-hop-limit as long as
it is 64 (when you do not use explicit defaults during the
retrieval). Hm. More below... I guess my problem really is with the
text saying how to choose a value if no explicit config is provided.

> This one is really a dynamic default so it is up to the server to compute the value if nothing is configured.

Yes. But in my view, state objects really just report the actual
value. In other words, I would have placed the text that says how the
dynamic default is picked if a value is not configured into the
configuration tree, not the state tree. The state tree is supposed to
report the real value used. I do not expect that an implementor looks
into the description of state objects in order to figure out what to
do if a config object is not present.

> - References to RFC: I think they needn't be twice in the module, and I slightly prefer to leave them with state data because this is where the constraints really matter.  

I would like have done it the other way around because the question
how something is initialized if it is not in the configuration really
matters when you implement the configuration logic, not the rather
simply logic to read out the current value.

> I am not sure what's better. The example is short and it's useful that the reader can easily see the structure of the entire module. Note that RFC 7223 also has the examples sans descriptions.

OK - I can go along with that.

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 22 May 2014 10:56:41 +0200

> text saying how to choose a value if no explicit config is provided.

I think it is somewhat unclear what the following sentence in 6020 means for defaults in configuration data:

   When the default value is in use, the server MUST operationally
   behave as if the leaf was present in the data tree with the default
   value as its value.

For example, assume the data model defines the default value for 'cur-hop-limit' in *config* to be 64. Now, IANA changes the default TTL, and device X uses this new value as its operational default (independent of NETCONF). It can now mean two things:

1. Device X is no more compliant with the data model, or

2. When the NETCONF server is started on device X, it has to change the 'cur-hop-limit' to 64 on its own so that the contract with its clients expressed by the data model still holds.  

On the other hand, a default value defined for a state leaf must IMO be the "native" operational default that the device uses even in the absence of NETCONF.

> do if a config object is not present.

It is true that such instructions are more of interest to those that implement the guts of the system, and state data should just tell the result. So I will move these parts of the descriptions to the config tree as you suggest.

> simply logic to read out the current value.

OK, will do.

Lada

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 22 May 2014 11:07:10 +0200

> 2. When the NETCONF server is started on device X, it has to change the 'cur-hop-limit' to 64 on its own so that the contract with its clients expressed by the data model still holds.  

I would say 2. But in this case, there is no static default - the
default can be changed by IANA. Hence, there should not be a default
on the config leaf. There can only be text describing how to pick a
value if the leaf is not provided.
 
> On the other hand, a default value defined for a state leaf must IMO
> be the "native" operational default that the device uses even in the
> absence of NETCONF.

Or there is no default statement at all because there is not static
value that all device will use today and in the future.

> It is true that such instructions are more of interest to those that implement the guts of the system, and state data should just tell the result. So I will move these parts of the descriptions to…

Great.

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 22 May 2014 11:15:35 +0200

> value if the leaf is not provided.

I agree, I used it just as an example.

> value that all device will use today and in the future.

I am just trying to figure out whether the semantics of the ‘default’ statement are different for config and state data. If we accept option #2 above, it looks like they really are.

Lada

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 22 May 2014 11:32:47 +0200

> I agree, I used it just as an example.

OK. So we close this specific case.

> I am just trying to figure out whether the semantics of the ‘default’ statement are different for config and state data. If we accept option #2 above, it looks like they really are.

My understanding is that a default in the config tree says "if this
leaf is not provided in the config data tree, act as if the default
value is configured for the leaf". For operational state, my
understanding is that the only benefit of a default statement is
suppression of data in 'trim' and 'explicit' mode (RFC 6243).

For many subsystems, the logic to choose a certain operational value
if no config is provided and there is no default value in the config
tree is really deep inside the kernel or device driver. All the state
tree does it really digging out the value and reporting it.

Makes sense?

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 22 May 2014 11:37:48 +0200

> OK. So we close this specific case.

Yup.

> suppression of data in 'trim' and 'explicit' mode (RFC 6243).

Agreed, but then it is protocol-dependent.

> tree does it really digging out the value and reporting it.

Yes, it does.

Lada

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 22 May 2014 11:49:55 +0200

> Agreed, but then it is protocol-dependent.

What is protocol dependent? RFC 6243 clarifies default handling
options. And yes, if your server only does report-all basic mode, the
default value has no effect.

For RESTCONF, it seems that currently things boil down to
report-all. But RESTCONF is not yet done (and I would hope that the
text in section 4.5.2 will be critically reviewed - I agree that
RESTCONF should simplify this, I am not sure what this section
currently says is the right solution). That said, our job is to
publish this data model - lets not worry about RESTCONF here.

/js

---

From: Andy Bierman <[email-masked]>
Date: Thu, 22 May 2014 03:56:58 -0700

> publish this data model - lets not worry about RESTCONF here.

I don't think with-defaults basic mode applies to config=false nodes.
The 'explicit' mode means the leaf is only a default if the client sets
the value (which cannot happen in NC or RC).

For config=false, a default leaf is only used to save bytes in an
<rpc-reply>.
A missing default leaf means the operational value is the same as the
default.
(Unless the reason the leaf is missing is because of filters or access
control.)

Andy

> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
>

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 22 May 2014 13:04:15 +0200

> default value has no effect.

It is protocol-dependent because the description of the semantics in this case has to start with “In NETCONF, …”. In RESTCONF it currently means nothing, and it is not clear yet what it could possibly mean for I2RS.

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 22 May 2014 13:17:26 +0200

On 22 May 2014, at 12:56, Andy Bierman <[email-masked]> wrote:

> 
> 
> 
> On Thu, May 22, 2014 at 2:49 AM, Juergen Schoenwaelder <[email-masked]> wrote:

IMO ‘report-all’ and ‘trim’ modes do apply.

Lada

> For config=false, a default leaf is only used to save bytes in an <rpc-reply>.
> A missing default leaf means the operational value is the same as the default.
> (Unless the reason the leaf is missing is because of filters or access control.)
> 
> 
> Andy
> 
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 22 May 2014 13:33:56 +0200

> I don't think with-defaults basic mode applies to config=false nodes.

The modes are 'report-all', 'trim', 'explicit'. Basic mode says which
one of the three is the normal behaviour.

> the value (which cannot happen in NC or RC).

Yes.

> (Unless the reason the leaf is missing is because of filters or access

Are you saying a server that does 'report-all' as its basic mode has
to do 'trim' when it return config false data? This would surprise me.

/js

---

From: Andy Bierman <[email-masked]>
Date: Thu, 22 May 2014 04:35:38 -0700

On Thu, May 22, 2014 at 4:17 AM, Ladislav Lhotka <[email-masked]> wrote:

> IMO 'report-all' and 'trim' modes do apply.
>
>
They do not have any conformance meaning like configuration.
There is no requirement on the server to have any particular
operational state "by default".

A YANG default is the value in use if the leaf is not present.
For 'explicit', the client cannot set config=false so this mode does not
apply.
For 'report-all', every leaf is reported so a missing leaf in a <get> reply
does not mean anything either.  For 'trim', it could mean the YANG default
is the operational value for a missing leaf.

But access control can cause a config=false leaf to be missing in
a <get> reply so a client should never assume the YANG default
is the operational value in effect.

It is also unclear what mandatory=false means for config=false nodes.
This means the server is NEVER required to return a value (so how
does the client even know the server implements the node?)

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 22 May 2014 13:35:39 +0200

> It is protocol-dependent because the description of the semantics in this case has to start with “In NETCONF, …”. In RESTCONF it currently means nothing, and it is not clear yet what it could possi…

I can't follow you. Why would the semantics of the leafs have to be
different?

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 22 May 2014 13:47:42 +0200

> I can't follow you. Why would the semantics of the leafs have to be

I mean sematics of the ‘default’ statement - what it actually means for state data seems to depend on the protocol.

The definitions in sec. 7.6.1 of RFC 6020 are clarly aimed at configuration data:

   The default value of a leaf is the value that the server uses if the
   leaf does not exist in the data tree.

For state data and NETCONF protocol, required server behaviour may depend on the with-defaults mode.

Lada

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 22 May 2014 13:52:53 +0200

> For state data and NETCONF protocol, required server behaviour may depend on the with-defaults mode.

Yes. But this is not a problem for finishing up this document so
lets not get side tracked.

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 22 May 2014 14:29:58 +0200

> lets not get side tracked.

Of course. I am now ready to post revision -14, can I do it if the draft is stil in the state “Waiting for WG Chair Go-Ahead”?

Lada

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 22 May 2014 14:53:42 +0200

Yes.

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 22 May 2014 21:23:27 +0200 (CEST)

Juergen Schoenwaelder <[email-masked]> wrote:
> > >> I agree the default should be probably removed, but then the text is an
> > >> information for the server implementor about how to choose the operational
> > >> default. One option would be to make cur-hop-limit mandatory instead - so
> > >> a server implementor chooses an operational default value but the server
> > >> has to report it.
> > >> 
> > >
> > For example, assume the data model defines the default value for
> > 'cur-hop-limit' in *config* to be 64. Now, IANA changes the default TTL, and
> > device X uses this new value as its operational default (independent of
> > NETCONF). It can now mean two things:
> > 
> > 2. When the NETCONF server is started on device X, it has to change the
> > 'cur-hop-limit' to 64 on its own so that the contract with its clients
> > expressed by the data model still holds.
> 

I agree.

I noticed that in -14, this leaf has a default value of 64, and the
text that contradicts the default statement.  Did I miss something in
your mail discussion?  Shouldn't the default statement be removed?

This leaf's description says:

  The default value to be placed in the Cur Hop Limit field
      ^^^^^^^^^^^^^

All other similar leaf has this:

  The value to be placed in the XXX field

Should s/default value/value?  If not, what does this mean?

Minor nit: this leaf's reference text has hypens before the RFCs; that
sticks out as compared to the other leafs, and compared to e.g. the
system draft.

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 22 May 2014 22:06:05 +0200

> your mail discussion?  Shouldn't the default statement be removed?

This kind of started this debate. ;-)

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 22 May 2014 22:08:15 +0200 (CEST)

> This kind of started this debate. ;-)

Right, but I thought it was resolved (i.e., that the default should be
removed)?

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 22 May 2014 22:30:28 +0200

Yes.

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 23 May 2014 00:47:20 +0200

> your mail discussion?  Shouldn't the default statement be removed?

In his item (f), Jürgen was specifically complaining about the default for ‘cur-hop-limit’ in state data, and I removed that one. I think it is appropriate to leave it in config because that value doesn’t seem to change very often. If there is no default value at all, the client may have no way to find out what value the server actually uses.

I also thought we agreed with Jürgen that even if IANA changes the default TTL there is no immediate need to update the ietf-ipv6-unicast-routing module - it is up to the NETCONF server to keep the contract and set the operational value to 64. 

>  The default value to be placed in the Cur Hop Limit field

I just used the text from RFC 4861. I guess it means it is the “default TTL value” - the host that receives the RA may use another value. I do agree though that s/default value/value/ makes sense here. 

> sticks out as compared to the other leafs, and compared to e.g. the

There are actually two references in that ‘reference’ statement, so I made them into an itemized list. Other leafs have only one reference.

Lada

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 23 May 2014 08:13:39 +0200 (CEST)

Ladislav Lhotka <[email-masked]> wrote:
> >>> I think it is somewhat unclear what the following sentence in 6020
> >>> means for
> >>> defaults in configuration data:
> >>> 
> In his item (f), Jürgen was specifically complaining about the default
> for ‘cur-hop-limit’ in state data, and I removed that one. I think it
> is appropriate to leave it in config because that value doesn’t seem
> to change very often. If there is no default value at all, the client
> may have no way to find out what value the server actually uses.
> 
> I also thought we agreed with Jürgen that even if IANA changes the
> default TTL there is no immediate need to update the
> ietf-ipv6-unicast-routing module - it is up to the NETCONF server to
> keep the contract and set the operational value to 64.

But then the last paragraph of the description should be removed:

      If this parameter is not configured, the device SHOULD use
      the value specified in IANA Assigned Numbers that was in
      effect at the time of implementation.

since this paragraph contradicts the fact that you have a default
statement.

(I would keep the text and remove the default though.)

> I just used the text from RFC 4861. I guess it means it is the
> “default TTL value” - the host that receives the RA may use another
> value. I do agree though that s/default value/value/ makes sense here.
> 
> > 
> > 
> There are actually two references in that ‘reference’ statement, so I
> made them into an itemized list. Other leafs have only one reference.

The other documents we have follow the convention introduced by RFC
6021:

      reference
        "RFC 3339: Date and Time on the Internet: Timestamps
         RFC 2579: Textual Conventions for SMIv2
         XSD-TYPES: XML Schema Part 2: Datatypes Second Edition";

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 23 May 2014 08:56:36 +0200

> (I would keep the text and remove the default though.)

Just to avoid confusion, we are talking about the config leaf
cur-hop-limit in -14, right? I agree that having the default statement
together with the text quoted above is broken. And like Martin, I
would prefer to remove the default (because otherwise we kind of kill
the IANA control of this value).

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 23 May 2014 10:33:26 +0200

> cur-hop-limit in -14, right? I agree that having the default statement

I must admit I mixed up the two different cases in my head, I thought we were talking about a leaf like 'default-lifetime' that really has no static default. Sorry for the confusion.

Now back to 'cur-hop-limit': its default value is IMO in the same position as those we already have in other similar cases. For example, ietf-ip has the leaf 'temporary-valid-lifetime' with a default value of 1 week. If this value is updated in a future revision of RFC 4941, then we are in the same situation. So my preference is to keep the default - apparently, the recommended default TTL hasn't changed since 1994 (RFC 1700).

> the IANA control of this value).

I agree the text should be better removed.

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 23 May 2014 10:49:52 +0200

Martin Bjorklund <[email-masked]> writes:

...

>          XSD-TYPES: XML Schema Part 2: Datatypes Second Edition";

I personally don't like this formatting, I think at the very least each item should be terminated with a full stop, and perhaps an empty line as well. With references that span more lines it gets really messy. On the other hand, it is IMO not that important to be absolutely consistent in these free-form texts. If we want tools to be able to parse them easily, we should really use some kind of markup. 

Lada