snmpmod(3)

NAME

INSERT_OBJECT_OID_LINK_INDEX, INSERT_OBJECT_INT_LINK_INDEX, FIND_OBJECT_OID_LINK_INDEX, NEXT_OBJECT_OID_LINK_INDEX, FIND_OBJECT_INT_LINK_INDEX, NEXT_OBJECT_INT_LINK_INDEX, INSERT_OBJECT_OID_LINK, INSERT_OBJECT_INT_LINK,

FIND_OBJECT_OID_LINK

NEXT_OBJECT_OID_LINK, FIND_OBJECT_INT_LINK,

NEXT_OBJECT_INT_LINK

INSERT_OBJECT_OID, INSERT_OBJECT_INT, FIND_OBJECT_OID,

FIND_OBJECT_INT

NEXT_OBJECT_OID, NEXT_OBJECT_INT, this_tick, start_tick,

get_ticks,

systemg, comm_define, community, oid_zeroDotZero,

reqid_allocate,

reqid_next, reqid_base, reqid_istype, reqid_type,

timer_start,

timer_start_repeat, timer_stop, fd_select, fd_deselect,

fd_suspend,

fd_resume, or_register, or_unregister, buf_alloc, buf_size, snmp_input_start, snmp_input_finish, snmp_output,

snmp_send_port,

snmp_send_trap, string_save, string_commit, string_rollback,

string_get,

string_get_max, string_free, ip_save, ip_rollback,

ip_commit, ip_get,

oid_save, oid_rollback, oid_commit, oid_get, index_decode,

index_compare,

index_compare_off, index_append, index_append_off - SNMP

daemon loadable

module interface

LIBRARY

Begemot SNMP library (libbsnmp, -lbsnmp)

SYNOPSIS

#include <bsnmp/snmpmod.h>
INSERT_OBJECT_OID_LINK_INDEX(PTR, LIST, LINK, INDEX);
INSERT_OBJECT_INT_LINK_INDEX(PTR, LIST, LINK, INDEX);
FIND_OBJECT_OID_LINK_INDEX(LIST, OID, SUB, LINK, INDEX);
FIND_OBJECT_INT_LINK_INDEX(LIST, OID, SUB, LINK, INDEX);
NEXT_OBJECT_OID_LINK_INDEX(LIST, OID, SUB, LINK, INDEX);
NEXT_OBJECT_INT_LINK_INDEX(LIST, OID, SUB, LINK, INDEX);
INSERT_OBJECT_OID_LINK(PTR, LIST, LINK);
INSERT_OBJECT_INT_LINK(PTR, LIST, LINK);
FIND_OBJECT_OID_LINK(LIST, OID, SUB, LINK);
FIND_OBJECT_INT_LINK(LIST, OID, SUB, LINK);
NEXT_OBJECT_OID_LINK(LIST, OID, SUB, LINK);
NEXT_OBJECT_INT_LINK(LIST, OID, SUB, LINK);
INSERT_OBJECT_OID(PTR, LIST);
INSERT_OBJECT_INT(PTR, LIST);
FIND_OBJECT_OID(LIST, OID, SUB);
FIND_OBJECT_INT(LIST, OID, SUB);
NEXT_OBJECT_OID(LIST, OID, SUB);
NEXT_OBJECT_INT(LIST, OID, SUB);
extern uint64_t this_tick;
extern uint64_t start_tick;
uint64_t
get_ticks(void);
extern struct systemg systemg;
u_int
comm_define(u_int priv, const char  *descr,  struct  lmodule
*mod,
        const char *str);
const char *
comm_string(u_int comm);
extern u_int community;
extern const struct asn_oid oid_zeroDotZero;
u_int
reqid_allocate(int size, struct lmodule *mod);
int32_t
reqid_next(u_int type);
int32_t
reqid_base(u_int type);
int
reqid_istype(int32_t reqid, u_int type);
u_int
reqid_type(int32_t reqid);
void *
timer_start(u_int ticks, void (*func)(void *), void *uarg,
        struct lmodule *mod);
