Subject: [netmod] YANG conformance idea -- take two

From: Andy Bierman <[email-masked]>
Date: Sun, 10 Aug 2008 12:54:46 -0700

Hi,

IMO, we were on the right track with capabilities, and all
this feature stuff conflicts with the established conformance
mechanism in NETCONF.  The following example shows a much
less ambitious conformance model:

    - If no module capabilities exist then the entire module
      is mandatory-to-implement
    - Otherwise,
      - any object (or even an enum or bit) can be tagged with
        zero or more 'if-capability' statements.
      - multiple 'if-capability' statements are ANDed together
        if more than one is in effect for a given node

Module compliance variance, such as SMIv2 MIN-ACCESS is punted
to a future version of YANG.

Agent variance, such as SMIv2 AGENT-CAPABILITIES, or Martin's
yet undocumented overlay mechanism, is punted to a future version
of YANG.

==============================

module acme {
   ...

   import if { prefix if; }

   ...

   list foo {
      if-capability "acme-1";
      if-capability "if:if-table";

      ...
   }

   // entire module is mandatory except anything
   // tagged with any 'if-capability' statements

   capability acme1 {
     status current;
     description "";
     reference "";
     uri "http://example.com/capabilities/acme1";
   }
}

module if {

  container interfaces {

    list interface {
      if-capability "if-table";
      ...
    }
    leaf ifNumber {
      // conformance is mandatory for module 'if'
    }
    list ifStackTable {
       if-capability "if-table";
       if-capability "if-stack";
       ...
    }
  }

  capability if-table {
    description "Basic interface table support";
    uri "http://example.com/capabilities/if-table";
  }

  capability if-stack {
    description "Interface stack table support.";
    uri "http://example.com/capabilities/if-stack";
  }
}

module netconf {

   // RPC example
   rpc edit-config {
     input {
       ...
       leaf error-option {
         type enumeration {
           enum stop-on-error;
           enum continue-on-error;
           enum rollback-on-error {
             if-capability "rollback-on-error";
           }
         }
       }
     }
   }

   capability rollback-on-error {
     description
       "If an error condition occurs such that an
        error severity <rpc-error> element is generated, the server
        will stop processing the edit-config operation and restore
        the specified configuration to its complete state at the
        start of this edit-config operation.";
     reference "RFC 4741, section 8.5";
     uri "urn:ietf:params:netconf:capability:rollback-on-error:1.0";
   }

}

==============================

Andy

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

---

From: Martin Bjorklund <[email-masked]>
Date: Sun, 10 Aug 2008 22:36:32 +0200 (CEST)

Hi,

>         if more than one is in effect for a given node

This is what we had in mind when we came to Dublin.  But after
discussion with the IPFIX people, we proposed the "feature"-feature
instead.  It can be defined exactly as you describe above with
s/capability/feature/g.  But it solves the scalability problem
associated with capabilities.  Instead of getting one huge flat list
of all capabilities, you get two levels of capabilities/features.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Sun, 10 Aug 2008 14:09:31 -0700

> of all capabilities, you get two levels of capabilities/features.

OK.
How is a feature associated with a capability in machine-readable
format?  How does an application automatically learn this hierarchy
definition and its usage within the entire module set?

Andy

---

From: Phil Shafer <[email-masked]>
Date: Mon, 11 Aug 2008 00:34:01 -0400

>definition and its usage within the entire module set?

A new rpc will be defined that accepts a namespace and returns the
features that are implemented for the module with that namespace.
The application performs this RPC and learns from the device which
features are supported.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Tue, 12 Aug 2008 11:04:51 -0700

> The application performs this RPC and learns from the device which

Do you mean capability URI or namespace URI?

So when I read the YANG module, I have no idea what features
are defined as part of what (completely unspecified) capabilities?
I have to get the agent capabilities at run-time,
and then call this new RPC method, and then match up
features to the undocumented capabilities?

I have doubts about the standards value to DM readers of this approach.

This assumes a rather generalized conformance model that addresses
the feature partitioning aspect only.  Every little detail that
a WG decides is optional will potentially become its own 'feature'.

SMIv2 experience with conformance issues goes back a couple decades.
A SMIv2 GROUP is stable forever, and one can always tell what
is supposed to be implemented, and how the conformance requirements
changed over time.

