namibv3: User Defined MIB Example Application, using SNMPv3 library.

This application demonstrates:
- How to use the NET+OS MIB Compiler.  
- How to add a custom MIB to the SNMP agent and use it with SNMPv3 library. 
- How to add SNMPv3 users that can access this MIB.
- 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.


*************************************************************************
*                                                                       *
*  Adding the EXAMPLE MIB						                        *
*                                                                       *
*************************************************************************

The application adds a custom enterprise MIB, called EXAMPLE, defined in the 
.\mibs\example-mib2.mib file. 

In order to add this EXAMPLE MIB:

1. It was compiled, using a MIB compiler. 

The resulting instruction file, C and header files were used in the application: 

example.ins			- instructions to customize custvars.h and custvars.c
example.h		    - application-specific header file
example.c		    - application-specific C file.

File names, generated by the NET+OS MIB compiler depend on the MIB definition name,
not on the MIB file name. 

1. custvars.h and custvars.c were modyfied, according to instructions in example.ins.

2. example.c was customized to add initialization data to conceptual table.

3. EXAMPLE MIB variables are added to the agent MIB database by naInitializeCustomMibs
   call in custvars.c. The wrapper function initializeCustomMibs is called in the 
   applicationStart before naSnmpStart is called.


*************************************************************************
*                                                                       *
*  Hard-coded application data					                        *
*                                                                       *
*************************************************************************

IMPORTANT: The notification targets IP address in notificationTargets table and AGENT_SOURCE_ADDR
		   must be changed before you run the application. Both are hard-coded in root.c.

1. The namibv3 sample exampleEnterprise is 1.3.6.1.4.1.901.  
   
   The hierarchy of the enterprise MIB's objects is:

            exampleEnterprise\examples\example\group\greenLedOn
                                         \yellowLedOn
                                         \bigBoss
            exampleEnterprise\examples\example\table\simpleTable\simpleEntry\index
																		    \rowStatus
																			\name

All the application data that does not represent EXAMPLE MIB is hard-coded in root.c: 

2. The EXAMPLE_ENTERPRISE_NUMBER == 901

3. The notification targets (trap destination) IP address is 10.52.35.113, hard-coded in root.c.

4. The agent IP address (AGENT_SOURCE_ADDR), used in the generation of default Engine Id 
   is 0x0a342079 (10.52.32.121), hard-coded in root.c

5. Default Treck USM and VACM tables have the following access:

   "initial1" SNMPv3 user (no security)  - read-only access to all MIBs 
										   
   "initial2" SNMPv3 user (authentication only, auth. password "auth_key") 
										 - read-write access to all MIBs.
										 
   "initial" SNMPv3 user (authentication and privacy, auth. password "auth_key", priv. password "priv_key") 
										 - read-write access to all MIBs.

6.  The application adds the following users and communities:

	"secureUser" SNMPv3 user (authentication and privacy, auth. password "auth_key", priv. password "priv_key")
										- read-write access to all MIBs.
										
	"authUser" SNMPv3 user (authentication only, auth. password "auth_key")
										- read-only access to all MIBs.	
										
	"authUser" SNMPv3 user (no authentication only, no privacy)
										- read-only access MIB-II only (1.3.6.1.2.1. RFC 1213).	
										
	V1 and V2C access for "public" and "private" communities is disabled.																																			 
										
	"exampleV1V2cComm" community with the following access:
										- read-only V1 access to MIB-II only.
										- read-only V2 access to all MIBs.

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


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

