Debian Codegraph @

agent/mibgroup/examples/example.c

raw
1 /*
2 * Template MIB group implementation - example.c
3 *
4 */
5
6 /*
7 * include important headers
8 */
9 #include <net-snmp/net-snmp-config.h>
10 #ifdef HAVE_STDLIB_H
11 #include <stdlib.h>
12 #endif
13 #ifdef HAVE_STRING_H
14 #include <string.h>
15 #else
16 #include <strings.h>
17 #endif
18
19 #include <net-snmp/net-snmp-includes.h>
20 #include <net-snmp/agent/net-snmp-agent-includes.h>
21
22 /*
23 * header_generic() comes from here
24 */
25 #include "util_funcs/header_generic.h"
26
27 /*
28 * include our .h file
29 */
30 #include "example.h"
31
32
33 /*
34 * Certain objects can be set via configuration file directives.
35 * These variables hold the values for such objects, as they need to
36 * be accessible to both the config handlers, and the callback routine.
37 */
38 #define EXAMPLE_STR_LEN 300
39 #define EXAMPLE_STR_DEFAULT "life the universe and everything"
40 int example_int = 42;
41 char example_str[EXAMPLE_STR_LEN];
42
43 /*
44 * Forward declarations for the config handlers
45 */
46 void example_parse_config_exampleint(const char *token,
47 char *cptr);
48 void example_parse_config_examplestr(const char *token,
49 char *cptr);
50 void example_free_config_exampleint(void);
51 void example_free_config_examplestr(void);
52
53
54 /*********************
55 *
56 * Initialisation & common implementation functions
57 *
58 *********************/
59
60 /*
61 * This array structure defines a representation of the
62 * MIB being implemented.
63 *
64 * The type of the array is 'struct variableN', where N is
65 * large enough to contain the longest OID sub-component
66 * being loaded. This will normally be the maximum value
67 * of the fifth field in each line. In this case, the second
68 * and third entries are both of size 2, so we're using
69 * 'struct variable2'
70 *
71 * The supported values for N are listed in <agent/var_struct.h>
72 * If the value you need is not listed there, simply use the
73 * next largest that is.
74 *
75 * The format of each line is as follows
76 * (using the first entry as an example):
77 * 1: EXAMPLESTRING:
78 * The magic number defined in the example header file.
79 * This is passed to the callback routine and is used
80 * to determine which object is being queried.
81 * 2: ASN_OCTET_STR:
82 * The type of the object.
83 * Valid types are listed in <snmp_impl.h>
84 * 3: NETSNMP_OLDAPI_RONLY (or NETSNMP_OLDAPI_RWRITE):
85 * Whether this object can be SET or not.
86 * 4: var_example:
87 * The callback routine, used when the object is queried.
88 * This will usually be the same for all objects in a module
89 * and is typically defined later in this file.
90 * 5: 1:
91 * The length of the OID sub-component (the next field)
92 * 6: {1}:
93 * The OID sub-components of this entry.
94 * In other words, the bits of the full OID that differ
95 * between the various entries of this array.
96 * This value is appended to the common prefix (defined later)
97 * to obtain the full OID of each entry.
98 */
99 struct variable2 example_variables[] = {
100 {EXAMPLESTRING, ASN_OCTET_STR, NETSNMP_OLDAPI_RONLY,
101 var_example, 1, {1}},
102 {EXAMPLEINTEGER, ASN_INTEGER, NETSNMP_OLDAPI_RWRITE,
103 var_example, 2, {2, 1}},
104 {EXAMPLEOBJECTID, ASN_OBJECT_ID, NETSNMP_OLDAPI_RONLY,
105 var_example, 2, {2, 2}},
106 {EXAMPLETIMETICKS, ASN_TIMETICKS, NETSNMP_OLDAPI_RONLY,
107 var_example, 1, {3}},
108 {EXAMPLEIPADDRESS, ASN_IPADDRESS, NETSNMP_OLDAPI_RONLY,
109 var_example, 1, {4}},
110 {EXAMPLECOUNTER, ASN_COUNTER, NETSNMP_OLDAPI_RONLY,
111 var_example, 1, {5}},
112 {EXAMPLEGAUGE, ASN_GAUGE, NETSNMP_OLDAPI_RONLY,
113 var_example, 1, {6}},
114 {EXAMPLETRIGGERTRAP, ASN_INTEGER, NETSNMP_OLDAPI_RWRITE,
115 var_example, 1, {7}},
116 {EXAMPLETRIGGERTRAP2, ASN_INTEGER, NETSNMP_OLDAPI_RWRITE,
117 var_example, 1, {8}}
118 };
119
120 /*
121 * This array defines the OID of the top of the mib tree that we're
122 * registering underneath.
123 * Note that this needs to be the correct size for the OID being
124 * registered, so that the length of the OID can be calculated.
125 * The format given here is the simplest way to achieve this.
126 */
127 oid example_variables_oid[] = { 1, 3, 6, 1, 4, 1, 2021, 254 };
128
129
130
131 /*
132 * This function is called at the time the agent starts up
133 * to do any initializations that might be required.
134 *
135 * In theory it is optional and can be omitted if no
136 * initialization is needed. In practise, every module
137 * will need to register itself (or the objects being
138 * implemented will not appear in the MIB tree), and this
139 * registration is typically done here.
140 *
141 * If this function is added or removed, you must re-run
142 * the configure script, to detect this change.
143 */
144 void
145 init_example(void)
146 {
147 /*
148 * Register ourselves with the agent to handle our mib tree.
149 * The arguments are:
150 * descr: A short description of the mib group being loaded.
151 * var: The variable structure to load.
152 * (the name of the variable structure defined above)
153 * vartype: The type of this variable structure
154 * theoid: The OID pointer this MIB is being registered underneath.
155 */
156 REGISTER_MIB("example", example_variables, variable2,
157 example_variables_oid);
158
159
160 /*
161 * Register config handlers for the two objects that can be set
162 * via configuration file directive.
163 * Also set a default value for the string object. Note that the
164 * example integer variable was initialised above.
165 */
166 strlcpy(example_str, EXAMPLE_STR_DEFAULT, sizeof(example_str));
167
168 snmpd_register_config_handler("exampleint",
169 example_parse_config_exampleint,
170 example_free_config_exampleint,
171 "exampleint value");
172 snmpd_register_config_handler("examplestr",
173 example_parse_config_examplestr,
174 example_free_config_examplestr,
175 "examplestr value");
176 snmpd_register_config_handler("examplestring",
177 example_parse_config_examplestr,
178 example_free_config_examplestr,
179 "examplestring value");
180
181 /*
182 * One common requirement is to read values from the kernel.
183 * This is usually initialised here, to speed up access when the
184 * information is read in, as a response to an incoming request.
185 *
186 * This module doesn't actually use this mechanism,
187 * so this call is commented out here.
188 */
189 /*
190 * auto_nlist( "example_symbol", 0, 0 );
191 */
192 }
193
194 /*********************
195 *
196 * Configuration file handling functions
197 *
198 *********************/
199
200 void
201 example_parse_config_exampleint(const char *token, char *cptr)
202 {
203 example_int = atoi(cptr);
204 }
205
206 void
207 example_parse_config_examplestr(const char *token, char *cptr)
208 {
209 /*
210 * Make sure the string fits in the space allocated for it.
211 */
212 if (strlen(cptr) < sizeof(example_str))
213 strcpy(example_str, cptr);
214 else {
215 /*
216 * Truncate the string if necessary.
217 * An alternative approach would be to log an error,
218 * and discard this value altogether.
219 */
220 sprintf(example_str, "%.*s...", (int) (sizeof(example_str) - 4), cptr);
221 netsnmp_assert(strlen(example_str) < sizeof(example_str));
222 }
223 }
224
225 /*
226 * We don't need to do anything special when closing down
227 */
228 void
229 example_free_config_exampleint(void)
230 {
231 }
232
233 void
234 example_free_config_examplestr(void)
235 {
236 }
237
238 /*********************
239 *
240 * System specific implementation functions
241 *
242 *********************/
243
244 /*
245 * Define the callback function used in the example_variables structure.
246 * This is called whenever an incoming request refers to an object
247 * within this sub-tree.
248 *
249 * Four of the parameters are used to pass information in.
250 * These are:
251 * vp The entry from the 'example_variables' array for the
252 * object being queried.
253 * name The OID from the request.
254 * length The length of this OID.
255 * exact A flag to indicate whether this is an 'exact' request
256 * (GET/SET) or an 'inexact' one (GETNEXT/GETBULK).
257 *
258 * Four of the parameters are used to pass information back out.
259 * These are:
260 * name The OID being returned.
261 * length The length of this OID.
262 * var_len The length of the answer being returned.
263 * write_method A pointer to the SET function for this object.
264 *
265 * Note that name & length serve a dual purpose in both roles.
266 */
267
268 u_char *
269 var_example(struct variable *vp,
270 oid * name,
271 size_t * length,
272 int exact, size_t * var_len, WriteMethod ** write_method)
273 {
274 /*
275 * The result returned from this function needs to be a pointer to
276 * static data (so that it can be accessed from outside).
277 * Define suitable variables for any type of data we may return.
278 */
279 static char string[EXAMPLE_STR_LEN]; /* for EXAMPLESTRING */
280 static oid oid_ret[8]; /* for EXAMPLEOBJECTID */
281 static long long_ret; /* for everything else */
282
283 /*
284 * Before returning an answer, we need to check that the request
285 * refers to a valid instance of this object. The utility routine
286 * 'header_generic' can be used to do this for scalar objects.
287 *
288 * This routine 'header_simple_table' does the same thing for "simple"
289 * tables. (See the AGENT.txt file for the definition of a simple table).
290 *
291 * Both these utility routines also set up default values for the
292 * return arguments (assuming the check succeeded).
293 * The name and length are set suitably for the current object,
294 * var_len assumes that the result is an integer of some form,
295 * and write_method assumes that the object cannot be set.
296 *
297 * If these assumptions are correct, this callback routine simply
298 * needs to return a pointer to the appropriate value (using 'long_ret').
299 * Otherwise, 'var_len' and/or 'write_method' should be set suitably.
300 */
301 DEBUGMSGTL(("example", "var_example entered\n"));
302 if (header_generic(vp, name, length, exact, var_len, write_method) ==
303 MATCH_FAILED)
304 return NULL;
305
306
307 /*
308 * Many object will need to obtain data from the operating system in
309 * order to return the appropriate value. Typically, this is done
310 * here - immediately following the 'header' call, and before the
311 * switch statement. This is particularly appropriate if a single
312 * interface call can return data for all the objects supported.
313 *
314 * This example module does not rely on external data, so no such
315 * calls are needed in this case.
316 */
317
318 /*
319 * Now use the magic number from the variable pointer 'vp' to
320 * select the particular object being queried.
321 * In each case, one of the static objects is set up with the
322 * appropriate information, and returned mapped to a 'u_char *'
323 */
324 switch (vp->magic) {
325 case EXAMPLESTRING:
326 strcpy(string, example_str);
327 /*
328 * Note that the assumption that the answer will be an
329 * integer does not hold true in this case, so the length
330 * of the answer needs to be set explicitly.
331 */
332 *var_len = strlen(string);
333 return (u_char *) string;
334
335 case EXAMPLEINTEGER:
336 /*
337 * Here the length assumption is correct, but the
338 * object is writeable, so we need to set the
339 * write_method pointer as well as the current value.
340 */
341 long_ret = example_int;
342 *write_method = write_exampleint;
343 return (u_char *) & long_ret;
344
345 case EXAMPLEOBJECTID:
346 oid_ret[0] = 1;
347 oid_ret[1] = 3;
348 oid_ret[2] = 6;
349 oid_ret[3] = 1;
350 oid_ret[4] = 4;
351 oid_ret[5] = oid_ret[6] = oid_ret[7] = 42;
352 /*
353 * Again, the assumption regarding the answer length is wrong.
354 */
355 *var_len = 8 * sizeof(oid);
356 return (u_char *) oid_ret;
357
358 case EXAMPLETIMETICKS:
359 /*
360 * Here both assumptions are correct,
361 * so we just need to set up the answer.
362 */
363 long_ret = 363136200; /* 42 days, 42 minutes and 42.0 seconds */
364 return (u_char *) & long_ret;
365
366 case EXAMPLEIPADDRESS:
367 /*
368 * ipaddresses get returned as a long. ick
369 */
370 /*
371 * we're returning 127.0.0.1
372 */
373 {
374 in_addr_t addr = ntohl(INADDR_LOOPBACK);
375 memcpy(string, &addr, sizeof(addr));
376 *var_len = sizeof(addr);
377 }
378 return (u_char *) string;
379
380 case EXAMPLECOUNTER:
381 long_ret = 42;
382 return (u_char *) & long_ret;
383
384 case EXAMPLEGAUGE:
385 long_ret = 42; /* Do we detect a theme running through these answers? */
386 return (u_char *) & long_ret;
387
388 case EXAMPLETRIGGERTRAP:
389 /*
390 * This object is essentially "write-only".
391 * It only exists to trigger the sending of a trap.
392 * Reading it will always return 0.
393 */
394 long_ret = 0;
395 *write_method = write_exampletrap;
396 return (u_char *) & long_ret;
397
398 case EXAMPLETRIGGERTRAP2:
399 /*
400 * This object is essentially "write-only".
401 * It only exists to trigger the sending of a v2 trap.
402 * Reading it will always return 0.
403 */
404 long_ret = 0;
405 *write_method = write_exampletrap2;
406 return (u_char *) & long_ret;
407
408 default:
409 /*
410 * This will only be triggered if there's a problem with
411 * the coding of the module. SNMP requests that reference
412 * a non-existant OID will be directed elsewhere.
413 * If this branch is reached, log an error, so that
414 * the problem can be investigated.
415 */
416 DEBUGMSGTL(("snmpd", "unknown sub-id %d in examples/var_example\n",
417 vp->magic));
418 }
419 /*
420 * If we fall through to here, fail by returning NULL.
421 * This is essentially a continuation of the 'default' case above.
422 */
423 return NULL;
424 }
425
426 /*********************
427 *
428 * Writeable object SET handling routines
429 *
430 *********************/
431 int
432 write_exampleint(int action,
433 u_char * var_val,
434 u_char var_val_type,
435 size_t var_val_len,
436 u_char * statP, oid * name, size_t name_len)
437 {
438 /*
439 * Define an arbitrary maximum permissible value
440 */
441 #define MAX_EXAMPLE_INT 100
442 static long intval;
443 static long old_intval;
444
445 switch (action) {
446 case RESERVE1:
447 /*
448 * Check that the value being set is acceptable
449 */
450 if (var_val_type != ASN_INTEGER) {
451 DEBUGMSGTL(("example", "%x not integer type", var_val_type));
452 return SNMP_ERR_WRONGTYPE;
453 }
454 if (var_val_len > sizeof(long)) {
455 DEBUGMSGTL(("example", "wrong length %" NETSNMP_PRIz "u",
456 var_val_len));
457 return SNMP_ERR_WRONGLENGTH;
458 }
459
460 intval = *((long *) var_val);
461 if (intval > MAX_EXAMPLE_INT) {
462 DEBUGMSGTL(("example", "wrong value %lx", intval));
463 return SNMP_ERR_WRONGVALUE;
464 }
465 break;
466
467 case RESERVE2:
468 /*
469 * This is conventially where any necesary
470 * resources are allocated (e.g. calls to malloc)
471 * Here, we are using static variables
472 * so don't need to worry about this.
473 */
474 break;
475
476 case FREE:
477 /*
478 * This is where any of the above resources
479 * are freed again (because one of the other
480 * values being SET failed for some reason).
481 * Again, since we are using static variables
482 * we don't need to worry about this either.
483 */
484 break;
485
486 case ACTION:
487 /*
488 * Set the variable as requested.
489 * Note that this may need to be reversed,
490 * so save any information needed to do this.
491 */
492 old_intval = example_int;
493 example_int = intval;
494 break;
495
496 case UNDO:
497 /*
498 * Something failed, so re-set the
499 * variable to its previous value
500 * (and free any allocated resources).
501 */
502 example_int = old_intval;
503 break;
504
505 case COMMIT:
506 /*
507 * Everything worked, so we can discard any
508 * saved information, and make the change
509 * permanent (e.g. write to the config file).
510 * We also free any allocated resources.
511 *
512 * In this case, there's nothing to do.
513 */
514 break;
515
516 }
517 return SNMP_ERR_NOERROR;
518 }
519
520 int
521 write_exampletrap(int action,
522 u_char * var_val,
523 u_char var_val_type,
524 size_t var_val_len,
525 u_char * statP, oid * name, size_t name_len)
526 {
527 long intval;
528
529 DEBUGMSGTL(("example", "write_exampletrap entered: action=%d\n",
530 action));
531 switch (action) {
532 case RESERVE1:
533 /*
534 * The only acceptable value is the integer 1
535 */
536 if (var_val_type != ASN_INTEGER) {
537 DEBUGMSGTL(("example", "%x not integer type", var_val_type));
538 return SNMP_ERR_WRONGTYPE;
539 }
540 if (var_val_len > sizeof(long)) {
541 DEBUGMSGTL(("example", "wrong length %" NETSNMP_PRIz "u",
542 var_val_len));
543 return SNMP_ERR_WRONGLENGTH;
544 }
545
546 intval = *((long *) var_val);
547 if (intval != 1) {
548 DEBUGMSGTL(("example", "wrong value %lx", intval));
549 return SNMP_ERR_WRONGVALUE;
550 }
551 break;
552
553 case RESERVE2:
554 /*
555 * No resources are required....
556 */
557 break;
558
559 case FREE:
560 /*
561 * ... so no resources need be freed
562 */
563 break;
564
565 case ACTION:
566 /*
567 * Having triggered the sending of a trap,
568 * it would be impossible to revoke this,
569 * so we can't actually invoke the action here.
570 */
571 break;
572
573 case UNDO:
574 /*
575 * We haven't done anything yet,
576 * so there's nothing to undo
577 */
578 break;
579
580 case COMMIT:
581 /*
582 * Everything else worked, so it's now safe
583 * to trigger the trap.
584 * Note that this is *only* acceptable since
585 * the trap sending routines are "failsafe".
586 * (In fact, they can fail, but they return no
587 * indication of this, which is the next best thing!)
588 */
589 DEBUGMSGTL(("example", "write_exampletrap sending the trap\n"));
590 send_easy_trap(SNMP_TRAP_ENTERPRISESPECIFIC, 99);
591 DEBUGMSGTL(("example", "write_exampletrap trap sent\n"));
592 break;
593
594 }
595 return SNMP_ERR_NOERROR;
596 }
597
598 /*
599 * this documents how to send a SNMPv2 (and higher) trap via the
600 * send_v2trap() API.
601 *
602 * Coding SNMP-v2 Trap:
603 *
604 * The SNMPv2-Trap PDU contains at least a pair of object names and
605 * values: - sysUpTime.0 whose value is the time in hundredths of a
606 * second since the netwok management portion of system was last
607 * reinitialized. - snmpTrapOID.0 which is part of the trap group SNMPv2
608 * MIB whose value is the object-id of the specific trap you have defined
609 * in your own MIB. Other variables can be added to characterize the
610 * trap.
611 *
612 * The function send_v2trap adds automatically the two objects but the
613 * value of snmpTrapOID.0 is 0.0 by default. If you want to add your trap
614 * name, you have to reconstruct this object and to add your own
615 * variable.
616 *
617 */
618
619
620
621 int
622 write_exampletrap2(int action,
623 u_char * var_val,
624 u_char var_val_type,
625 size_t var_val_len,
626 u_char * statP, oid * name, size_t name_len)
627 {
628 long intval;
629
630 /*
631 * these variables will be used when we send the trap
632 */
633 oid objid_snmptrap[] = { 1, 3, 6, 1, 6, 3, 1, 1, 4, 1, 0 }; /* snmpTrapOID.0 */
634 oid demo_trap[] = { 1, 3, 6, 1, 4, 1, 2021, 13, 990 }; /*demo-trap */
635 oid example_string_oid[] =
636 { 1, 3, 6, 1, 4, 1, 2021, 254, 1, 0 };
637 static netsnmp_variable_list var_trap;
638 static netsnmp_variable_list var_obj;
639
640 DEBUGMSGTL(("example", "write_exampletrap2 entered: action=%d\n",
641 action));
642 switch (action) {
643 case RESERVE1:
644 /*
645 * The only acceptable value is the integer 1
646 */
647 if (var_val_type != ASN_INTEGER) {
648 DEBUGMSGTL(("example", "%x not integer type", var_val_type));
649 return SNMP_ERR_WRONGTYPE;
650 }
651 if (var_val_len > sizeof(long)) {
652 DEBUGMSGTL(("example", "wrong length %" NETSNMP_PRIz "u",
653 var_val_len));
654 return SNMP_ERR_WRONGLENGTH;
655 }
656
657 intval = *((long *) var_val);
658 if (intval != 1) {
659 DEBUGMSGTL(("example", "wrong value %lx", intval));
660 return SNMP_ERR_WRONGVALUE;
661 }
662 break;
663
664 case RESERVE2:
665 /*
666 * No resources are required....
667 */
668 break;
669
670 case FREE:
671 /*
672 * ... so no resources need be freed
673 */
674 break;
675
676 case ACTION:
677 /*
678 * Having triggered the sending of a trap,
679 * it would be impossible to revoke this,
680 * so we can't actually invoke the action here.
681 */
682 break;
683
684 case UNDO:
685 /*
686 * We haven't done anything yet,
687 * so there's nothing to undo
688 */
689 break;
690
691 case COMMIT:
692 /*
693 * Everything else worked, so it's now safe
694 * to trigger the trap.
695 * Note that this is *only* acceptable since
696 * the trap sending routines are "failsafe".
697 * (In fact, they can fail, but they return no
698 * indication of this, which is the next best thing!)
699 */
700
701 /*
702 * trap definition objects
703 */
704
705 var_trap.next_variable = &var_obj; /* next variable */
706 var_trap.name = objid_snmptrap; /* snmpTrapOID.0 */
707 var_trap.name_length = sizeof(objid_snmptrap) / sizeof(oid); /* number of sub-ids */
708 var_trap.type = ASN_OBJECT_ID;
709 var_trap.val.objid = demo_trap; /* demo-trap objid */
710 var_trap.val_len = sizeof(demo_trap); /* length in bytes (not number of subids!) */
711
712
713 /*
714 * additional objects
715 */
716
717
718 var_obj.next_variable = NULL; /* No more variables after this one */
719 var_obj.name = example_string_oid;
720 var_obj.name_length = sizeof(example_string_oid) / sizeof(oid); /* number of sub-ids */
721 var_obj.type = ASN_OCTET_STR; /* type of variable */
722 var_obj.val.string = (u_char *)example_str; /* value */
723 var_obj.val_len = strlen(example_str);
724 DEBUGMSGTL(("example", "write_exampletrap2 sending the v2 trap\n"));
725 send_v2trap(&var_trap);
726 DEBUGMSGTL(("example", "write_exampletrap2 v2 trap sent\n"));
727
728 break;
729
730 }
731 return SNMP_ERR_NOERROR;
732 }