Subject: snmpconf Policy MIB: elements

From: "Robert Moore" <[email-masked]>
Date: Thu, 8 Mar 2001 15:46:00 -0500

Clearly the concept of an element is at the very
center of the Policy Management MIB.  But I'm having
a hard time getting my hands around this concept
I can break my questions down into three broad groups:

1. The Element Type Registration table

   In the discussion in Section 6.1, much of which
   is repeated back in the MIB module, I'm confused
   about the relationship between elements, element
   types, and entries in the table.  I think part of
   the problem is just bad terminology; for example,
   I think that "Note that agents may automatically
   configure elements in this table..." is really
   saying "...agents may automatically configure
   *entries* in this table...," where these entries
   correspond to element *types*, not to elements.
   The next few sentences blur the picture, however,
   by bringing in discover of *elements* (like the
   asynchronous notification of new elements like
   "card inserted" -- here this does seem to be
   talking about an element rather than an element
   type).  Elements exist in their own tables, not
   in this table.  So it's a bit confusing for them
   to come into the discussion at this point.

   Here's what I make of this table.  The first
   question is, am I right?  Second, can the document
   say whatever is right here a lot more clearly than
   it does?

   a. The entries in the table correspond to element
      types.  They can be created either via a
      management flow or by the agent.
   b. For each element type, the agent has a means of
      discovering elements of that type.  These means
      may be different for different types.
   c. For some element types, the agent will create
      a new element type entry in this table when it
      discovers the first element [instance] of that
      type.  Discovery of subsequent elements of the
      type will have no effect on the table.  (Or do
      these entries corresponding to "frequently used
      element types" exist all the time, even before
      the agent has discovered the first element of
      the type?)

2. Elements in general

   The first paragraph in Section 6.1 makes a
   distinction between what I'll term "single-table
   elements" and "multi-table elements".  Most of my
   element questions pertain to multi-table elements;
   they're below, under number 3.  I do have one
   question even for single-table elements, though.

   The question is, why is *any* columnar OID allowed
   to identify an element type, leading to the
   clumsy-sounding rule that to detect duplicate
   element types, the last arcs of their OIDs must
   be ignored?  Is there any reason the OID for a
   (single-table) element type can't be defined to be
   the first accessible column in the table, similar
   to how the RowPointer TC is defined?

3. Multi-table elements

   Here's where I really get lost.  Taking the
   example from Section 6.1, an entry in the ifTable
   and the entry in the dot3Stats table with the
   same value for ifIndex together make up one
   element.  For cases like this, where there's a
   second table that reuses ifIndex, it seems like
   the element type should correspond to the second
   table -- say, "dot3Interface".  But in other cases
   there is no second table: all the information that
   exists for an interface is in the ifTable.  In
   these cases it seems like the element type will
   have to be just "interface".

   The problem here seems to be that in some cases,
   "interface" and the ifTable function like an
   abstract superclass, while in other cases they
   function like a concrete class.  I'm not sure how
   to represent this in the Element Type Registration
   table.  If there's an entry there for "interface"
   (needed for the interface types that don't have a
   "second" table), and also one for "dot3Interface",
   then what does an instantiated dot3Interface
   correspond to?

      - an element of the type "interface"?
      - an element of the type "dot3Interface"?
      - an element of both types?
      - two elements, one of each type?

   It's also not clear what happens when there are
   multiple "second" tables, as there are in a number
   of standard MIBs (and even more so when you bring
   in vendor extensions to standard MIBs).  Does an
   element correspond to the union of all the table
   entries in the agent that share the same index
   values?  If so, what is its element type?  Without
   a clear answer to this question, the algorithm for
   detecting duplicate element types (strip off the
   last arc of the OIDs, and compare what's left)
   won't work.

   A third question relates to the various RowPointer
   objects in the MIB that point to multi-table
   elements.  As RowPointers, these objects must
   point to the first accessible object in a
   conceptual row.  But conceptual row in which table?
   The rows that together make up a multi-table
   element will share index values, but they don't
   share their tabular/columnar OIDs.  So these
   RowPointers will be different, depending on which
   of an element's tables they point to.

By the way, I apologize a little if any of this has
been discussed on the list over the past couple of
months, while I've been buried in PCIM Extensions.
But I don't apologize very much:  by the time we're
done, the information must be in a form where it's
communicated by the document alone, without reference
to any outside knowledge.  So think of me as an early
test case of a reader coming into this material cold.

Regards,
Bob

Bob Moore
Advanced Design and Technology
Application Integration Middleware Division
IBM Software Group
+1-919-254-4436
[email-masked]

---

From: Steve Waldbusser <[email-masked]>
Date: Thu, 08 Mar 2001 18:22:39 -0800

Hi Bob,

  You bring up some good questions. Let me try to clarify here and
figure out how to make the document more clear.

Robert Moore wrote:
>    *entries* in this table...,"

Exactly. And it's not bad terminology, it's wrong terminology - it was a
typo.

> where these entries

Yes.

>    type).

