a82212bd36e1074408974b466798b9966bbaf49bvboxsyncSNMPv1 agent for lwIP
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncAuthor: Christiaan Simons
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncThis is a brief introduction how to use and configure the SNMP agent.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncNote the agent uses the raw-API UDP interface so you may also want to
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncread rawapi.txt to gain a better understanding of the SNMP message handling.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync0 Agent Capabilities
a82212bd36e1074408974b466798b9966bbaf49bvboxsync====================
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncSNMPv1 per RFC1157
a82212bd36e1074408974b466798b9966bbaf49bvboxsync This is an old(er) standard but is still widely supported.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync For SNMPv2c and v3 have a greater complexity and need many
a82212bd36e1074408974b466798b9966bbaf49bvboxsync more lines of code. IMHO this breaks the idea of "lightweight IP".
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Note the S in SNMP stands for "Simple". Note that "Simple" is
a82212bd36e1074408974b466798b9966bbaf49bvboxsync relative. SNMP is simple compared to the complex ISO network
a82212bd36e1074408974b466798b9966bbaf49bvboxsync management protocols CMIP (Common Management Information Protocol)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync and CMOT (CMip Over Tcp).
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncMIB II per RFC1213
a82212bd36e1074408974b466798b9966bbaf49bvboxsync The standard lwIP stack management information base.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync This is a required MIB, so this is always enabled.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync When builing lwIP without TCP, the mib-2.tcp group is omitted.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync The groups EGP, CMOT and transmission are disabled by default.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Most mib-2 objects are not writable except:
a82212bd36e1074408974b466798b9966bbaf49bvboxsync sysName, sysLocation, sysContact, snmpEnableAuthenTraps.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Writing to or changing the ARP and IP address and route
a82212bd36e1074408974b466798b9966bbaf49bvboxsync tables is not possible.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Note lwIP has a very limited notion of IP routing. It currently
a82212bd36e1074408974b466798b9966bbaf49bvboxsync doen't have a route table and doesn't have a notion of the U,G,H flags.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Instead lwIP uses the interface list with only one default interface
a82212bd36e1074408974b466798b9966bbaf49bvboxsync acting as a single gateway interface (G) for the default route.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync The agent returns a "virtual table" with the default route 0.0.0.0
a82212bd36e1074408974b466798b9966bbaf49bvboxsync for the default interface and network routes (no H) for each
a82212bd36e1074408974b466798b9966bbaf49bvboxsync network interface in the netif_list.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync All routes are considered to be up (U).
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncLoading additional MIBs
a82212bd36e1074408974b466798b9966bbaf49bvboxsync MIBs can only be added in compile-time, not in run-time.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync There is no MIB compiler thus additional MIBs must be hand coded.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncLarge SNMP message support
a82212bd36e1074408974b466798b9966bbaf49bvboxsync The packet decoding and encoding routines are designed
a82212bd36e1074408974b466798b9966bbaf49bvboxsync to use pbuf-chains. Larger payloads then the minimum
a82212bd36e1074408974b466798b9966bbaf49bvboxsync SNMP requirement of 484 octets are supported if the
a82212bd36e1074408974b466798b9966bbaf49bvboxsync PBUF_POOL_SIZE and IP_REASS_BUFSIZE are set to match your
a82212bd36e1074408974b466798b9966bbaf49bvboxsync local requirement.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync1 Building the Agent
a82212bd36e1074408974b466798b9966bbaf49bvboxsync====================
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncFirst of all you'll need to add the following define
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncto your local lwipopts.h:
a82212bd36e1074408974b466798b9966bbaf49bvboxsync#define LWIP_SNMP 1
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncand add the source files in lwip/src/core/snmp
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncand some snmp headers in lwip/src/include/lwip to your makefile.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncNote you'll might need to adapt you network driver to update
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncthe mib2 variables for your interface.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync2 Running the Agent
a82212bd36e1074408974b466798b9966bbaf49bvboxsync===================
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncThe following function calls must be made in your program to
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncactually get the SNMP agent running.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncBefore starting the agent you should supply pointers
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncto non-volatile memory for sysContact, sysLocation,
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncand snmpEnableAuthenTraps. You can do this by calling
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsnmp_set_syscontact()
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsnmp_set_syslocation()
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsnmp_set_snmpenableauthentraps()
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncAdditionally you may want to set
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsnmp_set_sysdescr()
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsnmp_set_sysobjid() (if you have a private MIB)
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsnmp_set_sysname()
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncAlso before starting the agent you need to setup
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncone or more trap destinations using these calls:
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsnmp_trap_dst_enable();
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsnmp_trap_dst_ip_set();
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncIn the lwIP initialisation sequence call snmp_init() just after
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncthe call to udp_init().
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncExactly every 10 msec the SNMP uptime timestamp must be updated with
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsnmp_inc_sysuptime(). You should call this from a timer interrupt
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncor a timer signal handler depending on your runtime environment.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync3 Private MIBs
a82212bd36e1074408974b466798b9966bbaf49bvboxsync==============
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncIf want to extend the agent with your own private MIB you'll need to
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncadd the following define to your local lwipopts.h:
a82212bd36e1074408974b466798b9966bbaf49bvboxsync#define SNMP_PRIVATE_MIB 1
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncYou must provide the private_mib.h and associated files yourself.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncNote we don't have a "MIB compiler" that generates C source from a MIB,
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncso you're required to do some serious coding if you enable this!
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncNote the lwIP enterprise ID (26381) is assigned to the lwIP project,
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncALL OBJECT IDENTIFIERS LIVING UNDER THIS ID ARE ASSIGNED BY THE lwIP
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncMAINTAINERS!
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncIf you need to create your own private MIB you'll need
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncto apply for your own enterprise ID with IANA: http://www.iana.org/numbers.html
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncYou can set it by passing a struct snmp_obj_id to the agent
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncusing snmp_set_sysobjid(&my_object_id), just before snmp_init().
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncNote the object identifiers for thes MIB-2 and your private MIB
a82212bd36e1074408974b466798b9966bbaf49bvboxsynctree must be kept in sorted ascending (lexicographical) order.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncThis to ensure correct getnext operation.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncAn example for a private MIB is part of the "minimal Unix" project:
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncThe next chapter gives a more detailed description of the
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncMIB-2 tree and the optional private MIB.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync4 The Gory Details
a82212bd36e1074408974b466798b9966bbaf49bvboxsync==================
a82212bd36e1074408974b466798b9966bbaf49bvboxsync4.0 Object identifiers and the MIB tree.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncWe have three distinct parts for all object identifiers:
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncthe middle part
a82212bd36e1074408974b466798b9966bbaf49bvboxsync .mgmt.mib-2.ip.ipNetToMediaTable.ipNetToMediaEntry.ipNetToMediaPhysAddress
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncand the index part
a82212bd36e1074408974b466798b9966bbaf49bvboxsync .1.192.168.0.1
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncObjects located above the .internet hierarchy aren't supported.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncCurrently only the .mgmt sub-tree is available and
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncwhen the SNMP_PRIVATE_MIB is enabled the .private tree
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncbecomes available too.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncObject identifiers from incoming requests are checked
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncfor a matching prefix, middle part and index part
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncor are expanded(*) for GetNext requests with short
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncor inexisting names in the request.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync(* we call this "expansion" but this also
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncresembles the "auto-completion" operation)
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncThe middle part is usually located in ROM (const)
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncto preserve precious RAM on small microcontrollers.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncHowever RAM location is possible for an dynamically
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncchanging private tree.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncThe index part is handled by functions which in
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncturn use dynamically allocated index trees from RAM.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncThese trees are updated by e.g. the etharp code
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncwhen new entries are made or removed form the ARP cache.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync/** @todo more gory details */