void *
timer_start_repeat(u_int  ticks,  u_int  repeat_ticks,  void
(*func)(void *),
        void *uarg, struct lmodule *mod);
void
timer_stop(void *timer_id);
void *
fd_select(int fd, void (*func)(int, void *), void *uarg,
        struct lmodule *mod);
void
fd_deselect(void *fd_id);
void
fd_suspend(void *fd_id);
int
fd_resume(void *fd_id);
u_int
or_register(const struct asn_oid *oid, const char *descr,
        struct lmodule *mod);
void
or_unregister(u_int or_id);
void *
buf_alloc(int tx);
size_t
buf_size(int tx);
enum snmpd_input_err
snmp_input_start(const u_char *buf, size_t len,  const  char
*source,
        struct snmp_pdu *pdu, int32_t *ip, size_t *pdulen);
enum snmpd_input_err
snmp_input_finish(struct   snmp_pdu   *pdu,   const   u_char
*rcvbuf,
        size_t rcvlen, u_char *sndbuf, size_t *sndlen,
        const  char  *source,  enum  snmpd_input_err   ierr,
int32_t ip,
        void *data);
void
snmp_output(struct  snmp_pdu  *pdu,  u_char  *sndbuf, size_t
*sndlen,
        const char *dest);
void
snmp_send_port(void *trans, const struct asn_oid *port,
        struct snmp_pdu *pdu, const struct sockaddr *addr,
        socklen_t addrlen);
void
snmp_send_trap(const struct asn_oid *oid, ...);
int
string_save(struct  snmp_value  *val,  struct   snmp_context
*ctx,
        ssize_t req_size, u_char **strp);
void
string_commit(struct snmp_context *ctx);
void
string_rollback(struct snmp_context *ctx, u_char **strp);
int
string_get(struct   snmp_value   *val,  const  u_char  *str,
ssize_t len);
int
string_get_max(struct snmp_value *val,  const  u_char  *str,
ssize_t len,
        size_t maxlen);
void
string_free(struct snmp_context *ctx);
int
ip_save(struct  snmp_value  *val,  struct snmp_context *ctx,
u_char *ipa);
void
ip_rollback(struct snmp_context *ctx, u_char *ipa);
void
ip_commit(struct snmp_context *ctx);
int
ip_get(struct snmp_value *val, u_char *ipa);
int
oid_save(struct snmp_value *val, struct snmp_context *ctx,
        struct asn_oid *oid);
void
oid_rollback(struct snmp_context *ctx, struct asn_oid *oid);
void
oid_commit(struct snmp_context *ctx);
int
oid_get(struct snmp_value *val, const struct asn_oid *oid);
int
index_decode(const  struct  asn_oid  *oid,  u_int sub, u_int
code, ...);
int
index_compare(const struct asn_oid *oid1, u_int sub,
        const struct asn_oid *oid2);
int
index_compare_off(const struct asn_oid *oid1, u_int sub,
        const struct asn_oid *oid2, u_int off);
void
index_append(struct asn_oid *dst, u_int  sub,  const  struct
asn_oid *src);
void
index_append_off(struct asn_oid *dst, u_int sub,
        const struct asn_oid *src, u_int off);

DESCRIPTION

The bsnmpd(1) SNMP daemon implements a minimal MIB which

consists of the

system group, part of the SNMP MIB, a private configuration

MIB, a trap

destination table, a UDP port table, a community table, a

module table, a

statistics group and a debugging group. All other MIBs are

support

through loadable modules. This allows bsnmpd(1) to use for

task, that

are not the classical SNMP task.

MODULE LOADING AND UNLOADING

Modules are loaded by writing to the module table. This

table is indexed

by a string, that identifies the module to the daemon. This

identifier

is used to select the correct configuration section from the

configuration files and to identify resources allocated to this mod

ule. A row in

the module table is created by writing a string of non-zero

length to the

begemotSnmpdModulePath column. This string must be the com

plete path to

the file containing the module. A module can be unloaded by

