351 lines
11 KiB
Groff
351 lines
11 KiB
Groff
.\"
|
|
.\" 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.3 2004/04/13 17:01:31 novo Exp $
|
|
.\"
|
|
.Dd August 19, 2002
|
|
.Dt snmp_mibII 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mibII ,
|
|
.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" = "@MODPATH@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 @DEFPATH@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 @DEFPATH@mibII_tree.def" -compact
|
|
.It Pa @DEFPATH@mibII_tree.def
|
|
The description of the MIB tree implemented by
|
|
.Nm .
|
|
.It Pa /usr/local/share/snmp/mibs
|
|
.It Pa @MIBSPATH@
|
|
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 harti@freebsd.org
|