tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 3512


Configuring Networks and Devices with Simple Network Management Protocol (SNMP)

Part 2 of 4, p. 9 to 41
Prev RFC Part       Next RFC Part


prevText      Top      Up      ToC       Page 9 
3.  Designing a MIB Module

   Carefully considered MIB module designs are crucial to practical
   configuration with SNMP.  As we have just seen, MIB objects designed
   for configuration can be very effective since they can be associated
   with integrated diagnostic, monitoring, and fault objects.  MIB
   modules for configuration also scale when they expose their notion of
   template object types.  Template objects can represent information at
   a higher level of abstraction than instance-level ones.  This has the
   benefit of reducing the amount of instance-level data to move from
   management application to the agent on the managed element, when that
   instance-level data is brought about by applying a template object on
   the agent.  Taken together, all of these objects can provide a robust
   configuration subsystem.

   The remainder of this section provides specific practices used in MIB
   module design with SMIv2 and SNMPv3.

Top      Up      ToC       Page 10 
3.1.  MIB Module Design - General Issues

   One of the first tasks in defining a MIB module is the creation of a
   model that reflects the scope and organization of the management
   information an agent will expose.

   MIB modules can be thought of as logical models providing one or more
   aspects/views of a subsystem.  The objective for all MIB modules
   should be to serve one or more operational requirements such as
   accounting information collection, configuration of one or more parts
   of a system, or fault identification.  However, it is important to
   include only those aspects of a subsystem that are proven to be
   operationally useful.

   In 1993, one of most widely deployed MIB modules supporting
   configuration was published, RFC 1493, which contained the BRIDGE-
   MIB.  It defined the criteria used to develop the MIB module as

      To be consistent with IAB directives and good engineering
      practice, an explicit attempt was made to keep this MIB as simple
      as possible.  This was accomplished by applying the following
      criteria to objects proposed for inclusion:

   (1)  Start with a small set of essential objects and add only as
        further objects are needed.

   (2)  Require objects be essential for either fault or configuration

   (3)  Consider evidence of current use and/or utility.

   (4)  Limit the total (sic) of objects.

   (5)  Exclude objects which are simply derivable from others in this
        or other MIBs.

   (6)  Avoid causing critical sections to be heavily instrumented.  The
        guideline that was followed is one counter per critical section
        per layer.

   Over the past eight years additional experience has shown a need to
   expand these criteria as follows:

   (7)  Before designing a MIB module, identify goals and objectives for
        the MIB module.  How much of the underlying system will be
        exposed depends on these goals.

Top      Up      ToC       Page 11 
   (8)  Minimizing the total number of objects is not an explicit goal,
        but usability is.  Be sure to consider deployment and usability

   (9)  During configuration, consider supporting explicit error state,
        capability and capacity objects.

   (10) When evaluating rule (5) above, consider the impact on a
        management application.  If an object can help reduce a
        management application's complexity, consider defining objects
        that can be derived.

3.2.  Naming MIB modules and Managed Objects

   Naming of MIB modules and objects informally follows a set of best
   practices.  Originally, standards track MIB modules used RFC names.
   As the MIB modules evolved, the practice changed to using more
   descriptive names.  Presently, Standards Track MIB modules define a
   given area of technology such as ATM-MIB, and vendors then extend
   such MIB modules by prefixing the company name to a given MIB module
   as in ACME-ATM-MIB.

   Object descriptors (the "human readable names" assigned to object
   identifiers [2]) defined in standard MIB modules should be unique
   across all MIB modules.  Generally, a prefix is added to each managed
   object that can help reference the MIB module it was defined in.  For
   example, the IF-MIB uses "if" prefix for descriptors of object types
   such as ifTable, ifStackTable and so forth.

   MIB module object type descriptors can include an abbreviation for
   the function they perform.  For example the objects that control
   configuration in the example MIB module in Section 8 include "Cfg" as
   part of the object descriptor, as in bldgHVACCfgDesiredTemp.

   This is more fully realized when the object descriptors that include
   the fault, configuration, accounting, performance and security [33]
   abbreviations are combined with an organized OID assignment approach.
   For example, a vendor could create a configuration branch in their
   private enterprises area.  In some cases this might be best done on a
   per product basis.  Whatever the approach used, "Cfg" might be
   included in every object descriptor in the configuration branch.
   This has two operational benefits.  First, for those that do look at
   instances of MIB objects, descriptors as seen through MIB browsers or
   other command line tools assist in conveying the meaning of the
   object type.  Secondly, management applications can be pointed at
   specific subtrees for fault or configuration, causing a more
   efficient retrieval of data and a simpler management application with
   potentially better performance.

Top      Up      ToC       Page 12 
3.3.  Transaction Control And State Tracking

   Transactions and keeping track of their state is an important
   consideration when performing any type of configuration activity
   regardless of the protocol.  Here are a few areas to consider when
   designing transaction support into an SNMP-based configuration

3.3.1.  Conceptual Table Row Modification Practices

   Any discussion of transaction control as it pertains to MIB module
   design often begins with how the creation or modification of object
   instances in a conceptual row in the MIB module is controlled.

   RowStatus [3] is a standard textual convention for the management of
   conceptual rows in a table.  Specifically, the RowStatus textual
   convention that is used for the SYNTAX value of a single column in a
   table controls the creation, deletion, activation, and deactivation
   of conceptual rows of the table.  When a table has been defined with
   a RowStatus object as one of its columns, changing an instance of the
   object to 'active' causes the row in which that object instance
   appears to become 'committed'.

   In a multi-table scenario where the configuration data must be spread
   over many columnar objects, a RowStatus object in one table can be
   used to cause the entire set of data to be put in operation or stored
   based on the definition of the objects.

   In some cases, very large amounts of data may need to be 'committed'
   all at once.  In these cases, another approach is to configure all of
   the rows in all the tables required and have an "activate" object
   that has a set method that commits all the modified rows.

   The RowStatus textual convention specifies that, when used in a
   conceptual row, a description must define what can be modified.
   While the description of the conceptual row and its columnar object
   types is the correct place to derive this information on instance
   modifiability, it is often wrongly assumed in some implementations

   1) objects either must all be presently set or none need be set to
      make a conceptual RowStatus object transition to active(1)

   2) objects in a conceptual row cannot be modified once a RowStatus
      object is active(1).  Restricting instance modifiability like
      this, so that after a RowStatus object is set to active(1) is in
      fact a reasonable limitation, since such a set of RowStatus may
      have agent system side-effects which depend on committed columnar

Top      Up      ToC       Page 13 
      object instance values.  However, where this restriction exists on
      an object, it should be made clear in a DESCRIPTION clause such as
      the following:

      protocolDirDescr OBJECT-TYPE
        SYNTAX      DisplayString (SIZE (1..64))
        MAX-ACCESS  read-create
        STATUS      current
            "A textual description of the protocol encapsulation.
            A probe may choose to describe only a subset of the
            entire encapsulation (e.g., only the highest layer).

            This object is intended for human consumption only.

            This object may not be modified if the associated
            protocolDirStatus object is equal to active(1)."
        ::= { protocolDirEntry 4 }

   Any such restrictions on columnar object instance modification while
   a row's RowStatus object instance is set to active(1) should appear
   in the DESCRIPTION clause of the RowStatus columnar OBJECT-TYPE as

