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_con‐
11       fig_print_usage, config_perror, config_pwarn - netsnmp_config_api func‐
12       tions
13

SYNOPSIS

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

DESCRIPTION

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

REGISTERING A HANDLER

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

READING CONFIGURATION FILES

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

HELP STRINGS AND ERRORS

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

ENVIRONMENT VARIABLES

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

SEE ALSO

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