diff options
Diffstat (limited to 'lib/snmp/doc/src/snmp_mib_compiler.xml')
| -rw-r--r-- | lib/snmp/doc/src/snmp_mib_compiler.xml | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/lib/snmp/doc/src/snmp_mib_compiler.xml b/lib/snmp/doc/src/snmp_mib_compiler.xml new file mode 100644 index 0000000000..63af19f479 --- /dev/null +++ b/lib/snmp/doc/src/snmp_mib_compiler.xml @@ -0,0 +1,252 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>The MIB Compiler</title> + <prepared></prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date></date> + <rev></rev> + <file>snmp_mib_compiler.xml</file> + </header> + <p>The chapter <em>The MIB Compiler</em> describes the MIB compiler + and contains the following topics: + </p> + <list type="bulleted"> + <item>Operation</item> + <item>Import</item> + <item>Consistency checking between MIBs</item> + <item>.hrl file generation</item> + <item>Emacs integration</item> + <item>Deviations from the standard + </item> + </list> + <note> + <p>When importing MIBs, ensure that the imported MIBs as well as the + importing MIB are compiled using the same version of the + SNMP-compiler.</p> + </note> + + <section> + <title>Operation</title> + <p>The MIB must be written as a text file in SMIv1 or SMIv2 using + an ASN.1 notation before + it will be compiled. This text file must have the same name as the MIB, + but with the suffix <c>.mib</c>. This is necessary for handling + the <c>IMPORT</c> statement. + </p> + <p>The association file, which contains the names of + instrumentation functions for the MIB, should have the suffix + <c>.funcs</c>. If the compiler does not find the association file, + it gives a warning message and uses default instrumentation + functions. (See <seealso marker="snmp_instr_functions#snmp_3">Default Instrumentation</seealso> for more details). + </p> + <p>The MIB compiler is started with a call to + <c><![CDATA[snmpc:compile(<mibname>).]]></c> For example: + </p> + <code type="none"> +snmpc:compile("RFC1213-MIB"). + </code> + <p>The output is a new file which is called <c><![CDATA[<mibname>.bin]]></c>. + </p> + <p>The MIB compiler understands both SMIv1 and SMIv2 MIBs. It + uses the MODULE-IDENTITY statement to determinate if the MIB is + written in SMI version 1 or 2. + </p> + </section> + + <section> + <title>Importing MIBs</title> + <p>The compiler handles the <c>IMPORT</c> statement. It is important to + import the compiled file and not the ASN.1 (source) file. A MIB must + be recompiled to make changes visible to other MIBs importing it. + </p> + <p>The compiled files of the imported MIBs must be present in the + current directory, or a directory in the current path. The path is + supplied with the <c>{i, Path}</c> option, for example: + </p> + <code type="none"> +snmpc:compile("MY-MIB", + [{i, ["friend_mibs/", "../standard_mibs/"]}]). + </code> + <p>It is also possible to import MIBs from OTP applications in an + <c>"include_lib"</c> like fashion with the <c>il</c> + option. Example: + </p> + <code type="none"> +snmpc:compile("MY-MIB", + [{il, ["snmp/priv/mibs/", "myapp/priv/mibs/"]}]). + </code> + <p>finds the latest version of the <c>snmp</c> and <c>myapp</c> + applications in the OTP system and uses the expanded paths as + include paths. + </p> + <p>Note that an SMIv2 MIB can import an SMIv1 MIB and vice versa. + </p> + <p>The following MIBs are built-ins of the Erlang SNMP compiler: + SNMPv2-SMI, RFC-1215, RFC-1212, SNMPv2-TC, SNMPv2-CONF, and + RFC1155-SMI. They cannot therefore be compiled separately. + </p> + </section> + + <section> + <title>MIB Consistency Checking</title> + <p>When an MIB is compiled, the compiler detects if several + managed objects use the same <c>OBJECT IDENTIFIER</c>. If that is + the case, it issues an error message. However, the compiler cannot + detect Oid conflicts between different MIBs. These kinds of + conflicts generate an error at load time. To avoid this, the + following function can be used to do consistency checking between + MIBs: + </p> + <pre> + +erl><input>snmpc:is_consistent(ListOfMibNames).</input> + </pre> + <p><c>ListOfMibNames</c> is a list of compiled MIBs, for example + <c>["RFC1213-MIB", "MY-MIB"]</c>. The function also performs + consistency checking of trap definitions.</p> + </section> + + <section> + <title>.hrl File Generation</title> + <p>It is possible to generate an <c>.hrl</c> file which contains + definitions of Erlang constants from a compiled MIB file. This + file can then be included in Erlang source code. The file will + contain constants for: + </p> + <list type="bulleted"> + <item>object Identifiers for tables, table entries and variables</item> + <item>column numbers</item> + <item>enumerated values</item> + <item>default values for variables and table columns. + </item> + </list> + <p>Use the following command to generate a .hrl file from an MIB: + </p> + <pre> +erl><input>snmpc:mib_to_hrl(MibName).</input> + </pre> + </section> + + <section> + <title>Emacs Integration</title> + <p>With the Emacs editor, the <c>next-error</c> (<c>C-X `</c>) + function can be used indicate where a compilation error occurred, + provided the error message is described by a line number. + </p> + <p>Use <c>M-x compile</c> to compile an MIB from inside Emacs, and + enter: + </p> + <pre> + <input>erl -s snmpc compile <MibName> -noshell</input> + </pre> + <p>An example of <c><![CDATA[<MibName>]]></c> is <c>RFC1213-MIB</c>. + </p> + </section> + + <section> + <title>Compiling from a Shell or a Makefile</title> + <p>The <c>erlc</c> commands can be used to compile SNMP MIBs. Example: + </p> + <pre> + <input>erlc MY-MIB.mib</input> + </pre> + <p>All the standard <c>erlc</c> flags are supported, e.g. + </p> + <pre> + <input>erlc -I mymibs -o mymibs -W MY-MIB.mib</input> + </pre> + <p>The flags specific to the MIB compiler can be specified by + using the <c>+</c> syntax: + </p> + <pre> + <input>erlc +'{group_check,false}' MY-MIB.mib</input> + </pre> + </section> + + <section> + <title>Deviations from the Standard</title> + <p>In some aspects the Erlang MIB compiler does not follow or + implement the SMI fully. Here are the differences: + </p> + <list type="bulleted"> + <item> + <p>Tables must be written in the following order: + <c>tableObject</c>, <c>entryObject</c>, <c>column1</c>, ..., + <c>columnN</c> (in order).</p> + </item> + <item> + <p>Integer values, for example in the <c>SIZE</c> expression + must be entered in decimal syntax, not in hex or bit syntax.</p> + </item> + <item> + <p>Symbolic names must be unique within a MIB and within a + system.</p> + </item> + <item> + <p>Hyphens are allowed in SMIv2 (a pragmatic approach). The + reason for this is that according to SMIv2, hyphens are allowed + for objects converted from SMIv1, but not for others. This is + impossible to check for the compiler.</p> + </item> + <item> + <p>If a word is a keyword in any of SMIv1 or SMIv2, it is a + keyword in the compiler (deviates from SMIv1 only).</p> + </item> + <item> + <p>Indexes in a table must be objects, not types (deviates + from SMIv1 only).</p> + </item> + <item> + <p>A subset of all semantic checks on types are + implemented. For example, strictly the <c>TimeTicks</c> may not + be sub-classed but the compiler allows this (standard MIBs must + pass through the compiler) (deviates from SMIv2 only).</p> + </item> + <item> + <p>The <c>MIB.Object</c> syntax is not implemented (since all + objects must be unique anyway).</p> + </item> + <item> + <p>Two different names cannot define the same OBJECT IDENTIFIER.</p> + </item> + <item> + <p>The type checking in the SEQUENCE construct is non-strict + (i.e. subtypes may be specified). The reason for this is + that some standard MIBs use this.</p> + </item> + <item>A definition has normally a status field. When the status field + has the value deprecated, then the MIB-compiler will ignore this + definition. With the MIB-compiler option <c>{deprecated,true}</c> + the MIB-compiler does not ignore the deprecated definitions.</item> + <item>An object has a DESCRIPTIONS field. The descriptions-field will + not be included in the compiled mib by default. In order to get + the description, the mib must be compiled with the option + <c>description</c>.</item> + </list> + </section> +</chapter> + |