3.3.2.  Fate sharing with multiple tables

   An important principle associated with transaction control is fate
   sharing of rows in different tables.  Consider the case where a
   relationship has been specified between two conceptual tables of a
   MIB module (or tables in two different MIB modules).  In this
   context, fate sharing means that when a row of a table is deleted,
   the corresponding row in the other table is also deleted.  Fate
   sharing in a transaction control context can also be used with the
   activation of very large configuration changes.  If we have two
   tables that hold a set of configuration information, a row in one
   table might have to be put in the 'ready' state before the second can
   be put in the 'ready' state.  When that second table can be placed in
   the 'ready' state, then the entire transaction can be considered to
   have been 'committed'.

   Fate sharing of SNMP table data should be explicitly defined where
   possible using the SMI index qualifier AUGMENTS.  If the relationship
   between tables cannot be defined using SMIv2 macros, then the
   DESCRIPTION clause of the object types which particularly effect the
   cross-table relationship should define what should happen when rows
   in related tables are added or deleted.

Top      Up      ToC       Page 14 
   Consider the relationship between the dot1dBasePortTable and the
   ifTable.  These tables have a sparse relationship.  If a given
   ifEntry supports 802.1D bridging then there is a dot1dBasePortEntry
   that has a pointer to it via dot1dBasePortIfIndex.

   Now, what should happen if an ifEntry that can bridge is deleted?
   Should the object dot1dBasePortIfIndex simply be set to 0 or should
   the dot1dBasePortEntry be deleted as well?  A number of acceptable
   design and practice techniques can provide the answer to these
   questions, so it is important for the MIB module designer to provide
   the guidance to guarantee consistency and interoperability.

   To this end, when two tables are related in such a way, ambiguities
   such as this should be avoided by having the DESCRIPTION clauses of
   the pertinent row object types define the fate sharing of entries in
   the respective tables.

3.3.3.  Transaction Control MIB Objects

   When a MIB module is defined that includes configuration object
   types, consider providing transaction control objects.  These objects
   can be used to cause a large transaction to be committed.  For
   example, we might have several tables that define the configuration
   of a portion of a system.  In order to avoid churn in the operational
   state of the system we might create a single scalar object that, when
   set to a particular value, will cause the activation of the rows in
   all the necessary tables.  Here are some examples of further usage
   for such object types:

   o  Control objects that are the 'write' or 'commit' objects.

      Such objects can cause all pending transactions (change MIB object
      values as a result of SET operations) to be committed to a
      permanent repository or operational memory, as defined by the
      semantics of the MIB objects.

   o  Control objects at different levels of configuration granularity.

      One of the decisions for a MIB module designer is what are the
      levels of granularity that make sense in practice.  For example,
      in the routing area, would changes be allowed on a per protocol
      basis such as BGP? If allowed at the BGP level, are sub-levels
      permitted such as per autonomous system? The design of these
      control objects will be impacted by the underlying software
      design.  RowStatus (see Section 3.3.1) also has important
      relevance as a general transaction control object.

Top      Up      ToC       Page 15 
3.3.4.  Creating And Activating New Table Rows

   When designing read-create objects in a table, a MIB module designer
   should first consider the default state of each object in the table
   when a row is created.  Should an implementation of a standard MIB
   module vary in terms of the objects that need to be set in order to
   create an instance of a given row, an agent capabilities statement
   should be used to name the additional objects in that table using the

   It is useful when configuring new rows to use the notReady status to
   indicate row activation cannot proceed.

   When creating a row instance of a conceptual table, one should
   consider the state of instances of required columnar objects in the
   row.  The DESCRIPTION clause of such a required columnar object
   should specify it as such.

   During the period of time when a management application is attempting
   to create a row, there may be a period of time when not all of these
   required (and non-defaultable) columnar object instances have been
   set. Throughout this time, an agent should return a noSuchInstance
   error for a GET of any object instance of the row until such time
   that all of these required instance values are set.  The exception is
   the RowStatus object instance, for which a notReady(3) value should
   be returned during this period.

   One need only be concerned with the notReady value return for a
   RowStatus object when the row under creation does not yet have all of
   the required, non-defaultable instance values for the row.  One
   approach to simplifying in-row configuration transactions when
   designing MIB modules is to construct table rows that have no more
   instance data for columnar objects than will fit inside a single SET
   PDU.  In this case, the createAndWait() value for the RowStatus
   columnar object is not required.  It is possible to use createAndGo()
   in the same SET PDU, thus simplifying transactional management.

3.3.5.  Summary Objects and State Tracking

   Before beginning a new set of configuration transactions, a
   management application might want to checkpoint the state of the
   managed devices whose configuration it is about to change.  There are
   a number of techniques that a MIB module designer can provide to
   assist in the (re-)synchronization of the managed systems.  These
   objects can also be used to verify that the management application's
   notion of the managed system state is the same as that of the managed

Top      Up      ToC       Page 16 
   These techniques include:

   1. Provide an object that reports the number of rows in a table

   2. Provide an object that flags when data in the table was last

   3. Send a notification message (InformRequests are preferable) to
      deliver configuration change.

   By providing an object containing the number of rows in a table,
   management applications can decide how best to retrieve a given
   table's data and may choose different retrieval strategies depending
   on table size.  Note that the availability of and application
   monitoring of such an object is not sufficient for determining the
   presence of table data change over a checkpointed duration since an
   equal number of row creates and deletes over that duration would
   reflect no change in the object instance value.  Additionally, table
   data change which does not change the number of rows in the table
   would not be reflected through simple monitoring of such an object

   Instead, the change in the value of any table object instance data
   can be tracked through an object that monitors table change state as
   a function of time.  An example is found in RFC 2790, Host Resources

   hrSWInstalledLastUpdateTime OBJECT-TYPE
       SYNTAX     TimeTicks
       MAX-ACCESS read-only
       STATUS     current
           "The value of sysUpTime when the hrSWInstalledTable
           was last completely updated.  Because caching of this
           data will be a popular implementation strategy,
           retrieval of this object allows a management station
           to obtain a guarantee that no data in this table is
           older than the indicated time."
       ::= { hrSWInstalled 2 }

   A similar convention found in many standards track MIB modules is the
   "LastChange" type object.

   For example, the ENTITY-MIB, RFC 2737 [34], provides the following

   entLastChangeTime OBJECT-TYPE
     SYNTAX      TimeStamp

Top      Up      ToC       Page 17 
     MAX-ACCESS  read-only
     STATUS      current
             "The value of sysUpTime at the time a conceptual row is
             created, modified, or deleted in any of these tables:
                     - entPhysicalTable
                     - entLogicalTable
                     - entLPMappingTable
                     - entAliasMappingTable
                     - entPhysicalContainsTable"
     ::= { entityGeneral 1 }

   This convention is not formalized.  There tend to be small
   differences in what a table's LastChanged object reflects.  IF-MIB
   (RFC 2863 [20]) defines the following:

   ifTableLastChange  OBJECT-TYPE
       SYNTAX      TimeTicks
       MAX-ACCESS  read-only
       STATUS      current
               "The value of sysUpTime at the time of the last
               creation or deletion of an entry in the ifTable.  If
               the number of entries has been unchanged since the
               last re-initialization of the local network management
               subsystem, then this object contains a zero value."
       ::= { ifMIBObjects 5 }

   So, if an agent modifies a row with an SNMP SET on ifAdminStatus, the
   value of ifTableLastChange will not be updated.  It is important to
   be specific about what can cause an object to update so that
   management applications will be able to detect and more properly act
   on these changes.

   The final way to keep distributed configuration data consistent is to
   use an event-driven model, where configuration changes are
   communicated as they occur.  When the frequency of change to
   configuration is relatively low or polling a cache object is not
   desired, consider defining a notification that can be used to report
   all configuration change details.

   When doing so, the option is available to an SNMPv3 (or SNMPv2c)
   agent to deliver the notification using either a trap or an inform.
   The decision as to which PDU to deliver to the recipient is generally
   a matter of local configuration.  Vendors should recommend the use of
   informs over traps for NOTIFICATION-TYPE data since the agent can use
   the presence or absence of a response to help know whether it needs

