90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
# Uptime Kuma Push Client
|
||
|
||
`kuma-push.sh` sends heartbeat updates to your Uptime Kuma instance by iterating through a JSON inventory of checks. It is built for guests that cannot be polled directly but can reach the Kuma push endpoint.
|
||
|
||
## Files
|
||
- `kuma-push.sh` – performs the checks and submits results via HTTP GET.
|
||
- `kuma-checks.json` – declarative list of checks the script will execute.
|
||
|
||
## Requirements
|
||
- `bash`, `jq`, `wget`, and access to `https://status.jordanwages.com` (adjust `BASE` in the script if your Kuma lives elsewhere).
|
||
- Optional: `systemd`, `cron`, or another scheduler to run the script every minute.
|
||
|
||
## Configuration (`kuma-checks.json`)
|
||
Each object in the array represents one Kuma monitor and should contain:
|
||
|
||
| Field | Required | Description |
|
||
|-------|----------|-------------|
|
||
| `name` | ✔ | Human-friendly label shown inside Kuma. Sent back in the push message. |
|
||
| `type` | ✔ | One of `native`, `http`, `service`, `docker`, `mount`, or `disk`. |
|
||
| `push` | ✔ | Kuma push token for the monitor. |
|
||
| `target` | ◐ | Interpreted per check type (URL, systemd service name, container name, mount path, or disk device). Not used for `native`. |
|
||
| `threshold` | ◐ | Only used for `disk` checks. Marks the percentage usage at which the disk turns unhealthy. |
|
||
|
||
Example:
|
||
```json
|
||
{
|
||
"name": "web_frontend",
|
||
"type": "http",
|
||
"target": "http://localhost:8080/health",
|
||
"push": "xxxxxxxxxxxxxxxx"
|
||
}
|
||
```
|
||
|
||
## Check Types
|
||
- **native**: Always reports `up`. Useful for “is the agent alive” checks.
|
||
- **http**: Issues a `wget` to the target URL and reports `up` when the request succeeds. Ping time is the response time in ms.
|
||
- **service**: Calls `systemctl is-active` on the target unit.
|
||
- **docker**: Uses `docker inspect` to confirm the container is running.
|
||
- **mount**: Uses `mountpoint -q` to verify the target path is mounted.
|
||
- **disk**: Finds the mount that corresponds to the device (e.g. `vda5` or `/dev/sda1`) and reports `down` when usage meets/exceeds `threshold`.
|
||
|
||
## Scheduling
|
||
A one-minute cadence keeps Kuma happy without overwhelming it. Two common options:
|
||
|
||
### systemd timer
|
||
Create `/etc/systemd/system/kuma-push.service`:
|
||
```ini
|
||
[Unit]
|
||
Description=Send Uptime Kuma push heartbeats
|
||
|
||
[Service]
|
||
Type=oneshot
|
||
ExecStart=/usr/local/bin/kuma-push.sh
|
||
```
|
||
|
||
Create `/etc/systemd/system/kuma-push.timer`:
|
||
```ini
|
||
[Unit]
|
||
Description=Run Uptime Kuma push heartbeats every minute
|
||
|
||
[Timer]
|
||
OnBootSec=1min
|
||
OnUnitActiveSec=1min
|
||
AccuracySec=5s
|
||
|
||
[Install]
|
||
WantedBy=timers.target
|
||
```
|
||
|
||
Enable both:
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now kuma-push.timer
|
||
```
|
||
|
||
### cron
|
||
Copy the script into `/usr/local/bin` and drop the following into `crontab -e`:
|
||
```
|
||
* * * * * /usr/local/bin/kuma-push.sh >/dev/null 2>&1
|
||
```
|
||
|
||
## Customization Tips
|
||
- Update the `BASE` variable inside `kuma-push.sh` if your Kuma origin or token path changes.
|
||
- When `curl` is available you can swap `wget` for `curl` calls; the current implementation favours `wget` so the template can stay minimal.
|
||
- Add jitter with the `sleep $(( RANDOM % 5 ))` line if you scale to dozens of VMs—feel free to widen the range.
|
||
|
||
## Troubleshooting
|
||
- **Missing dependencies**: install `jq` and `wget` (`apt install jq wget`). The script exits if either is missing.
|
||
- **No pushes arriving**: confirm the machine reaches the Kuma endpoint manually with `wget`. Kuma will mark the monitor down automatically when pushes stop.
|
||
- **Disk check always down**: ensure the `target` resolves to a mounted device (`lsblk -f` and `findmnt` help confirm the correct name).
|