2 .\" Copyright (c) 2004-2005
4 .\" All rights reserved.
5 .\" Copyright (c) 2001-2003
6 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
7 .\" All rights reserved.
9 .\" Author: Harti Brandt <harti@FreeBSD.org>
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
14 .\" 1. Redistributions of source code must retain the above copyright
15 .\" notice, this list of conditions and the following disclaimer.
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\" notice, this list of conditions and the following disclaimer in the
18 .\" documentation and/or other materials provided with the distribution.
20 .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" $Begemot: bsnmp/snmp_mibII/snmp_mibII.3,v 1.10 2005/10/04 08:46:52 brandt_h Exp $
42 .Nm mib_refresh_iflist ,
45 .Nm mib_find_if_name ,
48 .Nm mib_register_newif ,
49 .Nm mib_unregister_newif ,
55 .Nm mib_ifstack_create ,
56 .Nm mib_ifstack_delete ,
57 .Nm mib_find_rcvaddr ,
58 .Nm mib_rcvaddr_create ,
59 .Nm mib_rcvaddr_delete ,
62 .Nd "mib-2 module for bsnmpd."
64 .Pq begemotSnmpdModulePath."mibII" = "@MODPATH@snmp_mibII.so"
67 .In bsnmp/snmp_mibII.h
69 .Fn (*mibif_notify_f) "struct mibif *ifp" "enum mibif_notify event" "void *uarg"
70 .Vt extern int mib_netsock ;
72 .Fn mib_if_set_dyn "const char *ifname"
74 .Fn mib_refresh_iflist "void"
76 .Fn mib_find_if "u_int ifindex"
78 .Fn mib_find_if_sys "u_int sysindex"
80 .Fn mib_find_if_name "const char *ifname"
82 .Fn mib_first_if "void"
84 .Fn mib_next_if "const struct mibif *ifp"
86 .Fn mib_register_newif "int (*func)(struct mibif *)" "const struct lmodule *mod"
88 .Fn mib_unregister_newif "const struct lmodule *mod"
90 .Fn mib_fetch_ifmib "struct mibif *ifp"
92 .Fn mib_if_admin "struct mibif *ifp" "int up"
94 .Fn mib_find_ifa "struct in_addr ipa"
96 .Fn mib_first_ififa "const struct mibif *ifp"
98 .Fn mib_next_ififa "struct mibifa *ifa"
100 .Fn mib_ifstack_create "const struct mibif *lower" "const struct mibif *upper"
102 .Fn mib_ifstack_delete "const struct mibif *lower" "const struct mibif *upper"
103 .Ft struct mibrcvaddr *
104 .Fn mib_find_rcvaddr "u_int ifindex" "const u_char *addr" "size_t addrlen"
105 .Ft struct mibrcvaddr *
106 .Fn mib_rcvaddr_create "struct mibif *ifp" "const u_char *addr" "size_t addrlen"
108 .Fn mib_rcvaddr_delete "struct mibrcvaddr *addr"
110 .Fn mibif_notify "struct mibif *ifp" "const struct lmodule *mod" "mibif_notify_f func" "void *uarg"
112 .Fn mibif_unnotify "void *reg"
116 module implements parts of the internet standard MIB-2.
117 Most of the relevant MIBs are implemented.
118 Some of the tables are restricted to be read-only instead of read-write.
119 The exact current implementation can be found in
120 .Pa @DEFPATH@mibII_tree.def .
121 The module also exports a number of functions and global variables for use
122 by other modules, that need to handle network interfaces.
123 This man page describes these functions.
124 .Ss DIRECT NETWORK ACCESS
127 module opens a socket that is used to execute all network related
130 This socket is globally available under the name
132 .Ss NETWORK INTERFACES
135 module handles a list of all currently existing network interfaces.
137 other modules to handle their own interface lists with special information
138 by providing a mechanism to register to events that change the interface list
140 The basic data structure is the interface structure:
141 .Bd -literal -offset indent
143 TAILQ_ENTRY(mibif) link;
145 u_int index; /* logical ifindex */
149 struct ifmibdata mib;
157 uint64_t counter_disc;
158 mibif_notify_f xnotify;
160 const struct lmodule *xnotify_mod;
161 struct asn_oid spec_oid;
167 module tries to implement the semantic if
169 as described in RFC-2863.
170 This RFC states, that an interface indexes may not be reused.
171 That means, for example, if
173 is a synthetic interface type and the system creates the interface
175 destroys this interfaces and again creates a
177 then these interfaces must have different interface indexes, because in fact
178 they are different interfaces.
179 If, on the other hand, there is a hardware interface
181 and this interface disappears, because its driver is unloaded and appears
182 again, because the driver is loaded again, the interface index must stay
185 implements this by differentiating between real and synthetic (dynamic)
187 An interface type can be declared dynamic by calling the function
189 with the name if the interface type (for example
191 For real interfaces, the module keeps the mapping between the interface name
194 in a special list, if the interface is unloaded.
195 For dynamic interfaces
198 is generated each time the interface comes into existence.
199 This means, that the interface index as seen by SNMP is not the same index
200 as used by the system.
205 the system's interface index is
209 .Nm mib_refresh_iflist
210 causes the entire interface list to be re-created.
212 The interface list can be traversed with the functions
216 Be sure not to change the interface list while traversing the list with
219 There are three functions to find an interface by name or index.
221 finds an interface by searching for an SNMP
224 finds an interface by searching for a system interface index and
226 finds an interface by looking for an interface name.
227 Each of the function returns
229 if the interface cannot be found.
233 causes the interface MIB to be refreshed from the kernel.
237 can be used to change the interface administrative state to up
238 (argument is 1) or down (argument is 0).
240 A module can register itself to receive a notification when a new entry is
241 created in the interface list.
242 This is done by calling
243 .Fn mib_register_newif .
244 A module can register only one function, a second call to
245 .Fn mib_register_newif
246 causes the registration to be overwritten.
247 The registration can be removed with a call to
248 .Fn mib_unregister_newif .
249 It is unregistered automatically, when the registering module is unloaded.
251 A module can also register to events on a specific interface.
252 This is done by calling
254 This causes the given callback
256 to be called with the interface pointer, a notification code and
259 when any of the following events occur:
260 .Bl -tag -width "XXXXX"
261 .It Li MIBIF_NOTIFY_DESTROY
262 The interface is destroyed.
265 This mechanism can be used to implement interface type specific MIB parts
267 The registration can be removed with
269 which the return value from
271 Any notification registration is removed automatically when the interface
272 is destroyed or the registering module is unloaded.
273 .Em Note that only one module can register to any given interface .
274 .Ss INTERFACE ADDRESSES
277 module handles a table of interface IP-addresses.
278 These addresses are held in a
279 .Bd -literal -offset indent
281 TAILQ_ENTRY(mibifa) link;
282 struct in_addr inaddr;
283 struct in_addr inmask;
284 struct in_addr inbcast;
285 struct asn_oid index;
291 The (ordered) list of IP-addresses on a given interface can be traversed by
296 The list should not be considered read-only.
297 .Ss INTERFACE RECEIVE ADDRESSES
298 The internet MIB-2 contains a table of interface receive addresses.
299 These addresses are handled in:
300 .Bd -literal -offset indent
302 TAILQ_ENTRY(mibrcvaddr) link;
303 struct asn_oid index;
305 u_char addr[ASN_MAXOIDLEN];
310 MIBRCVADDR_VOLATILE = 0x00000001,
311 MIBRCVADDR_BCAST = 0x00000002,
312 MIBRCVADDR_HW = 0x00000004,
316 Note, that the assignment of
318 is based on a list of known interface types.
319 The flags should be handled
320 by modules implementing interface type specific MIBs.
322 A receive address can be created with
323 .Fn mib_rcvaddr_create
325 .Fn mib_rcvaddr_delete .
326 This needs to be done only for addresses that are not automatically handled
329 A receive address can be found with
330 .Fn mib_find_rcvaddr .
331 .Ss INTERFACE STACK TABLE
334 module maintains also the interface stack table.
335 Because for complex stacks,
336 there is no system supported generic way of getting this information, interface
337 type specific modules need to help setting up stack entries.
340 module handles only the top and bottom entries.
342 A table entry is created with
343 .Fn mib_ifstack_create
345 .Fn mib_ifstack_delete .
346 Both functions need the pointers to the interfaces.
347 Entries are automatically
348 deleted if any of the interfaces of the entry is destroyed.
350 both the stack table and the reverse stack table.
352 .Bl -tag -width ".It Pa @DEFPATH@mibII_tree.def" -compact
353 .It Pa @DEFPATH@mibII_tree.def
354 The description of the MIB tree implemented by
356 .It Pa /usr/local/share/snmp/mibs
358 The various internet MIBs.
364 This implementation conforms to the applicable IETF RFCs.
366 .An Hartmut Brandt Aq harti@FreeBSD.org