Subject: [netmod] smi2yang-08: inline vs. outside smiv2:oid mapping [open]

From: Juergen Schoenwaelder <[email-masked]>
Date: Sun, 5 Jun 2011 14:43:56 +0200

Hi,

I like to close this open issue. Please comment on the options
provided below.

* smi2yang-08: inline vs. outside smiv2:oid mapping [open]

  The current translation uses the smiv2:oid to denote the OID of
  constructs that are mapped to YANG. However, this leaves out any
  constructs or OID descriptors that are not mapped to YANG.

** Solution #08-01

   Do not inline OID definition but instead create a separate
   "section" at the end of a YANG module that just contains the
   OID mappings:

     smiv2:oid 1.3.6.1.2.1.2 { smiv2:alias "interfaces"; }
     smiv2:oid 1.3.6.1.2.1.2.1 { smiv2:alias "ifNumber"; }

   This means less "noise" in the YANG definitions and it allows to
   capture all known OID descriptors within the YANG module. The
   downside is that in order to find out the OID for say a leaf like
   ifNumber, one has to do a lookup.

/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: David Spakes <[email-masked]>
Date: Mon, 6 Jun 2011 11:09:17 -0400 (EDT)

Juergen,

My opinion on this issue is that the OID mapping statement format in 08-01
should be adopted, but don't require that all mappings should appear at
the end of the YANG module.  Basically, allow them to be anywhere. For
example, this should be allowed:

    leaf ifNumber {
      type int32;
      config false;
      description
       "The number of network interfaces (regardless of their
        current state) present on this system.";
      smiv2:oid 1.3.6.1.2.1.2.1
        smiv2:alias "ifNumber";
      }
    }

The smiv2:alias substatement should be optional for the inline situation,
in which case the alias name would be equal to the name of the parent.
This following would be equivalent to the above (and I think it is very
readable, not noisy):

    leaf ifNumber {
      type int32;
      config false;
      description
       "The number of network interfaces (regardless of their
        current state) present on this system.";
      smiv2:oid 1.3.6.1.2.1.2.1;
    }

If smiv2:oid statements can appear anywhere in the document, then this
would also be legal, although arguably more readable or less readable,
depending on your biases:

    leaf ifNumber {
      type int32;
      config false;
      description
       "The number of network interfaces (regardless of their
        current state) present on this system.";
      smiv2:oid 1.3.6.1.2.1.2 { smiv2:alias "interfaces"; }
      smiv2:oid 1.3.6.1.2.1.2.1;
    }

Can we define in this document that smiv2:oid substatements (and other
types of smiv2: substatements) can be added to a YANG document in a later
revision, like new leaf nodes can be added within a choice?  I think that
would be greatly beneficial.

-dss

On Sun, 5 Jun 2011, Juergen Schoenwaelder wrote:

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

-------------------------------------------------------------
 David Spakes                       email:   [email-masked]
 SNMP Research                      voice:   +1 865 573 1434
 3001 Kimberlin Heights Road          fax:   +1 865 573 9197
 Knoxville, TN  37920-9716  USA      http://www.snmp.com
-------------------------------------------------------------

---

From: David Spakes <[email-masked]>
Date: Mon, 6 Jun 2011 11:16:40 -0400 (EDT)

Oops.  I forgot to type the open brace.

-dss

On Mon, 6 Jun 2011, David Spakes wrote:

>       smiv2:oid 1.3.6.1.2.1.2.1 {
..................................^

---

From: Andy Bierman <[email-masked]>
Date: Mon, 06 Jun 2011 08:28:56 -0700

>        smiv2:oid 1.3.6.1.2.1.2.1

This would be simpler if smiv2:alias was not nested inside smiv2:oid.

     leaf ifNumber {
       type int32;
       config false;
       description

The 'alias' statement seems redundant if the node name is the same value.

Andy

>> Fax:   +49 421 200 3103<http://www.jacobs-university.de/>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 6 Jun 2011 18:23:47 +0200

>       smiv2:oid 1.3.6.1.2.1.2.1;

So you are saying we leave it to implementations how they do this? Or
can we find agreement on a common way of doing this?
 
> would be greatly beneficial.

Not sure how to read this or how to do this. I mean, the translator is
either generating those statements or it does not. There is no new
revision of the YANG module being generated. I somehow prefer a
solution where it is clear what can be expected to be generated from a
translator.

/js

---

From: Andy Bierman <[email-masked]>
Date: Mon, 06 Jun 2011 09:46:20 -0700

> can we find agreement on a common way of doing this?

No -- why can't the 2nd smiv2:oid be defined in the parent of 'ifNumber'?
IMO the complexity is too high if arbitrary 'smiv2' extensions can appear
in any node.  I prefer that any extension only refer to the immediate containment node,
in this case 'ifNumber'.  Perhaps arbitrary statements can be contained within the module itself,
but not within unrelated data nodes.

> solution where it is clear what can be expected to be generated from a

agreed.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 6 Jun 2011 19:00:01 +0200

On Mon, Jun 06, 2011 at 09:46:20AM -0700, Andy Bierman wrote:

> No -- why can't the 2nd smiv2:oid be defined in the parent of
> 'ifNumber'?  IMO the complexity is too high if arbitrary 'smiv2'
> extensions can appear in any node.  I prefer that any extension only
> refer to the immediate containment node, in this case 'ifNumber'.
> Perhaps arbitrary statements can be contained within the module
> itself, but not within unrelated data nodes.

As settled before, in order to avoid ambiguities, not all SMIv2
"nodes" translate to YANG "nodes". Hence, if we want to capture all
OIDs, some can't be inline and hence the proposal was made to make
none of them inline.

David seems to propose a new solution where those which can be inline
are inline and the others are at "random" (means implementation
specific) places. I will call this 

** Solution #08-02

   Do inline OID definitions wherever possible, e.g.,

     leaf ifNumber {
       //..
       smiv2:oid "1.3.6.1.2.1.2.1";
     }

   but allow smiv2:oid with nested smiv2:alias statements at other
   places to capture OIDs that do not map to YANG constructs.

/js

---

From: David Spakes <[email-masked]>
Date: Mon, 6 Jun 2011 15:23:35 -0400 (EDT)

YANG compilers that don't know or don't care about the smiv2:oid
extensions will simply ignore them.  So, they could be thought of as
structured comments.  My thought is, What does it matter if they appear
inline, appear at the bottom, are repeated, etc.?  Since the MIB tree is
no longer represented by the structure of containers, an application that
does care about the OIDs is going to build a map regardless where the
statements appear in the document.  Allowing them to be inline verses
clumped together at the bottom is simply a matter of readability,
convenience, and user preference.  I'm not even certain if or why it would
be necessary to have a different revision of the YANG document if these
extensions are present versus not present.  Think: comments.

-dss

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 6 Jun 2011 21:45:06 +0200

On Mon, Jun 06, 2011 at 03:23:35PM -0400, David Spakes wrote:
> extensions will simply ignore them.  

Correct.

> So, they could be thought of as structured comments.  My thought is,
> What does it matter if they appear inline, appear at the bottom, are
> repeated, etc.?  Since the MIB tree is no longer represented by the
> structure of containers, an application that does care about the
> OIDs is going to build a map regardless where the statements appear
> in the document.  Allowing them to be inline verses clumped together
> at the bottom is simply a matter of readability, convenience, and
> user preference.

Since I am coding a translator, I need to decide where to generate the
smiv2:oid statements. I can see the point of putting them inline for
SMIv2 constructs that are translated into separate YANG constructs.
However, having all smiv2:oid definitions in one place allows to more
easily to see the structure of the OID tree. So here is a another
proposal:

** Solution #08-03

   The smiv2:oid can be used inline (where it makes sense) as in

     leaf ifNumber {
       //..

   and in addition at the top-level (with nested smiv2:alias
   statements) as shown below:

     smiv2:oid 1.3.6.1.2.1.2         { smiv2:alias interfaces; }
     smiv2:oid 1.3.6.1.2.1.2.1       { smiv2:alias ifNumber; }
     smiv2:oid 1.3.6.1.2.1.2.2       { smiv2:alias ifTable; }
     smiv2:oid 1.3.6.1.2.1.2.2.1     { smiv2:alias ifEntry; }
     smiv2:oid 1.3.6.1.2.1.2.2.1.1   { smiv2:alias ifIndex; }
     smiv2:oid 1.3.6.1.2.1.2.2.1.2   { smiv2:alias ifDescr; }

   For a translator, both are easy to generate and a user gets two
   reading benefits (and technically the OID now provides the link
   between the YANG leaf ifNumber and the SMIv2 OID descriptor
   ifNumber).

> I'm not even certain if or why it would be necessary to have a
> different revision of the YANG document if these extensions are
> present versus not present.  Think: comments.

Yes, we (you, Andy, me) seem to be in agreement here.

I start to like #08-03. Comments?

/js

---

From: David Spakes <[email-masked]>
Date: Mon, 6 Jun 2011 16:26:51 -0400 (EDT)

The statement "where it makes sense" needs to be clarified.  Consider the
following.

1. The translator should be able to use smiv2:alias if the inline
invocation needs to supply an identifier that is different from the name
of the parent node.

   choice sysDescr-leaf {
     config false;
     leaf sysDescr-string {
       type string;
     }
     leaf sysDescr-binary {
       type binary;
     }
     smiv2:oid 1.3.6.1.2.1.1.1 {
       smiv2:alias sysDescr;
     }
     description
      "A textual description of the entity.  This value should
       include the full name and version identification of
       the system's hardware type, software operating-system,
       and networking software.";
   }

2. In the above example, does the OID have multiple descriptors?  One
that is explicitly specified, "sysDescr", and another that is inherted
from the parent, "sysDescr-leaf"?

-dss

On Fri, 6 May 2011, Juergen Schoenwaelder wrote:

> You understand the collapsing correctly. The reason is that
> descriptors can change and you have have multiple descriptors for the
> same OID, hence it is ambiguous which one to choose.
...
> Right now, the smiv2:oid statements are inline with the translated
> SMIv2 macros. This means and this means not all OID descriptors are
> captured. If the proposal is accepted to change the smiv2:oid
> statement, I would prefer
>
> smiv2:oid 1.3.6.1.4.1.xxxxx.1.1.1 {
>   smiv2:alias "statsGroupA";
>   smiv2:alias "oldStatsGroupA";
> }

On Sun, 5 Jun 2011, Juergen Schoenwaelder wrote:

> ** Solution #04-04
>
>    Always translate OCTET STRINGS into a choice which contains a
>    binary leaf. Add a second string leaf if there is a DISPLAY-HINT.
>    This would also apply to objects using an OCTET STRING TC, that is
>    in the extreme case (no special rules for well known string types),
>    we get for sysDescr:
>
>    choice sysDescr-leaf {
>      leaf sysDescr-string {
>        type string;
>      }
>      leaf sysDescr-binary {
>        type binary;
>      }
>    }
>
>    While this solution is robust wrt. module revisions that add a
>    DISPLAY-HINT, the cost of having to support two formats are
>    significant.

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 6 Jun 2011 22:43:37 +0200

> from the parent, "sysDescr-leaf"?

Your question assumes we adopt Solution #04-04, not sure yet this is
what we end up with (note that DISPLAY-HINTs only exist in TC
definitions and so we would have to unroll them for the choice
solution or we would have to try with groupings).

Anyway, back to the topic at hand, 'sysDescr-leaf' does not exist in
the SMIv2 namespace so claiming it does would be wrong. What about
this:

    choice _sysDescr {
      config false;
      leaf sysDescr {
        type string;
      }
      leaf sysDescr-binary {
        type binary;
      }
      description
       "A textual description of the entity.  This value should
        include the full name and version identification of
        the system's hardware type, software operating-system,
        and networking software.";
      smiv2:max-access "read-only";
      smiv2:oid "1.3.6.1.2.1.1.1";
    }

    smiv2:oid 1.3.6.1.2.1.1.1 { smiv2:alias sysDescr; }

In other words, the inline smiv2:oid value really just tags an OID to
a YANG definition. You get the associated SMIv2 descriptors by looking
for an smiv2:oid statement with smiv2:alias substatements.

/js

---

From: David Spakes <[email-masked]>
Date: Mon, 6 Jun 2011 16:56:51 -0400 (EDT)

On Mon, 6 Jun 2011, Juergen Schoenwaelder wrote:

> the SMIv2 namespace so claiming it does would be wrong

Agreed.

> What about this:
...
> for an smiv2:oid statement with smiv2:alias substatements.

I don't really like requiring that the numeric OID appear twice in
the document.

What about this:  If an inline invocation does not have an smiv2:alias
substatement, then the descriptor automatically becomes the name of the
parent node.  If an inline invocation does have an smiv2:alias, then the
name of the parent node name is not used.  An inline invocation may not
specify more than one descriptor.  Further, an inline invocation may not
be changed by a subsequent revision of the document.

    choice _sysDescr {
      config false;
      leaf sysDescr {
        type string;
      }
      leaf sysDescr-binary {
        type binary;
      }
      description
      smiv2:oid "1.3.6.1.2.1.1.1" {
        smiv2:alias sysDescr;
      }
    }

An invocation that is not inline MUST have an smiv2:alias substatement
since there is no parent node to contain it.

Further, smiv2:oid statements may be added to the YANG document at the
bottom without creating a new revision of the document (since these are
essentially comments).

-dss

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 7 Jun 2011 21:09:39 +0200

> be changed by a subsequent revision of the document.

A translation is never a revision. I do not understand your revision
concerns. And why is an inline invocation limited to exactly one
descriptor? An arbitrary rule to complicate matters?

>     smiv2:oid 1.3.6.1.2.1.1.1 { smiv2:alias sysDescr; }

I still like the readability of having all OIDs listed together
instead of just a subset. As long as it is not made illegal to do
this, I am fine. (Redundancy is not really an issue since all this is
machine generated and unless the translator is buggy, things will be
consistent.) And as noted before, a translation never generates a new
revision.

/js

---

From: David Spakes <[email-masked]>
Date: Tue, 7 Jun 2011 15:25:51 -0400 (EDT)

On Tue, 7 Jun 2011, Juergen Schoenwaelder wrote:

> And why is an inline invocation limited to exactly one

If this implies a mapping of 1.3.6.1.2.1.2.1 to ifNumber,

     leaf ifNumber {
       //..

and if this means "map 1.3.6.1.2.1.2.1 to the supplied descriptor,
foo, not the parent, ifNumber" (as in would need to in the case of
choice _sysDescr),

     leaf ifNumber {
       //..
       smiv2:oid "1.3.6.1.2.1.2.1" {
         smiv2:alias foo;
       }
     }

then if your translator produces this,

     leaf ifNumber {
       //..

what happens if somebody makes another module that does this?

     import IF-MIB {
         prefix "if";
     }
     augment "/if:ifNumber" {
       smiv2:oid "1.3.6.1.2.1.2.1" {
         smiv2:alias foo;
       }
     }

-dss

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 7 Jun 2011 22:48:34 +0200

>        smiv2:oid "1.3.6.1.2.1.2.1" {

I guess I do not understand where the catch is. You seem to assume
that humans write manually smiv2:oid statements while I assume that
they are generated by an automated translator. Or are you trying to
make an argument why allowing smiv2:alias statements in inlined
smiv2:oid statements is a bad idea?

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 10 Jun 2011 09:40:16 +0200 (CEST)

Juergen Schoenwaelder <[email-masked]> wrote:
> instead of just a subset.

I'm note sure why this is important, it isn't possible in MIBs, so it
is not clear why it is required here.

Anyway, I think I mentioned another alternative at some point:

  Use inline smiv2:oid, and introduce smiv2:alias to be used at the
  top-level, with smiv2:oid as a substatement:

    smiv2:alias interfaces {
      smiv2:oid 1.3.6.1.2.1.2;
    }

I like this better b/c the meaning of smiv2:oid doesn't change
depending on if it has a substatement or not.

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 18 Jun 2011 15:54:04 +0200

> depending on if it has a substatement or not.

Martin,

is this a proper writeup of your proposal?

** Solution #08-04

     leaf ifNumber {
       //..

   and in addition at the top-level we allow smiv2:alias statements
   with embedded smiv2:oid statements as shown below:

     smiv2:alias interfaces { smiv2:oid 1.3.6.1.2.1.2; }
     smiv2:alias ifNumber   { smiv2:oid 1.3.6.1.2.1.2.1; }
     smiv2:alias ifTable    { smiv2:oid 1.3.6.1.2.1.2.2; }
     smiv2:alias ifEntry    { smiv2:oid 1.3.6.1.2.1.2.2.1; }
     smiv2:alias ifDescr    { smiv2:oid 1.3.6.1.2.1.2.2.1.2; }
     smiv2:alias ifIndex    { smiv2:oid 1.3.6.1.2.1.2.2.1.1; }

   This is essentially solution #08-03 with the nesting of the
   smiv2:oid and smiv2:alias statements reversed. This solution does
   not require to change the semantics of smiv2:oid depending on
   whether it has substatements or not (the OID always "belongs"
   to the identifier defined by the "parent" statement).

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Sun, 19 Jun 2011 22:41:33 +0200 (CEST)

> is this a proper writeup of your proposal?

Yes.

/martin