Top      Up      ToC       Page 18 
   to retransmit or not.  Overall, it is preferable to use an inform
   instead of a trap so that changes have a higher likelihood of
   confirmed end-to-end delivery.

   As a matter of MIB module design, when practical, the NOTIFICATION-
   TYPE should include in the PDU all of the modified columnar objects
   in a row of a table.  This makes it easier for the management
   application receiving the notification to keep track of what has
   changed in the row of a table and perform addition analysis on the
   state of the managed elements.

   However, the use of notifications to communicate the state of a
   rapidly changing object may not be ideal either.  This leads us back
   to the MIB module design question of what is the right level of
   granularity to expose.

   Finally, having to poll many "LastChange" objects does not scale
   well.  Consider providing a global LastChange type object to
   represent overall configuration in a given agent implementation.

3.3.6.  Optimizing Configuration Data Transfer

   Configuration management software should keep track of the current
   configuration of all devices under its control.  It should ensure
   that the result is a consistent view of the configuration of the
   network, which can help reduce inadvertent configuration errors.

   In devices that have very large amounts of configuration data, it can
   be costly to both the agent and the manager to have the manager
   periodically poll the entire contents of these configuration tables
   for synchronization purposes.  A benefit of good synchronization
   between the manager and the agent is that the manager can determine
   the smallest and most effective set of data to send to managed
   devices when configuration changes are required.  Depending on the
   table organization in the managed device and the agent
   implementation, this practice can reduce the burden on the managed
   device for activation of these configuration changes.

   In the previous section, we discussed the "LastChange" style of
   object.  When viewed against the requirements just described, the
   LastChange object is insufficient for large amounts of data.

   There are three design options that can be used to assist with the
   synchronization of the configuration data found in the managed device
   with the manager:

Top      Up      ToC       Page 19 
   1) Design multiple indices to partition the data in a table logically
      or break a table into a set of tables to partition the data based
      on what an application will use the table for

   2) Use a time-based indexing technique

   3) Define a control MIB module that manages a separate data delivery
      protocol  Index Design

   Index design has a major impact on the amount of data that must be
   transferred between SNMP entities and can help to mitigate scaling
   issues with large tables.

   Many tables in standard MIB modules follow one of two indexing

   - Indexing based upon increasing Integer32 or Unsigned32 values of
      the kind one might find in an array.

   - Associative indexing, which refers to the technique of using
      potentially sparse indices based upon a "key" of the sort one
      would use for a hash table.

   When tables grow to a very large number of rows, using an associative
   indexing scheme offers the useful ability to efficiently retrieve
   only the rows of interest.

   For example, if an SNMP entity exposes a copy of the default-free
   Internet routing table as defined in the ipCidrRouteTable, it will
   presently contain around 100,000 rows.

   Associative indexing is used in the ipCidrRouteTable and allows one
   to retrieve, for example, all routes for a given IPv4 destination

   Yet, if the goal is to extract a copy of the table, the associative
   indexing reduces the throughput and potentially the performance of
   retrieval.  This is because each of the index objects are appended to
   the object identifiers for every object instance returned.

   ipCidrRouteEntry OBJECT-TYPE
      SYNTAX   IpCidrRouteEntry
      MAX-ACCESS not-accessible
      STATUS   current
       "A particular route to a particular destination,

