MIB Smithy

MODULE-IDENTITY Statements

Every SMIv2 and COPS-PR-SPPI compliant MIB Module must contain exactly one MODULE-IDENTITY statement; no more, no fewer. Additionally, it is required that this MODULE-IDENTITY be the very first item defined in the module after the module header and IMPORTS section. The MODULE-IDENTITY statement is where information is collected such as the module's purpose, the organization responsible for the module, and contact information for the module's authors. It also contains revision tracking information -- in the form of a timestamp for the last update and a list of REVISION statements -- that can be used to distinguish between different versions of the same module. The basic form for an SMIv2 MODULE-IDENTITY statement is:

moduleIdentityName MODULE-IDENTITY
    LAST-UPDATED "timestamp"
    ORGANIZATION "text"
    CONTACT-INFO "text"
    DESCRIPTION  "text"
   ?RevisionList?
    ::= { OIDValue }

While the form for a COPS-PR-SPPI (PIB) MODULE-IDENTITY statement is:

moduleIdentityName MODULE-IDENTITY
    SUBJECT-CATEGORIES { named-number-list|all }
    LAST-UPDATED "timestamp"
    ORGANIZATION "text"
    CONTACT-INFO "text"
    DESCRIPTION  "text"
   ?RevisionList?
    ::= { OIDValue }

...where timestamp follows a specific timestamp format (described below) and RevisionList, the only optional part of the MODULE-IDENTITY statement, consists of zero or more REVISION statements as follows:

    REVISION    "timestamp"
    DESCRIPTION "text"
    REVISION    "timestamp"
    DESCRIPTION "text"
    ...

The format for the timestamp values, in both REVISION and LAST-UPDATED fields, is that of the ExtUTCTime internal datatype defined by SNMPv2-SMI, which is described below.

Creating a MODULE-IDENTITY

If you used the New Module Wizard to create the module and specified SMIv2 or COPS-PR-SPPI, a MODULE-IDENTITY statement will have been created for you automatically. Otherwise, you can create a MODULE-IDENTITY statement manually.

To manually create a MODULE-IDENTITY in MIB Smithy, you must first have created or loaded one or more MIB Modules within the project. Use the Project Tree to select the module in which to create the record. Then, you can either: use Insert → MODULE-IDENTITY from the main menu; click on the Create MODULE-IDENTITY button in the Toolbar; or right-click on the module within the Project Tree, and use its New → MODULE-IDENTITY menu. MIB Smithy will then create the record with a unique, automatically assigned name, and open a page in the Workspace Panel where you can edit its name and other properties.

General Properties

The Module Identity Name, Last Updated and OID Value properties are all available to be edited from the General Page of the MODULE-IDENTITY Workspace, which is pictured below.

Figure - MODULE-IDENTITY Workspace, General Page

Module Identity Name

The MODULE-IDENTITY name should be chosen so-as to minimize to the possibility of other records (of any type) being given the same name, and to give some idea as to the nature of the module (as with the module name). It is most often chosen to be derived from the module name its self (e.g. with hyphens removed, and converted partly to lowercase, as in the case of SNMP-FRAMEWORK-MIB and snmpFrameworkMIB). It is also often chosen so-as to be an adequately unique yet meaningful prefix for other records defined within the same module: this promotes some level of uniqueness between modules and association within modules. For example, SNMPv2-MIB defines a MODULE-IDENTITY named snmpMIB, and most of the other (non-type) records in that module start with "snmp".

A valid MODULE-IDENTITY name begins with a lowercase letter and may contain zero or more additional letters or numbers. Hyphens are allowed in SMIv1 provided the name does not end in a hyphen and no two hyphens are adjacent. Hyphens are not allowed in SMIv2 except by way of conversion from SMIv1.

This property is unconditionally required.

Last Updated

The Last Updated property indicates the date and time that the module was most recently modified, which may or may not be the same as (but must always be equal or later than) the most recent REVISION statement. The format for the timestamp in the LAST-UPDATED field and in the REVISION fields follows the ExtUTCTime type defined internally in the SNMPv2-SMI base module (RFC 2578).

ExtUTCTime ::= OCTET STRING(SIZE(11 | 13))
    -- format is 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    - denotes GMT (the ASCII character Z)
    --
    -- For example, "9502192015Z" and "199502192015Z" represent
    -- 8:15pm GMT on 19 February 1995. Years after 1999 must use
    -- the four digit year format. Years 1900-1999 may use the
    -- two or four digit format.

MIB Smithy can work with a few different date/time formats and convert them to ExtUTCTime format automatically, but it is best to use the appropriate format directly to avoid conversion errors. As well, one should get into the practice of recognizing the timestamp so that one can distinguish between the earlier and later versions of a single module. A popup calendar is available in locations where ExtUTCTime is expected to aid in writing the timestamps. Just click the button to the right of the entry field to view the calendar and select the date and time, or select the "Now" button for the current date and time, and the value will be filled in fore you.

Figure - MODULE-IDENTITY Workspace, Popup Calendar

When modules are saved to the normal SMI (MIB) or COPS-PR-SPPI (PIB) output format, MIB Smithy will include an ASN.1 style comment with both the LAST-UPDATED and REVISION fields that provides the timestamp in a more familiar form. The date and time pictured above are represented in ExtUTCTime format as 200302180000Z.

