1CONFIG_API(3)                      Net-SNMP                      CONFIG_API(3)
2
3
4

NAME

6       register_config_handler, register_premib_handler unregister_config_han‐
7       dler, register_mib_handlers,  read_configs,  read_premib_configs,  con‐
8       fig_perror, config_pwarn - config_api functions
9

SYNOPSIS

11       #include <net-snmp/config_api.h>
12
13       struct config_line *
14         register_config_handler(const char *filePrefix,
15                            const char *token,
16                            void (*parser)(const char *, char *),
17                            void (*releaser)(void),
18                            const char *usageLine);
19
20       struct config_line *
21         register_premib_handler(const char *filePrefix,
22                            const char *token,
23                            void (*parser)(const char *, char *),
24                            void (*releaser)(void),
25                            const char *usageLine);
26
27       void register_mib_handlers(void);
28
29       void unregister_config_handler(const char *filePrefix,
30                            const char *token);
31
32       void unregister_all_config_handlers(void);
33
34   Application Handlers
35       struct config_line *
36         register_app_config_handler(const char *token,
37                            void (*parser)(const char *, char *),
38                            void (*releaser)(void),
39                            const char *usageLine);
40
41       struct config_line *
42         register_app_premib_handler(const char *token,
43                            void (*parser)(const char *, char *),
44                            void (*releaser)(void),
45                            const char *usageLine);
46
47       void unregister_app_config_handler(const char *token);
48
49   Reading Configuration Files
50       void read_premib_configs(void);
51       void read_configs(void);
52
53   Help Strings and Errors
54       void read_config_print_usage(char *lead);
55       void config_pwarn(const char *string);
56       void config_perror(const char *string);
57
58

DESCRIPTION

60       The functions are a fairly extensible system of parsing various config‐
61       uration files at the run time of  an  application.   The  configuration
62       file flow is broken into the following phases:
63
64           1.  Registration of handlers.
65
66           2.  Reading of the configuration files for pre-MIB parsing require‐
67               ments.
68
69           3.  Reading and parsing of the textual MIB files.
70
71           4.  Reading of the configuration  files  for  configuration  direc‐
72               tives.
73
74           5.  Optionally re-reading the configuration files at a future date.
75
76       The  idea  is that the calling application is able to register handlers
77       for certain tokens specified in certain named configuration files.  The
78       read_configs()  function  can  then  be called to look for all relevant
79       configuration files, match the first word on each line against the list
80       of  registered  tokens and pass the remainder of the line to the appro‐
81       priate registered handler.
82

REGISTERING A HANDLER

84       register_config_handler()
85              Registers a  configuration  handler  routine,  which  should  be
86              called  to  process  configuration  directives starting with the
87              specified token.  For example:
88
89                     register_config_handler("snmp",   "exampleToken",   exam‐
90                     ple_handler, NULL, "ARG1 [ARG2]");
91
92              would  register  the  example_handler() function so that it will
93              get called every time the first word of a line in the  snmp.conf
94              configuration file(s) matches "exampleToken".
95              Calling  the  appropriate  handlers to process the configuration
96              file directives is the  responsibility  of  read_configs()  (see
97              below).
98
99       register_premib_handler()
100              Similar  to the register_config_handler() function, but the reg‐
101              istered handler routine will be called before the  textual  MIBs
102              are read in.  This is typically used for tokens that will affect
103              the configuration of the MIB parser, and will normally  only  be
104              used within the SNMP library itself.
105
106       register_mib_handlers()
107              Initialisation  routine  to  register  the internal SNMP library
108              configuration handlers.
109
110       unregister_config_handler()
111              Removes the registered configuration handler for  the  specified
112              filePrefix and token.
113
114       unregister_all_config_handlers()
115              Removes all registered configuration handlers.
116
117
118   Token Handlers
119       Handler functions should have the following signature:
120
121              void handler(const char *token, char *line);
122
123       The  function  will  be  called with two arguments, the first being the
124       token that triggered the call to this function  (i.e.  the  token  used
125       when  registering  the  handler), and the second being the remainder of
126       the configuration file line (i.e. everything following the white  space
127       following the matched token).
128
129
130   Freeing Handlers
131       If the token handler function dynamically allocates resources when pro‐
132       cessing a configuration entry, then  these  may  need  to  be  released
133       before  re-reading  the configuration files.  If the fourth parameter (
134       releaser ) passed to register_config_handler  is  non-NULL,  then  this
135       specifies  a  function to be called before re-reading the configuration
136       files.  This function should free any resources allocated by the  token
137       handler  function  and  reset  its  notion  of the configuration to its
138       default.  The token handler function can then safely be  called  again.
139       No arguments are passed to the resource freeing handler.
140       Note  that this function is not called when the handler is unregistered
141       individually (but is called as part of unregister_all_config_handlers()
142       ).
143
144
145   Application Handlers
146       register_app_config_handler()
147
148       register_app_premib_handler()
149
150       unregister_app_config_handler()
151              These functions are analagous to register_config_handler(), reg‐
152              ister_premib_handler() and  unregister_config_handler()  but  do
153              not  require  the  file type argument (which is filled in by the
154              application).  It is intended that MIB modules written  for  the
155              agent  use  these functions to allow the agent to have more con‐
156              trol over which configuration  files  are  read  (typically  the
157              snmpd.conf files).
158