Top      Up      ToC       Page 20 
       under a particular policy."
      INDEX {

   A simple array-like index works efficiently since it minimizes the
   index size and complexity while increasing the number of rows that
   can be sent in a PDU.  If the indexing is not sparse, concurrency can
   be gained by sending multiple asynchronous non-overlapping collection
   requests as is explained in RFC 2819 [32], Page 41 (in the section
   pertaining to Host Group indexing).

      Should requirements dictate new methods of access, multiple
      indices can be defined such that both associative and simple
      indexing can coexist to access a single logical table.

   Two examples follow.

   First, consider the ifStackTable found in RFC 2863 [20] and the
   ifInvStackTable RFC 2864 [33].  They are logical equivalents with the
   order of the auxiliary (index) objects simply reversed.

   ifStackEntry  OBJECT-TYPE
        SYNTAX        IfStackEntry
        MAX-ACCESS    not-accessible
        STATUS        current
                "Information on a particular relationship between
                two sub-layers, specifying that one sub-layer runs
                on 'top' of the other sub-layer.  Each sub-layer
                corresponds to a conceptual row in the ifTable."
                INDEX { ifStackHigherLayer, ifStackLowerLayer }
        ::= { ifStackTable 1 }

   ifInvStackEntry  OBJECT-TYPE
      SYNTAX        IfInvStackEntry
      MAX-ACCESS    not-accessible
      STATUS        current
          "Information on a particular relationship between two
          sub-layers, specifying that one sub-layer runs underneath
          the other sub-layer.  Each sub-layer corresponds to a
          conceptual row in the ifTable."
          INDEX { ifStackLowerLayer, ifStackHigherLayer }
      ::= { ifInvStackTable 1 }

Top      Up      ToC       Page 21 
   Second, table designs that can factor data into multiple tables with
   well-defined relationships can help reduce overall data transfer
   requirements.  The RMON-MIB, RFC 2819 [32], demonstrates a very
   useful technique of organizing tables into control and data
   components.  Control tables contain those objects that are configured
   and change infrequently, and the data tables contain information to
   be collected that can be large and may change quite frequently.

   As an example, the RMON hostControlTable provides a way to specify
   how to collect MAC addresses learned as a source or destination from
   a given port that provides transparent bridging of Ethernet packets.

   Configuration is accomplished using the hostControlTable.  It is
   indexed by a simple integer.  While this may seem to be array-like,
   it is common practice for command generators to encode the ifIndex
   into this simple integer to provide associative lookup capability.

   The RMON hostTable and hostTimeTable represent dependent tables that
   contain the results indexed by the hostControlTable entry.

   The hostTable is further indexed by the MAC address which provides
   the ability to reasonably search for a collection, such as the
   Organizationally Unique Identifier (OUI), the first three octets of
   the MAC address.

   The hostTimeTable is designed explicitly for fast transfer of bulk
   RMON data.  It demonstrates how to handle collecting large number of
   rows in the face of deletions and insertions by providing

   hostControlLastDeleteTime OBJECT-TYPE
   SYNTAX     TimeTicks
   MAX-ACCESS read-only
   STATUS     current
       "The value of sysUpTime when the last entry
       was deleted from the portion of the hostTable
       associated with this hostControlEntry.  If no
       deletions have occurred, this value shall be zero."
   ::= { hostControlEntry 4 }  Time Based Indexing

   The TimeFilter as defined in RFC 2021 [44] and used in RMON2-MIB and
   Q-BRIDGE-MIB (RFC 2674 [26]) provides a way to obtain only those rows
   that have changed on or after some specified period of time has

Top      Up      ToC       Page 22 
   One drawback to TimeFilter index tables is that a given row can
   appear at many points in time, which artificially inflates the size
   of the table when performing standard getNext or getBulk data
   retrieval.  Alternate Data Delivery Mechanisms

   If the amount of data to transfer is larger than current SNMP design
   restrictions permit, as in the case of OCTET STRINGS (64k minus
   overhead of IP/UDP header plus SNMP header plus varbind list plus
   varbind encoding), consider delivery of the data via an alternate
   method, such as FTP and use a MIB module to control that data
   delivery process.  In many cases, this problem can be avoided via
   effective MIB design.  In other words, object types requiring this
   kind of transfer size should be used judiciously, if at all.

   There are many enterprise MIB modules that provide control of the
   TFTP or FTP protocol.  Often the SNMP part defines what to send where
   and setting an object initiates the operation (for an example, refer
   to the CISCO-FTP-CLIENT-MIB, discussed in [38]).

   Various approaches exist for allowing a local agent process running
   within the managed node to take a template for an object instance
   (for example for a set of interfaces), and adapt and apply it to all
   of the actual instances within the node.  This is an architecture for
   one form of policy-based configuration (see [36], for example).  Such
   an architecture, which must be designed into the agent and some
   portions of the MIB module, affords the efficiency of specifying many
   copies of instance data only once, along with the execution
   efficiency of distributing the application of the instance data to
   the agent.

   Other work is currently underway to improve efficiency for bulk SNMP
   transfer operations [37].  The objective of these efforts is simply
   the conveyance of more information with less overhead.

3.4.  More Index Design Issues

   Section 3.3.5 described considerations for table row index design as
   it pertains to the synchronization of changes within sizable table
   rows. This section simply considers how to specify this syntactically
   and how to manage indices semantically.

   In many respects, the design issues associated with indices in a MIB
   module are similar to those in a database.  Care must be taken during
   the design phase to determine how often and what kind of information
   must be set or retrieved.  The next few points provide some guidance.

Top      Up      ToC       Page 23 
3.4.1.  Simple Integer Indexing

   When indexing tables using simple Integer32 or Unsigned32, start with
   one (1) and specify the maximum range of the value.  Since object
   identifiers are unsigned long values, a question that arises is why
   not index from zero (0) instead of one(1)?

   RFC 2578 [2], Section 7.7, page 28 states the following: Instances
   identified by use of integer-valued objects should be numbered
   starting from one (i.e., not from zero).  The use of zero as a value
   for an integer-valued index object type should be avoided, except in
   special cases.  Consider the provisions afforded by the following
   textual convention from the Interfaces Group MIB module [33]:

   InterfaceIndexOrZero ::= TEXTUAL-CONVENTION
       DISPLAY-HINT "d"
       STATUS       current
           "This textual convention is an extension of the
           InterfaceIndex convention.  The latter defines a greater
           than zero value used to identify an interface or interface
           sub-layer in the managed system.  This extension permits the
           additional value of zero.  the value zero is object-specific
           and must therefore be defined as part of the description of
           any object which uses this syntax.  Examples of the usage of
           zero might include situations where interface was unknown,
           or when none or all interfaces need to be referenced."
       SYNTAX       Integer32 (0..2147483647)

3.4.2.  Indexing with Network Addresses

   There are many objects that use IPv4 addresses (SYNTAX IpAddress) as
   indexes.  One such table is the ipAddrTable from RFC 2011 [14] IP-
   MIB.  This limits the usefulness of the MIB module to IPv4.  To avoid
   such limitations, use the addressing textual conventions INET-
   ADDRESS-MIB [13] (or updates to that MIB module), which provides a
   generic way to represent addresses for Internet Protocols.  In using
   the InetAddress textual convention in this MIB, however, pay heed to
   the following advisory found in its description clause:

      When this textual convention is used as the syntax of an index
      object, there may be issues with the limit of 128 sub-identifiers
      specified in SMIv2, STD 58.  In this case, the OBJECT-TYPE
      declaration MUST include a 'SIZE' clause to limit the number of
      potential instance sub-identifiers.

Top      Up      ToC       Page 24 
   One should consider the SMI limitation on the 128 sub-identifier
   specification when using certain kinds of network address index
   types.  The most likely practical liability encountered in practice
   has been with DNS names, which can in fact be in excess of 128 bytes.
   The problem can be, of course, compounded when multiple indices of
   this type are specified for a table.

3.5.  Conflicting Controls

   MIB module designers should avoid specifying read-write objects that
   overlap in function partly or completely.

   Consider the following situation where two read-write objects
   partially overlap when a dot1dBasePortEntry has a corresponding

   The BRIDGE-MIB defines the following managed object:

   dot1dStpPortEnable OBJECT-TYPE
                   disabled(2)            }
       ACCESS  read-write
       STATUS  mandatory
           "The enabled/disabled status of the port."
           "IEEE 802.1D-1990: Section"
       ::= { dot1dStpPortEntry 4 }

   The IF-MIB defines a similar managed object:

   ifAdminStatus OBJECT-TYPE
                   up(1),       -- ready to pass packets
                   testing(3)   -- in some test mode
       MAX-ACCESS  read-write
       STATUS      current
           "The desired state of the interface.  The testing(3)
           state indicates that no operational packets can be
           passed.  When a managed system initializes, all
           interfaces start with ifAdminStatus in the down(2) state.
           As a result of either explicit management action or per
           configuration information retained by the managed system,
           ifAdminStatus is then changed to either the up(1) or

Top      Up      ToC       Page 25 
           testing(3) states (or remains in the down(2) state)."
       ::= { ifEntry 7 }

   If ifAdminStatus is set to testing(3), the value to be returned for
   dot1dStpPortEnable is not defined.  Without clarification on how
   these two objects interact, management implementations will have to
   monitor both objects if bridging is detected and correlate behavior.

   The dot1dStpPortEnable object type could have been written with more
   information about the behavior of this object when values of
   ifAdminStatus which impact it change.  For example, text could be
   added that described proper return values for the dot1dStpPortEnable
   object instance for each of the possible values of ifAdminStatus.

   In those cases where overlap between objects is unavoidable, then as
   we have just described, care should be taken in the description of
   each of the objects to describe their possible interactions.  In the
   case of an object type defined after an incumbent object type, it is
   necessary to include in the DESCRIPTION of this later object type the
   details of these interactions.

3.6.  Textual Convention Usage

   Textual conventions should be used whenever possible to create a
   consistent semantic for an oft-recurring datatype.

   MIB modules often define a binary state object such as enable/disable
   or on/off.  Current practice is to use existing Textual Conventions
   and define the read-write object in terms of a TruthValue from
   SNMPv2-TC [3].  For example, the Q-BRIDGE-MIB [26] defines:

   dot1dTrafficClassesEnabled OBJECT-TYPE
       SYNTAX      TruthValue
       MAX-ACCESS  read-write
       STATUS      current
          "The value true(1) indicates that Traffic Classes are
          enabled on this bridge.  When false(2), the bridge
          operates with a single priority level for all traffic."
       DEFVAL      { true }
       ::= { dot1dExtBase 2 }

   Textual conventions that have a reasonable chance of being reused in
   other MIB modules ideally should also be defined in a separate MIB
   module to facilitate sharing of such object types.  For example, all
   ATM MIB modules draw on the ATM-TC-MIB [39] to reference and utilize
   common definitions for addressing, service class values, and the