writing a

zero length string to the path column of an existing row.

Modules may depend on each other an hence must be loaded in

the correct

order. The dependencies are listed in the corresponding

manual pages.

Upon loading a module the SNMP daemon expects the module

file to a export

a global symbol config. This symbol should be a variable of

type struct

snmp_module:

typedef enum snmpd_proxy_err (*proxy_err_f)(struct sn

mp_pdu *, void *,

const struct asn_oid *, const struct sockaddr *,

socklen_t,

enum snmpd_input_err, int32_t);

struct snmp_module {

const char *comment;

int (*init)(struct lmodule *, int argc, char

*argv[]);

int (*fini)(void);

void (*idle)(void);

void (*dump)(void);

void (*config)(void);

void (*start)(void);

proxy_err_f proxy;

const struct snmp_node *tree;

u_int tree_size;

void (*loading)(const struct lmodule *, int);

};

This structure must be statically initialized and its fields

have the

following functions:

comment This is a string that will be visible in

the module

table. It should give some hint about the

function of

this module.

init This function is called upon loading the

module. The

module pointer should be stored by the

module because

it is needed in other calls and the argu

ment vector

will contain the arguments to this module

from the daemons command line. This function should

return 0 if

everything is ok or an UNIX error code

(see errno(3)).

Once the function returns 0, the fini

function is

called when the module is unloaded.

fini The module is unloaded. This gives the

module a chance

to free resources that are not automati

cally freed. Be

sure to free all memory, because daemons

tend to run

very long. This function pointer may be

NULL if it is

not needed.

idle If this function pointer is not NULL, the

function

pointed to by it is called whenever the

daemon is going

to wait for an event. Try to avoid using

this feature.

dump Whenever the daemon receives a SIGUSR1 it

dumps it

internal state via syslog(3). If the dump

field is not

NULL it is called by the daemon to dump

the state of

the module.

config Whenever the daemon receives a SIGHUP sig

nal it re

reads its configuration file. If the

config field is

not NULL it is called after reading the

configuration

file to give the module a chance to adapt

to the new

configuration.

start If not NULL this function is called after

successful

loading and initializing the module to

start its actual

operation.

proxy If the daemon receives a PDU and that PDU

has a commu

nity string whose community was registered

by this module and proxy is not NULL than this func

tion is called

to handle the PDU.

tree This is a pointer to the node array for

the MIB tree

implemented by this module.

tree_size This is the number of nodes in tree.

loading If this pointer is not NULL it is called

whenever

another module was loaded or unloaded. It

gets a

pointer to that module and a flag that is

0 for unloading and 1 for loading.

When everything is ok, the daemon merges the module's MIB

tree into its

current global tree, calls the modules init() function. If

this function

returns an error, the modules MIB tree is removed from the

global one and

the module is unloaded. If initialization is successful,

the modules

start() function is called. After it returns the loaded()

functions of

all modules (including the loaded one) are called.

When the module is unloaded, its MIB tree is removed from

the global one,

the communities, request id ranges, running timers and se

lected file

descriptors are released, the fini() function is called, the

module file

is unloaded and the loaded() functions of all other modules

are called.

IMPLEMENTING TABLES

There are a number of macros designed to help implementing

SNMP tables.

A problem while implementing a table is the support for the

GETNEXT operator. The GETNEXT operation has to find out whether, given

an arbitrary

OID, the lessest table row, that has an OID higher than the

given OID.

The easiest way to do this is to keep the table as an or

dered list of

structures each one of which contains an OID that is the in

dex of the

table row. This allows easy removal, insertion and search.

The helper macros assume, that the table is organized as a

