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 perform, 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 response 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 asynchronously 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 registered 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.Fa id 242argument to the 243.Fn ng_register_cookie 244call was either 0 or equals the node id which sent the control message, the 245handler function 246.Fa func 247is called with a pointer to the received message, the hook on which the 248message was received (or NULL if it was received not on a hook), the id 249of the sender's node and the 250.Fa uarg 251argument of the registration call. 252The handler function should not modify 253the contents of the message, because more than one function may be registered 254to the same cookie and node id. 255.Pp 256A control message registration can be undone by calling 257.Fn ng_unregister_cookie 258with the return value of the registration call. 259If an error occurs while registering, 260.Fn ng_register_cookie 261returns NULL. 262.Pp 263A module can call 264.Fn ng_register_hook 265to register a callback for data messages on one of the 266.Va snmp_node Ns 's 267hooks. 268If a data message is received on that hook, the callback function 269.Fa func 270is called with the hook name, a pointer to the data message, the size of 271the message and the argument 272.Fa uarg 273to the registration function. 274The message should be treated as read-only. 275A data message registration can be undone by calling 276.Fn ng_unregister_hook 277with the return value of the registration call. 278If an error occurs while registering, 279.Fn ng_register_hook 280returns NULL. 281.Pp 282The function 283.Fn ng_unregister_module 284removes all control and data registrations for that module. 285.Ss FINDING NODES AND NODE CHARACTERISTICS 286.Pp 287The function 288.Fn ng_node_id 289returns the id of the node addressed by 290.Fa path 291or 0 if the node does not exists. 292.Pp 293The function 294.Fn ng_node_id_node 295returns the id of the node with name 296.Fa node 297or 0 if the node does not exist. 298.Pp 299The function 300.Fn ng_node_node 301retrieves the name of the node with id 302.Fa id 303and writes it to the buffer pointed to by 304.Fa name . 305This buffer should be at least 306.Li NG_NODESIZ 307bytes long. 308The function returns the node id or 0 if the 309node is not found 310.Pp 311The function 312.Fn ng_node_type 313retrieves the name of the node with id 314.Fa id 315and writes it to the buffer pointed to by 316.Fa type . 317This buffer should be at least 318.Li NG_TYPESIZ 319bytes long. 320The function returns the node id or 0 if the 321node is not found. 322.Pp 323The function 324.Fn ng_peer_hook_id 325writes the name of the peer hook of the hook 326.Fa hook 327on the node with 328.Fa id 329to the buffer pointed to by 330.Fa peer_hook . 331The buffer should be at least 332.Li NG_HOOKSIZ 333bytes long. 334The function returns 0 if the node and the hook is found, -1 335otherwise. 336The function skips intermediate tee nodes (see 337.Xr ng_tee 4 ) . 338.Pp 339The function 340.Fn ng_next_node_id 341returns the node id of the peer node that is on the other side of hook 342.Fa hook 343of node 344.Fa id . 345If 346.Fa type 347is not NULL, the function checks, that the peer node's type is 348.Fa type . 349The function skips intermediate tee nodes (see 350.Xr ng_tee 4 ) . 351It returns the node id of the peer node or 0 if an error occurs or the 352types do not match. 353.Ss CHANGING THE GRAPH 354A number of functions can be used to create or destroy nodes and hooks. 355.Pp 356The function 357.Fn ng_mkpeer_id 358creates a new node of type 359.Fa type 360whose hook 361.Fa peerhook 362will be connected to 363.Fa hook 364of node 365.Fa id . 366If 367.Fa name 368is not NULL the new node is named with this name. 369The function returns 370The node id of the new node or 0 if an error happens. 371.Pp 372The functions 373.Fn ng_connect_node 374and 375.Fn ng_connect_id 376make a new hook connecting 377.Fa ourhook 378of the modules socket node 379.Va snmp_node 380to 381.Fa peerhook 382of the node identified by id 383.Fa id 384or name 385.Fa node . 386The functions return 0 on success or -1 otherwise. 387.Pp 388The function 389.Fn ng_connect2_id 390connects hook 391.Fa ourhook 392of the node with id 393.Fa id 394to hook 395.Fa peerhook 396of the node with id 397.Fa peer . 398The functions return 0 on success or -1 otherwise. 399The function 400.Fn ng_connect2_tee_id does the same as 401.Fn ng_connect2_id 402except, that it puts an unnamed tee node between the two nodes. 403.Pp 404The function 405.Fn ng_rmhook 406removes hook 407.Fa hook 408on the module's 409.Va snmp_node . 410The function 411.Fn ng_rmhook_id 412removes hook 413.Fa hook 414on the node with id 415.Fa id . 416The function 417.Fn ng_rmhook_tee_id 418additionally shuts down all tee nodes between the node and the first non-tee 419peer. 420.Pp 421The function 422.Fn ng_shutdown_id 423destroys the given node. 424.Sh FILES 425.Bl -tag -width "XXXXXXXXX" 426.It Pa /usr/share/bsnmp/defs/netgraph_tree.def 427The description of the MIB tree implemented by 428.Nm . 429.It Pa /usr/share/bsnmp/mibs/BEGEMOT-NETGRAPH.txt 430This 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 437