Subject: [netmod] Working Group Last Call: Common YANG Data Types

From: David Partain <[email-masked]>
Date: Wed, 13 Jan 2010 08:07:18 +0100

Dear all,

This is a two-week working group last call on the current working group 
document:

- Common YANG Data Types: 
http://tools.ietf.org/html/draft-ietf-netmod-yang-types-05.txt

This WGLC will end on January 27, 2010.  Please review the document and post 
your comments on the mailing list.  Please use an appropriate Subject line so 
that the chairs and editor can easily keep track of the issues that need to 
be dealt with.

Thanks.

David^2

---

From: "Remi Scavenius" <[email-masked]>
Date: Wed, 13 Jan 2010 09:42:40 +0100

Dear all,

Just a few words for the Network Automation CFP, ending at the end of this 
month.
I would gladly welcome papers proposals from IETF members involved in this 
process.
http://www.upperside.fr/networkautomation2010/networkautomation2010intro.htm

Best
Remi Scavenius, agenda manager
----- Original Message ----- 
From: "David Partain" <[email-masked]>
To: <[email-masked]>
Sent: Wednesday, January 13, 2010 8:07 AM
Subject: [netmod] Working Group Last Call: Common YANG Data Types

> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
> ---------------------------------------------------------------------------------------
> Orange vous informe que cet  e-mail a ete controle par l'anti-virus mail.
> Aucun virus connu a ce jour par nos services n'a ete detecte.
>
>

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 14 Jan 2010 22:37:33 +0100 (CET)

Hi,

I have reviewed this document, and here are my (minor) comments.

1.  Section 2.  The overview mentions the types and their equivalent
    SMIv2 types.  It is not clear why the SMIv2 types are listed.  Is
    it just as information, or something else?  And what does
    "equivalent" really mean?

2.  s/Table 1 list the/Table 1 lists the/
    s/Table 2 list the/Table 2 lists the/

3.  Some YANG types in table 2 do not have an "equivalent" SMIv2
    type.   It seems ip-version should have InetVersion?  Or is it not
    "equivalent enough"?  

4.  Terminology.  The terms "object" and "object instance" are used,
    e.g. counter32 says:

      "... as specified in the
       description of an object instance using this type"

    (should this be object?)

    The YANG spec does not use the term "object".

5.  The type zero-based-counter32 has a default statement, I think
    it should be removed.  (same for zero-based-counter64)

6.  counter32 says:

       increases until it reaches a
       maximum value of 2^32-1 (4294967295 decimal), when it
       wraps around and starts increasing again from zero.

    but zero-based-counter32 says:

       wrapping
       back to zero(0) when the value 2^32 is reached

    It presumably means the same thing, but looks odd (I understand
    that the text is copied from 2578 and 2021...)

7.  gauge32:  s/semantics equivalent to the Counter32/
              s/semantics equivalent to the Gauge32/

8.  timeticks:  s/When objects are defined which use/
                  When an object is defined which uses/

9.  xpath1.0:

      We should add something like:   When an object is defined which
      uses this type, the description of the object MUST specify the
      XPath context in which the XPath expression is evaluated.

10.  ipv6-address:  s/The normalized format/The canonical format/ ?
 
       (same for ipv6-prefix)

11.  domain-name:  The text says:

       The description clause of objects using the domain-name
       type MUST describe how (and when) these names are
       resolved to IP addresses.

     s/description clause/description/  (or description statement)

     I realize that this text comes from rfc 4001, but I do not quite
     understand why this is necessary.  I couldn't find many MIBs that
     allow dns(16), but some did not follow this MUST, and
     DISMAN-NSLOOKUP-MIB has:  

        Specification of dns(16) as the value for this object
        means that a function such as, for example, getaddrinfo()
        or gethostbyname() should be performed to return one or
        more numeric addresses.

     Is this necessary (as in MUST)?

12.  uri: s/uri type must be/uri type MUST be/ ?

13.  uri: s/where required/where required./

