*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->FreeBSD man pages -> snmpmod (3)              



NAME    [Toc]    [Back]

     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_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_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    [Toc]    [Back]

     Begemot SNMP library (libbsnmp, -lbsnmp)

SYNOPSIS    [Toc]    [Back]

     #include <bsnmp/snmpmod.h>



















     extern u_int32_t this_tick;
     extern u_int32_t start_tick;


     extern struct systemg systemg;

     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;

     reqid_allocate(int size, struct lmodule *mod);

     reqid_next(u_int type);

     reqid_base(u_int type);

     reqid_istype(int32_t reqid, u_int type);

     reqid_type(int32_t reqid);

     void *
     timer_start(u_int ticks, void (*func)(void *), void *uarg,
	 struct lmodule *mod);

     timer_stop(void *timer_id);

     void *
     fd_select(int fd, void (*func)(int, void *), void *uarg,
	 struct lmodule *mod);

     fd_deselect(void *fd_id);

     fd_suspend(void *fd_id);

     fd_resume(void *fd_id);

     or_register(const struct asn_oid *oid, const char *descr,
	 struct lmodule *mod);

     or_unregister(u_int or_id);

     void *
     buf_alloc(int tx);

     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);

     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);

     snmp_output(struct snmp_pdu *pdu, u_char *sndbuf, size_t *sndlen,
	 const char *dest);

     snmp_send_port(const struct asn_oid *port, struct snmp_pdu *pdu,
	 const struct sockaddr *addr, socklen_t addrlen);

     snmp_send_trap(const struct asn_oid *oid, ...);

     string_save(struct snmp_value *val, struct snmp_context *ctx,
	 ssize_t req_size, u_char **strp);

     string_commit(struct snmp_context *ctx);

     string_rollback(struct snmp_context *ctx, u_char **strp);

     string_get(struct snmp_value *val, const u_char *str, ssize_t len);

     string_free(struct snmp_context *ctx);

     ip_save(struct snmp_value *val, struct snmp_context *ctx, u_char *ipa);

     ip_rollback(struct snmp_context *ctx, u_char *ipa);

     ip_commit(struct snmp_context *ctx);

     ip_get(struct snmp_value *val, u_char *ipa);

     oid_save(struct snmp_value *val, struct snmp_context *ctx,
	 struct asn_oid *oid);

     oid_rollback(struct snmp_context *ctx, struct asn_oid *oid);

     oid_commit(struct snmp_context *ctx);

     oid_get(struct snmp_value *val, const struct asn_oid *oid);

     index_decode(const struct asn_oid *oid, u_int sub, u_int code, ...);

     index_compare(const struct asn_oid *oid1, u_int sub,
	 const struct asn_oid *oid2);

     index_compare_off(const struct asn_oid *oid1, u_int sub,
	 const struct asn_oid *oid2, u_int off);

     index_append(struct asn_oid *dst, u_int sub, const struct asn_oid *src);

     index_append_off(struct asn_oid *dst, u_int sub,
	 const struct asn_oid *src, u_int off);

DESCRIPTION    [Toc]    [Back]

     The snmpd(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 snmpd(1) to use for task, that are
     not the classical SNMP task.

     Modules are loaded by writing to the module table. This table is indexed
     by a string, that identfies 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 module. 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 complete 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

	   typedef enum snmpd_proxy_err (*proxy_err_f)(struct snmp_pdu *,
	       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 who's 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 initialisation 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    [Toc]    [Back]
     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 ordered list of
     structures each one of which contains an OID that is the index 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


     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 *_OBJECT_OID_*() assume the existence of a struct asn_oid that
     is used as index, the macros *_OBJECT_INT_*() assume the existance 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.
     Explicitely 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    [Toc]    [Back]
     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    [Toc]    [Back]
     The scalar fields of the system group are held in the global variable

	   struct systemg {
		   u_char	   *descr;
		   struct asn_oid  object_id;
		   u_char	   *contact;
		   u_char	   *name;
		   u_char	   *location;
		   u_int32_t	   services;
		   u_int32_t	   or_last_change;

   COMMUNITIES    [Toc]    [Back]
     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 community. Community
 identifiers are unsigned integers. For the three standard 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

     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:

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

   WELL KNOWN OIDS    [Toc]    [Back]
     The global variable oid_zeroDotZero contains the OID 0.0.

   REQUEST ID RANGES    [Toc]    [Back]
     For modules that implement SNMP client functions besides SNMP agent functions
 it may be necessary to identify SNMP requests by their identifier
     to allow easier routing of responses to the correct sub-system. 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 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

     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    [Toc]    [Back]
     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. Timers are one-shot, they are
     not restarted. 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.

     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 whenever the file
     descriptor fd can be red 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 synchronuous input on a selected socket.  The effect of
     fd_suspend() can be undone with fd_resume().

   OBJECT RESOURCES    [Toc]    [Back]
     The system group contains an object resource table. A module 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 registrations of a
     module are automatically removed if the module is unloaded.

     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

PROCESSING PDUS    [Toc]    [Back]

     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 community 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

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

     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 to execute the request and depending on the outcome constructs
     a response or error response PDU or ignores the request 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 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 oid identifying the trap and a NULL-terminated list of
     struct snmp_value pointers that are to be inserted into the trap binding

   SIMPLE ACTION SUPPORT    [Toc]    [Back]
     For simple scalar variables that need no dependencies a number 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:

		should be called for SNMP_OP_SET.  value and ctx are the resp.
		arguments to the node callback.  valp is a pointer to the
		pointer that holds the current value and 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.

		simply frees the saved old value in the scratch area.

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

		is used for GET or GETNEXT. 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.

		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.

		Does nothing.

		Restores the old IP address from the scratch area.

     ip_get()	Retrieves the IP current address.

     The following functions handle OID-typed variables:

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

		Frees the old value in the scratch area.

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

     oid_get()	Retrieves the OID

   TABLE INDEX HANDLING    [Toc]    [Back]
     The following functions help in handling table indexes:

		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 (parameter 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 argument.

		COUNTER64     u_int64_t * expected as argument. Note, that
			      this syntax is illegal for indexes.

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

		OID	      A struct asn_oid * is expected as argument.

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

			      A u_int32_t expected.

		NULL	      No argument expected.

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

		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.

		appends OID src beginning at position sub to dst.

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

SEE ALSO    [Toc]    [Back]

     snmpd(1), gensnmptree(1), bsnmplib(3) bsnmpclient(3), bsnmpagent(3)

STANDARDS    [Toc]    [Back]

     This implementation conforms to the applicable IETF RFCs and ITU-T recommendations.

AUTHORS    [Toc]    [Back]

     Hartmut Brandt <brandt@fokus.gmd.de>

FreeBSD 5.2.1			August 16, 2002 		 FreeBSD 5.2.1
[ Back ]
 Similar pages
Name OS Title
delete_module Linux delete a loadable module entry
init_module Linux initialize a loadable module entry
create_module Linux create a loadable module entry
insmod Linux install loadable kernel module
bsnmpd FreeBSD simple and extendable SNMP daemon
os_mibs Tru64 Tru64 UNIX extensible SNMP subagent daemon
snmpd Tru64 Simple Network Management Protocol (SNMP) agent daemon
cpqthresh_mib Tru64 Tru64 UNIX SNMP subagent daemon that supports thresholding
snmpd.conf Tru64 Simple Network Management Protocol (SNMP) agent daemon
cpq_mibs Tru64 Tru64 UNIX SNMP subagent daemon for supported MIBS
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service