Commit | Line | Data |
---|---|---|
0275eedb | 1 | # Overview # |
c5de9e27 | 2 | |
0275eedb AT |
3 | ICMPmonitor pings a set of hosts, executing per-host, user-defined commands |
4 | whenever a host begins or ceases to respond. | |
5 | ||
6 | Assuming your build environment is suitable, build and execute the example | |
7 | configuration with the following commands. | |
8 | ||
9 | % make clean && make | |
10 | % sudo ./icmpmonitor -f ./icmpmonitor.ini -v | |
11 | ||
12 | ||
13 | # Status # | |
14 | ||
15 | Complete. Tested on FreeBSD and Debian Linux. | |
16 | ||
17 | ||
18 | # Instructions # | |
19 | ||
20 | After editing the `Makefile` to suit your environment, build ICMPmonitor with | |
21 | `make clean && make`. Copy the resulting `icmpmonitor` binary somewhere | |
22 | suitable and create a configuration file based on the examples in | |
23 | `icmpmonitor.ini`. | |
24 | ||
25 | Execute ICMPmonitor as shown below, adding any additional flags desired. Note | |
26 | that ICMPmonitor requires permission to send and receive network packets. | |
27 | ||
28 | % sudo icmpmonitor -f /path/to/config/file.ini | |
29 | ||
30 | ||
31 | # Reference: Command Line Flags # | |
32 | ||
33 | -f <file> Required. Pathname of configuration file. | |
34 | ||
35 | -v Enable verbose mode, printing a message for each packet | |
36 | sent/received as well as each host up/down event. | |
37 | ||
38 | -r Repeat `down_cmd` every time a downed host fails to respond to | |
39 | a ping. This contrasts with the default behavior which executes | |
40 | `down_cmd` only once per downed host event, requiring a ping | |
41 | response to complete the event before `down_cmd` can repeat. | |
42 | ||
43 | -h Prints simple help information and exits. | |
44 | ||
45 | ||
46 | # Reference: Configuration File Format # | |
47 | ||
48 | Each host to be monitored should have a corresponding `host entry` in the | |
49 | configuration file. This entry consists of a label in square brackets and a | |
50 | series of mandatory configuration options. Comments may be included and are | |
51 | demarked with pound signs. For example: | |
52 | ||
53 | [Example entry for localhost] | |
54 | host = 127.0.0.1 | |
55 | interval = 2 | |
56 | max_delay = 30 | |
57 | up_cmd = "echo host up" # This is a comment. | |
58 | down_cmd = "echo host down" | |
59 | start_condition = down | |
60 | ||
61 | The `host` option references the host to be monitored and can be either an IP | |
62 | address or fully-qualified hostname. | |
63 | ||
64 | The `interval` specifies the number of seconds between pings. Values smaller | |
65 | than TIMER_RESOLUTION as `#defined`ed in `icmpmonitor.c` will result in a ping | |
66 | sent roughly once every `TIMER_RESOLUTION` seconds. | |
67 | ||
68 | Hosts will only be marked down after missing all pings sent in the last | |
69 | `max_delay` seconds. | |
70 | ||
71 | After a host misses all pings sent in the last `max_delay` seconds, the | |
72 | `down_cmd` is executed. Upon receipt of a response from the host, the `up_cmd` | |
73 | is executed and all counters are reset. | |
74 | ||
75 | The initial state ICMPmonitor should assume is specified by `start_condition`. | |
76 | This can be important if the external commands executed for up/down events have | |
77 | significant consequences. Allowed values are `up` or `down`. |