Subject: [netmod] WGLC comments about notifications

From: David Reid <[email-masked]>
Date: Tue, 12 May 2009 23:09:33 -0400

I have a few comments and questions about the notification examples.

The example in section 4.2.10 defines a leaf of type ifAdminStatus. 

     notification link-failure {
         description "A link failure has been detected";
         leaf if-name {
             type keyref {
                 path "/interfaces/interface/name";
             }
         }
         leaf if-admin-status {
             type ifAdminStatus;
         }
     }
   
I find it confusing to use ifAdminStatus as a type since ifAdminStatus is a 
well known MIB object from MIB-2. I think a different type would be more clear.
Would it be better to make this a leafref? This example was originally written 
when we had keyref but not leafref. Now that we have leafref, I think that 
would be a better example.

--

The notification example in section 9.9.6:

     notification link-failure {
         leaf if-name {
             type leafref {
                 path "/interfaces/interface/name";
             }
         }
         leaf index {
             type leafref {
                 path
                   "/interfaces/interface[name = current()/../if-name]"
                 + "/ifIndex";
             }
         }
     }

I find the use of ifIndex confusing because I expect it to be the key for
the interfaces table. But in this example, it is not a key. I think it would
be better to use a name other than ifIndex.

It might also be instructive to show a notification example that includes
an object from a list with more than one key.

--

If I want to have objects from more than one list in my notification, do I 
need put the the objects in different containers?

--

>From section 9.9.2:

   The predicates are only used when more than one key reference is
   needed to uniquely identify a leaf instance.  This occurs if a list
   has multiple keys, or a reference to a leaf other than the key in a
   list is needed.  In these cases, multiple leafrefs are typically
   specified, and predicates are used to tie them together.

This paragraph was not clear to me. I'm not sure that anything in the text
needs to be changed, maybe I just need to read an xpath book. Or maybe someone
could explain it to me in different words or with an example.

--

In SNMP notifications, an agent is allowed to append as many additional
objects as it considers useful to the end of the notification. This has
proved useful in many implementations. Can I do this in yang? I guess I 
can augment any notification and add whatever I want.

-David Reid

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 13 May 2009 09:09:37 +0200 (CEST)

Hi David,

David Reid <[email-masked]> wrote:
> I find it confusing to use ifAdminStatus as a type since
> ifAdminStatus is a well known MIB object from MIB-2. I think a
> different type would be more clear.  Would it be better to make this
> a leafref? This example was originally written when we had keyref
> but not leafref. Now that we have leafref, I think that would be a
> better example.

I want to show also some leafs which are not leafrefs, and I believe
we have some other examples of notifications with leafrefs.  So I
suggest we simply call the type "AdminStatus".

> be better to use a name other than ifIndex.

Ok, I will simply remove ifIndex from the examples in this section.

> an object from a list with more than one key.

No.

> could explain it to me in different words or with an example.

A predicate in the leafref path is the stuff inside the square
brackets.  There are some examples of using predicates in 9.9.6
(leafref usage examples).  If the leafref points to a single-keyed
list, you don't use predicates:

    leaf if-name {
        type leafref {

But if there's a list 'address' within the interface list, you need to
specify the values for both the interface name and the address ip:

    leaf address {
        type leafref {
        path "/interfaces/interface[name = current()/../if-name]"
           + "/address/ip";
        }
    }

The predicate is used to select the interface entry.

> can augment any notification and add whatever I want.

Yes, you can do this with augment.

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 13 May 2009 09:15:29 +0200

> suggest we simply call the type "AdminStatus".

Or admin-status to be consistent in writing style...

/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, 13 May 2009 12:06:20 +0200 (CEST)

> Ok, I will simply remove ifIndex from the examples in this section.

On second thought I changed this leaf to an admin-statues leaf.  One
example shows how a leafref is used to reference a non-key leaf, and I
think we should keep it.

So we get:

  list interface {
      key "name";
      leaf name {
          type string;
      }
      leaf admin-status {
          type admin-status;
      }
      list address {
          key "ip";
          leaf ip {
              type yang:ip-address;
          }
      }
  }

and the notification:

      leaf admin-status {
              + "/admin-status";
          }
      }
  }

