--- name: "snmp_netgraph" section: "3" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/snmp_netgraph" --- # snmp\_netgraph(3) netgraph module for snmpd ## NAME **snmp\_netgraph**, **snmp\_node**, **snmp\_nodename**, **ng\_cookie\_f**, **ng\_hook\_f**, **ng\_register\_cookie**, **ng\_unregister\_cookie**, **ng\_register\_hook**, **ng\_unregister\_hook**, **ng\_unregister\_module**, **ng\_output**, **ng\_output\_node**, **ng\_output\_id**, **ng\_dialog**, **ng\_dialog\_node**, **ng\_dialog\_id**, **ng\_send\_data**, **ng\_mkpeer\_id**, **ng\_connect\_node**, **ng\_connect\_id**, **ng\_connect2\_id**, **ng\_connect2\_tee\_id**, **ng\_rmhook**, **ng\_rmhook\_id**, **ng\_rmhook\_tee\_id**, **ng\_shutdown\_id**, **ng\_next\_node\_id**, **ng\_node\_id**, **ng\_node\_id\_node**, **ng\_node\_name**, **ng\_node\_type**, **ng\_peer\_hook\_id** – netgraph module for snmpd ## LIBRARY (begemotSnmpdModulePath."netgraph" = /usr/lib/snmp\_netgraph.so) ## SYNOPSIS **#include \** **#include \** *extern* *ng\_ID\_t* *snmp\_node*; *extern* *u\_char* *\*snmp\_nodename*; *typedef* *void*\ **ng\_cookie\_f**(*const struct ng\_mesg \*mesg*, *const char \*path*, *ng\_ID\_t id*, *void \*uarg*); *typedef* *void*\ **ng\_hook\_f**(*const char \*hook*, *const u\_char \*mesg*, *size\_t len*, *void \*uarg*); *void* *\**\ **ng\_register\_cookie**(*const struct lmodule \*mod*, *uint32\_t cookie*, *ng\_ID\_t id*, *ng\_cookie\_f \*func*, *void \*uarg*); *void*\ **ng\_unregister\_cookie**(*void \*reg*); *void* *\**\ **ng\_register\_hook**(*const struct lmodule \*mod*, *const char \*hook*, *ng\_hook\_f \*func*, *void \*uarg*); *void*\ **ng\_unregister\_hook**(*void \*reg*); *void*\ **ng\_unregister\_module**(*const struct lmodule \*mod*); *int*\ **ng\_output**(*const char \*path*, *u\_int cookie*, *u\_int opcode*, *const void \*arg*, *size\_t arglen*); *int*\ **ng\_output\_node**(*const char \*node*, *u\_int cookie*, *u\_int opcode*, *const void \*arg*, *size\_t arglen*); *int*\ **ng\_output\_id**(*ng\_ID\_t node*, *u\_int cookie*, *u\_int opcode*, *const void \*arg*, *size\_t arglen*); *struct* *ng\_mesg* *\**\ **ng\_dialog**(*const char \*path*, *u\_int cookie*, *u\_int opcode*, *const void \*arg*, *size\_t arglen*); *struct* *ng\_mesg* *\**\ **ng\_dialog\_node**(*const char \*node*, *u\_int cookie*, *u\_int opcode*, *const void \*arg*, *size\_t arglen*); *struct* *ng\_mesg* *\**\ **ng\_dialog\_id**(*ng\_ID\_t id*, *u\_int cookie*, *u\_int opcode*, *const void \*arg*, *size\_t arglen*); *int*\ **ng\_send\_data**(*const char \*hook*, *const void \*sndbuf*, *size\_t sndlen*); *ng\_ID\_t*\ **ng\_mkpeer\_id**(*ng\_ID\_t id*, *const char \*name*, *const char \*type*, *const char \*hook*, *const char \*peerhook*); *int*\ **ng\_connect\_node**(*const char \*node*, *const char \*ourhook*, *const char \*peerhook*); *int*\ **ng\_connect\_id**(*ng\_ID\_t id*, *const char \*ourhook*, *const char \*peerhook*); *int*\ **ng\_connect2\_id**(*ng\_ID\_t id*, *ng\_ID\_t peer*, *const char \*ourhook*, *const char \*peerhook*); *int*\ **ng\_connect2\_tee\_id**(*ng\_ID\_t id*, *ng\_ID\_t peer*, *const char \*ourhook*, *const char \*peerhook*); *int*\ **ng\_rmhook**(*const char \*ourhook*); *int*\ **ng\_rmhook\_id**(*ng\_ID\_t id*, *const char \*hook*); *int*\ **ng\_rmhook\_tee\_id**(*ng\_ID\_t id*, *const char \*hook*); *int*\ **ng\_shutdown\_id**(*ng\_ID\_t id*); *ng\_ID\_t*\ **ng\_next\_node\_id**(*ng\_ID\_t node*, *const char \*type*, *const char \*hook*); *ng\_ID\_t*\ **ng\_node\_id**(*const char \*path*); *ng\_ID\_t*\ **ng\_node\_id\_node**(*const char \*node*); *ng\_ID\_t*\ **ng\_node\_name**(*ng\_ID\_t id*, *char \*name*); *ng\_ID\_t*\ **ng\_node\_type**(*ng\_ID\_t id*, *char \*type*); *int*\ **ng\_peer\_hook\_id**(*ng\_ID\_t id*, *const char \*hook*, *char \*peerhook*); ## DESCRIPTION The **snmp\_netgraph** module implements a number of tables and scalars that enable remote access to the netgraph subsystem. It also exports a number of global variables and functions, that allow other modules to easily use the netgraph system. If upon start up of the module the variable *begemotNgControlNodeName* is not empty the module opens a netgraph socket and names that socket node. If the variable is empty, the socket is created, as soon as the variable is written with a non-empty name. The socket can be closed by writing an empty string to the variable. The socket itself and its name are available in *snmp\_node* and *snmp\_nodename*. ### SENDING AND RECEIVING MESSAGES AND DATA There are three functions for sending control message: - **ng\_output**() sends a control message along the given *path*. - **ng\_output\_node**() sends a control message to the node with name *node* and - **ng\_output\_id**() sends a control message to the node with node id *id*. Each of these functions takes the following arguments: - *cookie* is the node specific command cookie, - *opcode* is the node specific code for the operation to perform, - *arg* is a pointer to the message itself. This message must start with a *struct* *ng\_mesg*. - *arglen* is the overall length of the message (header plus arguments). The functions return the message id that can be used to match incoming responses or -1 if an error occurs. Another class of functions is used to send a control message and to wait for a matching response. Note, that this operation blocks the daemon, so use it only if you are sure that the response will happen. There is a maximum timeout that is configurable in the MIB variable *begemotNgTimeout*. Other messages arriving while the functions are waiting for the response are queued and delivered on the next call to the module's idle function. - **ng\_dialog**() sends a control message along the given *path* and waits for a matching response. - **ng\_dialog\_node**() sends a control message to the node with name *node* and waits for a matching response. - **ng\_dialog\_id**() sends a control message to the node with id *id* and waits for a matching response. All three functions take the same arguments as the **ng\_output\***() functions. The functions return the response message in a buffer allocated by [malloc(3)](/malloc/3.md) or NULL in case of an error. The maximum size of the response buffer can be configured in the variable *begemotNgResBufSiz*. A data message can be send with the function **ng\_send\_data**(). This function takes the name of the *snmp\_node*'s hook through which to send the data, a pointer to the message buffer and the size of the message. It returns -1 if an error happens. ### ASYNCHRONOUS CONTROL AND DATA MESSAGES A module can register functions to asynchronously receive control and data message. The function **ng\_register\_cookie**() registers a control message receive function. If a control message is received, that is not consumed by the dialog functions, the list of registered control message receive functions is scanned. If the cookie in the received message is the same as the *cookie* argument to the **ng\_register\_cookie**() call and the *id* argument to the **ng\_register\_cookie**() call was either 0 or equals the node id which sent the control message, the handler function *func* is called with a pointer to the received message, the hook on which the message was received (or NULL if it was received not on a hook), the id of the sender's node and the *uarg* argument of the registration call. The handler function should not modify the contents of the message, because more than one function may be registered to the same cookie and node id. A control message registration can be undone by calling **ng\_unregister\_cookie**() with the return value of the registration call. If an error occurs while registering, **ng\_register\_cookie**() returns NULL. A module can call **ng\_register\_hook**() to register a callback for data messages on one of the *snmp\_node*'s hooks. If a data message is received on that hook, the callback function *func* is called with the hook name, a pointer to the data message, the size of the message and the argument *uarg* to the registration function. The message should be treated as read-only. A data message registration can be undone by calling **ng\_unregister\_hook**() with the return value of the registration call. If an error occurs while registering, **ng\_register\_hook**() returns NULL. The function **ng\_unregister\_module**() removes all control and data registrations for that module. ### FINDING NODES AND NODE CHARACTERISTICS The function **ng\_node\_id**() returns the id of the node addressed by *path* or 0 if the node does not exists. The function **ng\_node\_id\_node**() returns the id of the node with name *node* or 0 if the node does not exist. The function **ng\_node\_node**() retrieves the name of the node with id *id* and writes it to the buffer pointed to by *name*. This buffer should be at least NG\_NODESIZ bytes long. The function returns the node id or 0 if the node is not found. The function **ng\_node\_type**() retrieves the name of the node with id *id* and writes it to the buffer pointed to by *type*. This buffer should be at least NG\_TYPESIZ bytes long. The function returns the node id or 0 if the node is not found. The function **ng\_peer\_hook\_id**() writes the name of the peer hook of the hook *hook* on the node with *id* to the buffer pointed to by *peer\_hook*. The buffer should be at least NG\_HOOKSIZ bytes long. The function returns 0 if the node and the hook is found, -1 otherwise. The function skips intermediate tee nodes (see [ng\_tee(4)](/ng_tee/4.md)). The function **ng\_next\_node\_id**() returns the node id of the peer node that is on the other side of hook *hook* of node *id*. If *type* is not NULL, the function checks, that the peer node's type is *type*. The function skips intermediate tee nodes (see [ng\_tee(4)](/ng_tee/4.md)). It returns the node id of the peer node or 0 if an error occurs or the types do not match. ### CHANGING THE GRAPH A number of functions can be used to create or destroy nodes and hooks. The function **ng\_mkpeer\_id**() creates a new node of type *type* whose hook *peerhook* will be connected to *hook* of node *id*. If *name* is not NULL the new node is named with this name. The function returns The node id of the new node or 0 if an error happens. The functions **ng\_connect\_node**() and **ng\_connect\_id**() make a new hook connecting *ourhook* of the modules socket node *snmp\_node* to *peerhook* of the node identified by id *id* or name *node*. The functions return 0 on success or -1 otherwise. The function **ng\_connect2\_id**() connects hook *ourhook* of the node with id *id* to hook *peerhook* of the node with id *peer*. The functions return 0 on success or -1 otherwise. The function **ng\_connect2\_tee\_id**() does the same as **ng\_connect2\_id**() except, that it puts an unnamed tee node between the two nodes. The function **ng\_rmhook**() removes hook *hook* on the module's *snmp\_node*. The function **ng\_rmhook\_id**() removes hook *hook* on the node with id *id*. The function **ng\_rmhook\_tee\_id**() additionally shuts down all tee nodes between the node and the first non-tee peer. The function **ng\_shutdown\_id**() destroys the given node. ## FILES - */usr/share/bsnmp/defs/netgraph\_tree.def* The description of the MIB tree implemented by **snmp\_netgraph**. - */usr/share/bsnmp/mibs/BEGEMOT-NETGRAPH.txt* This is the MIB that is implemented by this module. ## SEE ALSO [gensnmptree(1)](/gensnmptree/1.md), [snmpmod(3)](/snmpmod/3.md) ## AUTHORS Hartmut Brandt ⟨*harti@FreeBSD.org*⟩