SMIC User's Guide July 23, 1992 -------------------------------------------------------------------- *** * * ******* **** * * ** ** * * * * * * * * * * * * * * * * * *** * * * * * * * * ** * * * * * * * * * * * * * * * * * * * * *** * * ******* **** -------------------------------------------------------------------- User's guide for the SNMP MIB Compiler program, SMIC July 23, 1992 David T. Perkins SynOptics Communications, Inc. Phone: (408) 764-1516 EMAIL: dperkins@synoptics.com -------------------------------------------------------------------- Copyright 1992 SynOptics Communications, Inc. All Rights Reserved. SynOptics grants a non-exclusive license to use, copy, modify, and distribute this software for any purpose and without fee, provided that this copyright notice and license appear on all copies and supporting documentation. SynOptics makes no representations about the suitability of this software for any particular purpose. The software is supplied "AS IS", and SynOptics makes no warranty, either express or implied, as to the use, operation, condition, or performance of the software. SynOptics retains all title and ownership in the software. SMIC User's Guide July 23, 1992 Table of Contents ----------------- 1. Introduction....................................1 2. Overview........................................2 3. Use of SMIC.....................................3 4. Input/Output Diagram............................5 5. MIB Stripper....................................6 6. Command Line Arguments to SMIC..................6 7. SMIC Input......................................9 8. Output from SMIC...............................13 9. MIBs with SMIC.................................26 10. Compiler Extensions and Limitations...........27 11. Acknowledgments...............................30 [Page ii] SMIC User's Guide July 23, 1992 1. Introduction --------------- This document describes a compiler for SNMP MIBs called SMIC. SMIC is available on several hardware and operating system platforms including MS-DOS and UNIX. SMIC processes SNMP MIBs written in the concise format (i.e., RFC1212 & RFC1215). SMIC is designed for use by MIB developers, agent implementors, management station implementors, management station users, managed device vendors, and users of managed devices. SMIC can be used alone to check the syntax of a SNMP MIB or as the front-end to another program called a back-end that can be used to generate MIB representations in other formats. These formats include those used in management station MIB schema files, the data structures used for the development of SNMP agents, and the data structures used to develop network management applications. SMIC has the capability to check MIBs at varying levels of strictness. The checking level is controlled with both command line switches and compiler directives. Output from SMIC is specified with command line switches and includes the following: internal data structures used for debugging or analysis by sophisticated MIB developers, an intermediate file to be used by back-end programs, "MOSY" and "Extended MOSY" output (MOSY is a popular SNMP MIB compiler), a list of object name to object identifier assignments, a list of object identifier to name assignments, and a list of defined traps. The generation of MIB information in an output format not directly provided by SMIC is accomplished by writing a custom back-end program or by writing a filter program for one of SMIC's outputs, such as the MOSY output. Other documents specify use of the back-end programs and information on how to write a custom back-end. [Page 1] SMIC User's Guide July 23, 1992 2. Overview ----------- SMIC supports the following features: * multiple input files * concise MIB format (RFC1212) * concise trap format (RFC1215) * multiple MIB modules * items in IMPORTs * textual conventions * alias assignments for modules and object names * selective checking of MIB constructs * extensive MIB syntax checking and continuation of syntax checking after syntax errors * extensive checking of MIB consistency * runs on many platforms including MS-DOS and UNIX * multiple output options * uses environment variable to locate "included" files SMIC is NOT a general purpose ASN.1 parser. Thus, it lacks the capability to compile arbitrary ASN.1 MACROs or any ASN.1 construct not needed for parsing SNMP MIBs. The SMIC package includes: * A MIB compiler, SMIC, for several different platforms * A MIB stripper, MSTRIP, for several different platforms * Source files and makefiles for SMIC and MSTRIP * This documentation * Stripped and "corrected" MIBs from RFCs [Page 2] SMIC User's Guide July 23, 1992 3. Use of SMIC -------------- Using SMIC is a five step process shown below: 1) select and prepare the MIBs to be compiled; 2) set the environment variable SMICINCL to name the directories containing MIBs; 3) create a "MIB include file"; 4) run SMIC and correct errors in the MIBs, and 5) generate output(s). 3.1. Select and Prepare MIBs ---------------------------- To use SMIC, first obtain the MIBs (i.e., the ASN.1 modules) to be compiled. A MIB may be contained in a document such as an RFC. If so, the text before and after the MIB module, and the page breaks within the MIB module must be stripped from the document. The result, one or more MIB modules, can now be used by SMIC. The stripping process can be done manually in a text editor, and/or with the help of a MIB stripper program. A stripper program and all of the standard MIBs are provided with the SMIC package. Typically, all the standard MIBs are placed in a directory and made read-only, while proprietary MIBs are placed in another directory and made read-only, and MIBs under development or testing are placed in yet another directory. 3.2. Set SMICINCL Environment Variable -------------------------------------- For SMIC to locate the MIB files, the environment variable named SMICINCL must be set to the names of the directories to be searched (after the current directory) for MIB files. The value for SMICINCL should be a list of directories separated by either semicolons in DOS, or colons or spaces in UNIX. For example, the following shows how to set up the environment variable to search two directories for both UNIX and DOS: in UNIX setenv SMICINCL "/usr/mibs/rfc /usr/mibs/draft" or setenv SMICINCL /usr/mibs/rfc:/usr/mibs/draft in DOS SET SMICINCL=C:\MIBS\RFC;C:\MIBS\DRAFT [Page 3] SMIC User's Guide July 23, 1992 3.3. Create a "MIB Include File" -------------------------------- The next step is to construct a "MIB include file" using a text editor. This file uses "include" directives to name all the MIBs to be compiled. The includes must be ordered so that all IMPORTed items must be defined in a previously included MIB. For example, MIB-II from RFC1213 IMPORTs items from RFC1155 and RFC1212. These MIBs must be included before RFC1213. Typically, the modules defining the SMI items, the OBJECT-TYPE macro, the TRAP-TYPE macro, MIB-II, and the generic traps are always included. Other standard MIBs and/or proprietary MIBs should be specified them. 3.4. Run SMIC ------------- SMIC has a multitude of options that can be chosen when it is executed. Running SMIC without any arguments will cause a synopsis of the program's usage and a list of the available options to be displayed. The options can be entered with either the "/" or "-" symbol, while the letters signifying the option can be specified in either upper or lower case. Typically the command to execute SMIC will be very simple, but it can contain many arguments depending on the level of checking desired. In most cases the following command is sufficient to check MIB syntax: smic mibIncludeFilename 3.5. Output ----------- When compiling a new MIB, several passes may be needed to correct all the errors in the MIB found by SMIC. When all errors have been eliminated, it is appropriate to select output from SMIC. However, SMIC does allow output to be generated even when error are present. Other than errors and warnings, output from SMIC is specified via command line switches. The details on these and the format of error and warning messages are shown later. [Page 4] SMIC User's Guide July 23, 1992 4. Input/Output Diagram ----------------------- Shown below is a "MIB include file" to compile the core MIBs and one new MIB. It also shows the possible outputs from SMIC. MIB Include file -------------- --------------------------------------------- /->| rfc1155.smi| | -- Example MIB Include file | / | file | |#include "rfc1155.smi" -- SMI items |-------/ -------------- |#include "rfc1212.smi" -- OBJECT-TYPE macro|--------\ |#include "rfc1215.smi" -- TRAP-TYPE macro |------\ \ -------------- |#include "rfc1213.mib" -- MIB-II |----\ \ ->| rfc1212.smi| |#include "rfc1215.trp" -- generic traps |--\ \ \ | file | | | \ \ | -------------- |#include "new.mib" -- a new MIB |\ \ | | ---------------------------------------------| | | \ -------------- | | | | \->| rfc1215.smi| | | | | | file | ----V---- | | | -------------- / \ | | | ---------\ | smic | | | \ -------------- | \ | program | | | \--->| rfc1213.mib| ---------V------- \---\ \ / | | | file | | Errors and/or | | \ --------- | | -------------- | Warnings | | \ / | \ ----------------- | \ / | \ -------------- ----------V-- \V--\ | \---->| rfc1215.trp| | Debugging | | \ \ | file | | output | | \ \ -------------- ------------- | \---\ \ -------------V-- | \ \ -------------- | Intermediate | | \ \------>| new.mib | | Form file | | \---\ | file | ---------------- | | \ -------------- ----------------V---- | \ | MOSY and Extended | | \---- | MOSY output | | | --------------------- | | ------------V-- ---V----------- | OID to name | | name to OID | | assignments | | assignments | | and traps | --------------- --------------- Figure 1 - SMIC Inputs and Outputs [Page 5] SMIC User's Guide July 23, 1992 5. MIB Stripper --------------- A simple program is provided along with SMIC to strip an RFC to reveal a MIB module. This program, called MSTRIP, uses form feed (e.g., page break) characters to determine the footer and header lines in a document. If form feeds are not used, MSTRIP will not be able to remove header and footer lines. These will have to be removed with a text editor. The program is very simple, and does not do sophisticated blank line elimination. Thus, the resulting MIB module, while being compilable, may have extra blank lines in the quoted strings which are used in DESCRIPTION and REFERENCE clauses. These must be fixed with a text editor, if desired. Running MSTRIP is simple. The one and only argument is the name of the document to be stripped. The output from MSTRIP is on standard out. This must be redirected to a file. The following shows how to run MSTRIP: mstrip rfcDocument >mibModule 6. Command Line Arguments to SMIC --------------------------------- The command line arguments to SMIC are the options, which are not required, followed by the name of the "MIB include file", which is mandatory. The syntax is shown below: smic [] 6.1. Command Line Options ------------------------- There are many options for SMIC since it is such a versatile program. Entering no arguments for SMIC will cause a synopsis of the program's usage and a list of the available options to be displayed. The options can be entered with either the "/" or "-" symbol, while the letters signifying the options can be specified in either upper or lower case. The "1" and "2" options cause the copyright and version information to be output. The "N", "S", "P", "O", "T", "K", "M", "A", "Q", "V", "D", and "I" options are used to print out information about the type of objects and files that SMIC has processed. [Page 6] SMIC User's Guide July 23, 1992 The "U" option prints out information regarding the amount of dynamic memory used in the compilation process. The "C", "R", "3", "4", "5", "6", "7", "E", "J", "W", "B", and "G" option are used to control the amount of MIB semantic checking. Some options add more rigid checking, while others allow looser checking. The "X" option suppresses the use of strings from the description and reference clauses in the MIB text files. These elements take up a significant amount of memory and if they are suppressed, the memory is free to be used for other purposes by SMIC. This option is useful if SMIC runs out of memory when executed without the "X" option. This may occur when running the MS-DOS version of SMIC. The "F" option allows the user to send the output from SMIC to a specified file. If the F option is not used the output goes to standard out. The "8" option outputs the MIB in MOSY format, and the "9" outputs the MIB in Extended MOSY format. The "Z" option outputs the MIB text files in the intermediate form format, which is used by the SMIC companion back-end programs. 6.2 Command Line Example ------------------------ Typically the command to execute SMIC is simple, but it can contain many arguments depending on the level of checking desired. In most cases the following command is sufficient to check MIB syntax: smic The following command line requests the "most" strict checking available: smic /c /r /w /b /7 OR smic -c -r -w -b -7 The following command line requests the "least" strict checking available: smic -3 -4 -5 -6 -e -j -g [Page 7] SMIC User's Guide July 23, 1992 6.3 Command Line Options Detailed --------------------------------- Status/Statistics /U - dump resource usage statistics. /I - print names of include files while compiling. /X - suppress strings in description and reference clauses. Checking Levels /C - verify that all INTEGER items have a range and all OCTET STRING items have a size associated with them. /R - verify that all INDEX items are read-only. /W - verify the syntax of items in a SEQUENCE definition for the following and generate an error if they are present: range on OCTET STRINGs, size on INTEGERs, syntax of INTEGER for a object with syntax of textual convention for an enumerated integer. /B - verify that INTEGER INDEX items have a non-negative range and OCTET STRING INDEX items have a size specified. /3 - allow INDEX clause on leaf objects. /4 - allow non-standard access of "write-only" or "not-accessible". /5 - allow "optional" status. /6 - do not verify that table, row, and sequence names are related. /7 - verify that all INDEX items are in SEQUENCE for row. /E - allow SEQUENCE item syntax to match Textual conventions. /J - allow DEFVAL on a Counter or Gauge. /G - turn off warnings for unused IMPORTs and textual conventions. Output Options /0 - set message (and error/warning) file to output file. (normally standard error is used) /1 - print copyright. /2 - print version. /N - Output OID tree (this is like the "numbers" file produced by the Epilogue MIB compiler) and traps. /L - Output objects sorted by name. /8 - Output in MOSY format. /9 - Output in Extended MOSY format. /Z - Output in intermediate format. /F - file to write output to. [Page 8] SMIC User's Guide July 23, 1992 Debugging (and Sophisticated MIB Developer) Options /S - dump string table. /P - dump trap names. /O - dump OID items (this includes the format for instances of each object). /T - dump IMPORT names. /K - dump SMI names. /M - dump module names. /A - dump alias names. /Q - dump SEQUENCES. /V - dump textual conventions. /D - dump all. 7. SMIC Input ------------- The input to SMIC is a "MIB include file" that contains compiler directives. The most important directive is the "include" directive which is used to specify the names of the MIB files. There are also directives to define aliases, or to change command line option settings. Directives can be contained within the MIB include file or any MIB file. If so, they can be placed only between MIB modules. All directives are listed below: #help -- print a list of directives. #include "" -- process include file. #aliasModule -- alias a module's name. #aliasSymbol -- alias an object's name. #pushOpt -- push options (i.e., save current checking options). #popOpt -- pop options (i.e., restore saved checking options). #addOpt "" -- add one or more checking option. #removeOpt "" -- remove one or more checking option. #printOpt -- print current setting of checking options. 7.1. Include Directive ---------------------- The include directive is used typically only within the file specified on the command line to SMIC. This file is called the "MIB include file" since it is typically used to include all the files containing MIB definitions. Each included file may contain zero, one, or several MIB module definitions. The filename must be enclosed in quotes. If the file name is not absolute (i.e., start with a drive letter [Page 9] SMIC User's Guide July 23, 1992 or "\" in DOS, or start with a "/" in UNIX), SMIC tries to locate the file in the current directory. If the file is not found, then SMIC tries to locate the file in the directories specified by the value for the SMICINCL environment variable. Shown below are examples of the "include" directive. in both UNIX and DOS #include "filename" in UNIX #include "../../filename" or #include "/usr/mibs/filename" in DOS #include "C:\MIBS\XXX\filename" or #include "\MIBS\STD\filename" or #include "..\..\filename" Any combination of standard MIBs and proprietary MIBs can be included. However, any item that is IMPORTed into a MIB module must first be defined in a previously included MIB module. (Note: The alias feature can be used to change the names of modules or objects. This is provided so that MIBs that reference an older version of a MIB do not have to be modified to make the module or object in the IMPORT match the name used in the definition. Many MIBs incorrectly IMPORT from module RFC1158-MIB (or RFC1066-MIB) instead of RFC1213-MIB.) The include mechanism (and if necessary, the alias mechanism) is used so that the MIB files need not be modified in any way (after they have been extracted from the RFC documents.) 7.2. Alias Directives --------------------- The alias directives allows an alternative name to be defined for items in IMPORT statements. This includes both the object and textual convention names as well as the "FROM" module name. These names can change as the defining document is evolved as it moves through the standards process. For example, consider a MIB written with the following IMPORT: "OwnerString FROM RFC1271-MIB" [Page 10] SMIC User's Guide July 23, 1992 If RFC1271 is republished with a new RFC number, say RFC9999, the module name would be changed to RFC9999-MIB. To process this new version without changing any other MIB files that import items defined in it, the "MIB include file" must be modified by changing the include directive to use the new version of the file instead of the old, and a "moduleAlias" directive should be added to map the old module name to the new name. The following shows the directive to be added: #moduleAlias RFC9999-MIB RFC1271-MIB ^ ^ \-Real name \-Old name (i.e., alias) If the name of the textual convention was also changed, to say "OwnerStringXXX", the following directive would also be needed: #aliasSymbol RFC9999-MIB OwnerStringXXX OwnerString ^ ^ ^ \-Real Name-/ | Old name (i.e., alias) As shown, these alias directives can eliminate changes to MIBs due to changes of the names of IMPORTed items. Without the alias facility, the references would be left dangling. A module or symbol may have multiple aliases. 7.3. Option (or checking) Directives ------------------------------------ The "option" directives are used to manage the settings of the options that are used for MIB checking. When processing MIBs, the amount of checking is determined by the settings of the checking options. The initial values for options are set on the command line to SMIC. Before processing each MIB module, the options may be changed. Before changing the options, the current setting may be saved. After a module is compiled with the changed option settings, the saved options may be restored. For example, suppose a new MIB module was to be developed and it was desired to use the most strict MIB checking rules for it. However, this MIB depends on IETF standard MIBs written with somewhat relaxed MIB checking rules. A "MIB include file" would be set up to include the standard MIBs and the new MIB under development. If the most strict checking was specified on the command line to SMIC, many warnings and errors would be generated by the standard MIBs. (NOTE: The conventions for [Page 11] SMIC User's Guide July 23, 1992 writing MIBs have changed over the years. The "rules" have "changed" as experienced has been gained by writing MIBs. It is expected that the older MIBs will be updated to use the modern conventions which will make them easier to understand. Until then, SMIC will have options for specifying which rules to use.) To get around the generation of these errors, the directives managing the checking options should be used before and after the include directives for the standard files. The following is a fragment from a "MIB include file" showing how to eliminate errors from standard MIBs: -- Save current checking option settings and -- set to least amount of checking. #pushOpt #removeOpt "c r w b 7" #addOpt "3 4 5 6 e j g" #include "rfc1155.smi" -- SMI items #include "rfc1212.smi" -- OBJECT-TYPE macro #include "rfc1215.smi" -- TRAP-TYPE macro #include "rfc1213.mib" -- MIB-II #include "rfc1215.trp" -- generic traps -- Restore checking option settings #popOpt -- Include MIB(s) being developed #include "myMib.mib" The option directives can be used to change the settings for individual MIB modules, or as shown above, the settings for multiple MIB modules. [Page 12] SMIC User's Guide July 23, 1992 8. Output from SMIC ------------------- Output from SMIC is caused by errors or warnings during compiling and by command line switches. The following sections detail each output. 8.1. Format of Error/Warning Messages ------------------------------------- Error and warning messages generated by SMIC are tagged with the location of the next symbol to be parsed. Thus, the exact location of a problem is approximately at or before the location printed. When SMIC completes parsing a MODULE, it will check all the items defined within the module for consistency. The problems found at this point are tagged with the location of the end of the module. All messages generated during consistency checking include the name of the problem item so that a text editor can be used to locate and correct the item. All messages printed by SMIC have the following format: {"W"|"E"} [ "F(" ")" ] "(" "," ")" Where: W - warning E - error file - name of file line - line number in file column - column in line message - text message indicating the problem SMIC will try to continue parsing the input file in spite of errors. Some errors may cause bogus errors to be generated. Fixing the source error will eliminate bogus errors. For example, a syntax error in the definition of a table object could cause bogus errors to be generated relating to the SEQUENCE and row associated with the table. Fixing the syntax error for the table will eliminate the errors for the row and SEQUENCE. [Page 13] SMIC User's Guide July 23, 1992 8.2. Format of the Usage Statistics Output ------------------------------------------ This output is designed for use mainly for testing of SMIC, as well as for sophisticated MIB developers. It can be used to see the usage count for each type of item that may be contained in a MIB. The following is the "U" option output from compiling MIB-II and the standard SNMP traps: Statistics: String Space: 49152 Strings: 600 510(10200) Modules: 5 5(560) Mod Refs: 8 4(56) Imported items: 20 11(88) Imports: 20 11(1232) Aliases: 0 0(0) SMI items: 8 8(896) OID items: 240 212(23744) RegPt/group: 22 Table: 8 Row: 8 Leaf: 174 Enum items: 100 89(1068) Index items: 20 14(252) Sequences: 10 8(96) Sequence members: 80 69(1794) Text conv: 5 2(224) Traps: 20 6(672) Trap vars: 20 3(24) Trap ents: 5 1(12) Dynamic memory used: 90070 On each line with three values, the first value is the number of items allocated, the second is the number actually used, and the third, (in parenthesis) is the amount of memory used. The following is a description of each line: "String space" is the memory used to store all of the symbol names and strings used by SMIC. Most memory usage for MIB objects is typically for the "DESCRIPTION" and "REFERENCE" strings. (The "X" option can be used to suppress these strings.) "Strings" is the number of items in the "string space". "Modules" is the number of modules defined. "Mod Refs" is the total number of modules specified in all IMPORT statements. [Page 14] SMIC User's Guide July 23, 1992 "Import items" and "Imports", which have the same value in valid MIBs, is the total number of items specified in all IMPORT statements. "Aliases" is the number of aliases that are defined. "SMI items" is the number of SMI data types and macros that are enabled. "OID items" is the total number of items that are defined with OID values associated with them. (NOTE: SMIC does not associate an OID with a MIB module. If one is specified, then it is ignored.) The "OID items" are broken down into four types. "RegPt/Group" is the count of OID registration points and SNMP "groups". "Table" and "Row", which have the same value in valid MIBs, is the total number of SNMP tables/rows. "Leaf" is the total count of "column" and "simple" objects. "Enum items" is the total number of values of enumerated syntax objects. "Index items" is the number of items, both SNMP objects and syntax names, used in all INDEX clauses. "Sequences" is the total number of sequences, and is the same as the number of tables and rows in valid MIBs. "Sequence members" is the total number of items in sequences. "Text conv" is the total number of textual conventions. "Traps" is the total number of traps. "Trap vars" is the total number of variables specified for traps. "Trap ents" is the number of unique values for the enterprise clause for all traps. "Dynamic memory used" is the sum of the memory allocated for SMIC's data structures. (NOTE: this is less than the "real" amount of dynamic data used by SMIC, since most runtime library implementations of "malloc" also allocate additional space to track the allocated memory.) [Page 15] SMIC User's Guide July 23, 1992 Note: An easy way to determine the number of objects in a private MIB is: 1) determine the number of objects in the MIBs that are IMPORTed by the private MIB (i.e., get the statistics from compiling only the standard MIBs) 2) determine the total number of objects in all of the MIBs (i.e., get the statistics from compiling both the standard and private MIBs) 3) subtract the counts to determine the difference which is number of objects defined in the private MIB. 8.3. Output of Version and Copyright ------------------------------------ The "1" and "2" options can be used to print the version and copyright message for SMIC. Note that SMIC is copyrighted. There are different versions of SMIC. The restrictions and rights to use SMIC are printed with the copyright message. 8.4. Output of the OID tree and Traps ------------------------------------- The "N" option is used to output the MIB in OID order and to also output the traps in "enterprise" order. Two tables are output. The first contains a line for each object in the MIB consisting of its OID value, its name, and the type or syntax of the object. The format is similar to the "numbers" output from Epilogue Technology Corporation's MIB compiler. The second table is a list of traps organized by the value of the "enterprise" clause. Below are a few fragments from MIB-II: OID tree 0 ccitt: reg point 0.0 null: reg point 1 iso: reg point 1.3 org: reg point 1.3.6 dod: reg point 1.3.6.1 internet: reg point 1.3.6.1.1 directory: reg point 1.3.6.1.2 mgmt: reg point 1.3.6.1.2.1 mib-2: reg point 1.3.6.1.2.1.1 system: reg point 1.3.6.1.2.1.1.1 sysDescr: DisplayString (SIZE(0..255)) 1.3.6.1.2.1.1.2 sysObjectID: OBJECT IDENTIFIER 1.3.6.1.2.1.1.3 sysUpTime: TimeTicks [Page 16] SMIC User's Guide July 23, 1992 ... 1.3.6.1.2.1.4.20 ipAddrTable: SEQUENCE OF IpAddrEntry 1.3.6.1.2.1.4.20.1 ipAddrEntry: SEQUENCE IpAddrEntry 1.3.6.1.2.1.4.20.1.1 ipAdEntAddr: IpAddress 1.3.6.1.2.1.4.20.1.2 ipAdEntIfIndex: INTEGER 1.3.6.1.2.1.4.20.1.3 ipAdEntNetMask: IpAddress 1.3.6.1.2.1.4.20.1.4 ipAdEntBcastAddr: INTEGER 1.3.6.1.2.1.4.20.1.5 ipAdEntReasmMaxSize: INTEGER (0..65535) ... 1.3.6.1.2.1.11.29 snmpOutTraps: Counter 1.3.6.1.2.1.11.30 snmpEnableAuthenTraps: Enum 1.3.6.1.3 experimental: reg point 1.3.6.1.4 private: reg point 1.3.6.1.4.1 enterprises: reg point **end of oid tree** Traps enterprise: snmp 1.3.6.1.2.1.11 trap: coldStart, value 0 trap: warmStart, value 1 trap: linkDown, value 2 trap: linkUp, value 3 trap: authenticationFailure, value 4 trap: egpNeighborLoss, value 5 **end of TRAPs** [Page 17] SMIC User's Guide July 23, 1992 8.5. Output of Objects Sorted by Name ------------------------------------- The "L" option is used to output the MIB objects sorted by name. All the objects in IETF standard MIBs must have unique names. However, experimental or private MIBs may have objects whose names are the same as other objects. Each line of output contains the name of the object followed by its associated OID. Objects that have duplicate names are marked with the phrase "**Dup**" on the right end of the line. The following is a fragment of a combination of MIB-II and a private MIB: at 1.3.6.1.2.1.3 atEntry 1.3.6.1.2.1.3.1.1 atIfIndex 1.3.6.1.2.1.3.1.1.1 atNetAddress 1.3.6.1.2.1.3.1.1.3 atPhysAddress 1.3.6.1.2.1.3.1.1.2 atTable 1.3.6.1.2.1.3.1 ccitt 0 directory 1.3.6.1.1 dod 1.3.6 ... ipRouteType 1.3.6.1.2.1.4.21.1.8 ipRoutingDiscards 1.3.6.1.2.1.4.23 iso 1 mgmt 1.3.6.1.2 mib-2 1.3.6.1.2.1 null 0.0 org 1.3 private 1.3.6.1.4 snmp 1.3.6.1.2.1.11 **dup** snmp 1.3.6.1.4.1.9999.1.4 **dup** snmpEnableAuthenTraps 1.3.6.1.2.1.11.30 snmpInASNParseErrs 1.3.6.1.2.1.11.6 [Page 18] SMIC User's Guide July 23, 1992 8.6. Output in MOSY and Extended MOSY format -------------------------------------------- MOSY is a popular MIB compiler written by Marshall Rose. It is part of the ISO Development Environment (ISODE) package. The output from MOSY is being used by some private MIB tools. SMIC was designed to have an output identical to MOSY to allow continued use of MOSY output tools. Unfortunately MOSY, does not output all the information that it gathers about a MIB. The extended MOSY format from SMIC has additional information so that MOSY output MIB tools can be easily extended to use the missing information not available from MOSY output. The "8" option causes output in MOSY format. Below are a few MOSY format output fragments from MIB-II: ccitt 0 null ccitt.0 iso 1 org iso.3 dod org.6 internet dod.1 directory internet.1 mgmt internet.2 ... sysDescr system.1 DisplayString read-only mandatory sysObjectID system.2 ObjectID read-only mandatory sysUpTime system.3 TimeTicks read-only mandatory ... ipAddrTable ip.20 Aggregate not-accessable mandatory ipAddrEntry ipAddrTable.1 Aggregate not-accessable mandatory ipAdEntAddr ipAddrEntry.1 IpAddress read-only mandatory ipAdEntIfIndex ipAddrEntry.2 INTEGER read-only mandatory ipAdEntNetMask ipAddrEntry.3 IpAddress read-only mandatory ipAdEntBcastAddr ipAddrEntry.4 INTEGER read-only mandatory ipAdEntReasmMaxSize ipAddrEntry.5 INTEGER read-only mandatory ... snmpOutTraps snmp.29 Counter read-only mandatory snmpEnableAuthenTraps snmp.30 INTEGER read-write mandatory As shown above, the MOSY output contains only a small part of the information from the MIB. The "9" option is used to cause the extended MOSY output. Displayed below are the fragments of the Extended MOSY format output. It is in the style of the original [Page 19] SMIC User's Guide July 23, 1992 MOSY format output, but includes information about enumerations, sequences, textual conventions, and syntax sizes and ranges. The lines that would not fit in the space below and that had to be "wrapped" are shown with a plus (i.e., "+") in the left margin below. -- Enumerations *ifType 32 ( other 1 regular1822 2 hdh1822 3 ... frame-relay 32 ) *ifAdminStatus 3 ( up 1 down 2 testing 3 ) ... -- Textual Conventions +DisplayString OctetString +PhysAddress OctetString -- Sequences $IfEntry 22 { ifIndex ifDescr ... ifSpecific } $AtEntry 3 { atIfIndex atPhysAddress atNetAddress } ... ccitt 0 regPt null ccitt.0 regPt iso 1 regPt org iso.3 regPt [Page 20] SMIC User's Guide July 23, 1992 dod org.6 regPt internet dod.1 regPt directory internet.1 regPt mgmt internet.2 regPt mib-2 mgmt.1 regPt system mib-2.1 regPt sysDescr system.1 DisplayString (SIZE (0..255)) + read-only mandatory sysObjectID system.2 ObjectID read-only mandatory sysUpTime system.3 TimeTicks read-only mandatory ... ipAddrTable ip.20 Table not-accessable mandatory ipAddrEntry ipAddrTable.1 seq IpAddrEntry 1 ( ipAdEntAddr ) + not-accessable mandatory ipAdEntAddr ipAddrEntry.1 IpAddress read-only mandatory ipAdEntIfIndex ipAddrEntry.2 INTEGER read-only mandatory ipAdEntNetMask ipAddrEntry.3 IpAddress read-only mandatory ipAdEntBcastAddr ipAddrEntry.4 INTEGER read-only mandatory ipAdEntReasmMaxSize ipAddrEntry.5 INTEGER (0..65535) + read-only mandatory ... snmpOutTraps snmp.29 Counter read-only mandatory snmpEnableAuthenTraps snmp.30 Enum read-write mandatory 8.7. Output in the Intermediate File Format ------------------------------------------- SMIC was designed so that "back-end" programs that use the intermediate file can be easily written. These programs can be used to select MIB objects of interest and perform desired analysis and/or output the data in any desired format. The format of SMIC's intermediate file was designed so that it could be easily parsed with a very simple top down parser. The syntax of the intermediate file is specified in the documentation on how to write a back-end program. [Page 21] SMIC User's Guide July 23, 1992 8.8. Debugging and Sophisticated User Output ------------------------------------------- In developing SMIC it was helpful to have some functions to dump out the data structures containing the MIB objects. The debugging options are used to select which data structures to output. This complete MIB information is also useful to sophisticated MIB developers who want to see all aspects of a MIB. The "string table" is a balanced binary tree. Dumping it prints each item in the tree with the associated level and left or right tag. The string table is also traversed "in-order" which causes all the items to be printed in sorted order. The "Module Dump" is used to print statistics, the names of all modules, and the IMPORTed items and aliases for the module. The "Import Dump" is used to print statistics, the names of all IMPORTed items, and the use count for each one. The "Alias Dump" is used to print statistics, the names and definitions of all aliases, and the use count for each one. The "SMI Dump" is used to print statistics, the names of all SMI syntax types that have been enabled, and the names of the MACROs that have been enabled (these may only be TRAP-TYPE or OBJECT-TYPE). The "Trap Dump" is used to print statistics and the names and information associated with each trap. It also prints a list of each unique value for the "enterprise" field and the traps that have that value. The "Textual Convention Dump" is used to print statistics and the names and value of each textual convention. The "Sequence Dump" is used to print statistics and the names of all sequences with the items that are contained in them. The "OID Dump" is used to print statistics and the name and associated value for each SNMP object that is defined with an OID. The associated information includes: status; the type (one of OID, Table, Row, or Object); the OID value; the syntax; the resolved syntax; the access; and for "objects", the instance construction rule. The "syntax" and "resolved syntax" can be interesting. If an object uses one of the SMI syntax types, then the syntax and resolved syntax have the same value. However, if the syntax is a textual convention, the line where the syntax is printed is the [Page 22] SMIC User's Guide July 23, 1992 chain of textual convention definitions until the base SMI syntax type is reached. For example, the object "etherStatsOwner" from RFC1271 is defined with syntax OwnerString. This textual convention is defined as a DisplayString, which is defined as a OCTET STRING. The syntax and resolved syntax for "etherStatsOwner" is shown below: syntax: [OwnerString]-> [DisplayString]-> OCTET STRING resynt: OCTET STRING The values printed for object sysDescr from RFC1213 are shown below: syntax: [DisplayString (SIZE(0..255))]-> OCTET STRING resynt: OCTET STRING (SIZE(0..255)) The derived instance construction rules are shown for each object. For "simple" objects, the instance is always a single component with value of zero. This is shown as the following: instance: 0 For items in tables, the name of the row is printed. For the row, the index items and the instance encoding rule are shown. (HINT: the instance encoding rules are given in the Concise MIB RFC, RFC-1212). Below are the instance construction rules for all tables in MIB-II: ifEntry indices(1): ifIndex instance encoding: . atEntry indices(2): atIfIndex atNetAddress instance encoding: ..<1>.... ipAddrEntry indices(1): ipAdEntAddr instance encoding: .... ipRouteEntry indices(1): ipRouteDest instance encoding: .... [Page 23] SMIC User's Guide July 23, 1992 ipNetToMediaEntry indices(2): ipNetToMediaIfIndex ipNetToMediaNetAddress instance encoding: ..... tcpConnEntry indices(4): tcpConnLocalAddress tcpConnLocalPort tcpConnRemAddress tcpConnRemPort instance encoding: ..... ..... udpEntry indices(2): udpLocalAddress udpLocalPort instance encoding: ..... egpNeighEntry indices(1): egpNeighAddr instance encoding: .... The objects and tables in MIB-II are well formed and follow the standard conventions. SMIC does parse MIBs that use the INDEX clause in tables where the items in the INDEX clause are syntax names (i.e., INTEGER, DisplayString, IpAddress, etc.) and not just column names. It also parses MIBs where an item is not defined in a table, but has an index clause. (This type of construct may seem unconventional, but SMIC can be made to accept it by using the "3" option.) SMIC supports a variant of instance construction rules for varying length OCTET STRINGs and OBJECT IDENTIFIERs. This is implemented by extending SMIC to recognize a NOLENGTH or a IMPLIED qualifier to be used on the last item in an INDEX clause. The normal instance construction rules for varying length OCTET STRINGs and OIDs used as index items is to proceed their value with a single component containing the number of components to follow. The NOLENGTH qualifier is used to indicate that the length component is not present. Below is an object and row with their instance encoding rules: x1 OBJECT-TYPE INDEX { INTEGER, OCTET STRING, OCTET STRING (SIZE(0..10)), INTEGER (0..45), OCTET STRING (SIZE(4)) } [Page 24] SMIC User's Guide July 23, 1992 x1 indices(5): INTEGER OCTET STRING OCTET STRING (SIZE(0..10)) INTEGER (0..45) OCTET STRING (SIZE(4)) instance: from index clause instance encoding: ... ... .... x3Entry OBJECT-TYPE INDEX { INTEGER, INTEGER, OCTET STRING, OCTET STRING (SIZE(0..10)), INTEGER (0..45), OBJECT IDENTIFIER, NetworkAddress, IpAddress, x3Index, NOLENGTH OCTET STRING } x3Entry indices(11): INTEGER INTEGER OCTET STRING OCTET STRING (SIZE(0..10)) INTEGER (0..45) OCTET STRING (SIZE(4)) OBJECT IDENTIFIER NetworkAddress IpAddress x3Index NOLENGTH OCTET STRING instance encoding: .... ... .... .. .<1>.... ..... . It is believed that all "reasonable" encodings for SNMP objects can be described using an INDEX clause with the addition of the NOLENGTH (or IMPLIED) extension. It is expected that all private MIBs which have instance rules specified in the text for the DESCRIPTION clause or in ASN.1 comments will be updated to have the instance information specified in INDEX clauses. [Page 25] SMIC User's Guide July 23, 1992 9. MIBs with SMIC ----------------- Files have been prepared for all the MIBs contained in RFCs. Many of these MIBs had errors in them. Each MIB contains header lines indicating if corrections were done, and if so, what was changed. Below is a list of all the MIB files currently available with SMIC: rfc1065.smi - SMI (obsoleted by rfc1155) rfc1066.mib - MIB I (obsoleted by rfc1156) rfc1155.smi - (modified) SMI (obsoletes rfc1065) rfc1156.mib - MIB I (obsoletes rfc1066, obsoleted by MIB-II) rfc1158.mib - MIB II (obsoleted by rfc1213) rfc1212.smi - (modified) Concise MIB rfc1213.mib - MIB II (obsoletes rfc1158) rfc1213s.mib - shortened version of MIB-II rfc1215.smi - (modified) Concise Traps rfc1215.trp - SNMP generic traps rfc1227.mib - SMUX rfc1229.mib - IF extensions rfc1230.mib - Token Bus rfc1231.mib - Token Ring rfc1232.mib - DS1 rfc1233.mib - DS3 rfc1238.mib - CLNS rfc1243.mib - AppleTalk rfc1253.mib - OSPF MIB rfc1269.mib - BGP MIB rfc1271.mib - RMON rfc1284.mib - Ethernet rfc1285.mib - FDDI rfc1286.mib - Bridge rfc1289.mib - DECnet rfc1304.mib - SMDS (SIP) rfc1315.mib - Frame relay rfc1316.mib - Character rfc1317.mib - RS-232 rfc1318.mib - Parallel printer rfc1353.mib - Party rfc1354.mib - IP forwarding table The following "MIB Include Files" are available with SMIC: mibo - the original versions of MIB-I and the SMI mibi - the current version of MIB-I, but using OBJECT-TYPE from rfc1212 mibii - the current version of MIB-II rfc - all mibs from RFCs specified above (except obsolete versions) [Page 26] SMIC User's Guide July 23, 1992 10. Compiler Extensions and Limitations --------------------------------------- SMIC has only one extension. This is the addition of the NOLENGTH (or IMPLIED) qualifier for the last item in an INDEX clause. Its use is explained in the section on debugging output. SMIC has very few limitations as a compiler for SNMP MIBs. It is not, however, a general purpose ASN.1 compiler. It does not parse ASN.1 MACROs. SMIC has built into it the knowledge of the OBJECT-TYPE and TRAP-TYPE MACROs and the SMI syntax types. It uses a special directive to enable these items and thus does not parse their definitions directly. SMIC would need to be changed to support additional MACROs. SMIC is limited under MS-DOS with the amount of memory that it has available for holding the MIB objects. The UNIX version of SMIC is virtually unlimited. Whenever a memory allocation fails, SMIC will print out the current memory usage statistics and terminate. The "X" option can be used to cause SMIC to discard the strings from the DESCRIPTION and REFERENCE clauses. This helps on memory use (and also results in SMIC running a little faster). The current version of SMIC can recover from most syntax errors in a MIB. It also can continue on most semantic errors in a MIB. For example, the ACCESS clause has a few well defined values. If an invalid value is specified, for example a typing mistake, SMIC handles this as a semantic error and continues. If an extra comma is used or if a comma is not placed at the appropriate place in the definition of a sequence, SMIC will report a syntax error and continue. There are few places where SMIC cannot recover from a syntax error. When this occurs, SMIC will print a message that it is terminating. SMIC does not expect a MIB module to have an OID assigned to it. If it finds one, it will be ignored without checking the values. [Page 27] SMIC User's Guide July 23, 1992 SMIC expects the value used to define OBJECT IDENTIFIERs and items defined using the OBJECT-TYPE macro to be in the simple format that, by convention, is used in defining items in the standard IETF MIBs. The valid forms are: "{" "}" - only for defining OIDs or "{" "}" The can be any item with an OID value. SMIC allows this to be a forward reference (or an IMPORTed item). All the forward references in a module must be resolved by the end of the module. The syntax for the OID value for the DEFVAL clause is fully general. Below is shown the syntax for this value: "{" { | { ["("")"] } }... "}" examples: { 0 0 } { 1 3 6 1 mgmt(2) 1 system } However, if a number is used without a name, an item with that OID value must already be defined in a previously included MIB module. The case of { 0 0 }, a common case, is not a problem since the OID "null" is defined in the supplied MIB for RFC1155. Currently, SMIC does not support dotted IP addresses or NetworkAddress values for DEFVALs. SMIC checks to make sure that the value for a DEFVAL matches the type of the object. However, at this time SMIC does not check the range of INTEGERs or the size of OCTET STRINGs to make sure they are valid. Items must be already defined before they can be IMPORTed. All MIBs that are of interest and are referenced directly or indirectly through an IMPORT must be compiled. SMIC does not use a library of previously compiled MIBs to resolve IMPORTs. All of the MIBs must be compiled together. If speed and space are concerns, a MIB that defines a textual convention or a OID branch can be stripped to contain only those items of interest. This new version can be specified in the "MIB include file". Also, the "G" option can be specified with the option directives to turn off warnings for unused textual conventions. Since an IMPORTed item must already be defined, it is impossible for a pair of MIB modules to IMPORT items from each other. [Page 28] SMIC User's Guide July 23, 1992 There are no other "compiler" limitations in the syntax of MIBs that SMIC can parse correctly. There are some SNMP MIB limitations which are taken as assumptions to SMIC, but may appear to the user as limitations of SMIC. For example, the OBJECT-TYPE macro must be IMPORTed for SMIC to recognize the syntax of the OBJECT-TYPE macro. This is also true for the TRAP-TYPE macro. Other items, such as textual conventions and OID branches, must be IMPORTed before they can be used. [Page 29] SMIC User's Guide July 23, 1992 11. Acknowledgments Many people have helped with testing SMIC to make sure that it really "does the right thing." These people include: Fred Baker and colleagues at ACC Bob Stewart and colleagues at Xyplex Mark Kepke at HP Mark Therieau at Microcom Dean Throop at Data General Ted Brunner and colleagues at Bellcore Jon Saperia at DEC Barry Reinhold and colleagues at UNH Jack Pollar and colleagues at Novell Marshall Rose at Dover Beach Consulting Chuck Davin at MIT Evan McGinnis at 3Com Jeff Case and associates at SNMP Research Greg Foster and all my other colleagues at SynOptics Special thanks to Fred Baker who provided the MIB striper, MSTRIP. Extra special thanks go to Dean Throop who provided lots of help and insight to writing YACC error productions. Lastly, all of this would not be possible without the support from SMP and the entertainment provided by IMMER. And finally, please send me bugs, suggestions, fixes, enhancements from using SMIC so that I can put them into the next version. Enjoy using this tool and let us know how it works for you. Your friend... David T. Perkins dperkins@synoptics.com (408) 764-1516 [Page 30]