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

FreeBSD Manual Pages

  
 
  

home | help
NETSNMP_CONFIG_API(3)		   Net-SNMP		 NETSNMP_CONFIG_API(3)

NAME
       register_config_handler,	     register_const_config_handler,	regis-
       ter_prenetsnmp_mib_handler,	unregister_config_handler,	regis-
       ter_mib_handlers,   unregister_all_config_handlers,   register_app_con-
       fig_handler,  register_app_prenetsnmp_mib_handler,  unregister_app_con-
       fig_handler,	 read_configs,	    read_premib_configs,     read_con-
       fig_print_usage,	config_perror, config_pwarn - netsnmp_config_api func-
       tions

SYNOPSIS
       #include	<net-snmp/config_api.h>

   Config Handlers
       struct config_line *
	 register_config_handler(const char *filePrefix,
			    const char *token,
			    void (*parser)(const char *, char *),
			    void (*releaser)(void),
			    const char *usageLine);

       struct config_line *
	 register_const_config_handler(const char *filePrefix,
			    const char *token,
			    void (*parser)(const char *, const char *),
			    void (*releaser)(void),
			    const char *usageLine);

       struct config_line *
	 register_prenetsnmp_mib_handler(const char *filePrefix,
			    const char *token,
			    void (*parser)(const char *, char *),
			    void (*releaser)(void),
			    const char *usageLine);

       void unregister_config_handler(const char *filePrefix,
			    const char *token);

       void register_mib_handlers(void);
       void unregister_all_config_handlers(void);

   Application Handlers
       struct config_line *
	 register_app_config_handler(const char	*token,
			    void (*parser)(const char *, char *),
			    void (*releaser)(void),
			    const char *usageLine);

       struct config_line *
	 register_app_prenetsnmp_mib_handler(const char	*token,
			    void (*parser)(const char *, char *),
			    void (*releaser)(void),
			    const char *usageLine);

       void unregister_app_config_handler(const	char *token);

   Reading Configuration Files
       void read_premib_configs(void);
       void read_configs(void);

   Help	Strings	and Errors
       void read_config_print_usage(char *lead);
       void config_pwarn(const char *string);
       void config_perror(const	char *string);

DESCRIPTION
       The functions are a fairly extensible system of parsing various config-
       uration files at	the run	time of	 an  application.   The	 configuration
       file flow is broken into	the following phases:

	   1.  Registration of handlers.

	   2.  Reading of the configuration files for pre-MIB parsing require-
	       ments.

	   3.  Reading and parsing of the textual MIB files.

	   4.  Reading of the configuration  files  for	 configuration	direc-
	       tives.

	   5.  Optionally re-reading the configuration files at	a future date.

       The  idea  is that the calling application is able to register handlers
       for certain tokens specified in certain named configuration files.  The
       read_configs()  function	 can  then  be called to look for all relevant
       configuration files, match the first word on each line against the list
       of  registered  tokens and pass the remainder of	the line to the	appro-
       priate registered handler.

REGISTERING A HANDLER
       register_config_handler()
	      Registers	a  configuration  handler  routine,  which  should  be
	      called  to  process  configuration  directives starting with the
	      specified	token.	For example:

		     register_config_handler("snmp",   "exampleToken",	 exam-
		     ple_handler, NULL,	"ARG1 [ARG2]");

	      would  register  the  example_handler() function so that it will
	      get called every time the	first word of a	line in	the  snmp.conf
	      configuration file(s) matches "exampleToken".
	      Calling  the  appropriate	 handlers to process the configuration
	      file directives is the  responsibility  of  read_configs()  (see
	      below).

       register_const_config_handler()
	      Similar  to  the	register_config_handler()  function,  but  the
	      parser routine is	 explicitly  constrained  to  not  modify  the
	      string being parsed.

       register_prenetsnmp_mib_handler()
	      Similar  to the register_config_handler()	function, but the reg-
	      istered handler routine will be called before the	 textual  MIBs
	      are read in.  This is typically used for tokens that will	affect
	      the configuration	of the MIB parser, and will normally  only  be
	      used within the SNMP library itself.

       register_mib_handlers()
	      Initialisation  routine  to  register  the internal SNMP library
	      configuration handlers.

       unregister_config_handler()
	      Removes the registered configuration handler for	the  specified
	      filePrefix and token.

       unregister_all_config_handlers()
	      Removes all registered configuration handlers.

   Token Handlers
       Handler functions should	have the following signature:

	      void handler(const char *token, char *line);
	      or
	      void handler(const char *token, const char *line); br (if	regis-
	      tered using register_const_config_handler)

       The function will be called with	two arguments,	the  first  being  the
       token  that  triggered  the  call to this function (i.e.	the token used
       when registering	the handler), and the second being  the	 remainder  of
       the  configuration file line (i.e. everything following the white space
       following the matched token).

   Freeing Handlers
       If the token handler function dynamically allocates resources when pro-
       cessing	a  configuration  entry,  then	these  may need	to be released
       before re-reading the configuration files.  If the fourth  parameter  (
       releaser	 )  passed  to	register_config_handler	is non-NULL, then this
       specifies a function to be called before	re-reading  the	 configuration
       files.	This function should free any resources	allocated by the token
       handler function	and reset its  notion  of  the	configuration  to  its
       default.	  The  token handler function can then safely be called	again.
       No arguments are	passed to the resource freeing handler.
       Note that this function is not called when the handler is  unregistered
       individually (but is called as part of unregister_all_config_handlers()
       ).

   Application Handlers
       register_app_config_handler()

       register_app_prenetsnmp_mib_handler()

       unregister_app_config_handler()
	      These functions are analagous to register_config_handler(), reg-
	      ister_prenetsnmp_mib_handler()  and  unregister_config_handler()
	      but do not require the file type argument	(which is filled in by
	      the  application).   It is intended that MIB modules written for
	      the agent	use these functions to allow the agent	to  have  more
	      control  over  which configuration files are read	(typically the
	      snmpd.conf files).