Yes again.

The talk about elements occurs for the following reason. 
   The 3 paragraphs starting with "Note that agents..." are dealing
   with elementType entries that come installed "out of the box". The
   agent might want to install some entries for convenience sake
   (saving some set requests), but there are a couple of reasons that
   are much more compelling:

   1) The agent might have specialized code that scans internal data
   structures for certain element types rather than doing a getNext
   walk; or,
   2) The agent might be able to register for a card-inserted
   interrupt or signal and learn of elements without polling.
 
   These reasons are much more compelling because they require
   specialized code per element type - stuff that ain't gonna happen
   automatically by decoding some new OID value. In other words, while
   I can teach an agent to walk a new table by downloading a new OID,
   I can't cause it to grow new code for these specialized
   techniques. So since the code is already hardwired, and thus the
   support for the elementType, the agent can hardwire the 
   elementTypeRegEntry and make everyone's life easier.

This wasn't intended to blur things by talking about elements but to
describe the pre-installed behavior of elementTypeRegEntries.

>  Elements exist in their own tables, not

A and B are correct, but C isn't.

The agent won't do discovery of elements that aren't listed in the
elementTypeRegTable. In most cases the manager writes an entry into the
table, in effect saying "I want to have some policies that act on
elements of the following type. Please discover and manage execution for
elements of this new type". So if ifEntry is not represented in the
table, policies will not be run on interfaces. Further, even if there
are no circuits at the moment, there can be a frCircuit entry in the
table that causes the agent to continuously check for new circuits.

>    to how the RowPointer TC is defined?

Maybe it could be, I was just trying to be careful. It was hard to
declare at the moment I was writing that text that: "the first
accessible column in the table will *always* be appropriate". On the
other hand, I really can't think of any reason why not.

>    element.  

Assume this baseline "normal" code (a filter):

    if (insubtree(elementName(), "ifEntry")
        && getvar("ifOperStatus.$0") == 1)
        return 1; // Match
    else
       return 0;

What I'm trying to say is the following code is also valid:

    if (insubtree(elementName(), "ifEntry")
        && getvar("ifOperStatus.$0") == 1
        && getvar("dot3StatsDuplexStatus.$0") == 2)
        return 1; // Match
    else
       return 0;

Note that the element type is ifEntry, and we are using the address of
ifEntry elements ($0), but we are using dot3StatsDuplexStatus as one of
the "attributes" of this element. We don't need to create an elementType
for dot3Entries.

Let me add that the agent doesn't need to know that this is happening.
It doesn't need to be set up to know that $0 will also index
dot3Entries. It just blindly replaces $0 with the current value of
ifIndex for elements of type interface. Only the script writer needs to
know which tables share the same index and can thus be modeled this way.

Maybe part of the problem is that the topic sounds complicated
("abstract superclass" and so on) and yet the mechanism is so blindingly
simple ("blindly replacing $0").

> For cases like this, where there's a
>    table -- say, "dot3Interface".

I don't see why this is so.

In fact, it is very important that the ifEntry type be registered
because it is the one that is guaranteed to discover all interface
instances (registering dot3Entry would only find a subset).

>   But in other cases

Ditto.

>       - two elements, one of each type?

You really only want to register ifEntry. If you *did* register both, I
suppose the answer would be "two elements, one of each type". More
concretely speaking, an entry in the dot3StatsTable would have a policy
executed twice on it, once as an interface and once as a dot3Interface.

>    last arc of the OIDs, and compare what's left)

I hope my answers above make this more clear. Just register ifEntry and
all will be fine. There will be no duplicates. You will be able to use
$0 as the index to attributes that are in the ifTable, the
dot3StatsTable, the Dsx1ConfigTable, or a private locIfTable.

