MIB Smithy

17 Common MIB Design Errors

Listed below are among the most common MIB design errors and pitfalls observed by this author that have been submitted with technical support requests over the years in various projects (particularly in the realm of SNMP compliance testing) that the author has been involved with. Along with most of these is an explaination for the error, suggested corrections, and information on how MIB Smithy handles and can help you overcome such errors.

Typically the user has a MIB file that is successfully compiled and loaded by one or more applications in use by the user. He or she (or worse, a customer) at some point finds themselves faced with the task of using that MIB file with a new compiler or application that either warns the user about problems that their other application(s) did not or, worse yet, is unable to successfully load and use the MIB file at all. This is often the result of MIB authors using inadequate or poorly designed tools to create and maintain their MIB modules. MIB authors who use simple text editors and only basic command-line validation tools are often the worst off because the text editor will allow them to make mistakes that the validation tools may silently ignore.

MIB modules should, at the very least, always be tested for SMI and ASN.1 compliance using a wide variety of tools. It is important that one find the errors before their customers do to avoid incurring technical support costs. Better still is using an application such as MIB Smithy, which performs very extensive checks for nearly every possible aspect of the SMI and ASN.1 rules. MIB Smithy will also prevent errors before they happen by ensuring that generated MIBs are correct ASN.1 and not allowing erroneous data entry. As well, MIB Smithy can often automatically correct common errors such as the ones listed below.

In addition to this document, MIB authors are encouraged to read Section 3, Designing a MIB Module, of RFC 3512 (Configuring Networks and Devices with SNMP) for additional "Best Common Practices" in MIB Design, as well as RFC 4181 (Guidelines for Authors and Reviewers of MIB Documents).

Contents

1. The SMIv2 'BITS' data type MUST NOT be imported.
2. ASN.1 comments begin AND end with two hyphens ('--') OR newline.
3. Placing newlines or comments inside the ASN.1 module header.
4. ASN.1 forbids the use of the underscore ('_') character in descriptors.
5. SMIv2 forbids the use of the hyphen ('-') character in descriptors.
6. Using SMIv1 ACCESS versus SMIv2 MAX-ACCESS.
7. SMIv2 Modules MUST define exactly one MODULE-IDENTITY immediately after IMPORTS.
8. SEQUENCE structure elements MUST match a table's columns exactly.
9. ASN.1 'INTEGER' type SHOULD have a range or named-number list in SMIv2.
10. SMIv1 forbids named-number enumerations of value '0'.
11. ExtUTCTime (REVISION/LAST-UPDATED) MUST use four-digit years after 1999.
12. Failure to use ASN.1 SIZE keyword for length refinements correctly.
13. DESCRIPTION MUST be present in SMIv2 OBJECT-TYPE.
14. TEXTUAL-CONVENTIONs cannot be derived from other TEXTUAL-CONVENTIONs.
15. Failure to define reverse-mappable NOTIFICATION-TYPEs.
16. Mixing SMIv1 and SMIv2 in one MIB Module.
17. Using Counter64 to represent non-monotonically increasing values.

The SMIv2 'BITS' data type MUST NOT be imported.

The SMIv2 'BITS' data type is a construct which allows one to define labels for individual bit fields in an OCTET STRING value, similar to the ASN.1 'BIT STRING' data type which is forbidden in SNMP. This data type is what ASN.1 refers to as a "Local Type Reference", due to the fact that it is defined within the OBJECT-TYPE and TEXTUAL-CONVENTION MACROs.

Local Type References of this sort exist only within the scope of the MACRO that defines them, and within any invocation of such a macro in a definition. Outside the OBJECT-TYPE and TEXTUAL-CONVENTION MACROs, the 'BITS' symbol is undefined. Unlike the MACROs themselves and other symbols defined within the SNMPv2-SMI module, an ASN.1 module can not export such as symbol; thus, neither can it be imported in another module. When a module IMPORTS the OBJECT-TYPE and/or TEXTUAL-CONVENTION MACROs, the 'BITS' data type is defined implicitly within the scope of any invocation of those MACROs. So it is neither allowed nor necessary to import the data type.

Depending on the implementation, many MIB compilers will either fail to compile modules that import BITS, or silently ignore this error. A small number of older (buggy) versions of some MIB compilers may require it even though it is forbidden.

MIB Smithy will automatically correct this error for you. When a MIB is loaded into MIB Smithy, if the 'BITS' symbol is detected within the module's IMPORTS list, MIB Smithy will issue a compiler warning and automatically delete the symbol from the IMPORTS list. When the file is subsequently saved, the resulting file will not have the symbol listed. MIB Smithy will also not allow the symbol to be added via the IMPORTS property of the Module Workspace.

