MIB Design Dos and Dont's
This page contains descriptions, explanations, and solutions for the top 10 MIB Design errors. These issues have been collected over years from support questions and consulting projects. Soon it turned out, that a few misunderstandings of the Structure of Management Information RFCs produce a majority of over 80% of the syntax errors. This page is an attempt to help MIB authors to identify and avoid these, unfortunately very common, errors in order to increase interoperability and usability of SNMP based solutions.
Readers are encouraged to view also the following documents:
- Guidelines for Authors and Reviewers of MIB Documents (RFC4181)
- Configuring Networks and Devices with Simple Network Management Protocol (SNMP), section 3, Designing a MIB Module (RFC 3512)
Why do so many (enterprise) MIB modules contain syntax errors and other design flaws? The main reason is probably, a lack of good MIB design tools (editors and compilers) in the early years of SNMP. MIB authors relied on inaccurate implementations of MIB parsers that were not developed to do strict syntax and semantic checking but rather designed to be error-forgiving. With an increasing number of available SNMP tools, interoperability problems also increased caused by the diversity of different error checking levels and capabilities.
Another reason for many interoperability issues is likely to be the “bad habit” of many MIB compilers and tools to provide customizable error reporting levels allowing users to disable reporting of errors/warnings although these errors - or even more worse - warnings report SMI standard violations.
The following list is by far not complete by means of a complete collection of MIB design errors or pitfalls, nevertheless it tries to shed some light on the most commonly made and fewest understood errors:
- Every SMIv2 MIB module must define exactly one MODULE-IDENTITY immediately following IMPORTS
- Descriptors must start with a lower case letter and MIB module names with an upper case letter
- In SMIv2 sub-typing and enumerating values are forbidden in SEQUENCE clauses
- Descriptors must not contain underscore (‘_’) characters
- The ASN.1 primitive type ‘INTEGER’ should only be used for named-number lists in SMIv2
- Every accessible OBJECT- and every NOTIFICATION-TYPE definition must be contained in at least one object group
- The ExtUTCTime format used for LAST-UPDATED and REVISION clauses is [YY]YYMMDDhhmmZ
- A TEXTUAL-CONVENTION cannot refer to a previously defined TEXTUAL-CONVENTION
- The elements in a SEQUENCE clause must match a table’s lexicographic ordered columns exactly
- Mixing SMIv1 and SMIv2 constructs and clauses in the same MIB module
RFC 2578 §3 requires that every SMIv2 MIB module starts with a MODULE-IDENTITY construct (immediately following the IMPORTS clause). Because the Structure of Management Information (SMI) lacks explicit versioning, the absence or presence of the MODULE-IDENTITY is the only usable indication for a SMI parser whether a module is written for SMI version 1 (MODULE-IDENTITY is absent) or version 2 (MODULE-IDENTITY is present). Probably caused by some MIB compilers that cannot handle object identifier forward referencing correctly, some MIB authors do not place the MODULE-IDENTITY immediately following the IMPORTS clause as shown be the below example.
The attentive reader will have recognized a second error in the above example: The missing import of the MODULE-IDENTITY macro (see RFC 2578 §3.2). But more important is the wrong placement of the MODULE-IDENTITY construct. MIB parsers that differentiate between SMIv1 and SMIv2 (what any validating MIB parser should) will report an error about the unexpected MODULE-IDENTITY construct in the above example. A correct version of the above MIB module would read as follows:
Note: All comments (green text) in the above example are optional and need not to be present. In fact some old MIB compilers have problems correctly recognize the end of comments. The end of a comment is either marked by two consecutive hyphens (‘--’) or the end of the line. The first should be avoided for maximum interoperability.
Descriptors, i.e., object names, enumeration labels, have to start with a lower case letter. MIB module names and type names, i.e., names of TEXTUAL-CONVENTIONs and SEQUENCEs, have to start with an upper case letter. For more details see RFC 2578 §3.1.
RFC 2578 §7.1.12 requires that syntax clauses of the subordinate objects do not contain sub-typing or enumeration of values. Consequently the red marked content have to be removed from the following conceptual row definition example in order to be valid SMIv2:
Note: In the above example, only the red marked portions are invalid. The object names for the OBJECT-TYPE definitions have been chosen to have a common prefix as recommended by RFC 2578, that is unique (by best effort) across other MIB modules. For this example, the common prefix is “mibdesignInvalidSequence”.
Descriptors (including identifiers like MIB module names and type names) must not contain other characters than:
a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 -
* The hyphen (‘-’) is only allowed in MIB module names and for SMIv1 descriptors and identifiers (e.g. enumeration labels). In SMIv2, hyphens are only allowed if the MIB module was converted from SMIv1 (which is hard to prove by a MIB compile, see also SMIv2 Design Team Issues). Hyphens in enumeration labels are not allowed in SMIv2. In any case a descriptor or identifier must not end with a hyphen. One reason for the latter, might be easier mapping of enumeration labels to programming languages, where the hyphen is commonly interpreted as minus sign.
Although RFC 2578 not explicitly forbids using the INTEGER primitive type for (non-enumerated) integer types, it is recommended to use Integer32 for such type definitions instead. When ignoring this recommendation, one has to add a range restriction on the INTEGER primitive type, to narrow its value range at least to -2147483648 to 2147483647 which is a requirement by RFC 2576 (Coexistence between Version 1, Version 2, and Version 3 of the Internet-standard Network Management Framework) §2.1.1. This restriction seems to be unnecessary because INTEGER and Integer32 are indistinguishable on the wire, but theoretically the ASN.1 primitive type can represent values outside the above range. RFC 2576 probably tried to avoid misunderstandings by MIB readers familiar with ASN.1 about the possible value range of such types. Future enhancements regarding 64bit signed INTEGER values might have been also a motivation for this rule. The following example illustrates this typical error. The error is solved simply by replacing “INTEGER” with “Integer32” in the first red marked row:
Note: The second line above was marked by MIB Designer because it expected a range restriction but found “MAX-ACCESS”.
6. Every accessible OBJECT- and every NOTIFICATION-TYPE definition must be contained in at least one object group
RFC 2580 §3.1 and §4.1 respectively require that each accessible OBJECT-TYPE definition must be contained in at least one OBJECT-GROUP definition and every NOTIFICATION-TYPE definition must be contained in at least one NOTIFICATION-GROUP definition. These requirements assure that every object of a MIB module can referenced by a compliance statement. This kind of error is usually introduced in a MIB module when a new object is added and the MIB author forgets to add it to a group. MIB Designer offers the option to import a MIB module with a lenient MIB compiler mode and then adding the missing object group entries by using a shuffle dialog that shows the unassigned OBJECT-TYPEs or NOTIFICATION-TYPEs respectively.
The correct format for the LAST-UPDATED and REVISION fields is as follows (see RFC 2578 §2): YYMMDDhhmmZ or YYYYMMDDhhmmZ where:
|YY||last two digits of year (only years between 1900-1999)|
|YYYY||last four digits of the year (any year)|
|MM||month (01 through 12)|
|DD||day of month (01 through 31)|
|hh||hours (00 through 23)|
|mm||minutes (00 through 59)|
|Z||the character Z, which denotes GMT, must always be present.|
RFC 2579 §3.5 requires that the SYNTAX clause of a TEXTUAL-CONVENTION refers to SMIv2 base types only. Thus, it is an error to derive a TEXTUAL-CONVENTION from another as the following example shows:
The above TEXTUAL-CONVENTION would have been correctly defined as follows:
Since ASN.1 allows type assignments to derive types from other types an evil-minded MIB author could think about defining AppnTOSPrecedence as follows:
Although this would be legal, it is not recommended for the following reasons:
- There cannot be associated any parsable information to an ASN.1 type assignment. In the above example important information included in the description clause would be lost.
- RFC 2576 §2.1.1 demands that all ASN.1 type assignments should be converted to TEXTUAL-CONVENTION definitions in a SMIv2 MIB module.
- Although MIB Designer can resolve such derivation chains even across several MIB modules, some MIB compilers cannot which could cause interoperability issues. For example, there are MIB compilers that would not recognize that AppnTOSPrecedence in the above example has inherited the DISPLAY-HINT “255a” from DisplayString.
RFC 2578 §7.1.12 requires that for every columnar object of a conceptual table definition a corresponding entry is present in the SEQUENCE clause defining the syntax of the conceptual row of the table. The entries in the SEQUENCE clause must appear in the lexicographic order of the columnar objects (thus ordered by their last sub-identifier). Normally this is not problematic, since most MIB authors order the columns by the last sub-identifier. But if this is not the case, for example if columns have been added by a new revision of a MIB module, then attention has to paid on the order of the elements in the corresponding SEQUENCE clause.
The following example illustrates an error caused by wrong ordering of the SEQUENCE elements. To correct the error, one would have to swap mibdesignDontsInvalidSeqCol3 and mibdesignDontsInvalidSeqCol2 entries as indicated by the red boxes. Changing the sub-identifiers of those columns is not allowed by a revision, because this would change the behavior of the table on the wire.
RFC 2578 §3 explicitly forbids the usage of SMIv1 macro definitions in SMIv2 modules. The usage of SMIv2 constructs like TEXTUAL-CONVENTION is forbidden in SMIv1 too. These kind of errors often occur when manually converting a module from from one version to another and when the MIB parser/compiler used to check the conversion result does not properly distinguish between SMIv1 and SMIv2. MIB Designer clearly distinguishes between SMIv1 and SMIv2 and will reliably report such errors. In addition it provides automatic conversion from SMIv2 to SMIv1 (see RFC 2576 for situations where an automatic conversion is not completely possible). Any new SNMP MIB module should be written in SMIv2 (the corresponding RFCs 2578, 2579, and 2580 are STANDARD). That’s why MIB Designer focusses on SMIv2 and does not allow to write new MIB modules in SMIv1. Nevertheless, MIB Designer warns MIB author’s when defining a NOTIFICATION-TYPE that is not backward-compatible with SMIv1 and SNMPv1 (see RFC 2576 §3 for details), because the NOTIFICATION-TYPE’s second to last sub-identifier is not zero. Although RFC 2576 defines a mapping for such notifications to SNMPv1 traps, it is wise to avoid such notification definitions for better interoperability.