[ новости /+++ | форум | теги | ]

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

DESCRIPTION

MODULE LOADING AND UNLOADING

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 Vt struct snmp_module :

typedef enum snmpd_proxy_err (*proxy_err_f)(struct snmp_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 argument 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 automatically 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 signal 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 community string whose community was registered by this module and proxy is not NULL than this function 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 selected 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

The helper macros assume, that the table is organized as a TAILQ (see queue(3) and each structure contains a Vt 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 insert 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 Fn *_OBJECT_OID_* assume the existence of a Vt struct asn_oid that is used as index, the macros Fn *_OBJECT_INT_* assume the existence of an unsigned integer field that is used as index.

The macros Fn *_INDEX allow the explicit naming of the index field in the parameter Fa INDEX , whereas the other macros assume that this field is named index The macros Fn *_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:

Fa PTR

A pointer to the new structure to be inserted into the table.

Fa LIST

A pointer to the tail queue head.

Fa LINK

The name of the link field in the row structure.

Fa INDEX

The name of the index field in the row structure.

Fa OID

Must point to the var field of the Fa value argument to the node operation callback. This is the OID to search for.

Fa SUB

This is the index of the start of the table index in the OID pointed to by Fa OID . This is usually the same as the Fa sub argument to the node operation callback.

DAEMON TIMESTAMPS

get_ticks() - start_tick

THE SYSTEM GROUP

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

#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 necessary 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:

Fa 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.

Fa descr

This is a string providing a human readable description of the community. It is visible in the community table.

Fa mod

This is the module defining the community.

Fa 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 released when the module is unloaded.  

WELL KNOWN OIDS

REQUEST ID RANGES

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 outstanding 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 Fa reqid is withing the range identified by Fa type . The function reqid_type ();
returns the range identifier for the given Fa reqid or 0 if the request id is in none of the ranges.  

TIMERS

FILE DESCRIPTOR SUPPORT

The function fd_select ();
causes the callback function Fa func to be called with the file descriptor Fa fd and the user argument Fa uarg whenever the file descriptor Fa 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 selected by a module are automatically deselected when the module is unloaded.

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

TRANSMIT AND RECEIVE BUFFERS

PROCESSING PDUS

Function snmp_input_start ();
decodes the PDU, searches the community, and sets the global this_tick It returns one of the following error codes:

Er SNMPD_INPUT_OK

Everything ok, continue with processing.

Er SNMPD_INPUT_FAILED

The PDU could not be decoded, has a wrong version or an unknown community string.

Er SNMPD_INPUT_VALBADLEN

A SET PDU had a value field in a binding with a wrong length field in an ASN.1 header.

Er 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.

Er SNMPD_INPUT_VALBADENC

A SET PDU had a value field in a binding with wrong ASN.1 encoding.

Er 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 datagram was lost and the input should be ignored.

The function snmp_input_finish ();
does the other half of processing: if snmp_input_start ();
did not return OK, tries to construct an error response. If the start was OK, it calls the correct function from bsnmpagent(3) to execute the request and depending on the outcome constructs a response or error response PDU or ignores the request PDU. It returns either Er SNMPD_INPUT_OK or Er 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 destinations. The arguments are the Fa oid identifying the trap and a NULL-terminated list of Vt struct snmp_value pointers that are to be inserted into the trap binding list.  

SIMPLE ACTION SUPPORT

The following functions are used for OCTET STRING scalars, either NUL terminated or not:

Fn string_save

should be called for SNMP_OP_SET. Fa value and Fa ctx are the resp. arguments to the node callback. Fa valp is a pointer to the pointer that holds the current value and Fa req_size should be -1 if any size of the string is acceptable or a number 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 malloc(3)), allocates a new string, copies over the new value, NUL-terminates it and sets the new current value.

Fn string_commit

simply frees the saved old value in the scratch area.

Fn string_rollback

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

Fn string_get

is used for GET or GETNEXT. The function

Fn string_get_max

can be used instead of Nf stringto ensure that the returned string has a certain maximum length. If Fa 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.

Fn 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:

Fn ip_save

Saves the current value in the scratch area and sets the new value from Fa valp .

Fn ip_commit

Does nothing.

Fn ip_rollback

Restores the old IP address from the scratch area.

Fn ip_get

Retrieves the IP current address.

The following functions handle OID-typed variables:

Fn oid_save

Saves the current value in the scratch area by allocating a Vt struct asn_oid with malloc(3) and sets the new value from Fa oid .

Fn oid_commit

Frees the old value in the scratch area.

Fn oid_rollback

Restores the old OID from the scratch area and frees the old OID.

Fn oid_get

Retrieves the OID

TABLE INDEX HANDLING

Fn index_decode

Decodes the index part of the OID. The parameter Fa oid must be a pointer to the var field of the Fa value argument of the node callback. The Fa sub argument must be the index of the start of the index in the OID (this is the Fa sub argument to the node callback). Fa code is the index expression (parameter Fa idx to the node callback). These parameters are followed by parameters depending on the syntax of the index elements as follows:

INTEGER

Vt int32_t * expected as argument.

COUNTER64

Vt uint64_t * expected as argument. Note, that this syntax is illegal for indexes.

OCTET STRING

A Vt u_char ** and a Vt size_t * expected as arguments. A buffer is allocated to hold the decoded string.

OID

A Vt struct asn_oid * is expected as argument.

IP ADDRESS

A Vt u_int8_t * expected as argument that points to a buffer of at least four byte.

COUNTER, GAUGE, TIMETICKS

A Vt u_int32_t expected.

NULL

No argument expected.

Fn index_compare

compares the current variable with an OID. Fa oid1 and Fa sub come from the node callback arguments Fa value->var and Fa sub resp. Fa oid2 is the OID to compare to. The function returns -1, 0, +1 when the variable is lesser, equal, higher to the given OID. Fa oid2 must contain only the index part of the table column.

Fn index_compare_off

is equivalent to index_compare ();
except that it takes an additional parameter Fa off that causes it to ignore the first Fa off components of both indexes.

Fn index_append

appends OID Fa src beginning at position Fa sub to Fa dst .

Fn index_append_off

appends OID Fa src beginning at position Fa off to Fa dst beginning at position Fa sub + Fa off .

SEE ALSO

STANDARDS

AUTHORS

Index

NAME

LIBRARY

SYNOPSIS

DESCRIPTION

MODULE LOADING AND UNLOADING

IMPLEMENTING TABLES

DAEMON TIMESTAMPS

THE SYSTEM GROUP

COMMUNITIES

WELL KNOWN OIDS

REQUEST ID RANGES

TIMERS

FILE DESCRIPTOR SUPPORT

OBJECT RESOURCES

TRANSMIT AND RECEIVE BUFFERS

PROCESSING PDUS

SIMPLE ACTION SUPPORT

TABLE INDEX HANDLING

SEE ALSO

STANDARDS

AUTHORS

Партнёры:

Хостинг: