Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ignlg/pingkeeper
Command line application that monitorizes the exit status of a check (command or ping or network response) and, in case of failure, runs a command. Optionally it can monitor that the provided command is permanently running, triggering a restart (kill & run) if checking fails.
https://github.com/ignlg/pingkeeper
daemon launch-daemon launcher linux macos monitoring network openvpn ping shell unix unix-command unix-shell vpn
Last synced: 4 months ago
JSON representation
Command line application that monitorizes the exit status of a check (command or ping or network response) and, in case of failure, runs a command. Optionally it can monitor that the provided command is permanently running, triggering a restart (kill & run) if checking fails.
- Host: GitHub
- URL: https://github.com/ignlg/pingkeeper
- Owner: ignlg
- License: gpl-3.0
- Created: 2020-04-13T16:37:26.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2021-09-02T16:48:34.000Z (over 3 years ago)
- Last Synced: 2024-09-14T03:29:53.002Z (5 months ago)
- Topics: daemon, launch-daemon, launcher, linux, macos, monitoring, network, openvpn, ping, shell, unix, unix-command, unix-shell, vpn
- Language: Rust
- Homepage:
- Size: 209 KB
- Stars: 9
- Watchers: 2
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pingkeeper
[![Crate][crate-image]][crate-link]
[![GPLv3 license][license-image]][license-link]
![MSRV][rustc-image]
[![Safety Dance][safety-image]][safety-link]
[![Build Status][build-image]][build-link]
[![Release Date][releases-image]][releases-link]
![Stability stable][stability-image]
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?
![Flow Chart][flowchart-image]
## 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][releases-link].
1. 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`
1. Extract archive _(version may differ)_ with:
tar xvf pingkeeper-macos-v3.2.0.tar.gz
1. Check the integrity of the binary file with:
sha512sum --check pingkeeper.sha512
It should say: `pingkeeper: OK`
1. 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][rust-link] 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:
```shell
sudo pingkeeper -k "openvpn /home/user/vpn_configuration.ovpn"
```
- Keep your vpn connection alive using [Hummingbird][hummingbird-link] 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.\" [email protected] < /dev/null"
```
- Send yourself a [pushbullet-cli][pushbullet-cli-link] 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][opentracker-link] bittorrent tracker server seems down, using [t][t-link]:
```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"
```
- Shutdown server when the canary file is missing:
```shell
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]
FLAGS:
-h, --help
Prints help information
-k, --keep-alive
Keep alive.
Run on start, also restart it when it dies.
-q, --quiet
Do not output anything from 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
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
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
Use custom command to kill
Example: --kill-cmd "echo \"My baby shot me down\" >> bang_bang.log"
-m, --max-errors
Maximum number of errors in a row.
0 for infinite. Only used by `--keep-alive`. [default: 0]
-n, --network-every
Network check delay, in seconds.
Check network again after this amount of seconds from the latest success. [default: 5]
--ping-opt
Options for `ping` command, requires `--use-ping` [default: -c1]
-p, --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
Execution delay, in seconds.
Seconds to check network for the first time after executing . [default: 5]
-s, --signal
Signal to kill .
Could be any unix signal: `SIGINT`, `SIGTERM`, etc. [default: SIGINT]
-t, --timeout
Timeout in seconds, ignored if `--use-ping` [default: 2]
ARGS:
Command to run
```
## Changelog
### v3.2.0
- [x] opt `--kill-cmd`, custom kill command.
- [x] opt `--check-cmd`, custom check command.
- [x] add tests.
- [x] improve documentation.
### v3.1.1
- [x] fix error with option `-v`.
### 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
- [ ] 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 .
[//]: # "assets"
[flowchart-image]: assets/Pingkeeper-flowchart.png
[//]: # "badges"
[crate-image]: https://img.shields.io/crates/v/pingkeeper
[downloads-image]: https://img.shields.io/crates/d/pingkeeper
[crate-link]: https://crates.io/crates/pingkeeper
[license-image]: https://img.shields.io/crates/l/pingkeeper
[license-link]: https://github.com/ignlg/pingkeeper/blob/next/LICENSE
[rustc-image]: https://img.shields.io/badge/rustc-1.36+-blue.svg
[safety-image]: https://img.shields.io/badge/unsafe-forbidden-success
[safety-link]: https://github.com/rust-secure-code/safety-dance/
[build-image]: https://travis-ci.org/ignlg/pingkeeper.svg?branch=master
[build-link]: https://travis-ci.org/ignlg/pingkeeper
[releases-image]: https://img.shields.io/github/release-date/ignlg/pingkeeper
[releases-link]: https://github.com/ignlg/pingkeeper/releases
[stability-image]: https://img.shields.io/badge/stability-stable-blue
[librariesio-image]: https://img.shields.io/librariesio/release/ignlg/pingkeeper
[librariesio-link]: https://libraries.io/github/ignlg/pingkeeper
[//]: # "links"
[rust-link]: https://www.rust-lang.org/
[hummingbird-link]: https://gitlab.com/AirVPN/hummingbird
[pushbullet-cli-link]: https://github.com/GustavoKatel/pushbullet-cli
[opentracker-link]: https://erdgeist.org/arts/software/opentracker/
[t-link]: https://github.com/sferik/t