Subject: Re: [netmod] smi2yang-16: smiv2:oid oid representations [open]

From: David Spakes <[email-masked]>
Date: Tue, 15 Nov 2011 14:52:52 -0500 (EST)

On Mon, 14 Nov 2011, David Spakes wrote:

> Subject : Re: smi2yang-14: unflatten scalars [open]
>
> I would like to propose another solution in which logical collections
> are preserved by having a separate top-level container for each of those
> collections.
>
>    foo-fum-mib
>      +-- fooScalars
>      |     +-- fooScalar1
>      |     +-- fooScalar2
>      +-- fumScalars
>      |     +-- fumScalar1
>      |     +-- fumScalar2
>      +-- fooTable
>      +-- fumTable

On Tue, 15 Nov 2011, Juergen Schoenwaelder wrote:

> Clarification question: Is a translator allowed / required / ... to
> produce both smiv2:oid and smiv2:subid statements?
>
> /js

Juergen,

If my proposed solution to unflatten scalars (smi2yang-14) is adopted
so the logical collections from the MIB are preserved, then here are
the usage rules I propose for oid and subid statements.

  extension oid

    1) MUST be used in the first level of containment within the module.
       For example, in augments, top-level containers, notifications,
       and alias.

    2) SHOULD NOT be used below the first level of containment within a
       module, except in the following cases:

         a) to specify the object identifier for leaf objects defined
            within notifications

         b) as a substatement to an alias

  extension subid

    1) MUST NOT be used above the second level of containment within a
       module.

    2) MUST be used at every level below the first level of containment
       within a module to determine the object identifier for every
       scalar object and columnar object translated from the SMIv2
       module, not including objects defined within a notification.

I would also change the description of the extension alias as follows.
For an example of the new form, take a look at the substatements of
the augment statement in the example below.

  extension alias {
    argument "descriptor"
    description
     "The alias statement introduces an SMIv2 descriptor. If the alias
      statement appears at the top level within a module, the body of
      the alias statement is expected to contain an oid statement that
      provides the numeric OID associated with the descriptor. Otherwise,
      the numeric OID is determined by the adjacent oid statement or by
      the adjacent subid statement taken with parental oid/subid
      statements.";
    reference
     "RFC2578: Structure of Management Information Version 2 (SMIv2)";
  }

