Subject: [netmod] Constraints section

From: David Spakes <[email-masked]>
Date: Wed, 17 Dec 2008 14:43:16 -0500 (EST)

I would like to suggest a change to the text in Section 8, paragraph 2
for draft-ietf-netmod-yang-03.txt.

------------
BEFORE
------------
8.  Constraints

   Several YANG statements define constraints on valid data.  These
   constraints are enforced at different times, depending on what type
   of data the statement defines.

   If the constraint is defined on configuration data, it MUST be true
   in a valid configuration data tree.

   If the constraint is defined on state data, it MUST be true in a
   reply to the <get> command.

------------
AFTER
------------
8.  Constraints

   Several YANG statements define constraints on valid data.  These
   constraints are enforced at different times, depending on what type
   of data the statement defines.

   If the constraint is defined on configuration data, it MUST be true
   in an <edit-config> command in order for the command to succeed.

   If the constraint is defined on state data, it MUST be true in a
   reply to the <get> command.

------------
Rationale
------------
The change affects the application of a "must" statement on a deviate
where the underlying system might return some data as valid configuration
for <get-config> but where an <edit-config> operation would not succeed.
Below is an example.

I have been looking recently at how an SMIv2 AGENT-CAPABILITIES
document might map onto a Yang module containing deviation statements.
For test cases, I have been using existing AGENT-CAPABILITIES documents
describing MIB-II variations in SNMP Research agents.

On the AIX platform, the SNMP agent is currently able to fetch
information from the kernel for both IPv4 and IPv6 routes, and it can
add/delete/modify an IPv4 route, but it is currently unable to
add/delete/modify an IPv6 route.  Here is a relavant portion of
the AGENT-CAPABILITIES document:

SUPPORTS         IP-FORWARD-MIB    -- RFC 4292
    INCLUDES     { inetForwardCidrRouteGroup }

    VARIATION    inetCidrRouteTable
    DESCRIPTION
         "This table supports read, write, and row creation, but
          currently, SNMP sets have no effect on the underlying
          IP stack(s) on the system if the inetCidrRouteDestType or
          inetCidrRouteNextHopType is ipv6(2) or ipv6z(4)."

    VARIATION    inetCidrRouteDestType
    SYNTAX       INTEGER {
                     ipv4(1),
                     ipv6(2),
                     ipv4z(3),
                     ipv6z(4)
                 }
    WRITE-SYNTAX INTEGER {
                     ipv4(1),
                     ipv4z(3)
                 }
    DESCRIPTION
         "The implementation does not support unknown(0) or dns(16)."

In a Yang document intended to be equivalent to the definitions in
RFC 4292 combined with the above AGENT-CAPABILITIES text, I have
produced Yang statements as follows:

/****************************
 * Text describing /ipForward/inetCidrRouteTable deviation:
 *
         "This table supports read, write, and row creation, but
          currently, SNMP sets have no effect on the underlying
          IP stack(s) on the system if the inetCidrRouteDestType or
          inetCidrRouteNextHopType is ipv6(2) or ipv6z(4)."
 *
 ****************************/

deviation /ipForward/inetCidrRouteEntry/inetCidrRouteDestType {
  deviate replace {
    type enumeration {
      enum ipv4  { value 1; }
      enum ipv6  { value 2; }
      enum ipv4z { value 3; }
      enum ipv6z { value 4; }
    }
  }
  deviate add {
    must "ipv4 or ipv4z" {
      error-message
         "The implementation does not support unknown(0) or dns(16)."
    }
  }
}

The scope of the constraint applied by the "must" should be limited only
to the <edit-config>.  A <get-config> command sent to this agent might
return data describing IPv6 configuration data, but an <edit-config>
command containing IPv6 configuration data would fail.

Regards,
David

-------------------------------------------------------------
 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
-------------------------------------------------------------
_______________________________________________
netmod mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netmod

---

From: Andy Bierman <[email-masked]>
Date: Wed, 17 Dec 2008 12:01:52 -0800

> for draft-ietf-netmod-yang-03.txt.

This will not for work <candidate>.
The manager is allowed to make incremental changes
that do not meet the constraints.  The constraints
do not always apply to a delete operation, since the content
may be absent in the <edit-config> PDU.

