1NETSNMP_CONFIG_API(3) Net-SNMP NETSNMP_CONFIG_API(3)
2
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
15 #include <net-snmp/config_api.h>
16 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 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 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 void unregister_config_handler(const char *filePrefix,
40 const char *token);
41 void register_mib_handlers(void);
43 void unregister_all_config_handlers(void);
44 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 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 void unregister_app_config_handler(const char *token);
59 Reading Configuration Files
61 void read_premib_configs(void);
62 void read_configs(void);
63 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
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 1. Registration of handlers.
76 2. Reading of the configuration files for pre-MIB parsing require‐
78 ments.
79 3. Reading and parsing of the textual MIB files.
81 4. Reading of the configuration files for configuration direc‐
83 tives.
84 5. Optionally re-reading the configuration files at a future date.
86 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
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 register_config_handler("snmp", "exampleToken", exam‐
101 ple_handler, NULL, "ARG1 [ARG2]");
102 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 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 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 register_mib_handlers()
123 Initialisation routine to register the internal SNMP library
124 configuration handlers.
125 unregister_config_handler()
127 Removes the registered configuration handler for the specified
128 filePrefix and token.
129 unregister_all_config_handlers()
131 Removes all registered configuration handlers.
132 Token Handlers
135 Handler functions should have the following signature:
136 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 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 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 Application Handlers
165 register_app_config_handler()
166 register_app_prenetsnmp_mib_handler()
168 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
179 read_premib_configs()
180 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 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 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 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 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 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 If the init_snmp() function is used, none of these functions need to be
231 explicitly called by the application.
232
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 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 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
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
265 netsnmp_mib_api(3), snmp_api(3)
266V5.9 13 Aug 2010 NETSNMP_CONFIG_API(3)