README
¶
pingreporter
A CLI tool that pings a target host and optionally reports the results to an HTTP endpoint. Useful for uptime monitoring integrations where you need to report connectivity status from a specific network location. Created to report data to Uptime Kuma.
Installation
From source
go install codeberg.org/backplane/pingreporter@latest
Pre-built binaries
Download from the releases page.
Docker
docker pull backplane/pingreporter
Usage
pingreporter --target <host> [options]
Options
| Flag | Environment Variable | Default | Description |
|---|---|---|---|
--target |
TARGET_ADDR |
(required) | Hostname or IP address to ping |
--endpoint |
ENDPOINT_URL |
URL to report results to | |
--count |
PING_COUNT |
3 | Number of ping probes to send |
--icmp |
ICMP_MODE |
false | Use ICMP pings instead of unprivileged UDP pings |
--loglevel |
INFO | Log verbosity: DEBUG, INFO, WARN, ERROR |
By default, pingreporter uses unprivileged UDP pings which work without elevated permissions. Use --icmp to send traditional ICMP echo requests, which requires either root privileges or the cap_net_raw capability on Linux:
sudo setcap cap_net_raw=+ep /path/to/pingreporter
Examples
Ping a host and print results:
pingreporter --target example.com
Ping and report to a monitoring endpoint:
pingreporter --target 192.168.1.1 --endpoint https://monitor.example.com/ping
Using environment variables (useful for containers/cron):
export TARGET_ADDR=example.com
export ENDPOINT_URL=https://monitor.example.com/ping
pingreporter --loglevel WARN
Endpoint Integration
When --endpoint is specified, pingreporter makes a GET request with these query parameters:
| Parameter | Description |
|---|---|
status |
up if any packets received, down otherwise |
msg |
Statistics string with packet loss and RTT metrics |
ping |
Average round-trip time in milliseconds |
The endpoint must return a 2xx status code and a JSON response containing "ok":true.
Example request:
GET https://monitor.example.com/ping?status=up&msg=pkts_sent%3D3%3B+pkts_received%3D3%3B+...&ping=12.5
License
LGPL-2.1 - See LICENSE.txt for details.
Documentation
Source Files