1SNMPv1 agent for lwIP 2 3Author: Christiaan Simons 4 5This is a brief introduction how to use and configure the SNMP agent. 6Note the agent uses the raw-API UDP interface so you may also want to 7read rawapi.txt to gain a better understanding of the SNMP message handling. 8 90 Agent Capabilities 10==================== 11 12SNMPv1 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 22MIB 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 43Loading 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 47Large 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 541 Building the Agent 55==================== 56 57First of all you'll need to add the following define 58to your local lwipopts.h: 59 60#define LWIP_SNMP 1 61 62and add the source files in lwip/src/core/snmp 63and some snmp headers in lwip/src/include/lwip to your makefile. 64 65Note you'll might need to adapt you network driver to update 66the mib2 variables for your interface. 67 682 Running the Agent 69=================== 70 71The following function calls must be made in your program to 72actually get the SNMP agent running. 73 74Before starting the agent you should supply pointers 75to non-volatile memory for sysContact, sysLocation, 76and snmpEnableAuthenTraps. You can do this by calling 77 78snmp_set_syscontact() 79snmp_set_syslocation() 80snmp_set_snmpenableauthentraps() 81 82Additionally you may want to set 83 84snmp_set_sysdescr() 85snmp_set_sysobjid() (if you have a private MIB) 86snmp_set_sysname() 87 88Also before starting the agent you need to setup 89one or more trap destinations using these calls: 90 91snmp_trap_dst_enable(); 92snmp_trap_dst_ip_set(); 93 94In the lwIP initialisation sequence call snmp_init() just after 95the call to udp_init(). 96 97Exactly every 10 msec the SNMP uptime timestamp must be updated with 98snmp_inc_sysuptime(). You should call this from a timer interrupt 99or a timer signal handler depending on your runtime environment. 100 101An alternative way to update the SNMP uptime timestamp is to do a call like 102snmp_add_sysuptime(100) each 1000ms (which is bigger "step", but call to 103a lower frequency). Another one is to not call snmp_inc_sysuptime() or 104snmp_add_sysuptime(), and to define the SNMP_GET_SYSUPTIME(sysuptime) macro. 105This one is undefined by default in mib2.c. SNMP_GET_SYSUPTIME is called inside 106snmp_get_sysuptime(u32_t *value), and enable to change "sysuptime" value only 107when it's queried (any function which need "sysuptime" have to call 108snmp_get_sysuptime). 109 110 1113 Private MIBs 112============== 113 114If want to extend the agent with your own private MIB you'll need to 115add the following define to your local lwipopts.h: 116 117#define SNMP_PRIVATE_MIB 1 118 119You must provide the private_mib.h and associated files yourself. 120Note we don't have a "MIB compiler" that generates C source from a MIB, 121so you're required to do some serious coding if you enable this! 122 123Note the lwIP enterprise ID (26381) is assigned to the lwIP project, 124ALL OBJECT IDENTIFIERS LIVING UNDER THIS ID ARE ASSIGNED BY THE lwIP 125MAINTAINERS! 126 127If you need to create your own private MIB you'll need 128to apply for your own enterprise ID with IANA: http://www.iana.org/numbers.html 129 130You can set it by passing a struct snmp_obj_id to the agent 131using snmp_set_sysobjid(&my_object_id), just before snmp_init(). 132 133Note the object identifiers for thes MIB-2 and your private MIB 134tree must be kept in sorted ascending (lexicographical) order. 135This to ensure correct getnext operation. 136 137An example for a private MIB is part of the "minimal Unix" project: 138contrib/ports/unix/proj/minimal/lwip_prvmib.c 139 140The next chapter gives a more detailed description of the 141MIB-2 tree and the optional private MIB. 142 1434 The Gory Details 144================== 145 1464.0 Object identifiers and the MIB tree. 147 148We have three distinct parts for all object identifiers: 149 150The prefix 151 .iso.org.dod.internet 152 153the middle part 154 .mgmt.mib-2.ip.ipNetToMediaTable.ipNetToMediaEntry.ipNetToMediaPhysAddress 155 156and the index part 157 .1.192.168.0.1 158 159Objects located above the .internet hierarchy aren't supported. 160Currently only the .mgmt sub-tree is available and 161when the SNMP_PRIVATE_MIB is enabled the .private tree 162becomes available too. 163 164Object identifiers from incoming requests are checked 165for a matching prefix, middle part and index part 166or are expanded(*) for GetNext requests with short 167or inexisting names in the request. 168(* we call this "expansion" but this also 169resembles the "auto-completion" operation) 170 171The middle part is usually located in ROM (const) 172to preserve precious RAM on small microcontrollers. 173However RAM location is possible for a dynamically 174changing private tree. 175 176The index part is handled by functions which in 177turn use dynamically allocated index trees from RAM. 178These trees are updated by e.g. the etharp code 179when new entries are made or removed form the ARP cache. 180 181/** @todo more gory details */ 182