xref: /freebsd/contrib/bsnmp/snmpd/snmpmod.h (revision 282a3889ebf826db9839be296ff1dd903f6d6d6e)
1 /*
2  * Copyright (c) 2001-2003
3  *	Fraunhofer Institute for Open Communication Systems (FhG Fokus).
4  *	All rights reserved.
5  *
6  * Author: Harti Brandt <harti@freebsd.org>
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  * 1. Redistributions of source code must retain the above copyright
12  *    notice, this list of conditions and the following disclaimer.
13  * 2. Redistributions in binary form must reproduce the above copyright
14  *    notice, this list of conditions and the following disclaimer in the
15  *    documentation and/or other materials provided with the distribution.
16  *
17  * THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27  * SUCH DAMAGE.
28  *
29  * $Begemot: bsnmp/snmpd/snmpmod.h,v 1.32 2006/02/14 09:04:20 brandt_h Exp $
30  *
31  * SNMP daemon data and functions exported to modules.
32  */
33 #ifndef snmpmod_h_
34 #define snmpmod_h_
35 
36 #include <sys/types.h>
37 #include <sys/socket.h>
38 #include <net/if.h>
39 #include <netinet/in.h>
40 #include "asn1.h"
41 #include "snmp.h"
42 #include "snmpagent.h"
43 
44 #define MAX_MOD_ARGS	16
45 
46 /*
47  * These macros help to handle object lists for SNMP tables. They use
48  * tail queues to hold the objects in ascending order in the list.
49  * ordering can be done either on an integer/unsigned field, an asn_oid
50  * or an ordering function.
51  */
52 #define INSERT_OBJECT_OID_LINK_INDEX(PTR, LIST, LINK, INDEX) do {	\
53 	__typeof (PTR) _lelem;						\
54 									\
55 	TAILQ_FOREACH(_lelem, (LIST), LINK)				\
56 		if (asn_compare_oid(&_lelem->INDEX, &(PTR)->INDEX) > 0)	\
57 			break;						\
58 	if (_lelem == NULL)						\
59 		TAILQ_INSERT_TAIL((LIST), (PTR), LINK);			\
60 	else								\
61 		TAILQ_INSERT_BEFORE(_lelem, (PTR), LINK);		\
62     } while (0)
63 
64 #define INSERT_OBJECT_INT_LINK_INDEX(PTR, LIST, LINK, INDEX) do {	\
65 	__typeof (PTR) _lelem;						\
66 									\
67 	TAILQ_FOREACH(_lelem, (LIST), LINK)				\
68 		if ((asn_subid_t)_lelem->INDEX > (asn_subid_t)(PTR)->INDEX)\
69 			break;						\
70 	if (_lelem == NULL)						\
71 		TAILQ_INSERT_TAIL((LIST), (PTR), LINK);			\
72 	else								\
73 		TAILQ_INSERT_BEFORE(_lelem, (PTR), LINK);		\
74     } while (0)
75 
76 #define	INSERT_OBJECT_FUNC_LINK(PTR, LIST, LINK, FUNC) do {		\
77 	__typeof (PTR) _lelem;						\
78 									\
79 	TAILQ_FOREACH(_lelem, (LIST), LINK)				\
80 		if ((FUNC)(_lelem, (PTR)) > 0)				\
81 			break;						\
82 	if (_lelem == NULL)						\
83 		TAILQ_INSERT_TAIL((LIST), (PTR), LINK);			\
84 	else								\
85 		TAILQ_INSERT_BEFORE(_lelem, (PTR), LINK);		\
86     } while (0)
87 
88 #define	INSERT_OBJECT_FUNC_LINK_REV(PTR, LIST, HEAD, LINK, FUNC) do {	\
89 	__typeof (PTR) _lelem;						\
90 									\
91 	TAILQ_FOREACH_REVERSE(_lelem, (LIST), HEAD, LINK)		\
92 		if ((FUNC)(_lelem, (PTR)) < 0)				\
93 			break;						\
94 	if (_lelem == NULL)						\
95 		TAILQ_INSERT_HEAD((LIST), (PTR), LINK);			\
96 	else								\
97 		TAILQ_INSERT_AFTER((LIST), _lelem, (PTR), LINK);	\
98     } while (0)
99 
100 #define FIND_OBJECT_OID_LINK_INDEX(LIST, OID, SUB, LINK, INDEX) ({	\
101 	__typeof (TAILQ_FIRST(LIST)) _lelem;				\
102 									\
103 	TAILQ_FOREACH(_lelem, (LIST), LINK)				\
104 		if (index_compare(OID, SUB, &_lelem->INDEX) == 0)	\
105 			break;						\
106 	(_lelem);							\
107     })
108 
109 #define NEXT_OBJECT_OID_LINK_INDEX(LIST, OID, SUB, LINK, INDEX) ({	\
110 	__typeof (TAILQ_FIRST(LIST)) _lelem;				\
111 									\
112 	TAILQ_FOREACH(_lelem, (LIST), LINK)				\
113 		if (index_compare(OID, SUB, &_lelem->INDEX) < 0)	\
114 			break;						\
115 	(_lelem);							\
116     })
117 
118 #define FIND_OBJECT_INT_LINK_INDEX(LIST, OID, SUB, LINK, INDEX) ({	\
119 	__typeof (TAILQ_FIRST(LIST)) _lelem;				\
120 									\
121 	if ((OID)->len - SUB != 1)					\
122 		_lelem = NULL;						\
123 	else								\
124 		TAILQ_FOREACH(_lelem, (LIST), LINK)			\
125 			if ((OID)->subs[SUB] == (asn_subid_t)_lelem->INDEX)\
126 				break;					\
127 	(_lelem);							\
128     })
129 
130 #define NEXT_OBJECT_INT_LINK_INDEX(LIST, OID, SUB, LINK, INDEX) ({	\
131 	__typeof (TAILQ_FIRST(LIST)) _lelem;				\
132 									\
133 	if ((OID)->len - SUB == 0)					\
134 		_lelem = TAILQ_FIRST(LIST);				\
135 	else								\
136 		TAILQ_FOREACH(_lelem, (LIST), LINK)			\
137 			if ((OID)->subs[SUB] < (asn_subid_t)_lelem->INDEX)\
138 				break;					\
139 	(_lelem);							\
140     })
141 
142 #define FIND_OBJECT_FUNC_LINK(LIST, OID, SUB, LINK, FUNC) ({		\
143 	__typeof (TAILQ_FIRST(LIST)) _lelem;				\
144 									\
145 	TAILQ_FOREACH(_lelem, (LIST), LINK)				\
146 		if ((FUNC)(OID, SUB, _lelem) == 0)			\
147 			break;						\
148 	(_lelem);							\
149     })
150 
151 #define NEXT_OBJECT_FUNC_LINK(LIST, OID, SUB, LINK, FUNC) ({		\
152 	__typeof (TAILQ_FIRST(LIST)) _lelem;				\
153 									\
154 	TAILQ_FOREACH(_lelem, (LIST), LINK)				\
155 		if ((FUNC)(OID, SUB, _lelem) < 0)			\
156 			break;						\
157 	(_lelem);							\
158     })
159 
160 /*
161  * Macros for the case where the index field is called 'index'
162  */
163 #define INSERT_OBJECT_OID_LINK(PTR, LIST, LINK)				\
164     INSERT_OBJECT_OID_LINK_INDEX(PTR, LIST, LINK, index)
165 
166 #define INSERT_OBJECT_INT_LINK(PTR, LIST, LINK) do {			\
167     INSERT_OBJECT_INT_LINK_INDEX(PTR, LIST, LINK, index)
168 
169 #define FIND_OBJECT_OID_LINK(LIST, OID, SUB, LINK)			\
170     FIND_OBJECT_OID_LINK_INDEX(LIST, OID, SUB, LINK, index)
171 
172 #define NEXT_OBJECT_OID_LINK(LIST, OID, SUB, LINK)			\
173     NEXT_OBJECT_OID_LINK_INDEX(LIST, OID, SUB, LINK, index)
174 
175 #define FIND_OBJECT_INT_LINK(LIST, OID, SUB, LINK)			\
176     FIND_OBJECT_INT_LINK_INDEX(LIST, OID, SUB, LINK, index)
177 
178 #define NEXT_OBJECT_INT_LINK(LIST, OID, SUB, LINK)			\
179     NEXT_OBJECT_INT_LINK_INDEX(LIST, OID, SUB, LINK, index)
180 
181 /*
182  * Macros for the case where the index field is called 'index' and the
183  * link field 'link'.
184  */
185 #define INSERT_OBJECT_OID(PTR, LIST)					\
186     INSERT_OBJECT_OID_LINK_INDEX(PTR, LIST, link, index)
187 
188 #define INSERT_OBJECT_INT(PTR, LIST)					\
189     INSERT_OBJECT_INT_LINK_INDEX(PTR, LIST, link, index)
190 
191 #define	INSERT_OBJECT_FUNC_REV(PTR, LIST, HEAD, FUNC)			\
192     INSERT_OBJECT_FUNC_LINK_REV(PTR, LIST, HEAD, link, FUNC)
193 
194 #define FIND_OBJECT_OID(LIST, OID, SUB)					\
195     FIND_OBJECT_OID_LINK_INDEX(LIST, OID, SUB, link, index)
196 
197 #define FIND_OBJECT_INT(LIST, OID, SUB)					\
198     FIND_OBJECT_INT_LINK_INDEX(LIST, OID, SUB, link, index)
199 
200 #define	FIND_OBJECT_FUNC(LIST, OID, SUB, FUNC)				\
201     FIND_OBJECT_FUNC_LINK(LIST, OID, SUB, link, FUNC)
202 
203 #define NEXT_OBJECT_OID(LIST, OID, SUB)					\
204     NEXT_OBJECT_OID_LINK_INDEX(LIST, OID, SUB, link, index)
205 
206 #define NEXT_OBJECT_INT(LIST, OID, SUB)					\
207     NEXT_OBJECT_INT_LINK_INDEX(LIST, OID, SUB, link, index)
208 
209 #define	NEXT_OBJECT_FUNC(LIST, OID, SUB, FUNC)				\
210     NEXT_OBJECT_FUNC_LINK(LIST, OID, SUB, link, FUNC)
211 
212 struct lmodule;
213 
214 /* The tick when the program was started. This is the absolute time of
215  * the start in 100th of a second. */
216 extern uint64_t start_tick;
217 
218 /* The tick when the current packet was received. This is the absolute
219  * time in 100th of second. */
220 extern uint64_t this_tick;
221 
222 /* Get the current absolute time in 100th of a second. */
223 uint64_t get_ticks(void);
224 
225 /*
226  * Return code for proxy function
227  */
228 enum snmpd_proxy_err {
229 	/* proxy code will process the PDU */
230 	SNMPD_PROXY_OK,
231 	/* proxy code does not process PDU */
232 	SNMPD_PROXY_REJ,
233 	/* drop this PDU */
234 	SNMPD_PROXY_DROP,
235 	/* drop because of bad community */
236 	SNMPD_PROXY_BADCOMM,
237 	/* drop because of bad community use */
238 	SNMPD_PROXY_BADCOMMUSE
239 };
240 
241 /*
242  * Input handling
243  */
244 enum snmpd_input_err {
245 	/* proceed with packet */
246 	SNMPD_INPUT_OK,
247 	/* fatal error in packet, ignore it */
248 	SNMPD_INPUT_FAILED,
249 	/* value encoding has wrong length in a SET operation */
250 	SNMPD_INPUT_VALBADLEN,
251 	/* value encoding is out of range */
252 	SNMPD_INPUT_VALRANGE,
253 	/* value has bad encoding */
254 	SNMPD_INPUT_VALBADENC,
255 	/* need more data (truncated packet) */
256 	SNMPD_INPUT_TRUNC,
257 	/* unknown community */
258 	SNMPD_INPUT_BAD_COMM,
259 };
260 
261 /*
262  * Every loadable module must have one of this structures with
263  * the external name 'config'.
264  */
265 struct snmp_module {
266 	/* a comment describing what this module implements */
267 	const char *comment;
268 
269 	/* the initialization function */
270 	int (*init)(struct lmodule *, int argc, char *argv[]);
271 
272 	/* the finalisation function */
273 	int (*fini)(void);
274 
275 	/* the idle function */
276 	void (*idle)(void);
277 
278 	/* the dump function */
279 	void (*dump)(void);
280 
281 	/* re-configuration function */
282 	void (*config)(void);
283 
284 	/* start operation */
285 	void (*start)(void);
286 
287 	/* proxy a PDU */
288 	enum snmpd_proxy_err (*proxy)(struct snmp_pdu *, void *,
289 	    const struct asn_oid *, const struct sockaddr *, socklen_t,
290 	    enum snmpd_input_err, int32_t, int);
291 
292 	/* the tree this module is going to server */
293 	const struct snmp_node *tree;
294 	u_int tree_size;
295 
296 	/* function called, when another module was unloaded/loaded */
297 	void (*loading)(const struct lmodule *, int);
298 };
299 
300 /*
301  * Stuff exported to modules
302  */
303 
304 /*
305  * The system group.
306  */
307 struct systemg {
308 	u_char		*descr;
309 	struct asn_oid	object_id;
310 	u_char		*contact;
311 	u_char		*name;
312 	u_char		*location;
313 	u_int32_t	services;
314 	u_int32_t	or_last_change;
315 };
316 extern struct systemg systemg;
317 
318 /*
319  * Community support.
320  *
321  * We have 2 fixed communities for SNMP read and write access. Modules
322  * can create their communities dynamically. They are deleted automatically
323  * if the module is unloaded.
324  */
325 #define COMM_INITIALIZE	0
326 #define COMM_READ	1
327 #define COMM_WRITE	2
328 
329 u_int comm_define(u_int, const char *descr, struct lmodule *, const char *str);
330 const char * comm_string(u_int);
331 
332 /* community for current packet */
333 extern u_int community;
334 
335 /*
336  * Well known OIDs
337  */
338 extern const struct asn_oid oid_zeroDotZero;
339 
340 /*
341  * Request ID ranges.
342  *
343  * A module can request a range of request ids and associate them with a
344  * type field. All ranges are deleted if a module is unloaded.
345  */
346 u_int reqid_allocate(int size, struct lmodule *);
347 int32_t reqid_next(u_int type);
348 int32_t reqid_base(u_int type);
349 int reqid_istype(int32_t reqid, u_int type);
350 u_int reqid_type(int32_t reqid);
351 
352 /*
353  * Timers.
354  */
355 void *timer_start(u_int, void (*)(void *), void *, struct lmodule *);
356 void *timer_start_repeat(u_int, u_int, void (*)(void *), void *,
357     struct lmodule *);
358 void timer_stop(void *);
359 
360 /*
361  * File descriptors
362  */
363 void *fd_select(int, void (*)(int, void *), void *, struct lmodule *);
364 void fd_deselect(void *);
365 void fd_suspend(void *);
366 int fd_resume(void *);
367 
368 /*
369  * Object resources
370  */
371 u_int or_register(const struct asn_oid *, const char *, struct lmodule *);
372 void or_unregister(u_int);
373 
374 /*
375  * Buffers
376  */
377 void *buf_alloc(int tx);
378 size_t buf_size(int tx);
379 
380 /* decode PDU and find community */
381 enum snmpd_input_err snmp_input_start(const u_char *, size_t, const char *,
382     struct snmp_pdu *, int32_t *, size_t *);
383 
384 /* process the pdu. returns either _OK or _FAILED */
385 enum snmpd_input_err snmp_input_finish(struct snmp_pdu *, const u_char *,
386     size_t, u_char *, size_t *, const char *, enum snmpd_input_err, int32_t,
387     void *);
388 
389 void snmp_output(struct snmp_pdu *, u_char *, size_t *, const char *);
390 void snmp_send_port(void *, const struct asn_oid *, struct snmp_pdu *,
391 	const struct sockaddr *, socklen_t);
392 
393 /* sending traps */
394 void snmp_send_trap(const struct asn_oid *, ...);
395 
396 /*
397  * Action support
398  */
399 int string_save(struct snmp_value *, struct snmp_context *, ssize_t, u_char **);
400 void string_commit(struct snmp_context *);
401 void string_rollback(struct snmp_context *, u_char **);
402 int string_get(struct snmp_value *, const u_char *, ssize_t);
403 int string_get_max(struct snmp_value *, const u_char *, ssize_t, size_t);
404 void string_free(struct snmp_context *);
405 
406 int ip_save(struct snmp_value *, struct snmp_context *, u_char *);
407 void ip_rollback(struct snmp_context *, u_char *);
408 void ip_commit(struct snmp_context *);
409 int ip_get(struct snmp_value *, u_char *);
410 
411 int oid_save(struct snmp_value *, struct snmp_context *, struct asn_oid *);
412 void oid_rollback(struct snmp_context *, struct asn_oid *);
413 void oid_commit(struct snmp_context *);
414 int oid_get(struct snmp_value *, const struct asn_oid *);
415 
416 int index_decode(const struct asn_oid *oid, u_int sub, u_int code, ...);
417 int index_compare(const struct asn_oid *, u_int, const struct asn_oid *);
418 int index_compare_off(const struct asn_oid *, u_int, const struct asn_oid *,
419     u_int);
420 void index_append(struct asn_oid *, u_int, const struct asn_oid *);
421 void index_append_off(struct asn_oid *, u_int, const struct asn_oid *, u_int);
422 
423 #endif
424