usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3

   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 of this software and documentation and use in source and
   9 .\" binary forms, with or without modification, are permitted provided that
  10 .\" the following conditions are met:
  11 .\"
  12 .\" 1. Redistributions of source code or documentation must retain the above
  13 .\"    copyright notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY FRAUNHOFER FOKUS
  19 .\" AND ITS CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  20 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  21 .\" FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
  22 .\" FRAUNHOFER FOKUS OR ITS CONTRIBUTORS  BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
  25 .\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  26 .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  27 .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  28 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd November 14, 2003
  33 .Dt SNMP_NETGRAPH 3
  34 .Os
  35 .Sh NAME
  36 .Nm snmp_netgraph ,
  37 .Nm snmp_node ,
  38 .Nm snmp_nodename ,
  39 .Nm ng_cookie_f ,
  40 .Nm ng_hook_f ,
  41 .Nm ng_register_cookie ,
  42 .Nm ng_unregister_cookie ,
  43 .Nm ng_register_hook ,
  44 .Nm ng_unregister_hook ,
  45 .Nm ng_unregister_module ,
  46 .Nm ng_output ,
  47 .Nm ng_output_node ,
  48 .Nm ng_output_id ,
  49 .Nm ng_dialog ,
  50 .Nm ng_dialog_node ,
  51 .Nm ng_dialog_id ,
  52 .Nm ng_send_data ,
  53 .Nm ng_mkpeer_id ,
  54 .Nm ng_connect_node ,
  55 .Nm ng_connect_id ,
  56 .Nm ng_connect2_id ,
  57 .Nm ng_connect2_tee_id ,
  58 .Nm ng_rmhook ,
  59 .Nm ng_rmhook_id ,
  60 .Nm ng_rmhook_tee_id ,
  61 .Nm ng_shutdown_id ,
  62 .Nm ng_next_node_id ,
  63 .Nm ng_node_id ,
  64 .Nm ng_node_id_node ,
  65 .Nm ng_node_name ,
  66 .Nm ng_node_type ,
  67 .Nm ng_peer_hook_id
  68 .Nd "netgraph module for snmpd"
  69 .Sh LIBRARY
  70 .Pq begemotSnmpdModulePath."netgraph" = "/usr/lib/snmp_netgraph.so"
  71 .Sh SYNOPSIS
  72 .In bsnmp/snmpmod.h
  73 .In bsnmp/snmp_netgraph.h
  74 .Vt extern ng_ID_t snmp_node ;
  75 .Vt extern u_char *snmp_nodename ;
  76 .Ft typedef void
  77 .Fn ng_cookie_f "const struct ng_mesg *mesg" "const char *path" "ng_ID_t id" "void *uarg"
  78 .Ft typedef void
  79 .Fn ng_hook_f "const char *hook" "const u_char *mesg" "size_t len" "void *uarg"
  80 .Ft void *
  81 .Fn ng_register_cookie "const struct lmodule *mod" "uint32_t cookie" "ng_ID_t id" "ng_cookie_f *func" "void *uarg"
  82 .Ft void
  83 .Fn ng_unregister_cookie "void *reg"
  84 .Ft void *
  85 .Fn ng_register_hook "const struct lmodule *mod" "const char *hook" "ng_hook_f *func" "void *uarg"
  86 .Ft void
  87 .Fn ng_unregister_hook "void *reg"
  88 .Ft void
  89 .Fn ng_unregister_module "const struct lmodule *mod"
  90 .Ft int
  91 .Fn ng_output "const char *path" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen"
  92 .Ft int
  93 .Fn ng_output_node "const char *node" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen"
  94 .Ft int
  95 .Fn ng_output_id "ng_ID_t node" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen"
  96 .Ft struct ng_mesg *
  97 .Fn ng_dialog "const char *path" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen"
  98 .Ft struct ng_mesg *
  99 .Fn ng_dialog_node "const char *node" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen"
 100 .Ft struct ng_mesg *
 101 .Fn ng_dialog_id "ng_ID_t id" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen"
 102 .Ft int
 103 .Fn ng_send_data "const char *hook" "const void *sndbuf" "size_t sndlen"
 104 .Ft ng_ID_t
 105 .Fn ng_mkpeer_id "ng_ID_t id" "const char *name" "const char *type" "const char *hook" "const char *peerhook"
 106 .Ft int
 107 .Fn ng_connect_node "const char *node" "const char *ourhook" "const char *peerhook"
 108 .Ft int
 109 .Fn ng_connect_id "ng_ID_t id" "const char *ourhook" "const char *peerhook"
 110 .Ft int
 111 .Fn ng_connect2_id "ng_ID_t id" "ng_ID_t peer" "const char *ourhook" "const char *peerhook"
 112 .Ft int
 113 .Fn ng_connect2_tee_id "ng_ID_t id" "ng_ID_t peer" "const char *ourhook" "const char *peerhook"
 114 .Ft int
 115 .Fn ng_rmhook "const char *ourhook"
 116 .Ft int
 117 .Fn ng_rmhook_id "ng_ID_t id" "const char *hook"
 118 .Ft int
 119 .Fn ng_rmhook_tee_id "ng_ID_t id" "const char *hook"
 120 .Ft int
 121 .Fn ng_shutdown_id "ng_ID_t id"
 122 .Ft ng_ID_t
 123 .Fn ng_next_node_id "ng_ID_t node" "const char *type" "const char *hook"
 124 .Ft ng_ID_t
 125 .Fn ng_node_id "const char *path"
 126 .Ft ng_ID_t
 127 .Fn ng_node_id_node "const char *node"
 128 .Ft ng_ID_t
 129 .Fn ng_node_name "ng_ID_t id" "char *name"
 130 .Ft ng_ID_t
 131 .Fn ng_node_type "ng_ID_t id" "char *type"
 132 .Ft int
 133 .Fn ng_peer_hook_id "ng_ID_t id" "const char *hook" "char *peerhook"
 134 .Sh DESCRIPTION
 135 The
 136 .Nm snmp_netgraph
 137 module implements a number of tables and scalars that enable remote access to
 138 the netgraph subsystem.
 139 It also exports a number of global variables and
 140 functions, that allow other modules to easily use the netgraph system.
 141 .Pp
 142 If upon start up of the module the variable
 143 .Va begemotNgControlNodeName
 144 is not empty the module opens a netgraph socket and names that socket node.
 145 If the variable is empty, the socket is created, as soon as the variable is
 146 written with a non-empty name.
 147 The socket can be closed by writing an empty
 148 string to the variable.
 149 The socket itself and its name are available in
 150 .Va snmp_node
 151 and
 152 .Va snmp_nodename .
 153 .Ss SENDING AND RECEIVING MESSAGES AND DATA
 154 There are three functions for sending control message:
 155 .Bl -tag -width ".It Fn ng_output_node"
 156 .It Fn ng_output
 157 sends a control message along the given
 158 .Fa path .
 159 .It Fn ng_output_node
 160 sends a control message to the node with name
 161 .Fa node
 162 and
 163 .It Fn ng_output_id
 164 sends a control message to the node with node id
 165 .Fa id .
 166 .El
 167 .Pp
 168 Each of these functions takes the following arguments:
 169 .Bl -tag -width ".It Fa cookie"
 170 .It Fa cookie
 171 is the node specific command cookie,
 172 .It Fa opcode
 173 is the node specific code for the operation to perform,
 174 .It Fa arg
 175 is a pointer to the message itself.
 176 This message must start with a
 177 .Vt struct ng_mesg .
 178 .It Fa arglen
 179 is the overall length of the message (header plus arguments).
 180 .El
 181 The functions return the message id that can be used to match incoming responses
 182 or -1 if an error occurs.
 183 .Pp
 184 Another class of functions is used to send a control message and to wait for
 185 a matching response.
 186 Note, that this operation blocks the daemon, so use it
 187 only if you are sure that the response will happen.
 188 There is a maximum timeout
 189 that is configurable in the MIB variable
 190 .Va begemotNgTimeout .
 191 Other messages arriving while the functions are waiting for the response are
 192 queued and delivered on the next call to the module's idle function.
 193 .Bl -tag -width ".It Fn ng_output_node"
 194 .It Fn ng_dialog
 195 sends a control message along the given
 196 .Fa path
 197 and waits for a matching response.
 198 .It Fn ng_dialog_node
 199 sends a control message to the node with name
 200 .Fa node
 201 and waits for a matching response.
 202 .It Fn ng_dialog_id
 203 sends a control message to the node with id
 204 .Fa id
 205 and waits for a matching response.
 206 .El
 207 .Pp
 208 All three functions take the same arguments as the
 209 .Fn ng_output*
 210 functions.
 211 The functions return the response message in a buffer allocated by
 212 .Xr malloc 3
 213 or NULL in case of an error.
 214 The maximum size of the response buffer can be
 215 configured in the variable
 216 .Va begemotNgResBufSiz .
 217 .Pp
 218 A data message can be send with the function
 219 .Fn ng_send_data .
 220 This function takes the name of the
 221 .Va snmp_node Ns 's
 222 hook through which to send the data, a pointer to the message buffer and
 223 the size of the message.
 224 It returns -1 if an error happens.
 225 .Ss ASYNCHRONOUS CONTROL AND DATA MESSAGES
 226 A module can register functions to asynchronously receive control and data
 227 message.
 228 .Pp
 229 The function
 230 .Fn ng_register_cookie
 231 registers a control message receive function.
 232 If a control message is
 233 received, that is not consumed by the dialog functions, the list of registered
 234 control message receive functions is scanned.
 235 If the cookie in the received
 236 message is the same as the
 237 .Fa cookie
 238 argument to the
 239 .Fn ng_register_cookie
 240 call and the
 241 .Fa id
 242 argument to the
 243 .Fn ng_register_cookie
 244 call was either 0 or equals the node id which sent the control message, the
 245 handler function
 246 .Fa func
 247 is called with a pointer to the received message, the hook on which the
 248 message was received (or NULL if it was received not on a hook), the id
 249 of the sender's node and the
 250 .Fa uarg
 251 argument of the registration call.
 252 The handler function should not modify
 253 the contents of the message, because more than one function may be registered
 254 to the same cookie and node id.
 255 .Pp
 256 A control message registration can be undone by calling
 257 .Fn ng_unregister_cookie
 258 with the return value of the registration call.
 259 If an error occurs while registering,
 260 .Fn ng_register_cookie
 261 returns NULL.
 262 .Pp
 263 A module can call
 264 .Fn ng_register_hook
 265 to register a callback for data messages on one of the
 266 .Va snmp_node Ns 's
 267 hooks.
 268 If a data message is received on that hook, the callback function
 269 .Fa func
 270 is called with the hook name, a pointer to the data message, the size of
 271 the message and the argument
 272 .Fa uarg
 273 to the registration function.
 274 The message should be treated as read-only.
 275 A data message registration can be undone by calling
 276 .Fn ng_unregister_hook
 277 with the return value of the registration call.
 278 If an error occurs while registering,
 279 .Fn ng_register_hook
 280 returns NULL.
 281 .Pp
 282 The function
 283 .Fn ng_unregister_module
 284 removes all control and data registrations for that module.
 285 .Ss FINDING NODES AND NODE CHARACTERISTICS
 286 The function
 287 .Fn ng_node_id
 288 returns the id of the node addressed by
 289 .Fa path
 290 or 0 if the node does not exists.
 291 .Pp
 292 The function
 293 .Fn ng_node_id_node
 294 returns the id of the node with name
 295 .Fa node
 296 or 0 if the node does not exist.
 297 .Pp
 298 The function
 299 .Fn ng_node_node
 300 retrieves the name of the node with id
 301 .Fa id
 302 and writes it to the buffer pointed to by
 303 .Fa name .
 304 This buffer should be at least
 305 .Li NG_NODESIZ
 306 bytes long.
 307 The function returns the node id or 0 if the
 308 node is not found.
 309 .Pp
 310 The function
 311 .Fn ng_node_type
 312 retrieves the name of the node with id
 313 .Fa id
 314 and writes it to the buffer pointed to by
 315 .Fa type .
 316 This buffer should be at least
 317 .Li NG_TYPESIZ
 318 bytes long.
 319 The function returns the node id or 0 if the
 320 node is not found.
 321 .Pp
 322 The function
 323 .Fn ng_peer_hook_id
 324 writes the name of the peer hook of the hook
 325 .Fa hook
 326 on the node with
 327 .Fa id
 328 to the buffer pointed to by
 329 .Fa peer_hook .
 330 The buffer should be at least
 331 .Li NG_HOOKSIZ
 332 bytes long.
 333 The function returns 0 if the node and the hook is found, -1
 334 otherwise.
 335 The function skips intermediate tee nodes (see
 336 .Xr ng_tee 4 ) .
 337 .Pp
 338 The function
 339 .Fn ng_next_node_id
 340 returns the node id of the peer node that is on the other side of hook
 341 .Fa hook
 342 of node
 343 .Fa id .
 344 If
 345 .Fa type
 346 is not NULL, the function checks, that the peer node's type is
 347 .Fa type .
 348 The function skips intermediate tee nodes (see
 349 .Xr ng_tee 4 ) .
 350 It returns the node id of the peer node or 0 if an error occurs or the
 351 types do not match.
 352 .Ss CHANGING THE GRAPH
 353 A number of functions can be used to create or destroy nodes and hooks.
 354 .Pp
 355 The function
 356 .Fn ng_mkpeer_id
 357 creates a new node of type
 358 .Fa type
 359 whose hook
 360 .Fa peerhook
 361 will be connected to
 362 .Fa hook
 363 of node
 364 .Fa id .
 365 If
 366 .Fa name
 367 is not NULL the new node is named with this name.
 368 The function returns
 369 The node id of the new node or 0 if an error happens.
 370 .Pp
 371 The functions
 372 .Fn ng_connect_node
 373 and
 374 .Fn ng_connect_id
 375 make a new hook connecting
 376 .Fa ourhook
 377 of the modules socket node
 378 .Va snmp_node
 379 to
 380 .Fa peerhook
 381 of the node identified by id
 382 .Fa id
 383 or name
 384 .Fa node .
 385 The functions return 0 on success or -1 otherwise.
 386 .Pp
 387 The function
 388 .Fn ng_connect2_id
 389 connects hook
 390 .Fa ourhook
 391 of the node with id
 392 .Fa id
 393 to hook
 394 .Fa peerhook
 395 of the node with id
 396 .Fa peer .
 397 The functions return 0 on success or -1 otherwise.
 398 The function
 399 .Fn ng_connect2_tee_id
 400 does the same as
 401 .Fn ng_connect2_id
 402 except, that it puts an unnamed tee node between the two nodes.
 403 .Pp
 404 The function
 405 .Fn ng_rmhook
 406 removes hook
 407 .Fa hook
 408 on the module's
 409 .Va snmp_node .
 410 The function
 411 .Fn ng_rmhook_id
 412 removes hook
 413 .Fa hook
 414 on the node with id
 415 .Fa id .
 416 The function
 417 .Fn ng_rmhook_tee_id
 418 additionally shuts down all tee nodes between the node and the first non-tee
 419 peer.
 420 .Pp
 421 The function
 422 .Fn ng_shutdown_id
 423 destroys the given node.
 424 .Sh FILES
 425 .Bl -tag -width "XXXXXXXXX"
 426 .It Pa /usr/share/bsnmp/defs/netgraph_tree.def
 427 The description of the MIB tree implemented by
 428 .Nm .
 429 .It Pa /usr/share/bsnmp/mibs/BEGEMOT-NETGRAPH.txt
 430 This is the MIB that is implemented by this module.
 431 .El
 432 .Sh SEE ALSO
 433 .Xr gensnmptree 1 ,
 434 .Xr snmpmod 3
 435 .Sh AUTHORS
 436 .An Hartmut Brandt Aq harti@FreeBSD.org