TAILQ (see

queue(3) and each structure contains a struct asn_oid that

is used as

index. For simple tables with only a integer or unsigned

index, an

alternate form of the macros is available, that presume the

existence of

an integer or unsigned field as index field.

The macros have name of the form

{INSERT,FIND,NEXT}_OBJECT_{OID,INT}[_LINK[_INDEX]]

The INSERT_*() macros are used in the SET operation to in

sert a new table

row into the table. The FIND_*() macros are used in the GET

operation to

find a specific row in the table. The NEXT_*() macros are

used in the

GETNEXT operation to find the next row in the table. The

last two macros

return a pointer to the row structure if a row is found,

NULL otherwise.

The macros *_OBJECT_OID_*() assume the existence of a struct

asn_oid that

is used as index, the macros *_OBJECT_INT_*() assume the ex

istence of an

unsigned integer field that is used as index.

The macros *_INDEX() allow the explicit naming of the index

field in the

parameter INDEX, whereas the other macros assume that this

field is named

index. The macros *_LINK_*() allow the explicit naming of

the link field

of the tail queues, the others assume that the link field is

named link.

Explicitly naming the link field may be necessary if the

same structures

are held in two or more different tables.

The arguments to the macros are as follows:

PTR A pointer to the new structure to be inserted into

the table.

LIST A pointer to the tail queue head.

LINK The name of the link field in the row structure.

INDEX The name of the index field in the row structure.

OID Must point to the var field of the value argument to

the node

operation callback. This is the OID to search for.

SUB This is the index of the start of the table index in

the OID

pointed to by OID. This is usually the same as the

sub argument

to the node operation callback.

DAEMON TIMESTAMPS

The variable this_tick contains the tick (there are 100 SNMP

ticks in a

second) when the current PDU processing was started. The

variable

start_tick contains the tick when the daemon was started.

The function

get_ticks() returns the current tick. The number of ticks

since the daemon was started is

get_ticks() - start_tick

THE SYSTEM GROUP

The scalar fields of the system group are held in the global

variable

systemg:

struct systemg {

u_char *descr;

struct asn_oid object_id;

u_char *contact;

u_char *name;

u_char *location;

uint32_t services;

uint32_t or_last_change;

};

COMMUNITIES

The SNMP daemon implements a community table. On recipte of

a request

message the community string in that message is compared to

each of the

community strings in that table, if a match is found, the

global variable

community is set to the community identifier for that commu

nity. Community identifiers are unsigned integers. For the three stan

dard communities there are three constants defined:

#define COMM_INITIALIZE 0

#define COMM_READ 1

#define COMM_WRITE 2

community is set to COMM_INITIALIZE while the assignments in

the configuration file are processed. To COMM_READ or COMM_WRITE when

the community

strings for the read-write or read-only community are found

in the incoming PDU.

Modules can define additional communities. This may be nec

essary to provide transport proxying (a PDU received on one communication

link is

proxied to another link) or to implement non-UDP access

points to SNMP.

A new community is defined with the function comm_define().

It takes the

following parameters:

priv This is an integer identifying the community

to the module.

Each module has its own namespace with regard

to this

parameter. The community table is indexed

with the module

name and this identifier.

descr This is a string providing a human readable

description of

the community. It is visible in the community

table.

mod This is the module defining the community.

str This is the initial community string.

The function returns a globally unique community identifier.

If a PDU is

received who's community string matches, this identifier is

set into the

global community.

The function comm_string() returns the current community

string for the

given community.

All communities defined by a module are automatically re

leased when the

module is unloaded.

WELL KNOWN OIDS

The global variable oid_zeroDotZero contains the OID 0.0.

REQUEST ID RANGES

For modules that implement SNMP client functions besides SN

MP agent functions it may be necessary to identify SNMP requests by their

identifier

to allow easier routing of responses to the correct sub-sys

tem. Request

id ranges provide a way to aquire globally non-overlapping

sub-ranges of

the entire 31-bit id range.

A request id range is allocated with reqid_allocate(). The

arguments

are: the size of the range and the module allocating the

range. For

example, the call

id = reqid_allocate(1000, module);

allocates a range of 1000 request ids. The function returns

the request

id range identifier or 0 if there is not enough identifier

space. The

function reqid_base() returns the lowest request id in the

given range.

Request id are allocated starting at the lowest one linear

throughout the

range. If the client application may have a lot of out

standing request

the range must be large enough so that an id is not reused

until it is

really expired. reqid_next() returns the sequentially next

id in the

range.

The function reqid_istype() checks whether the request id

reqid is withing the range identified by type. The function reqid_type()

returns the

range identifier for the given reqid or 0 if the request id

is in none of

the ranges.

TIMERS

The SNMP daemon supports an arbitrary number of timers with

SNMP tick

granularity. The function timer_start() arranges for the

callback func

to be called with the argument uarg after ticks SNMP ticks

have expired.

mod is the module that starts the timer. These timers are

one-shot, they

are not restarted. Repeatable timers are started with

timer_start_repeat() which takes an additional argument

repeat_ticks.

The argument ticks gives the number of ticks until the first

execution of

the callback, while repeat_ticks is the number of ticks be

tween invocations of the callback. Note, that currently the number of

initial ticks

silently may be set identical to the number of ticks between

callback

invocations. The function returns a timer identifier that

can be used to

stop the timer via timer_stop(). If a module is unloaded

all timers

started by the module that have not expired yet are stopped.

FILE DESCRIPTOR SUPPORT

A module may need to get input from socket file descriptors

without

blocking the daemon (for example to implement alternative

SNMP transports).

The function fd_select() causes the callback function func

to be called

with the file descriptor fd and the user argument uarg when

ever the file

descriptor fd can be read or has a close condition. If the

file descriptor is not in non-blocking mode, it is set to non-blocking

mode. If the

callback is not needed anymore, fd_deselect() may be called

with the

value returned from fd_select(). All file descriptors se

lected by a module are automatically deselected when the module is unload

ed.

To temporarily suspend the file descriptor registration

fd_suspend() can

be called. This also causes the file descriptor to be

switched back to

blocking mode if it was blocking prior the call to

fd_select(). This is

necessary to do synchronous input on a selected socket. The

effect of

fd_suspend() can be undone with fd_resume().

OBJECT RESOURCES

The system group contains an object resource table. A mod

ule may create

an entry in this table by calling or_register() with the oid

to be registered, a textual description in str and a pointer to the

module mod. The

registration can be removed with or_unregister(). All reg

istrations of a

module are automatically removed if the module is unloaded.

TRANSMIT AND RECEIVE BUFFERS

A buffer is allocated via buf_alloc(). The argument must be

1 for transmit and 0 for receive buffers. The function may return NULL

if there is

no memory available. The current buffersize can be obtained

with

buf_size().

PROCESSING PDUS

For modules that need to do their own PDU processing (for

example for

proxying) the following functions are available:

Function snmp_input_start() decodes the PDU, searches the

community, and

sets the global this_tick. It returns one of the following

error codes:

SNMPD_INPUT_OK Everything ok, continue with

processing.

SNMPD_INPUT_FAILED The PDU could not be decoded,

has a wrong

version or an unknown communi

ty string.

SNMPD_INPUT_VALBADLEN A SET PDU had a value field in

a binding

with a wrong length field in

an ASN.1

header.

SNMPD_INPUT_VALRANGE A SET PDU had a value field in

a binding

with a value that is out of

range for the

given ASN.1 type.

SNMPD_INPUT_VALBADENC A SET PDU had a value field in

a binding

with wrong ASN.1 encoding.

SNMPD_INPUT_TRUNC The buffer appears to contain

a valid begin

of a PDU, but is too short.

For streaming

transports this means that the

caller must

save what he already has and

trying to

obtain more input and reissue

this input to

the function. For datagram

transports this

means that part of the data

gram was lost

and the input should be ig

nored.

The function snmp_input_finish() does the other half of pro

cessing: if

snmp_input_start() did not return OK, tries to construct an

error

response. If the start was OK, it calls the correct func

tion from

bsnmpagent(3) to execute the request and depending on the

outcome constructs a response or error response PDU or ignores the re

quest PDU. It

returns either SNMPD_INPUT_OK or SNMPD_INPUT_FAILED. In the

first case a

response PDU was constructed and should be sent.

The function snmp_output() takes a PDU and encodes it.

The function snmp_send_port() takes a PDU, encodes it and

sends it

through the given port (identified by the transport and the

index in the

port table) to the given address.

The function snmp_send_trap() sends a trap to all trap des

tinations. The

arguments are the oid identifying the trap and a NULL-termi

nated list of

struct snmp_value pointers that are to be inserted into the

trap binding

list.

SIMPLE ACTION SUPPORT

For simple scalar variables that need no dependencies a num

ber of support

functions is available to handle the set, commit, rollback

and get.

The following functions are used for OCTET STRING scalars,

either NUL

terminated or not:

string_save()

should be called for SNMP_OP_SET. value and ctx

are the resp.

arguments to the node callback. valp is a point

er to the

pointer that holds the current value and req_size

should be -1

if any size of the string is acceptable or a num

ber larger or

equal zero if the string must have a specific

size. The function saves the old value in the scratch area

(note, that any

initial value must have been allocated by mal

loc(3)), allocates a new string, copies over the new value,

NUL-terminates

it and sets the new current value.

string_commit()

simply frees the saved old value in the scratch

area.

string_rollback()

frees the new value, and puts back the old one.

string_get()

is used for GET or GETNEXT. The function

string_get_max()

can be used instead of If len is -1, the length

is computed

via strlen(3) from the current string value. If

the current

value is NULL, a OCTET STRING of zero length is

returned.

string_free()

must be called if either rollback or commit fails

to free the

saved old value.

The following functions are used to process scalars of type

IP-address:

ip_save() Saves the current value in the scratch area and

sets the new

value from valp.

ip_commit()

Does nothing.

ip_rollback()

Restores the old IP address from the scratch

area.

ip_get() Retrieves the IP current address.

The following functions handle OID-typed variables:

oid_save()

Saves the current value in the scratch area by

allocating a

struct asn_oid with malloc(3) and sets the new

value from oid.

oid_commit()

Frees the old value in the scratch area.

oid_rollback()

Restores the old OID from the scratch area and

frees the old

OID.

oid_get() Retrieves the OID

TABLE INDEX HANDLING

The following functions help in handling table indexes:

index_decode()

Decodes the index part of the OID. The parameter

oid must be

a pointer to the var field of the value argument

of the node

callback. The sub argument must be the index of

the start of

the index in the OID (this is the sub argument to

the node

callback). code is the index expression (parame

ter idx to the

node callback). These parameters are followed by

parameters

depending on the syntax of the index elements as

follows:

INTEGER int32_t * expected as argu

ment.

COUNTER64 uint64_t * expected as argu

ment. Note,

that this syntax is illegal

for indexes.

OCTET STRING A u_char ** and a size_t *

expected as

arguments. A buffer is al

located to hold

the decoded string.

OID A struct asn_oid * is ex

pected as argu

ment.

IP ADDRESS A u_int8_t * expected as ar

gument that

points to a buffer of at

least four byte.

COUNTER, GAUGE, TIMETICKS

A u_int32_t expected.

NULL No argument expected.

index_compare()

compares the current variable with an OID. oid1

and sub come

from the node callback arguments value->var and

sub resp.

oid2 is the OID to compare to. The function re

turns -1, 0, +1

when the variable is lesser, equal, higher to the

given OID.

oid2 must contain only the index part of the

table column.

index_compare_off()

is equivalent to index_compare() except that it

takes an additional parameter off that causes it to ignore the

first off

components of both indexes.

index_append()

appends OID src beginning at position sub to dst.

index_append_off()

appends OID src beginning at position off to dst

beginning at

position sub + off.

SEE ALSO

gensnmptree(1), bsnmpd(1), bsnmpagent(3), bsnmpclient(3),

bsnmplib(3)

STANDARDS

This implementation conforms to the applicable IETF RFCs and

ITU-T recommendations.

AUTHORS

Hartmut Brandt <harti@freebsd.org>

BSD February 27, 2006

BSD