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:

{
  "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:

[Unit]
Description=Send Uptime Kuma push heartbeats

[Service]
Type=oneshot
ExecStart=/usr/local/bin/kuma-push.sh

Create /etc/systemd/system/kuma-push.timer:

[Unit]
Description=Run Uptime Kuma push heartbeats every minute

[Timer]
OnBootSec=1min
OnUnitActiveSec=1min
AccuracySec=5s

[Install]
WantedBy=timers.target

Enable both:

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

3.5 KiB Raw Permalink Blame History Unescape Escape