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_config_print_us-
       age, config_perror, config_pwarn	- netsnmp_config_api functions

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 be-
	      low).

       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 to-
       ken 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 fol-
       lowing 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  be-
       fore re-reading the configuration files.	 If the	fourth parameter ( re-
       leaser )	passed to register_config_handler is non-NULL, then this spec-
       ifies  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 de-
       fault.  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  di-
       rectories 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_config_print_us-
       age() 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/lo-
		 cal/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&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help