pingkeeper

Command line application that monitorizes the exit status of a check command and, in case of failure, runs another main command. Optionally it can monitor that the provided main command is permanently running, triggering a restart (kill & run) if check command fails.

Primarily intended for checking if network is reachable (direct tcp connection or ping), current releases can do much more with the addition of custom check and kill commands.

Proudly made from Barcelona with Rust 🦀.

How does it work?

Installation

Three options:

Cargo & Go

1. If you already have cargo installed, use:

   cargo install pingkeeper
   

Manual download

1. Download release binaries from releases page.

2. Check the integrity of the downloaded file (version may differ):

   sha512sum --check pingkeeper-macos-v3.2.0.tar.gz.sha512
   

   It should say: pingkeeper-macos-v3.2.0.tar.gz: OK

3. Extract archive (version may differ) with:

   tar xvf pingkeeper-macos-v3.2.0.tar.gz
   

4. Check the integrity of the binary file with:

   sha512sum --check pingkeeper.sha512
   

   It should say: pingkeeper: OK

5. Copy pingkeeper binary file to somewhere within your $PATH, ie: /usr/local/bin.

Build it yourself

This requires the stable version of rust & cargo installed. Visit Rust website for more information.

1. Run this command:

   cargo build --release
   

2. You will find your executable at ./target/release/pingkeeper.

Usage

Usage examples

• Keep your vpn connection alive using OpenVPN:

  sudo pingkeeper -k "openvpn /home/user/vpn_configuration.ovpn"
  

• Keep your vpn connection alive using Hummingbird without any logging:

  sudo pingkeeper --keep-alive --quiet "hummingbird denmark.ovpn"
  

• Send an email to your boss when your network is down, using ping as test:

  pingkeeper --use-ping "mail -s \"Sorry, my network is down. I will be right back asap.\" myboss@example.com < /dev/null"
  

• Send yourself a pushbullet-cli message when your home server seems down, using ping as test:

  pingkeeper --hosts "192.168.1.50" --use-ping "pb push \"Is home server down?\""
  

• Tweet when your opentracker bittorrent tracker server seems down, using t:

  pingkeeper --hosts "10.1.1.28:6969" "t update \"Dear users, the tracker is currently down :(\""
  

• Run your own script when the damn wifi seems down again:

  pingkeeper "/home/user/try_reset_router.sh"
  

• Shutdown server when the canary file is missing:

  sudo pingkeeper --check-cmd "cat /root/canary.txt" --kill-cmd "echo" "shutdown -h now"
  

Usage manual

Help available running pingkeeper --help:

USAGE:
    pingkeeper [FLAGS] [OPTIONS] <COMMAND>

FLAGS:
    -h, --help
            Prints help information

    -k, --keep-alive
            Keep <COMMAND> alive.

            Run <COMMAND> on start, also restart it when it dies.
    -q, --quiet
            Do not output anything from <COMMAND> output, also reduces `-v` by one

    -P, --use-ping
            Use `ping` to check connection.

            Use system's `ping` command to check network connection.
    -V, --version
            Prints version information

    -v
            Verbosity, -v -vv -vvv.

            Log levels: 0 = error, 1 = warning, 2 = info, 3 = debug.

OPTIONS:
        --check-cmd <check-cmd>
            Use custom command to check

            Check network or something else. This will trigger the execution / kill flow as if it was a network check.
            Example: --check-cmd "cat canary.txt"
    -H, --hosts <hosts>
            Space separated list of addresses or hosts (ping).

            For direct connection: List of IPv4 and IPv6, with or without port.

            For ping: List of hosts.

            Order does not matter, list will be shuffled. [default: 8.8.8.8 8.8.6.6 1.1.1.1 1.0.0.1]
        --kill-cmd <kill-cmd>
            Use custom command to kill

            Example: --kill-cmd "echo \"My baby shot me down\" >> bang_bang.log"
    -m, --max-errors <max-errors>
            Maximum number of <COMMAND> errors in a row.

            0 for infinite. Only used by `--keep-alive`. [default: 0]
    -n, --network-every <n>
            Network check delay, in seconds.

            Check network again after this amount of seconds from the latest success. [default: 5]
        --ping-opt <opts>
            Options for `ping` command, requires `--use-ping` [default: -c1]

    -p, --port <port>
            Default port to connect, ignored if `--use-ping`.

            Port to connect if host does not have a port specified. [default: 53]
    -w, --wait-after-exec <seconds>
            Execution delay, in seconds.

            Seconds to check network for the first time after executing <COMMAND>. [default: 5]
    -s, --signal <signal>
            Signal to kill <COMMAND>.

            Could be any unix signal: `SIGINT`, `SIGTERM`, etc. [default: SIGINT]
    -t, --timeout <timeout>
            Timeout in seconds, ignored if `--use-ping` [default: 2]


ARGS:
    <COMMAND>
            Command to run

Changelog

v3.2.0

• opt --kill-cmd, custom kill command.
• opt --check-cmd, custom check command.
• add tests.
• improve documentation.

v3.1.1

• fix error with option -v.

v3.1.0

• support addresses with port in --hosts.
• support IPv4 and IPv6 addresses.
• improve documentation.
• improve tests.

v3.0.2

• improve documentation.
• improve tests.
• add usage examples to docs.

v3.0.1

• improve documentation.

v3.0.0

• detect network connection directly.
• opt --use-ping, use system ping instead of direct connection.
• opt -t --timeout, seconds waiting for network connection.
• opt --max-errors, number of keep-alive errors allowed in a row to keep running.
• improve documentation.

v2.0.0

• rename opt --boot-time -> --wait-after-exec.
• reanme opt --check-time -> --ping-every.
• opt --signal; default: "SIGINT".
• flow chart.
• move logic to subfiles.
• tests.

v1.0.0

• launch command when ping fails.
• opt --hosts; default: "8.8.8.8 8.8.6.6 1.1.1.1 1.0.0.1".
• detect if network is reachable.
• opt --ping-opt, ping options; default: "-c1".
• opt --boot-time, seconds wait to check network after command; default: 5.
• opt --check-time, network check delay in seconds; default: 5.
• restart (send SIGINT signal) on network error.
• opt --keep-alive, run command on init and restart on command exit.
• opt -v --verbose, show log.
• opt -q --quiet, hide stdout/stderr from subcommand.

Backlog

• wait for child after kill, then SIGTERM.
• improve generated docs.
• export lib too.
• integration tests: mocks.
• integration tests: commandline.
• website.
• LaunchDaemon generator.
• macOS notifications: connection lost, connection recovered.
• opt --disable-notifications.
• detect SIGTERM on subprocess and stop.
• write pid to proc.
• opt -f --force to kill pid and remove pid from proc.
• check if interface is up.
• write logs to /var/log.

License

Pingkeeper Copyright (C) 2020 Ignacio Lago

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.