NAME
subagentx_log_fatal
,
subagentx_log_warn
,
subagentx_log_info
,
subagentx_log_debug
,
subagentx
,
subagentx_connect
,
subagentx_read
,
subagentx_write
,
subagentx_wantwrite
,
subagentx_free
,
subagentx_session
,
subagentx_session_free
,
subagentx_context
,
subagentx_context_object_find
,
subagentx_context_object_nfind
,
subagentx_context_uptime
,
subagentx_context_free
,
subagentx_region
,
subagentx_region_free
,
subagentx_agentcaps
,
subagentx_agentcaps_free
,
subagentx_index_integer_new
,
subagentx_index_integer_any
,
subagentx_index_integer_value
,
subagentx_index_integer_dynamic
,
subagentx_index_string_dynamic
,
subagentx_index_nstring_dynamic
,
subagentx_index_oid_dynamic
,
subagentx_index_noid_dynamic
,
subagentx_index_ipaddress_dynamic
,
subagentx_index_free
,
subagentx_object
,
subagentx_object_free
,
subagentx_varbind_integer
,
subagentx_varbind_string
,
subagentx_varbind_nstring
,
subagentx_varbind_printf
,
subagentx_varbind_null
,
subagentx_varbind_oid
,
subagentx_varbind_object
,
subagentx_varbind_index
,
subagentx_varbind_ipaddress
,
subagentx_varbind_counter32
,
subagentx_varbind_gauge32
,
subagentx_varbind_timeticks
,
subagentx_varbind_opaque
,
subagentx_varbind_counter64
,
subagentx_varbind_notfound
,
subagentx_varbind_error
,
subagentx_varbind_request
,
subagentx_varbind_get_index_integer
,
subagentx_varbind_get_index_string
,
subagentx_varbind_get_index_oid
,
subagentx_varbind_get_index_ipaddress
,
subagentx_varbind_set_index_integer
,
subagentx_varbind_set_index_string
,
subagentx_varbind_set_index_nstring
,
subagentx_varbind_set_index_oid
,
subagentx_varbind_set_index_object
,
subagentx_varbind_set_index_ipaddress
—
manage an interface to an agentx
master
SYNOPSIS
#include
<subagentx.h>
extern void
(*subagentx_log_fatal)
(const
char *fmt,
...);
extern void
(*subagentx_log_warn)
(const
char *fmt,
...);
extern void
(*subagentx_log_info)
(const
char *fmt,
...);
extern void
(*subagentx_log_debug)
(const
char *fmt,
...);
struct subagentx *
subagentx
(void
(*nofd)(struct subagentx *, void *, int),
void *cookie);
void
subagentx_connect
(struct
subagentx *sa, int
fd);
void
subagentx_read
(struct
subagentx *sa);
void
subagentx_write
(struct
subagentx *sa);
extern void
(*subagentx_wantwrite)
(struct
subagentx *sa, int
fd);
void
subagentx_free
(struct
subagentx *sa);
struct subagentx_session *
subagentx_session
(struct subagentx
*sa, uint32_t oid[], size_t
oidlen, const char *descr,
uint8_t timeout);
void
subagentx_session_free
(struct
subagentx_session *sas);
struct subagentx_context *
subagentx_context
(struct
subagentx_session *sas,
const char *name);
struct subagentx_object *
subagentx_context_object_find
(struct
subagentx_context *sac, const uint32_t oid[],
size_t oidlen, int active,
int instance);
struct subagentx_object *
subagentx_context_object_nfind
(struct
subagentx_context *, const uint32_t oid[],
size_t oidlen, int active,
int inclusive);
uint32_t
subagentx_context_uptime
(struct
subagentx_context *sac);
void
subagentx_context_free
(struct
subagentx_context *sac);
struct subagentx_agentcaps *
subagentx_agentcaps
(struct
subagentx_context *sac, uint32_t oid[],
size_t oidlen, const char
*descr);
void
subagentx_agentcaps_free
(struct
subagentx_agentcaps *saa);
struct subagentx_region *
subagentx_region
(struct
subagentx_context *sac, uint32_t oid[],
size_t oidlen, uint8_t
timeout);
void
subagentx_region_free
(struct
subagentx_region *sar);
struct subagentx_index *
subagentx_index_integer_new
(struct
subagentx_region *sar, uint32_t oid[],
size_t oidlen);
struct subagentx_index *
subagentx_index_integer_any
(struct
subagentx_region *sar, uint32_t oid[],
size_t oidlen);
struct subagentx_index *
subagentx_index_integer_value
(struct
subagentx_region *sar, uint32_t oid[],
size_t oidlen, uint32_t
value);
struct subagentx_index *
subagentx_index_integer_dynamic
(struct
subagentx_region *sar, uint32_t oid[] ,
size_t, oidlen");
struct subagentx_index *
subagentx_index_string_dynamic
(struct
subagentx_region *sar, uint32_t oid[],
size_t oidlen);
struct subagentx_index *
subagentx_index_nstring_dynamic
(struct
subagentx_region *sar, uint32_t oid[],
size_t oidlen, size_t slen);
struct subagentx_index *
subagentx_index_oid_dynamic
(struct
subagentx_region *sar, uint32_t oid[],
size_t oidlen);
struct subagentx_index *
subagentx_index_noid_dynamic
(struct
subagentx_region *sar, uint32_t oid[],
size_t oidlen, size_t vlen);
struct subagentx_index *
subagentx_index_ipaddress_dynamic
(struct
subagentx_region *sar, uint32_t oid[],
size_t oidlen);
void
subagentx_index_free
(struct
subagentx_index *sai);
struct subagentx_object *
subagentx_object
(struct
subagentx_region *sar, uint32_t oid[],
size_t oidlen, struct subagentx_index
*index[], size_t indexlen, int
implied, void (*getcb)(struct subagentx_varbind
*));
void
subagentx_object_free
(struct
subagentx_object *sao);
void
subagentx_varbind_integer
(struct
subagentx_varbind *sav,
uint32_t value);
void
subagentx_varbind_string
(struct
subagentx_varbind *sav,
const char *value);
void
subagentx_varbind_nstring
(struct
subagentx_varbind *sav, const char *value,
size_t slen);
void
subagentx_varbind_printf
(struct
subagentx_varbind *sav, const char *fmt,
...);
void
subagentx_varbind_null
(struct
subagentx_varbind *sav);
void
subagentx_varbind_oid
(struct
subagentx_varbind *sav, const uint32_t oid[],
size_t oidlen);
void
subagentx_varbind_object
(struct
subagentx_varbind *sav, struct subagentx_object
*sao);
void
subagentx_varbind_index
(struct
subagentx_varbind *sav, struct subagentx_index
*sai);
void
subagentx_varbind_ipaddress
(struct
subagentx_varbind *sav, const struct in_addr
*addr);
void
subagentx_varbind_counter32
(struct
subagentx_varbind *sav,
uint32_t value);
void
subagentx_varbind_gauge32
(struct
subagentx_varbind *sav,
uint32_t value);
void
subagentx_varbind_timeticks
(struct
subagentx_varbind *sav, uint32_t value);
void
subagentx_varbind_opaque
(struct
subagentx_varbind *sav, const char *value,
size_t slen);
void
subagentx_varbind_counter64
(struct
subagentx_varbind *sav,
uint64_t value);
void
subagentx_varbind_notfound
(struct
subagentx_varbind *sav);
void
subagentx_varbind_error
(struct
subagentx_varbind *sav);
enum subagentx_request_type
subagentx_varbind_request
(struct
subagentx_varbind *sav);
uint32_t
subagentx_varbind_get_index_integer
(struct
subagentx_varbind *sav, struct subagentx_index
*sai);
const unsigned char *
subagentx_varbind_get_index_string
(struct
subagentx_varbind *sav, struct subagentx_index
*sai, size_t *slen, int
*implied);
const uint32_t *
subagentx_varbind_get_index_oid
(struct
subagentx_varbind *sav, struct subagentx_index
*sai, size_t *oidlen, int
*implied);
const struct in_addr *
subagentx_varbind_get_index_ipaddress
(struct
subagentx_varbind *sav, struct subagentx_index
*sai);
void
subagentx_varbind_set_index_integer
(struct
subagentx_varbind *sav, struct subagentx_index
*sai, uint32_t value);
void
subagentx_varbind_set_index_string
(struct
subagentx_varbind *sav, struct subagentx_index
*sai, const unsigned char *value);
void
subagentx_varbind_set_index_nstring
(struct
subagentx_varbind *sav, struct subagentx_index
*sai, const unsigned char *value,
size_t slen);
void
subagentx_varbind_set_index_oid
(struct
subagentx_varbind *sav, struct subagentx_index
*sai, const uint32_t *oid,
size_t oidlen);
void
subagentx_varbind_set_index_object
(struct
subagentx_varbind *sav, struct subagentx_index
*sai, struct subagentx_object *sao);
void
subagentx_varbind_set_index_ipaddress
(struct
subagentx_varbind *sav, struct subagentx_index
*sai, const struct in_addr *addr);
enum subagentx_request_type { SUBAGENTX_REQUEST_TYPE_GET, SUBAGENTX_REQUEST_TYPE_GETNEXT, SUBAGENTX_REQUEST_TYPE_GETNEXTINCLUSIVE };
#define SUBAGENTX_AGENTX_MASTER
"/var/agentx/master"
#define SUBAGENTX_OID_MAX_LEN 128
#define SUBAGENTX_OID_INDEX_MAX_LEN 10
#define SUBAGENTX_OID(...)
#define SUBAGENTX_MIB2 1, 3, 6, 1, 2, 1
#define SUBAGENTX_ENTERPRISES 1, 3, 6, 1, 4, 1
DESCRIPTION
The subagentx
functions allow an
application to describe their MIB layout and provide an
fd based interface to control the internal agentx
state. subagentx
is not thread safe.
DESCRIBING THE MIB
subagentx
is a framework to abstract away
the agentx protocol from the application. For the framework to report
information to the administrator, the
subagentx_log_fatal
(),
subagentx_log_warn
(),
subagentx_log_info
()
and
subagentx_log_debug
()
functions must be set.
When sa is created by
subagentx
()
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
SUBAGENTX_AGENTX_MASTER
. This
fd can be returned to sa at any
moment via
subagentx_connect
(),
but must always be done as a result of a call to
nofd
(). Once
subagentx_connect
() has been called the application
is responsible for retrieving data when available on
fd by calling
subagentx_read
().
If nonblocking writes are desirable the
subagentx_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 write the function
subagentx_write
()
should be called.
sa can be freed via
subagentx_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 subagentx_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 visiable through the agentxSessionDescr object on the agentx master.
The subagentx_context is the SNMPv3 context in which the objects operate and is built on top of subagentx_session sas. If the default context is requested name must be NULL.
subagentx_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 subagentx_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 subagentx_session counterpart.
For objects in a table one or
more subagentx_index elements must be supplied.
subagentx_index_integer_new
(),
subagentx_index_integer_any
()
and
subagentx_index_integer_value
()
register an integer index at the agentx master. Of these
subagentx_index_integer_new
() registers a new,
previously unused, index;
subagentx_index_integer_any
() registers the first
available index; and subagentx_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
subagentx_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
subagentx_index_nstring_dynamic
()
and
subagentx_index_noid_dynamic
()
respectively.
subagentx_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
SUBAGENTX_OID_MAX_LEN
and indexlen can't be more
than SUBAGENTX_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:
subagentx_varbind_integer
()- Set the return value to an uint32_t value.
subagentx_varbind_string
()- A C string wrapper around
subagentx_varbind_nstring
(). subagentx_varbind_nstring
()- Set the return value to an octetstring.
subagentx_varbind_printf
()- A printf wrapper around
subagentx_varbind_nstring
(). subagentx_varbind_null
()- Set the return value to null.
subagentx_varbind_oid
()- Set the return value to an OID value.
subagentx_varbind_object
()- An subagentx_object wrapper around
subagentx_varbind_oid
(). subagentx_varbind_index
()- An subagentx_index wrapper around
subagentx_varbind_oid
(). subagentx_varbind_ipaddress
()- Set the return value to ipaddress.
subagentx_varbind_counter32
()- Set the return value to an uint32_t of type counter32.
subagentx_varbind_gauge32
()- Set the return value to an uint32_t of type gauge32.
subagentx_varbind_timeticks
()- Set the return value to an uint32_t of type timeticks.
subagentx_varbind_opaque
()- Set the return value to an opaque value.
subagentx_varbind_counter64
()- Set the return value to an uint64_t of type counter64.
subagentx_varbind_notfound
()- When the request is of type GET return an 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.
subagentx_varbind_error
()- Returns a GENERR error to the client.
For objects containing *_dynamic indices the following support functions are to be used:
subagentx_varbind_request
()- Returns whether the request is of type GET, GETNEXT or GETNEXTINCLUSIVE.
subagentx_varbind_get_index_integer
()- Retrieve a single uint32_t index value.
subagentx_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.
subagentx_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.
subagentx_varbind_get_index_ipaddress
()- Retrieve an ipaddress index value.
subagentx_varbind_set_index_integer
()- Sets a single uint32_t index value.
subagentx_varbind_set_index_string
()- A C string wrapper around
subagentx_varbind_set_index_nstring
(). subagentx_varbind_set_index_nstring
()- Set an octetstring index value.
subagentx_varbind_set_index_oid
()- Set an oid index value.
subagentx_varbind_set_index_object
()- A subagentx_object wrapper around
subagentx_varbind_set_index_oid
(). subagentx_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:
subagentx_context_object_find
()- Find a subagentx_object created inside subagentx_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.
subagentx_context_object_nfind
()- Find the next subagentx_object created inside subagentx_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.
subagentx_context_uptime
()- Returns the sysuptime in seconds for sac in timeticks.
SEE ALSO
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 subagentx
API first appeared in
OpenBSD 6.8.
AUTHORS
Martijn van Duren <martijn@openbsd.org>