It is not the contents of the <edit-config> request that matters.
It is the resulting database that would occur after the edit
is applied that matters.

When the <commit> operation is applied to the <candidate>,
it is the resulting <running> config that matters.
Only the <running> config is ever in use by the agent,
so it is the only one required to be valid and present.

BTW, I think you want this XPath in your must-stmt example:

    must ". = 'ipv4' or . = 'ipv4z'";

Andy

---

From: Andy Bierman <[email-masked]>
Date: Wed, 17 Dec 2008 12:50:08 -0800

> for draft-ietf-netmod-yang-03.txt.
....
>          "The implementation does not support unknown(0) or dns(16)."
.....
>          "The implementation does not support unknown(0) or dns(16)."

Actually, in your example, all that is needed is:

You do not want a must-stmt there.
That (. = 'ipv4') makes the node mandatory,
since '.' must exist for the expression to be true.

Andy

---

From: David Spakes <[email-masked]>
Date: Wed, 17 Dec 2008 16:44:45 -0500 (EST)

> >     VARIATION    inetCidrRouteDestType

At my current level of understanding of Yang, "deviation replace" is
eqivalent to SMIv2's "VARIATION...SYNTAX".

What I am trying to figure out is how one expresses SMIv2's
"VARIATION...WRITE-SYNTAX" in Yang.

