1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
|
.\"
.\" Copyright (c) 2001-2003
.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
.\" All rights reserved.
.\"
.\" Author: Harti Brandt <harti@freebsd.org>
.\"
.\" Redistribution of this software and documentation and use in source and
.\" binary forms, with or without modification, are permitted provided that
.\" the following conditions are met:
.\"
.\" 1. Redistributions of source code or documentation must retain the above
.\" copyright notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the Institute nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY FRAUNHOFER FOKUS
.\" AND ITS CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
.\" FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
.\" FRAUNHOFER FOKUS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
.\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Begemot: bsnmp/snmp_mibII/snmp_mibII.3,v 1.2 2003/12/03 10:01:19 hbb Exp $
.\"
.Dd August 19, 2002
.Dt snmp_mibII 3
.Os
.Sh NAME
.Nm mibif_notify_f ,
.Nm mib_netsock ,
.Nm mib_if_set_dyn ,
.Nm mib_refresh_iflist ,
.Nm mib_find_if ,
.Nm mib_find_if_sys ,
.Nm mib_find_if_name ,
.Nm mib_first_if ,
.Nm mib_next_if ,
.Nm mib_register_newif ,
.Nm mib_unregister_newif ,
.Nm mib_fetch_ifmib ,
.Nm mib_if_admin ,
.Nm mib_find_ifa ,
.Nm mib_first_ififa ,
.Nm mib_next_ififa ,
.Nm mib_ifstack_create ,
.Nm mib_ifstack_delete ,
.Nm mib_find_rcvaddr ,
.Nm mib_rcvaddr_create ,
.Nm mib_rcvaddr_delete ,
.Nm mibif_notify ,
.Nm mibif_unnotify
.Nd "mib-2 module for snmpd.
.Sh LIBRARY
.Pq begemotSnmpdModulePath."mibII" = "/usr/local/lib/snmp_mibII.so"
.Sh SYNOPSIS
.In bsnmp/snmpmod.h
.In bsnmp/snmp_mibII.h
.Ft typedef void
.Fn (*mibif_notify_f) "struct mibif *ifp" "enum mibif_notify event" "void *uarg"
.Vt extern int mib_netsock ;
.Ft void
.Fn mib_if_set_dyn "const char *ifname"
.Ft void
.Fn mib_refresh_iflist "void"
.Ft struct mibif *
.Fn mib_find_if "u_int ifindex"
.Ft struct mibif *
.Fn mib_find_if_sys "u_int sysindex"
.Ft struct mibif *
.Fn mib_find_if_name "const char *ifname"
.Ft struct mibif *
.Fn mib_first_if "void"
.Ft struct mibif *
.Fn mib_next_if "const struct mibif *ifp"
.Ft int
.Fn mib_register_newif "int (*func)(struct mibif *)" "const struct lmodule *mod"
.Ft void
.Fn mib_unregister_newif "const struct lmodule *mod"
.Ft int
.Fn mib_fetch_ifmib "struct mibif *ifp"
.Ft int
.Fn mib_if_admin "struct mibif *ifp" "int up"
.Ft struct mibifa *
.Fn mib_find_ifa "struct in_addr ipa"
.Ft struct mibifa *
.Fn mib_first_ififa "const struct mibif *ifp"
.Ft struct mibifa *
.Fn mib_next_ififa "struct mibifa *ifa"
.Ft int
.Fn mib_ifstack_create "const struct mibif *lower" "const struct mibif *upper"
.Ft void
.Fn mib_ifstack_delete "const struct mibif *lower" "const struct mibif *upper"
.Ft struct mibrcvaddr *
.Fn mib_find_rcvaddr "u_int ifindex" "const u_char *addr" "size_t addrlen"
.Ft struct mibrcvaddr *
.Fn mib_rcvaddr_create "struct mibif *ifp" "const u_char *addr" "size_t addrlen"
.Ft void
.Fn mib_rcvaddr_delete "struct mibrcvaddr *addr"
.Ft void *
.Fn mibif_notify "struct mibif *ifp" "const struct lmodule *mod" "mibif_notify_f func" "void *uarg"
.Ft void
.Fn mibif_unnotify "void *reg"
.Sh DESCRIPTION
The
.Nm snmp_mibII
module implements parts of the internet standard MIB-2. Most of the relevant
MIBs are implemented. Some of the tables are restricted to be read-only
instead of read-write. The exact current implementation can be found in
.Pa /usr/local/include/bsnmp/mibII_tree.def .
The module also exports a number of functions and global variables for use
by other modules, that need to handle network interfaces. This man page describes
these functions.
.Ss DIRECT NETWORK ACCESS
The
.Nm
module opens a socket that is used to execute all network related
.Xr ioctl 2
functions. This socket is globally available under the name
.Va mib_netsock .
.Ss NETWORK INTERFACES
The
.Nm
module handles a list of all currently existing network interfaces. It allows
other modules to handle their own interface lists with special information
by providing a mechanism to register to events that change the interface list
(see below). The basic data structure is the interface structure:
.Bd -literal -offset indent
struct mibif {
TAILQ_ENTRY(mibif) link;
u_int flags;
u_int index; /* logical ifindex */
u_int sysindex;
char name[IFNAMSIZ];
char descr[256];
struct ifmibdata mib;
u_int32_t mibtick;
void *specmib;
size_t specmiblen;
u_char *physaddr;
u_int physaddrlen;
int has_connector;
int trap_enable;
u_int32_t counter_disc;
mibif_notify_f xnotify;
void *xnotify_data;
const struct lmodule *xnotify_mod;
};
.Ed
.Pp
The
.Nm
module tries to implement the semantic if
.Va ifIndex
as described in RFC-2863. This RFC states, that an interface indexes may not
be reused. That means, for example, if
.Pa tun
is a synthetic interface type and the system creates the interface
.Pa tun0 ,
destroys this interfaces and again creates a
.Pa tun 0 ,
then these interfaces must have different interface indexes, because in fact
they are different interfaces. If, on the other hand, there is a hardware
interface
.Pa xl0
and this interface disappears, because its driver is unloaded and appears
again, because the driver is loaded again, the interface index must stay
the same.
.Nm
implements this by differentiating between real and synthetic (dynamic)
interfaces. An interface type can be declared dynamic by calling the function
.Fn mib_if_set_dyn
with the name if the interface type (for example
.Qq tun ).
For real interfaces, the module keeps the mapping between the interface name
and its
.Va ifIndex
in a special list, if the interface is unloaded. For dynamic interfaces
a new
.Va ifIndex
is generated each time the interface comes into existance. This
means, that the interface index as seen by SNMP is not the same index
as used by the system. The SNMP
.Va ifIndex
is held in field
.Va index ,
the system's interface index is
.Va sysindex .
.Pp
A call to
.Nm mib_refresh_iflist
causes the entire interface list to be re-created.
.Pp
The interface list can be traversed with the functions
.Fn mib_first_if
and
.Fn mib_next_if .
Be sure not to change the interface list while traversing the list with
these two calls.
.Pp
There are three functions to find an interface by name or index.
.Fn mib_find_if
finds an interface by searching for an SNMP
.Va ifIndex ,
.Fn mib_find_if_sys
finds an interface by searching for a system interface index and
.Fn mib_find_if_name
finds an interface by looking for an interface name. Each of the
function returns
.Li NULL
if the interface cannot be found.
.Pp
The function
.Fn mib_fetch_ifmib
causes the interface MIB to be refreshed from the kernel.
.Pp
The function
.Fn mib_if_admin
can be used to change the interface administrative state to up
(argument is 1) or down (argument is 0).
.Ss INTERFACE EVENTS
A module can register itself to receive a notification when a new entry is
created in the interface list. This is done by calling
.Fn mib_register_newif .
A module can register only one function, a second call to
.Fn mib_register_newif
causes the registration to be overwritten. The registration can be removed
with a call to
.Fn mib_unregister_newif .
If is unregistered automatically, when the registering module is unloaded.
.Pp
A module can also register to events on a specific interface. This is done
by calling
.Fn mibif_notify .
This causes the given callback
.Fa func
to be called with the interface pointer, a notification code and
the user argument
.Fa uarg
when any of the following events occur:
.Bl -tag -width "XXXXX"
.It Li MIBIF_NOTIFY_DESTROY
The interface is destroyed.
.El
.Pp
This mechanism can be used to implement interface type specific MIB parts
in other modules. The registration can be removed with
.Fn mib_unnotify
which the return value from
.Fa mib_notify .
Any notification registration is removed automatically when the interface
is destroyed or the registering module is unloaded.
.Em Note that only one module can register to any given interface .
.Ss INTERFACE ADDRESSES
The
.Nm
module handles a table of interface IP-addresses. These addresses are held
in a
.Bd -literal -offset indent
struct mibifa {
TAILQ_ENTRY(mibifa) link;
struct in_addr inaddr;
struct in_addr inmask;
struct in_addr inbcast;
struct asn_oid index;
u_int ifindex;
u_int flags;
};
.Ed
.Pp
The (ordered) list of IP-addresses on a given interface can be traversed by
calling
.Fn mib_first_ififa
and
.Fn mib_next_ififa .
The list should not be considered read-only.
.Ss INTERFACE RECEIVE ADDRESSES
The internet MIB-2 contains a table of interface receive addresses. These
addresses are handled in:
.Bd -literal -offset indent
struct mibrcvaddr {
TAILQ_ENTRY(mibrcvaddr) link;
struct asn_oid index;
u_int ifindex;
u_char addr[ASN_MAXOIDLEN];
size_t addrlen;
u_int flags;
};
enum {
MIBRCVADDR_VOLATILE = 0x00000001,
MIBRCVADDR_BCAST = 0x00000002,
MIBRCVADDR_HW = 0x00000004,
};
.Ed
.Pp
Note, that the assignment of
.Li MIBRCVADDR_BCAST
is based on a list of known interface types. The flags should be handled
by modules inplementing interface type specific MIBs.
.Pp
A receive address can be created with
.Fn mib_rcvaddr_create
and deleted with
.Fn mib_rcvaddr_delete .
This needs to be done only for addresses that are not automatically handled
by the system.
.Pp
A receive address can be found with
.Fn mib_find_rcvaddr .
.Ss INTERFACE STACK TABLE
The
.Nm
module maintains also the interface stack table. Because for complex stacks,
there is no system supported generic way of getting this information, interface
type specific modules need to help setting up stack entries. The
.Nm
module handles only the top and bottom entries.
.Pp
A table entry is created with
.Fn mib_ifstack_create
and deleted with
.Fn mib_ifstack_delete .
Both functions need the pointers to the interfaces. Entries are automatically
deleted if any of the interfaces of the entry is destroyed. The functions handle
both the stack table and the reverse stack table.
.Sh FILES
.Bl -tag -width ".It Pa /usr/local/include/bsnmp/mibII_tree.def" -compact
.It Pa /usr/local/include/bsnmp/mibII_tree.def
The description of the MIB tree implemented by
.Nm .
.It Pa /usr/local/share/snmp/mibs
The various internet MIBs.
.Sh SEE ALSO
.Xr snmpmod 3 ,
.Xr gensnmptree 1
.Sh STANDARDS
This implementation conforms to the applicable IETF RFCs.
.Sh AUTHORS
.An Hartmut Brandt Aq brandt@fokus.gmd.de
|