Document the network defaults, LAN opt-in and migration

This commit is contained in:
2026-11-10 01:06:17 +00:00
parent d35ae9b65a
commit e614f93578
2 changed files with 138 additions and 5 deletions
+11 -5
View File
@@ -88,11 +88,13 @@ one; it does not touch that binary.
| Service | Default | Flag |
| --- | --- | --- |
| Web proxy (sign-in, web app, `/updates/`) | `0.0.0.0:8082` | `--web-port`, `--web-host` |
| Web proxy (sign-in, web app, `/updates/`) | port 8082, loopback + tailnet only | `--web-port`, `--web-host`, `--web-lan` |
| Server API (no auth) | `127.0.0.1:8080` | `--port`, `--bind-address` |
| ntfy | `:8090` | `--ntfy-port`, `--ntfy-url` |
Expose only the web proxy. A reinstall keeps the saved ports and bind
Expose only the web proxy. It listens on loopback and this machine's Tailscale
addresses unless you opt into the LAN; see
[network defaults](notes/network-and-update-signing.md). A reinstall keeps the saved ports and bind
addresses unless you pass the flag again, so an installation set up with
`--web-port 8083` stays on 8083.
@@ -101,7 +103,8 @@ so the phone app's "Find servers on this network" lists it. The advertised port
is the web proxy's (when it listens beyond loopback; the supervisor passes
`-mdns-port`), or the server's own `-addr` port when that is a LAN address.
TXT records: `v` (version), `name` (host), `path=/connect`, `tls=0`,
`auth=password|none`. Set `PIPELINES_MDNS=off` (or `-mdns=false`) to disable
`auth=password|none`, plus `ts=`/`public=` routes; without `--web-lan` the
advert carries no LAN route (`lan=0`, address records are the tailnet IPs). Set `PIPELINES_MDNS=off` (or `-mdns=false`) to disable
it; a failure to advertise is logged and never stops the server.
`PIPELINES_WEB_PUBLIC_URL` is the address phones and notification links use.
@@ -111,7 +114,8 @@ Set it once; reinstalls keep it:
PIPELINES_WEB_PUBLIC_URL=https://mymac.tailnet-name.ts.net ./install
```
Without it the installer records `http://<LAN IP>:<web-port>`. Use HTTPS or a
Without it the installer records the tailnet IP (or `127.0.0.1`), or
`http://<LAN IP>:<web-port>` where LAN sign-in is allowed. Use HTTPS or a
VPN for remote access; plain HTTP does not protect the password.
## Flags
@@ -124,7 +128,9 @@ From `arguments()` in `scripts/setup-native.py`:
| `--port N` | server API port (default 8080) |
| `--bind-address IP` | server API bind (default `127.0.0.1`) |
| `--web-port N` | web proxy port (default 8082) |
| `--web-host IP` | web proxy bind (default `0.0.0.0`) |
| `--web-host tailnet\|IP` | web proxy access: `tailnet` (default for new installs: loopback and Tailscale addresses only) or a literal IPv4 bind such as `0.0.0.0`; existing installs keep theirs and get a warning |
| `--web-lan` | also accept plain-HTTP LAN connections; sign-in over them stays refused |
| `--web-lan-plain-login` | allow sign-in over plain-HTTP LAN (unencrypted password and cookie; trusted networks only) |
| `--ntfy-port N` | ntfy port (default 8090) |
| `--ntfy-url URL` | ntfy address given to phones (default `http://<LAN IP>:<ntfy-port>`) |
| `--timezone TZ` | override the detected timezone (fallback UTC) |
+127
View File
@@ -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