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" "u_int32_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 .Pp
 287 The function
 288 .Fn ng_node_id
 289 returns the id of the node addressed by
 290 .Fa path
 291 or 0 if the node does not exists.
 292 .Pp
 293 The function
 294 .Fn ng_node_id_node
 295 returns the id of the node with name
 296 .Fa node
 297 or 0 if the node does not exist.
 298 .Pp
 299 The function
 300 .Fn ng_node_node
 301 retrieves the name of the node with id
 302 .Fa id
 303 and writes it to the buffer pointed to by
 304 .Fa name .
 305 This buffer should be at least
 306 .Li NG_NODESIZ
 307 bytes long.
 308 The function returns the node id or 0 if the
 309 node is not found.
 310 .Pp
 311 The function
 312 .Fn ng_node_type
 313 retrieves the name of the node with id
 314 .Fa id
 315 and writes it to the buffer pointed to by
 316 .Fa type .
 317 This buffer should be at least
 318 .Li NG_TYPESIZ
 319 bytes long.
 320 The function returns the node id or 0 if the
 321 node is not found.
 322 .Pp
 323 The function
 324 .Fn ng_peer_hook_id
 325 writes the name of the peer hook of the hook
 326 .Fa hook
 327 on the node with
 328 .Fa id
 329 to the buffer pointed to by
 330 .Fa peer_hook .
 331 The buffer should be at least
 332 .Li NG_HOOKSIZ
 333 bytes long.
 334 The function returns 0 if the node and the hook is found, -1
 335 otherwise.
 336 The function skips intermediate tee nodes (see
 337 .Xr ng_tee 4 ) .
 338 .Pp
 339 The function
 340 .Fn ng_next_node_id
 341 returns the node id of the peer node that is on the other side of hook
 342 .Fa hook
 343 of node
 344 .Fa id .
 345 If
 346 .Fa type
 347 is not NULL, the function checks, that the peer node's type is
 348 .Fa type .
 349 The function skips intermediate tee nodes (see
 350 .Xr ng_tee 4 ) .
 351 It returns the node id of the peer node or 0 if an error occurs or the
 352 types do not match.
 353 .Ss CHANGING THE GRAPH
 354 A number of functions can be used to create or destroy nodes and hooks.
 355 .Pp
 356 The function
 357 .Fn ng_mkpeer_id
 358 creates a new node of type
 359 .Fa type
 360 whose hook
 361 .Fa peerhook
 362 will be connected to
 363 .Fa hook
 364 of node
 365 .Fa id .
 366 If
 367 .Fa name
 368 is not NULL the new node is named with this name.
 369 The function returns
 370 The node id of the new node or 0 if an error happens.
 371 .Pp
 372 The functions
 373 .Fn ng_connect_node
 374 and
 375 .Fn ng_connect_id
 376 make a new hook connecting
 377 .Fa ourhook
 378 of the modules socket node
 379 .Va snmp_node
 380 to
 381 .Fa peerhook
 382 of the node identified by id
 383 .Fa id
 384 or name
 385 .Fa node .
 386 The functions return 0 on success or -1 otherwise.
 387 .Pp
 388 The function
 389 .Fn ng_connect2_id
 390 connects hook
 391 .Fa ourhook
 392 of the node with id
 393 .Fa id
 394 to hook
 395 .Fa peerhook
 396 of the node with id
 397 .Fa peer .
 398 The functions return 0 on success or -1 otherwise.
 399 The function
 400 .Fn ng_connect2_tee_id
 401 does the same as
 402 .Fn ng_connect2_id
 403 except, that it puts an unnamed tee node between the two nodes.
 404 .Pp
 405 The function
 406 .Fn ng_rmhook
 407 removes hook
 408 .Fa hook
 409 on the module's
 410 .Va snmp_node .
 411 The function
 412 .Fn ng_rmhook_id
 413 removes hook
 414 .Fa hook
 415 on the node with id
 416 .Fa id .
 417 The function
 418 .Fn ng_rmhook_tee_id
 419 additionally shuts down all tee nodes between the node and the first non-tee
 420 peer.
 421 .Pp
 422 The function
 423 .Fn ng_shutdown_id
 424 destroys the given node.
 425 .Sh FILES
 426 .Bl -tag -width "XXXXXXXXX"
 427 .It Pa /usr/share/bsnmp/defs/netgraph_tree.def
 428 The description of the MIB tree implemented by
 429 .Nm .
 430 .It Pa /usr/share/bsnmp/mibs/BEGEMOT-NETGRAPH.txt
 431 This is the MIB that is implemented by this module.
 432 .El
 433 .Sh SEE ALSO
 434 .Xr gensnmptree 1 ,
 435 .Xr snmpmod 3
 436 .Sh AUTHORS
 437 .An Hartmut Brandt Aq harti@FreeBSD.org