READING CONFIGURATION FILES

160       read_premib_configs()
161
162       read_configs()
163              These routines process the configuration files found in the con‐
164              figuration search path (see below).  For each entry, the handler
165              registered for that configuration token is called.
166
167       read_premib_configs() is run before the MIB files are read in, and pro‐
168       cesses those configuration tokens registered using register_premib_han‐
169       dler()  (or  register_app_premib_handler()  ).   All  other entries are
170       ignored.
171
172       read_configs() is run after the MIB files have been read in,  and  pro‐
173       cesses those configuration tokens registered using register_config_han‐
174       dler() (or register_app_config_handler() ).  If it encounters a config‐
175       uration  token for which no handler has been registered (either pre- or
176       post-mib), then it will display a warning message,  and  continue  pro‐
177       cessing with the next line of the configuration file.
178
179   Configuration Search Path
180       The  configuration  files  to  be read are found by searching a list of
181       configuration directories for appropriately named files.  In each  such
182       directory, the library will look for files named
183        snmp.conf,
184        snmp.local.conf,  app.conf,  app.local.conf, (where app is the appica‐
185       tion-specific filePrefix used to register configuration handlers).   It
186       is  not  necessary  for any or all of these files to be present in each
187       directory.  Missing files will be silently skipped.
188       The idea behind the two different suffixes is that the first  file  can
189       be shared (via rdist or an NFS mount) across a large number of machines
190       and the second file can be used to configure  local  settings  for  one
191       particular machine.
192
193       The  default  list  of  directories to search is /etc/snmp, followed by
194       /usr/share/snmp,   followed   by   /usr/lib(64)/snmp,    followed    by
195       $HOME/.snmp.   This  list  can  be changed by setting the environmental
196       variable SNMPCONFPATH to be a (colon separated) list of directories  to
197       search.
198
199   init_snmp()
200       The  normal mode of operation would be to register the application-spe‐
201       cific configuration handlers, and then invoke init_snmp().  This  would
202       call the routines listed above to register the internal library config‐
203       uration handlers, process any configuration tokens registered with reg‐
204       ister_premib_handler(), read in the textual MIB files using init_mib(),
205       and finally parse the configuration file tokens registered with  regis‐
206       ter_config_handler().
207
208       If the init_snmp() function is used, none of these functions need to be
209       explicitly called by the application.
210

HELP STRINGS AND ERRORS

212       The usageLine parameter passed to register_config_handler() and similar
213       calls,   is  used  to  display  help  information  when  the  read_con‐
214       fig_print_usage() function is called.  This function is used by all  of
215       the  applications  when  the -H flag is passed on the command line.  It
216       prints a summary of all of the configuration file lines, and the  asso‐
217       ciated files, that the configuration system understands.  The usageLine
218       parameter should be a list of arguments expected after the  token,  and
219       not a lengthy description (which should go into a manual page instead).
220       The lead prefix will be prepended to each line that the function prints
221       to stderr, where it displays its output.
222
223       The   init_snmp()  function  should  be  called  before  the  read_con‐
224       fig_print_usage() function is called, so that the library can  register
225       its   configuration   file   directives   as  well  for  the  read_con‐
226       fig_print_usage() function to display.
227
228   Error Handling Functions
229       The two functions config_pwarn() and config_perror() both take an error
230       string  as  an  argument and print it to stderr along with the file and
231       line number that caused the error.  A call to the second function  will
232       also force read_configs() to eventually return with an error code indi‐
233       cating to it's calling function that it should abort the  operation  of
234       the application.
235

ENVIRONMENT VARIABLES

237       SNMPCONFPATH
238                 A  colon separated list of directories to search for configu‐
239                 ration            files             in.              Default:
240                 /etc/snmp:/usr/share/snmp:/usr/lib(64)/snmp:$HOME/.snmp
241

SEE ALSO

243       mib_api(3), snmp_api(3)
244
245
246
2474.2 Berkeley Distribution         07 Mar 2002                    CONFIG_API(3)
Impressum