Subject: [netmod] module capabilities

From: Andy Bierman <[email-masked]>
Date: Tue, 17 Feb 2009 06:50:07 -0800

Hi,

Consider the example below.
Does the agent advertise capabilities for both module
revisions for 'Z'?  Or just the highest value?

Does the draft need some text that says a manager must inspect
all the module capabilities for a given module-name,
because there may be more than 1?

Advertising N versions is confusing, but advertising 'Y',
which uses an unadvertised revision of 'Z' is also confusing.

The agent is only required to support 1 version of the 'foo'
container, so which one is it?

What happens when module X tries to refine leaf y-A,
(that is defined with module Y's notion of type Z:A)?
Module Z is using a different typedef for y-A.
Is this an error? Does one version win out over the other?
Does an implementor just choose whatever they want to do?

Supporting multiple versions of the same YANG construct
within the same module is confusing.  Important semantic changes
can be effectively buried in nested revision differences.

Andy

-------------------------------

module X {
    ...
    revision "2009-02-17" { description ""; }

    import Y {
       prefix Y;
       revision "2009-01-01";
    }

    import Z {
       prefix Y;
       revision "2009-02-01";
    }

    leaf X-a { type Z:A; }

    uses Y:YAZ {
      refine y-A { ... }
    }
}

module Y {
    ...
    revision "2009-01-01" { description ""; }

    import Z {
       prefix Y;
       revision "2008-12-12";
    }

    leaf Y-a { type Z:A; }

    grouping YAZ {
       leaf Y-a { type Z:A; }
    }
}

module Z {
    ...
    revision "2009-02-01" { description ""; }

    typedef A {
        <range-removed>
    }

    container foo {
        ...
        leaf new-leaf { ... }
    }
}

module Z {
    ...
    revision "2008-12-12" { description ""; }

    typedef A { ... }
    container foo { ... }
}

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 17 Feb 2009 16:18:25 +0100 (CET)

Andy Bierman <[email-masked]> wrote:
> revisions for 'Z'?

No.

> Or just the highest value?

It would advertise Z only if it implements the container 'foo', and it
would advertise the version it implements.

"library modules" are not advertised.

> because there may be more than 1?

Never more than 1.

> Does an implementor just choose whatever they want to do?

All type- and grouping references are resolved at "compile time".
Thus, leaf Y-a is always the same in module X, regardless of which
version of Z is imported by module X, or other modules.

/martin

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 17 Feb 2009 17:42:55 +0100

Hello,

> "library modules" are not advertised.

BALAZS:
- I assume that library modules are visible in the monitoring schema. True?
- I assume that all used versions of library modules (YAMs) are available in the monitoring 
schema. True?
- I assume that in the monitoring schema it will be possible to find out if a YAM is used just 
as a library or if its data nodes are implemented as well. True?
Balazs

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 17 Feb 2009 18:17:12 +0100 (CET)

> - I assume that library modules are visible in the monitoring schema. True?

Yes.  All modules are listed in the 'schema' list.

> - I assume that all used versions of library modules (YAMs) are available in
>   the monitoring schema. True?

Yes.

> - I assume that in the monitoring schema it will be possible to find out if a
>   YAM is used just as a library or if its data nodes are implemented as
>   well. True?

Yes, since the capabilites from hello are repeated in the 'capability'
leaf-list.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Tue, 17 Feb 2009 13:44:53 -0800

> version of Z is imported by module X, or other modules.

thanks.
Implementation makes a little more sense now.

This is not intuitive for the module 'X' data model writer,
who will need to know that objects from groupings
may not have the same typedef semantics as objects
that are not from groupings.  It is critical to follow
the prefixes.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Tue, 17 Feb 2009 14:01:45 -0800

Hi,

What about multiple imports or includes within the same [sub]module?

The text in 7.1.6 and 7.1.7 seems to suggest the opposite.

IMO, it MUST be an error to directly include or import
multiple revisions of the same [sub]module.
I think this was the consensus at the interim.

module X {
    ...

    import Y {
       prefix Y;
       revision "2009-01-01";
    }

    import Z {
       prefix Z1;
       revision "2009-02-01";
    }

    import Z {
       prefix Z2;
       revision "2008-12-12";
    }

    leaf a1 { type Z1:A; }

    leaf a2 { type Z2:A; }

    uses Y:YAZ {
      refine Y-a { ... }
    }
}

This is just complexity waiting to fall off the slippery slope.
The data modeler must be forced to choose one version of 'Z' to import.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 17 Feb 2009 23:19:32 +0100 (CET)

> I think this was the consensus at the interim.

Yes, I think you're right about this being the consensus.

>   leaf a2 { type Z2:A; }

But note that there are not really any theoretical problems with
this; just look at the two leafs a1 and a2 above.  They clearly use
different types, and each type is resolved (and fixed) when it is
used.

If we don't allow multiple imports, there is a workaroud by using
submodules:

   submodule s1 {
     belongs-to Y { ... }

     import Z {
       prefix Z1;
       revision "2009-02-01";
     }

     typedef A-s1 {
       type Z1:a;
     }
   }

   submodule s2 {
     belongs-to Y { ... }

     import Z {
       prefix Z2;
       revision "2008-12-12";
     }

     typedef A-s2 {
       type Z2:a;
     }
   }

   module Y {
     ...
     include s1;
     include s2;

     leaf a1 { type A-s1; }
     leaf a2 { type A-s2; }
   }

Multiple includes will not work though.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Tue, 17 Feb 2009 14:34:49 -0800

> Multiple includes will not work though.

This is one of the reasons I was against adding import-by-revision
at the interim -- sub-modules can each have different revisions
for all their imports.

IMO this breaks the concept that sub-modules are merely
physical partitions of a main module into multiple files.
Instead they are really full-blown modules that happen
to all use the same XML namespace.

(BTW, are submodules advertised in the module capabilities?
IMO this is too much detail, but what if the include does
not specify a revision, like in your example)?

Andy

---

From: Andy Bierman <[email-masked]>
Date: Fri, 20 Feb 2009 17:35:39 -0800

> "library modules" are not advertised.

module A {
   ...

   import B { prefix B; }
   ...
   container foo {
     uses B:Group1;
   }
}

I ran into some implementation problems on this one.
Consider module 'A' which imports 'B'.  The manager will
know the correct version of 'A' to use because it will
be in the <capabilities>.

But the manager has N versions of 'B' available.
Module B just has groupings and typedefs in it,
and since it is a library module, it is not advertised at all.

IMO, it takes a major commitment to use import-by-revision,
making sure the revision dates line up exactly right.
It may be left out often, in which case (of course)
the manager is back at square one, not knowing which
version of 'Group1' to use.

There seems to be no solution possible without the agent advertising
the library file 'B', but there might be N active versions
of 'B' within the agent, so that doesn't always work either.
But if the agent implements 1 or 2 of 10 versions it would help.

The only other solution seems to be to make the revision
mandatory, and the WG consensus is against that.

I think the draft should be changed to allow the agent to
advertise all the modules it implements if it wants.
More info helps debugging.  It also helps applications
put up more intelligent dialog boxes to pick the right version.

I never understood this CLR from the start,
and now in implementation, it is getting in the way.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 21 Feb 2009 12:07:33 +0100 (CET)

> advertise all the modules it implements if it wants.

So we should change this text:

  Modules that do not contribute any data definitions, rpcs,
  notifications, or deviations to the device are not advertised in the
  <hello> message.

with s/are not/SHOULD NOT/
     s/are not/MAY be/

?

You're reasoning works fine for pure library modules, but if B in your
example also define some data definition nodes, and your agent does
not implement them, it would be wrong to advertise it.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Sat, 21 Feb 2009 07:28:16 -0800

> not implement them, it would be wrong to advertise it.

It is not fool-proof, but if there is one version of the library module
then it solves the problem completely.  If there are objects in the
module though, then the agent will advertise more than one version of it.

The logic at it stands now is  already broken.
What if there are objects that are conditional
due to false 'if-feature' or 'when' statements?
I can advertise module 'A', and the submodules of 'A'
can pull in all kinds different definitions via 'uses'
and none of it may be visible to the manager.

IMO, the module capability URI is something of a hack,
and loading it down with CLRs doesn't change that.
In any event, I don't see how giving more information to
the manager impair interoperability.  It seems to only
help in most scenarios.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Sat, 21 Feb 2009 08:09:26 -0800

> not implement them, it would be wrong to advertise it.

Perhaps you could add some text in the draft that just
says that usage of groupings and typedefs across modules
or sub-modules needs to be done carefully, if those definitions
ever need to be changed during the lifetime of the data model.

I think an example module with a grouping would help.
(e.g., version 1 has a leaf, version 2 adds a leaf).
When import/include by revision is complete (no missing
revision dates at all), it works perfectly, and is even
quite impressive.  No matter how you scramble the definitions,
everything just works.

But as soon as the 'revision-date chain' is broken, it
all starts to fall apart.  Keeping typedefs/groupings in
a separate module from any objects/rpcs/notifications
will certainly help.  This concept has already proven
useful in SMIv2, and will really be important in YANG.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 21 Feb 2009 22:36:22 +0100 (CET)

Andy Bierman <[email-masked]> wrote:
> then it solves the problem completely.

Yes.

> If there are objects in the
> due to false 'if-feature'

The agent advertises the module uri with the 'features' parameter.

> or 'when' statements?

Objects covered by 'when' statements are implemented, but might not be
present due to the dynamic nature of the when expression.

> the manager impair interoperability.  It seems to only

So if my proposals for changed text was not what you were looking for,
could you suggest some text?

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 21 Feb 2009 22:39:47 +0100 (CET)

> useful in SMIv2, and will really be important in YANG.

Right.  But in one case it might work better w/o import by revision;
with a module like IANAifType-MIB.  OTOH, maybe this kind of
information would be better defined using identities in YANG.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Sat, 21 Feb 2009 15:02:19 -0800

> The agent advertises the module uri with the 'features' parameter.

right -- forgot about that.

(BTW, is there any text about what the agent does if
it can no longer support a feature it gave to a
currently open session?  Drop the session?  Resend the <hello>?)

> could you suggest some text?

I should have looked closer.
It looks like multiple choice.
I prefer:

   s/are not/MAY be/

How about adding a sentence that says the agent SHOULD omit
any redundant module capability information (without going into details
or CLRs)?

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Sun, 22 Feb 2009 21:45:06 +0100 (CET)

Hi,

> currently open session?  Drop the session?  Resend the <hello>?)

I think this is a general NETCONF issue - what if an agent no longer
can support a capability it advertised?  We have talked about this in
the discussions about the monitoring draft.

> It looks like multiple choice.

Ok.

> any redundant module capability information (without going into

I'd be hesitant to add this, because I think people might wonder what
was meant with the word "redundant", and different implementors might
interpret this differently.  We should aim for clear rules about which
uris MUST and MUST NOT be advertised, and say that the agent MAY
advertise anything else.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Sun, 22 Feb 2009 12:58:58 -0800

> uris MUST and MUST NOT be advertised, and say that the agent MAY

good -- leave it out.

another detail?
what about submodules?
Leave that for the monitoring draft, right?
(It would require even more variants of
the module-capability-URI.)

Andy