local/README.mib2c - vendor/opensource/netsnmp - Git at Google

 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
	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