mirror of
https://github.com/coder/coder.git
synced 2026-09-01 14:53:15 +08:00
blinkagent[bot]
043bebb7bc
## What Adds a **Recovering from a stale tunnel** section to the Coder Desktop user guide, with separate macOS and Windows procedures, and tightens the existing macOS log-collection instructions. ## Why Users in the field have hit a state where Coder Desktop's menu bar / tray shows **Coder Connect** as enabled but the embedded tunnel is no longer working: * `workspace.coder` fails to resolve (`No such host`), or * DNS returns stale `fd60:627a:a42b::/48` addresses that no longer route, causing `coder ssh`, file sync, and the directory picker to hang. Related issues: * coder/coder#26669 — `ExistsViaCoderConnect` false positives when Coder Desktop has stale DNS * coder/coder-desktop-windows#171 — Tray reports Coder Connect as healthy while tunnel/DNS is broken Until the underlying state-management gap is fixed in the apps, the docs should give users (and support) a safe, repeatable way to recover without rebooting. ## Changes `docs/user-guides/desktop/index.md`: 1. **New "Recovering from a stale tunnel" section** under Troubleshooting: * **macOS:** stop the VPN configuration with `scutil --nc stop`, quit the app via `osascript`, restart the helper daemon in place with `launchctl kickstart -k system/com.coder.Coder-Desktop.Helper`, flush DNS caches, then relaunch. * Includes a warning to **not** use `launchctl bootout`, which removes the daemon from launchd's system domain entirely and is not re-bootstrapped on app relaunch. * Includes a verification step using the built-in sentinel hostname `is.coder--connect--enabled--right--now.coder` (defined in `tailnet/conn.go` as `IsCoderConnectEnabledFmtString`) so users don't need a workspace name to confirm the tunnel is healthy. * Uses `dig @fd60:627a:a42b::53` (explicit server) and `dscacheutil -q host -a name` because plain `dig` does not respect the macOS system resolver. * **Windows:** stop the app and `Coder Desktop` service, flush DNS, restart, then verify the NRPT rule and Wintun adapter. Notes that `ipconfig /flushdns` does not reset the embedded resolver and that filtering agents (e.g., Zscaler) may still shadow `.coder` lookups. 2. **macOS log-collection improvements:** * Switch the predicate from `subsystem == "com.coder.Coder-Desktop"` to `subsystem BEGINSWITH "com.coder.Coder-Desktop"` so the export captures the app, helper daemon, and network extension (which all log under prefixed subsystems). * Add a `log stream` example for live tailing while reproducing an issue. ## Verification * `npx markdownlint-cli2 docs/user-guides/desktop/index.md` — 0 errors. * macOS recovery steps were validated end-to-end on a real install (the `kickstart -k` form, in particular, was confirmed to restart the helper without breaking the install, unlike `bootout`). --- Created on behalf of @mdanter --------- Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com> Co-authored-by: Atif Ali <atif@coder.com> Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com> Co-authored-by: Matyas Danter <mdanter@gmail.com>