AGENTX(3) FreeBSD Library Functions Manual AGENTX(3)
NAME
agentx_log_fatal, agentx_log_warn, agentx_log_info, agentx_log_debug,
agentx, agentx_connect, agentx_retry, agentx_read, agentx_write,
agentx_wantwrite, agentx_free, agentx_session, agentx_session_free,
agentx_context, agentx_context_object_find, agentx_context_object_nfind,
agentx_context_uptime, agentx_context_free, agentx_region,
agentx_region_free, agentx_agentcaps, agentx_agentcaps_free,
agentx_index_integer_new, agentx_index_integer_any,
agentx_index_integer_value, agentx_index_integer_dynamic,
agentx_index_string_dynamic, agentx_index_nstring_dynamic,
agentx_index_oid_dynamic, agentx_index_noid_dynamic,
agentx_index_ipaddress_dynamic, agentx_index_free, agentx_object,
agentx_object_free, agentx_varbind_integer, agentx_varbind_string,
agentx_varbind_nstring, agentx_varbind_printf, agentx_varbind_null,
agentx_varbind_oid, agentx_varbind_object, agentx_varbind_index,
agentx_varbind_ipaddress, agentx_varbind_counter32,
agentx_varbind_gauge32, agentx_varbind_unsigned32,
agentx_varbind_timeticks, agentx_varbind_opaque,
agentx_varbind_counter64, agentx_varbind_notfound, agentx_varbind_error,
agentx_varbind_request, agentx_varbind_get_index_integer,
agentx_varbind_get_index_string, agentx_varbind_get_index_oid,
agentx_varbind_get_index_ipaddress, agentx_varbind_set_index_integer,
agentx_varbind_set_index_string, agentx_varbind_set_index_nstring,
agentx_varbind_set_index_oid, agentx_varbind_set_index_object,
agentx_varbind_set_index_ipaddress - manage an interface to an agentx
master
SYNOPSIS
#include <agentx.h>
extern void
(*agentx_log_fatal)(const char *fmt, ...);
extern void
(*agentx_log_warn)(const char *fmt, ...);
extern void
(*agentx_log_info)(const char *fmt, ...);
extern void
(*agentx_log_debug)(const char *fmt, ...);
struct agentx *
agentx(void (*nofd)(struct agentx *, void *, int), void *cookie);
void
agentx_connect(struct agentx *sa, int fd);
void
agentx_retry(struct agentx *sa);
void
agentx_read(struct agentx *sa);
void
agentx_write(struct agentx *sa);
extern void
(*agentx_wantwrite)(struct agentx *sa, int fd);
void
agentx_free(struct agentx *sa);
struct agentx_session *
agentx_session(struct agentx *sa, uint32_t oid[], size_t oidlen,
const char *descr, uint8_t timeout);
void
agentx_session_free(struct agentx_session *sas);
struct agentx_context *
agentx_context(struct agentx_session *sas, const char *name);
struct agentx_object *
agentx_context_object_find(struct agentx_context *sac,
const uint32_t oid[], size_t oidlen, int active, int instance);
struct agentx_object *
agentx_context_object_nfind(struct agentx_context *,
const uint32_t oid[], size_t oidlen, int active, int inclusive);
uint32_t
agentx_context_uptime(struct agentx_context *sac);
void
agentx_context_free(struct agentx_context *sac);
struct agentx_agentcaps *
agentx_agentcaps(struct agentx_context *sac, uint32_t oid[],
size_t oidlen, const char *descr);
void
agentx_agentcaps_free(struct agentx_agentcaps *saa);
struct agentx_region *
agentx_region(struct agentx_context *sac, uint32_t oid[], size_t oidlen,
uint8_t timeout);
void
agentx_region_free(struct agentx_region *sar);
struct agentx_index *
agentx_index_integer_new(struct agentx_region *sar, uint32_t oid[],
size_t oidlen);
struct agentx_index *
agentx_index_integer_any(struct agentx_region *sar, uint32_t oid[],
size_t oidlen);
struct agentx_index *
agentx_index_integer_value(struct agentx_region *sar, uint32_t oid[],
size_t oidlen, int32_t value);
struct agentx_index *
agentx_index_integer_dynamic(struct agentx_region *sar, uint32_t oid[] ,
size_t, oidlen");
struct agentx_index *
agentx_index_string_dynamic(struct agentx_region *sar, uint32_t oid[],
size_t oidlen);
struct agentx_index *
agentx_index_nstring_dynamic(struct agentx_region *sar, uint32_t oid[],
size_t oidlen, size_t slen);
struct agentx_index *
agentx_index_oid_dynamic(struct agentx_region *sar, uint32_t oid[],
size_t oidlen);
struct agentx_index *
agentx_index_noid_dynamic(struct agentx_region *sar, uint32_t oid[],
size_t oidlen, size_t vlen);
struct agentx_index *
agentx_index_ipaddress_dynamic(struct agentx_region *sar, uint32_t oid[],
size_t oidlen);
void
agentx_index_free(struct agentx_index *sai);
struct agentx_object *
agentx_object(struct agentx_region *sar, uint32_t oid[], size_t oidlen,
struct agentx_index *index[], size_t indexlen, int implied,
void (*getcb)(struct agentx_varbind *));
void
agentx_object_free(struct agentx_object *sao);
void
agentx_varbind_integer(struct agentx_varbind *sav, int32_t value);
void
agentx_varbind_string(struct agentx_varbind *sav, const char *value);
void
agentx_varbind_nstring(struct agentx_varbind *sav, const char *value,
size_t slen);
void
agentx_varbind_printf(struct agentx_varbind *sav, const char *fmt, ...);
void
agentx_varbind_null(struct agentx_varbind *sav);
void
agentx_varbind_oid(struct agentx_varbind *sav, const uint32_t oid[],
size_t oidlen);
void
agentx_varbind_object(struct agentx_varbind *sav,
struct agentx_object *sao);
void
agentx_varbind_index(struct agentx_varbind *sav,
struct agentx_index *sai);
void
agentx_varbind_ipaddress(struct agentx_varbind *sav,
const struct in_addr *addr);
void
agentx_varbind_counter32(struct agentx_varbind *sav, uint32_t value);
void
agentx_varbind_gauge32(struct agentx_varbind *sav, uint32_t value);
void
agentx_varbind_unsigned32(struct agentx_varbind *sav, uint32_t value);
void
agentx_varbind_timeticks(struct agentx_varbind *sav, uint32_t value);
void
agentx_varbind_opaque(struct agentx_varbind *sav, const char *value,
size_t slen);
void
agentx_varbind_counter64(struct agentx_varbind *sav, uint64_t value);
void
agentx_varbind_notfound(struct agentx_varbind *sav);
void
agentx_varbind_error(struct agentx_varbind *sav);
enum agentx_request_type
agentx_varbind_request(struct agentx_varbind *sav);
int32_t
agentx_varbind_get_index_integer(struct agentx_varbind *sav,
struct agentx_index *sai);
const unsigned char *
agentx_varbind_get_index_string(struct agentx_varbind *sav,
struct agentx_index *sai, size_t *slen, int *implied);
const uint32_t *
agentx_varbind_get_index_oid(struct agentx_varbind *sav,
struct agentx_index *sai, size_t *oidlen, int *implied);
const struct in_addr *
agentx_varbind_get_index_ipaddress(struct agentx_varbind *sav,
struct agentx_index *sai);
void
agentx_varbind_set_index_integer(struct agentx_varbind *sav,
struct agentx_index *sai, int32_t value);
void
agentx_varbind_set_index_string(struct agentx_varbind *sav,
struct agentx_index *sai, const unsigned char *value);
void
agentx_varbind_set_index_nstring(struct agentx_varbind *sav,
struct agentx_index *sai, const unsigned char *value, size_t slen);
void
agentx_varbind_set_index_oid(struct agentx_varbind *sav,
struct agentx_index *sai, const uint32_t *oid, size_t oidlen);
void
agentx_varbind_set_index_object(struct agentx_varbind *sav,
struct agentx_index *sai, struct agentx_object *sao);
void
agentx_varbind_set_index_ipaddress(struct agentx_varbind *sav,
struct agentx_index *sai, const struct in_addr *addr);
enum agentx_request_type {
AGENTX_REQUEST_TYPE_GET,
AGENTX_REQUEST_TYPE_GETNEXT,
AGENTX_REQUEST_TYPE_GETNEXTINCLUSIVE
};
#define AGENTX_MASTER_PATH "/var/agentx/master"
#define AGENTX_OID_MAX_LEN 128
#define AGENTX_OID_INDEX_MAX_LEN 10
#define AGENTX_OID(...)
#define AGENTX_MIB2 1, 3, 6, 1, 2, 1
#define AGENTX_ENTERPRISES 1, 3, 6, 1, 4, 1
DESCRIPTION
The agentx functions allow an application to describe their MIB layout
and provide an fd based interface to control the internal agentx state.
agentx is not thread safe.
DESCRIBING THE MIB
agentx is a framework to abstract away the agentx protocol from the
application. For the framework to report information to the
administrator, the agentx_log_fatal(), agentx_log_warn(),
agentx_log_info() and agentx_log_debug() functions must be set.
When sa is created by agentx() or when sa detects that there is no
connection to the agentx master, it calls out to nofd with itself, cookie
and an integer close as arguments. If close is not set, nofd() is
expected to set up a new fd to the agentx master. This one can usually
be found at AGENTX_MASTER_PATH. This fd can be returned to sa at any
moment via agentx_connect(), but must always be done as a result of a
call to nofd(). Once agentx_connect() has been called, the application
is responsible for retrieving data when available on fd by calling
agentx_read(). If nonblocking writes are desirable, the
agentx_wantwrite() pointer can be set to an application function and will
be called as soon as there's data available to be written out. Once fd
is ready for a write, the function agentx_write() should be called.
If any of the session, agentcaps, region, index, or objects failed to
enable correctly (as can be seen by the admin through the logs) they can
be retried through agentx_retry().
sa can be freed via agentx_free(). It will close all active sessions and
free all derived objects. Once freed, no new objects can be derived from
the freed objects. Once all sessions are closed, it will call out to
nofd() with close set, indicating that the application can clean up any
context related to sa.
On top of the sa connection a agentx_session must be set up. Normally
there's only a single session per sa. The timeout argument specifies the
maximum time in seconds the master should wait for a reply before
determining we're gone. If set to 0, the agentx master determines the
timeout. The oid and oidlen combination identifies the subagent and will
be visible through the agentxSessionObjectID object on the agentx master.
The descr is a short displaystring description of the agent and will be
visible through the agentxSessionDescr object on the agentx master.
The agentx_context is the SNMPv3 context in which the objects operate and
is built on top of agentx_session sas. If the default context is
requested, name must be NULL.
agentx_agentcaps() registers an entry in the agentx master's sysORTable.
The oid, oidlen combination should point to an AGENT-CAPABILITIES object
which describes the capabilities of the subagent. descr should be a
textual description of the capabilities. If no AGENT-CAPABILITIES object
is defined, this function can be omitted.
A agentx_region indicates a region inside the object-tree for which get-
and set-requests will be queried. If the OID has already been claimed by
another subagent, it will try to claim it on a lower priority. The
timeout parameter overrules its agentx_session counterpart.
For objects in a table one or more agentx_index elements must be
supplied. agentx_index_integer_new(), agentx_index_integer_any() and
agentx_index_integer_value() register an integer index at the agentx
master. Of these agentx_index_integer_new() registers a new, previously
unused, index; agentx_index_integer_any() registers the first available
index; and agentx_index_integer_value() tries to register a specific
value. If the registration of an index fails, an error will be logged
and all objects using it will remain disabled. The OID where the index
should be registered is documented by the MIB. These registered indices
are usually used for tables where multiple subagents are registered.
For dynamic indices the agentx_index_*_dynamic functions can be used,
based on the data type of the object. The data type should match the
data type in the MIB at the oid object. Indices of data type string or
oid with a fixed length should be created via
agentx_index_nstring_dynamic() and agentx_index_noid_dynamic()
respectively.
agentx_object is an object as described in the MIB. For scalar objects
(without indices) the final zero must be omitted. For table entries a
list of 1 or more indices must be added via index and indexlen. The list
of indices must match the INDEX list on the ENTRY object in the MIB. The
total length of the OID, including indices, can't be more than
AGENTX_OID_MAX_LEN and indexlen can't be more than
AGENTX_OID_INDEX_MAX_LEN. If implied is set, the final index must be of
type OID or string and will omit the leading length indicator. This
value must only be set if specified in the MIB. getcb() will be called
for each varbind in a GET, GETNEXT or GETBULK request that matches the
object.
HANDLING GET REQUESTS
A call to getcb() must eventually result in a call to one of the
following functions:
agentx_varbind_integer() Set the return value to an int32_t value.
agentx_varbind_string() A C string wrapper around
agentx_varbind_nstring().
agentx_varbind_nstring() Set the return value to an octetstring.
agentx_varbind_printf() A printf wrapper around
agentx_varbind_nstring().
agentx_varbind_null() Set the return value to null.
agentx_varbind_oid() Set the return value to an OID value.
agentx_varbind_object() An agentx_object wrapper around
agentx_varbind_oid().
agentx_varbind_index() An agentx_index wrapper around
agentx_varbind_oid().
agentx_varbind_ipaddress() Set the return value to ipaddress.
agentx_varbind_counter32() Set the return value to an uint32_t of type
counter32.
agentx_varbind_gauge32() Set the return value to an uint32_t of type
gauge32.
agentx_varbind_unsigned32()
A wrapper around agentx_varbind_gauge32.
agentx_varbind_timeticks() Set the return value to an uint32_t of type
timeticks.
agentx_varbind_opaque() Set the return value to an opaque value.
agentx_varbind_counter64() Set the return value to an uint64_t of type
counter64.
agentx_varbind_notfound() When the request is of type GET, return a
nosuchinstance error. When the request is of
type GETNEXT or GETBULK, return an
endofmibview error. On endofmibview the next
object is queried. This function can only be
called on objects that contain one or more
*_dynamic indices.
agentx_varbind_error() Returns a GENERR error to the client.
For objects containing *_dynamic indices the following support functions
are to be used:
agentx_varbind_request()
Returns whether the request is of type GET, GETNEXT or
GETNEXTINCLUSIVE.
agentx_varbind_get_index_integer()
Retrieve a single int32_t index value.
agentx_varbind_get_index_string()
Retrieve an octetstring index value. slen is the length of the
string and implied indicates if the next value for this index
should be length sorted before alphabetically sorted.
agentx_varbind_get_index_oid()
Retrieve an oid index value. oidlen is the length of the oid and
implied indicates if the next value for this index should be
length sorted before alphabetically sorted.
agentx_varbind_get_index_ipaddress()
Retrieve an ipaddress index value.
agentx_varbind_set_index_integer()
Sets a single int32_t index value.
agentx_varbind_set_index_string()
A C string wrapper around agentx_varbind_set_index_nstring().
agentx_varbind_set_index_nstring()
Set an octetstring index value.
agentx_varbind_set_index_oid()
Set an oid index value.
agentx_varbind_set_index_object()
A agentx_object wrapper around agentx_varbind_set_index_oid().
agentx_varbind_set_index_ipaddress()
Set an ipaddress index value.
For these functions sai must be part of the object the request is
performed on. The function type must also match the data type of sai.
Other functions that can retrieve information from the agentx context
are:
agentx_context_object_find()
Find an agentx_object created inside agentx_context sac based on
oid and oidlen. If active is set the object must be reachable
from the agentx master, else NULL is returned. If oid can be an
instance, find its parent object.
agentx_context_object_nfind()
Find the next agentx_object created inside agentx_context sac
based on oid and oidlen. If active is set the object must be
reachable from the agentx master, else NULL is returned. If
inclusive is set, the object returned may also exactly match oid.
agentx_context_uptime()
Returns the sysuptime in seconds for sac in timeticks.
SEE ALSO
snmp(1), snmpd(8)
STANDARDS
M. Daniele, B. Wijnen, M. Ellison, Ed., and D. Francisco, Ed., Agent
Extensibility (AgentX) Protocol Version 1, RFC 2741, January 2000.
L. Heintz, S. Gudur, and M. Ellison, Ed., Definitions of Managed Objects
for Extensible SNMP Agents, RFC 2742, January 2000.
HISTORY
The agentx API first appeared in OpenBSD 6.9.
AUTHORS
Martijn van Duren <
[email protected]>
FreeBSD 14.1-RELEASE-p8 October 14, 2022 FreeBSD 14.1-RELEASE-p8