Home | History | Annotate | Download | only in doc
      1 SNMPv1 agent for lwIP
      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 message handling.
      8 
      9 0 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 
     17   Note the S in SNMP stands for "Simple". Note that "Simple" is
     18   relative. SNMP is simple compared to the complex ISO network
     19   management protocols CMIP (Common Management Information Protocol)
     20   and CMOT (CMip Over Tcp).
     21 
     22 MIB II per RFC1213
     23   The standard lwIP stack management information base.
     24   This is a required MIB, so this is always enabled.
     25   When builing lwIP without TCP, the mib-2.tcp group is omitted.
     26   The groups EGP, CMOT and transmission are disabled by default.
     27   
     28   Most mib-2 objects are not writable except:
     29   sysName, sysLocation, sysContact, snmpEnableAuthenTraps.
     30   Writing to or changing the ARP and IP address and route
     31   tables is not possible.
     32  
     33   Note lwIP has a very limited notion of IP routing. It currently
     34   doen't have a route table and doesn't have a notion of the U,G,H flags.
     35   Instead lwIP uses the interface list with only one default interface
     36   acting as a single gateway interface (G) for the default route.
     37 
     38   The agent returns a "virtual table" with the default route 0.0.0.0
     39   for the default interface and network routes (no H) for each
     40   network interface in the netif_list.
     41   All routes are considered to be up (U).
     42 
     43 Loading additional MIBs
     44   MIBs can only be added in compile-time, not in run-time.
     45   There is no MIB compiler thus additional MIBs must be hand coded.
     46 
     47 Large SNMP message support
     48   The packet decoding and encoding routines are designed
     49   to use pbuf-chains. Larger payloads than the minimum
     50   SNMP requirement of 484 octets are supported if the 
     51   PBUF_POOL_SIZE and IP_REASS_BUFSIZE are set to match your
     52   local requirement.
     53 
     54 1 Building the Agent
     55 ====================
     56 
     57 First of all you'll need to add the following define
     58 to your local lwipopts.h:
     59 
     60 #define LWIP_SNMP               1
     61 
     62 and add the source files in lwip/src/core/snmp
     63 and some snmp headers in lwip/src/include/lwip to your makefile.
     64 
     65 Note you'll might need to adapt you network driver to update
     66 the mib2 variables for your interface.
     67 
     68 2 Running the Agent
     69 ===================
     70 
     71 The following function calls must be made in your program to
     72 actually get the SNMP agent running.
     73 
     74 Before starting the agent you should supply pointers
     75 to non-volatile memory for sysContact, sysLocation,
     76 and snmpEnableAuthenTraps. You can do this by calling
     77 
     78 snmp_set_syscontact()
     79 snmp_set_syslocation()
     80 snmp_set_snmpenableauthentraps()
     81 
     82 Additionally you may want to set
     83 
     84 snmp_set_sysdescr()
     85 snmp_set_sysobjid() (if you have a private MIB)
     86 snmp_set_sysname()
     87 
     88 Also before starting the agent you need to setup
     89 one or more trap destinations using these calls:
     90 
     91 snmp_trap_dst_enable();
     92 snmp_trap_dst_ip_set();
     93 
     94 In the lwIP initialisation sequence call snmp_init() just after
     95 the call to udp_init().
     96 
     97 Exactly every 10 msec the SNMP uptime timestamp must be updated with
     98 snmp_inc_sysuptime(). You should call this from a timer interrupt
     99 or a timer signal handler depending on your runtime environment.
    100 
    101 An alternative way to update the SNMP uptime timestamp is to do a call like
    102 snmp_add_sysuptime(100) each 1000ms (which is bigger "step", but call to
    103 a lower frequency). Another one is to not call snmp_inc_sysuptime() or
    104 snmp_add_sysuptime(), and to define the SNMP_GET_SYSUPTIME(sysuptime) macro.
    105 This one is undefined by default in mib2.c. SNMP_GET_SYSUPTIME is called inside
    106 snmp_get_sysuptime(u32_t *value), and enable to change "sysuptime" value only
    107 when it's queried (any function which need "sysuptime" have to call
    108 snmp_get_sysuptime).
    109 
    110 
    111 3 Private MIBs
    112 ==============
    113 
    114 If want to extend the agent with your own private MIB you'll need to
    115 add the following define to your local lwipopts.h:
    116 
    117 #define SNMP_PRIVATE_MIB        1
    118 
    119 You must provide the private_mib.h and associated files yourself.
    120 Note we don't have a "MIB compiler" that generates C source from a MIB,
    121 so you're required to do some serious coding if you enable this!
    122 
    123 Note the lwIP enterprise ID (26381) is assigned to the lwIP project,
    124 ALL OBJECT IDENTIFIERS LIVING UNDER THIS ID ARE ASSIGNED BY THE lwIP
    125 MAINTAINERS!
    126 
    127 If you need to create your own private MIB you'll need
    128 to apply for your own enterprise ID with IANA: http://www.iana.org/numbers.html 
    129 
    130 You can set it by passing a struct snmp_obj_id to the agent
    131 using snmp_set_sysobjid(&my_object_id), just before snmp_init().
    132 
    133 Note the object identifiers for thes MIB-2 and your private MIB
    134 tree must be kept in sorted ascending (lexicographical) order.
    135 This to ensure correct getnext operation.
    136 
    137 An example for a private MIB is part of the "minimal Unix" project:
    138 contrib/ports/unix/proj/minimal/lwip_prvmib.c
    139 
    140 The next chapter gives a more detailed description of the
    141 MIB-2 tree and the optional private MIB.
    142 
    143 4 The Gory Details
    144 ==================
    145 
    146 4.0 Object identifiers and the MIB tree.
    147 
    148 We have three distinct parts for all object identifiers:
    149 
    150 The prefix
    151   .iso.org.dod.internet
    152 
    153 the middle part 
    154   .mgmt.mib-2.ip.ipNetToMediaTable.ipNetToMediaEntry.ipNetToMediaPhysAddress
    155 
    156 and the index part
    157   .1.192.168.0.1
    158 
    159 Objects located above the .internet hierarchy aren't supported.
    160 Currently only the .mgmt sub-tree is available and
    161 when the SNMP_PRIVATE_MIB is enabled the .private tree
    162 becomes available too.
    163 
    164 Object identifiers from incoming requests are checked
    165 for a matching prefix, middle part and index part
    166 or are expanded(*) for GetNext requests with short
    167 or inexisting names in the request.
    168 (* we call this "expansion" but this also
    169 resembles the "auto-completion" operation)
    170 
    171 The middle part is usually located in ROM (const)
    172 to preserve precious RAM on small microcontrollers.
    173 However RAM location is possible for a dynamically
    174 changing private tree.
    175 
    176 The index part is handled by functions which in
    177 turn use dynamically allocated index trees from RAM.
    178 These trees are updated by e.g. the etharp code
    179 when new entries are made or removed form the ARP cache.
    180 
    181 /** @todo more gory details */
    182