PageRenderTime 106ms CodeModel.GetById 95ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

/contrib/bsnmp/snmp_mibII/snmp_mibII.3

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