Subject: snmpconf capMatch and capabilities

From: Jon Saperia <[email-masked]>
Date: Thu, 15 Mar 2001 12:17:51 -0500

This note was prompted by Steve's recent post and commentary about the
Capabilities table. It is not a point-by-point response since we come at
this from different perspectives. His comments show that there are
places where wording needs to be fixed. Additional thinking and
discussions have shown that there are some modifications that are needed
for capMatch and Capabilities table. I posted a note last week about
some specific changes that will be summarized in the final section of
this note which is divided into the following sections:

     I. Comments on capabilities and why we need flexibility in their
        expression and why they should be expressed as extant OIDs.
    II. Relationship of capMatch to the Capabilities table.
   III. Modifications/corrections to the Capabilities table.

I. Comments on capabilities and why we need flexibility in their
   expression and why they should be expressed as extant MIB OIDs:

     1. Some elements (such as interfaces) will have different
     capabilities. If we do not have both capabilities and the capMatch
     function, we would have to overload roles so say which elements
     could be used as targets of a particular policy based on capability
     described in roles (very messy). In the absence of this or the
     approach we currently have of using both capMatch and a flexible
     Capability Table, policies would fail on a significant number of
     targets. One important purpose of including both capMatch and a
     fully fleshed out Capability table is to reduce the number of
     possible policy failures and improve the fault diagnosis and
     likelihood of repair when they do occur.

     2. Even single OIDs can represent a capability and be
     modified. This facility was added in the table last summer based on
     conversations on this email list previously posted with Andrew
     Smith and others. This is accomplished via the ModificationOID
     facilities in the table. See the modifications section of this
     email for additional suggested changes.

     Capabilities are dynamic, can change frequently and often can not be
     'pre-assigned' much as we would like:

         A. They are dynamic in that they can come and go as cards come
         and go. In this sense, capabilities can be different between
         different instances of cards. A good example of this is the
         DiffServ domain. A vendor may release a card with 0C-12 ports
         on it and later either upgrade the hardware, firmware, software
         or any combination to provide new or better queuing mechanisms
         or extensions to standards.  This type of difference is not
         restricted to DiffServ. In the routing area, there are
         differences in the controls between one vendor and
         another. Many are common, it is the differences that are
         'interesting'. 

         B. Capabilities, to some extent like roles and element
         discovery types, can be defined by managers, thus my recent
         suggestion that the table be made read-create. Not all
         instances of an element type may have identical
         capabilities. We should allow instance level restriction as
         described above.

     3. To efficiently allow transfer of policies or related sets of
     polices to devices, managers must be able to know, just as they
     know element types, what the capabilities are for each element
     type. Each element type may have several different capabilities for
     each instance of the element type. This is not due to the
     variability previously described but due to the fact that just as
     we can have several roles for each element, there may be different
     capabilities used for each role. For example configuration of
     DiffServ parameters in the Quality of Service domain and
     configuration of security parameters for VPN service might both be
     needed on the same element. The [SNMPCONF] system currently
     supports this and will need full expression of capabilities in
     order to correctly and efficiently send policies to the managed
     device.

     4. Steve commented: "It is a bad idea to suggest that capabilities
     OIDs map to base OIDs of tables or MIBS or that capabilities are
     tied to the implementation of a MIB. While it's true that many
     times we're interested in whether we'll be able to set a particular
     MIB variable, often we need something different." Actually direct
     connection to MIB Objects is exactly what we want:

         A. The suggestion that capabilities should be tied to some
         other construct other than a MIB object is counter to our
         work. We configure things with MIB Objects and we monitor them
         with the same. The capability table indicates what the
         restrictions are on MIB Objects. Since this is the SNMPCONF
         work, and eventually our configuration activities will 'touch'
         MIB Objects. The best way to express availability is to use 
         MIB Object OIDs. As previously noted, we may sometimes need to
         express different capabilities on different elements of the
         same element type.

         B. A static IANA-based OID for registration of capabilities
         would have the following unattractive properties:
               a. Take a long time to get agreement on (if ever).
               b. Take a long time to get through the process.
               c. Would take some time to modify since changes would
                  require consensus.
               e. Would not be sufficiently expressive to deal with
                  instance level differences.
               f. Would not be sufficiently expressive to deal with
                  vendor and model differences within vendors.
               g. Is an inappropriate place to force standardization.

         We (the IETF) standardize some external behaviors, like PHBs in
         DiffServ or what an LSA should look like in the routing
         area. To some degree, we standardize configuration, but vendors
         will always want new capabilities and features to realize
         standard behavior or new behaviors as a way of differentiating
         their products from the competition. It is operationally
         naive to think this will not happen and provide for these
         differences in the system we are creating.

In summary, a greatly abbreviated MIB such as the one Steve suggests
would not meet our requirements. A standard set of capabilities for each
technology is not likely to be usefully defined in a timely fashion in
any working group. They (capabilities) are just not that static or
constant. Such a process would greatly slow down our progress. This does
not mean that future collections of OIDs that express capabilities could
not be created, agreed to and given a single IANA number (though I think
a base OIDs would be fine and so is not needed).

