diff --git a/CLAUDE.md b/CLAUDE.md index 35022cb..3303e5f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -78,6 +78,21 @@ The `~/bin/dns` script manages Technitium DNS (internal zone: lab.georgsen.dk): ~/bin/dns lookup # Query DNS ``` +## Uptime Kuma API Access + +Uptime Kuma (status.georgsen.dk) has limited REST API - mainly for metrics and push monitors. + +```bash +# Get Prometheus metrics +source ~/.config/uptime-kuma/credentials +curl -u ":$KUMA_API_KEY" "http://$KUMA_HOST:$KUMA_PORT/metrics" + +# Push monitor update (for passive checks) +curl "http://$KUMA_HOST:$KUMA_PORT/api/push/?status=up&msg=OK&ping=50" +``` + +Note: Full monitor management (add/edit/delete) requires Socket.IO API, not REST. + ## Common SSH Targets ```bash diff --git a/TODO.md b/TODO.md index 7d0f51b..3c97100 100644 --- a/TODO.md +++ b/TODO.md @@ -13,6 +13,8 @@ - Already correct: mgmt (.102), general (.113) - Also update: NPM proxy hosts, DNS records (lab.georgsen.dk), iptables NAT rules, documentation +- [ ] **Review Uptime Kuma monitors** - Check which services are monitored and add missing ones (via web UI at status.georgsen.dk) + - [ ] **Fix ping on all unprivileged containers** - Run `setcap cap_net_raw+ep /bin/ping` on each container (requires restart or at least root access inside container) - Containers to fix: 100 (npm), 101 (dockge), 102 (mgmt), 103 (postgresql01), 104 (redis01), 105 (sentry), 107 (pve-scripts-local), 108 (jukebox), 110 (sense), 111 (dev), 112 (dataloes), 114 (forgejo), 115 (dns), 1000 (tailscale) - Skip: 106 (pbs) - privileged container, 113 (general) - already done diff --git a/homelab-documentation.md b/homelab-documentation.md index aa2bdae..6d09752 100644 --- a/homelab-documentation.md +++ b/homelab-documentation.md @@ -594,6 +594,19 @@ Personal company website - **API Token:** root@pam!pve - **Fingerprint:** f6:5d:3f:63:0e:15:38:10:38:7a:33:82:3a:c0:b0:59:98:a7:04:7d:8d:ed:64:7d:fc:85:ab:8f:87:a4:48:eb +### Uptime Kuma API (from mgmt container) + +- **Host:** 10.5.0.10:3001 (on Dockge container) +- **URL:** https://status.georgsen.dk +- **Config:** ~/homelab/uptime-kuma/credentials (symlinked to ~/.config/uptime-kuma) +- **API Key:** uk1_... (stored in credentials file) +- **REST Endpoints:** + - `/metrics` - Prometheus metrics (auth: Basic with API key as password) + - `/api/push/` - Push monitor updates + - `/api/status-page/` - Status page data + - `/api/badge//status` - Status badges +- **Note:** Full monitor management requires Socket.IO API, not REST + ### PVE API (from mgmt container) - **Token:** root@pam!mgmt diff --git a/uptime-kuma/README.md b/uptime-kuma/README.md new file mode 100644 index 0000000..8cad1cb --- /dev/null +++ b/uptime-kuma/README.md @@ -0,0 +1,92 @@ +# Uptime Kuma API + +## Overview + +- **Host:** 10.5.0.10:3001 (Dockge container) +- **Public URL:** https://status.georgsen.dk +- **Credentials:** `~/.config/uptime-kuma/credentials` + +## Authentication + +```bash +source ~/.config/uptime-kuma/credentials +# Variables: KUMA_HOST, KUMA_PORT, KUMA_API_KEY +``` + +Use API key as password with empty username for Basic Auth: +```bash +curl -u ":$KUMA_API_KEY" "http://$KUMA_HOST:$KUMA_PORT/metrics" +``` + +Or Bearer token: +```bash +curl -H "Authorization: Bearer $KUMA_API_KEY" "http://$KUMA_HOST:$KUMA_PORT/api/entry-page" +``` + +## REST API Endpoints + +### Prometheus Metrics +```bash +curl -u ":$KUMA_API_KEY" "http://$KUMA_HOST:$KUMA_PORT/metrics" +``` + +### Push Monitor (Passive Checks) +For push-type monitors, update status via URL: +```bash +# Basic +curl "http://$KUMA_HOST:$KUMA_PORT/api/push/" + +# With parameters +curl "http://$KUMA_HOST:$KUMA_PORT/api/push/?status=up&msg=OK&ping=50" +``` + +Parameters: +- `status` - "up" or "down" (default: "up") +- `msg` - Status message, ~250 chars max (default: "OK") +- `ping` - Response time in ms + +### Status Page Data +```bash +# Get status page info (requires published status page) +curl "http://$KUMA_HOST:$KUMA_PORT/api/status-page/" + +# Get heartbeats and uptime +curl "http://$KUMA_HOST:$KUMA_PORT/api/status-page/heartbeat/" +``` + +### Status Badges +```bash +# Status badge (monitor must be in public status page group) +curl "http://$KUMA_HOST:$KUMA_PORT/api/badge//status" + +# Uptime badge +curl "http://$KUMA_HOST:$KUMA_PORT/api/badge//uptime" +curl "http://$KUMA_HOST:$KUMA_PORT/api/badge//uptime/24h" +curl "http://$KUMA_HOST:$KUMA_PORT/api/badge//uptime/7d" + +# Response time badge +curl "http://$KUMA_HOST:$KUMA_PORT/api/badge//ping" + +# Certificate expiry badge +curl "http://$KUMA_HOST:$KUMA_PORT/api/badge//cert-exp" +``` + +### Entry Page +```bash +curl "http://$KUMA_HOST:$KUMA_PORT/api/entry-page" +``` + +## Limitations + +The REST API is limited to: +- Push monitor updates +- Reading metrics/status +- Badge generation + +**Full monitor management** (create, edit, delete monitors) requires the **Socket.IO API**, which is more complex and uses WebSockets. For adding monitors, use the web UI at https://status.georgsen.dk. + +## References + +- [API Documentation](https://github.com/louislam/uptime-kuma/wiki/API-Documentation) +- [API Keys](https://github.com/louislam/uptime-kuma/wiki/API-Keys) +- [Internal API](https://github.com/louislam/uptime-kuma/wiki/Internal-API) diff --git a/uptime-kuma/credentials b/uptime-kuma/credentials new file mode 100644 index 0000000..530da99 --- /dev/null +++ b/uptime-kuma/credentials @@ -0,0 +1,3 @@ +KUMA_HOST=10.5.0.10 +KUMA_PORT=3001 +KUMA_API_KEY=uk1_Vuph7SHROz7iagvmjz2Vb5z1Bn3PwZS6z2PGqd9i