Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions site/src/content/docs/docs/guides/deploy.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -99,3 +99,65 @@ 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.
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.

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.
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. 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:

```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
```

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`.
Loading