From c5bd3f5e3bee0475d6fd339e6eff717946083bad Mon Sep 17 00:00:00 2001
From: christiaans <christiaans>
Date: Thu, 7 Sep 2006 14:46:41 +0000
Subject: [PATCH] Documented TRAP destination setup.

---
 doc/snmp_agent.txt | 83 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 72 insertions(+), 11 deletions(-)

diff --git a/doc/snmp_agent.txt b/doc/snmp_agent.txt
index b08c26ee..2c426368 100644
--- a/doc/snmp_agent.txt
+++ b/doc/snmp_agent.txt
@@ -6,8 +6,8 @@ This is a brief introduction how to use and configure the SNMP agent.
 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.
@@ -18,6 +18,23 @@ SNMPv1 per RFC1157
 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.
@@ -30,8 +47,8 @@ Large SNMP message support
   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:
@@ -44,8 +61,8 @@ and some snmp headers in lwip/src/include/lwip to your makefile.
 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.
@@ -64,6 +81,12 @@ snmp_set_sysdescr()
 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().
 
@@ -72,8 +95,8 @@ snmp_inc_sysuptime(). You should call this from a timer interrupt
 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:
@@ -94,9 +117,47 @@ to apply for your own enterprise ID with IANA: http://www.iana.org/numbers.html
 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.
 
-todo
+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.
+
+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.