From aece68639a46ad324fec4f29cf476e138a1077cb Mon Sep 17 00:00:00 2001 From: Dirk Ziegelmeier Date: Wed, 27 Jul 2016 18:58:28 +0200 Subject: [PATCH] Integrate snmp_agent.txt in doxygen documentation, delete outdated file --- doc/snmp_agent.txt | 168 -------------------------------------- src/apps/snmp/snmp_core.c | 80 ++++++++++++++++++ 2 files changed, 80 insertions(+), 168 deletions(-) delete mode 100644 doc/snmp_agent.txt diff --git a/doc/snmp_agent.txt b/doc/snmp_agent.txt deleted file mode 100644 index 224a986d..00000000 --- a/doc/snmp_agent.txt +++ /dev/null @@ -1,168 +0,0 @@ -* THIS DOCUMENTATION IS OUTDATED * -It was written before the agent was largely rewritten in 2015. - -SNMPv1 agent for lwIP - -Author: Christiaan Simons - -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 message handling. - -0 Agent Capabilities -==================== - -SNMPv1 per RFC1157 - This is an old(er) standard but is still widely supported. - For SNMPv2c and v3 have a greater complexity and need many - more lines of code. IMHO this breaks the idea of "lightweight IP". - - Note the S in SNMP stands for "Simple". Note that "Simple" is - relative. SNMP is simple compared to the complex ISO network - management protocols CMIP (Common Management Information Protocol) - and CMOT (CMip Over Tcp). - -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. - There is no MIB compiler thus additional MIBs must be hand coded. - -Large SNMP message support - The packet decoding and encoding routines are designed - to use pbuf-chains. Larger payloads than the minimum - SNMP requirement of 484 octets are supported if the - PBUF_POOL_SIZE and IP_REASS_BUFSIZE are set to match your - local requirement. - -1 Building the Agent -==================== - -First of all you'll need to add the following define -to your local lwipopts.h: - -#define LWIP_SNMP 1 - -and add the source files in lwip/src/core/snmp -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. - -2 Running the Agent -=================== - -The following function calls must be made in your program to -actually get the SNMP agent running. - -Before starting the agent you should supply pointers -to non-volatile memory for sysContact, sysLocation, -and snmpEnableAuthenTraps. You can do this by calling - -snmp_set_syscontact() -snmp_set_syslocation() -snmp_set_snmpenableauthentraps() - -Additionally you may want to set - -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(); - - -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: - -#define SNMP_PRIVATE_MIB 1 - -You must provide the private_mib.h and associated files yourself. -Note we don't have a "MIB compiler" that generates C source from a MIB, -so you're required to do some serious coding if you enable this! - -Note the lwIP enterprise ID (26381) is assigned to the lwIP project, -ALL OBJECT IDENTIFIERS LIVING UNDER THIS ID ARE ASSIGNED BY THE lwIP -MAINTAINERS! - -If you need to create your own private MIB you'll need -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(). - -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. - -An example for a private MIB is part of the "minimal Unix" project: -contrib/ports/unix/proj/minimal/lwip_prvmib.c - -The next chapter gives a more detailed description of the -MIB-2 tree and the optional private MIB. - -4 The Gory Details -================== - -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 a 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. - -/** @todo more gory details */ diff --git a/src/apps/snmp/snmp_core.c b/src/apps/snmp/snmp_core.c index 328b0881..5c8b42fe 100644 --- a/src/apps/snmp/snmp_core.c +++ b/src/apps/snmp/snmp_core.c @@ -42,7 +42,87 @@ * (interfaces, UDP, TCP, SNMP, ICMP, SYSTEM). IP MIB is an older version * whithout IPv6 statistics (TODO).\n * Work on SNMPv3 has started, but is not finished. + * + * 0 Agent Capabilities + * ==================== * + * SNMPv1 per RFC1157 and SNMPv2c per RFC 3416 + * ------------------------------------------- + * Note the S in SNMP stands for "Simple". Note that "Simple" is + * relative. SNMP is simple compared to the complex ISO network + * management protocols CMIP (Common Management Information Protocol) + * and CMOT (CMip Over Tcp). + * + * MIB II + * ------ + * The standard lwIP stack management information base. + * This is a required MIB, so this is always enabled. + * 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. + * + * + * 1 Building the Agent + * ==================== + * First of all you'll need to add the following define + * to your local lwipopts.h: + * \#define LWIP_SNMP 1 + * + * and add the source files your makefile. + * + * Note you'll might need to adapt you network driver to update + * the mib2 variables for your interface. + * + * 2 Running the Agent + * =================== + * The following function calls must be made in your program to + * actually get the SNMP agent running. + * + * Before starting the agent you should supply pointers + * for sysContact, sysLocation, and snmpEnableAuthenTraps. + * You can do this by calling + * + * - snmp_mib2_set_syscontact() + * - snmp_mib2_set_syslocation() + * - snmp_set_auth_traps_enabled() + * + * You can register a callback which is called on successful write access: + * snmp_set_write_callback(). + * + * Additionally you may want to set + * + * - snmp_mib2_set_sysdescr() + * - snmp_set_device_enterprise_oid() + * - snmp_mib2_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() + * + * If you need more than MIB2, set the MIBs you want to use + * by snmp_set_mibs(). + * + * Finally, enable the agent by calling snmp_init() + * * @defgroup snmp_core Core * @ingroup snmp *