2 .\" Copyright (c) 2001-2003
3 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
4 .\" All rights reserved.
6 .\" Author: Harti Brandt <harti@FreeBSD.org>
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:
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.
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.
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 ,
57 .Nm ng_connect2_tee_id ,
60 .Nm ng_rmhook_tee_id ,
68 .Nd "netgraph module for snmpd.
70 .Pq begemotSnmpdModulePath."netgraph" = "/usr/lib/snmp_netgraph.so"
73 .In bsnmp/snmp_netgraph.h
74 .Vt extern ng_ID_t snmp_node ;
75 .Vt extern u_char *snmp_nodename ;
77 .Fn ng_cookie_f "const struct ng_mesg *mesg" "const char *path" "ng_ID_t id" "void *uarg"
79 .Fn ng_hook_f "const char *hook" "const u_char *mesg" "size_t len" "void *uarg"
81 .Fn ng_register_cookie "const struct lmodule *mod" "u_int32_t cookie" "ng_ID_t id" "ng_cookie_f *func" "void *uarg"
83 .Fn ng_unregister_cookie "void *reg"
85 .Fn ng_register_hook "const struct lmodule *mod" "const char *hook" "ng_hook_f *func" "void *uarg"
87 .Fn ng_unregister_hook "void *reg"
89 .Fn ng_unregister_module "const struct lmodule *mod"
91 .Fn ng_output "const char *path" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen"
93 .Fn ng_output_node "const char *node" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen"
95 .Fn ng_output_id "ng_ID_t node" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen"
97 .Fn ng_dialog "const char *path" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen"
99 .Fn ng_dialog_node "const char *node" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen"
101 .Fn ng_dialog_id "ng_ID_t id" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen"
103 .Fn ng_send_data "const char *hook" "const void *sndbuf" "size_t sndlen"
105 .Fn ng_mkpeer_id "ng_ID_t id" "const char *name" "const char *type" "const char *hook" "const char *peerhook"
107 .Fn ng_connect_node "const char *node" "const char *ourhook" "const char *peerhook"
109 .Fn ng_connect_id "ng_ID_t id" "const char *ourhook" "const char *peerhook"
111 .Fn ng_connect2_id "ng_ID_t id" "ng_ID_t peer" "const char *ourhook" "const char *peerhook"
113 .Fn ng_connect2_tee_id "ng_ID_t id" "ng_ID_t peer" "const char *ourhook" "const char *peerhook"
115 .Fn ng_rmhook "const char *ourhook"
117 .Fn ng_rmhook_id "ng_ID_t id" "const char *hook"
119 .Fn ng_rmhook_tee_id "ng_ID_t id" "const char *hook"
121 .Fn ng_shutdown_id "ng_ID_t id"
123 .Fn ng_next_node_id "ng_ID_t node" "const char *type" "const char *hook"
125 .Fn ng_node_id "const char *path"
127 .Fn ng_node_id_node "const char *node"
129 .Fn ng_node_name "ng_ID_t id" "char *name"
131 .Fn ng_node_type "ng_ID_t id" "char *type"
133 .Fn ng_peer_hook_id "ng_ID_t id" "const char *hook" "char *peerhook"
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.
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
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"
157 sends a control message along the given
159 .It Fn ng_output_node
160 sends a control message to the node with name
164 sends a control message to the node with node id
168 Each of these functions takes the following arguments:
169 .Bl -tag -width ".It Fa cookie"
171 is the node specific command cookie,
173 is the node specific code for the operation to perform,
175 is a pointer to the message itself.
176 This message must start with a
179 is the overall length of the message (header plus arguments).
181 The functions return the message id that can be used to match incoming responses
182 or -1 if an error occurs.
184 Another class of functions is used to send a control message and to wait for
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"
195 sends a control message along the given
197 and waits for a matching response.
198 .It Fn ng_dialog_node
199 sends a control message to the node with name
201 and waits for a matching response.
203 sends a control message to the node with id
205 and waits for a matching response.
208 All three functions take the same arguments as the
211 The functions return the response message in a buffer allocated by
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 .
218 A data message can be send with the function
220 This function takes the name of the
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
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
239 .Fn ng_register_cookie
243 .Fn ng_register_cookie
244 call was either 0 or equals the node id which sent the control message, the
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
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.
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
265 to register a callback for data messages on one of the
268 If a data message is received on that hook, the callback function
270 is called with the hook name, a pointer to the data message, the size of
271 the message and the argument
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,
283 .Fn ng_unregister_module
284 removes all control and data registrations for that module.
285 .Ss FINDING NODES AND NODE CHARACTERISTICS
289 returns the id of the node addressed by
291 or 0 if the node does not exists.
295 returns the id of the node with name
297 or 0 if the node does not exist.
301 retrieves the name of the node with id
303 and writes it to the buffer pointed to by
305 This buffer should be at least
308 The function returns the node id or 0 if the
313 retrieves the name of the node with id
315 and writes it to the buffer pointed to by
317 This buffer should be at least
320 The function returns the node id or 0 if the
325 writes the name of the peer hook of the hook
329 to the buffer pointed to by
331 The buffer should be at least
334 The function returns 0 if the node and the hook is found, -1
336 The function skips intermediate tee nodes (see
341 returns the node id of the peer node that is on the other side of hook
347 is not NULL, the function checks, that the peer node's type is
349 The function skips intermediate tee nodes (see
351 It returns the node id of the peer node or 0 if an error occurs or the
353 .Ss CHANGING THE GRAPH
354 A number of functions can be used to create or destroy nodes and hooks.
358 creates a new node of type
368 is not NULL the new node is named with this name.
370 The node id of the new node or 0 if an error happens.
376 make a new hook connecting
378 of the modules socket node
382 of the node identified by id
386 The functions return 0 on success or -1 otherwise.
398 The functions return 0 on success or -1 otherwise.
400 .Fn ng_connect2_tee_id
403 except, that it puts an unnamed tee node between the two nodes.
419 additionally shuts down all tee nodes between the node and the first non-tee
424 destroys the given node.
426 .Bl -tag -width "XXXXXXXXX"
427 .It Pa /usr/share/bsnmp/defs/netgraph_tree.def
428 The description of the MIB tree implemented by
430 .It Pa /usr/share/bsnmp/mibs/BEGEMOT-NETGRAPH.txt
431 This is the MIB that is implemented by this module.
437 .An Hartmut Brandt Aq harti@FreeBSD.org