Also, I have implemented the modules in this document.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 14 Jan 2010 15:02:57 -0800

Martin Bjorklund wrote:
...
>     it should be removed.  (same for zero-based-counter64)

We already established that default-stmt for config=false is OK.
It has meaning wrt/ the with-defaults=trim filtering.

In this case, the default means the server MUST create all
instances of the leaf with the value zero.

This is the exact semantics that is required for these typedefs.

I think the default-stmt text says that default (for a data node)
means that the server will create the node with that value.
It doesn't say (or mean) that the server has to keep
the leaf at that value forever.

In other contexts, the server does not have a
chance to alter the leaf (rpc-reply, notification).

> /martin

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 15 Jan 2010 00:09:35 +0100 (CET)

> We already established that default-stmt for config=false is OK.

Yes.

> It has meaning wrt/ the with-defaults=trim filtering.

Yes.

> instances of the leaf with the value zero.

The YANG spec does not say that default for config false means initial
value.  The description of this typedef says that though, and that is
correct.

A default on a config false means the same as a default on config
true, right?  I.e. if the instance does not exist, it operationally
has the default value.

> means that the server will create the node with that value.

No it says:

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

But I don't want to re-re-re-start the debate of what a default is!

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 14 Jan 2010 15:31:50 -0800

> But I don't want to re-re-re-start the debate of what a default is!

Well, this is still the desired behavior, especially for
rare error counters.  The default=0 says the server does not
actually have to return all these 'never been incremented' counters.

Without the default-stmt, the server MUST return all these zeros.
With the default-stmt, the server MAY wait until the counter is non-zero
before creating the actual state data node.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Thu, 14 Jan 2010 23:10:05 -0500

>> But I don't want to re-re-re-start the debate of what a default is!

Amen.

>Without the default-stmt, the server MUST return all these zeros.

Not unless the leaf is mandatory.

Thanks,
 Phil

---

From: Martin Bjorklund <[email-masked]>
Date: Sun, 17 Jan 2010 21:44:11 +0100 (CET)

> before creating the actual state data node.

Ok, this makes sense.

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 18 Jan 2010 12:15:14 +0100

> I have reviewed this document, and here are my (minor) comments.

Thanks for your review.
 
>     "equivalent" really mean?

I propose to add the following sentence:

  A YANG data type is equivalent to an SMIv2 data type if both data
  types have the same set of values and the semantics of the values
  are equivalent.

>     s/Table 2 list the/Table 2 lists the/

fixed

>     type.   It seems ip-version should have InetVersion?  Or is it not

It seems to be equivalent, despite the text saying "However, the
lexical appearance is different from the InetVersion textual
convention." I think the proper resolution is to remove this sentence
from the description statement and to list ip-version as equivalent to
InetVersion in the summary table.

>     The YANG spec does not use the term "object".

Shall I use "data node" instead of "object"?

>     it should be removed.  (same for zero-based-counter64)

I did not really understand the concern and it seems the discussion
led to the conclusion that the default clause is OK. So I will not
make any edits here.

>     that the text is copied from 2578 and 2021...)

I will align the wording for both, zero-based-counter32 and
zero-based-counter64.

>               s/semantics equivalent to the Gauge32/

fixed

>                   When an object is defined which uses/

fixed

>       XPath context in which the XPath expression is evaluated.

yes, makes sense

> 10.  ipv6-address:  s/The normalized format/The canonical format/ ?

fixed

>      Is this necessary (as in MUST)?

The key really is the '(and when)' part. The point is that it makes a
difference whether you resolve the name when you load a config or
whether you resolve the name once the config is being used. I will
remove the parenthesis to make the "and when" part clearer. Since the
question when you resolve a name matters, I believe a MUST is
justified.

> 12.  uri: s/uri type must be/uri type MUST be/ ?

fixed
 
> 13.  uri: s/where required/where required./

fixed

/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: Martin Bjorklund <[email-masked]>
Date: Mon, 18 Jan 2010 22:42:20 +0100 (CET)

