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