MIB Smithy

MIB Modules and PIB Modules

MIB Modules are the topmost structure in a MIB specification, and likewise for PIB modules. A typical SNMP or COPS device supports many modules, each containing related definitions for subset of that device's functionality, often shared with other similar devices. For example, most SNMP devices support IF-MIB, which defines a set of objects for management of network interfaces in the device. The basic form for an ASN.1 module, is as follows:

ModuleName ?OIDValue? DEFINITIONS ?TagDefault? ::= BEGIN
?ImportsList?
?ExportsList?
?AssignmentsList?
END

The OIDValue, TagDefault, and ExportsList properties, described below, are not allowed by SMIv2 (nor the latter two by SMIv1), although MIB Smithy will allow you to edit them so that they may be removed or so that MIB Smithy can be used to edit other ASN.1 (but non-SMI) modules. The AssignmentsList property represents zero or more type assignments, value assignments (although SMI allows only OBJECT IDENTIFIER value assignments) and macro invocations (not allowed by SMI), which are described in later chapters. For SMIv2 modules, the AssignmentsList always begins with a single MODULE-IDENTITY statement, which may or may not be the topmost node in OID space that all other OIDs in the module are assigned under.

Creating a MIB or PIB Module

To create a module in MIB Smithy, one or more files must first be present (created or loaded) in the project. Use the Project Tree to select the file in which to create the module. Then, you can either: use Insert → New Module from the main menu; click on the Create Module button in the Toolbar; or right-click on the file within the Project Tree and use its New Module menu item. MIB Smithy will then launch the New Module Wizard, which can guide you through creating the basic top-level structure of the module.

The first page of the New Module wizard is where you specify the type of module you would like to create: whether it will be an SMIv1 MIB Module, an SMIv2 MIB Module or a COPS-PR-SPPI PIB Module. The type of module selected will help to determine naming conventions, the initial set of symbols to add to the IMPORTS section for the module, and what basic layout elements will likely be needed. Selecting Custom allows you to create an empty module with no IMPORTS and none of the basic structure if you find the suggested layout is unsuitable.

After selecting the type of module to create, you can specify a prefix identifier string (starting with a lowercase letter) to use for each of the records in the module's basic layout. MIB Smithy will suggest a module name based on the prefix by converting all characters to uppercase, inserting hyphens before any capitalized letters in the prefix, and adding a "-MIB" or "-PIB" suffix depending on the module type. You are free to change the module name, although this is the common naming convention. You can also skip the naming entirely and let MIB Smithy generate unique names to start with.

If you selected Custom, then you can click the Finish button to create the empty module at this point. Otherwise, click the Next button to proceed to the next page.

The second page of the wizard is where the basic top-level structure of the OID tree can be configured. By selecting the types of records you plan to create in the module, MIB Smithy will add appropriate IMPORTS and build the tree based on IETF guidelines. Some options may not be available depending on the type of module being created: for instance, COPS-PR-SPPI does not have NOTIFICATION-TYPE, TRAP-TYPE or AGENT-CAPABILITIES macros, so they do not apply.

You can also specify the OID value to assign to the top-most record of the OID tree within the module. For SMIv2 and COPS-PR-SPPI modules, this is usually the required MODULE-IDENTITY statement; for SMIv1 modules, it is a simple OBJECT IDENTIFIER Value Assignment. You can leave this field blank if you don't yet know the OID that will be assigned, in which case MIB Smithy will give it a default initial value of 0.0.

Once you have finished configuring the module, click Finish and the module and its structure will be created. Assuming all of the options were checked, and the prefix, module name and OID value are as shown in the figures (muonicsBase, MUONICS-BASE-MIB and enterprises.15957, respectively), the following layout will be created:

MUONICS-BASE-MIB
|
+--muonicsBaseMIB(enterprises.15957)
   |
   +--muonicsBaseNotifications(0)
   |
   +--muonicsBaseObjects(1)
   |  |
   |  +--muonicsBaseStats(1)
   |  |
   |  +--muonicsBaseConfig(2)
   |
   +--muonicsBaseConformance(2)
      |
      +--muonicsBaseCompliances(1)
      |
      +--muonicsBaseCapabilities(2)
      |
      +--muonicsBaseGroups(3)

This layout provides a decent balance between organization for ease of understanding of the module and manageability for the user. For instance, it is recommended that configuration objects, which typically require higher administrator-level access priviledges than do other objects, have a branch of their own. This makes it easier for the administrator to grant permissions via the View Based Access Control Module (VACM), which grants access to users by subtree. Also, defining all of the notifications under a single branch with a subidentifer of 0 allows the notifications to be compatibile with SNMPv1 and SMIv1, where the OID of a NOTIFICATION-TYPE is split at the 0 to determine the enterprise-oid and specific-trap parameters of a TRAP-TYPE or SNMPv1 Trap PDU.