This property is unconditionally required.

OID Value

The object identifier value assigned to the module's MODULE-IDENTITY statement registers a unique identity to the module that distinguishes it unambiguously from all other modules for all time (with exception of different versions of the same module). This value may be used in another SMIv2 module's IMPORTS statement to refer to a specific module, where two or more modules may have the same actual name, but are required to have unique MODULE-IDENTITY OID values. It is common practice, although not required, for the MODULE-IDENTITY's OID value to also serve the purpose of defining a "relative root" under which all other OIDs within the module are assigned.

This property is unconditionally required.

See Also

Object Identifier Values

Organization Property

The MODULE-IDENTITY's Organization property is used to specify the authoritative organization responsible for the MIB module in which the MODULE-IDENTITY is defined. Typically this contains at least the name of the organization, but it can contain other information (such as the company's address) as well.

MIB Smithy will apply the same formatting rules to this property as it does for other similar quoted-text fields such as descriptions.

This property is unconditionally required.

See Also

Formatting Text Fields

Figure - MODULE-IDENTITY Workspace, Organization Page

Contact Information Property

The MODULE-IDENTITY's Contact Information property is used to list information and methods for contacting those parties responsible for the MIB module in which the MODULE-IDENTITY is defined. Typically this includes the name, postal address, electronic mail address and telephone number of each of the author(s), editor(s) and/or similarly authoritative figures. These are the persons to whom technical or administrative inquiries regarding the modules should be addressed in lieu of more general audience mailing lists such as that of a particular IETF Working Group responsible for developing and maintaining the module.

MIB Smithy will apply the same formatting rules to this property as it does for other similar quoted-text fields such as descriptions.

This property is unconditionally required.

See Also

Formatting Text Fields

Figure - MODULE-IDENTITY Workspace, Contact Page

Description Property

The MODULE-IDENTITY's Description property is used to provide the reader or implementor a high-level overview of the technical contents and purpose of the module. Often times (such as with RFCs) much of the technical details of a module are contained within text documentation external to the module that are extracted prior to the module's use in an application. A module author can use this property to present an abstract overview that will usually be preserved when the module is extracted from any such external documentation, with more specific details provided in the description fields for other records defined in the module.

MIB Smithy will apply the same formatting rules to this property as it does for other similar quoted-text fields such as descriptions.

This property is unconditionally required.

See Also

Formatting Text Fields

Figure - MODULE-IDENTITY Workspace, Description Page

Subject Categories Property

The MODULE-IDENTITY's Subject Categories property is specific to COPS-PR-SPPI (PIB) modules, in which it is required to be present. It specifies a list of named-number enumerations identifying the categories of provisioning data that the PIB module applies to, with each value mapping to one of the COPS-PR Client Types. In the COPS-PR-SPPI language, the keyword all can be used instead of a list of enumerations if the PIB module is applicable to all categories. In MIB Smithy, this is the default situation if no enumerations are defined (that is, the all keyword will automatically be inserted, if required, when the module is exported to COPS-PR-SPPI format).

Figure - MODULE-IDENTITY Workspace, Categories Page

To add a category, enter its name, value and optional comments (such as a short description if the label does not suffice) into the spaces provided and press the "Add" button. MIB Smithy will automatically sort the categories in increasing order. Category labels must begin with a lowercase letter, and may contain zero or more additional letters and numbers. Hyphens are not permitted.

To delete a category, select it from the list or enter its name or value and press the "Delete" button.

Revisions Property

The MODULE-IDENTITY's Revisions property allows for some degree of change history between different versions of the same module. Along with the LAST-UPDATED property, it gives users and implementors the ability to determine which of two or more versions of the same module is the most recent, as well as to determine what's different about the two versions through descriptive text detailing the nature of the changes.

It is important that each published or official release of the module be accompanied by an additional entry to the list of revisions, detailing those changes (in aggregate) since the last published version. It is not usually necessary (or recommended) to add multiple entries for changes between publications; rather, a single entry stamped with the date of the new publication with a full list of changes will suffice.

This property is optional, but useful for preserving (at a minimum) information on the first official release of the module.

Figure - MODULE-IDENTITY Workspace, Revisions Page

To add a revision, enter the timestamp and a description of the changes the spaces provided and click on the "Add" button. The format for the timestamp should be as described above for the Last Updated property (that is, ExtUTCTime format, though MIB Smithy can often interpret other formats as well).

Revisions are required to be listed in order of most recent to oldest revision; however, MIB Smithy will automatically sort revisions for you when you add or modify the revision list, and will subsequently generate output in the correct order when the module is saved. It is usually a good idea to also set the Last Updated timestamp to the same value as your most recent revision entry -- certainly when a new version of the module is to be published. Although most compilers and applications ignore these fields, MIB Smithy will generate a warning during validation if the most recent revision has a timestamp that is later than the Last Updated field.

To modify or delete a revision, you can either select it with the mouse or enter its timestamp in the space provided. If the entered timestamp is the same as an existing revision, the existing revision will be highlighted and you can either enter a new description for the revision and click the "Modify" button to change its description, or click the "Delete" button to delete the revision.

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. When MIB Smithy generates the module, either when saving or previewing, the comments for a particular record will be generated immediately above the record they are associated with.

See Also

Formatting Comments

Figure - MODULE-IDENTITY Workspace, Comments Page