An example of a corresponding XML notification:

  <notification
    xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
    <eventTime>2008-04-01T00:01:00Z</eventTime>
    <link-failure xmlns="http://acme.example.com/system">
      <if-name>eth0</if-name>
      <admin-status>up</admin-status>
    </link-failure>
  </notification>

/martin

---

From: David Reid <[email-masked]>
Date: Wed, 13 May 2009 11:04:18 -0400

>             path "/interfaces/interface/name";

If the leafref points to a leaf that is not the key, such as ifIndex in the
example from 9.9.6, do I use predicates? For example:

     leaf ifIndex {
         type leafref {
             path "/interfaces/interface/ifIndex";
         }
     }

-David Reid

---

From: David Reid <[email-masked]>
Date: Wed, 13 May 2009 11:07:30 -0400

I like this updated version of the example.

---

From: David Reid <[email-masked]>
Date: Wed, 13 May 2009 11:34:54 -0400

> > need put the the objects in different containers?

I guess my confusion is that I want the keys to always be encoded first. But
a leafref type in a notification points to a list entry but is not a list, so
the keys don't have to be encoded first. I don't think I'm saying this clearly,
let me try an example. Is the following example with items from 2 different 
lists in a notification correct?

module foo {

  namespace "http://www.example.com/foo";
  prefix "foo";

 list list1 {
   key "a";
   leaf a { type int32; }
   leaf b { type string; }
 }

 list list2 {
   key "x";
   leaf x { type int32; }
   leaf y { type string; }
  }

  notification test-notification {
    leaf a {
      type leafref {
        path "/list1/a";
      }
    }
    leaf b {
      type leafref {
        path "/list1/[a = current()/../a]/b";
      }
    }
    leaf x {
      type leafref {
        path "/list2/x";
      }
    }
    leaf y {
      type leafref {
        path "/list2[x = current()/../x]/y";
      }
    }
  }
}

XML encoding:

     <notification xmlns="..."><eventTime>...</eventTime>
       <test-notification xmlns="http://www.example.com/foo">
         <a>1</a>
         <b>some stuff</b>
         <x>2</x>
         <y>more stuff</y>
       </test-notification>
     </notification>

-David Reid

---

From: David Reid <[email-masked]>
Date: Wed, 13 May 2009 11:36:16 -0400

> suggest we simply call the type "AdminStatus".

Keeping an example with leafs which are not leafrefs is good. I like your
suggested change.

-David Reid

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 13 May 2009 22:31:21 +0200 (CEST)

>              path "/interfaces/interface/ifIndex";

Note that the path argument is a normal XPath epression.  When this
expression is evaluated, it will return all nodes called
/interfaces/interface/ifIndex.   If multiple 'interface' entries, you
will get multiple ifIndex nodes back.  In this particular example,
ifIndex might actually be unique across all instances, so there might
be just one entry with a given ifIndex value, but in general this is
not the case.  Consider this example:

   leaf my-admin-status {
       type leafref {
           path "/interfaces/interface/admin-status";
       }
   }

   <interfaces>
     <interface>
       <name>eth0</name>
       <admin-status>up</admin-status>
     </interface>
     <interface>
       <name>eth1</name>
       <admin-status>down</admin-status>
     </interface>
     <interface>
       <name>lo</name>
       <admin-status>up</admin-status>
     </interface>
   <interfaces>

Now, the value space for the leaf 'my-admin-status' is [up, down].
(If eth1 has admin-status 'up', the value space would have been [up]).

So a valid my-admin-status could be:

   <my-admin-status>up<my-admin-status>

Getting just this leaf in a notification isn't very usefulf, so
changing it into:

   leaf my-name {
       type leafref {
           path "/interfaces/interface/name";
       }
   }
   leaf my-admin-status {
       type leafref {
           path "/interfaces/interface[name = current()/../my-name]"
              + "/admin-status";
       }
   }

would give:

   <my-name>lo<my-name>
   <my-admin-status>up<my-admin-status>

which is more useful.

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 13 May 2009 22:43:32 +0200 (CEST)

> lists in a notification correct?

Yes, it is correct.

/martin

---

From: David Reid <[email-masked]>
Date: Thu, 14 May 2009 11:00:37 -0400

Thanks Martin, I think I understand this better now.

-David Reid