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 add and remove conceptual rows to tables. 
- How to use trap functions, generated by the MIB compiler.


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

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

In order to add this EXAMPLE MIB:

1. It was compiled, using a MIB compiler command:

>mib2src .\mibs\example-mib2

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

example.ins			- instructions to add initialization data,
example_local.h		- application-specific structure definitions,
example_var.h		- application-specific constunts and function prototypes,
example_local.c		- application-specific variable access code, that requires customization,
example_var.c		- application-specific variable access code, that does not require customization.

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

1. The initialization data and include statements were added to custvars.c file,
   according to instructions in example.ins.

2. example_local.c and example_var.c files were added to Makefile and project.gpj.

3. example_local.c was customized for this application by adding application-specific 
   function calls, which are be used by SNMP agent on remote access to the EXAMPLE MIB.
   These application-specific calls are all preceded by the comment:
   /* namibv3 specific code added */ in example_local.c. Application-specific 
   functions themself are placed in mibstubs.c file, which has been also added to 
   Makefile and project.gpj.

4. Compiler warnings in code, generated by the MIB compiler, were removed manually.

5. EXAMPLE MIB variables are added 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.1234567.  
   The EXAMPLE MIB variables are located at 1.3.6.1.4.1.1234567.33.1

   The hierarchy of the enterprise MIB's objects is:

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

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

2. The EXAMPLE_ENTERPRISE_NUMBER == 1234567

3. The notification targets (trap destination) IP address is 10.52.35.143.

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

5. All default Treck USM and VACM tables are left as described in NET+OS API Reference guide, 
   except for the vacmAccessTable. The vacmAccessTable has been changed to provide the following 
   MIB access:

   "initial1" SNMPv3 user (no security)  - read-only access to Internet MIB-II (1.3.6.1.2.1. RFC 1213) 
										   No access to EXAMPLE MIB.

   "initial2" SNMPv3 user (authentication only, auth. password "auth_key") 
										 - read-write access to MIB-II.
										 - read-only access to  EXAMPLE MIB.

   "initial" SNMPv3 user (authentication and privacy, auth. password "auth_key", priv. password "priv_key") 
										 - read-write access to MIB-II.
										 - read-only access to  EXAMPLE MIB.

   "public / private" communities with V1 access	
										- read-only access to MIB-II. 
										- No access to EXAMPLE MIB.

  "public / private" communities with V2C access	
										- read-write access to MIB-II. 
										- No access to EXAMPLE MIB.

6. The application adds 2 users and a V2c community:

	"secureExampleUser" SNMPv3 user (authentication and privacy, auth. password "example_auth_password", 
																 priv. password "example_priv_password") 
										- no access to MIB-II
										- read-write access to EXAMPLE MIB.

	"exampleV2Comm" community with V2C access
										- no access to MIB-II
										- read-only access to EXAMPLE MIB.


*************************************************************************
*                                                                       *
*  Adding Conceptual rows					                            *
*                                                                       *
*************************************************************************

The NET+OS MIB compiler does not generate code for adding conceptual rows
to tables. 

All code for for adding conceptual rows was written for this application, 
it resides in app_simpletable_entry_get and app_write_simpletable_entry
functions in mibstubs.c.


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

Trap functions tfexampletrapgreen_trap and tfexampletrapyellow_trap have 
been generated by the MIB compiler; they are in example_vars.c. Their 
wrapper functions sendGreenLedTrap and sendYellowLedTrapar are in mibstubs.c
and called in root.c.

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

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

Assuming that c:\netos is the NET+OS installation directory.

1.  Open a Windows command line window.
2.  Change directory to c:\netos\src\examples\namibv3
3.  Delete the NET+OS MIB Compiler output files example*.*.  A copy of these 
    exist in the .\backup directory and will be used for reference later.
4.  Invoke the NET+OS MIB Compiler by entering in the Windows command line:

    >mib2src .\mibs\example-mib2

    In the case of a successful compilation, the  NET+OS MIB compiler genarates 
    files: example_local.c, example_local.h, example_var.c, example_var.h, 
    example.ins.  

    The file example.ins contains instructions on the changes needed to 
    integrate the user defined MIB with the SNMP agent.  For this sample 
    application, the root.c makes a call to initializeCustomMibs(), located in 
    custvars.c, which contains a call to naInitializeCustomMibs() that 
    includes the custSnmpSubtrees and custConceptualTables data structures.

    When you use your own custom enterprise MIB, the file custvars.c will 
    require updates with your specific custSnmpSubtrees, custConceptualTables 
    and tvSnmpExampleoneVars per your MIB's *.ins file.

    To rerun this example, no change is needed, since the instructions from 
    example.ins have already been integrated into the custvars.c file.

    The application specific portion of your enterprise MIB should be placed 
    in the empty function stubs created in the example_local.c file.  For 
    convenience, all the demonstration code is located in mibstubs.c.  The
    added application hooks fleshing out the stub functions can be better 
    understood by comparing the originally modified example_local.c file 
    (located in the .\backup directory) to the new one just generated.

5.  Copy the original .\backup\example_local.c to .\example_local.c. 

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

*************************************************
*                                               *
*   Next Steps                                  *
*                                               *
*************************************************

    At this point, you can modify the sample MIB or replace this MIB with your
    own MIB.  Assuming the MIB Definition name in your MIB is now called
    MibName (instead of EXAMPLE), the procedure outlined can be repeated, 
    except the files generated by the MIB Compiler will be mibname_local.c, 
    mibname_local.h, mibname_var.c, mibname_var.h, and mibname.ins.  The 
    make/build files will need to be updated to incorporate the new MIB 
    Compiler output files (and removing the old example*.* files).

    The structures in custvars.c will need modification per the mibname.ins
    file and the empty function stubs in mibname_local.c will need fleshing 
    out.  Note the comments in function headers in mibname_local.c provide 
    guidance to how the functions should be implemented.

The following files are provided in this template.

appconf.h         Sets application configuration settings
.\32b\image.gpj   Used to build the big endian Green Hills version of the
                  application.  The build script creates a version that
                  can be debugged with Multi, and the file image.bin 
                  which can be written into a ROM that uses the bootloader.
.\32b\makefile    Make file for the GNU toolset.
.\32b\rom.gpj     used to build the big endian ROM image of application
project.gpj       Contains application specific build settings
readme            This file
root.c            Contains the applicationStart() function that starts
                  the SNMP agent
custvars.c        Contains custSnmpSubtrees and custConceptualTables tables, 
                  to which entries must be added from example.ins file, and 
                  the call to naInitializeCustomMibs API call.
mibstubs.c        Contains application specific MIB functionality.  These 
                  functions are included and used to flesh out the raw 
                  example_local.c file.  Note that all modifications to this 
                  file are encapsulated within the NET_OS_SPECIFIC definition.
example_local.h   Header file generated by the MIB compiler
example_local.c   C file generated by the MIB compiler that contains stub
                  functions for the user to fill in
example_var.h     Header file generated by the MIB compiler
example_var.c     C file generated by the MIB compiler that contains code
                  calls the stub functions in example_local.c
.\backup          Contains a copy of the example_*.* files, which will be overwritten by the MIB compiler.