ASN.1 comments begin AND end with two hyphens ('--') OR newline.

In ASN.1, comments (informational text intended to be discarded by compilers/parsers) function as a sort of cross between C's opening and closing /* */ form for comments and C++'s comments, which begin with // and continue to the end of the line. Comments in ASN.1 begin with two hyphen characters immediately adjacent to one another, but they can be closed in two ways. Like C++'s //, is that comments continue to the end of the line unless they are closed. A second pair of adjacent hyphens in a line closes the comment.

It is very common for MIB authors to assume that that ASN.1 comments continue to the end of the line regardless of what other characters are present in the line. Often they will use long sets of hyphens to simulate horizontal lines separating sections of their document, not realizing that what they are entering several opened and closed comment sequences. If they happen to use a multiple of four hyphens, plus an additional one at the end (e.g. 5, 9, 13 etc.), a parse error will occur in a compliant ASN.1 parser.

This problem is not helped any by the fact that many MIB compiler authors also make the same mistake, silently discarding the entire line following the opening pair of hyphens. In such a case, the compiler not only has the potential to run into parse errors if a necessary token is interpreted as being commented out, by also has the potential to cause parse errors in a compliant parser that sees a token where another parser sees a comment.

MIB Smithy attempts to find some middle ground and ensure that comments in your MIBs are compatible with both varieties of parsers. First, MIB Smithy correctly interprets a second pair of hyphens in a line as closing a comment. Second, MIB Smithy will detect long sequences of hyphens that end in an extra un-commented hyphen that will cause parse errors in compliant parsers, issue a warning, and discard the extra. Lastly, MIB Smithy's parser will reposition comments that fall between tokens such that all comments appear at the end of the line, and all comments other than those assigned to enumeration or bit labels appear before the assignment they are associated with.

For more information, see "How does MIB Smithy process/format ASN.1 comments?" in the MIB Smithy FAQs.

Placing newlines or comments inside the ASN.1 module header.

While not actually an error in ASN.1 nor in SMI, placing comments or newlines inside the ASN.1 module header can cause problems for tools that attempt to provide some convenience for the user by automatically extracting MIBs from RFC text. MIB modules begin with an upper-case identifier defining the name of the module and the sequence of symbols "DEFINITIONS ::= BEGIN", e.g.:

EXAMPLE-MIB DEFINITIONS ::= BEGIN

ASN.1 also allows an optional OBJECT IDENTIFIER value immediately following the module name to distinguish it from other modules by the same name, and optional "EXPLICIT TAGS" or "IMPLICIT TAGS" keywords immediately after "DEFINITIONS" (See X.208), although these parameters are not allowed by SNMP.

As with elsewhere in an ASN.1 module, comments and newlines are allowed between any token and are treated as whitespace, serving only to separate tokens and are otherwise ignored by parsers. However, some programs which are designed to extract non-ASN.1 text (such as RFC documentation) from a module prior to feeding it into the ASN.1 parser tend to be overly simplistic in their method of finding the start of the module. It is not uncommon for these extractor programs to simply treat the first line containing "DEFINITIONS ::= BEGIN" as the start of the module. Consider the following example:

EXAMPLE-MIB
-- An example ASN.1 module header with
-- newlines and comments thrown in between.
DEFINITIONS ::= BEGIN

In such a case, an extractor that only checks for "DEFINIIONS ::= BEGIN" will fail to treat the module name and comments as part of the module. The first thing the ASN.1 parser will see will be the "DEFINITIONS" token and a parse error will occur. Perfectly valid ASN.1, but a potential pitfall nonetheless.

To avoid this problem, MIB Smithy will always print the module header on a single line, unless for some reason word wrapping kicks in due to an excessively long module name. As mentioned elsewhere on MIB Smithy's handling of ASN.1 comments, it will also reposition all of the comments so that they appear immediately before the name of the record (in this case, immediately before the module name), resulting in:

-- An example ASN.1 module header with
-- newlines and comments thrown in between.

EXAMPLE-MIB DEFINITIONS ::= BEGIN

MIB Smithy also contains a built-in extractor of its own that understands newlines and comments between the module header and other tokens. Importing an RFC document in MIB Smithy will preserve any comments appearing before, in or around the module header, repositioning them as necessary for maximum interoperability.

ASN.1 forbids the use of the underscore ('_') character in descriptors.

The ASN.1 specification defines an explicit set of characters that are allowed within parsed items (generally anything that is not a "quoted string") such as descriptors (i.e., the symbolic name -- or "identifier" in ASN.1 terminology -- of some definition or assignment). Table 2/X.208 of the ASN.1 specification indicates these characters are as follows:

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
1 2 3 4 5 6 7 8 9 0 ; = , { } < . ( ) [ ] - ' "

