monitor-ip

Robust, efficient, hook-driven internet and remote IP monitoring using ICMP echo-request/reply.

Description:

IP address monitoring for GNU/Linux written in C. It allows specifying a remote address (IPv4 or IPv6) to monitor with ICMP echos. monitor-ip can be given a configurable ping interval, reply timeout, and maximum number of missed pings. Whenever the number of consecutive missed (lost or expired) pings exceeds the configured value, monitor-ip will run the supplied command.

Writing notify command scripts:

monitor-ip will run the configured hook command with any provided arguments using the exec family of functions (see exec(3)). This means it will not interpret the provided command as a shell command. It will search the PATH if needed.

monitor-ip will export the following environment variables to the hook command:

• MONITOR_NOTIFY_MISSED_PING_COUNT: a decimal integer representation of the current number of consecutively missed pings.
• MONITOR_NOTIFY_REMOTE_ADDRESS: the configured remote IP address (IPv4 or IPv6) as formatted by inet_ntop(3).

Treat any other environment variables prefixed by MONITOR_NOTIFY_ as reserved for future releases of monitor-ip.

Building and installing:

• Ensure a recent version of glibc, glib-2.0, and pkgconf are installed.
• Run make or make debug to generate a binary with debugging symbols. The resulting executable will be named monitor-ip
• There is no install make target. Simply copy the executable to wherever you need it: it has not dependant files as part of this build.

Gotchas:

• monitor-ip DOES NOT attempt to resolve DNS names, please provide an plain IP address. If you need to extend it to support DNS names, I recommend you attempt to script a solution using dig(1) or host(1).
• By default, monitor-ip attempts to parse the provided address as an IPv4 address. To use IPv6, add the -6 flag.
• Yes, you do need to run as root (use sudo). You can also use setcap to give the executable cap_net_raw, which is why you can use the ping command as a non-root user.
• By default, monitor-ip will block the main loop until the hook command exits. As a result, it must also clear the list of echos waiting for a reply. It will not however reset the count of consecutively missed pings by default, which means if the status condition remains, it will execute the hook command again after just one interval. Both of these behaviors are configurable.

Help:

USAGE: monitor-ip [OPTIONS] <address> [<hook command> [<arg> [...]]

Send pings (echo requests) to <address>, excessive missed pongs (echo response)
results in <hook command> being run with provided arguments, if it is set.

OPTIONS:
    -h --help                   Print this message.
    -v --verbose                Be verbose (may be specified multiple times).
    -q --quiet                  Be less verbose (may be specified multiple times).
    -4 --ipv4                   Interpret <address> as an IPv4 address.
                                (default)
    -6 --ipv6                   Interpret <address> as an IPv6 address.
    -t --ttl <ttl>              Use <ttl> as IP(v6) TTL/Hop-Limit. (default: 64)
    -s --message-size <size>    Use <size> as ICMP message data size.
                                (default: 56)
    -i --interval <interval>    Use <interval> (may be decimal) as ping
                                interval in seconds. (default: 1.0)
    -W --expiration <expire>    Use <expire> (may be decimal) as ping expiration
                                time in seconds. (default: 1.99)
    -m --missed-max <missed>    Use <missed> as number of missed pongs
                                exceeding which triggers the <hook command>.
                                (default: 10)
    -b --notify-block           Block until <hook command> exits. (default)
    -B --no-notify-block        Don't block until <hook command> exits. May
                                result in multiple <hook command>s executing
                                simultaneously.
    -r --reset                  Reset missed ping count after successful run of
                                notify command. Only valid with --notify-block.

Contributors:

A special thanks to:

• Isabelle Erin Cowan-Bergman <izzi(åt)izzette(dòt)com> (main author) and her coworkers at Bodhi Digital for supporting this and other endeavors.

Usage and licensing:

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.

In jurisdictions that recognize copyright laws, the author or authors
of this software dedicate any and all copyright interest in the
software to the public domain. We make this dedication for the benefit
of the public at large and to the detriment of our heirs and
successors. We intend this dedication to be an overt act of
relinquishment in perpetuity of all present and future rights to this
software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to <http://unlicense.org>