If you were to register the "second" table (there's no law against it),
there would be no duplicate detection (the agent doesn't really know
enough to do such duplicate detection anyway).

>    of an element's tables they point to.

Again, don't register the "secondary" tables. But if you did, the roles
registered to the base element type will not be registered to the
secondary element type. So if you wanted to make this work (no reason
you would) you would have to register the same roleStrings to
dot3StatsIndex.7 as you did to ifIndex.7, and so on.

> test case of a reader coming into this material cold.

You're off the hook on both counts. It hasn't been discussed and even if
it had, you're right: it needs to be readable by people who will never
participate in our discussions.

Unfortunately in this message I haven't proposed any wording changes to
help out. Can I propose that once I get you on the right track, that you
might be able to help by pointing out what text set you on the wrong
path or with suggestions on a more clear way to describe this?

Thanks,
Steve

---

From: Jon Saperia <[email-masked]>
Date: Fri, 09 Mar 2001 07:41:49 -0500

Bob/Steve,

The conversation about Element discovery is a good one. I have a couple

> table that causes the agent to continuously check for new circuits.

I agree with Steve in terms of the importance of allow for 'specialized'
code. One rewording I would like to help avoid the problem Steve pointed
out. From Section 5.2 Element Discovery on page 9:

Change:

> For example, the ifTable and the dot3Stats table both contain
> attributes of interfaces and share the same index (ifIndex),
> therefore they can be modeled in this model as one element
> type.

to:

For example, the ifTable and the dot3Stats table both contain
attributes of interfaces and share the same index (ifIndex),
therefore they should be modeled in this model as one element
type.

I think 'should' more clearly conveys the intent and level of what an
elment type is intended to be.

Also from page 9:

> The Element Type Registration table is used for the manager to
> learn what element types are being managed by the system and
> to register new types if necessary. An element type is
> registered by providing the OID of an SNMP object (i.e.,
> without the instance). Each SNMP instance that exists under
> that object is a distinct element. The address of the element
> is the index part of the discovered OID. This address will be
> supplied to policy filters and actions so that this code can
> inspect and configure the element.

Change 'used for the manager' to used by the manager.

We probably also want a word or two in the table definition that says
talks about interactions where a Manager attempts to delete or modify a
row that has been 'discovered' by an agent. I would bet the behavior
that one would want is that the manager overrides native behavior for
the length of time of pmElementTypeRegStorageType.

Thanks,
/jon
--

Jon Saperia		     [email-masked]
			     Phone: 617-744-1079
			     Fax:   617-249-0874
			     http://www.jdscons.com/

---

From: Steve Waldbusser <[email-masked]>
Date: Fri, 09 Mar 2001 09:16:24 -0800

> elment type is intended to be.

I'm a bit leery of this. The agent doesn't participate in this (it's
just blindly applying element addresses). The manager who sets up the
elementTypeRegTable only indirectly participates in this (by choosing
not to register the dot3StatsTable - but in fact this is really directed
by the script writer). The entity that does this is the human script
writer who chooses to borrow $0 from interface elements and apply it to
any other table indexed by ifIndex, conceptually extending the interface
element to contain a whole new list of attributes.

In other words, this isn't an instruction to the implementor, this is an
instruction to the user that is unenforceable by the agent or manager.
I'm leery of dictating to the script writer how they should design their
script, particularly when it would still work the other way. It's kindof
like if the C spec said that programmers should not use goto.

The text was originally supposed to point out a modelling opportunity
that script writers have - a modeling practice that I think will become
an idiom.
 
> Change 'used for the manager' to used by the manager.

Done.

> the length of time of pmElementTypeRegStorageType.

The semantics of the StorageType object cover this - and the answer is
that the behavior depends on the value of storageType. Mostly I think
that readOnly or permanent will be used.

Steve

---

From: Jon Saperia <[email-masked]>
Date: Fri, 09 Mar 2001 12:39:24 -0500

> element to contain a whole new list of attributes.

We are talking about new code here. The agent should not 'blindly
apply element addresses' - OIDs. 

> like if the C spec said that programmers should not use goto.

I think this should be an instruction ot the implementor (those that
choose to autopopulate the element table - which I think is a good
thing). I could see a script writer doing this. I have more envisioned
it to be a part of the rest of the management sub system on the device.
That is they should know what to register - after all the info is pretty
easy when doing the agent code.

> that readOnly or permanent will be used.

I agree 100% with the StorageType object dictates this. My point in
raising the issue is that may not be obvious to many readers.

Thanks,
/jon
--

---

From: Pablo Halpern <[email-masked]>
Date: Fri, 09 Mar 2001 12:46:16 -0500

>other hand, I really can't think of any reason why not.

For that matter, why does a columnar OID need to be specified at all? Why 
not just the table or tableEntry OID?  Doing a getnext on a tableEntry OID 
will return the first row of the first accessible column of the table, 
right?  Then there is no need to strip off the last arc of the OID.

There is one reason I can think of for requiring a columnar OID and 
allowing *any* column to be specified: holes.  Some columns may have holes 
in them. Using these columns's OIDs for element discovery would cause some 
elements to be missed. Ain't SNMP wonderful? :-(

>the "attributes" of this element. We don't need to create an elementType

This makes me wonder, do we want to run every policy filter over every 
discovered element?  Won't most policies be specific to certain element 
types?  Here's an idea (although it might be too late for it):

Add a column to the pmPolicyTable (e.g. pmPolicyElementPrefix) that acts as 
a "pre-filter" for a policy.  Only elements that match the specified 
prefix  will require running the filter. If the prefix is empty, then the 
filter would be run on all element types.  This would have three beneficial 
effects:

1. improved performance (because filters will not need to be run as often, 
especially if the agent is properly optimized).

2. Simpler filter code (drastically reduce need to call insubtree()),

3. (Addressing the confusion about multi-table element types), it would 
encourage the user to consider what really makes an element. In the above 
example, the pmPolicyElementPrefix value would probably contain the ifEntry 
OID. The user would hopefully realize that there is no need to also match 
dot3StatsEntry.  Even if he doesn't the policy action would still run only 
once per element because only ifEntry would actually trigger it.

- Pablo
---------------------------------------------------------------------
Pablo Halpern                                    [email-masked]
http://www.halpernwightsoftware.com

---

From: Steve Waldbusser <[email-masked]>
Date: Fri, 09 Mar 2001 18:23:44 -0800

> apply element addresses' - OIDs.

(I don't understand the 1st sentence).

Maybe I shouldn't use provocative words like "blindly apply", but it's
accurate. If my script tells the agent to append the index of an ifEntry
to an object in the dot3StatsTable, the agent should just do it
(blindly). It's just appending another subid to an OID. It doesn't know
about table structure so it couldn't complain even if it wanted to.

> easy when doing the agent code.

Bob's 1st question was the one the refers to autopopulation. I think
we're discussing his 3rd question which deals with modeling a single
element type even though the information is in separate tables by virtue
of the fact that the indexes are shared. This is a decision for the
PolicyScript author to make.

> raising the issue is that may not be obvious to many readers.

OK. How about the following text:

"Note that the disposition of agent-installed entries is described by
the pmPolicyStorageType object."

Steve

---

From: Steve Waldbusser <[email-masked]>
Date: Sat, 10 Mar 2001 10:01:24 -0800

> right?  Then there is no need to strip off the last arc of the OID.

You don't know which is the first accessible column so you have to
depend on getnext to tell you. Normally when we getnext through a column
we give as a constraint the column oid which is the root of the subtree
- this algorithm is different, you have to retrieve an OID which will
become the constraint OID. In this case you'd say, if I have OID with N
subids, do a getnext and save the N+1 subids of the response oid and
then walk the subtree constrained by these N+1 subids. So the answer was
"this is too complex to write without confusing many readers". Maybe I
could define it in policyScript code.

Of course there are benefits to not having the columnar OID. One is that
the de-duplication text could be removed (The paragraph beginning with
"Before registering ..."). The other is that I fear that with the
columnar subid included that it is too suggestive that a getnext walk is
the only way (or even the suggested way) to do discovery. It would also
be easier for the policy script to do a match on the element type.

Now that I think about it I have a better answer: 
There's no reason I need to describe the discovery mechanism as a walk
of a subtree. If we just specify up to the "entry" part of the oid (e.g.
ifEntry), then it can just speak of "all instances of xxxEntry" without
getting caught up in any description of the algorithm to retrieve them
with getnext.

> elements to be missed. Ain't SNMP wonderful? :-(

That's one of the things I was originally uncomfortable with which led
me to say *any* columnar OID. Another was what if that column isn't
implemented by a particular agent. I realize now that practically
speaking, the agent will be in a better position to choose the column
than the manager.

> once per element because only ifEntry would actually trigger it.

Yes, this is one of the proposals I plan to make in Minneapolis. Those
of you in the New Hampshire meeting (a long time ago) will remember we
discussed this topic but didn't act on it. I now think this is really
important.

Steve