Document the network defaults, LAN opt-in and migration
This commit is contained in:
@@ -1,5 +1,132 @@
|
||||
# Network defaults and update-feed signing
|
||||
|
||||
## Where the web proxy listens
|
||||
|
||||
Before this change `./install` bound the web proxy to `0.0.0.0` over plain
|
||||
HTTP. With the macOS firewall off, anyone on the same café or hotel Wi-Fi could
|
||||
reach the sign-in page, and the password and the 30-day session cookie crossed
|
||||
that network unencrypted. The operator reaches the Mac over Tailscale
|
||||
(`https://<host>.ts.net:8443` through `tailscale serve` to `127.0.0.1:8083`,
|
||||
and `ws://100.x:8083` from tank), so the LAN listener was not needed.
|
||||
|
||||
### Defaults and opt-ins
|
||||
|
||||
`web.host` in `pipelines-install.json` takes one of two forms:
|
||||
|
||||
| `web.host` | Proxy flags (`manage.web_listen_args`) | Who can connect |
|
||||
| --- | --- | --- |
|
||||
| `tailnet` (new installs) | `--host :: --allow loopback,tailnet` | loopback and this machine's Tailscale IPv4/IPv6 addresses |
|
||||
| `tailnet` with `web.lan: true` | `... --allow loopback,tailnet,lan` | also the LAN, but no sign-in or signed-in pages over plain HTTP |
|
||||
| `tailnet` with `web.lan: true`, `web.lan_plain_login: true` | `... --lan-plain-login` | the LAN, with plain-HTTP sign-in (the old behaviour) |
|
||||
| an IPv4 address, e.g. `0.0.0.0` | `--host 0.0.0.0` | whatever the bind reaches, unfiltered (the old behaviour) |
|
||||
|
||||
Installer flags: `--web-host tailnet|IPv4`, `--web-lan` / `--no-web-lan`,
|
||||
`--web-lan-plain-login` / `--no-web-lan-plain-login`. A reinstall keeps the
|
||||
saved values unless you pass the flag again. `--web-lan` on an install that
|
||||
still has a literal host moves it to `tailnet`. `--web-lan` together with an
|
||||
explicit IPv4 `--web-host` is refused.
|
||||
|
||||
On an opted-in LAN without `lan_plain_login`, a plain-HTTP LAN connection gets
|
||||
`403` with an explanation for `POST /login`, `GET /login`, every signed-in
|
||||
page, `/updates/`, `/api/*` and websocket upgrades. Only the public icons and
|
||||
manifest are served. **Risk of `web.lan_plain_login`:** anyone on that network
|
||||
who can watch the traffic sees the password and session cookie, and the cookie
|
||||
works for 30 days. Use it only on a network you trust. `X-Forwarded-Proto` is
|
||||
not trusted from the LAN, because a client can set it to anything.
|
||||
|
||||
### Why the proxy binds the wildcard and filters each connection
|
||||
|
||||
Tailscale often starts after the proxy (both start at login), and its address
|
||||
can change. Binding the tailnet IP itself would fail at boot, and keeping it
|
||||
working would need retry and rebind logic. Instead the proxy binds `::`, which
|
||||
on macOS and Linux also accepts IPv4 (it falls back to `0.0.0.0` on a host
|
||||
without IPv6). On every `connection` it drops the socket, before any HTTP is
|
||||
read, unless **both** ends are loopback (`127/8`, `::1`) or **both** are
|
||||
tailnet (`100.64.0.0/10`, `fd7a:115c:a1e0::/48`); see
|
||||
`web/src/listenPolicy.js`.
|
||||
|
||||
Both ends are checked because macOS uses the weak host model: it accepts a
|
||||
packet addressed to its tailnet IP on any interface. A LAN host that spoofs a
|
||||
tailnet source address cannot finish the TCP handshake, because the reply is
|
||||
routed into the tunnel.
|
||||
|
||||
The cost: a LAN scan sees the port open and immediately reset, and no HTTP is
|
||||
served. One edge case is not handled: Tailscale subnet routes without SNAT
|
||||
deliver peers with non-tailnet source addresses, and those are treated as LAN.
|
||||
|
||||
### Discovery (mDNS)
|
||||
|
||||
`manage.mdns_args` passes `-mdns-lan=false` when `web.host` is `tailnet`
|
||||
without `web.lan`. `discovery.Plan` with `NoLAN` then makes these changes:
|
||||
|
||||
- The A records are the tailnet IPv4 addresses, not the LAN ones.
|
||||
- TXT gains `lan=0`, and `ts=` and `public=` stay.
|
||||
- The port is still the proxy's, which answers on the tailnet.
|
||||
- With no tailnet address, nothing is published (`ErrNotReachable`).
|
||||
|
||||
The advert is still multicast on the LAN, so a tailnet client on the same Wi-Fi
|
||||
finds the machine. `Browse` (Go, also behind `/api/discovery`) and the app's
|
||||
`DiscoveredServer.fromRecord` drop the LAN route when `lan=0`, so the endpoint
|
||||
becomes the first tailnet or public route. An older client still sees a "LAN"
|
||||
route, but it points at the tailnet IP, which works from the tailnet.
|
||||
|
||||
### Firewall
|
||||
|
||||
The installer turns nothing on at the OS level. It only reads
|
||||
`socketfilterfw --getglobalstate` and prints a recommendation when the firewall
|
||||
is off. On this Mac on 2026-11-10 it reported `Firewall is disabled.
|
||||
(State = 0)`. Recommendation: turn it on (System Settings > Network >
|
||||
Firewall). The proxy no longer depends on it, but other local services
|
||||
(ntfy on `:8090`, development servers) do.
|
||||
|
||||
### Migration
|
||||
|
||||
- **Live Mac** (`web.host: 0.0.0.0`, port 8083, public URL
|
||||
`https://alans-macbook-pro.tail6bf4dc.ts.net:8443`): a plain `./install`
|
||||
keeps `0.0.0.0` and prints
|
||||
`WARNING: the web proxy listens on 0.0.0.0 over plain HTTP ... Recommended: ./install --web-host tailnet ...`.
|
||||
To switch, run `./install --web-host tailnet` while no run or chat is active
|
||||
(the install restarts the services). `tailscale serve` still reaches
|
||||
`127.0.0.1:8083`, and tank's `ws://100.85.25.33:8083` is a tailnet
|
||||
connection, so both keep working. Phones on the home Wi-Fi that saved
|
||||
`ws://10.0.0.x:8083` must switch to the tailnet route (rediscover, or pick
|
||||
the Tailscale address).
|
||||
- **tank:** the same `./install --web-host tailnet`. Check first that every
|
||||
client reaches it through Tailscale.
|
||||
- An install whose recorded `PIPELINES_WEB_PUBLIC_URL` is a plain-HTTP LAN
|
||||
address gets a warning to set it to the tailnet HTTPS address.
|
||||
|
||||
### Verification (network)
|
||||
|
||||
- `cd web && node --test test/`: `tests 24, pass 24, fail 0`. This includes
|
||||
`listenPolicy.test.mjs`, which uses real sockets on this Mac's LAN (10.0.0.x)
|
||||
and tailnet (100.85.25.33) addresses.
|
||||
- `umask 022 && go test ./internal/discovery ./cmd/pipelines-server ./internal/server`:
|
||||
all `ok`. This includes `TestPlanWithoutLANAdvertisesOnlyTailnetAndPublicRoutes`
|
||||
and `TestBrowseOmitsTheLANRouteWhenTheAdvertSaysLan0`.
|
||||
- `cd scripts && python3 -m unittest`: `Ran 229 tests ... OK (skipped=1)`.
|
||||
This includes `test_web_access` and
|
||||
`test_upgrade_keeps_an_all_interfaces_web_host_with_a_warning_and_lan_is_opt_in`.
|
||||
- App: `tool/memwatch/full.sh 'test/features/updates test/features/onboarding test/features/settings'`
|
||||
gave `PASS: 212 passed, 0 failed`, and `tool/analyze.sh` was clean.
|
||||
- Scratch end-to-end: an isolated `HOME`, an OS-chosen port, real sign-in, and
|
||||
the proxy started with `manage.web_listen_args` output:
|
||||
|
||||
```
|
||||
== default loopback + tailnet: serve.mjs --port 53780 --host :: --allow loopback,tailnet
|
||||
GET http://127.0.0.1:53780/login -> 200 POST -> 303
|
||||
GET http://100.85.25.33:53780/login -> 200 POST -> 303
|
||||
GET http://10.0.0.249:53780/login -> 000 (connection reset, curl exit 56)
|
||||
== LAN opted in, no plain login: ... --allow loopback,tailnet,lan
|
||||
GET/POST via 127.0.0.1 and 100.85.25.33 -> 200/303; via 10.0.0.249 -> 403/403
|
||||
== LAN with lan_plain_login: ... --lan-plain-login
|
||||
GET/POST via 10.0.0.249 -> 200/303
|
||||
```
|
||||
|
||||
The live mDNS advert was not exercised, because a scratch server would publish
|
||||
the same `Pipelines-<host>` instance name as the live one. The records are
|
||||
covered by `Plan`/`Zone` tests.
|
||||
|
||||
## Update feed signing
|
||||
|
||||
Before this change the app trusted whatever `/updates/` served: the Linux
|
||||
|
||||
Reference in New Issue
Block a user