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