II. Relationship of capMatch to the Capabilities table.

A number of Steve's comments stem from two areas that have not yet been
clearly detailed in the current draft. Below is a clarification of the
relationship of the capMatch function to the capabilities table: 

   The capMatch function (optionally present in the filter script), will
   search the information in the capabilities table for the 'longest'
   match for the OID specified in the script. This longest match search
   is necessary to ensure that possible exclusions or restrictions are
   found. A secondary index in the Capabilities table, pmCapabilitiesOID
   is the 'base' OID that can be used to speed searches.

In order to make use of the Capabilities table, capMatch will have to do
more work than is currently specified. In addition to the inclusions and
exclusions described above, capMatch will also have to compare values in
the policy script with pmCapabilitiesModificationType and
pmCapabilitiesModificationValue information if the
pmCapabilitiesModificationType object is other than null to ensure
errors do not occur.

III. Modifications/corrections to the Capabilities table.

The second area that prompted comments was ambiguity in some of the
description clauses. Below is the capabilities table from out 05
draft. It has the following modifications:

       1. Is now read-create to allow managers to define capabilities
       that might not have been 'auto-registered' by an agent.

       2. Many of the descriptions have been modified to provide
       additional clarity.

       3. pmCapabilitiesOID replaces pmCapabilitiesType. This is more
       descriptive of the object.

       4. pmCapabilitiesOID is added to the INDEX of the table to
       improve retrieval efficiency for both the capMatch function and
       managers.

       5. The value 'unsupported(0)' has been removed from the
       pmCapabilitiesModificationType. It is no longer needed due to
       modification of the pmCapabilitiesSubType object that has been
       renamed the pmCapabilitiesSubType to pmCapabilitiesInclude.

       6. Modified pmCapabilitiesEntry to make clear when entries are
       added to or deleted from the system and what a manager should do
       since the table is now read-create.

       7. Removed reference to inherent since we can add capabilities
       over time.
       
Suggestions I made last week for this table are either included or
modified in this version which is what I suggest we base our further
discussion on.

-- Capabilities table

-- The pmCapabilitiesTable contains a description of
-- the capabilities of a system so that policies can
-- differentially apply based on capabilities and so that
-- management stations can learn of an agent's capabilities and
-- differentially install policies based on the capabilities.

pmCapabilitiesTable OBJECT-TYPE
    SYNTAX      SEQUENCE OF PmCapabilitiesEntry
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
         "The pmCapabilitiesTable contains a description of
         the capabilities of the system.

         Note that it is not necessary to list all OIDs that domain,
         mechanism and implementation specific MIB Modules support, just
         the base OID if the implementation is a fully compliant
         one. This OID is specified in the pmCapabilitiesOID object. If
         the implementation is not fully compliant, then additional rows
         will exist in the table that list the limitations or
         enhancements."
    ::= { policyMgt 6 }

pmCapabilitiesEntry OBJECT-TYPE
    SYNTAX      PmCapabilitiesEntry
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
         "The description of a capability or limitation of a capability
         of the system. An entry will exist for each domain, mechanism,
         and instance-specific ability the system has. In the case of
         capability with no domain, mechanism or implementation specific
         extensions, the pmCapabilitiesInclude object would have a value
         of 1 and all other columns may be null. There would be no need
         for further rows in this table for restrictions or
         exclusions. An example of this would be the for a system that
         had the full set of configuration capabilities for OSPF as
         specified in OSPF MIB Module. The value of the
         pmCapabilitiesOID would be '1.3.6.1.2.1.14'.

         Additional rows will exist that contain additional
         features (inclusions) missing features (exclusions) or
         modifications to the pmCapabilitiesOID as needed. Details of
         these expanded or restricted capabilities are described in the
         pmCapabilitiesModificationOID, pmCapabilitiesModificationType,
         pmCapabilitiesModificationValue, and
         pmCapabilitiesModificationString objects.

         Note for additional refinement. In some cases, it may be
         necessary to express limitations on elements for a specific
         capability. These restrictions can be the result of version or
         other differences of hardware and software elements of a
         system. These differences should be expressed with additional
         entries in this table for the pmCapabilitiesOID with
         pmCapabilitiesInclude and following columnar objects filled in
         as necessary. Note that both the pmCapabilitiesOID and
         pmCapabilitiesModificationOID can represent capabilities at the
         instance level of granularity if necessary." Implicit in this
         feature is the ability to have values in pmCapabilitiesOID that
         are instance level or anywhere further up the OID tree."
    INDEX       { pmCapabilitiesIndex, pmCapabilitiesOID }
    ::= { pmCapabilitiesTable 1 }

PmCapabilitiesEntry ::= SEQUENCE {
    pmCapabilitiesIndex              Unsigned32,
    pmCapabilitiesOID                OBJECT IDENTIFIER,
    pmCapabilitiesInclude            OBJECT IDENTIFIER,
    pmCapabilitiesModificationOID    OBJECT IDENTIFIER,
    pmCapabilitiesModificationType   INTEGER,
    pmCapabilitiesModificationValue  Integer32,
    pmCapabilitiesModificationString OCTET STRING
}