Top      Up      ToC       Page 26 
   To simplify management, it is recommended that existing SNMPv2-TC
   based definitions be used when possible.  For example, consider the
   following object definition:

   acmePatioLights OBJECT-TYPE
       MAX-ACCESS  read-write
       STATUS      current
           "Current status of outdoor lighting."
       ::= { acmeOutDoorElectricalEntry 3 }

   This could be defined as follows using existing SNMPv2-TC TruthValue.

   acmePatioLightsOn OBJECT-TYPE
       SYNTAX  TruthValue
       MAX-ACCESS  read-write
       STATUS      current
           "Current status of outdoor lighting.  When set to true (1),
           this means that the lights are enabled and turned on.
           When set to false (2), the lights are turned off."
        ::= { acmeOutDoorElectricalEntry 3 }

3.7.  Persistent Configuration

   Many network devices have two levels of persistence with regard to
   configuration data.  In the first case, the configuration data sent
   to the device is persistent only until changed with a subsequent
   configuration operation, or the system is reinitialized.  The second
   level is where the data is made persistent as an inherent part of the
   acceptance of the configuration information.  Some configuration
   shares both these properties, that is, that on acceptance of new
   configuration data it is saved permanently and in memory.  Neither of
   these necessarily means that the data is used by the operational
   code.  Sometimes separate objects are required to activate this new
   configuration data for use by the operational code.

   However, many SNMP agents presently implement simple persistence
   models, which do not reflect all the relationships of the
   configuration data to the actual persistence model as described
   above.  Some SNMP set requests against MIB objects with MAX-ACCESS
   read-write are written automatically to a persistent store. In other
   cases, they are not.  In some of the latter cases, enterprise MIB

