[ SEA-GHOST MINI SHELL]

This README describes the ./local/mib2c script.

Author:  Derek Simkowiak
         dereks@kd-dev.com
         http://www.kd-dev.com
         (please mail questions to net-snmp-coders@lists.sourceforge.net,
         not to the author directly.  Thanks!)

Date:    Wed Jan 20 02:51:06 PST 1999
-----------------------------------------------------------------------
mib2c

OVERVIEW

	mib2c is a Perl script that takes a MIB (such as those files found
in ./mibs/ ) and converts it into C code.  That C code can then be used as a
"template" to implement your MIB.  Then, when you are done editing the C
code and recompiling, the UCD-SNMP agent (snmpd) will support your MIB.
mib2c takes the place of "MIB Compilers" that come with commercial SNMP
agents.


REQUIREMENTS/INSTALLATION

	mib2c requires the SNMP.pm Perl module.  As of this writing the
latest version of the SNMP.pm module is 1.8.

	The SNMP.pm module can be downloaded from CPAN at 

http://www.cpan.org/modules/by-module/SNMP/

	...the file that you want is probably SNMP-1.8b5.tar.gz .
If you didn't know that already, most every Perl module can be downloaded
from CPAN (www.cpan.org).  Follow the installation instructions for the
module.

	NOTE: If you are running Redhat Linux 5.2 (and perhaps other
versions), you might get the following errors during the "make test" phase
of the installation of the SNMP.pm module:

[root@olly SNMP-1.8b5]# make test             # This is the command...
PERL_DL_NONLAZY=1 /usr/bin/perl -I./blib/arch -I./blib/lib
-I/usr/lib/perl5/i386-linux/5.00404 -I/usr/lib/perl5 -e 'use Test::Harness
qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
t/mib...............ok
t/session...........FAILED tests 7-8
        Failed 2/14 tests, 85.71% okay
t/translate.........ok
Failed Test  Status Wstat Total Fail  Failed  List of failed
-------------------------------------------------------------------------------
t/session.t                  14    2  14.29%  7-8
Failed 1/3 test scripts, 66.67% okay. 2/24 subtests failed, 91.67% okay.
make: *** [test_dynamic] Error 9


	If the "make" went okay, then you can ignore these test failures.
These indicate you don't have write access to the portions of the mib
tree that the test script is trying to use.  Please don't email the
UCD-SNMP list with other errors regarding the SNMP.pm module.
comp.lang.perl.modules is probably the most appropriate spot to
discuss problems with the SNMP.pm perl module itself. Interelated
problems between net-snmp and SNMP could be discussed on the net-snmp
mailing lists though.


USAGE

	mib2c takes one argument: an OID.  It then traces down that OID
and generates the template C code.  Here is the documentation, from the
top of the script:

# This program, given an OID reference as an argument, creates some
# template mib module files to be used with the net-snmp agent.  It is
# far from perfect and will not generate working modules, but it
# significantly shortens development time by outlining the basic
# structure.
#
# Its up to you to verify what it does and change the default values
# it returns.
#
# You *must* correct the beginning of the var_XXX() function to
# correctly determine mib ownership of the incoming request.


FINDING YOUR MIB

	Before you can specify the OID for your enterprise/MIB on the
command line, the script needs to be able to find your MIB so that it can
read it in and generate template code.  Joe Marzot (gmarzot@nortelnetworks.com)
tells us:
--------------------------------------
you should read (man mib_api). The default behaviour for mib loading
from within the perl interface uses the environment variables described
there. You can also override these and explicitly define mibdirs and
load modules through the perl/SNMP api.

the easiest thing to do is toss the mibs in /usr/local/share/snmp/mibs
and set the env. var., MIBS, to 'ALL'.
--------------------------------------

	I recommend following the last two lines of advice.  I simply did

# cp /home/dereks/MY-MIB-FILE.txt /usr/local/share/snmp/mibs/
# export MIBS=ALL

	...on my Redhat system (with a BASH shell) and it was able to find
my MIB just fine.


EXAMPLES

	Here are some examples from Wes Hardaker (wjhardaker@ucdavis.edu).
He's using a C shell.  Wes writes:
--------------------------------------
Ok, in order to run the thing, you actually need to do something like
this:

setenv MIBS MY-ITEM-MIB          # assumes csh
mib2c itemNode

Where, "itemNode" should be a node in the mib tree that you want to
generate C code for.  Note, pick small pieces not large ones.  Yes, it 
will generate code for the entire mibII tree if you ask it to, in one
very large mib file.

Examples:

% mib2c interfaces
outputing to interfaces.c and interfaces.h ...
  depth: 3
  Number of Lines Created:
178 interfaces.c
84 interfaces.h
262 total
Done.

% mib2c mib-2                             # Don't ever do this.
outputing to mib-2.c and mib-2.h ...
  depth: 5
  Number of Lines Created:
2783 mib-2.c
617 mib-2.h
3400 total
Done.

It may have some sorting problems with multiple level mib tree
branches being generated into one piece of code (reorder the .h file
structure to be in OID lexical order if needed).
--------------------------------------

WHAT TO DO WITH THE CODE THAT GETS GENERATED

	You will need to edit your generated code to work with your
hardware.  For instance, if your MIB is for a refrigerator, you will need
to write the code that talks to the refridgerator (through the serial
port, maybe?) in Fridge Protocol.

	See the files in ./agent/mibgroup/examples/ and
./agent/mibgroup/dummy/ for heavily-commented example code.  Don't ask me
questions about this stuff--I'm just now figuring it out myself...

	[NOTE: If anyone out there has tips about necessary options to
./configure, or re-compiling snmpd with custom MIB support, please add
them here...]

WARNING

	As of this writing, the mib2c compiler is a bit outdated and needs
some work.  Wes writes:
--------------------------------------
It already needs changing, because the architecture has changed in the 
3.6 line (though its backwards compatible, I'd prefer to generate
code from newer models than older ones).
--------------------------------------
	When I asked him to elaborate on the new 3.6 archictecture, all I
got was:
--------------------------------------
It hopefully will be in the new documentation about mib module api
that Dave Shield is putting together (which is also currently wrong,
for that matter)...
--------------------------------------
	...so I don't know what the hell he's talking about.


SOME ERRORS AND THEIR MEANING

	If you get a large number of errors that look like:

[...]
unknown type:  INTEGER for prIndex
unknown type:  OCTETSTR for prNames
unknown type:  INTEGER for prMin
[...]

	...then you are trying to use an old version of the mib2c script
that does not support the SNMP.pm module version 1.8.  Get the latest
version of the script.

	If you get the error 

Couldn't find mib reference: myEnterpriseOID

	...when you know that it should be finding your MIB file(s), then
you forgot to put the word "END" at the very end of your MIB.  (Uh...I'm
not speaking from experience here.  Really.)

ACKNOWLEGMENTS

	Many thanks to the people on the UCD-SNMP mailing list
(net-snmp-users@lists.sourceforge.net).  In particular, many thanks to

Wes Hardaker <wjhardaker@ucdavis.edu>
Ken McNamara <conmara@tcon.net>
Joe Marzot <gmarzot@nortelnetworks.com>

	...since about half this document is just cut'n'pasted from emails
they sent me.

	Good luck with your project.

Derek Simkowiak
dereks@kd-dev.com
http://www.kd-dev.com