The underscore character is not among these allowed characters. Most compilers fall into one of two categories here: either they silently allow underscore characters or else they fail to load the MIB module, generating a "parse error". A valid identifier in ASN.1 begins with a letter and is followed by zero or more letters, numbers or hyphen ('-') characters, with the additional restriction that two hyphens cannot be consecutive (as this marks the beginning of an ASN.1 comment) and the last character cannot be a hyphen. All identifiers assigned to MACRO definitions, modules and data types begin with an upper-case letter, and all others begin with a lower-case letter.

When MIB Smithy loads a MIB file, it will issue a compiler warning about any descriptor containing underscores, and automatically convert any it encounters to hyphen characters, which are allowed by ASN.1. This conversion is done wherever identifiers/descriptors are found, so references between definitions will not be broken in the process. Note, however, the following notes on the use of hyphens in SMIv2.

SMIv2 forbids the use of the hyphen ('-') character in descriptors.

Depending on the implementation, some compilers/tools will silently ignore hyphens, and some written only to support SMIv2 have been known to fail with parse errors. Section 3.1 (Macro Invocation) of RFC 2578 (SMIv2) states:

For the purposes of this specification, an ASN.1 identifier consists of one or more letters or digits, and its initial character must be a lower-case letter*. Note that hyphens are not allowed by this specification (except for use by information modules converted from SMIv1 which did allow hyphens).

One should keep this in mind when defining new modules and avoid using hyphen characters wherever possible. During validation, MIB Smithy will warn about any hyphens in descriptors that it finds and, due to ASN.1 restrictions, it will remove hyphens that appear as the last character in a descriptor. It will not, however, convert or remove other hyphens (nor should a person converting an SMIv1 module to SMIv2 do so), as doing so would break backwards compatibility with any other modules that depend on the module with the hyphenated descriptors. This is why, for example, the 'mib-2' OBJECT IDENTIFIER assignment was not renamed 'mib2' when MIB-II was converted to SMIv2.

Using SMIv1 ACCESS versus SMIv2 MAX-ACCESS.

In SMIv1, the ACCESS clause in the OBJECT-TYPE macro specifies which SNMP operations (GET/SET/etc.) are allowed on the object. An ACCESS value of 'read-write', for example, means that the object can be both read with GET or GET-NEXT request and written with a SET request, while an ACCESS value of 'not-accessible' means that the object can neither be read nor written to.

In SMIv2, this clause changed to MAX-ACCESS. In contrast with SMIv1, this clause specifies the maximum allowed access level for any implementation of the object. An object with a MAX-ACCESS value of 'read-write', for example, means that an implementation MAY (and typically will) allow both read and write access, but it is also allowed for implementation-dependent reasons for this object to be implemented as 'read-only'. Additionally, SMIv2 adds a MODULE-COMPLIANCE MACRO, which can be used to specify a 'MIN-ACCESS' value for an object, which is the minimum access level that an implementation MUST support.

When loading MIB files, MIB Smithy uses a module's IMPORTS clause to determine which SMI version is being used, and will issue a "recoverable" compiler error if ACCESS is used where MAX-ACCESS is expected, or vise-versa. When saving MIB files, MIB Smithy will automatically generate whichever is appropriate given the SMI version.

SMIv2 Modules MUST define exactly one MODULE-IDENTITY immediately after IMPORTS.

It is a requirement of SMIv2 that every module define one (and only one) MODULE-IDENTITY, immediately after the module's IMPORTS list. The MODULE-IDENTITY MACRO contains information about and contact information for the MIB author and organization responsible for the MIB module, as well as information on each revision to the module and the date and time the module was last updated.

The OBJECT IDENTIFIER assigned to a module's MODULE-IDENTITY invocation is also commonly used as a top-level anchor point under which all other OBJECT IDENTIFIER values in the module are assigned. Authors of new MIB modules are encouraged to make use of this practice, though it is not always possible when converting SMIv1 modules to SMIv2.

Depending on the implementation, a compiler or tool may be unable to load a module that places the MODULE-IDENTITY other than immediately after the IMPORTS list or contains the fewer or more than one invocation of the macro. At load time, MIB Smithy will issue a "recoverable" compiler error in such cases. If a module contains more than one MODULE-IDENTITY, then the user MUST redefine all but one before validation will be successful. When saving, MIB Smithy will generate the MODULE-IDENTITY in the correct position in the file.

When converting SMIv1 modules to SMIv2, MIB Smithy will also attempt to help automate this process. If all of the module's OIDs are defined under a single top-level anchor point, and that anchor point is an OBJECT-IDENTITY or an ASN.1 OBJECT IDENTIFIER Value Assignment, then MIB Smithy will automatically convert it to a MODULE-IDENTITY. Otherwise, it is up to the user to create a new MODULE-IDENTITY definition within the module, and MIB Smithy will issue a compiler error until this is done.

