| < Prev | Back to Table of Contents | Next > |
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.
Figure - New Module Wizard, Step 1
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.
Figure - New Module Wizard, Step 2
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 and 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:
- Update IMPORTS module references to the SMIv2 base modules (e.g. SNMPv2-SMI).
- 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.
- Convert TRAP-TYPEs to NOTIFICATION-TYPEs.
- 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.
- Convert Counter to Counter32, Gauge to Gauge32.
- Convert the OBJECT-TYPE's ACCESS field to MAX-ACCESS.
- Add an empty DESCRIPTION field to OBJECT-TYPEs.
- 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:
- Update IMPORTS module references to the SMIv1 base modules (e.g. RFC-1212, RFC1155-SMI).
- Convert NOTIFICATION-TYPEs to TRAP-TYPEs.
- Convert the OBJECT-TYPE's MAX-ACCESS field to ACCESS.
- Convert to TEXTUAL-CONVENTIONs to Type Assignments.
- Convert all other SMIv2-only macros to OID value assignments, with fields of those macros converted to comments.
- Convert Counter32 to Counter, Gauge32 to Gauge.
General Properties
The Module Name (1), TagDefault (2) and OID Value (3) properties are all available to be edited from the General Page of the Module Workspace, which is pictured below.
Figure - Module Workspace, General Page
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
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.
Figure - Module Workspace, Imports Page
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
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.
Figure - Module Workspace, Exports Page
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
Figure - Module Workspace, Comments Page
| < Prev | Back to Table of Contents | Next > |