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 135The 136.Nm snmp_netgraph 137module implements a number of tables and scalars that enable remote access to 138the netgraph subsystem. 139It also exports a number of global variables and 140functions, that allow other modules to easily use the netgraph system. 141.Pp 142If upon start up of the module the variable 143.Va begemotNgControlNodeName 144is not empty the module opens a netgraph socket and names that socket node. 145If the variable is empty, the socket is created, as soon as the variable is 146written with a non-empty name. 147The socket can be closed by writing an empty 148string to the variable. 149The socket itself and its name are available in 150.Va snmp_node 151and 152.Va snmp_nodename . 153.Ss SENDING AND RECEIVING MESSAGES AND DATA 154There are three functions for sending control message: 155.Bl -tag -width ".It Fn ng_output_node" 156.It Fn ng_output 157sends a control message along the given 158.Fa path . 159.It Fn ng_output_node 160sends a control message to the node with name 161.Fa node 162and 163.It Fn ng_output_id 164sends a control message to the node with node id 165.Fa id . 166.El 167.Pp 168Each of these functions takes the following arguments: 169.Bl -tag -width ".It Fa cookie" 170.It Fa cookie 171is the node specific command cookie, 172.It Fa opcode 173is the node specific code for the operation to performa, 174.It Fa arg 175is a pointer to the message itself. 176This message must start with a 177.Vt struct ng_mesg . 178.It Fa arglen 179is the overall length of the message (header plus arguments). 180.El 181The functions return the message id that can be used to match incoming responses 182or -1 if an error occurs. 183.Pp 184Another class of functions is used to send a control message and to wait for 185a matching response. 186Note, that this operation blocks the daemon, so use it 187only if you are sure that the response will happen. 188There is a maximum timeout 189that is configurable in the MIB variable 190.Va begemotNgTimeout . 191Other messages arriving while the functions are waiting for the response are 192queued 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 195sends a control message along the given 196.Fa path 197and waits for a matching response. 198.It Fn ng_dialog_node 199sends a control message to the node with name 200.Fa node 201and waits for a matching response. 202.It Fn ng_dialog_id 203sends a control message to the node with id 204.Fa id 205and waits for a matching response. 206.El 207.Pp 208All three functions take the same arguments as the 209.Fn ng_output* 210functions. 211The functions return the reponse message in a buffer allocated by 212.Xr malloc 3 213or NULL in case of an error. 214The maximum size of the response buffer can be 215configured in the variable 216.Va begemotNgResBufSiz . 217.Pp 218A data message can be send with the function 219.Fn ng_send_data . 220This function takes the name of the 221.Va snmp_node Ns 's 222hook through which to send the data, a pointer to the message buffer and 223the size of the message. 224It returns -1 if an error happens. 225.Ss ASYNCHRONOUS CONTROL AND DATA MESSAGES 226A module can register functions to asynchronuosly receive control and data 227message. 228.Pp 229The function 230.Fn ng_register_cookie 231registers a control message receive function. 232If a control message is 233received, that is not consumed by the dialog functions, the list of registerred 234control message receive functions is scanned. 235If the cookie in the received 236message is the same as the 237.Fa cookie 238argument to the 239.Fn ng_register_cookie 240call and the 241.Fn 242.Fa id 243argument to the 244.Fn ng_register_cookie 245call was either 0 or equals the node id which sent the control message, the 246handler function 247.Fa func 248is called with a pointer to the received message, the hook on which the 249message was received (or NULL if it was received not on a hook), the id 250of the sender's node and the 251.Fa uarg 252argument of the registration call. 253The handler function should not modify 254the contents of the message, because more than one function may be registered 255to the same cookie and node id. 256.Pp 257A control message registration can be undone by calling 258.Fn ng_unregister_cookie 259with the return value of the registration call. 260If an error occures while registering, 261.Fn ng_register_cookie 262returns NULL. 263.Pp 264A module can call 265.Fn ng_register_hook 266to register a callback for data messages on one of the 267.Va snmp_node Ns 's 268hooks. 269If a data message is received on that hook, the callback function 270.Fa func 271is called with the hook name, a pointer to the data message, the size of 272the message and the argument 273.Fa uarg 274to the registration function. 275The message should be treated as read-only. 276A data message registration can be undone by calling 277.Fn ng_unregister_hook 278with the return value of the registration call. 279If an error occures while registering, 280.Fn ng_register_hook 281returns NULL. 282.Pp 283The function 284.Fn ng_unregister_module 285removes all control and data registrations for that module. 286.Ss FINDING NODES AND NODE CHARACTERISTICS 287.Pp 288The function 289.Fn ng_node_id 290returns the id of the node addressed by 291.Fa path 292or 0 if the node does not exists. 293.Pp 294The function 295.Fn ng_node_id_node 296returns the id of the node with name 297.Fa node 298or 0 if the node does not exist. 299.Pp 300The function 301.Fn ng_node_node 302retrieves the name of the node with id 303.Fa id 304and writes it to the buffer pointed to by 305.Fa name . 306This buffer should be at least 307.Li NG_NODESIZ 308bytes long. 309The function returns the node id or 0 if the 310node is not found 311.Pp 312The function 313.Fn ng_node_type 314retrieves the name of the node with id 315.Fa id 316and writes it to the buffer pointed to by 317.Fa type . 318This buffer should be at least 319.Li NG_TYPESIZ 320bytes long. 321The function returns the node id or 0 if the 322node is not found. 323.Pp 324The function 325.Fn ng_peer_hook_id 326writes the name of the peer hook of the hook 327.Fa hook 328on the node with 329.Fa id 330to the buffer pointed to by 331.Fa peer_hook . 332The buffer should be at least 333.Li NG_HOOKSIZ 334bytes long. 335The function returns 0 if the node and the hook is found, -1 336otherwise. 337The function skips intermediate tee nodes (see 338.Xr ng_tee 4 ). 339.Pp 340The function 341.Fn ng_next_node_id 342returns the node id of the peer node that is on the other side of hook 343.Fa hook 344of node 345.Fa id . 346If 347.Fa type 348is not NULL, the function checks, that the peer node's type is 349.Fa type . 350The function skips intermediate tee nodes (see 351.Xr ng_tee 4 ). 352It returns the node id of the peer node or 0 if an error occurres or the 353types do not match. 354.Ss CHANGING THE GRAPH 355A number of functions can be used to create or destroy nodes and hooks. 356.Pp 357The function 358.Fn ng_mkpeer_id 359creates a new node of type 360.Fa type 361who's hook 362.Fa peerhook 363will be connected to 364.Fa hook 365of node 366.Fa id . 367If 368.Fa name 369is not NULL the new node is named with this name. 370The function returns 371The node id of the new node or 0 if an error happens. 372.Pp 373The functions 374.Fn ng_connect_node 375and 376.Fn ng_connect_id 377make a new hook connecting 378.Fa ourhook 379of the modules socket node 380.Va snmp_node 381to 382.Fa peerhook 383of the node identified by id 384.Fa id 385or name 386.Fa node . 387The functions return 0 on success or -1 otherwise. 388.Pp 389The function 390.Fn ng_connect2_id 391connects hook 392.Fa ourhook 393of the node with id 394.Fa id 395to hook 396.Fa peerhook 397of the node with id 398.Fa peer . 399The functions return 0 on success or -1 otherwise. 400The function 401.Fn ng_connect2_tee_id does the same as 402.Fn ng_connect2_id 403except, that it puts an unnamed tee node between the two nodes. 404.Pp 405The function 406.Fn ng_rmhook 407removes hook 408.Fa hook 409on the module's 410.Va snmp_node . 411The function 412.Fn ng_rmhook_id 413removes hook 414.Fa hook 415on the node with id 416.Fa id . 417The function 418.Fn ng_rmhook_tee_id 419additionally shuts down all tee nodes between the node and the first non-tee 420peer. 421.Pp 422The function 423.Fn ng_shutdown_id 424destroys the given node. 425.Sh FILES 426.Bl -tag -width "XXXXXXXXX" 427.It Pa /usr/share/bsnmp/defs/netgraph_tree.def 428The description of the MIB tree implemented by 429.Nm . 430.It Pa /usr/share/bsnmp/mibs/BEGEMOT-NETGRAPH.txt 431This is the MIB that is implemented by this module. 432.Sh SEE ALSO 433.Xr gensnmptree 1 , 434.Xr snmpmod 3 435.Sh AUTHORS 436.An Hartmut Brandt Aq harti@freebsd.org 437