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 */
|
||||
@ -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
|
||||
*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user