From 8de0fad77636434976bff725371febc72e9adf8b Mon Sep 17 00:00:00 2001 From: Joakim Persson Date: Sun, 21 Jun 2026 00:23:29 +0200 Subject: [PATCH] docs(lan): document ssh-lan.conf for naming LAN peers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The host-owned, bind-mounted ~/.config/devbox-shell/ssh-lan.conf is the intended place to add `ProxyJump host` overrides for named LAN peers (so `pi --ssh ` / `dssh ` route through the host), but it was only documented in .env.example and the setup-lan-access.sh header — never in the README, where someone hitting "can't reach LAN peers" actually looks. - README: add a "Naming LAN peers" subsection under the macOS LAN-peers troubleshooting block, with a ProxyJump example and the read-only ~/.ssh caveat; add a pointer to it from the SSH and ControlMaster section. - setup-lan-access.sh: correct the INCLUDE_BLOCK comment that suggested adding ProxyJump to the read-only ~/.ssh/config; point at ssh-lan.conf instead. - CHANGELOG: note under Unreleased. Docs/comment only — no behavior change. --- CHANGELOG.md | 11 ++++++++ README.md | 28 ++++++++++++++++++- .../local/lib/pi-devbox/setup-lan-access.sh | 4 ++- 3 files changed, 41 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ab7f6e1..1ef4f44 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,17 @@ Pre-v1.0.0 tags followed the pi npm version (`v{pi_version}[letter]`). ## Unreleased +### Docs: document `~/.config/devbox-shell/ssh-lan.conf` for naming LAN peers + +The host-owned, bind-mounted `~/.config/devbox-shell/ssh-lan.conf` is the +intended place to add `ProxyJump host` overrides for **named** LAN peers (so +`pi --ssh ` / `dssh ` route through the host), but it was only +mentioned in `.env.example` and the `setup-lan-access.sh` header — never in the +README. Added a "Naming LAN peers" subsection to the README troubleshooting +block (plus a pointer from the SSH/ControlMaster section), and corrected the +stale `setup-lan-access.sh` comment that suggested editing the read-only +`~/.ssh/config` instead of `ssh-lan.conf`. + ## v1.1.6 — 2026-06-19 Build provenance + reproducibility hardening, plus pi `0.79.7` → `0.79.8` diff --git a/README.md b/README.md index 74545c1..3c9db4a 100644 --- a/README.md +++ b/README.md @@ -479,7 +479,11 @@ this without editing the read-only config: cannot fail on the read-only socket dir. - **`ssh -F ~/.ssh-local/config` / `dssh` / `dscp`** — `setup-lan-access.sh` redirects `ControlPath` into the writable `~/.ssh-local/cm` for every host - (the sidecar is rendered on all host OSes). + (the sidecar is rendered on all host OSes). To name LAN peers that should + jump via the host, add `ProxyJump host` overrides in the host-owned + `~/.config/devbox-shell/ssh-lan.conf` (see + [Naming LAN peers](#naming-lan-peers)) rather than the read-only + `~/.ssh/config`. ## tmux and 0-indexed sessions @@ -615,6 +619,28 @@ auto-runs on container start and writes `~/.ssh-local/config` with a ssh-jump-via-host configuration. Set `DEVBOX_LAN_ACCESS=jump` and `HOST_SSH_USER=` in `.env` if auto-detection fails. +#### Naming LAN peers + +`DEVBOX_LAN_ACCESS` / `HOST_SSH_USER` only set up the *jump* to the host. To +make a **named** peer route through it — so `pi --ssh alpserv-2`, +`dssh alpserv-2`, etc. resolve the ProxyJump — add a `ProxyJump host` override +for it in the host-owned, bind-mounted `~/.config/devbox-shell/ssh-lan.conf` +(**not** `~/.ssh/config`, which is mounted read-only): + +``` +Host pve pve-2 alpserv-2 lagret + ProxyJump host +``` + +`HostName` / `User` / `IdentityFile` are inherited from the matching block in +your real `~/.ssh/config` (first-value-wins, so only `ProxyJump` is taken from +here). This file is `Include`d *before* `~/.ssh/config` and read fresh on every +connection — newly added peers work immediately, no container or session +restart needed — and the peer names stay out of the published image (they're a +fact about your specific LAN, not the image). Alternatively, set +`DEVBOX_LAN_AUTOJUMP_PRIVATE=1` to ProxyJump *any* RFC1918 address through the +host without naming peers (see `.env.example`). + ### Smoke-testing a local build ```bash diff --git a/rootfs/usr/local/lib/pi-devbox/setup-lan-access.sh b/rootfs/usr/local/lib/pi-devbox/setup-lan-access.sh index 03d36db..06ef5cd 100755 --- a/rootfs/usr/local/lib/pi-devbox/setup-lan-access.sh +++ b/rootfs/usr/local/lib/pi-devbox/setup-lan-access.sh @@ -188,7 +188,9 @@ if [ -r "${HOME}/.ssh/config" ]; then # Your own target hosts. Scope reset to match-all so this Include applies to # every target (an Include is otherwise scoped to the enclosing Host block). -# Add 'ProxyJump host' to LAN entries here (or in ssh-lan.conf above). +# To make a LAN peer jump via the host, add 'ProxyJump host' to its entry in +# the host-owned ~/.config/devbox-shell/ssh-lan.conf (Included above) — NOT +# here in ~/.ssh/config, which is typically bind-mounted read-only. Host * Include ~/.ssh/config EOF