# 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).