OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [freertos-6.1.1/] [Demo/] [Common/] [ethernet/] [lwIP_130/] [doc/] [snmp_agent.txt] - Blame information for rev 606

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 606 jeremybenn
SNMPv1 agent for lwIP
2
 
3
Author: Christiaan Simons
4
 
5
This is a brief introduction how to use and configure the SNMP agent.
6
Note the agent uses the raw-API UDP interface so you may also want to
7
read rawapi.txt to gain a better understanding of the SNMP message handling.
8
 
9
 
10
====================
11
 
12
SNMPv1 per RFC1157
13
  This is an old(er) standard but is still widely supported.
14
  For SNMPv2c and v3 have a greater complexity and need many
15
  more lines of code. IMHO this breaks the idea of "lightweight IP".
16
 
17
  Note the S in SNMP stands for "Simple". Note that "Simple" is
18
  relative. SNMP is simple compared to the complex ISO network
19
  management protocols CMIP (Common Management Information Protocol)
20
  and CMOT (CMip Over Tcp).
21
 
22
MIB II per RFC1213
23
  The standard lwIP stack management information base.
24
  This is a required MIB, so this is always enabled.
25
  When builing lwIP without TCP, the mib-2.tcp group is omitted.
26
  The groups EGP, CMOT and transmission are disabled by default.
27
 
28
  Most mib-2 objects are not writable except:
29
  sysName, sysLocation, sysContact, snmpEnableAuthenTraps.
30
  Writing to or changing the ARP and IP address and route
31
  tables is not possible.
32
 
33
  Note lwIP has a very limited notion of IP routing. It currently
34
  doen't have a route table and doesn't have a notion of the U,G,H flags.
35
  Instead lwIP uses the interface list with only one default interface
36
  acting as a single gateway interface (G) for the default route.
37
 
38
  The agent returns a "virtual table" with the default route 0.0.0.0
39
  for the default interface and network routes (no H) for each
40
  network interface in the netif_list.
41
  All routes are considered to be up (U).
42
 
43
Loading additional MIBs
44
  MIBs can only be added in compile-time, not in run-time.
45
  There is no MIB compiler thus additional MIBs must be hand coded.
46
 
47
Large SNMP message support
48
  The packet decoding and encoding routines are designed
49
  to use pbuf-chains. Larger payloads then the minimum
50
  SNMP requirement of 484 octets are supported if the
51
  PBUF_POOL_SIZE and IP_REASS_BUFSIZE are set to match your
52
  local requirement.
53
 
54
1 Building the Agent
55
====================
56
 
57
First of all you'll need to add the following define
58
to your local lwipopts.h:
59
 
60
#define LWIP_SNMP               1
61
 
62
and add the source files in lwip/src/core/snmp
63
and some snmp headers in lwip/src/include/lwip to your makefile.
64
 
65
Note you'll might need to adapt you network driver to update
66
the mib2 variables for your interface.
67
 
68
2 Running the Agent
69
===================
70
 
71
The following function calls must be made in your program to
72
actually get the SNMP agent running.
73
 
74
Before starting the agent you should supply pointers
75
to non-volatile memory for sysContact, sysLocation,
76
and snmpEnableAuthenTraps. You can do this by calling
77
 
78
snmp_set_syscontact()
79
snmp_set_syslocation()
80
snmp_set_snmpenableauthentraps()
81
 
82
Additionally you may want to set
83
 
84
snmp_set_sysdescr()
85
snmp_set_sysobjid() (if you have a private MIB)
86
snmp_set_sysname()
87
 
88
Also before starting the agent you need to setup
89
one or more trap destinations using these calls:
90
 
91
snmp_trap_dst_enable();
92
snmp_trap_dst_ip_set();
93
 
94
In the lwIP initialisation sequence call snmp_init() just after
95
the call to udp_init().
96
 
97
Exactly every 10 msec the SNMP uptime timestamp must be updated with
98
snmp_inc_sysuptime(). You should call this from a timer interrupt
99
or a timer signal handler depending on your runtime environment.
100
 
101
An alternative way to update the SNMP uptime timestamp is to do a call like
102
snmp_add_sysuptime(100) each 1000ms (which is bigger "step", but call to
103
a lower frequency). Another one is to not call snmp_inc_sysuptime() or
104
snmp_add_sysuptime(), and to define the SNMP_GET_SYSUPTIME(sysuptime) macro.
105
This one is undefined by default in mib2.c. SNMP_GET_SYSUPTIME is called inside
106
snmp_get_sysuptime(u32_t *value), and enable to change "sysuptime" value only
107
when it's queried (any function which need "sysuptime" have to call
108
snmp_get_sysuptime).
109
 
110
 
111
3 Private MIBs
112
==============
113
 
114
If want to extend the agent with your own private MIB you'll need to
115
add the following define to your local lwipopts.h:
116
 
117
#define SNMP_PRIVATE_MIB        1
118
 
119
You must provide the private_mib.h and associated files yourself.
120
Note we don't have a "MIB compiler" that generates C source from a MIB,
121
so you're required to do some serious coding if you enable this!
122
 
123
Note the lwIP enterprise ID (26381) is assigned to the lwIP project,
124
ALL OBJECT IDENTIFIERS LIVING UNDER THIS ID ARE ASSIGNED BY THE lwIP
125
MAINTAINERS!
126
 
127
If you need to create your own private MIB you'll need
128
to apply for your own enterprise ID with IANA: http://www.iana.org/numbers.html
129
 
130
You can set it by passing a struct snmp_obj_id to the agent
131
using snmp_set_sysobjid(&my_object_id), just before snmp_init().
132
 
133
Note the object identifiers for thes MIB-2 and your private MIB
134
tree must be kept in sorted ascending (lexicographical) order.
135
This to ensure correct getnext operation.
136
 
137
An example for a private MIB is part of the "minimal Unix" project:
138
contrib/ports/unix/proj/minimal/lwip_prvmib.c
139
 
140
The next chapter gives a more detailed description of the
141
MIB-2 tree and the optional private MIB.
142
 
143
4 The Gory Details
144
==================
145
 
146
4.0 Object identifiers and the MIB tree.
147
 
148
We have three distinct parts for all object identifiers:
149
 
150
The prefix
151
  .iso.org.dod.internet
152
 
153
the middle part
154
  .mgmt.mib-2.ip.ipNetToMediaTable.ipNetToMediaEntry.ipNetToMediaPhysAddress
155
 
156
and the index part
157
  .1.192.168.0.1
158
 
159
Objects located above the .internet hierarchy aren't supported.
160
Currently only the .mgmt sub-tree is available and
161
when the SNMP_PRIVATE_MIB is enabled the .private tree
162
becomes available too.
163
 
164
Object identifiers from incoming requests are checked
165
for a matching prefix, middle part and index part
166
or are expanded(*) for GetNext requests with short
167
or inexisting names in the request.
168
(* we call this "expansion" but this also
169
resembles the "auto-completion" operation)
170
 
171
The middle part is usually located in ROM (const)
172
to preserve precious RAM on small microcontrollers.
173
However RAM location is possible for an dynamically
174
changing private tree.
175
 
176
The index part is handled by functions which in
177
turn use dynamically allocated index trees from RAM.
178
These trees are updated by e.g. the etharp code
179
when new entries are made or removed form the ARP cache.
180
 
181
/** @todo more gory details */

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.