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 367