From 0275eedb63a10317fe1a50b510cbb91f02b16799 Mon Sep 17 00:00:00 2001 From: Aaron Taylor Date: Sat, 5 Oct 2019 04:36:33 -0700 Subject: [PATCH] Complete rewrite of README. --- README.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 76 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 4bce2f5..dc0007a 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,77 @@ -It was reported to compile and work on following platfoms: - -BSDi 2.1 -BSDi 3.1 -FreeBSD 3.3-RC -Solaris 2.7 sparc -Solaris 2.6 sparc -Solaris 2.6 x86 -Solaris 2.5.1 sparc with GNU C 2.8.1 -RedHat Linux 6.0-9 -Slackware 6.0 (beta) -Slackware 4.0 -MacOS 10.3.4 +# Overview # +ICMPmonitor pings a set of hosts, executing per-host, user-defined commands +whenever a host begins or ceases to respond. + +Assuming your build environment is suitable, build and execute the example +configuration with the following commands. + + % make clean && make + % sudo ./icmpmonitor -f ./icmpmonitor.ini -v + + +# Status # + +Complete. Tested on FreeBSD and Debian Linux. + + +# Instructions # + +After editing the `Makefile` to suit your environment, build ICMPmonitor with +`make clean && make`. Copy the resulting `icmpmonitor` binary somewhere +suitable and create a configuration file based on the examples in +`icmpmonitor.ini`. + +Execute ICMPmonitor as shown below, adding any additional flags desired. Note +that ICMPmonitor requires permission to send and receive network packets. + + % sudo icmpmonitor -f /path/to/config/file.ini + + +# Reference: Command Line Flags # + + -f Required. Pathname of configuration file. + + -v Enable verbose mode, printing a message for each packet + sent/received as well as each host up/down event. + + -r Repeat `down_cmd` every time a downed host fails to respond to + a ping. This contrasts with the default behavior which executes + `down_cmd` only once per downed host event, requiring a ping + response to complete the event before `down_cmd` can repeat. + + -h Prints simple help information and exits. + + +# Reference: Configuration File Format # + +Each host to be monitored should have a corresponding `host entry` in the +configuration file. This entry consists of a label in square brackets and a +series of mandatory configuration options. Comments may be included and are +demarked with pound signs. For example: + + [Example entry for localhost] + host = 127.0.0.1 + interval = 2 + max_delay = 30 + up_cmd = "echo host up" # This is a comment. + down_cmd = "echo host down" + start_condition = down + +The `host` option references the host to be monitored and can be either an IP +address or fully-qualified hostname. + +The `interval` specifies the number of seconds between pings. Values smaller +than TIMER_RESOLUTION as `#defined`ed in `icmpmonitor.c` will result in a ping +sent roughly once every `TIMER_RESOLUTION` seconds. + +Hosts will only be marked down after missing all pings sent in the last +`max_delay` seconds. + +After a host misses all pings sent in the last `max_delay` seconds, the +`down_cmd` is executed. Upon receipt of a response from the host, the `up_cmd` +is executed and all counters are reset. + +The initial state ICMPmonitor should assume is specified by `start_condition`. +This can be important if the external commands executed for up/down events have +significant consequences. Allowed values are `up` or `down`. -- 2.20.1