SEQUENCE structure elements MUST match a table's columns exactly.

SMI allows the definition of OBJECT-TYPEs to be structured in a way that forms what is commonly called a "conceptual table". There are no actual tables in SMI or SNMP, since all accessible objects form a simple ordered list. However, by defining objects so that they share a common OID prefix and subidentifiers corresponding to one or more INDEX objects, the row/column arrangement of a table can be simulated. Each column in a single row shares a common OID prefix, followed by a subidentifier identifying the column OBJECT-TYPE definition, and finally followed by one or more subidentifiers identifying the row that are shared by each column in that row.

To define a conceptual table, four items are needed:

1. An ASN.1 Type Assignment of type "SEQUENCE" that identifies each column OBJECT-TYPE within a row of the table. This assignment is typically named PrefixEntry, where Prefix is a common identifier prefix shared with 2 and 3 (with an upper-case first letter).
2. An OBJECT-TYPE of type "SEQUENCE OF prefixEntry", named prefixTable, which defines the branch in OID space corresponding to the conceptual table.
3. An OBJECT-TYPE of type "PrefixEntry", named prefixEntry, and with subidentifier '1', which identifies the branch in OID space corresponding to rows in the table.
4. A set of OBJECT-TYPE definitions corresponding to each column, assigned OIDs immediately below (subordinate to) 3. Once instantiated in an agent with a set of instance subidentifiers, these define the "cells" of the table.

The "SEQUENCE" Type Assignment above in 1. MUST match exactly the names, order, and types of each column object in 4., and no further subtyping of items in the SEQUENCE definition are allowed. MIB Smithy will check each of these, and issue a compiler error if any item is missing, out of order, with the wrong type, or the SEQUENCE definition contains subtyping structures beyond that allowed for a simple conceptual row. The MIB author must correct these errors for validation to succeed. As of this writing, MIB Smithy will not automatically correct these errors.

ASN.1 'INTEGER' type SHOULD have a range or named-number list in SMIv2.

The ASN.1 'INTEGER' base type, which has no inherent range restrictions imposed by ASN.1, was supplemented by the 'Integer32' type in SMIv2. Identical "on the wire" to INTEGER, Integer32 is defined defined as having an explicit signed 32-bit range of (-2147483648..2147483647). Earlier versions of the SMIv2 specification and Coexistance documents required that any object with a SYNTAX resolving to the ASN.1 'INTEGER' type have either a range or a set of named-number enumerations to ensure that the object has bounded values within the range allowed by SNMP, or else be replaced by Integer32.

For example, RFC 2576 (Coexistence between Version 1, Version 2, and Version 3 of the Internet-standard Network Management Framework), section 2.1.1 (3), states:

(3) For any object with an integer-valued SYNTAX clause, in which the corresponding INTEGER does not have a range restriction (i.e., the INTEGER has neither a defined set of named-number enumerations nor an assignment of lower- and upper-bounds on its value), the object MUST have the value of its SYNTAX clause changed to Integer32, or have an appropriate range specified.

Recent consensus is that this requirement is unnecessary, and an update to RFC 2576 is pending that removes the requirement. The new interpretation is that ASN.1's lack of an inherent INTEGER range restriction is not an issue, because the SMI is not truely ASN.1, and thus the SMI has an implicit signed 32-bit range for 'INTEGER' when used within MIB modules. This has no bearing on the protocol definitions that specify alternate ranges (for e.g. Counter64 or Unsigned32) with tagged INTEGER encodings, as the protocol mappings are ASN.1 and are not strictly tied to the SMI.

However, many existing MIB compilers still follow the old rules and interpretations and will generate failures when encountering object definitions with unbounded INTEGER SYNTAX. To ensure interoperability, use of either Integer32 or INTEGER with bounds is encouraged but no longer required.

When converting modules from SMIv1 to SMIv2, MIB Smithy follows the rules of RFC 2576, section 2.1.1 (3) (as suggested by the pending RFC update), by converting unbounded INTEGER SYNTAX to Integer32. This provides the same on-the-wire encoding and bounds while also being compatible with older MIB compilers. When converting from SMIv2 to SMIv1, where Integer32 does not exist, the converse is also true: MIB Smithy will change OBJECT-TYPEs and TEXTUAL-CONVENTIONs of type Integer32 to INTEGER (and convert TEXTUAL-CONVENTIONs to ASN.1 Type Assignments).

SMIv1 forbids named-number enumerations of value '0'.

