Note the agent uses the raw-API UDP interface so you may also want to
read rawapi.txt to gain a better understanding of the SNMP messages handling.
-Agent capabilities
-==================
+0 Agent capabilities
+====================
SNMPv1 per RFC1157
This is an old(er) standard but is still widely supported.
MIB II per RFC1213
The standard lwIP stack management information base.
This is a required MIB, so this is always enabled.
+ When builing lwIP without TCP, the mib-2.tcp group is omitted.
+ The groups EGP, CMOT and transmission are disabled by default.
+
+ Most mib-2 objects are not writable except:
+ sysName, sysLocation, sysContact, snmpEnableAuthenTraps.
+ Writing to or changing the ARP and IP address and route
+ tables is not possible.
+
+ Note lwIP has a very limited notion of IP routing. It currently
+ doen't have a route table and doesn't have a notion of the U,G,H flags.
+ Instead lwIP uses the interface list with only one default interface
+ acting as a single gateway interface (G) for the default route.
+
+ The agent returns a "virtual table" with the default route 0.0.0.0
+ for the default interface and network routes (no H) for each
+ network interface in the netif_list.
+ All routes are considered to be up (U).
Loading additional MIBs
MIBs can only be added in compile-time, not in run-time.
PBUF_POOL_SIZE and IP_REASS_BUFSIZE are set to match your
local requirement.
-Building the agent
-==================
+1 Building the agent
+====================
First of all you'll need to add the following define
to your local lwipopts.h:
Note you'll might need to adapt you network driver to update
the mib2 variables for your interface.
-Running the agent
-=================
+2 Running the agent
+===================
The following function calls must be made in your program to
actually get the SNMP agent running.
snmp_set_sysobjid() (if you have a private MIB)
snmp_set_sysname()
+Also before starting the agent you need to setup
+one or more trap destinations using these calls:
+
+snmp_trap_dst_enable();
+snmp_trap_dst_ip_set();
+
In the lwIP initialisation sequence call snmp_init() just after
the call to udp_init().
or a timer signal handler depending on your runtime environment.
-Private MIBs
-============
+3 Private MIBs
+==============
If want to extend the agent with your own private MIB you'll need to
add the following define to your local lwipopts.h:
You can set it by passing a struct snmp_obj_id to the agent
using snmp_set_sysobjid(&my_object_id), just before snmp_init().
-Agent internals [advanced use]
-==============================
+Note the object identifiers for thes MIB-2 and your private MIB
+tree must be kept in sorted ascending (lexicographical) order.
+This to ensure correct getnext operation.
+
+The next chapter gives a more detailed description of the
+MIB-2 tree and the optional private MIB.
+
+4 Agent internals
+=================
+
+4.0 Object identifiers and the MIB tree.
+
+We have three distinct parts for all object identifiers:
+
+The prefix
+ .iso.org.dod.internet
+
+the middle part
+ .mgmt.mib-2.ip.ipNetToMediaTable.ipNetToMediaEntry.ipNetToMediaPhysAddress
+
+and the index part
+ .1.192.168.0.1
+
+Objects located above the .internet hierarchy aren't supported.
+Currently only the .mgmt sub-tree is available and
+when the SNMP_PRIVATE_MIB is enabled the .private tree
+becomes available too.
-todo
+Object identifiers from incoming requests are checked
+for a matching prefix, middle part and index part
+or are expanded(*) for GetNext requests with short
+or inexisting names in the request.
+(* we call this "expansion" but this also
+resembles the "auto-completion" operation)
+The middle part is usually located in ROM (const)
+to preserve precious RAM on small microcontrollers.
+However RAM location is possible for an dynamically
+changing private tree.
+The index part is handled by functions which in
+turn use dynamically allocated index trees from RAM.
+These trees are updated by e.g. the etharp code
+when new entries are made or removed form the ARP cache.