userapps/opensource/net-snmp/local/README.mib2c

   1 This README describes the ./local/mib2c script.
   2
   3 Author:  Derek Simkowiak
   4          dereks@kd-dev.com
   5          http://www.kd-dev.com
   6          (please mail questions to net-snmp-coders@lists.sourceforge.net,
   7          not to the author directly.  Thanks!)
   8
   9 Date:    Wed Jan 20 02:51:06 PST 1999
  10 -----------------------------------------------------------------------
  11 mib2c
  12
  13 OVERVIEW
  14
  15         mib2c is a Perl script that takes a MIB (such as those files found
  16 in ./mibs/ ) and converts it into C code.  That C code can then be used as a
  17 "template" to implement your MIB.  Then, when you are done editing the C
  18 code and recompiling, the UCD-SNMP agent (snmpd) will support your MIB.
  19 mib2c takes the place of "MIB Compilers" that come with commercial SNMP
  20 agents.
  21
  22
  23 REQUIREMENTS/INSTALLATION
  24
  25         mib2c requires the SNMP.pm Perl module.  As of this writing the
  26 latest version of the SNMP.pm module is 1.8.
  27
  28         The SNMP.pm module can be downloaded from CPAN at
  29
  30 http://www.cpan.org/modules/by-module/SNMP/
  31
  32         ...the file that you want is probably SNMP-1.8b5.tar.gz .
  33 If you didn't know that already, most every Perl module can be downloaded
  34 from CPAN (www.cpan.org).  Follow the installation instructions for the
  35 module.
  36
  37         NOTE: If you are running Redhat Linux 5.2 (and perhaps other
  38 versions), you might get the following errors during the "make test" phase
  39 of the installation of the SNMP.pm module:
  40
  41 [root@olly SNMP-1.8b5]# make test             # This is the command...
  42 PERL_DL_NONLAZY=1 /usr/bin/perl -I./blib/arch -I./blib/lib
  43 -I/usr/lib/perl5/i386-linux/5.00404 -I/usr/lib/perl5 -e 'use Test::Harness
  44 qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
  45 t/mib...............ok
  46 t/session...........FAILED tests 7-8
  47         Failed 2/14 tests, 85.71% okay
  48 t/translate.........ok
  49 Failed Test  Status Wstat Total Fail  Failed  List of failed
  50 -------------------------------------------------------------------------------
  51 t/session.t                  14    2  14.29%  7-8
  52 Failed 1/3 test scripts, 66.67% okay. 2/24 subtests failed, 91.67% okay.
  53 make: *** [test_dynamic] Error 9
  54
  55
  56         If the "make" went okay, then you can ignore these test failures.
  57 These indicate you don't have write access to the portions of the mib
  58 tree that the test script is trying to use.  Please don't email the
  59 UCD-SNMP list with other errors regarding the SNMP.pm module.
  60 comp.lang.perl.modules is probably the most appropriate spot to
  61 discuss problems with the SNMP.pm perl module itself. Interelated
  62 problems between net-snmp and SNMP could be discussed on the net-snmp
  63 mailing lists though.
  64
  65
  66 USAGE
  67
  68         mib2c takes one argument: an OID.  It then traces down that OID
  69 and generates the template C code.  Here is the documentation, from the
  70 top of the script:
  71
  72 # This program, given an OID reference as an argument, creates some
  73 # template mib module files to be used with the net-snmp agent.  It is
  74 # far from perfect and will not generate working modules, but it
  75 # significantly shortens development time by outlining the basic
  76 # structure.
  77 #
  78 # Its up to you to verify what it does and change the default values
  79 # it returns.
  80 #
  81 # You *must* correct the beginning of the var_XXX() function to
  82 # correctly determine mib ownership of the incoming request.
  83
  84
  85 FINDING YOUR MIB
  86
  87         Before you can specify the OID for your enterprise/MIB on the
  88 command line, the script needs to be able to find your MIB so that it can
  89 read it in and generate template code.  Joe Marzot (gmarzot@nortelnetworks.com)
  90 tells us:
  91 --------------------------------------
  92 you should read (man mib_api). The default behaviour for mib loading
  93 from within the perl interface uses the environment variables described
  94 there. You can also override these and explicitly define mibdirs and
  95 load modules through the perl/SNMP api.
  96
  97 the easiest thing to do is toss the mibs in /usr/local/share/snmp/mibs
  98 and set the env. var., MIBS, to 'ALL'.
  99 --------------------------------------
 100
 101         I recommend following the last two lines of advice.  I simply did
 102
 103 # cp /home/dereks/MY-MIB-FILE.txt /usr/local/share/snmp/mibs/
 104 # export MIBS=ALL
 105
 106         ...on my Redhat system (with a BASH shell) and it was able to find
 107 my MIB just fine.
 108
 109
 110 EXAMPLES
 111
 112         Here are some examples from Wes Hardaker (wjhardaker@ucdavis.edu).
 113 He's using a C shell.  Wes writes:
 114 --------------------------------------
 115 Ok, in order to run the thing, you actually need to do something like
 116 this:
 117
 118 setenv MIBS MY-ITEM-MIB          # assumes csh
 119 mib2c itemNode
 120
 121 Where, "itemNode" should be a node in the mib tree that you want to
 122 generate C code for.  Note, pick small pieces not large ones.  Yes, it
 123 will generate code for the entire mibII tree if you ask it to, in one
 124 very large mib file.
 125
 126 Examples:
 127
 128 % mib2c interfaces
 129 outputing to interfaces.c and interfaces.h ...
 130   depth: 3
 131   Number of Lines Created:
 132 178 interfaces.c
 133 84 interfaces.h
 134 262 total
 135 Done.
 136
 137 % mib2c mib-2                             # Don't ever do this.
 138 outputing to mib-2.c and mib-2.h ...
 139   depth: 5
 140   Number of Lines Created:
 141 2783 mib-2.c
 142 617 mib-2.h
 143 3400 total
 144 Done.
 145
 146 It may have some sorting problems with multiple level mib tree
 147 branches being generated into one piece of code (reorder the .h file
 148 structure to be in OID lexical order if needed).
 149 --------------------------------------
 150
 151 WHAT TO DO WITH THE CODE THAT GETS GENERATED
 152
 153         You will need to edit your generated code to work with your
 154 hardware.  For instance, if your MIB is for a refrigerator, you will need
 155 to write the code that talks to the refridgerator (through the serial
 156 port, maybe?) in Fridge Protocol.
 157
 158         See the files in ./agent/mibgroup/examples/ and
 159 ./agent/mibgroup/dummy/ for heavily-commented example code.  Don't ask me
 160 questions about this stuff--I'm just now figuring it out myself...
 161
 162         [NOTE: If anyone out there has tips about necessary options to
 163 ./configure, or re-compiling snmpd with custom MIB support, please add
 164 them here...]
 165
 166 WARNING
 167
 168         As of this writing, the mib2c compiler is a bit outdated and needs
 169 some work.  Wes writes:
 170 --------------------------------------
 171 It already needs changing, because the architecture has changed in the
 172 3.6 line (though its backwards compatible, I'd prefer to generate
 173 code from newer models than older ones).
 174 --------------------------------------
 175         When I asked him to elaborate on the new 3.6 archictecture, all I
 176 got was:
 177 --------------------------------------
 178 It hopefully will be in the new documentation about mib module api
 179 that Dave Shield is putting together (which is also currently wrong,
 180 for that matter)...
 181 --------------------------------------
 182         ...so I don't know what the hell he's talking about.
 183
 184
 185 SOME ERRORS AND THEIR MEANING
 186
 187         If you get a large number of errors that look like:
 188
 189 [...]
 190 unknown type:  INTEGER for prIndex
 191 unknown type:  OCTETSTR for prNames
 192 unknown type:  INTEGER for prMin
 193 [...]
 194
 195         ...then you are trying to use an old version of the mib2c script
 196 that does not support the SNMP.pm module version 1.8.  Get the latest
 197 version of the script.
 198
 199         If you get the error
 200
 201 Couldn't find mib reference: myEnterpriseOID
 202
 203         ...when you know that it should be finding your MIB file(s), then
 204 you forgot to put the word "END" at the very end of your MIB.  (Uh...I'm
 205 not speaking from experience here.  Really.)
 206
 207 ACKNOWLEGMENTS
 208
 209         Many thanks to the people on the UCD-SNMP mailing list
 210 (net-snmp-users@lists.sourceforge.net).  In particular, many thanks to
 211
 212 Wes Hardaker <wjhardaker@ucdavis.edu>
 213 Ken McNamara <conmara@tcon.net>
 214 Joe Marzot <gmarzot@nortelnetworks.com>
 215
 216         ...since about half this document is just cut'n'pasted from emails
 217 they sent me.
 218
 219         Good luck with your project.
 220
 221 Derek Simkowiak
 222 dereks@kd-dev.com
 223 http://www.kd-dev.com
 224