SMIv1, as described by (obsolete) RFC 1065, does not allow named-number enumerations with value '0', although RFC 1212 (what is officially referred to as SMIv1) does not specifically mention this. According to section 3.2.1.1 (Guidelines for Enumerated INTEGERs) of RFC 1065:

If an enumerated INTEGER is listed as an object type, then a named-number having the value 0 shall not be present in the list of enumerations. Use of this value is prohibited.

This prohibition is fairly arbitrary, however, and SMIv2 removes this restriction, allowing both negative and zero values for named-number enumerations. According to section 7.1.1 (Integer32 and INTEGER) of RFC 2578:

Note that although it is recommended that enumerated values start at 1 and be numbered contiguously, any valid value for Integer32 is allowed for an enumerated value and, further, enumerated values needn't be contiguously assigned.

Many SMIv1 compilers will fail to compile MIBs that define enumerations with value 0. Because of the potential for SMIv2 MIBs to later need conversion to SMIv1 for use in a particular (older) implementation, MIB Smithy will issue compatability warnings for both 0 and negative values, though it will allow them for both SMIv1 and SMIv2. MIB authors are encouraged to follow the guidelines of RFC 2578, and define all new objects and types with named-number enumerations as starting from 1.

ExtUTCTime (REVISION/LAST-UPDATED) MUST use four-digit years after 1999.

The ExtUTCTime data type, or Extended UTCTime, is an OCTET STRING data type that follows a format similar to that of ASN.1's UTCTime, in that it represents an extended subset of the format for UTCTime. While UTCTime is somewhat flexible in precision, allowing inclusion or omission of seconds, and allowing time zones to be represented with an offset from GMT or with a 'Z' suffix indicating GMT, ExtUTCTime is fairly rigid in its format.

ExtUTCTime values must always be specified in GMT using the 'Z' suffix, and may not include seconds. Additionally, while UTCTime supports only 2-digit years, ExtUTCTime values can be specified in either 2 digits or 4 digits, with 4 digits being a requirement for years after 1999. The complete format for ExtUTCTime is:

[YY]YYMMDDHHMMZ

Where: [YY]YY is the 2 or 4 digit year, MMDD is the two-digit month (01 through 12) and day of month (01 through 31), and HHMM are the hours in 24-hour time (00 through 23) and minutes (00 through 59), and the character 'Z' in the suffix indicates GMT.

Although the ExtUTCTime data type is defined as a normal ASN.1 Type Assignment, it is considered internal to the SMI and modules are expressly forbidden from importing the type. SMIv2's standard TEXTUAL-CONVENTIONs in SNMPv2-TC (RFC 2579) define a DateAndTime type for use in managed objects. The SMI uses ExtUTCTime to represent time stamps in the LAST-UPDATED and REVISION fields of an invocation of the MODULE-IDENTITY macro.

Since most compilers are primarily concerned with data types, ranges and sizes for managed objects, few bother to check the format of these ExtUTCTime values, and it is not unheard of for even some IETF Standards Track MIB modules to contain invalid years. MIB Smithy will verify the format of these values for you by checking to see if each field is within range and the proper capital-Z suffix is present.

MIB Smithy will also verify that that REVISIONs are listed in the proper decending order, automatically reordering them as appropariate, and that the date makes sense: that is, that it doesn't predate the existence of the SMI specification, and doesn't appear to be off in the future. For consistency, MIB Smithy will also automatically convert 2 digit years to 4 digit years where it makes sense to do so. If the format of the ExtUTCTime value is correct, and the year is between 1990 and 1999, MIB Smithy will convert to 4 digit years. Since dates earlier than the existence of the SMI specification may indicate a bigger error than simply forgetting to add a "20" prefix for years after 1999, MIB Smithy will issue a compiler warning and leave it to the user to make sure the date makes sense.

Failure to use ASN.1 SIZE keyword for length refinements correctly.

The SIZE keyword is a holdover from SMI's ASN.1 basis, used in refinements in which one or more allowed octet length constraints are given. In ASN.1, the SIZE keyword is used with some data types to distinguish from other possible constraints to those data types, such as a permitted subset of a character set or a subset of the components allowed by a structured type.

In SMI, the only allowed types of refinements are on the octet length for character string types (i.e., 'OCTET STRING'), an allowed set or range of values for integer types (e.g. INTEGER), or a set of named-number values or bits for the INTEGER or BITS data types. SMI does not allow other refinements to the character string types that are allowed by ASN.1, but the SIZE keyword is nonetheless required by the SMI rules for compatibility with ASN.1.

