v2mib2schema(1)

NAME
v2mib2schema - Translates SNMPv2 MIB files to SunNet Manager schema files.

SYNOPSIS
v2mib2schema mib_filename [schema_filename]

DESCRIPTION

v2mib2schema translates MIB files for SNMP agents to the format required by SunNet Manager's agent schema files.

MIB files must conform strictly to the RFC 1155 SMI ("Structure and Identification of Management Information for TCP/IP-based Internets"). MIB files must also conform to the subset of ASN.1 syntax specified in RFC 1155. MIB files may also include "Concise MIB Definitions" as specified in RFC 1212 and the TRAP-TYPE macro, as defined in "A Convention for Defining Traps for use with the SNMP" (RFC 1215).

v2mib2schema also generates two other files: a *.oid file and a *.traps file. The *.oid file is an object identifier file that contains a table of object identifiers and names. This file is used by the build_oid(1) program. The *.traps file contains traps definitions; this file may or may not be generated, depending on whether traps were specified in the MIB.

It is important to note that v2mib2schema is not a compiler for MIB specifications. In fact, v2mib2schema expects the MIB specification to conform strictly to the SMI defined in RFC 1155 to work correctly. However, v2mib2schema does perform some primitive error detections. If any syntax error is reported, v2mib2schema aborts immediately. If warnings are detected, v2mib2schema generates warning messages but generates the schema file anyway.

Please note the following:

1.  SNM schemas do not support nested groups and tables; therefore, v2mib2schema does not translate them. If your MIB uses nested groups or tables, you need to rewrite the groups and tables as un-nested groups or tables.

2.  SNM schemas do not support ranges defined for data types. Therefore, v2mib2schema ignores ranges defined for data types.

3.  v2mib2schema recognizes only the following set of data types as defined in RFC 1155: INTEGER, OCTET STRING, SEQUENCE and SEQUENCE OF.

4.  v2mib2schema recognizes only the following set of defined types: NetworkAddress, IpAddress, Counter, Counter32, Gauge, Gauge32, Timeticks and Opaque, as defined in RFC 1155; and PhysAddress and DisplayString, as defined in RFC 1213 (MIB-II). All defined types must eventually resolve to one of the data types listed in 3.

5.  v2mib2schema does not handle IMPORTed types very well. If a type is imported from any file other than the SMI, MIB I or MIB II, it will not be recognized. You will have to define the type in the MIB. Textual Conventions must be defined in the mib, they cannot be imported. Also, mibs which themselves contain Textual Conventions cannot be imported. The object identifier mib-2 cannot be imported, it must be defined in the mib as { mgmt 1 }.

6.  As defined in RFC 1155, you may not specify 0 as an object identifier or as an enumerated value. However, v2mib2schema would still generate the schema file, but warnings would be generated.

7.  The key value in the characteristics field for tables cannot be determined in all cases from the INDEX statement in the MIB. In instances when the MIB contains no INDEX clauses or when v2mib2schema cannot determine the key value, a warning is generated.

8.  Although v2mib2schema parses DEFVAL clauses, it currently ignores them.

9.  v2mib2schema generates only the objects found in the enterprise-specific MIB file into the schema file. If you want to include objects in the standard MIB-I schema file into the enterprise specific schema file, you would have to merge them yourself using your favorite editor.

OPTIONS
If only one file name is specified, v2mib2schema translates the MIB specifications in mib_filename to SunNet Manager schema format in mib_filename.schema. v2mib2schema also generates mib_filename.oid and, optionally, mib_filename.traps. If two file names are specified, v2mib2schema translates the MIB specifications in mib_filename to SunNet Manager schema format in schema_filename.

NOTES
This section describes some common errors that occur when writing MIBs. Reading this section may help to resolve any problems encountered when running v2mib2schema.

Sample MIB Module

Every MIB must have a module name, a BEGIN, an optional IMPORTS statement, the actual MIB body of definitions, and an END. The following is a skeletal structure of a MIB module:

    FOO-MIB DEFINITIONS ::= BEGIN
    -- FOO is the name you would give to the MIB module
    IMPORTS
        -- Objects which you import, usually from
        -- RFC1155-SMI, for example:
        experimental, OBJECT-TYPE FROM RFC1155-SMI;

    foo OBJECT IDENTIFIER ::= { enterprise 888 }
    -- The above statement defines foo as an
    -- object identifier with an enterprise number
    -- of 888.
    -- BODY OF DEFINITIONS
    END