pmCapabilitiesIndex OBJECT-TYPE
    SYNTAX      Unsigned32
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
         "A unique index for this entry."
    ::= { pmCapabilitiesEntry 1 }

pmCapabilitiesOID OBJECT-TYPE
    SYNTAX      OBJECT IDENTIFIER
    MAX-ACCESS  read-create
    STATUS      current
    DESCRIPTION
         "This can be a base OID of a mib module or any subtree or any
         single object type or object instance."
    ::= { pmCapabilitiesEntry 2 }

pmCapabilitiesInclude OBJECT-TYPE
    SYNTAX      INTEGER {
                    exclude(0),
                    include(1),
                    modify(2)
                }
    MAX-ACCESS  read-create
    STATUS      current
    DESCRIPTION
         "This value indicates whether the capability identified by
         pmCapabilitiesOID is included or excluded as a capability of
         the system. If the remaining columnar objects are null, then
         there are no modifications to this declaration. If the
         pmCapabilitiesModificationOID has a value, then the remaining
         columns of the row describe the modification. Several rows may
         be needed to fully express, extensions, restrictions or
         exclusions to a pmCapabilitiesOID object. This will depend on
         the number of object types below the pmCapabilitiesOID in the
         MIB tree, and the number of variations necessary. Note that it
         is not required to specify every instance in this table. The
         only appropriate time for instance level entries is for
         instance level variations from the system wide capabilities
         expressed by other rows of the table."
    DEFVAL { include }
    ::= { pmCapabilitiesEntry 3 }

pmCapabilitiesModificationOID OBJECT-TYPE
    SYNTAX      OBJECT IDENTIFIER
    MAX-ACCESS  read-create
    STATUS      current
    DESCRIPTION
         "The OID of the object or instance of the object that is either
         not supported, supported with one or more limitations, or
         expanded. If this columnar object is other than null then there
         must be at least an entry in pmCapabilitiesInclude. The
         pmCapabilitiesModificationType must also have a value if the
         value of pmCapabilitiesInclude is modify(2). Exclude would mean
         that this and all objects below this in the tree are excluded
         so it does not make sense to modify them. Include would add
         capabilities not in a standard and points to objects or
         portions of a vendor tree that extend a base capability. If
         modifications are needed to that base, they would appear as
         additional row entries in this table. This condition could be
         the result of differences in implementation by a vendor of
         features from one model to the next.

         Note pmCapabilitiesModificationOID objects need not only be a
         leaf node or scalar objects. If an entire table is not
         supported, this value can be the base OID for the table.

         To continue the OSPF example from the pmCapabilitiesEntry. If
         an implementation did not support Virtual Interfaces, the value
         of pmCapabilitiesModificationOID would be '1.3.6.1.2.1.14.9'
         which represents the ospfVirtIfTable. The value of
         pmCapabilitiesInclude would be exclude(0). The
         pmCapabilitiesModificationType and
         pmCapabilitiesModificationValue objects for this row of the
         table would be null."
     ::= { pmCapabilitiesEntry 4 }

pmCapabilitiesModificationType OBJECT-TYPE
    SYNTAX      INTEGER {
                    restricted(1),
                    additional(2),
                    addvalue(3),
                    maxlimit(4),
                    minlimit(5)
                }
    MAX-ACCESS  read-create
    STATUS      current
    DESCRIPTION
         "A value of 1 indicates that the OID
          is supported but with restricted values.
          These constraints are described in the
          pmCapabilitiesModificationValue and
          pmCapabilitiesModificationString objects. A value of
          2 indicates a vendor specific extension to a standard.
          The OID of the new object is pmCapabilitiesModificationOID.
          For some implementations, additional functions may be
          provided. addvalue indicates that this row of the table
          describes an additional value that the object can take.
          The specific value is in the pmCapabilitiesModificationValue.
          The values of 4 and 5 indicate restrictions or the removal
          of restrictions for the object identified."
    ::= { pmCapabilitiesEntry 5 }

pmCapabilitiesModificationValue OBJECT-TYPE
    SYNTAX      Integer32 (0..2147483647)
    MAX-ACCESS  read-create
    STATUS      current
    DESCRIPTION
         "A value of 1 in the pmCapabilitiesModificationType will be
         further modified by a single integer value in this object that
         corresponds to enumerated integer values that are not supported
         by the system for the object that is identified in this
         row. This value can also represent the min and max limit values
         in the pmCapabilitiesModificationType object. When the
         pmCapabilitiesModificationType has a value of (3) addvalue, the
         pmCapabilitiesModificationValue will contain the value of the
         new enumeration the system has. The
         pmCapabilitiesModificationString should be used to describe
         this capability."
    ::= { pmCapabilitiesEntry 6 }

pmCapabilitiesModificationString OBJECT-TYPE
    SYNTAX      OCTET STRING
    MAX-ACCESS  read-create
    STATUS      current
    DESCRIPTION
         "Any additional details or description or parameters needed."
    ::= { pmCapabilitiesEntry 7 }

Thanks,
/jon

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