Numeric data types do not have explicit restrictions on their octet length, as values for such types have an implicit length governed by the number of octets required to encode the value. A signed value between 0 and 127, for example, is typically encoded in a single octet (in addition to tag and content-length octets) for space efficiency, although some more limited implementations have been known to pad values with unnecessary leading 0 octets. As such, the SIZE keyword has no purpose for numeric types, and it is also not allowed for such types by ASN.1 or by the SMI.

Most compilers will fail if the SIZE keyword is used incorrectly, with the notable exception of non-cross-checking compilers (i.e., compilers that operate on a single MIB module and do not cross-check with any referenced information from the module's IMPORTS list). MIB Smithy will check for, and can usually automatically correct, incorrect usage of the SIZE keyword.

At load time, if the SIZE keyword is used in a refinement to a base type, MIB Smithy will issue a "recoverable" compiler error if the base type is one that does not allow the SIZE keyword, and the keyword will be removed, converting the length refinement into a range refinement. If the SIZE keyword is used with a derived type, then MIB Smithy will preserve the keyword and postpone usage checking until the MIB is to be validated or compiled. If, at validation time, the derived type resolves to base type that does not allow the SIZE keyword, it will issue a compiler warning and automatically convert the length refinement into range refinment. The converse is also true: if MIB Smithy finds that a range refinement was specified for a type that requires a length refinement, warnings or "recoverable" compiler errors will be issued and the range refinement will be converted to a length refinement.

If a derived type cannot be resolved to a base type due to a missing dependency, then MIB Smithy will assume that the SIZE keyword (or lack thereof) is correct, preserving the form of the refinment in saved files. If the error has been corrected, then it will be reflected in subsequent validation or compiling phases while the MIB is loaded, as well as in the generated MIB module when previewed or saved to disk.

DESCRIPTION MUST be present in SMIv2 OBJECT-TYPE.

The DESCRIPTION field in the OBJECT-TYPE macro, which did not exist in the original version defined by (obsolete) RFC 1065, nor in RFC 1155, was introduced in RFC 1212 (Concise MIB Definitions) and has been a required field ever since. Whether by accidental omission in a new manually-created MIB module or by manual conversion from modules importing OBJECT-TYPE from RFC 1065 or 1155 to SMIv2, it is often the case that this required field is omitted.

Fortunately, most compilers that this author is familiar with will at least issue a warning, if not generate an error, if this field is not present when OBJECT-TYPE is imported from SNMPv2-SMI. Those that generate errors, however, can pose a slight hassle in that they require the user to perform the tedious task of adding DESCRIPTION fields to all of the objects before they can use the MIB module in their application. MIB Smithy simplifies this task in several ways.

First, MIB Smithy will generate a "recoverable" compiler error* if the DESCRIPTION field is missing and OBJECT-TYPE is imported from an SMI version that requires it. It will also generate "recoverable" compiler errors if the field is present but OBJECT-TYPE is imported from RFC 1065 or 1155. Secondly, MIB Smithy will always generate DESCRIPTION fields in saved files where appropriate based on the imported OBJECT-TYPE version, even if the DESCRIPTION field is empty. Empty yet required DESCRIPTION fields also generate compiler warnings, notifying the user of some unfinished tasks. Lastly, MIB Smithy will automatically convert DESCRIPTION fields (as well as REFERENCES, etc.) to ASN.1 comments if the field is NOT supported by the imported OBJECT-TYPE version, yet those fields are present and non-empty.

TEXTUAL-CONVENTIONs cannot be derived from other TEXTUAL-CONVENTIONs.

The SMIv2 TEXTUAL-CONVENTION macro, defined in RFC 2579 (SNMPv2-TC) is used in SMIv2 MIB modules to define new data types with specific semantic or constraint properties. Functionally, it is similar to an ASN.1 Type Assignment, and types defined as TEXTUAL-CONVENTIONs can be used anywhere that ASN.1 Base Types and Type Assignments can. The macro allows extra information about the type to be given, including a textual description and a suggestion for how values of the given type can/should be formatted for display to the user.

There are a couple of diferences, however. One is that, while ASN.1 allows Type Assignments to be defined such that they reference (derive from) other Type Assignments, this is expressly forbidden by RFC 2579, Section 3.5 (Mapping of the SYNTAX clause):

The SYNTAX clause, which must be present, defines abstract data structure corresponding to the textual convention. The data structure must be one of the alternatives defined in the ObjectSyntax CHOICE or the BITS construct (see section 7.1 in [RFC-2578]). Note that this means that the SYNTAX clause of a Textual Convention can not refer to a previously defined Textual Convention.

Implementations vary with regard to this rule, owing in part, perhaps, to the fact the last sentence above was a change made between RFC 1903 and RFC 2579, and to the ASN.1 macro definition which, if one disregards the comments, would allow it:

Syntax ::=   -- Must be one of the following:
                   -- a base type (or its refinement), or
                   -- a BITS pseudo-type
              type
            | "BITS" "{" NamedBits "}"

Many implementations are capable of using TEXTUAL-CONVENTIONs that derive from other TEXTUAL-CONVENTIONs, despite this rule. Many, however, do not, and will issue compiler errors if they encounter violations of this rule. The restriction is somewhat arbitrary, and there has been talk of removing the restriction in SMIng, but MIB authors should keep it in mind nonetheless. Since many implementations support it, MIB Smithy will generate a compiler warning, and not an error, if violations of this rule are countered. It might be a good idea to rewrite such TEXTUAL-CONVENTIONs so that they derive from base types, particularly for IETF standards track MIBs, though one should carefully consider the ramifications either way.

Failure to define reverse-mappable NOTIFICATION-TYPEs.

The SMIv2 NOTIFICATION-TYPE macro, like its SMIv1 predecessor the TRAP-TYPE macro, is used to define information "contained within an unsolicited transmission of management information", i.e., an SNMPv1 Trap-PDU or an SNMPv2-Trap-PDU or InformRequest-PDU. Unlike other interactions, where an SNMP agent only acts as a responder to requests sent by an SNMP manager, these PDUs may be sent at any time by the agent.

In SNMPv2/SNMPv3, all of the PDUs have the same "on-the-wire" structure, although some fields have different semantics in the case of the Bulk-PDU. In SNMPv1, however, the Trap-PDU posessed an entirely different structure, aligned to the fields of the TRAP-TYPE macro, and identifying a trap/notification by its generic- and specific-trap integer fields and an enterprise OBJECT IDENTIFIER. The NOTIFICATION-TYPE macro is aligned to the structure and semantics of the SNMPv2-Trap-PDU and InformRequest-PDU, and identifies a notification solely by an OBJECT IDENTIFIER value in the snmpTrapOID variable of the PDU.

It is often the case, however, that SMIv2 NOTIFICATION-TYPEs must be transmitted via SNMPv1 Trap-PDU, or SMIv1 TRAP-TYPEs must be transmitted via SNMPv2-Trap-PDUs. Such is the case, for example, with an SNMPv1-only agent supporting SMIv2 MIBs (the SMI version and the SNMP version are not exclusively tied to one another), or an SNMPv1-to/from-SNMPv2/v3 proxy. For this reason, RFC 2576, (Coexistence between Version 1, Version 2, and Version 3 of the Internet-standard Network Management Framework), section 3, describes the process by which notification parameters can be translated between SMI and SNMP versions. Part of this process involves mapping the snmpTrapOID value to and from the generic-trap, specific-trap and enterprise fields of a TRAP-TYPE or SNMPv1 Trap-PDU:

(2) If the SNMPv1 generic-trap parameter is 'enterpriseSpecific(6)', the SNMPv2 snmpTrapOID parameter SHALL be the concatentation of the SNMPv1 enterprise parameter and two additional sub- identifiers, '0', and the SNMPv1 specific-trap parameter.

(3) If the SNMPv1 generic-trap parameter is not ' enterpriseSpecific(6)', the SNMPv2 snmpTrapOID parameter SHALL be the corresponding trap as defined in section 2 of RFC1907 [12]:

(RFC 2576, Section 3.1 - Translating SNMPv1 to SNMPv2)

- If the SNMPv2 snmpTrapOID parameter is not one of the standard traps as defined in RFC1907 [12], then the SNMPv1 enterprise parameter SHALL be determined from the SNMPv2 snmpTrapOID parameter as follows:

- If the next-to-last sub-identifier of the snmpTrapOID is zero, then the SNMPv1 enterprise SHALL be the SNMPv2 snmpTrapOID with the last 2 sub-identifiers removed, otherwise - If the next-to-last sub-identifier of the snmpTrapOID is non-zero, then the SNMPv1 enterprise SHALL be the SNMPv2 snmpTrapOID with the last sub-identifier removed.

(RFC 2576, Section 3.2 - Translating SNMPv2 to SNMPv1)

A NOTIFICATION-TYPE is considered "reverse-mappable" if it can be translated into a TRAP-TYPE or SNMPv1 Trap-PDU and back again and result in the same snmpTrapOID value. This can be accomplished by always defining NOTIFICATION-TYPEs with OID values such that the second to last subidentifier is 0. When translated to SMIv1/SNMPv1, each subidentifier up to the 0 becomes the enterprise value, and the subidentifier after the 0 becomes the specific-trap value. When translating back to SMIv2/SNMPv2, the snmpTrapOID value is set to enterprise.0.specific-trap, and the original snmpTrapOID value is restored. Otherwise, an original snmpTrapOID value of enterprise.specific-trap will also be remapped to enterprise.0.specific-trap, and the recipient will be unable to identify the notification.

MIB authors should also be wary of including variables in notifications with data types that are not supported by SMIv1/SNMPv1 (specifically, Counter64). An implementation will be either unable to translate the notification to SNMPv1 (if it follows RFC 2576, Section 3.2(6)), or it will will delete the variable from the notification (if it follows the earlier version of the Coexistance document, RFC 2089, Section 3.3(1)). Either way, this will result in information loss and the NOTIFICATION-TYPE will again be considered non-reverse-mappable.

MIB Smithy will issue compiler warnings if it finds that a NOTIFICATION-TYPE is not reverse-mappable. It will not automatically make any corrections, however, as doing so would potentially break compatibility between the module and any existing implementation of the module.

Mixing SMIv1 and SMIv2 in one MIB Module.

This problem is similar in nature to the use of ACCESS instead of MAX-ACCESS in an SMIv2 OBJECT-TYPE definition. The issue may occur due to a misunderstanding of the SMI rules or, more often, due to an incomplete conversion from one SMI version to the other, either manually (in which case some part of the conversion may have been overlooked) or with an converter program (if, for example, an SMIv2 module using SMIv2-only data types is converted to SMIv1).

SMIv2 rules explicitly forbid the use of SMIv1 macros within SMIv2 information modules (RFC 2578, Section 3) as well as the Coexistance rules for converting an SMIv1 module to SMIv2 (RFC 2576, Section 2.1). This includes the TRAP-TYPE macro, which is replaced by NOTIFICATION-TYPE in SMIv2, as well as using the SMIv1 form for OBJECT-TYPE, various SMIv1-only or SMIv2-only data types (Counter/Counter32, Gauge/Gauge32, Counter64, BITS), and certain ACCESS and STATUS values.

To avoid incomplete conversions, it is usually best to use an automated converter. One should carefully check the conversion for any unexpected changes, and use a thorough validation tool to check for compliance to the new SMI version. MIB Smithy will both automatically convert between SMI versions for you, as well as check them extensively for SMI compliance. MIB Smithy should be capable of completely converting your MIBs from one version to the other, including converting SMIv2-only macros such as MODULE-IDENTITY, OBJECT-GROUP, etc. to ASN.1 OBJECT IDENTIFIER value assignments, with the exception of objects or types based on Counter64.

The Counter64 data type does not exist in SMIv1, nor in SNMPv1. As it is conceivable in rare circumstances that a person converting from SMIv2 to SMIv1 may want the Counter64-based definitions preserved, MIB Smithy will not delete such definitions. However, SMIv1 modules that reference Counter64 will fail MIB Smithy's validation. The references must be deleted or changed (as appropriate and as allowed by SMI rules governing backwards-compatibility in modifications) before validation will succeed.

Using Counter64 to represent non-monotonically increasing values.

The SMIv1 Counter and SMIv2 Counter32 and Counter64 data types are specifically designated for use in representing monotonically increasing values (that is, values which only increase, and never decrease, unless they wrap around to 0 from their maximum value). Counter64 is the first and only 64-bit data type currently supported by SMI and SNMP (v2 and v3 only).

In lieu of Integer64, Unsigned64 and Gauge64 data types which have yet to be introduced, some MIB authors may be tempted to use Counter64 to represent arbitrary large values. Consider, for example, the CounterBasedGauge64 TEXTUAL-CONVENTION defined by RFC 2856 (HCNUM-TC), designed to act as a Gauge64 value by overriding the semantics of Counter64. This is forbidden by the rules governing the use of Counter data types, which is acknowledged in the DESCRIPTION for CounterBasedGauge64:

Note that this TC is not strictly supported in SMIv2, because the 'always increasing' and 'counter wrap' semantics associated with the Counter64 base type are not preserved. It is possible that management applications which rely solely upon the (Counter64) ASN.1 tag to determine object semantics will mistakenly operate upon objects of this type as they would for Counter64 objects.

Instead of using Counter64 for non-monotonically increasing data, MIB authors should consider using two Unsigned32 objects representing the upper and lower 4 bytes of data. Implementations that know the semantics of these objects and support 64-bit values can be written to format such values for display. Alternately, consider using two Unsigned32 values to represent different resolutions or significant digits. The UNITS field of the SMIv2 OBJECT-TYPE macro may be helpful in allowing management applications to represent the values in an understandable format for the user.

Once versions of SNMP and the SMI are introduced that support 64-bit values other than Counter64, MIBs can be extended with additional augmenting objects using the new 64-bit values. The pair of 32-bit objects can then be deprecated, made obsolete, or preserved along-side the new objects for backwards-compatibility.