proxmox-server-setup/docs/uptime-kuma

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