>    deviation /ipForward/inetCidrRouteEntry/inetCidrRouteDestType {

I considered this possibility, but it does not seem to fully express
the AIX agent implementation.

The above "deviation replace" reduces the list of enumerations supported
by the device to just ipv4 and ipv4z.  However, the configuration
data in the AIX agent implementation also includes ipv6 and ipv6z data.
The ipv6/ipv6z configuration data in the implementation is effectively
read-only.

Conceptually, what I'm looking for is something like this (I know this
isn't legal Yang syntax)...

   deviation /ipForward/inetCidrRouteEntry/inetCidrRouteDestType {
       deviate replace {
           type enumeration {
               enum ipv4  { value 1; }
               enum ipv6  { value 2; }
               enum ipv4z { value 3; }
               enum ipv6z { value 4; }
           }
           when ". = 'ipv6' or . = 'ipv6z'" {
               config false;
           }
       }
   }

Regards,
David

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 17 Dec 2008 22:47:42 +0100 (CET)

> since '.' must exist for the expression to be true.

No, the must expression does not make the node mandatory.  The must
expression is evaluated only if the node exists.

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 18 Dec 2008 09:29:37 +0100 (CET)

> "VARIATION...WRITE-SYNTAX" in Yang.

NETCONF and YANG differentiates between config and non-config data.
Only config data can be modified directly with standard NETCONF
operations.  For config data, what can be read must be possible to
write as well (to support config save and load).  Thus, a config
object cannot have different types for read and write.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 18 Dec 2008 06:29:16 -0800

> object cannot have different types for read and write.

This is one of those SMIv2 mechanisms to deal with WG consensus.
The WRITE-SYNTAX is supposed to be a subset of the SYNTAX.
The agent is saying "I support all the values, but you
can only set 2 of them and I can set the rest."

I agree this should not be supported in YANG.

Andy

---

From: David Spakes <[email-masked]>
Date: Thu, 18 Dec 2008 13:09:45 -0500 (EST)

> object cannot have different types for read and write.

Martin, I do understand and have appreciation for this difference
between SMIv2/SNMP and Yang/Netconf.  Thank you.

> I agree this should not be supported in YANG.

Andy, while I think you're right about this mechanism existing because
of WG concensus, that's not to say that WRITE-SYNTAX doesn't serve a
useful purpose.  However, the usefulness may not [nor may need to]
extend to Yang.  I agree with your statements.

>    deviation /ipForward/inetCidrRouteEntry/inetCidrRouteDestType {

Andy, here is how I interpret your response.

1. A contract between manager and agent based on the Yang equivalent to
   the MIB in RFC 4292 would state that the leaf inetCidrRouteDestType
   can take on any of the values 'unknown', 'ipv4', 'ipv6', 'ipv4z',
   'ipv6z', or 'dns'.

2. The deviation statement above regarding a particular implementation
   tells the manager that the agent AT MINIMUM supports only instances
   of inetCidrRouteDestType with values of 'ipv4' and 'ipv4z'.
   Therefore:

   (a) If the manager sends a <get-config> command to the agent,
       the reply from the agent includes only the rows having
       inetCidrRouteDestType = 'ipv4' or inetCidrRouteDestType = 'ipv4z'
       because those are the only configurable instances.  The agent's
       behavior is the CAUSE of the "deviate replace" statement,
       not the result of it.

   (b) The manager must assume that the agent only supports the
       minimum advertised behavior (ipv4/4z) when it constructs
       an <edit-config> command.  So, if the manager sends an
       <edit-config> command to the agent, the configuration data
       must include only rows that have inetCidrRouteDestType = 'ipv4'
       or inetCidrRouteDestType = 'ipv4z'.  The manager's behavior
       is the RESULT of the "deviate replace" statement.

3. If the agent has some non-configuration data (read-only instances)
   in the list inetCidrRouteEntry for rows that have
   inetCidrRouteDestType = 'ipv6' or inetCidrRouteDestType = 'ipv6z',
   and if the manager sends a <get> command to the agent, the reply
   from the agent may include this read-only data.  In this case,
   the agent exceeds the minimum expectations that it set for itself
   and communicated to the manager in the "deviate replace" statement.
   The ipv6/6z rows are still valid for a response to the <get> command
   because the original contract (in point 1) would state that 'ipv6'
   and 'ipv6z' are valid enumerations for inetCidrRouteDestType.

Is this a correct understanding of your response, Andy?

Regards,
David

---

From: Andy Bierman <[email-masked]>
Date: Thu, 18 Dec 2008 10:20:47 -0800

> Is this a correct understanding of your response, Andy?

sort of...

YANG has no concept of read-only configuration.
Or rather, if it is read-only, it isn't configuration data.
So there is no chance that the agent can have some instances
of ipv6 if declares a deviation like your example.

The deviations are likely to be set at code-compile-time,
not at code-runtime.  The deviation is not a minimum
conformance like MIN-ACCESS.  It is a conceptual
edit to the YANG definition specified by the target.

Andy

---

From: David Spakes <[email-masked]>
Date: Thu, 18 Dec 2008 16:34:37 -0500 (EST)

> Or rather, if it is read-only, it isn't configuration data.

I understand and agree, but that is one aspect of Yang that is
troubling to me.  My perception is that many real-world devices
have some initial configuration that you can build on but not
delete.  Usually not good if you're talking about security
configuration, but for application data there may be a lot of
pros compared to the cons.  Vendors want their devices to work
out-of-the-box with little or no setup.  Support teams want
a valid configuration to always be present on a device so they
can work around problems created by users.  And so on.

> not at code-runtime.

I'm not sure that really matters.  The main point for me is
that you might have a lot of leaf data items that are sometimes
configurable and sometimes not but otherwise identical.  One
_could_ define everything as a grouping and then have two uses,
one "config true;" and another "config false;".  This doesn't
seem "natural" to me though.  If it is routing entry, I want to
see it in the same table for a <get> whether it is a configurable
routing entry or a permanent routing entry.

> of ipv6 if declares a deviation like your example.

I think you are referring to your revision on my example...

>    deviation /ipForward/inetCidrRouteEntry/inetCidrRouteDestType {

...and yes, if defined this way (above), I concede that there would
be no chance that the agent could have ipv6 instances.

No one has commented yet on the conceptual syntax that I included in
an earlier message.  I would like to repeat it again (below) and invite
comments.

>            when ". = 'ipv6' or . = 'ipv6z'" {

If it is legal to have a deviation that changes "config true;" to
"config false;" for all instances (Section 7.18.3.2), why not allow a
deviation that does the same for a subset of instances?

Regards,
David

---

From: Andy Bierman <[email-masked]>
Date: Thu, 18 Dec 2008 14:08:01 -0800

David Spakes wrote:
...
> deviation that does the same for a subset of instances?

Isn't YANG complicated enough without evaluating
XPath expressions to see which sub-clauses are present
in a node?

I don't think the NETCONF community wants a complicated
definition of configuration data.
In the NETCONF view of the world, if the agent has
a bunch of data that the manager cannot change,
that is called state data.  Corner-cases such as this,
or create-only, or write-only, are not supported.

Andy