Top      Up      ToC       Page 27 
   objects are required in order to get standard configuration stored,
   thus making it difficult for a generic application to have a
   consistent effect.

   There are standard conventions for saving configuration data.  The
   first method uses the Textual Convention known as StorageType [3]
   which explicitly defines a given row's persistence requirement.

   Examples include the RFC 3231 [25] definition for the schedTable row
   object schedStorageType of syntax StorageType, as well as similar row
   objects for virtually all of the tables of the SNMP View-based Access
   Control Model MIB [10].

   A second method for persistence simply uses the DESCRIPTION clause to
   define how instance data should persist.  RFC 2674 [26] explicitly
   defines Dot1qVlanStaticEntry data persistence as follows:

   dot1qVlanStaticTable OBJECT-TYPE
       SYNTAX      SEQUENCE OF Dot1qVlanStaticEntry
       MAX-ACCESS  not-accessible
       STATUS      current
        "A table containing static configuration information for
        each VLAN configured into the device by (local or
        network) management.  All entries are permanent and will
        be restored after the device is reset."
       ::= { dot1qVlan 3 }

   The current practice is a dual persistence model where one can make
   changes to run-time configuration as well as to a non-volatile
   configuration read at device initialization.  The DISMAN-SCHEDULE-MIB
   module [25] provides an example of this practice.  A row entry of its
   SchedTable specifies the parameters by which an agent MIB variable
   instance can be set to a specific value at some point in time and
   governed by other constraints and directives.  One of those is:

   schedStorageType OBJECT-TYPE
        SYNTAX      StorageType
        MAX-ACCESS  read-create
        STATUS      current
            "This object defines whether this scheduled action is kept
             in volatile storage and lost upon reboot or if this row is
             backed up by non-volatile or permanent storage.
             Conceptual rows having the value `permanent' must allow
             write access to the columnar objects schedDescr,
             schedInterval, schedContextName, schedVariable, schedValue,
             and schedAdminStatus.  If an implementation supports the

Top      Up      ToC       Page 28 
             schedCalendarGroup, write access must be also allowed to
             the columnar objects schedWeekDay, schedMonth, schedDay,
             schedHour, schedMinute."
        DEFVAL { volatile }
        ::= { schedEntry 19 }

   It is important, however, to reiterate that the persistence is
   ultimately controlled by the capabilities and features (with respect
   to the storage model of management data) of the underlying system on
   which the MIB Module agent is being implemented.  This falls into
   very much the same kind of issue set as, for example, the situation
   where the size of data storage in the system for a Counter object
   type is not the same as that in the corresponding MIB Object Type.
   To generalize, the final word on the "when" and "how" of storage of
   persistent data is dictated by the system and the implementor of the
   agent on the system.

3.8.  Configuration Sets and Activation

   An essential notion for configuration of network elements with SNMP
   is awareness of the difference between the set of one or more
   configuration objects from the activation of those configuration
   changes in the actual subsystem.  That is, it often only makes sense
   to activate a group of objects as a single 'transaction'.

3.8.1.  Operational Activation Considerations

   A MIB module design must consider the implications of the preceding
   in the context of changes that will occur throughout a subsystem when
   changes are activated.  This is particularly true for configuration
   changes that are complex.  This complexity can be in terms of
   configuration data or the operational ramifications of the activation
   of the changes in the managed subsystem.  A practical technique to
   accommodate this kind of activation is the partitioning of contained
   configuration sets, as it pertains to their being activated as
   changes.  Any complex configuration should have a master on/off
   switch (MIB object type) as well as strategically placed on/off
   switches that partition the activation of configuration data in the
   managed subsystem.  These controls play a pivotal role during the
   configuration process as well as during subsequent diagnostics.
   Generally, a series of set operations should not cause an agent to
   activate each object, causing operational instability to be
   introduced with every changed object instance.  To avoid this
   liability, ideally a series of Set PDUs can install the configuration
   and a final set series of PDUs can activate the changes.

Top      Up      ToC       Page 29 
   During diagnostic situations, certain on/off switches can be set to
   localize the perceived error instead of having to remove the

   An example of such an object from the OSPF Version 2 MIB [29] is the
   global ospfAdminStat:

   ospfAdminStat OBJECT-TYPE
       SYNTAX   Status
       MAX-ACCESS   read-write
       STATUS   current
          "The administrative status of  OSPF  in the
          router.  The value 'enabled' denotes that the
          OSPF Process is active on at least one interface;
          'disabled' disables it on all interfaces."
      ::= { ospfGeneralGroup 2 }

   Elsewhere in the OSPF MIB, the semantics of setting ospfAdminStat to
   enabled(2) are clearly spelled out.

   The Scheduling MIB [25] exposes such an object on each entry in the
   scheduled actions table, along with the corresponding stats object
   type (with read-only ACCESS) on the scheduled actions row instance.

   This reflects a recurring basic design pattern which brings about
   semantic clarity in the object type usage.  A table can expose one
   columnar object type which is strictly for administrative control.
   When read, an instance of this object type will reflect its last set
   or defaulted value.  A companion operational columnar object type,
   with MAX-ACCESS of read-only, provides the current state of
   activation or deactivation resulting from the last set of the
   administrative columnar instance.  It is fully expected that these
   administrative and operational columnar instances may reflect
   different values over some period of time of activation latency,
   which is why they are separate.  Further sections display some of the
   problems which can result from attempting to combine the operational
   and administrative row columns into a single object type.

   Note that all of this is independent of the RowStatus columnar
   object, and the notion of 'activation' as it pertains to RowStatus.
   A defined RowStatus object type should be strictly concerned with the
   management of the table row itself (with 'activation' indicating "the
   conceptual row is available for use by the managed device" [3], and
   not to be confused with any operational activation semantics).

Top      Up      ToC       Page 30 
   In the following example, schedAdminStatus controls activation of the
   scheduled action, and schedOperStatus reports on its operational

   schedAdminStatus OBJECT-TYPE
       SYNTAX      INTEGER {
       MAX-ACCESS  read-create
       STATUS      current
           "The desired state of the schedule."
       DEFVAL { disabled }
       ::= { schedEntry 14 }

   schedOperStatus OBJECT-TYPE
       SYNTAX      INTEGER {
       MAX-ACCESS  read-only
       STATUS      current
           "The current operational state of this schedule.  The state
            enabled(1) indicates this entry is active and that the
            scheduler will invoke actions at appropriate times.  The
            disabled(2) state indicates that this entry is currently
            inactive and ignored by the scheduler.  The finished(3)
            state indicates that the schedule has ended.  Schedules
            in the finished(3) state are ignored by the scheduler.
            A one-shot schedule enters the finished(3) state when it
            deactivates itself."
       ::= { schedEntry 15 }

3.8.2.  RowStatus and Deactivation

   RowStatus objects should not be used to control
   activation/deactivation of a configuration.  While RowStatus looks
   ideally suited for such a purpose since a management application can
   set a row to active(1), then set it to notInService(2) to disable it
   then make it active(1) again, there is no guarantee that the agent
   won't discard the row while it is in the notInService(2) state.  RFC
   2579 [3], page 15 states:

Top      Up      ToC       Page 31 
      The agent must detect conceptual rows that have been in either
      state for an abnormally long period of time and remove them.  It
      is the responsibility of the DESCRIPTION clause of the status
      column to indicate what an abnormally long period of time would

   The DISMAN-SCHEDULE-MIB's managed object schedAdminStatus
   demonstrates how to separate row control from row activation.
   Setting the schedAdminStatus to disabled(2) does not cause the row to
   be aged out/removed from the table.

   Finally, a reasonable agent implementation must consider how many
   rows will be allowed to be created in the notReady/notInService state
   such that resources are not exhausted by an errant application.

3.9.  SET Operation Latency

   Many standards track and enterprise MIB modules that contain read-
   write objects assume that an agent can complete a set operation as
   quickly as an agent can send back the status of the set operation to
   the application.

   Consider the subtle operational shortcomings in the following object.
   It both reports the current state and allows a SET operation to
   change to a possibly new state.

wheelRotationState  OBJECT-TYPE
      SYNTAX        INTEGER { unknown(0),
      MAX-ACCESS    read-write
      STATUS        current
      "The current state of a wheel."
  ::= { XXX 2 }

Top      Up      ToC       Page 32 
With the object defined, the following example represents one possible

Time  Command Generator --------> <--- Command Responder
----- -----------------                -----------------
A  GetPDU(wheelRotationState.1.1)
|                          ResponsePDU(error-index 0,
|                                       error-code 0)
B                          wheelRotationState.1.1 == spinClockwise(2)
C  SetPDU(wheelRotationState.1.1 =
|                   spinCounterClockwise(3)
|                          ResponsePDU(error-index 0,
|                                       error-code 0)
D                          wheelRotationState.1.1
                                           == spinCounterClockwise(3)
E  GetPDU(wheelRotationState.1.1)
F                          ResponsePDU(error-index 0,
|                                       error-code 0)
V                          wheelRotationState.1.1 == spinClockwise(2)
   ....some time, perhaps seconds, later....
G       GetPDU(wheelRotationState.1.1)
H                         ResponsePDU(error-index 0,
|                                      error-code 0)
|                       wheelRotationState.1.1
V                                          == spinCounterClockwise(3)

   The response to the GET request at time E will often confuse
   management applications that assume the state of the object should be
   spinCounterClockwise(3).  In reality, the wheel is slowing down in
   order to come to the idle state then begin spinning counter

   This possibility of confusing and paradoxical interactions of
   administrative and operational state is inevitable when a single
   object type is used to control and report on both types of state.
   One common practice which we have already seen is to separate out the

Top      Up      ToC       Page 33 
   desired (settable) state from current state.  The objects
   ifAdminStatus and ifOperStatus from RFC 2863 [20] provide such an
   example of the separation of objects into desired and current state.

3.9.1.  Subsystem Latency, Persistence Latency, and Activation Latency

   A second way latency can be introduced in SET operations is caused by
   delay in agent implementations that must interact with loosely
   coupled subsystems.  The time it takes the instrumented system to
   accept the new configuration information from the SNMP agent, process
   it and 'install' the updated configuration in the system or otherwise
   process the directives can often be longer than the SNMP response

   In these cases, it is desirable to provide a "current state" object
   type which can be polled by the management application to determine
   the state of control of the loosely coupled subsystem which was
   affected by its configuration update.

   More generally, some MIB objects may have high latencies associated
   with changes to their values.  This could be either a function of
   saving the changed value to a persistent storage type, and/or
   activating a subsystem that inherently has high latency as discussed
   above.  When defining such MIB objects, it might be wise to have the
   agent process set operations in the managed subsystem as soon as the
   Set PDU has been processed, and then update appropriate status
   objects when the save-to- persistent storage and (if applicable)
   activation has succeeded or is otherwise complete.  Another approach
   would be to cause a notification to be sent that indicates that the
   operation has been completed.

   When you describe an activation object, the DESCRIPTION clauses for
   these objects should give a hint about the likely latency for the
   completion of the operation.  Keep in mind that from a management
   software perspective (as presented in the example of schedAdminStatus
   in Section 3.8.1), the combined latency of saving-to-persistence and
   activation are not distinguishable when they are part of a single

3.10.  Notifications and Error Reporting

   For the purpose of this section, a 'notification' is as described in
   the SMIv2, RFC 2578 [2], by the NOTIFICATION-TYPE macro.
   Notifications can be sent in either SNMPv2c [19] or SNMPv3 TRAP or
   InformRequest PDUs.  Given the sensitivity of configuration
   information, it is recommended that configuration operations always
   be performed using SNMPv3 due to its enhanced security capabilities.
   InformRequest PDUs should be used in preference to TRAP PDUs since

Top      Up      ToC       Page 34 
   the recipient of the InformRequest PDUs responds with a Response PDU.
   This acknowledgment can be used to avoid unnecessary retransmission
   of NOTIFICATION-TYPE information when retransmissions are in fact
   required.  The use of InformRequest PDUs (as opposed to TRAPs) is not
   at the control of the MIB module designer or agent implementor.  The
   determination as to whether or not a TRAP or InformRequest PDU is
   sent from an SNMPv2c or SNMPv3 agent is generally a function of the
   agent's local configuration (but can be controlled with MIB objects
   in SNMPv3).  To the extent notification timeout and retry values are
   determined by local configuration parameters, care should be taken to
   avoid unnecessary retransmission of InformRequest PDUs.

   Configuration change and error information conveyed in InformRequest
   PDUs can be an important part of an effective SNMP-based management
   system.  They also have the potential to be overused.  This section
   offers some guidance for effective definition of NOTIFICATION-TYPE
   information about configuration changes that can be carried in
   InformRequest PDUs.  Notifications can also play a key role for all
   kinds of error reporting from hardware failures to configuration and
   general policy errors.  These types of notifications should be
   designed as described in Section 3.11 (Application Error Reporting).

3.10.1.  Identifying Source of Configuration Changes

   A NOTIFICATION-TYPE designed to report configuration changes should
   report the identity of the management entity initiating the
   configuration change.  Specifically, if the entity is known to be a
   SNMP command generator, the transport address and SNMP parameters as
   found in table snmpTargetParamsTable from RFC 3413 SNMP-TARGET-MIB
   should be reported where  possible.  For reporting of configuration
   changes outside of the SNMP domain, the applicable change mechanism
   (for example, CLI vs. HTTP-based management client access) should be
   reported, along with whatever notion of "user ID" of the change
   initiator is applicable and available.

3.10.2.  Limiting Unnecessary Transmission of Notifications

   The design of event-driven synchronization models, essential to
   configuration management, can use notifications as an important
   enabling technique.  Proper usage of notifications allows the
   manager's view of the managed element's configuration to be in close
   synchronization with the actual state of the configuration of the
   managed element.

   When designing new NOTIFICATION-TYPEs, consider how to limit the
   number of notifications PDUs that will be sent with the notification
   information defined in the NOTIFICATION-TYPE in response to a
   configuration change or error event.

Top      Up      ToC       Page 35 
   InformRequest PDUs, when compared to TRAP PDUs, have an inherent
   advantage when the concern is the reduction of unnecessary messages
   from the system generating the NOTIFICATION-TYPE data, when in fact
   retransmission of this data is required.  That is, an InformRequest
   PDU is acknowledged by the receiving entity with a Response PDU.  The
   receipt of this response allows the entity which generated the
   InformRequest PDU to verify (and record an audit entry, where such
   facilities exist on the agent system) that the message was received.
   As a matter of notification protocol, this receipt guarantee is not
   available when using TRAP PDUs, and if it is required, must be
   accomplished by the agent using some mechanism out of band to SNMP,
   and usually requiring the penalty of polling.

   Regardless of the specific PDUs used to convey them, one way to limit
   the unnecessary generation of notifications is to include in the
   NOTIFICATION-TYPE definition situations where it need not be sent.  A
   good example is the frDLCIStatusChange defined in FRAME-RELAY-DTE-
   MIB, RFC 2115 [21].

       OBJECTS  { frCircuitState }
       STATUS      current
          "This trap indicates that the indicated Virtual Circuit
          has changed state.  It has either been created or
          invalidated, or has toggled between the active and
          inactive states.  If, however, the reason for the state
          change is due to the DLCMI going down, per-DLCI traps
          should not be generated."
   ::= { frameRelayTraps 1 }

   There are a number of other techniques which can be used to reduce
   the unwanted generation of NOTIFICATION-TYPE information.  When
   defining notifications, the designer can specify a number of temporal
   limitations on the generation of specific instances of a
   NOTIFICATION-TYPE.  For example, a definition could specify that
   messages will not be sent more frequently than once every 60 seconds
   while the condition which led to the generation of the notification
   persists.  Alternately, a NOTIFICATION-TYPE DESCRIPTION clause could
   provide a fixed limit on the number of messages sent over the
   duration of the condition leading to sending the notification.

   If NOTIFICATION-TYPE transmission is "aggregated" in some way -
   bounded either temporally or by absolute system state change as
   described above - the optimal design technique is to have the data
   delivered with the notification reference the actual number of
   underlying managed element transitions which brought about the
   notification.  No matter which threshold is chosen to govern the

Top      Up      ToC       Page 36 
   actual transmission of NOTIFICATION-TYPEs, the idea is to describe an
   aggregated event or related set of events in as few PDUs as possible.

3.10.3.  Control of Notification Subsystem

   There are standards track MIB modules that define objects that either
   augment or overlap control of notifications.  For instance, FRAME-
   RELAY-DTE-MIB RFC 2115 defines frTrapMaxRate and DOCS-CABLE-DEVICE-
   MIB defines a set of objects in docsDevEvent that provide for rate
   limiting and filtering of notifications.

   In the past, agents did not have a standard means to configure a
   notification generator.  With the availability of the SNMP-
   NOTIFICATION-MIB module in RFC 3413 [9], it is strongly recommended
   that the filtering functions of this MIB module be used.  This MIB
   facilitates the mapping of given NOTIFICATION-TYPEs and their
   intended recipients.

   If the mechanisms of the SNMP-NOTIFICATION-MIB are not suitable for
   this application, a explanation of why they are not suitable should
   be included in the DESCRIPTION clause of any replacement control

3.11.  Application Error Reporting

   MIB module designers should not rely on the SNMP protocol error
   reporting mechanisms alone to report application layer error state
   for objects that accept SET operations.

   Most MIB modules that exist today provide very little detail as to
   why a configuration request has failed.  Often the only information
   provided is via SNMP protocol errors which generally does not provide
   enough information about why an agent rejected a set request.
   Typically, there is an incumbent and sizable burden on the
   configuration application to determine if the configuration request
   failure is the result of a resource issue, a security issue, or an
   application error.

   Ideally, when a "badValue" error occurs for a given set request, an
   application can query the agent for more details on the error.  A
   badValue does not necessarily mean the command generator sent bad
   data.  An agent could be at fault.  Additional detailed diagnostic
   information may aid in diagnosing conditions in the integrated

Top      Up      ToC       Page 37 
   Consider the requirement of conveying error information about a MIB
   expression 'object' set within the DISMAN-EXPRESSION-MIB [40] that
   occurs when the expression is evaluated.  Clearly, none of the
   available protocol errors are relevant when reporting an error
   condition that occurs when an expression is evaluated.  Instead, the
   DISMAN-EXPRESSION-MIB provides objects to report such errors (the
   expErrorTable).  Instead, the expErrorTable maintains information
   about errors that occur at evaluation time:

    expErrorEntry OBJECT-TYPE
        SYNTAX      ExpErrorEntry
        MAX-ACCESS  not-accessible
        STATUS      current
        "Information about errors in processing an expression.
        Entries appear in this table only when there is a matching
        expExpressionEntry and then only when there has been an
        error for that expression as reflected by the error codes
        defined for expErrorCode."
   INDEX       { expExpressionOwner, expExpressionName }

   More specifically, a MIB module can provide configuration
   applications with information about errors on the managed device by
   creating columnar object types in log tables that contain error
   information particular to errors that occur on row activation.

   Notifications with detailed failure information objects can also be
   used to signal configuration failures.  If this approach is used, the
   configuration of destinations for NOTIFICATION-TYPE data generated
   from configuration failures should be considered independently of the
   those for other NOTIFICATION-TYPEs which are generated for other
   operational reasons.  In other words, in many management
   environments, the network operators interested in NOTIFICATION-TYPEs
   generated from configuration failures may not completely overlap with
   the community of network operators interested in NOTIFICATION-TYPEs
   generated from, for example, network interface failures.

3.12.  Designing MIB Modules for Multiple Managers

   When designing a MIB module for configuration, there are several
   pertinent considerations to provide support for multiple managers.

   The first is to avoid any race conditions between two or more
   authorized management applications issuing SET protocol operations
   spanning over more than a single PDU.

   The standard textual convention document [3] defines TestAndIncr,
   often called a spinlock, which is used to avoid race conditions.

Top      Up      ToC       Page 38 
   A MIB module designer may explicitly define a synchronization object
   of syntax TestAndIncr or may choose to rely on snmpSetSerialNo (a
   global spinlock object) as defined in SNMPv2-MIB.

   snmpSetSerialNo OBJECT-TYPE
   SYNTAX     TestAndIncr
   MAX-ACCESS read-write
   STATUS     current
           "An advisory lock used to allow several cooperating
           command generator applications to coordinate their
           use of the SNMP set operation.

           This object is used for coarse-grain coordination.
           To achieve fine-grain coordination, one or more similar
           objects might be defined within each MIB group, as
   ::= { snmpSet 1 }

   Another prominent TestAndIncr example can be found in the SNMP-
   TARGET- MIB [9], snmpTargetSpinLock.

   Secondly, an agent should be able to report configuration as set by
   different entities as distinguishable from configuration defined
   external to the SNMP domain, such as application of a default or
   through an alternate management interface like a command line
   interface.  Section 3.10.1 describes considerations for this practice
   when designing NOTIFICATION-TYPEs.  The OwnerString textual
   convention from RMON-MIB RFC 2819 [32] has been used successfully for
   this purpose.  More recently, RFC 3411 [1] introduced the
   SnmpAdminString which has been designed as a UTF8 string.  This is
   more suitable for representing names in many languages.

   Experience has shown that usage of OwnerString to represent row
   ownership can be a useful diagnostic tool as well.  Specifically, the
   use of the string "monitor" to identify configuration set by an
   agent/local management has been prevalent and useful in applications.

   Thirdly, consider whether there is a need for multiple managers to
   configure the same set of tables.  If so, an "OwnerString" may be
   used as the first component of a table's index to allow VACM to be
   used to protect access to subsets of rows, at least at the level of
   securityName or groupName provided.  RFC 3231 [25], Section 6
   presents this technique in detail.  This technique does add
   complexity to the managed device and to the configuration management
   application since the manager will need to be aware of these
   additional columnar objects in configuration tables and act
   appropriately to set them.  Additionally, the agent must be

Top      Up      ToC       Page 39 
   configured to provide the appropriate instance-level restrictions on
   the modifiability of the instances.

3.13.  Other MIB Module Design Issues

3.13.1.  Octet String Aggregations

   The OCTET STRING syntax can be used as an extremely flexible and
   useful datatype when defining managed objects that allow SET
   operation.  An octet string is capable of modeling many things and is
   limited in size to 65535 octets by SMIv2[2].

   Since OCTET STRINGS are very flexible, the need to make them useful
   to applications requires careful definition.  Otherwise, applications
   will at most simply be able to display and set them.

   Consider the following object from RFC 3418 SNMPv2-MIB [11].

   sysLocation OBJECT-TYPE
   SYNTAX      DisplayString (SIZE (0..255))
   MAX-ACCESS  read-write
   STATUS      current
           "The physical location of this node (e.g., `telephone
           closet, 3rd floor').  If the location is unknown, the value
           is the zero-length string."
   ::= { system 6 }

   Such informational object types have come to be colloquially known as
   "scratch pad objects".  While often useful, should an application be
   required to do more with this information than be able to read and
   set the value of this object, a more precise definition of the
   contents of the OCTET STRING is needed, since the actual format of an
   instance for such an object is unstructured.  Hence, alternatively,
   dividing the object type into several object type definitions can
   provide the required additional structural detail.

   When using OCTET STRINGS, avoid platform dependent data formats.
   Also avoid using OCTET STRINGS where a more precise SMI syntax such
   as SnmpAdminString or BITS would work.

   There are many MIB modules that attempt to optimize the amount of
   data sent/received in a SET/GET PDU by packing octet strings with
   aggregate data.  For example, the PortList syntax as defined in the
   Q-BRIDGE-MIB (RFC 2674 [26]) is defined as follows:

