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

NAME

6       register_config_handler,      register_const_config_handler,     regis‐
7       ter_prenetsnmp_mib_handler,      unregister_config_handler,      regis‐
8       ter_mib_handlers,   unregister_all_config_handlers,   register_app_con‐
9       fig_handler,  register_app_prenetsnmp_mib_handler,  unregister_app_con‐
10       fig_handler,  read_configs,  read_premib_configs, read_config_print_us‐
11       age, config_perror, config_pwarn - netsnmp_config_api functions
12

SYNOPSIS

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

DESCRIPTION

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

REGISTERING A HANDLER

94       register_config_handler()
95              Registers  a  configuration  handler  routine,  which  should be
96              called to process configuration  directives  starting  with  the
97              specified token.  For example:
98
99                     register_config_handler("snmp",   "exampleToken",   exam‐
100                     ple_handler, NULL, "ARG1 [ARG2]");
101
102              would register the example_handler() function so  that  it  will
103              get  called every time the first word of a line in the snmp.conf
104              configuration file(s) matches "exampleToken".
105              Calling the appropriate handlers to  process  the  configuration
106              file directives is the responsibility of read_configs() (see be‐
107              low).
108
109       register_const_config_handler()
110              Similar  to  the  register_config_handler()  function,  but  the
111              parser  routine  is  explicitly  constrained  to  not modify the
112              string being parsed.
113
114       register_prenetsnmp_mib_handler()
115              Similar to the register_config_handler() function, but the  reg‐
116              istered  handler  routine will be called before the textual MIBs
117              are read in.  This is typically used for tokens that will affect
118              the  configuration  of the MIB parser, and will normally only be
119              used within the SNMP library itself.
120
121       register_mib_handlers()
122              Initialisation routine to register  the  internal  SNMP  library
123              configuration handlers.
124
125       unregister_config_handler()
126              Removes  the  registered configuration handler for the specified
127              filePrefix and token.
128
129       unregister_all_config_handlers()
130              Removes all registered configuration handlers.
131
132
133   Token Handlers
134       Handler functions should have the following signature:
135
136              void handler(const char *token, char *line);
137              or
138              void handler(const char *token, const char *line); br (if regis‐
139              tered using register_const_config_handler)
140
141       The function will be called with two arguments, the first being the to‐
142       ken that triggered the call to this function (i.e. the token used  when
143       registering  the  handler),  and  the second being the remainder of the
144       configuration file line (i.e. everything following the white space fol‐
145       lowing the matched token).
146
147
148   Freeing Handlers
149       If the token handler function dynamically allocates resources when pro‐
150       cessing a configuration entry, then these may need to be  released  be‐
151       fore re-reading the configuration files.  If the fourth parameter ( re‐
152       leaser ) passed to register_config_handler is non-NULL, then this spec‐
153       ifies  a  function  to  be  called  before re-reading the configuration
154       files.  This function should free any resources allocated by the  token
155       handler  function  and reset its notion of the configuration to its de‐
156       fault.  The token handler function can then safely be called again.  No
157       arguments are passed to the resource freeing handler.
158       Note  that this function is not called when the handler is unregistered
159       individually (but is called as part of unregister_all_config_handlers()
160       ).
161
162
163   Application Handlers
164       register_app_config_handler()
165
166       register_app_prenetsnmp_mib_handler()
167
168       unregister_app_config_handler()
169              These functions are analagous to register_config_handler(), reg‐
170              ister_prenetsnmp_mib_handler()  and  unregister_config_handler()
171              but do not require the file type argument (which is filled in by
172              the application).  It is intended that MIB modules  written  for
173              the  agent  use  these functions to allow the agent to have more
174              control over which configuration files are read  (typically  the
175              snmpd.conf files).
176

READING CONFIGURATION FILES

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

HELP STRINGS AND ERRORS

233       The usageLine parameter passed to register_config_handler() and similar
234       calls,   is  used  to  display  help  information  when  the  read_con‐
235       fig_print_usage() function is called.  This function is used by all  of
236       the  applications  when  the -H flag is passed on the command line.  It
237       prints a summary of all of the configuration file lines, and the  asso‐
238       ciated files, that the configuration system understands.  The usageLine
239       parameter should be a list of arguments expected after the  token,  and
240       not a lengthy description (which should go into a manual page instead).
241       The lead prefix will be prepended to each line that the function prints
242       to stderr, where it displays its output.
243
244       The   init_snmp()  function  should  be  called  before  the  read_con‐
245       fig_print_usage() function is called, so that the library can  register
246       its configuration file directives as well for the read_config_print_us‐
247       age() function to display.
248
249   Error Handling Functions
250       The two functions config_pwarn() and config_perror() both take an error
251       string  as  an  argument and print it to stderr along with the file and
252       line number that caused the error.  A call to the second function  will
253       also force read_configs() to eventually return with an error code indi‐
254       cating to it's calling function that it should abort the  operation  of
255       the application.
256

ENVIRONMENT VARIABLES

258       SNMPCONFPATH
259                 A  colon separated list of directories to search for configu‐
260                 ration files in.  Default:
261                 /etc/snmp:/usr/share/snmp:/usr/lib(64)/snmp:$HOME/.snmp
262

SEE ALSO

264       netsnmp_mib_api(3), snmp_api(3)
265
266
267
268V5.9.1                            13 Aug 2010            NETSNMP_CONFIG_API(3)
Impressum