Skip to content

Upgrade Guide: v0.7.1 to v0.7.2

v0.7.2 simplifies the v0.7.1 auth surface to a clean binary posture. The headline auth.mode: open | secure is unchanged; what changes is that the intermediate, footgun-prone states beneath it are removed so that two invariants now always hold:

  • tokens ⟺ TLS ⟺ secure — HTTP bearer-token enforcement is derived purely from auth.mode: secure (the standalone auth.http.mode knob is gone).
  • https ⟺ secure — https_port is valid only in secure mode, and secure mode is TLS-only (it no longer serves a plain-HTTP listener at all, not even on loopback).

A breaking patch

Like v0.7.1, this is a 0.7.x patch that carries breaking config changes — the auth interface is still settling in the 0.7 line. Most users are unaffected: the default is auth.mode: open, byte-for-byte the trusted-network posture, and a plain auth.mode: secure + github_users config keeps working unchanged. The changes below only affect configs that used the now-removed intermediate states.

What changed

  • auth.http.mode is removed. HTTP token enforcement is no longer an independent knob — it is on iff auth.mode: secure. "Tokens enforced over plaintext" is no longer representable.
  • https_port requires auth.mode: secure. An open-mode server serves plain HTTP only; setting https_port without secure is rejected at startup. This is what lets a client (or the host-agent) treat an https api_url as proof the server enforces tokens.
  • auth.ssh.mode: enforce requires auth.mode: secure. Restricting SSH while leaving the HTTP API open is no longer a supported posture. Use auth.ssh.mode: warn to stage an allowlist on a trusted network (the SSH-allowlist pre-flight), then switch to secure (which forces enforce). An explicit auth.ssh.mode: off|warn under secure is rejected (secure derives enforce itself).
  • Secure mode is TLS-only. It no longer serves a loopback plain-HTTP listener. Only the pinned-TLS (https_port, default 8443) listener faces clients. On-box tooling and health probes must use the HTTPS endpoint; shed server add against a secure server requires --https-port.

Breaking: removed/invalid config now hard-fails

These are rejected at startup in v0.7.2 — the server names the gap and exits. Edit your server config before upgrading an affected host, or it will fail to restart:

v0.7.1 (now removed / invalid) v0.7.2 replacement
auth.http.mode: enforce (and the whole auth.http block) Remove it — enforcement derives from auth.mode: secure.
https_port under auth.mode: open Use auth.mode: secure (it defaults https_port to 8443), or drop https_port.
auth.ssh.mode: enforce under auth.mode: open Use auth.mode: secure, or warn to stage.
auth.ssh.mode: off | warn under auth.mode: secure Remove it — secure forces enforce.

Migrating

Most secure deployments need no change — a config like this is already correct:

auth:
  mode: secure
  ssh:
    github_users: [charliek]
tls_names: [shed.example.com]

If you had set auth.http.mode, an open-mode https_port, or an open-mode auth.ssh.mode: enforce, delete those keys per the table above. Clients are unaffected: shed server add … --https-port 8443 and the auto-minted, auto-refreshing tokens work exactly as in v0.7.1.

On-box access in secure mode

Because secure mode is now TLS-only, anything that previously reached the API over plain http://localhost:<http_port> (health probes, scripts) must use https://localhost:<https_port> with the pinned cert. A co-located credential-bus listener over loopback remains available only via the explicit, opt-in internal_http_port (unchanged) — there is no implicit plaintext channel.

See Security for the full model and the connection-flow breakdown, and Public VPS Deployment for the end-to-end secure flow.