Skip to content

Commit 9efaef0

Browse files
committed
docs(firewalls): document v1.10.3 single-port-443 compat-mode flags
Update web/src/pages/docs/firewalls.astro to reflect the v1.10.3 default: `pilot-daemon -transport=compat` is enough — registry now auto-targets registry.pilotprotocol.network:443 with TLS + system trust. Explicit form added showing all auto-applied flags. "How it works" section explains nginx ssl_preread SNI routing on the rendezvous box. "Airport wifi" bullet updated to call out v1.10.3 single-port behavior.
1 parent f24b502 commit 9efaef0

1 file changed

Lines changed: 18 additions & 5 deletions

File tree

web/src/pages/docs/firewalls.astro

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,37 +22,50 @@ const bodyContent = `<h1>Running pilot behind a firewall</h1>
2222
<ul>
2323
<li><strong>Container PaaS without UDP exposure:</strong> Render, Railway, Vercel, Fly.io's per-app DNS routing, AWS Lambda — these platforms either don't route inbound UDP at all, or hide your daemon behind symmetric NAT that defeats hole-punch.</li>
2424
<li><strong>Locked-down corporate networks</strong> where outbound UDP is firewalled but HTTPS to arbitrary internet hosts is allowed.</li>
25-
<li><strong>Airport / hotel / conference wifi</strong> that blocks everything but TCP/443.</li>
25+
<li><strong>Airport / hotel / conference wifi</strong> that blocks everything but TCP/443. As of v1.10.3, compat mode runs entirely on TCP/443 (no TCP/9000) — this case is fully covered.</li>
2626
</ul>
2727
2828
<p>If your daemon registers fine but heartbeats keep failing, or queries to specialists time out with relay-retransmit errors flooding the log, you're likely in one of these environments. <strong>Compat mode</strong> is the answer: same daemon binary, same overlay, just a different wire from your daemon to the beacon.</p>
2929
3030
<h2 id="enabling">Enabling compat mode</h2>
3131
32-
<p>Compat mode is opt-in via three CLI flags on the standalone <code>pilot-daemon</code> binary:</p>
32+
<p>Compat mode is opt-in via one CLI flag on the standalone <code>pilot-daemon</code> binary:</p>
3333
3434
<pre><code><span class="cmd">pilot-daemon</span> -transport=compat</code></pre>
3535
36-
<p>That's the minimum — every other flag has a working default. Explicit form:</p>
36+
<p>That's it — every other flag has a working default. As of v1.10.3 the daemon uses <strong>a single outbound TCP/443 connection</strong> for everything: the beacon WSS bridge AND the registry. Explicit form:</p>
3737
3838
<pre><code><span class="cmd">pilot-daemon</span> \\
3939
-transport=compat \\
4040
-compat-beacon=wss://beacon.pilotprotocol.network/v1/compat \\
41-
-tls-trust=system</code></pre>
41+
-tls-trust=system \\
42+
-registry=registry.pilotprotocol.network:443 \\
43+
-registry-tls -registry-trust=system</code></pre>
4244
4345
<p>Flag semantics:</p>
4446
4547
<ul>
4648
<li><code>-transport=compat</code> — switches the tunnel transport from UDP to WSS. Default is <code>udp</code>; the daemon falls back to UDP behavior if this flag is unset.</li>
4749
<li><code>-compat-beacon &lt;url&gt;</code> — the beacon's WSS endpoint. The default points at the managed public beacon (<code>wss://beacon.pilotprotocol.network/v1/compat</code>); self-hosted deployments override it.</li>
4850
<li><code>-tls-trust &lt;mode&gt;</code> — see <a href="#tls-trust">TLS trust</a>. Defaults to <code>system</code>.</li>
51+
<li><code>-registry &lt;host:port&gt;</code> — auto-defaults to <code>registry.pilotprotocol.network:443</code> in compat mode. Overrides the standard <code>34.71.57.205:9000</code> UDP-mode default; you can still pass a custom registry host:port if you self-host.</li>
52+
<li><code>-registry-tls</code> + <code>-registry-trust=system</code> — auto-enabled in compat mode. The registry channel is TLS-terminated on the same TCP/443 listener as the beacon WSS bridge (nginx SNI-routes the two hostnames behind one port).</li>
4953
</ul>
5054
5155
<p>The daemon also automatically forces <code>relay_only=true</code> when compat is enabled — peers will route to it via the beacon's relay path instead of trying direct UDP, which would fail anyway.</p>
5256
5357
<h2 id="how-it-works">How it works</h2>
5458
55-
<p>The compat-mode daemon opens one long-lived WebSocket Secure connection to the beacon. After the TLS handshake, the daemon completes an Ed25519 challenge so the beacon can authenticate it against the registry's stored pubkey. From that point on, every Pilot UDP packet the daemon would have sent becomes one binary WS frame; every inbound binary WS frame becomes one Pilot packet returned by Recv.</p>
59+
<p>The compat-mode daemon opens outbound connections to <strong>only TCP/443</strong> — multiplexed by SNI through a single nginx listener on the rendezvous host:</p>
60+
61+
<ul>
62+
<li><code>beacon.pilotprotocol.network:443</code> — long-lived WebSocket Secure connection that carries the data plane (peer-to-peer Pilot frames, wrapped as binary WS messages).</li>
63+
<li><code>registry.pilotprotocol.network:443</code> — TLS connection pool for the registry RPC channel (registration, heartbeats, resolve, hostname lookup). Same wire protocol as the legacy UDP-mode <code>tcp:9000</code>, just wrapped in TLS.</li>
64+
</ul>
65+
66+
<p>nginx pre-reads the TLS ClientHello's SNI field and routes registry traffic to its TLS terminator (which proxies plain bytes to the existing registry server), while beacon traffic terminates on the existing WSS-aware vhost. No code change on the registry side; the daemon's <code>-registry-trust=system</code> path verifies the public Let's Encrypt cert.</p>
67+
68+
<p>After the TLS handshake, the daemon completes an Ed25519 challenge so the beacon can authenticate it against the registry's stored pubkey. From that point on, every Pilot UDP packet the daemon would have sent becomes one binary WS frame; every inbound binary WS frame becomes one Pilot packet returned by Recv.</p>
5669
5770
<p>The beacon transparently bridges between UDP peers and WSS peers. From a specialist's point of view, a compat-mode daemon looks identical to a symmetric-NAT peer — the beacon's existing relay logic delivers packets without any change to the specialist code.</p>
5871

0 commit comments

Comments
 (0)