Note that ASN.1 syntax is case-sensitive, so it is very important to get the case right. For example, object variables and identifiers must start with a lowercase letter, while object types must start with an uppercase letter. Names cannot include underscore (_) characters. Failure to follow these conventions will result in v2mib2schema generating a syntax error and aborting. Comments are preceded by a pair of hyphens.

Common errors when writing MIBs

1.  MIBs must be written in the SMI syntax, which is a subset of ASN.1 syntax. v2mib2schema does not accept MIBs written in ASN.1 syntax outside of the SMI subset.

2.  ASN.1 syntax is case-sensitive. Be very careful when typing in names and types. Remember that types must begin with an uppercase letter while names must begin with a lowercase letter. Names cannot include underscores (_).

3.  Typographical errors make up the largest number of errors detected by v2mib2schema. Examples of common typos include (those on the left are typos):

    "enterprise" instead of "enterprises"
    "Timeticks" or "timeticks" instead of "TimeTicks"
    "IPADDRESS" instead of "IpAddress"
    "non-accessible" instead of "not-accessible"

4.  Tables must be made up of entries; they cannot have primitive types as entries. For example, if you defined:

    foo OBJECT-TYPE
    SYNTAX SEQUENCE OF Foo-Entry
    ACCESS read-only
    STATUS mandatory
    ::= { bar 1 }

    you must ensure that Foo-Entry is defined as a SEQUENCE constructor like:

    Foo-Entry ::= SEQUENCE {
    entry1
    INTEGER,
    entry2,
    INTEGER
    }

You may not define any other type for Foo-Entry.

Warning/Error Messages

This section describes the warning or error messages v2mib2schema generates and the actions you should take to correct your MIB. Warning messages indicate an inconsistency in your MIB, but nothing serious enough to prevent the generation of a schema file. Warning messages are preceded by the word "Warning" and the line number in your MIB that caused the message to be generated. Error messages are usually fatal, and cause v2mib2schema to abort. Error messages are accompanied by messages displaying the last token that was read from the MIB and the line number of that token in the MIB.

Warning Messages

"does not recognize IMPORTED symbol [symbol-name]"
    v2mib2schema only recognizes keywords and objects from the SMI, MIB-I, MIB-II, the Concise MIB revisions and the TRAP-TYPE macro. This warning message is generated if symbol-name is not an object from any of the aforementioned documents. symbol-name will have to be redefined in the MIB.

"[symbol-name] previously defined"
    If symbol-name is defined more than twice, this message is generated. When the symbol-name happens to be a group name, it is renamed by inserting its parent node name before its own name. This is necessary since the SNM schema format cannot accept duplicate group names.

"Object Identifier cannot be 0"
    As defined in the SMI, you may not use 0 as an object identifier, since 0 is reserved for instances.

"Enumeration Element Value cannot be 0"
    As defined in the SMI, you may not use 0 as an enumerated value.

"[symbol-name] is not a valid status type"
    As defined in the SMI, you may only use the following status types: "deprecated", "mandatory", "obsolete" and "optional". However, since SNM schema ignores the status types, only a warning message is generated.

"The following INDEX entries in table not resolved: name"
    If v2mib2schema is unable to determine the key value for table attributes, it inserts the characters -K ??? into the characteristics field. Users of SunNet Manager 2.x do not need to take any action. If you intend to use the generated schema file with SNM release 1.x, then you should edit the schema and manually change the occurrences of -K ??? with the appropriate key value.

Error Messages

"Fatal Error: [symbol-name] not defined"
    This message is generated if symbol-name is part of an object's component ID and if it was not previously defined. Typos are the main reason this message is generated.

"Fatal Error: [symbol-name] type not resolved"
    This message is generated when symbol-name is used as a type by an object variable, but is not defined anywhere in the MIB. Since the object's type cannot be resolved, the translation has to be aborted.

"Fatal error: [name] unknown enterprise in trap definition"
    This message is generated when an unknown enterprise is encountered in trap definitions. name is the unknown enterprise name.

BUGS
As mentioned above, v2mib2schema is not a compiler for MIB specifications. Hence, the behavior of v2mib2schema is not guaranteed if the MIB specification is syntactically incorrect. Agents are not required to accept messages that exceed 484 octets. For groups with very long var-bind entries, you may have to split the group into groups with smaller var-bind entries.

SEE ALSO
build_oid(1), snm_schema(5), mib2schema(1), na.snmpv2(8), na.snmp-trap(8)