Converting between SMI Versions

MIB Smithy can automate most of the tasks involved in converting a MIB module from SMIv1 to SMIv2 or vise versa. To convert, load the module into MIB Smithy and right-click on the module record in the Project Tree. There you can select Convert → To SMIv1 or Convert → To SMIv2 from the menu.

When converting from SMIv1 to SMIv2, MIB Smithy will, at a minimum:

1. Update IMPORTS module references to the SMIv2 base modules (e.g. SNMPv2-SMI).
2. If there is a single topmost OID assignment under which all other records in the module are defined, convert it to a MODULE-IDENTITY statement.
3. Convert TRAP-TYPEs to NOTIFICATION-TYPEs.
4. Convert NetworkAddress to IpAddress, creating a new additional columnar OBJECT-TYPE if necessary because the object happens to be called out in a table's INDEX.
5. Convert Counter to Counter32, Gauge to Gauge32.
6. Convert the OBJECT-TYPE's ACCESS field to MAX-ACCESS.
7. Add an empty DESCRIPTION field to OBJECT-TYPEs.
8. Convert Type Assignments to TEXTUAL-CONVENTIONs (at least once descriptions have been added).

When converting from SMIv2 to SMIv1, MIB Smithy will, at a minimum:

1. Update IMPORTS module references to the SMIv1 base modules (e.g. RFC-1212, RFC1155-SMI).
2. Convert NOTIFICATION-TYPEs to TRAP-TYPEs.
3. Convert the OBJECT-TYPE's MAX-ACCESS field to ACCESS.
4. Convert to TEXTUAL-CONVENTIONs to Type Assignments.
5. Convert all other SMIv2-only macros to OID value assignments, with fields of those macros converted to comments.
6. Convert Counter32 to Counter, Gauge32 to Gauge.

General Properties

The Module Name, TagDefault and OID Value properties are all available to be edited from the General Page of the Module Workspace, which is pictured below.

Module Name

The module name is the most common method of referring to the module, and is of primary importance in sharing definitions between modules. Care should be taken in choosing a name that roughly describes the purpose of the module while minimizing to the possibility of naming conflicts with other modules, since compilers often do not provide mechanisms for working around such collisions. Further, the IETF requires that all standards-track modules be assigned unique names.

A valid module name begins with an uppercase letter. It may contain zero or more additional letters, numbers or hyphens, provided it does not end in a hyphen and no two hyphens are adjacent. Module names are usually given in all-uppercase, such as SNMP-FRAMEWORK-MIB, although this is not a requirement and is not always the case (c.f. IANAifType-MIB).

This property is required for all modules.

Tag Default

This property is used in ASN.1 to specify the default tag handling in TaggedType definitions (which define new types with alternate on-the-wire encodings), and whether they are interpreted as being defined with the EXPLICIT or IMPLICIT keyword if unspecified in the TaggedType definition. The default taken by ASN.1 if the TagDefault property is unspecified is as if EXPLICIT TAGS was specified. Tags are the octet values at the beginning of the on-the-wire encoding that identify the data type associated with the contents of the encoding.

Implicit tagging indicates, for those encoding rules which provide the option, that explicit identification of the tag of the "Type" in the "TaggedType" is not needed during transfer. (X.208 section 26.9)

This property is optional, and not allowed by SMI.

In the SNMP world, only the base modules defining the SMI language are allowed to define TaggedTypes (those of the on-the-wire data types used by SNMP), and neither the SMI language nor the protocol allows definitions of types with alternate encodings: only refinements to the existing datatypes. Thus, this property should always be set to EXPLICIT when editing MIB modules. Because EXPLICIT TAGS is the ASN.1 default, and because this property is not permitted in MIB modules, MIB Smithy will not generate this field in the module header unless its value calls for IMPLICIT TAGS.

OID Value

ASN.1 allows an optional OBJECT IDENTIFIER value to be assigned to a module within the module header. It uses this value to resolve ambiguities that arise when two different modules have the same name, allowing (for example) a third module, which imports definitions from both, to indicate which of the two is intended for each module's list of imported symbols.

This property is optional, and not allowed by SMIv2.

SMIv2 does not allow OID values to be assigned to modules (although SMIv1 is silent on the matter). Instead, SMIv2 modules are uniquely identified by the OID value of the module's MODULE-IDENTITY statement, which is a requirement for all SMIv2 modules, and allows the name or OID of the MODULE-IDENTITY to be referenced in another module's IMPORTS statement in the same way that ASN.1 allows a module's OID to disambiguate module references.

See Also

Object Identifier Values

Imports Property

The Imports property, which corresponds to the ImportsList item shown above in the general form for an ASN.1 module, defines the list of symbols that the module depends on from other modules. If a module uses types or values defined in another module, they are listed in the IMPORTS section at the beginning of the module.

