{"id":17066242,"url":"https://github.com/ignlg/pingkeeper","last_synced_at":"2025-08-22T12:15:43.605Z","repository":{"id":48789593,"uuid":"255384019","full_name":"ignlg/pingkeeper","owner":"ignlg","description":"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 \u0026 run) if checking fails.","archived":false,"fork":false,"pushed_at":"2024-12-28T10:25:24.000Z","size":215,"stargazers_count":10,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T13:05:32.007Z","etag":null,"topics":["daemon","launch-daemon","launcher","linux","macos","monitoring","network","openvpn","ping","shell","unix","unix-command","unix-shell","vpn"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ignlg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-04-13T16:37:26.000Z","updated_at":"2025-01-15T04:02:29.000Z","dependencies_parsed_at":"2022-09-01T00:51:02.007Z","dependency_job_id":"af7f707f-0ab4-449c-9d04-07149edff0fb","html_url":"https://github.com/ignlg/pingkeeper","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ignlg%2Fpingkeeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ignlg%2Fpingkeeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ignlg%2Fpingkeeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ignlg%2Fpingkeeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ignlg","download_url":"https://codeload.github.com/ignlg/pingkeeper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248618222,"owners_count":21134199,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["daemon","launch-daemon","launcher","linux","macos","monitoring","network","openvpn","ping","shell","unix","unix-command","unix-shell","vpn"],"created_at":"2024-10-14T11:06:24.949Z","updated_at":"2025-04-12T18:50:38.835Z","avatar_url":"https://github.com/ignlg.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pingkeeper\n\n[![Crate][crate-image]][crate-link]\n[![GPLv3 license][license-image]][license-link]\n![MSRV][rustc-image]\n[![Safety Dance][safety-image]][safety-link]\n[![Build Status][build-image]][build-link]\n[![Release Date][releases-image]][releases-link]\n![Stability stable][stability-image]\n\nCommand 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 \u0026 run) if _check command_ fails.\n\nPrimarily 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.**\n\nProudly made from Barcelona with Rust 🦀.\n\n## How does it work?\n\n![Flow Chart][flowchart-image]\n\n## Installation\n\nThree options:\n\n### Cargo \u0026 Go\n\n1.  If you already have `cargo` installed, use:\n\n        cargo install pingkeeper\n\n### Manual download\n\n1.  Download release binaries from [releases page][releases-link].\n\n1.  Check the integrity of the downloaded file _(version may differ)_:\n\n        sha512sum --check pingkeeper-macos-v3.2.0.tar.gz.sha512\n\n    It should say: `pingkeeper-macos-v3.2.0.tar.gz: OK`\n\n1.  Extract archive _(version may differ)_ with:\n\n        tar xvf pingkeeper-macos-v3.2.0.tar.gz\n\n1.  Check the integrity of the binary file with:\n\n        sha512sum --check pingkeeper.sha512\n\n    It should say: `pingkeeper: OK`\n\n1.  Copy `pingkeeper` binary file to somewhere within your `$PATH`, ie: `/usr/local/bin`.\n\n### Build it yourself\n\nThis requires the stable version of `rust` \u0026 `cargo` installed. Visit [Rust website][rust-link] for more information.\n\n1.  Run this command:\n\n        cargo build --release\n\n2.  You will find your executable at `./target/release/pingkeeper`.\n\n## Usage\n\n### Usage examples\n\n- Keep your vpn connection alive using OpenVPN:\n\n  ```shell\n  sudo pingkeeper -k \"openvpn /home/user/vpn_configuration.ovpn\"\n  ```\n\n- Keep your vpn connection alive using [Hummingbird][hummingbird-link] without any logging:\n\n  ```shell\n  sudo pingkeeper --keep-alive --quiet \"hummingbird denmark.ovpn\"\n  ```\n\n- Send an email to your boss when your network is down, using ping as test:\n\n  ```shell\n  pingkeeper --use-ping \"mail -s \\\"Sorry, my network is down. I will be right back asap.\\\" myboss@example.com \u003c /dev/null\"\n  ```\n\n- Send yourself a [pushbullet-cli][pushbullet-cli-link] message when your home server seems down, using ping as test:\n\n  ```shell\n  pingkeeper --hosts \"192.168.1.50\" --use-ping \"pb push \\\"Is home server down?\\\"\"\n  ```\n\n- Tweet when your [opentracker][opentracker-link] bittorrent tracker server seems down, using [t][t-link]:\n\n  ```shell\n  pingkeeper --hosts \"10.1.1.28:6969\" \"t update \\\"Dear users, the tracker is currently down :(\\\"\"\n  ```\n\n- Run your own script when the damn wifi seems down again:\n\n  ```shell\n  pingkeeper \"/home/user/try_reset_router.sh\"\n  ```\n\n- Shutdown server when the canary file is missing:\n\n  ```shell\n  sudo pingkeeper --check-cmd \"cat /root/canary.txt\" --kill-cmd \"echo\" \"shutdown -h now\"\n  ```\n\n### Usage manual\n\nHelp available running `pingkeeper --help`:\n\n```\n\nUSAGE:\n    pingkeeper [FLAGS] [OPTIONS] \u003cCOMMAND\u003e\n\nFLAGS:\n    -h, --help\n            Prints help information\n\n    -k, --keep-alive\n            Keep \u003cCOMMAND\u003e alive.\n\n            Run \u003cCOMMAND\u003e on start, also restart it when it dies.\n    -q, --quiet\n            Do not output anything from \u003cCOMMAND\u003e output, also reduces `-v` by one\n\n    -P, --use-ping\n            Use `ping` to check connection.\n\n            Use system's `ping` command to check network connection.\n    -V, --version\n            Prints version information\n\n    -v\n            Verbosity, -v -vv -vvv.\n\n            Log levels: 0 = error, 1 = warning, 2 = info, 3 = debug.\n\nOPTIONS:\n        --check-cmd \u003ccheck-cmd\u003e\n            Use custom command to check\n\n            Check network or something else. This will trigger the execution / kill flow as if it was a network check.\n            Example: --check-cmd \"cat canary.txt\"\n    -H, --hosts \u003chosts\u003e\n            Space separated list of addresses or hosts (ping).\n\n            For direct connection: List of IPv4 and IPv6, with or without port.\n\n            For ping: List of hosts.\n\n            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]\n        --kill-cmd \u003ckill-cmd\u003e\n            Use custom command to kill\n\n            Example: --kill-cmd \"echo \\\"My baby shot me down\\\" \u003e\u003e bang_bang.log\"\n    -m, --max-errors \u003cmax-errors\u003e\n            Maximum number of \u003cCOMMAND\u003e errors in a row.\n\n            0 for infinite. Only used by `--keep-alive`. [default: 0]\n    -n, --network-every \u003cn\u003e\n            Network check delay, in seconds.\n\n            Check network again after this amount of seconds from the latest success. [default: 5]\n        --ping-opt \u003copts\u003e\n            Options for `ping` command, requires `--use-ping` [default: -c1]\n\n    -p, --port \u003cport\u003e\n            Default port to connect, ignored if `--use-ping`.\n\n            Port to connect if host does not have a port specified. [default: 53]\n    -w, --wait-after-exec \u003cseconds\u003e\n            Execution delay, in seconds.\n\n            Seconds to check network for the first time after executing \u003cCOMMAND\u003e. [default: 5]\n    -s, --signal \u003csignal\u003e\n            Signal to kill \u003cCOMMAND\u003e.\n\n            Could be any unix signal: `SIGINT`, `SIGTERM`, etc. [default: SIGINT]\n    -t, --timeout \u003ctimeout\u003e\n            Timeout in seconds, ignored if `--use-ping` [default: 2]\n\n\nARGS:\n    \u003cCOMMAND\u003e\n            Command to run\n\n```\n\n## Changelog\n\n### v3.2.0\n\n- [x] opt `--kill-cmd`, custom kill command.\n- [x] opt `--check-cmd`, custom check command.\n- [x] add tests.\n- [x] improve documentation.\n\n### v3.1.1\n\n- [x] fix error with option `-v`.\n\n### v3.1.0\n\n- [x] support addresses with port in `--hosts`.\n- [x] support IPv4 and IPv6 addresses.\n- [x] improve documentation.\n- [x] improve tests.\n\n### v3.0.2\n\n- [x] improve documentation.\n- [x] improve tests.\n- [x] add usage examples to docs.\n\n### v3.0.1\n\n- [x] improve documentation.\n\n### v3.0.0\n\n- [x] detect network connection directly.\n- [x] opt `--use-ping`, use system ping instead of direct connection.\n- [x] opt `-t --timeout`, seconds waiting for network connection.\n- [x] opt `--max-errors`, number of keep-alive errors allowed in a row to keep running.\n- [x] improve documentation.\n\n### v2.0.0\n\n- [x] rename opt ~~`--boot-time`~~ -\u003e `--wait-after-exec`.\n- [x] reanme opt ~~`--check-time`~~ -\u003e `--ping-every`.\n- [x] opt `--signal`; default: `\"SIGINT\"`.\n- [x] flow chart.\n- [x] move logic to subfiles.\n- [x] tests.\n\n### v1.0.0\n\n- [x] launch command when ping fails.\n- [x] opt `--hosts`; default: `\"8.8.8.8 8.8.6.6 1.1.1.1 1.0.0.1\"`.\n- [x] detect if network is reachable.\n- [x] opt `--ping-opt`, ping options; default: `\"-c1\"`.\n- [x] opt `--boot-time`, seconds wait to check network after command; default: `5`.\n- [x] opt `--check-time`, network check delay in seconds; default: `5`.\n- [x] restart (send SIGINT signal) on network error.\n- [x] opt `--keep-alive`, run command on init and restart on command exit.\n- [x] opt `-v --verbose`, show log.\n- [x] opt `-q --quiet`, hide stdout/stderr from subcommand.\n\n## Backlog\n\n- [ ] wait for child after kill, then SIGTERM.\n- [ ] improve generated docs.\n- [ ] export lib too.\n- [ ] integration tests: mocks.\n- [ ] integration tests: commandline.\n- [ ] website.\n- [ ] LaunchDaemon generator.\n- [ ] macOS notifications: connection lost, connection recovered.\n- [ ] opt `--disable-notifications`.\n- [ ] detect SIGTERM on subprocess and stop.\n- [ ] write pid to proc.\n- [ ] opt `-f --force` to kill pid and remove pid from proc.\n- [ ] check if interface is up.\n- [ ] write logs to `/var/log`.\n\n## License\n\nPingkeeper\nCopyright (C) 2020 Ignacio Lago\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program. If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n\n[//]: # \"assets\"\n[flowchart-image]: assets/Pingkeeper-flowchart.png\n[//]: # \"badges\"\n[crate-image]: https://img.shields.io/crates/v/pingkeeper\n[downloads-image]: https://img.shields.io/crates/d/pingkeeper\n[crate-link]: https://crates.io/crates/pingkeeper\n[license-image]: https://img.shields.io/crates/l/pingkeeper\n[license-link]: https://github.com/ignlg/pingkeeper/blob/next/LICENSE\n[rustc-image]: https://img.shields.io/badge/rustc-1.36+-blue.svg\n[safety-image]: https://img.shields.io/badge/unsafe-forbidden-success\n[safety-link]: https://github.com/rust-secure-code/safety-dance/\n[build-image]: https://travis-ci.org/ignlg/pingkeeper.svg?branch=master\n[build-link]: https://travis-ci.org/ignlg/pingkeeper\n[releases-image]: https://img.shields.io/github/release-date/ignlg/pingkeeper\n[releases-link]: https://github.com/ignlg/pingkeeper/releases\n[stability-image]: https://img.shields.io/badge/stability-stable-blue\n[librariesio-image]: https://img.shields.io/librariesio/release/ignlg/pingkeeper\n[librariesio-link]: https://libraries.io/github/ignlg/pingkeeper\n[//]: # \"links\"\n[rust-link]: https://www.rust-lang.org/\n[hummingbird-link]: https://gitlab.com/AirVPN/hummingbird\n[pushbullet-cli-link]: https://github.com/GustavoKatel/pushbullet-cli\n[opentracker-link]: https://erdgeist.org/arts/software/opentracker/\n[t-link]: https://github.com/sferik/t\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fignlg%2Fpingkeeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fignlg%2Fpingkeeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fignlg%2Fpingkeeper/lists"}