The most common variant is of course 'MIN-ACCESS read-only', which
is not handled well by this YANG approach at all.  Other common variants
include the SYNTAX clause to make some enums optional (e.g., 'ipv6' or 'dns'
in InetAddressType objects).

These variants are likely to occur anywhere, not just
within optional chunks partitioned by capabilities.

Most importantly, SMIv2 provides a small number of conformance
variants, which can be implemented in an inter-operable manner.
The YANG approach potentially leads to dozens of undocumented
permutations per module.  This is a burden on manager applications that
have to support multiple agent platforms, and have no idea
which permutations to expect in advance.

I am not convinced at all that the YANG approach of scattered
if-feature statements, attached to undocumented capabilities,
plus augment/uses complexities, will actually support an
ever-growing pool of IETF YANG modules.  It can be difficult to
figure out exactly what to implement the day the module
is published.  As potentially all the modules change over time,
it becomes nearly impossible.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Tue, 12 Aug 2008 14:55:22 -0400

>Do you mean capability URI or namespace URI?

They are identical.  The YANG module defines a unique namespace
which is associated with that module.  Devices that implement that
module will announce that namespace as a capability via their hello
message and the data model discovery mechanism.  If an application
knows a device implements a module and is interesting in learning
which optional feature are implement, the application performs this
new RPC, passing in the namespace and receiving the list of features
in return.

>are defined as part of what (completely unspecified) capabilities?

When you read the module, you learn which pieces of the model the
modeler has designated as optional.  These optional pieces are
grouped together into well-defined sets that are meaningful to the
modeler.

For example, the IPFIX model defines a number of roles which devices
can perform.  If your device is a collector, you have configuration
nodes associated with that specific role which an application can
configure.  If your device does not support this role, no one can
ask you to perform that role and any attempt to configure your
device as a collector is doomed to failure.  When an application
contacts a device, it learns which roles are supported and behaves
accordingly.

>a WG decides is optional will potentially become its own 'feature'.

There is nothing to prevent the rampant use of the "feature" feature
to turn a model into an unreadable mountain of goo.  The control
of this tool is given to the modeler, and they can use it for good
or for evil.

As mentioned before, this is nothing that cannot be accomplished
today in YANG via multiple modules and multiple namespaces, but the
interactions between the modules is less clear.  The "feature"
feature adds a hiearchy to our solution (namespace/feature) and
allows the modeler to put all the elements of the model within a
single module.  This is most important if the features affect a
number of nodes that are not adjacent within the YANG module.  It
is much more obvious to tag "one", "two", and "three" with "if-feature
one-two-three" than define a new module that augments the appropriate
parents to add these nodes.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Tue, 12 Aug 2008 13:10:18 -0700

Phil Shafer wrote:
> which is associated with that module.  

oops -- I misunderstood (A major downside of email).
I thought there would be the ability for data modelers
to define arbitrary protocol capabilities, like in RFC 4741.

Since the module itself is the one and only protocol capability
allowed for the data model, then this 'feature' idea is more
tractable.

It still does not support the most common feature: r/o vs. r/w.

   container foo-service {
     presence "Enables the foo service if present.";
     if-feature write-foo-service {
        config true;
     } else {
        config false;
     }
     // leafs ...
   }

This is going to be needed, but the 'if-feature'
approach is going to be just as complicated as the
MIN-ACCESS approach, and not nearly as intuitive.
(But I'm familiar with SMIv2, so that biases
what seems intuitive to me.)

WGs often cannot decide that every single code point knob
in their protocol must be controlled in a standard way,
even if they agree everybody must provide the same
read-only implementation of that knob.

That's the reality that YANG has to deal with.

Andy

Devices that implement that

---

From: Andy Bierman <[email-masked]>
Date: Tue, 12 Aug 2008 13:28:45 -0700