This conversion of IF-MIB to YANG demonstrates the oid, subid, and both
forms of the alias statement...

  container interfaces {
    config false;
    smiv2:oid "1.3.6.1.2.1.2";

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

  container ifMIBObjects {
    config false;
    smiv2:oid "1.3.6.1.2.1.31.1";

    leaf ifTableLastChange {
      type yang:timeticks;
      description
       "The value of sysUpTime at the time of the last creation or
        deletion of an entry in the ifTable.  If the number of
        entries has been unchanged since the last re-initialization
        of the local network management subsystem, then this object
        contains a zero value.";
      smiv2:subid 5;
    }

    leaf ifStackLastChange {
      type yang:timeticks;
      description
       "The value of sysUpTime at the time of the last change of
        the (whole) interface stack.  A change of the interface
        stack is defined to be any creation, deletion, or change in
        value of any instance of ifStackStatus.  If the interface
        stack has been unchanged since the last re-initialization of
        the local network management subsystem, then this object
        contains a zero value.";
      smiv2:subid 6;
    }
  }
  ...

  container ifTable {
    config false;
    description
     "A list of interface entries.  The number of entries is
      given by the value of ifNumber.";
    smiv2:oid "1.3.6.1.2.1.2.2";

    list ifEntry {
      key "ifIndex";
      description
       "An entry containing management information applicable to a
        particular interface.";
      smiv2:subid 1;

      leaf ifIndex {
        type if-mib:InterfaceIndex;
        description
         "A unique value, greater than zero, for each interface.  It
          is recommended that values are assigned contiguously
          starting from 1.  The value for each interface sub-layer
          must remain constant at least from one re-initialization of
          the entity's network management system to the next re-
          initialization.";
        smiv2:subid 1;
      }
      ...
    }
  }
  ...

  smiv2:alias ifXTable {
    description
     "A list of interface entries.  The number of entries is given by
      the value of ifNumber.  This table contains additional objects
      for the interface table.";
    smiv2:oid "1.3.6.1.2.1.31.1.1";
  }

  augment "/if-mib:ifTable/if-mib:ifEntry" {
    smiv2:alias ifXEntry;
    description
     "An entry containing additional management information
      applicable to a particular interface.";
    smiv2:oid "1.3.6.1.2.1.31.1.1.1";

    leaf ifName {
      type snmpv2-tc:DisplayString;
      description
       "The textual name of the interface.  The value of this
        object should be the name of the interface as assigned by
        the local device and should be suitable for use in commands
        entered at the device's `console'.  This might be a text
        name, such as `le0' or a simple port number, such as `1',
        depending on the interface naming syntax of the device.  If
        several entries in the ifTable together represent a single
        interface as named by the device, then each will have the
        same value of ifName.  Note that for an agent which responds
        to SNMP queries concerning an interface on some other
        (proxied) device, then the value of ifName for such an
        interface is the proxied device's local name for it.

        If there is no local name, or this object is otherwise not
        applicable, then this object contains a zero-length string.";
      smiv2:subid 1;
    }
    ...
  }
  ...

  notification linkDown {
    smiv2:oid "1.3.6.1.6.3.1.1.5.3";
    description
     "A linkDown trap signifies that the SNMP entity, acting in
      an agent role, has detected that the ifOperStatus object for
      one of its communication links is about to enter the down
      state from some other state (but not from the notPresent
      state).  This other state is indicated by the included value
      of ifOperStatus.";

    container object-1 {
      leaf ifIndex {
        type leafref {
          path /ifTable/ifEntry/ifIndex;
        }
        smiv2:oid "1.3.6.1.2.1.2.2.1.1";
      }
    }
    container object-2 {
      leaf ifIndex {
        type leafref {
          path /ifTable/ifEntry/ifIndex;
        }
        smiv2:oid "1.3.6.1.2.1.2.2.1.1";
      }
      leaf ifAdminStatus {
        type leafref {
          path /ifTable/ifEntry/ifAdminStatus;
        }
        smiv2:oid "1.3.6.1.2.1.2.2.1.7";
      }
    }
    container object-3 {
      leaf ifIndex {
        type leafref {
          path /ifTable/ifEntry/ifIndex;
        }
        smiv2:oid "1.3.6.1.2.1.2.2.1.1";
      }
      leaf ifOperStatus {
        type leafref {
          path /ifTable/ifEntry/ifOperStatus;
        }
        smiv2:oid "1.3.6.1.2.1.2.2.1.8";
      }
    }
  }

-dss

-------------------------------------------------------------
 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: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 17 Nov 2011 07:57:45 +0100

>        module, not including objects defined within a notification.

Hm, then I do not like it. I like to be able to pick up the full OID
from a definition. You want me to go up the containment hierarchy in
order to construct the identifier. Since my translator knows the full
OID, it is a no brainer to simply print it. It appears to me like we
make the file of everyone just more complicated than it needs to be.

/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, 16 Nov 2011 23:24:11 -0800

> make the file of everyone just more complicated than it needs to be.

IMO, this is more than a nice-to-have.
It is mandatory that the smi:oid extension contain exactly one format,
which the complete OID string.  Any solution that leaves it up to
the translator to do anything else is not acceptable.

Add additional extensions if you want, and I can (and will) ignore them.
Forcing tools to fish around for OID fragments so the actual OID string
can be reconstructed is a bad idea.

> /js

Andy

---

From: David Spakes <[email-masked]>
Date: Thu, 17 Nov 2011 10:24:35 -0500 (EST)

> make the file of everyone just more complicated than it needs to be.

Dealing with the subidentifiers was perhaps difficult when the translated
document could have an arbitrary depth of containers.  But today the
hierarchy is collapsed and there are only a few specific cases to handle.

If your translator knows the full OID, it should also be a no-brainer to
pluck off the last subidentifier (in the case of scalars and auments) or
the last two subidentifers (in the case of list) and print them instead.

The beauty of the subid approach is that it reflects and compliments the
preservation of logical collections of objects.  Whether the reader of the
translated YANG document is human or machine, a subid statement affirms
the logical collection (i.e., the 'normal' case) and an oid statement
below the top level screams "pay special attention".

-dss

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 18 Nov 2011 04:03:45 +0100

> below the top level screams "pay special attention".

I do not care about the implementation aspects in the translator. I
care about making postprocessing of YANG modules harder than it needs
to be.

/js

---

From: David Spakes <[email-masked]>
Date: Fri, 18 Nov 2011 11:49:10 -0500 (EST)

> care about making postprocessing of YANG modules harder than it needs

About which are you mainly concerned?
Postprocessing by an application that knows about/cares about SNMP?
Postprocessing by an application does doesn't know about/care about SNMP?

-dss

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 19 Nov 2011 13:00:18 +0100

> Postprocessing by an application does doesn't know about/care about SNMP?

Making the OID accessible as an OID seems really simple to me.

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 23 Nov 2011 13:57:21 +0100

We need to come to a resolution of this issue. Here is an attempt
to formulate a way forward.

a) The smiv2:oid statement contains a full OID in dotted number format
   and nothing else. Rationale: This is easiest to post process for
   example by xslt transforms processing YIN format since it is not
   required to move around in the tree to obtain a full OID.
   Extracting the last number, the subid, usually is simple.

b) A translator always generates smiv2:oid statements. Rationale: This
   is simple and straight-forward to do and supports the rationale for
   a).

c) We add an extension to the ietf-yang-smiv2.yang module defining a
   subid statement. There is not requirement for a translator to
   generate such statements; we merely provide this statement for
   convenience in situations where hand written annotations of YANG
   modules are created.

In other words, we provide means for a different notation so that
tools can be prepared to understand it but we do not mandate the use
of this different notation _by_a_translator_.

Does that work?

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 23 Nov 2011 14:19:38 +0100 (CET)

> of this different notation _by_a_translator_.

This works for me, although the logic is a bit weird - the rationale
in (a) seems to indicate that subid should not exist at all.  But
remove the rationale in (a), and I'm happy ;)

/martin

---

From: David Reid <[email-masked]>
Date: Wed, 23 Nov 2011 09:12:30 -0500

> remove the rationale in (a), and I'm happy ;)

I'm happy with this solution.

-David Reid

---

From: David Spakes <[email-masked]>
Date: Wed, 23 Nov 2011 15:41:40 -0500 (EST)

> of this different notation _by_a_translator_.

Yes, that seems fine.

-dss