>   types have the same set of values and the semantics of the values

Ok.  With this definition, would you say that any other of the inet
types are equivalent with the types in INET-ADDRESS-MIB?
(e.g. ipv4-address vs. InetAddressIPv4)?

> Shall I use "data node" instead of "object"?

What do you want to cover with the term "object"?  leaf? typedef?

> led to the conclusion that the default clause is OK. So I will not

Agreed.

> question when you resolve a name matters, I believe a MUST is

I agree that the 'when part' justifies the MUST.  I'm not convinced
that the 'how part' MUST be described (does the example description
from DISMAN-NSLOOKUP-MIB really say anything?  "A function such as
..."  seems pretty vague.)

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 19 Jan 2010 00:14:14 +0100

> (e.g. ipv4-address vs. InetAddressIPv4)?

ipv4-address and InetAddressIPv4 clearly are not the same since the
first allows for an optional zone index and InetAddressIPv4 does not.
In other words, ipv4-address is kind of a union of InetAddressIPv4 and
InetAddressIPv4z.
 
> What do you want to cover with the term "object"?  leaf? typedef?

The term was carried over from SMIv2 definitions and I think it refers
in most cases to leafs or leaf-list definitions. I guess data node
covers this best - given the set of defined YANG terms we have.

> ..."  seems pretty vague.)

So is your proposal to replace "MUST describe how (and when)" with
"MUST describe when"? The "how" probably came into existence because
it can matter whether you resolve AAAA records before trying A records
and such things.

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 19 Jan 2010 10:42:58 +0100 (CET)

> covers this best - given the set of defined YANG terms we have.

Agreed.  But the term 'data node' sounds a bit strange when it is used
here.  I don't have a better suggestion though.

> it can matter whether you resolve AAAA records before trying A records

Hmm.. I guess this makes sense.  Maybe we should add some hints about
how 'how and when' should be described.  Just saying that
getaddrbyinfo() or equivalent is used does not really answer the 'how'
question.

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 19 Jan 2010 12:41:12 +0100

> here.  I don't have a better suggestion though.

So unless someone has a better suggestion, I will make the edits to use
"data node". 

> getaddrbyinfo() or equivalent is used does not really answer the 'how'

The good news is that there is already a "note" following the sentence
in question"

      The description clause of objects using the domain-name
      type MUST describe how and when these names are
      resolved to IP addresses. Note that the resolution of a
      domain-name value may require to query multiple DNS records
      (e.g., A for IPv4 and AAAA for IPv6). The order of the
      resolution process and which DNS record takes precedence
      depends on the configuration of the resolver.

But then the last sentence kind of confuses things again since the
resolution order depends on the resolver config only if the
application chooses to not provide resolution hints. A more 
accurate phrasing might be this:

      The description clause of objects using the domain-name
      type MUST describe how and when these names are
      resolved to IP addresses. Note that the resolution of a
      domain-name value may require to query multiple DNS records
      (e.g., A for IPv4 and AAAA for IPv6). The order of the
      resolution process and which DNS records take precedence
      can either be controlled explicitely by the caller of the
      resolver or it may depend on the configuration of the
      resolver.

/js

---

From: "tom.petch" <[email-masked]>
Date: Wed, 20 Jan 2010 10:41:27 +0100

Martin

You say in item 4
'> > > > > >     The YANG spec does not use the term "object". '
but then in item 9 - since elided, implying agreement - you say

>       XPath context in which the XPath expression is evaluated.

Either object is in or object is out:-)

I would take it out but would prefer schema node to data node; I think that that
would be less confusing.

Tom Petch

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 20 Jan 2010 13:53:14 +0100

> Either object is in or object is out:-)

I am not mixing the resolution of different comments. Thats all.

> I would take it out but would prefer schema node to data node; I
> think that that would be less confusing.

I guess you are right since the data tree does not seem to include
"data content" passed in notifications and RPCs.

/js