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 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 286The function 287.Fn ng_node_id 288returns the id of the node addressed by 289.Fa path 290or 0 if the node does not exists. 291.Pp 292The function 293.Fn ng_node_id_node 294returns the id of the node with name 295.Fa node 296or 0 if the node does not exist. 297.Pp 298The function 299.Fn ng_node_node 300retrieves the name of the node with id 301.Fa id 302and writes it to the buffer pointed to by 303.Fa name . 304This buffer should be at least 305.Li NG_NODESIZ 306bytes long. 307The function returns the node id or 0 if the 308node is not found. 309.Pp 310The function 311.Fn ng_node_type 312retrieves the name of the node with id 313.Fa id 314and writes it to the buffer pointed to by 315.Fa type . 316This buffer should be at least 317.Li NG_TYPESIZ 318bytes long. 319The function returns the node id or 0 if the 320node is not found. 321.Pp 322The function 323.Fn ng_peer_hook_id 324writes the name of the peer hook of the hook 325.Fa hook 326on the node with 327.Fa id 328to the buffer pointed to by 329.Fa peer_hook . 330The buffer should be at least 331.Li NG_HOOKSIZ 332bytes long. 333The function returns 0 if the node and the hook is found, -1 334otherwise. 335The function skips intermediate tee nodes (see 336.Xr ng_tee 4 ) . 337.Pp 338The function 339.Fn ng_next_node_id 340returns the node id of the peer node that is on the other side of hook 341.Fa hook 342of node 343.Fa id . 344If 345.Fa type 346is not NULL, the function checks, that the peer node's type is 347.Fa type . 348The function skips intermediate tee nodes (see 349.Xr ng_tee 4 ) . 350It returns the node id of the peer node or 0 if an error occurs or the 351types do not match. 352.Ss CHANGING THE GRAPH 353A number of functions can be used to create or destroy nodes and hooks. 354.Pp 355The function 356.Fn ng_mkpeer_id 357creates a new node of type 358.Fa type 359whose hook 360.Fa peerhook 361will be connected to 362.Fa hook 363of node 364.Fa id . 365If 366.Fa name 367is not NULL the new node is named with this name. 368The function returns 369The node id of the new node or 0 if an error happens. 370.Pp 371The functions 372.Fn ng_connect_node 373and 374.Fn ng_connect_id 375make a new hook connecting 376.Fa ourhook 377of the modules socket node 378.Va snmp_node 379to 380.Fa peerhook 381of the node identified by id 382.Fa id 383or name 384.Fa node . 385The functions return 0 on success or -1 otherwise. 386.Pp 387The function 388.Fn ng_connect2_id 389connects hook 390.Fa ourhook 391of the node with id 392.Fa id 393to hook 394.Fa peerhook 395of the node with id 396.Fa peer . 397The functions return 0 on success or -1 otherwise. 398The function 399.Fn ng_connect2_tee_id 400does 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 Mt harti@FreeBSD.org 437