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