A small authentication gatekeeper that lets a Proxmox Backup Server (PBS) run its offsite push sync only when it can reach — and cryptographically verify — a trusted counterpart over the network. It is not a backup transport; it only decides whether the push is allowed to run right now.
A PBS should push its backups to an offsite target only when it is actually on the trusted network. A plain reachability check (ping/port) is forgeable. Instead, a client and server perform a mutual cryptographic authentication (HMAC-SHA256 challenge-response). Only when both sides prove they hold the same shared secret does the client trigger the local push sync job.
Both programs use the Go standard library only — no external modules.
client/ Go daemon on the source PBS (systemd service). On each interval, on
successful auth: `proxmox-backup-manager sync-job run <job>`.
server/ Go HTTP service, runs as a Docker container on a host reachable
by the source PBS.
docs/ PBS-side setup guides (source and target).
flowchart LR
T(["check cycle<br/>every PBS_CHECK_INTERVAL"]) --> C
subgraph SRC ["Source PBS"]
C["pbs-auth-client"]
J["proxmox-backup-manager<br/>sync-job run"]
C -->|"auth OK"| J
end
subgraph AUTH ["Auth host"]
V["pbs-sync-auth server"]
end
C <-->|"HTTP / JSON<br/>mutual HMAC auth"| V
J ==>|"PBS push sync<br/>fingerprint-pinned TLS · :8007"| TGT[("Target PBS")]
The thin link is the auth handshake (HTTP/JSON, mutual HMAC); the thick link is the actual backup transfer, which goes straight from source to target over the PBS-native, fingerprint-pinned TLS connection. The auth service transfers no backup data — it only decides whether the push may run.
Shared secret K (32 bytes, hex) in /etc/pbs-sync-auth/secret.key, identical on
client and server.
mac(tag, cn, sn) = HMAC-SHA256(K, "tag|cn|sn") (tag ∈ {"server","client"})
POST /auth/challenge {"client_nonce": cn}Server →{"server_nonce": sn, "server_proof": mac("server", cn, sn)}The client verifiesserver_proof→ the server is genuine.POST /auth/verify {"client_nonce": cn, "server_nonce": sn, "client_proof": mac("client", cn, sn)}Server verifiesclient_proof→{"status":"ok"}/401→ the client is authorized.
Security properties: fresh nonces on both sides (replay protection), domain
separation server/client (no reflection attack), single-use challenges with a
30 s TTL, constant-time comparison (hmac.Equal). The authentication is therefore
unforgeable even over plain HTTP — only the random nonces are visible on the wire.
# generate the shared secret
openssl rand -hex 32 > secret.key
# start the server
PBS_AUTH_SECRET=./secret.key PBS_AUTH_PORT=8099 go run ./server &
# run the client against it
PBS_AUTH_SECRET=./secret.key PBS_AUTH_URL=http://127.0.0.1:8099 go run ./client
See server/README.md and client/README.md
for building and deploying, and docs/ for the PBS-side setup.
Generate the 32-byte secret once and copy the same file to both the server and the source PBS:
openssl rand -hex 32 > secret.key # keep it safe, never commit it
Run the published multi-arch image (x86_64 / arm64 / armv7, incl. Raspberry Pi 3/4/5) on a host the source PBS can reach:
docker run -d --name pbs-auth-server \
-p 8099:8099 \
-v "$PWD/secret.key:/run/secrets/pbs_auth_secret:ro" \
-e PBS_AUTH_SECRET=/run/secrets/pbs_auth_secret \
--read-only --security-opt no-new-privileges \
ghcr.io/ftaeger/pbs-sync-auth:1
:1 follows the newest 1.x release (minor and patch/security updates, no
breaking changes); pin :1.0 for patches only or :1.0.0 for an exact release.
See server/README.md for all tags.
Optionally add -e PBS_TARGET_URL=https://pbs-target.example.com:8007 so the
server only returns OK once the target PBS API is reachable — otherwise the client
skips the sync and logs that the central PBS is unavailable (see
server/README.md).
The server speaks plain HTTP on :8099; put a reverse proxy in front for TLS.
Ready-to-use reverse-proxy examples are in examples/: Traefik
(automatic Let's Encrypt, HTTP-01 or Cloudflare DNS-01) plus nginx, Caddy,
HAProxy, Apache httpd and Envoy (TLS termination, bring your own
certificate). A standalone binary + systemd variant is in
server/README.md.
On a PBS you operate as root, so the client commands below use no
sudo.
Choose one of the two install options, then configure and enable.
Option A — APT repository (recommended, updates via apt upgrade)
curl -fsSL https://apt.pbs-sync-auth.com/pubkey.asc \
| gpg --dearmor > /usr/share/keyrings/pbs-sync-auth.gpg
echo "deb [signed-by=/usr/share/keyrings/pbs-sync-auth.gpg] \
https://apt.pbs-sync-auth.com stable main" \
> /etc/apt/sources.list.d/pbs-sync-auth.list
apt update && apt install pbs-sync-auth-client
Option B — manual, single .deb
Download pbs-sync-auth-client_X.Y.Z_amd64.deb from the
releases page and install it:
apt install ./pbs-sync-auth-client_X.Y.Z_amd64.deb
(For a plain-binary install without a package, see
client/README.md.)
Configure and enable (both options)
# 1) configure: auth server, sync job, and how often to check / back up
$EDITOR /etc/pbs-sync-auth/client.conf
# PBS_AUTH_URL, PBS_SYNC_JOB, PBS_CHECK_INTERVAL, PBS_MIN_BACKUP_INTERVAL
# 2) install the shared secret (the SAME secret.key as on the server)
install -m 600 secret.key /etc/pbs-sync-auth/secret.key
# 3) enable and start the daemon
systemctl enable --now pbs-sync-auth.service
Watch it:
systemctl status pbs-sync-auth.service
journalctl -u pbs-sync-auth.service -f
The PBS-side setup (remote, push sync job, permissions) is in
docs/pbs-source.md (source) and
docs/pbs-target.md (target).
Environment variables (see the component READMEs for defaults):
PBS_AUTH_SECRET path to the shared secret (default /etc/pbs-sync-auth/secret.key)
PBS_AUTH_URL client: auth server base URL (http:// or https://)
PBS_AUTH_PORT server: listen port (default 8099)
PBS_SYNC_JOB client: PBS sync job to run (default offsite-push)
PBS_CHECK_INTERVAL client: how often the daemon runs a cycle (default 30m)
PBS_MIN_BACKUP_INTERVAL client: min time between successful syncs (default 0 = every check)
PBS_AUTH_TIMEOUT client: HTTP timeout (default 3s)
PBS_AUTH_TLS_VERIFY client: verify the server cert on https (default true)
PBS_AUTH_TLS_CA client: optional PEM CA bundle to trust (internal CA)
PBS_TARGET_URL server: optional target-PBS reachability gate (e.g.
https://pbs-target.example.com:8007; unset = disabled)
PBS_TARGET_TIMEOUT server: probe timeout for the gate (default 3s)
PBS_MAX_PENDING server: max outstanding challenges (default 100)
PBS_TRUSTED_PROXIES server: proxy CIDRs whose X-Forwarded-For is trusted
for logging the client IP (unset = ignore headers)
For an https:// PBS_AUTH_URL, the client performs the TLS handshake as the
first gate — if certificate verification fails it aborts before the HMAC
round. A publicly trusted certificate (e.g. Let's Encrypt via the Traefik
example) needs no extra client config; PBS_AUTH_TLS_CA trusts an internal CA,
and PBS_AUTH_TLS_VERIFY=false disables verification for testing only. The mutual
HMAC authentication always runs in addition to the TLS check, never instead
of it — so the gate stays unforgeable even over plain HTTP.
- Go: standard library only — do not add external dependencies.
- Target architecture linux/amd64,
CGO_ENABLED=0, static binary. - Container:
scratchbase, non-root (65534), read-only; secret mounted read-only. - Never commit the shared secret (
secret.keyis in.gitignore).
See CHANGELOG.md for release notes.
MIT © 2026 Florian Taeger