This property is technically optional for all modules. Practically, however, MIB modules pretty much always define things that reference symbols from other modules that need to be imported!

In a sense, imports are similar to "include files" in a language such as C, although different applications handle them in different ways. Proper implementations are "forward-referencing", in that dependencies are resolved on an as-needed basis. Others are "reverse-referencing" and require the imported modules to already be present and loaded when the imports list is processed. MIB Smithy would be properly described as "forward-referencing", as it maintains an internal index that is automatically updated whenever modules are loaded or records are modified, postponing any "missing dependency" errors/warnings until necessary for validation or use.

In addition to importing types and values from other modules, SMI requires macros such as OBJECT-TYPE and TEXTUAL-CONVENTION to be imported if used, as well as the SMI base types (not including the BITS construct, which is not actually type definition). ASN.1 base types, on the other hand, may not be imported under any circumstances: they are defined implicitly in the same way that the int and similar data types are in C; you don't have to #include anything in a C source file to use the int data type, but you do if you want to use a type defined as typedef int in some other header file.

The module from which the SMI macros are imported determines the SMI version (such as SNMPv2-SMI for SMIv2's OBJECT-TYPE versus RFC-1212 for SMIv1's OBJECT-TYPE). When generating normal SMI format output (such as when saving or previewing files), MIB Smithy will output records using the appropriate format for the imported macro version. It will also use the imports to determine whether it should validate MIBs according to SMIv1 or SMIv2 rules. Note, however, that SMIv2 forbids modules from importing from both SMIv1 and SMIv2 base modules.

The Imports Page of the Module Workspace allows you to edit the list of imported symbols when required. With MIB Smithy version 2.3 and later, the module's Imports property is automatically amended whenever records are created or edited to reference definitions from other modules, that have yet to be imported, and which can be chosen unambiguously from the available options.

To add a symbol to the imports list manually, a module name and the symbol name must be typed or selected in the appropriate fields. Clicking on the arrow in the Module Name/Filter combo box allows you to select from among the set of loaded modules if you do not wish to type the module name by hand. Clicking on the arrow in the Symbol Name combo box allows you to select from among the symbols defined within the specified module or, if the Module Name/Filter entry is set to "-- Show All Modules --", from among all symbols in all other loaded modules.

Once a module and symbol name have been specified, click the "Add" button to add it to the list. If the specified symbol already exists in the imports list (such as if you click on an existing symbol), you also have the options to delete the symbol from the list using the "Remove" button, or change the module name associated with the symbol using the "Modify" button.

Because MIB Smithy supports disambiguating features of the SMI and ASN.1 language for duplicate symbols imported from different modules, it will allow you to add the same symbol with different module names, so you should be careful not to add duplicate symbols unintentionally. If you do, however, MIB Smithy will provide warnings to you during validation.

The "Advanced" button in this page makes visible a third column (the "Module OID" column), allowing an OID value to be specified to be associated with the module reference. For SMIv1 modules, this may be the OID value in the ASN.1 module header for the module. For SMIv2 modules, this may be the OID value for the MODULE-IDENTITY statement in that module. This feature may be used to disambiguate imported references when two imported modules have the same name. In this case, the OID uniquely identifies the module, while the module name may be different from what is specified in the actual module. This becomes the "local" module name, which can be used in type and value references of the form "modulename.descriptor".

See Also

Object Identifier Values

Exports Property

The Exports property, which corresponds to the ExportsList item listed above in the general form for an ASN.1 module, defines the list of symbols within the module that may be imported by other modules.

This property is optional, and not allowed by SMI.

ASN.1 recommends that each symbol in a module that is appropriate for reference from other modules be listed within the EXPORTS part of the module header. However, in SMI all symbols are implicitly exported. It should not usually be necessary to modify this property. It is provided only as a convenience for use in creating non-SMI modules in ASN.1 or for removing the exports list from older modules in the process of updating them to later SMI versions.

The Exports Page of the Module Workspace allows you to edit the list of exported symbols. By default, the "Export All Symbols" checkbutton is selected, the symbol list cannot be edited, and MIB Smithy will not generate the optional ExportsList part of the ASN.1 module when generated and saved.

To add a symbol to the exports list, uncheck the "Export All Symbols" checkbutton, enter the symbol name or click on the arrow in the combo box to select from among the module's exportable symbols, and click the "Add" button. To remove a single symbol from the exports list, click on the symbol or enter its name and click the "Remove" button. To remove all symbols from the exports list, you can remove each individually or simply check "Export All Symbols".

Comments Property

The Comments Property, which is common to all MIB Smithy records for which ASN.1 is generated (including modules, type assignments, OBJECT-TYPEs, etc.), allows you to specify optional comments that are to be associated with the record. Like comments in programming languages, ASN.1 comments are bits of text that allow extra descriptive text to be provided that are discarded by normal parsers.

This property is unconditionally optional.

See Also

Formatting Comments