Top      Up      ToC       Page 40 
    STATUS      current
        "Each octet within this value specifies a set of eight
        ports, with the first octet specifying ports 1 through
        8, the second octet specifying ports 9 through 16, etc.
        Within each octet, the most significant bit represents
        the lowest numbered port, and the least significant bit
        represents the highest numbered port.  Thus, each port
        of the bridge is represented by a single bit within the
        value of this object.  If that bit has a value of '1'
        then that port is included in the set of ports; the port
        is not included if its bit has a value of '0'."

   This compact representation saves on data transfer but has some
   limitations.  Such complex instance information is difficult to
   reference outside of the object or use as an index to a table.
   Additionally, with this approach, if a value within the aggregate
   requires change, the entire aggregated object instance must be

   Providing an SNMP table to represent aggregate data avoids the
   limitations of encoding data into OCTET STRINGs and is thus the
   better general practice.

   Finally, as previously mentioned in Section, one should
   consider the practical ramifications of instance transfer for object
   types of SYNTAX OCTET STRING where they have typical instance data
   requirements close to the upper boundary of SMIv2 OCTET STRING
   instance encoding.  Where such object types are truly necessary at
   all, SNMP/UDP may not be a very scalable means of transfer and
   alternatives should be explored.

3.13.2.  Supporting multiple instances of a MIB Module

   When defining new MIB modules, one should consider if there could
   ever be multiple instances of this MIB module in a single SNMP

   MIB modules exist that assume a one to many relationship, such as
   MIBs for routing protocols which can accommodate multiple "processes"
   of the underlying protocol and its administrative framework.
   However, the majority of MIB modules assume a one-to-one relationship
   between the objects found in the MIB module and how many instances
   will exist on a given SNMP agent.  The OSPF-MIB, IP-MIB, BRIDGE-MIB
   are all examples that are defined for a single instance of the

