Repository navigation
fix(fleet): installer-managed per-peer SSH forwards with standard keepalives + healthcheck #1775
Description
Important
Problem — The SSH forward a machine uses to reach a peer's hub is a hand-installed launch agent the fleet installer does not generate. It runs stale keepalives (30 s interval, 3 misses), so a dead link takes about 90 s to notice, and the healthcheck only inspects the hub-tunnel agent, so this one is never checked — its log is almost entirely resets and timeouts. A stray agent also sets the multiplex flag session-wide, leaking it into every GUI process, although the flag already defaults on.
Approach — The fleet installer generates one forward agent per attached peer with the repo-standard options (15 s keepalive, 2 misses, TCP keepalive, exit on forward failure), Fleet — Repair regenerates it, the healthcheck checks every peer forward the same way it checks the hub tunnel, and the installer retires the stray flag agent.
Scope — in: an installer template and regeneration for per-peer forwards; healthcheck coverage; retiring the flag agent. out: supervised links on Linux and WSL (#1260); Tailscale serve setup.
Assumptions — Per-peer forwards can follow a predictable label and local-port convention the healthcheck can enumerate; the peer token store already records each peer's local base URL.
Acceptance Criteria
- Running the installer or Fleet — Repair on a machine attached to a peer produces that peer's forward agent with a 15 s keepalive, 2 misses, TCP keepalive on, exit on forward failure, and the configured local port; re-running is idempotent.
- An existing hand-installed forward for the same peer is replaced, with a backup kept rather than a silent delete.
- The healthcheck reports each peer forward agent and flags missing or stale keepalive values with a fix line, exactly as it does for the hub tunnel.
- The installer removes the session-wide multiplex-flag agent and unsets the variable; fleet behavior is unchanged because the flag defaults on.
Testing Decisions
- Extend the fleet installer tests and the healthcheck suite (several forward agents; stale values).
Key Decisions
- One agent per peer, its label derived from the peer's machine id and its local port from the peer token store's base URL.
Constraints & Invariants
- Machine-scoped state changes only through the installer or Fleet — Repair, never through repo sync.
Prior Art
- The hub-tunnel agent template and its keepalive check; the fleet transport's standard forward options; the peer token store's base URLs.
Source
Notes
- Rollout is human-run: Fleet — Repair on each machine after merge.
Activity
jeonghun-jj-lee commentedon Oct 13, 2026
Merged into the #1770 integration branch as 3a6be6a (PR #1781, draft). Director gates: install.sh syntax ok, packaged copy in sync, tsc 0, suite 323/5483/0/48 (×3 clean; one earlier run hit a load-sensitive real-ssh flake in fleet_peer_e2e that also passes 8/8 alone on the tip — not this slice), 3 test files 0 failures in 20 runs, assert_fleet_guard exit 0, LaunchAgents listing and launchd job set identical before/after, live forward untouched. Rollout is a human step after merge: Fleet — Repair on each machine (it will briefly drop and restore the 45096 peer link).
test(fleet): installer write-mode runs reach launchctl only through a…
fix(fleet): the installer generates one SSH forward agent per attache…
fix(fleet): a hand-installed peer forward is replaced with a backup, …
fix(fleet): the healthcheck checks every per-peer forward agent the w…
fix(fleet): the installer retires the session-wide multiplex-flag age…
docs(fleet): the installer header and fleet README describe the per-p…
Merge #1775: installer-managed per-peer SSH forwards with standard ke…