doc/snmp_agent.txt

   1 SNMPv1 agent for lwIP [preliminairy]
   2
   3 Author: Christiaan Simons
   4
   5 This is a brief introduction how to use and configure the SNMP agent.
   6 Note the agent uses the raw-API UDP interface so you may also want to
   7 read rawapi.txt to gain a better understanding of the SNMP messages handling.
   8
   9 Agent capabilities
  10 ==================
  11
  12 SNMPv1 per RFC1157
  13   This is an old(er) standard but is still widely supported.
  14   For SNMPv2c and v3 have a greater complexity and need many
  15   more lines of code. IMHO this breaks the idea of "lightweight IP".
  16   Note the S in SNMP stands for "Simple" and is actually a bad joke.
  17
  18 MIB II per RFC1213
  19   The standard lwIP stack management information base.
  20   This is a required MIB, so this is always enabled.
  21
  22 Loading additional MIBs
  23   MIBs can only be added in compile-time, not in run-time.
  24   There is no MIB compiler thus additional MIBs must be hand coded.
  25
  26 Large SNMP message support
  27   The packet decoding and encoding routines are designed
  28   to use pbuf-chains. Larger payloads then the minimum
  29   SNMP requirement of 484 octets are supported if the
  30   PBUF_POOL_SIZE and IP_REASS_BUFSIZE are set to match your
  31   local requirement.
  32
  33 Building the agent
  34 ==================
  35
  36 First of all you'll need to add the following define
  37 to your local lwipopts.h:
  38
  39 #define LWIP_SNMP               1
  40
  41 and add the source files in lwip/src/core/snmp
  42 and some snmp headers in lwip/src/include/lwip to your makefile.
  43
  44 Note you'll might need to adapt you network driver to update
  45 the mib2 variables for your interface.
  46
  47 Running the agent
  48 =================
  49
  50 The following function calls must be made in your program to
  51 actually get the SNMP agent running.
  52
  53 Before starting the agent you should supply pointers
  54 to non-volatile memory for sysContact, sysLocation,
  55 and snmpEnableAuthenTraps. You can do this by calling
  56
  57 snmp_set_syscontact()
  58 snmp_set_syslocation()
  59 snmp_set_snmpenableauthentraps()
  60
  61 Additionally you may want to set
  62
  63 snmp_set_sysdescr()
  64 snmp_set_sysobjid() (if you have a private MIB)
  65 snmp_set_sysname()
  66
  67 In the lwIP initialisation sequence call snmp_init() just after
  68 the call to udp_init().
  69
  70 Exactly every 10 msec the SNMP uptime timestamp must be updated with
  71 snmp_inc_sysuptime(). You should call this from a timer interrupt
  72 or a timer signal handler depending on your runtime environment.
  73
  74
  75 Private MIBs
  76 ============
  77
  78 If want to extend the agent with your own private MIB you'll need to
  79 add the following define to your local lwipopts.h:
  80
  81 #define SNMP_PRIVATE_MIB        1
  82
  83 You must provide the private_mib.h and associated files yourself.
  84 Note we don't have a "MIB compiler" that generates C source from a MIB,
  85 so you're required to do some serious coding if you enable this!
  86
  87 Note the lwIP enterprise ID (26381) is assigned to the lwIP project,
  88 ALL OBJECT IDENTIFIERS LIVING UNDER THIS ID ARE ASSIGNED BY THE lwIP
  89 MAINTAINERS!
  90
  91 If you need to create your own private MIB you'll need
  92 to apply for your own enterprise ID with IANA: http://www.iana.org/numbers.html
  93
  94 You can set it by passing a struct snmp_obj_id to the agent
  95 using snmp_set_sysobjid(&my_object_id), just before snmp_init().
  96
  97 Agent internals [advanced use]
  98 ==============================
  99
 100 todo
 101
 102