>     if-feature write-foo-service {

I think min-access addresses a separate problem than
partitioning a module into features.  Perhaps both are needed.
Sharon likes in-line min-access, which may be better than
nothing (compared to full-blown SMIv2-style conformance).

E.g.: (?)

    container ping-service {
      presence "Enables the PING service if present.";
      if-feature "exec-services"
      config true;

      min-access {
         config false;
         // maybe the WG agrees how to report a PING service knob
         // but does not agree everybody must support standard config
         // editing via NETCONF for every knob.
         // this would likely appear in individual leafs, not a container
      }

      // leafs ...
    }

The alternative is to create 'read-only-exec-services' and 'exec-services'
and have 2 separate containers, 1 a clone of the other.  (ping-service
and ping-service-ro).  We MUST avoid this type of definition duplication.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Tue, 12 Aug 2008 16:43:24 -0400

>         // this would likely appear in individual leafs, not a container

This is a great example, since it shows why if-feature matches
YANG's needs better.  If a device doesn't support the ping service,
it need not implement the "ping-service" container, read-only or
otherwise.

    container ping-service {
        if-feature allows-ping;
        ...
    }

If you don't allow-ping, you don't need/want/support/grok the
ping-service container at all.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Tue, 12 Aug 2008 14:25:11 -0700

> ping-service container at all.

You are probably correct in that it is extremely
unlikely the entire ping service would be read-only.

A much more likely usage:

   container ping-service {
      presence "Enables the PING service if present.";
      if-feature "ping-service";
      config true;

      leaf target-host {
         description "Host to ping";
         type { inet:ip-address; }
      }

      leaf ip-protocol {
         description
           "IP version used to ping the target if the target
            contains a DNS name.";
         type enumeration {
            enum ipv4;
            enum ipv6;
         }
         min-access {
           // you MUST report which IP version was used
           // write access not mandatory
           config false;
         }
       }

       leaf payload {
         description "Payload portion for each ICMP echo packet.";
         if-feature ping-service-payload;
         type binary;
         // the agent does not have to provide any access to the
         // PDU payload unless the addition ping-service-payload
         // feature is also supported
       }

       // more leafs
    }

See how nicely both features work together? :-)
(Ignore the exact min-access syntax for now and look at the concept.)

Andy

---

From: Phil Shafer <[email-masked]>
Date: Tue, 12 Aug 2008 21:54:23 -0400

>           // write access not mandatory

I'm missing something.  How do you "report which IP version was
used" in the middle of config data?  It seems like you are mixing
the config to turn on a service with the data returned by using
that service, which isn't appropriate.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Tue, 12 Aug 2008 21:19:45 -0700

> that service, which isn't appropriate.

SNMP mixes manager-provided config and agent-provided config
all the time.  NETCONF has <get> and <get-config> to
distinguish between them. min-access 'config false'
is not really correct.  It is still config, but read-only config.

Just because you can create a row in the fooTable
does not automatically mean the agent allows you to select
a value for every leaf in the row.  Often a WG decides
that it is OK (via MIN-ACCESS) for an agent to always provide
a suitable value for that leaf, instead of allowing the
manager to set it.

This is usually what happens when an optional YANG
leaf is missing from a list.  The only difference is the
WG deciding that it is OK for the agent to provide
a valid value and not allow the manager to set the leaf
at all.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 13 Aug 2008 10:15:43 +0200 (CEST)

> partitioning a module into features. Perhaps both are needed.

Yes, and maybe it is best to wait with the min-access until yang 2.0?

> Sharon likes in-line min-access

I like this approach as well.  But it solves just one part of the
problem - it tells the module reader or client that an agent MAY
implement a particular object read only.  The other part of the
problem is how the manager can know the real access of a particular
object (ACCESS in AGENT-CAPABILITIES).  I think both parts of the
problem need to be solved simultaneously.

/martin

---

From: Phil Shafer <[email-masked]>
Date: Wed, 13 Aug 2008 11:08:52 -0400

Andy Bierman writes:
>It is still config, but read-only config.

IMHO: If I can't set it, it's not config.  Config is the instructions
I give the device to get to a known state.  If I can't give that
instruction, it's not config data.

>a valid value and not allow the manager to set the leaf

This makes big trouble for applications that attempt to save and
restore configuration.  If I get a node via <get-config> that I
can't restore via <edit-config>, then I can't do save/restore.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Wed, 13 Aug 2008 08:28:40 -0700

> instruction, it's not config data.

NETCONF has no such definition of config.
YANG has no concept of conformance that actually
accounts for the way that compromises are made in standard
data models.

A WG may decide that a leaf is writable, but that it
is not mandatory for a compliant agent to implement it.
The 'if-feature' approach will result in an artificial
'read-only' feature every time this happens.  It will result
in some 'row create' operations that are not the
same across all platforms.

