Subject: [netmod] smi2yang-23: config true deviations

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 11 Jan 2012 10:46:15 +0100

* smi2yang-23: config true deviations [open]

   One approach to support edit-config writable MIB objects is to use
   YANG deviations, i.e., an implementation announces an additional
   YANG module that provides config true information via YANG
   deviations. RFC 6020, Section 7.18.3, Page 103 says:

     Device deviations are strongly discouraged and MUST only be used as a
     last resort.  Telling the application how a device fails to follow a
     standard is no substitute for implementing the standard correctly.  A
     device that deviates from a module is not fully compliant with the
     module.

   This text apparently was written for the case that an
   implementation can't meet the minimum requirements of the YANG
   contract, which is not the case here.

** Solution #23-01

   Add text to clarify that config true deviations that add
   functionality do not impact the compliance of an implementation:

     Implementations may choose to implement some data nodes as
     configuration data nodes. Such a deviation from the generated
     YANG module should be formally documented in a separate YANG
     module that details the changes using YANG deviation statements
     changing the config tag of the data nodes implemented as
     configuration data nodes from false to true. Deviations that
     change the config false tag to true without any other changes to
     the semantics of the data node do not affect the compliance with
     the YANG module generated from an SMIv2 module.

/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: Wed, 11 Jan 2012 21:15:28 +0100 (CET)

>      the YANG module generated from an SMIv2 module.

I am fine with adding this text.  However, I would not use the term
"tag", since it is not used in 6020.  I think I would use the term
"property", since that's what's being used in the text about
deviations:

     Implementations may choose to implement some data nodes as
     configuration data nodes. Such a deviation from the generated
     YANG module should be formally documented in a separate YANG
     module that details the changes using YANG deviation statements
     changing the "config" property of the data nodes implemented as
     configuration data nodes from false to true. Deviations that
     change the "config" property to true without any other changes to
     the semantics of the data node do not affect the compliance with
     the YANG module generated from an SMIv2 module.

And probably add the example I sent, or something similar.

/martin

---

From: David Reid <[email-masked]>
Date: Wed, 11 Jan 2012 15:22:37 -0500

>      the YANG module generated from an SMIv2 module.

I like this solution.

-David Reid

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 12 Jan 2012 08:46:20 +0100

> "property", since that's what's being used in the text about

I picked 'tag' because of this:

   YANG can model state data, as well as configuration data, based on
   the "config" statement.  When a node is tagged with "config false",
   its subhierarchy is flagged as state data, to be reported using
   NETCONF's <get> operation, not the <get-config> operation.  Parent
   containers, lists, and key leafs are reported also, giving the
   context for the state data.

I originally had property and will change it back.

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 12 Jan 2012 10:38:31 +0100

On Wed, Jan 11, 2012 at 09:15:28PM +0100, Martin Bjorklund wrote:

> I am fine with adding this text.  [...]

> I like this solution.

While editing, I thought it is important to highlight the difference
in the persistency models in order to explain why by default data
nodes are read-only. I think this is important so that people
understand that it is sometimes wrong to simply mark writable SNMP
objects as config true. So I ended up writing a whole new section.
Please let me know if something needs changes or whether you are fine
with it.

11.  Configurable Data Objects

   The translation of SMIv2 MIB modules into YANG modules defined above
   is read-only.  One reason is that the persistency models of the
   underlying protocols, SNMP and NETCONF, are quite different.  With
   SNMP, the persistency of a writable object depends either on the
   object definition itself (i.e., the text in the DESCRIPTION clause)
   or the persistency properties of the conceptual row it is part of,
   sometimes controlled via a columnar object using the StorageType
   textual convention.  With NETCONF, the persistency of configuration
   objects is determined by the properties of the underlying datastore.
   Furthermore, NETCONF as defined in [RFC6241] does not provide a
   standard operation to modify operational state.  The <edit-config>
   and <copy-config> operations only manipulate configuration data.  As
   a consequence of these considerations, it is not possible to generate
   YANG configuration data nodes from SMIv2 definitions in an automated
   way.

   However, for selected SMIv2 objects where the SNMP and NETCONF
   persistency semantics are consistent, implementations may choose to
   implement some YANG data nodes generated from SMIv2 definitions as
   configuration data nodes.  Such a deviation from the generated read-
   only YANG module should be formally documented in a separate YANG
   module that uses YANG deviation statements to change the config
   property of the data nodes implemented as configuration data nodes
   from false to true.  Deviations that change the config false property
   to true without any other changes to the semantics of the data node
   do not affect the compliance with the YANG module generated from an
   SMIv2 module.

