From ab42a2bf358c0d104bffbc68f1b5b0d1c52dd153 Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Sat, 7 Nov 2026 10:59:15 -0800 Subject: [PATCH 1/2] docs(deploy): run the native systemd unit on port 443 Some TLS-terminating proxies, such as Cloudflare's gRPC proxying, reach the origin only on port 443. The deploy guide's unit binds loopback port 7520 as an unprivileged user and gave no way to bind 443 without root. Document a drop-in that moves FANOUT_ADDR to :443, passes the TLS certificate and key as systemd credentials, and grants only CAP_NET_BIND_SERVICE through AmbientCapabilities with a matching CapabilityBoundingSet and NoNewPrivileges. Include commands to confirm the process runs as the service user with only that capability. Closes #429 --- site/src/content/docs/docs/guides/deploy.mdx | 50 ++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/site/src/content/docs/docs/guides/deploy.mdx b/site/src/content/docs/docs/guides/deploy.mdx index f3ab22b7e..7ef3d3888 100644 --- a/site/src/content/docs/docs/guides/deploy.mdx +++ b/site/src/content/docs/docs/guides/deploy.mdx @@ -99,3 +99,53 @@ sudo journalctl -u fanout Use the setup URL from the journal. Restrict journal access because that URL is an administrator credential. Check `http://127.0.0.1:7520/readyz` after startup. See [hardening](/docs/guides/hardening) before exposing the listener. + +### Listen on port 443 + +Some TLS-terminating proxies connect to the origin only on port 443. For +example, [Cloudflare's gRPC proxying](https://developers.cloudflare.com/network/grpc-connections/) +requires the origin to listen on 443 with TLS and HTTP/2 advertised through +ALPN, which Fanout's [direct TLS](/docs/guides/tls#direct-tls) provides. +Linux reserves ports below 1024 for privileged processes, so grant the +unprivileged `fanout` user only the capability to bind them rather than running +as root. + +Add a drop-in with `sudo systemctl edit fanout`: + +```ini +[Service] +Environment=FANOUT_ADDR=:443 +LoadCredential=fanout_tls_cert:/etc/fanout/tls/cert.pem +LoadCredential=fanout_tls_key:/etc/fanout/tls/key.pem +Environment=FANOUT_TLS_CERT_FILE=%d/fanout_tls_cert +Environment=FANOUT_TLS_KEY_FILE=%d/fanout_tls_key +AmbientCapabilities=CAP_NET_BIND_SERVICE +CapabilityBoundingSet=CAP_NET_BIND_SERVICE +NoNewPrivileges=true +``` + +`AmbientCapabilities` gives the process `CAP_NET_BIND_SERVICE` although it runs +as `fanout`. `CapabilityBoundingSet` drops every other capability, and +`NoNewPrivileges` stops the process and its children from gaining more. +The later `FANOUT_ADDR` replaces the unit's loopback address; `:443` listens on +every interface, so restrict the port to the proxy's networks with a firewall. +The certificate and key are passed as credentials, like the auth secret, so +they can stay readable only by root. + +Restart and confirm the listener runs as `fanout` with only that capability: + +```sh +sudo systemctl daemon-reload +sudo systemctl restart fanout +systemctl show fanout -p User -p AmbientCapabilities -p CapabilityBoundingSet +sudo ss -ltnp 'sport = :443' +grep Cap /proc/"$(systemctl show fanout -p MainPID --value)"/status +``` + +`ss` should show the `fanout` process on port 443, and `CapAmb` and `CapEff` +should both be `0000000000000400` (`CAP_NET_BIND_SERVICE` alone). Check +readiness on the host with a name in the certificate: + +```sh +curl --resolve fanout.example.com:443:127.0.0.1 https://fanout.example.com/readyz +``` From 78d35ff129513632c61b966eac58ac7b6af78db8 Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Sat, 7 Nov 2026 11:32:49 -0800 Subject: [PATCH 2/2] docs(deploy): add Cloudflare prerequisites to the port 443 section Review follow-up. Cloudflare's gRPC proxying also needs gRPC enabled on the zone (otherwise it answers 403), a proxied DNS record and at least Full encryption; recommend Full (strict) so Cloudflare verifies the origin certificate. Link Cloudflare's IP ranges for the firewall, note that credentials are copied and the certificate loaded at service start so renewal needs a restart, and show --cacert for private or Cloudflare Origin CA certificates in the readiness check. Refs #429 --- site/src/content/docs/docs/guides/deploy.mdx | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/site/src/content/docs/docs/guides/deploy.mdx b/site/src/content/docs/docs/guides/deploy.mdx index 7ef3d3888..a66c6e630 100644 --- a/site/src/content/docs/docs/guides/deploy.mdx +++ b/site/src/content/docs/docs/guides/deploy.mdx @@ -106,6 +106,11 @@ Some TLS-terminating proxies connect to the origin only on port 443. For example, [Cloudflare's gRPC proxying](https://developers.cloudflare.com/network/grpc-connections/) requires the origin to listen on 443 with TLS and HTTP/2 advertised through ALPN, which Fanout's [direct TLS](/docs/guides/tls#direct-tls) provides. +On Cloudflare, also enable gRPC in the zone's network settings (otherwise +Cloudflare answers gRPC requests with `403 Forbidden`), set the DNS record to +proxied, and set the SSL/TLS encryption mode to Full (strict). Cloudflare +accepts Full, but only Full (strict) verifies the origin certificate. + Linux reserves ports below 1024 for privileged processes, so grant the unprivileged `fanout` user only the capability to bind them rather than running as root. @@ -129,8 +134,11 @@ as `fanout`. `CapabilityBoundingSet` drops every other capability, and `NoNewPrivileges` stops the process and its children from gaining more. The later `FANOUT_ADDR` replaces the unit's loopback address; `:443` listens on every interface, so restrict the port to the proxy's networks with a firewall. +For Cloudflare, allow only [Cloudflare's published IP ranges](https://www.cloudflare.com/ips/). The certificate and key are passed as credentials, like the auth secret, so -they can stay readable only by root. +they can stay readable only by root. systemd copies credentials when the +service starts, and Fanout loads the certificate once, so restart the service +after renewing the certificate. Restart and confirm the listener runs as `fanout` with only that capability: @@ -149,3 +157,7 @@ readiness on the host with a name in the certificate: ```sh curl --resolve fanout.example.com:443:127.0.0.1 https://fanout.example.com/readyz ``` + +If the certificate comes from a private CA or is a Cloudflare Origin CA +certificate, which public trust stores reject, pass that CA's certificate with +`--cacert`, for example `--cacert /etc/fanout/tls/origin-ca.pem`.