| 1 | # Overview # |
| 2 | |
| 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`. |