aboutsummaryrefslogtreecommitdiffstats
path: root/lib/snmp/doc/src/snmp_mib_compiler.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/snmp/doc/src/snmp_mib_compiler.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/snmp/doc/src/snmp_mib_compiler.xml')
-rw-r--r--lib/snmp/doc/src/snmp_mib_compiler.xml252
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 &lt;MibName&gt; -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>
+