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_config_print_us‐
11 age, config_perror, config_pwarn - netsnmp_config_api functions
12
14 #include <net-snmp/config_api.h>
15 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 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 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 void unregister_config_handler(const char *filePrefix,
39 const char *token);
40 void register_mib_handlers(void);
42 void unregister_all_config_handlers(void);
43 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 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 void unregister_app_config_handler(const char *token);
58 Reading Configuration Files
60 void read_premib_configs(void);
61 void read_configs(void);
62 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
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 1. Registration of handlers.
75 2. Reading of the configuration files for pre-MIB parsing require‐
77 ments.
78 3. Reading and parsing of the textual MIB files.
80 4. Reading of the configuration files for configuration direc‐
82 tives.
83 5. Optionally re-reading the configuration files at a future date.
85 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
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 register_config_handler("snmp", "exampleToken", exam‐
100 ple_handler, NULL, "ARG1 [ARG2]");
101 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 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 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 register_mib_handlers()
122 Initialisation routine to register the internal SNMP library
123 configuration handlers.
124 unregister_config_handler()
126 Removes the registered configuration handler for the specified
127 filePrefix and token.
128 unregister_all_config_handlers()
130 Removes all registered configuration handlers.
131 Token Handlers
134 Handler functions should have the following signature:
135 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 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 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 Application Handlers
164 register_app_config_handler()
165 register_app_prenetsnmp_mib_handler()
167 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
178 read_premib_configs()
179 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 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 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 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 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 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 If the init_snmp() function is used, none of these functions need to be
230 explicitly called by the application.
231
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 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 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
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
264 netsnmp_mib_api(3), snmp_api(3)
265V5.9.4.pre2 13 Aug 2010 NETSNMP_CONFIG_API(3)