One problem YANG is going to face is deployment within
the IETF, such that WGs can develop YANG models instead
of SMIv2 modules, if they so choose.

There are many WG that already know how to develop a standard MIB.
There are none that know how to develop a standard YANG module.
Perhaps "forget everything you know and learn all this new stuff
instead" is not the best transition plan.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Wed, 13 Aug 2008 09:26:57 -0700

> can't restore via <edit-config>, then I can't do save/restore.

YANG needs to support the following type of conformance scenario:

  1) A WG defines 17 conceptual knobs that make sense
     to control their new protocol

  2) Vendors do not agree that they should have to provide
     user control of all 17 knobs

  3) Instead of removing most of the 17 knobs, the WG agrees
     on a subset that MUST allow user control and the rest
     that MAY provide user control.

  4) If the optional leafs are the type that really
     are not used at all if not configured, then the GROUP
     mechanism is used to partition the optional objects
     for conformance purposes

  5) If the optional leafs are the type that really are
     used, but with an agent selected value, then the
     agent will create a knob instance with a valid value,
     depending on the data type for the knob.

  6) Even though the agent may not accept this type of optional
     knob when the NP container (table row) is created,
     the WG may decide that the manager needs to know which value was selected
     by the agent for that knob.  (Unless filtered via 'with-defaults').

  7) The way NETCONF works wrt/ this feature is TBD.
     The way to look at this in NETCONF/YANG is that this
     last sort of knob is config where the agent will
     only accept 1 particular value for the knob.

     If the agent must accept the optional leaf when it contains
     the one and only value supported by the agent, then
     edit-config, copy-config, and get-config will still work.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Wed, 13 Aug 2008 12:31:05 -0400

>NETCONF has no such definition of config.

But it does:

   Configuration data is the set of writable data that is required to
   transform a system from its initial default state into its current
   state. 

>accounts for the way that compromises are made in standard

I hope we are creating such mechanisms, with the feature feature
and device deviations.

>same across all platforms.

I don't think so.  SNMP had these issues do to the
lack of expressibility and the nature of the protocol.
NETCONF and YANG are more expressive and I hope to see
better use of these mechanism for expressing such optional
behaviors, modeled and unmodeled.

>instead" is not the best transition plan.

No, but neither is "carry your baggage forever".  We're not trying
to do "SNMP in XML".  We're trying to do something better.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Wed, 13 Aug 2008 10:22:44 -0700

> to do "SNMP in XML".  We're trying to do something better.

In order to distinguish 'better' from 'different',
one needs to understand SMIv2/SNMP and how it is used
in the IETF.  There are some practices (such as clearly
identifying the exact objects associated with a specific
version of a conformance macro) that have proven to
support inter-operable implementations.  The exact SMIv2
mechanisms and syntax are not important, but the features
they support are.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Wed, 13 Aug 2008 12:04:47 -0700

> I hope we are creating such mechanisms, with the feature feature

I am on board with the feature feature.  :-)
You sold me on that already.

My additional concerns depend on what we do about import-by-revision,
or some other way to deal with module changes over time,
especially my favorite target -- interactions between
grouping/uses/augment across modules, over time.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Wed, 13 Aug 2008 15:12:30 -0400

>You sold me on that already.

Cool.

>grouping/uses/augment across modules, over time.

So what issues do you see that import-by-revision doesn't solve?
To me, it permanently fixes the content (and the contract) of the
module.  New revisions of imported modules require specific action
to migrate the content (and renew the contract).

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Wed, 13 Aug 2008 12:31:40 -0700

> to migrate the content (and renew the contract).

import-by-revision could work with the right change control rules.
I already said I think that solution is the least painful route.

Andy

---

From: David Partain <[email-masked]>
Date: Tue, 26 Aug 2008 13:34:25 +0200

> You sold me on that already.

Hi all,

I've just re-re-read through this thread to see if I can get a sense of what's 
happened.

As I see it, the discussion has been about the idea that Martin proposed at 
the recent IETF (see slides 2-5 of 
http://www3.ietf.org/proceedings/08jul/slides/netmod-7.pdf) to add 
a "feature" feature to allow model designers to make implementation of some 
things in the model conditional.

Andy, Phil, and Martin are all in favor of this.  So are the IPFIX folks (the 
idea originated with them).  I think that it's a good idea as wel, but I'd 
like to know what the rest of the WG thinks.

Cheers,

David