Document the network defaults, LAN opt-in and migration
This commit is contained in:
+11
-5
@@ -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) |
|
||||
|
||||
@@ -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