mirror of
https://github.com/lwip-tcpip/lwip.git
synced 2024-11-19 05:10:40 +00:00
Integrate snmp_agent.txt in doxygen documentation, delete outdated file
This commit is contained in:
Dirk Ziegelmeier
parent
eb3261d6e0
commit
aece68639a
@ -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 */
|
|
||||||
@ -43,6 +43,86 @@
|
|||||||
* whithout IPv6 statistics (TODO).\n
|
* whithout IPv6 statistics (TODO).\n
|
||||||
* Work on SNMPv3 has started, but is not finished.
|
* 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
|
* @defgroup snmp_core Core
|
||||||
* @ingroup snmp
|
* @ingroup snmp
|
||||||
*
|
*
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user