contrib/bsnmp/snmp_mibII/snmp_mibII.3

   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
 116 The
 117 .Nm snmp_mibII
 118 module implements parts of the internet standard MIB-2.
 119 Most of the relevant MIBs are implemented.
 120 Some of the tables are restricted to be read-only instead of read-write.
 121 The exact current implementation can be found in
 122 .Pa @DEFPATH@mibII_tree.def .
 123 The module also exports a number of functions and global variables for use
 124 by other modules, that need to handle network interfaces.
 125 This man page describes these functions.
 126 .Ss DIRECT NETWORK ACCESS
 127 The
 128 .Nm
 129 module opens a socket that is used to execute all network related
 130 .Xr ioctl 2
 131 functions.
 132 This socket is globally available under the name
 133 .Va mib_netsock .
 134 .Ss NETWORK INTERFACES
 135 The
 136 .Nm
 137 module handles a list of all currently existing network interfaces.
 138 It allows
 139 other modules to handle their own interface lists with special information
 140 by providing a mechanism to register to events that change the interface list
 141 (see below).
 142 The basic data structure is the interface structure:
 143 .Bd -literal -offset indent
 144 struct 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
 167 The
 168 .Nm
 169 module tries to implement the semantic if
 170 .Va ifIndex
 171 as described in RFC-2863.
 172 This RFC states, that an interface indexes may not be reused.
 173 That means, for example, if
 174 .Pa tun
 175 is a synthetic interface type and the system creates the interface
 176 .Pa tun0 ,
 177 destroys this interfaces and again creates a
 178 .Pa tun 0 ,
 179 then these interfaces must have different interface indexes, because in fact
 180 they are different interfaces.
 181 If, on the other hand, there is a hardware interface
 182 .Pa xl0
 183 and this interface disappears, because its driver is unloaded and appears
 184 again, because the driver is loaded again, the interface index must stay
 185 the same.
 186 .Nm
 187 implements this by differentiating between real and synthetic (dynamic)
 188 interfaces.
 189 An interface type can be declared dynamic by calling the function
 190 .Fn mib_if_set_dyn
 191 with the name if the interface type (for example
 192 .Qq tun ).
 193 For real interfaces, the module keeps the mapping between the interface name
 194 and its
 195 .Va ifIndex
 196 in a special list, if the interface is unloaded.
 197 For dynamic interfaces
 198 a new
 199 .Va ifIndex
 200 is generated each time the interface comes into existence.
 201 This means, that the interface index as seen by SNMP is not the same index
 202 as used by the system.
 203 The SNMP
 204 .Va ifIndex
 205 is held in field
 206 .Va index ,
 207 the system's interface index is
 208 .Va sysindex .
 209 .Pp
 210 A call to
 211 .Nm mib_refresh_iflist
 212 causes the entire interface list to be re-created.
 213 .Pp
 214 The interface list can be traversed with the functions
 215 .Fn mib_first_if
 216 and
 217 .Fn mib_next_if .
 218 Be sure not to change the interface list while traversing the list with
 219 these two calls.
 220 .Pp
 221 There are three functions to find an interface by name or index.
 222 .Fn mib_find_if
 223 finds an interface by searching for an SNMP
 224 .Va ifIndex ,
 225 .Fn mib_find_if_sys
 226 finds an interface by searching for a system interface index and
 227 .Fn mib_find_if_name
 228 finds an interface by looking for an interface name.
 229 Each of the function returns
 230 .Li NULL
 231 if the interface cannot be found.
 232 .Pp
 233 The function
 234 .Fn mib_fetch_ifmib
 235 causes the interface MIB to be refreshed from the kernel.
 236 .Pp
 237 The function
 238 .Fn mib_if_admin
 239 can be used to change the interface administrative state to up
 240 (argument is 1) or down (argument is 0).
 241 .Ss INTERFACE EVENTS
 242 A module can register itself to receive a notification when a new entry is
 243 created in the interface list.
 244 This is done by calling
 245 .Fn mib_register_newif .
 246 A module can register only one function, a second call to
 247 .Fn mib_register_newif
 248 causes the registration to be overwritten.
 249 The registration can be removed with a call to
 250 .Fn mib_unregister_newif .
 251 It is unregistered automatically, when the registering module is unloaded.
 252 .Pp
 253 A module can also register to events on a specific interface.
 254 This is done by calling
 255 .Fn mibif_notify .
 256 This causes the given callback
 257 .Fa func
 258 to be called with the interface pointer, a notification code and
 259 the user argument
 260 .Fa uarg
 261 when any of the following events occur:
 262 .Bl -tag -width "XXXXX"
 263 .It Li MIBIF_NOTIFY_DESTROY
 264 The interface is destroyed.
 265 .El
 266 .Pp
 267 This mechanism can be used to implement interface type specific MIB parts
 268 in other modules.
 269 The registration can be removed with
 270 .Fn mib_unnotify
 271 which the return value from
 272 .Fa mib_notify .
 273 Any notification registration is removed automatically when the interface
 274 is destroyed or the registering module is unloaded.
 275 .Em Note that only one module can register to any given interface .
 276 .Ss INTERFACE ADDRESSES
 277 The
 278 .Nm
 279 module handles a table of interface IP-addresses.
 280 These addresses are held in a
 281 .Bd -literal -offset indent
 282 struct 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
 293 The (ordered) list of IP-addresses on a given interface can be traversed by
 294 calling
 295 .Fn mib_first_ififa
 296 and
 297 .Fn mib_next_ififa .
 298 The list should not be considered read-only.
 299 .Ss INTERFACE RECEIVE ADDRESSES
 300 The internet MIB-2 contains a table of interface receive addresses.
 301 These addresses are handled in:
 302 .Bd -literal -offset indent
 303 struct 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 };
 311 enum {
 312         MIBRCVADDR_VOLATILE     = 0x00000001,
 313         MIBRCVADDR_BCAST        = 0x00000002,
 314         MIBRCVADDR_HW           = 0x00000004,
 315 };
 316 .Ed
 317 .Pp
 318 Note, that the assignment of
 319 .Li MIBRCVADDR_BCAST
 320 is based on a list of known interface types.
 321 The flags should be handled
 322 by modules implementing interface type specific MIBs.
 323 .Pp
 324 A receive address can be created with
 325 .Fn mib_rcvaddr_create
 326 and deleted with
 327 .Fn mib_rcvaddr_delete .
 328 This needs to be done only for addresses that are not automatically handled
 329 by the system.
 330 .Pp
 331 A receive address can be found with
 332 .Fn mib_find_rcvaddr .
 333 .Ss INTERFACE STACK TABLE
 334 The
 335 .Nm
 336 module maintains also the interface stack table.
 337 Because for complex stacks,
 338 there is no system supported generic way of getting this information, interface
 339 type specific modules need to help setting up stack entries.
 340 The
 341 .Nm
 342 module handles only the top and bottom entries.
 343 .Pp
 344 A table entry is created with
 345 .Fn mib_ifstack_create
 346 and deleted with
 347 .Fn mib_ifstack_delete .
 348 Both functions need the pointers to the interfaces.
 349 Entries are automatically
 350 deleted if any of the interfaces of the entry is destroyed.
 351 The functions handle
 352 both 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
 356 The description of the MIB tree implemented by
 357 .Nm .
 358 .It Pa /usr/local/share/snmp/mibs
 359 .It Pa @MIBSPATH@
 360 The various internet MIBs.
 361 .El
 362 .Sh SEE ALSO
 363 .Xr gensnmptree 1 ,
 364 .Xr snmpmod 3
 365 .Sh STANDARDS
 366 This implementation conforms to the applicable IETF RFCs.
 367 .Sh AUTHORS
 368 .An Hartmut Brandt Aq harti@FreeBSD.org