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