userapps/opensource/net-snmp/agent/mibgroup/README

   1 This directory holds the implementation of individual MIB groups.
   2 Currently, this contains the eight MIB-2 groups, plus a basic template
   3 for new MIB groups (examples/example.c and examples/example.h)
   4
   5 Additionally, you may wish to check out the 'mib2c' perl script in the
   6 SRCDIR/local directory that can convert a written mib into C template
   7 files for use with this package as mib modules.
   8
   9 Each group consists of two files:
  10
  11   examples/example.h:   interface information
  12
  13         - declaration of the initialisation function 'init_example'
  14                 (optional)
  15         - declaration of the function(s) for retrieving variable
  16                 information 'var_example'
  17         - declaration of the function(s) for setting variable
  18                 information (if appropriate)
  19
  20         - declaration of the function(s) for parsing the snmpd.conf file
  21                 (optional)
  22         - a call to config_parse_dot_conf() to explain to the .conf
  23                 parser which tokens we want to parse.
  24                 (optional)
  25
  26         - definitions of the MIB group 'magic numbers'
  27                 declarations of the 'public' functions
  28
  29         - a list of the variables in the group, including
  30                 type information, mapping between magic numbers
  31                 and OID sub-identifiers within the group,
  32                 accessibility information, and the relevant
  33                 function for retrieving this variable's value.
  34                 They *must* be listed in the mib-descending order.
  35         - a call to 'config_load_mib', identifying the location of
  36                 this MIB group within the general MIB structure.
  37         - a call to 'config_require' to identify any other files
  38                 that are required by the implementation of this group.
  39                 (optional)
  40
  41     (these last three are only visible within the 'glue' file 'snmp_vars.c'
  42         (if at all), but are declared here for ease of maintainance)
  43
  44
  45
  46   examples/example.c:   implementation code
  47                 (can be non-existant if only the .h file is needed)
  48
  49         - a list of kernel information needed to report
  50                 on this group
  51         - an initialisation function (optional)
  52         - a routine to parse an snmpd.conf line.
  53         - a routine to free resources from above and return to
  54                 default settings.
  55         - 'header' function(s) to map the OID requested
  56                 to the next appropriate OID
  57                 (and similar system-independent setup)
  58         - function(s) (possibly system-specific) to
  59                 determine and return the value of the
  60                 variable requested.
  61         - (optionally) functions used to set values
  62         - other functions used internally
  63
  64
  65 To implement a new MIB group, copy the two files 'example.c'
  66 and 'example.h' to appropriate new files ({MODULENAME}.c and {MODULENAME}.h),
  67 and edit them as follows:
  68
  69         example.h:
  70                 globally change "example" to the new module name
  71                     and update the initial comment.
  72                 replace the EXAMPLE* defines with the list of
  73                     variables within this new group
  74                 fill in the 'MODULENAME_variables' structure with these
  75                     new variables, updating the type, accessibility
  76                     and sub-identifier information as appropriate.
  77                 replace 'variableN' with the maximum size of the
  78                     returned OID (omitting the group prefix).
  79                     For non-table values, this will probably be one
  80                     greater than the length of the sub-identifier.
  81                 update or remove the 'config_parse_dot_conf' call if
  82                     you need to handle lines in the snmpd.conf files.
  83                 update the 'config_load_mib' call with the appropriate
  84                     location within the global MIB structure, and
  85                     its length (note that 'MIB' has length 6)
  86                 provide a suitable 'config_require' call if this
  87                     code uses routines from any other files within
  88                     the 'mibgroup' directory (such as 'util_funcs.c')
  89
  90
  91
  92         example.c:
  93                 globally change "example" to the new module name
  94                     and update the initial comment.
  95                 replace the 'MODULENAME_nl' name list with any necessary
  96                     kernel variables, and update the associated #define's
  97                 replace the name length definition within the 'header'
  98                     function with the length of the requesting OID
  99                     (i.e. the sum of the lengths given in the subtree
 100                      definition, and the variable structure above).
 101                 replace the basic 'switch' structure within the
 102                     'var_MODULENAME' function with the necessary code
 103                     to calculate the required information.
 104                 (plus any other internal functions as needed).
 105
 106   It will then be necessary to (re-)run the configure script with the
 107 option
 108         --with-mib-modules="MODULENAME"
 109
 110 (where MODULENAME matches the name of the .c/.h file pair exactly).
 111 Note that if anything in the config_* macros changes, or the init function
 112 is added or removed, then the configure script will need to be re-run.
 113