pingkeeper

Command line application that monitorizes that network is reachable (direct tcp connection or ping) and, in case of failure, runs a command. Optionally it can monitor that the command is permanently running and restart it if network is unreachable.

Proudly made from Barcelona with Rust 🦀.

How does it work?

Flow Chart

Installation

Three options:

Cargo & Go

If you already have cargo installed, use:
```
cargo install pingkeeper
```

Manual download

Download release binaries from releases page.
Check the integrity of the downloaded file (version may differ):
```
sha512sum --check pingkeeper-macos-v3.0.0.tar.gz.sha512
```
It should say: pingkeeper-macos-v3.0.0.tar.gz: OK
Extract archive (version may differ) with:
```
tar xvf pingkeeper-macos-v3.0.0.tar.gz
```
Check the integrity of the binary file with:
```
sha512sum --check pingkeeper.sha512
```
It should say: pingkeeper: OK
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.

Run this command:
```
cargo build --release
```
You will find your executable at ./target/release/pingkeeper.

Usage

Usage examples

Keep your vpn connection alive using OpenVPN:

shell sudo pingkeeper -k "openvpn /home/user/vpn_configuration.ovpn"
Keep your vpn connection alive using Hummingbird without any logging:

shell sudo pingkeeper --keep-alive --quiet "hummingbird denmark.ovpn"
Send an email to your boss when your network is down, using ping as test:

shell 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:

shell 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:

shell 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:

shell pingkeeper "/home/user/try_reset_router.sh"

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


    OPTIONS:
    -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]
    -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]

    -v <verbose>...
            Verbosity, -v -vv -vvv.

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

    ARGS:
    <COMMAND>
            Command to run

Changelog

v3.1.0

[x] support addresses with port in --hosts.
[x] support IPv4 and IPv6 addresses.
[x] improve documentation.
[x] improve tests.

v3.0.2

[x] improve documentation.
[x] improve tests.
[x] add usage examples to docs.

v3.0.1

[x] improve documentation.

v3.0.0

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

v2.0.0

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

v1.0.0

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

Backlog

[ ] improve generated docs.
[ ] export lib too.
[ ] pingkeeper tests with mocks.
[ ] opt --kill-cmd, custom kill command.
[ ] opt --check-cmd, custom check network command.
[ ] 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

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/.