Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
SNMPMOD(3)	       FreeBSD Library Functions Manual		    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,
     oid_usmUnknownEngineIDs, oid_usmNotInTimeWindows, 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, snmp_pdu_auth_access 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, snmpd_usmstats, bsnmpd_get_usm_stats,
     bsnmpd_reset_usm_stats, usm_first_user, usm_next_user, usm_find_user,
     usm_new_user, usm_delete_user, usm_flush_users, usm_user
     snmpd_target_stat bsnmpd_get_target_stats target_first_address
     target_next_address target_new_address target_activate_address
     target_delete_address target_first_param target_next_param
     target_new_param target_delete_param target_first_notify
     target_next_notify	target_new_notify target_delete_notify
     target_flush_all target_address target_param target_notify	-- 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, ...);

     enum snmp_code
     snmp_pdu_auth_access(struct snmp_pdu *pdu,	int32_t	*ip);

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

     extern struct snmpd_usmstat snmpd_usmstats;

     struct snmpd_usmstat *
     bsnmpd_get_usm_stats(void);

     void
     bsnmpd_reset_usm_stats(void);

     struct usm_user *
     usm_first_user(void);

     struct usm_user *
     usm_next_user(struct usm_user *uuser);

     struct usm_user *
     usm_find_user(uint8_t *engine, uint32_t elen, char	*uname);

     struct usm_user *
     usm_new_user(uint8_t *engine, uint32_t elen, char *uname);

     void
     usm_delete_user(struct usm_user *);

     void
     usm_flush_users(void);

     extern struct usm_user *usm_user;

     struct snmpd_target_stats *
     bsnmpd_get_target_stats(void);

     struct target_address *
     target_first_address(void);

     struct target_address *
     target_next_address(struct	target_address *);

     struct target_address *
     target_new_address(char *);

     int
     target_activate_address(struct target_address *);

     int
     target_delete_address(struct target_address *);

     struct target_param *
     target_first_param(void);

     struct target_param *
     target_next_param(struct target_param *);

     struct target_param *
     target_new_param(char *);

     int
     target_delete_param(struct	target_param *);

     struct target_notify *
     target_first_notify(void);

     struct target_notify *
     target_next_notify(struct target_notify *);

     struct target_notify *
     target_new_notify(char *);

     int
     target_delete_notify(struct target_notify *);

     void
     target_flush_all(void);

     extern const struct asn_oid oid_usmUnknownEngineIDs;
     extern const struct asn_oid oid_usmNotInTimeWindows;

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 configura-
     tion 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
     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 imple-
		mented 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 mod-
		ule 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
     There are a number	of macros designed to help implementing	SNMP tables.
     A problem while implementing a table is the support for the GETNEXT oper-
     ator.  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 ta-
     ble 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 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 existence	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 dae-
     mon 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 community.  Commu-
     nity identifiers are unsigned integers.  For the three standard communi-
     ties 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 configu-
     ration 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	incom-
     ing PDU.

     Modules can define	additional communities.	 This may be necessary to pro-
     vide 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 identi-
	    fier.

     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	SNMPv1
     or	SNMPv2 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.

   THE USER-BASED SECURITY GROUP
     The scalar	statistics of the USM group are	held in	the global variable
     snmpd_usmstats:

	   struct snmpd_usmstat	{
		   uint32_t	   unsupported_seclevels;
		   uint32_t	   not_in_time_windows;
		   uint32_t	   unknown_users;
		   uint32_t	   unknown_engine_ids;
		   uint32_t	   wrong_digests;
		   uint32_t	   decrypt_errors;
	   };
     bsnmpd_get_usm_stats() returns a pointer to the global structure contain-
     ing the statistics.  bsnmpd_reset_usm_stats() clears the statistics of
     the USM group.

     A global list of configured USM users is maintained by the	daemon.

	   struct usm_user {
		   struct snmp_user		   suser;
		   uint8_t			   user_engine_id[SNMP_ENGINE_ID_SIZ];
		   uint32_t			   user_engine_len;
		   char				   user_public[SNMP_ADM_STR32_SIZ];
		   uint32_t			   user_public_len;
		   int32_t			   status;
		   int32_t			   type;
		   SLIST_ENTRY(usm_user)	   up;
	   };
     This structure represents an USM user. The	daemon only responds to	SNMPv3
     PDUs with user credentials	matching an USM	user entry in its global list.
     If	a SNMPv3 PDU is	received, whose	security model is USM, the global
     usm_user is set to	point at the user entry	that matches the credentials
     contained in the PDU.  However, the daemon	does not create	or remove USM
     users, it gives an	interface to external loadable module(s) to manage the
     list.  usm_new_user() adds	an user	entry in the list, and
     usm_delete_user() deletes an existing entry from the list.
     usm_flush_users() is used to remove all configured	USM users.
     usm_first_user() will return the first user in the	list, or NULL if the
     list is empty.  usm_next_user() will return  the next user	of a given
     entry if one exists, or NULL.  The	list is	sorted according to the	USM
     user name and Engine ID.  usm_find_user() returns the USM user entry
     matching the given	engine and uname or NULL if an user with the specified
     name and engine id	is not present in the list.

   THE MANAGEMENT TARGET GROUP
     The Management Target group holds target address information used when
     sending SNMPv3 notifications.

     The scalar	statistics of the Management Target group are held in the
     global variable snmpd_target_stats:

	   struct snmpd_target_stats {
		   uint32_t			   unavail_contexts;
		   uint32_t			   unknown_contexts;
	   };
     bsnmpd_get_target_stats() returns a pointer to the	global structure con-
     taining the statistics.

     Three global lists	of configured management target	addresses, parameters
     and notifications respectively are	maintained by the daemon.

	   struct target_address {
		   char				   name[SNMP_ADM_STR32_SIZ];
		   uint8_t			   address[SNMP_UDP_ADDR_SIZ];
		   int32_t			   timeout;
		   int32_t			   retry;
		   char				   taglist[SNMP_TAG_SIZ];
		   char				   paramname[SNMP_ADM_STR32_SIZ];
		   int32_t			   type;
		   int32_t			   socket;
		   int32_t			   status;
		   SLIST_ENTRY(target_address)	   ta;
	   };
     This structure represents a SNMPv3	Management Target address. Each	time a
     SNMP TRAP is send the daemon will send the	Trap to	all active Management
     Target addresses in its global list.

	   struct target_param {
		   char				   name[SNMP_ADM_STR32_SIZ];
		   int32_t			   mpmodel;
		   int32_t			   sec_model;
		   char				   secname[SNMP_ADM_STR32_SIZ];
		   enum	snmp_usm_level		   sec_level;
		   int32_t			   type;
		   int32_t			   status;
		   SLIST_ENTRY(target_param)	   tp;
	   };
     This structure represents the information used to generate	SNMP messages
     to	the associated SNMPv3 Management Target	addresses.

	   struct target_notify	{
		   char				   name[SNMP_ADM_STR32_SIZ];
		   char				   taglist[SNMP_TAG_SIZ];
		   int32_t			   notify_type;
		   int32_t			   type;
		   int32_t			   status;
		   SLIST_ENTRY(target_notify)	   tn;
	   };
     This structure represents Notification Tag	entries	- SNMP notifications
     are sent to the Target address for	each entry in the Management Target
     Address list that has a tag matching the specified	tag in this structure.

     The daemon	does not create	or remove entries in the Management Target
     group lists, it gives an interface	to external loadable module(s) to man-
     age the lists.  target_new_address() adds a target	address	entry, and
     target_delete_address() deletes an	existing entry from the	target address
     list.  target_activate_address() creates a	socket associated with the
     target address entry so that SNMP notifications may actually be send to
     that target address.  target_first_address() will return a	pointer	to the
     first target address entry	in the list, while target_next_address() will
     return a pointer to the next target address of a given entry if one
     exists.  target_new_param() adds a	target parameters' entry, and
     target_delete_param() deletes an existing entry from the target parame-
     ters list.	 target_first_param() will return a pointer to the first tar-
     get parameters' entry in the list,	while target_next_param() will return
     a pointer to the next target parameters of	a given	entry if one exists.
     target_new_notify() adds a	notification target entry, and
     target_delete_notify() deletes an existing	entry from the notification
     target list.  target_first_notify() will return a pointer to the first
     notification target entry in the list, while target_next_notify() will
     return a pointer to the next notification target of a given entry if one
     exists.  target_flush_all() is used to remove all configured data from
     the three global Management Target	Group lists.

   WELL	KNOWN OIDS
     The global	variable oid_zeroDotZero contains the OID 0.0.	The global
     variables oid_usmUnknownEngineIDs oid_usmNotInTimeWindows contains	the
     OIDs 1.3.6.1.6.3.15.1.1.4.0 and  1.3.6.1.6.3.15.1.1.2.0 used in the
     SNMPv3 USM	Engine Discovery.

   REQUEST ID RANGES
     For modules that implement	SNMP client functions besides SNMP agent func-
     tions 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	acquire	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
     range.

     The function reqid_istype() checks	whether	the request id reqid is	within
     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 between invoca-
     tions 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 trans-
     ports).

     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 read or has a	close condition.  If the file descrip-
     tor 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 mod-
     ule 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
     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	regis-
     tered, 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.

   TRANSMIT AND	RECEIVE	BUFFERS
     A buffer is allocated via buf_alloc().  The argument must be 1 for	trans-
     mit 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 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
			    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 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 con-
     structs 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 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 oid identifying the trap	and a NULL-terminated list of
     struct snmp_value pointers	that are to be inserted	into the trap binding
     list.  snmp_pdu_auth_access() verifies whether access to the object IDs
     contained in the pdu
      should be	granted	or denied, according to	the configured View-Based
     Access rules.  ip contains	the index of the first varbinding to which
     access was	denied,	or 0 if	access to all varbindings in the PDU is
     granted.

   SIMPLE ACTION SUPPORT
     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:

     string_save()
		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 func-
		tion saves the old value in the	scratch	area (note, that any
		initial	value must have	been allocated by malloc(3)), allo-
		cates 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 string_get() to ensure that the
		returned string	has a certain maximum length.  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 (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     uint64_t * expected as argument.	Note, that
			      this syntax is illegal for indexes.

		OCTET STRING  A	u_char ** and a	size_t * expected as argu-
			      ments.  A	buffer is allocated to hold the
			      decoded string.

		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.

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

     index_compare_off()
		is equivalent to index_compare() except	that it	takes an addi-
		tional 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	recom-
     mendations.

AUTHORS
     Hartmut Brandt <harti@FreeBSD.org>

FreeBSD	9.2		       December	19, 2010		   FreeBSD 9.2

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | PROCESSING PDUS | SEE ALSO | STANDARDS | AUTHORS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=snmpmod&sektion=3&manpath=FreeBSD+9.2-RELEASE>

home | help