Dirk Ziegelmeier
10 years ago
2 changed files with 80 additions and 168 deletions
@ -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 */ |
||||
Loading…
Reference in new issue