11.1.  Example: addressMapControlTable of RMON2-MIB

   The following example demonstrates how certain columnar objects of
   the addressMapControlTable of the RMON2-MIB [RFC4502] can be turned
   into YANG configuration data nodes.  Note that YANG deviations affect
   the property of the target node only and are not inherited downwards.

     module acme-RMON2-MIB-deviations {

       namespace "http://acme.example.com/RMON2-MIB-deviations";
       prefix "acme-rmon2-devs";

       import RMON2-MIB {
         prefix "rmon2-mib";
         revision-date 2006-05-02;
       }

       revision 2012-01-11 {
         description
           "First version.";
       }

       deviation "/rmon2-mib:RMON2-MIB" {
         deviate replace {
           config true;
         }
       }

       deviation "/rmon2-mib:RMON2-MIB/"
               + "rmon2-mib:addressMapControlTable" {
         deviate replace {
           config true;
         }
       }

       deviation "/rmon2-mib:RMON2-MIB/"
               + "rmon2-mib:addressMapControlTable/"
               + "rmon2-mib:addressMapControlEntry" {
         deviate replace {
           config true;
         }
       }

       deviation "/rmon2-mib:RMON2-MIB/"
               + "rmon2-mib:addressMapControlTable/"
               + "rmon2-mib:addressMapControlEntry/"
               + "rmon2-mib:addressMapControlIndex" {
         deviate replace {
           config true;
         }
       }

       deviation "/rmon2-mib:RMON2-MIB/"
               + "rmon2-mib:addressMapControlTable/"
               + "rmon2-mib:addressMapControlEntry/"
               + "rmon2-mib:addressMapControlDataSource" {
         deviate replace {
           config true;
         }
       }

       deviation "/rmon2-mib:RMON2-MIB/"
               + "rmon2-mib:addressMapControlTable/"
               + "rmon2-mib:addressMapControlEntry/"
               + "rmon2-mib:addressMapControlOwner" {
         deviate replace {
           config true;
         }
       }
     }

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 12 Jan 2012 12:35:31 +0100 (CET)

> Please let me know if something needs changes or whether you are fine

I like this new text.

>    only YANG module should be formally documented in a separate YANG

s/should/SHOULD/  ?

>                + "rmon2-mib:addressMapControlOwner" {

Maybe we can provide even more clarity here by giving an example how
this deviations module is used.  Strictly speaking it is not needed;
people can connect the dots by reading 6020, but examples are often
useful.

  A NETCONF server that implements the RMON2-MIB module with these
  deviations would advertise the following capabilities in its <hello>
  message (where whitespace has been added for readability):

    <capability>
      urn:ietf:params:xml:ns:yang:smiv2:RMON2-MIB?
        module=RMON2-MIB&amp;
        revision=2006-05-02&amp;
        deviations=acme-RMON2-MIB-deviations
    </capability>
    <capability>
      http://acme.example.com/RMON2-MIB-deviations?
        module=acme-RMON2-MIB-deviations&amp;
        revision=2012-01-11
    </capability>

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 12 Jan 2012 12:57:29 +0100

> I like this new text.

Great.

> >    only YANG module should be formally documented in a separate YANG

We can make it a SHOULD but it is not something one can implement and
hence I think it is really more a should. At the end, I always do what
the IESG wants me to do - so we can also leave it to them. ;-)

>         module=acme-RMON2-MIB-deviations&amp;

I will add this. Examples help implementors a great deal to come up
with the same conclusions or they simply save them some time.

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 12 Jan 2012 13:34:10 +0100 (CET)

Hi,

One small clarification below.

>    only YANG module should be formally documented in a separate YANG

s/in a separate/in the form of a separate/

/martin