READING	CONFIGURATION FILES
       read_premib_configs()

       read_configs()
	      These routines process the configuration files found in the con-
	      figuration search	path (see below).  For each entry, the handler
	      registered for that configuration	token is called.

       read_premib_configs() is	run before the MIB files are read in, and pro-
       cesses  those  configuration  tokens  registered	using register_prenet-
       snmp_mib_handler() (or  register_app_prenetsnmp_mib_handler()  ).   All
       other entries are ignored.

       read_configs()  is  run after the MIB files have	been read in, and pro-
       cesses those configuration tokens registered using register_config_han-
       dler() (or register_app_config_handler()	).  If it encounters a config-
       uration token for which no handler has been registered (either pre-  or
       post-mib),  then	 it  will display a warning message, and continue pro-
       cessing with the	next line of the configuration file.

   Configuration Search	Path
       The configuration files to be read are found by	searching  a  list  of
       configuration  directories for appropriately named files.  In each such
       directory, the library will look	for files named
	snmp.conf,
	snmp.local.conf,
	app.conf,
	app.local.conf,
       (where app is the appication-specific filePrefix	used to	register  con-
       figuration  handlers).	It  is	not  necessary for any or all of these
       files to	be present in each directory.  Missing files will be  silently
       skipped.
       The  idea  behind the two different suffixes is that the	first file can
       be shared (via rdist or an NFS mount) across a large number of machines
       and  the	 second	 file  can be used to configure	local settings for one
       particular machine.

       The default list	of directories to search is  /usr/local/etc/snmp, fol-
       lowed by	 /usr/local/share/snmp,	followed by  /usr/local/lib/snmp, fol-
       lowed by	 $HOME/.snmp.  This list can be	changed	by setting  the	 envi-
       ronmental  variable  SNMPCONFPATH  to  be  a  (colon separated) list of
       directories to search.

   init_snmp()
       The normal mode of operation would be to	register the  application-spe-
       cific  configuration handlers, and then invoke init_snmp().  This would
       call the	routines listed	above to register the internal library config-
       uration handlers, process any configuration tokens registered with reg-
       ister_prenetsnmp_mib_handler(), read in the  textual  MIB  files	 using
       init_mib(),  and	finally	parse the configuration	file tokens registered
       with register_config_handler().

       If the init_snmp() function is used, none of these functions need to be
       explicitly called by the	application.

HELP STRINGS AND ERRORS
       The usageLine parameter passed to register_config_handler() and similar
       calls,  is  used	 to  display  help  information	 when  the   read_con-
       fig_print_usage()  function is called.  This function is	used by	all of
       the applications	when the -H flag is passed on the  command  line.   It
       prints  a summary of all	of the configuration file lines, and the asso-
       ciated files, that the configuration system understands.	 The usageLine
       parameter  should  be a list of arguments expected after	the token, and
       not a lengthy description (which	should go into a manual	page instead).
       The lead	prefix will be prepended to each line that the function	prints
       to stderr, where	it displays its	output.

       The  init_snmp()	 function  should  be  called  before  the   read_con-
       fig_print_usage()  function is called, so that the library can register
       its  configuration  file	 directives  as	  well	 for   the   read_con-
       fig_print_usage() function to display.

   Error Handling Functions
       The two functions config_pwarn()	and config_perror() both take an error
       string as an argument and print it to stderr along with	the  file  and
       line  number that caused	the error.  A call to the second function will
       also force read_configs() to eventually return with an error code indi-
       cating  to  it's	calling	function that it should	abort the operation of
       the application.

ENVIRONMENT VARIABLES
       SNMPCONFPATH
		 A colon separated list	of directories to search for  configu-
		 ration		    files	      in.	      Default:
		 /usr/local/etc/snmp:/usr/local/share/snmp:/usr/local/lib/snmp:$HOME/.snmp

SEE ALSO
       netsnmp_mib_api(3), snmp_api(3)

V5.7.3				  13 Aug 2010		 NETSNMP_CONFIG_API(3)

NAME | SYNOPSIS | DESCRIPTION | REGISTERING A HANDLER | READING CONFIGURATION FILES | HELP STRINGS AND ERRORS | ENVIRONMENT VARIABLES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=netsnmp_config_api&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help