From ee8221e6c88640dba31c69c59c19e65a8dc54a3e Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Thu, 16 Apr 2026 09:06:42 +0300 Subject: Release 0.5.0: upload client docs for all OSes, host exclusion, Prometheus metrics - docs/upload-client.md: per-OS install instructions (FreeBSD, Linux, OpenBSD) covering script install, token setup, cron/systemd automation, and test runs - README.md: replace long upload section with pointer to docs/upload-client.md - Bump version to 0.5.0 (new features: excluded_hosts, /metrics endpoint, unified upload script with non-root/XDG support) Co-Authored-By: Claude Sonnet 4.6 --- docs/upload-client.md | 248 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 docs/upload-client.md (limited to 'docs') diff --git a/docs/upload-client.md b/docs/upload-client.md new file mode 100644 index 0000000..943d09d --- /dev/null +++ b/docs/upload-client.md @@ -0,0 +1,248 @@ +# Upload client installation + +`scripts/goprecords-upload-client.sh` is a POSIX `sh` script that uploads +uptimed record files to a running `goprecords` daemon. It works on FreeBSD, +Linux, and OpenBSD, and runs as root or as a regular user. + +A copy is also kept in `contrib/` for backward compatibility. + +## Prerequisites + +Install `curl` and `uptimed` on every client host and ensure `uptimed` is +running before setting up uploads. + +| OS | Package manager | +|----|-----------------| +| FreeBSD | `pkg install curl uptimed` | +| Rocky Linux / Fedora | `sudo dnf install curl uptimed` | +| OpenBSD | `pkg_add curl uptimed` | + +## Token path + +| Privilege | Path | +|-----------|------| +| root | `/etc/goprecords-upload.token` (mode `600`) | +| non-root | `${XDG_CONFIG_HOME:-$HOME/.config}/goprecords-upload-/token` (mode `600`) | + +Override with `GOPRECORDS_TOKEN_FILE`. + +## Environment variables + +| Variable | Default (root) | Default (non-root) | +|----------|----------------|--------------------| +| `GOPRECORDS_HOST` | **required** | **required** | +| `GOPRECORDS_TOKEN_FILE` | `/etc/goprecords-upload.token` | `$XDG_CONFIG_HOME/goprecords-upload-/token` | +| `GOPRECORDS_BASE_URL` | `https://goprecords.f3s.buetow.org` | same | + +## Step 1 — Issue a token on the server + +`HOSTNAME` must match the short stats name used in every upload URL (e.g. +`f0`, `pi2`, `earth`, `blowfish`). + +```bash +# daemon running in Kubernetes +kubectl exec -n services deployment/goprecords -- \ + goprecords --create-client-key HOSTNAME -stats-dir=/data/stats + +# daemon running locally +goprecords --create-client-key HOSTNAME -stats-dir=/var/lib/goprecords/stats +``` + +The plaintext token is printed once. Store it only on the client. +Re-running `--create-client-key` for the same hostname replaces the previous token. + +## Step 2 — Install the script + +**FreeBSD** + +```sh +doas install -m 755 scripts/goprecords-upload-client.sh \ + /usr/local/bin/goprecords-upload-client.sh +``` + +**Linux (root)** + +```sh +sudo install -m 755 scripts/goprecords-upload-client.sh \ + /usr/local/bin/goprecords-upload-client.sh +``` + +**OpenBSD** + +```sh +doas install -m 755 scripts/goprecords-upload-client.sh \ + /usr/local/bin/goprecords-upload-client.sh +``` + +**Linux (user session, e.g. earth)** + +```sh +install -m 700 scripts/goprecords-upload-client.sh \ + ~/.local/bin/goprecords-upload-client.sh +``` + +## Step 3 — Store the token + +**FreeBSD / Linux (root)** + +```sh +# FreeBSD +umask 077 +echo 'TOKEN' | doas tee /etc/goprecords-upload.token +doas chmod 600 /etc/goprecords-upload.token + +# Linux +umask 077 +echo 'TOKEN' | sudo tee /etc/goprecords-upload.token +sudo chmod 600 /etc/goprecords-upload.token +``` + +**OpenBSD** + +```sh +umask 077 +echo 'TOKEN' | doas tee /etc/goprecords-upload.token +doas chmod 600 /etc/goprecords-upload.token +``` + +**Linux (user session)** + +```sh +mkdir -p ~/.config/goprecords-upload-earth +umask 077 +echo 'TOKEN' > ~/.config/goprecords-upload-earth/token +``` + +## Step 4 — Automate + +### FreeBSD — hourly cron + +Add to root's crontab (`crontab -e` as root, or `/etc/crontab`). `curl` must +be on `PATH` for cron: + +```cron +PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin +0 * * * * root /usr/bin/env GOPRECORDS_HOST=f0 /usr/local/bin/goprecords-upload-client.sh +``` + +Repeat with the matching `GOPRECORDS_HOST` value on each host (`f1`, `f2`, `f3`, …). + +### Linux (Rocky/Fedora) — hourly systemd timer, system-wide + +`/etc/goprecords-upload.env` (mode `644`): + +```ini +GOPRECORDS_HOST=pi0 +``` + +`/etc/systemd/system/goprecords-upload.service`: + +```ini +[Unit] +Description=Upload uptimed stats to goprecords + +[Service] +Type=oneshot +EnvironmentFile=/etc/goprecords-upload.env +Environment=GOPRECORDS_TOKEN_FILE=/etc/goprecords-upload.token +ExecStart=/usr/local/bin/goprecords-upload-client.sh +``` + +`/etc/systemd/system/goprecords-upload.timer`: + +```ini +[Unit] +Description=Hourly uptimed upload to goprecords + +[Timer] +OnCalendar=hourly +OnActiveSec=90s +RandomizedDelaySec=300 +Persistent=true + +[Install] +WantedBy=timers.target +``` + +```sh +sudo systemctl daemon-reload +sudo systemctl enable --now goprecords-upload.timer +``` + +Use a different `GOPRECORDS_HOST` in `/etc/goprecords-upload.env` on each Pi +(`pi1`, `pi2`, `pi3`). + +### Linux — hourly systemd timer, user session (earth) + +`~/.config/systemd/user/goprecords-upload-earth.service`: + +```ini +[Unit] +Description=Upload uptimed stats to goprecords + +[Service] +Type=oneshot +Environment=GOPRECORDS_HOST=earth +ExecStart=%h/.local/bin/goprecords-upload-client.sh +``` + +`~/.config/systemd/user/goprecords-upload-earth.timer`: + +```ini +[Unit] +Description=Hourly uptimed upload to goprecords (earth) + +[Timer] +OnCalendar=hourly +OnActiveSec=90s +RandomizedDelaySec=300 +Persistent=true + +[Install] +WantedBy=timers.target +``` + +Enable lingering so uploads continue without an active login session: + +```sh +sudo loginctl enable-linger "$USER" +systemctl --user daemon-reload +systemctl --user enable --now goprecords-upload-earth.timer +``` + +### OpenBSD — daily cron via /etc/daily.local + +OpenBSD's `uptimed` only updates its records file once per day, so a daily run +is sufficient. Add to `/etc/daily.local`: + +```sh +GOPRECORDS_HOST=blowfish /usr/local/bin/goprecords-upload-client.sh +``` + +Adjust `GOPRECORDS_HOST` for each OpenBSD host (`fishfinger`, etc.). + +## Step 5 — Test one run + +**FreeBSD** + +```sh +doas env GOPRECORDS_HOST=f0 /usr/local/bin/goprecords-upload-client.sh +``` + +**Linux (root)** + +```sh +sudo env GOPRECORDS_HOST=pi0 /usr/local/bin/goprecords-upload-client.sh +``` + +**OpenBSD** + +```sh +doas env GOPRECORDS_HOST=blowfish /usr/local/bin/goprecords-upload-client.sh +``` + +**Linux (user session)** + +```sh +GOPRECORDS_HOST=earth ~/.local/bin/goprecords-upload-client.sh +``` -- cgit v1.2.3