Top      Up      ToC       Page 41 
   It is clear that single instancing of these MIB modules limits
   implementations that might support multiple instances of OSPF, IP
   stacks or logical bridges.

   In such cases, the ENTITY-MIB [RFC2737] can provide a means for
   supporting the one-to-many relationship through naming scopes using
   the entLogicalTable.  Keep in mind, however, that there are some
   drawbacks to this approach.

   1) One cannot issue a PDU request that spans naming scopes.  For
      example, given two instances of BRIDGE-MIB active in a single
      agent, one PDU cannot contain a request for dot1dBaseNumPorts from
      both the first and second instances.

   2) Reliance on this technique creates a dependency on the Entity MIB
      for an application to be able to access multiple instances of

   Alternately, completely independently of the Entity MIB, multiple MIB
   module instances can be scoped by different SNMP contexts.  This
   does, however, require the coordination of this technique with the
   administrative establishment of contexts in the configured agent

3.13.3.  Use of Special Optional Clauses

   When defining integer-based objects for read-create, read-write and
   read-only semantics, using the UNITS clause is recommended in
   addition to specification in the DESCRIPTION clause of any particular
   details of how UNITs are to be interpreted.

   The REFERENCE clause is also recommended as a way to help an
   implementer track down related information on a given object.  By
   adding a REFERENCE clause to the specific underlying technology
   document, multiple separate implementations will be more likely to

(page 41 continued on part 3)

Next RFC Part