namib: User Defined Enterprise MIB Example Application

This application demonstrates: 
- How to add an enterprise MIB to the SNMP agent
- How to use the NETOS MIB Compiler.  
- How to use trap functions, generated by the MIB compiler.
- How to locally add, remove, and modify conceptual table rows, 
  using API, generated by the MIB compiler
- How to write API functions to locally access scalar MIB data.

This application includes files that were generated by the NETOS MIB compiler, using 
the enterprise MIB located in .\mibs\example-mib2.mib.

If you are interested in creating a custom enterprise MIB and understanding 
the steps needed to achieve this, Digi recommends these steps:

1.  Run this application as is, using your favorite MIB Browser.  You can 
    communicate with the target SNMP agent by performing a full SNMP MIB walk, 
    which includes the standard Internet MIB-II (defined by RFC 1213), plus 
    the enterprise MIB defined by the example-mib2 MIB.  The Internet MIB are 
    those elements at OIDs 1.3.6.1.2.1. and the namib sample enterprise MIB, 
    created using the MIB Complier, are located at 1.3.6.1.4.1.901.  The 
    hierarchy of the enterprise MIB's objects is:

            example\nsil\exampleOne\group\greenLedOn
                                         \yellowLedOn
                                         \bigBoss
            example\nsil\exampleOne\table\simpleTable\simpleEntry\index
																 \rowStatus
                                                                 \name

2.  Now that you have completed executing the example application, we'd like 
    you to experience compiling a MIB and rebuilding the application using the 
    files generated by the MIB compiler.  To do so, follow the proceudure 
    below in the section "Instructions to recompile this sample's MIB".

3.  Now that you are familiar with running the MIB compiler and how the MIB
    Compiler output files link to your application code, create your own MIB. 
    Update the custvars.h and custvars.c file with instructions provided in *.ins.  
	Build your application and run, using your favorite MIB Browser.

    Note: A MIB file can contain only one MIB definition.  In the case of a 
    custom MIB containing other MIBs, place these MIB files in the 
    c:\netos\mibcomp\mibcomp_win321\smi\mibs\ietf directory.


*************************************************************************
*                                                                       *
*  Using trap functions, generated by the MIB compiler                  *
*                                                                       *
*************************************************************************

Trap functions tfexampletrapgreen_trap and tfexampletrapyellow_trap have 
been generated by the MIB compiler; they are located in example.c. and called 
in root.c.

The trap functions must not be called from within the MIB variable access 
functions.

*************************************************************************
*                                                                       *
*  Using API functions to insert and delete table rows,                 *
*        generated by the MIB compiler                                  *
*                                                                       *
*************************************************************************

MIB compiler generates API functions to insert, delete, and iterate through
the MIB table entries. In this example functions are:
    
    tfinsert_simpletable_entry
    tfdisplay_simpletable_entry
    tfremove_simpletable_entry

AddReplaceRemoveRowsExample() function (not generated by the MIB compiler),
provides an example to shows how to use generated API and how to
use memory for the entry for this table.


*************************************************************************
*                                                                       *
*  Instructions to recompile this sample's MIB                          *
*                                                                       *
*************************************************************************

1. Right click on the project name in Project Explorer window in Digi ESP.
2. Select NET+OS MIB Compiler.
3. Browse to your MIB file and select it. 
4. Check MIB Output Directory.
5. Click on Next button.
6. Click on Finish button.

	example.c and example.h files have been backed up to example.c.back and example.h.back. 

	In the case of a successful compilation, the  NETOS MIB compiler genarates files: 
	example.c, example.h, and example.ins.  

	The example.ins file contains instructions to how to update custvars.h and custvars.c files 
	to integrate your MIB with the NET+OS SNMP agent. These steps have been performed already for
	the EXAMPLE mib. 

    When you use your own custom enterprise MIB, the files custvars.h and custvars.c 
    will require the custvars.h and custvars.c to be updated with your specific MIB data.
	This should be done exactly as described in .ins file.

    Delete custvars.h and custvars.c files. Copy custvars_orig.hfile and custvars_orig.cfile
    files from the backup directory and rename them to custvars.h and custvars.c.
    Modify them according the instructions in example.ins.

7. Now you can recompile, link and rerun the namib sample application.

8. Some small changes were made in example.c to ititialize the conceptual table.
   Updated example.c is backed up in the backup directory as example.cfile.

9. The application, generated by the MIB compiler and integrated with custvars.h, custvars.c,
   and root.c maintains the custom MIB completely. It reads/writes variable values from/to 
   mibTableHeaders structure, adds and removes conceptual rows. Some customization might to 
   be needed to synchronize the MIB with the rest of the application: save data to permannent storage, 
   turn LEDs on/off, etc. Unfortunately, the MIB compiler does not generate any callbacks or comments 
   to aid this process.

*************************************************************************
*                                                                       *
*  Using the MIB compiler on command line.		                        *
*                                                                       *
*************************************************************************

In order to use the MIB compiler on a command line, backup and delete 
example.h and example.c manually. In DOS command prompt change directory
to the application directory of this sample and type:

	>mib2src .\mibs\example-mib2.mib


*************************************************************************
*                                                                       *
*  The following files are provided in this template:                   *
*                                                                       *
*************************************************************************

.\mibs\example\example-mib2.mib     MIB definition file

appconf.h         contains application configuration settings.
.\32b\makefile    make file for the GNU toolset.
readme            this file.
root.c            contains the applicationStart() function that starts
                  the SNMP agent. Also sets up traps and the agent IP address.
				  Calls initializeCustomMibs() to add the EXAMPLE MIB to 
				  the SNMP agent.
custvars.h        standard header file that integrates the custom MIB with SNMP 
                  agent, according to instructions in .ins file.
custvars.c        standard C file that integrates the custom MIB with SNMP 
                  agent, according to instructions in .ins file.
example.h         header file generated by the MIB compiler
example.c         C file generated by the MIB compiler 
.\backup          Contains a copy of the example.* files
                  and original custvars_orig.* files.

In addition, the following files in the BSP directory are built
as part of this application.

reset.s         contains the reset code
appconf_api.c   contains code used to read settings in appconf.h


*************************************************************************
*                                                                       *
*  Usage of SNMP and IPSEC.					                            *
*                                                                       *
*************************************************************************

Any aplication that uses an SNMP agent and IPSEC must: 
- Use the libtcpip.a library
- Use the libsnmp.a or the libsnmpv3.a library
- Define VPN_ENABLED in the application makefile.

Any aplication that uses an SNMP agent but no IPSEC must 
- Use the libtcpip_no_ipsec.a library
- Use the libsnmp_no_ipsec.a or the libsnmpv3_no_ipsec.a library
- Not define VPN_ENABLED in the application makefile.

Any mismatch between libraries with and without IPSEC and the the 
definition of VPN_ENABLED will cause memory corruptions.

By default all SNMP samples are built without IPSEC. Use the following command to build 
SNMP samples with IPSEC on a command line:	make USE_IPSEC=yes




