docs: document proxy_allowed_ips requirement for Cloudflare setups
The internal CA onboarding gate (enabled by default via tls_port = 8443) rejects non-localhost HTTP traffic unless the source IP is in proxy_allowed_ips. Cloudflare users must add edge IPs to this setting. - Add Proxy Origin Allowlist section to installation.md - Add migration note to upgrading.md for v2.31.0 - Cross-reference from Cloudflare SSL Mode section Closes #161
- commit
- a1f49f76ff7cac508f776fff98f650056cf17821
- author
- brice · · 2026-04-03 18:41 UTC
- parent
- cbca441
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
2 files · +40 -0
M docs/installation.md +23 -0
| @@ -258,8 +258,31 @@ Gordon serves HTTP by default. Cloudflare must connect to your origin over HTTP | |||
| 258 | 258 | ||
| 259 | 259 | Wrong mode causes: **521** (Cloudflare can't connect) or **525** (TLS handshake failed). | |
| 260 | 260 | ||
| 261 | + | > **Important:** You must also set `proxy_allowed_ips` with Cloudflare edge IPs — see [Proxy Origin Allowlist](#proxy-origin-allowlist) below. | |
| 262 | + | ||
| 261 | 263 | > **Rootless note:** Unprivileged users can't bind port 80. Forward port 80→8088 (or your configured port) via firewall — see the firewall section above. | |
| 262 | 264 | ||
| 265 | + | ## Proxy Origin Allowlist | |
| 266 | + | ||
| 267 | + | When Gordon's internal CA is enabled (default: `tls_port = 8443`), HTTP requests from non-localhost IPs are restricted to certificate onboarding paths only. Cloudflare and other reverse proxies must be listed in `proxy_allowed_ips` to reach your applications. | |
| 268 | + | ||
| 269 | + | Add Cloudflare edge IPs to your `gordon.toml`: | |
| 270 | + | ||
| 271 | + | ```toml | |
| 272 | + | [server] | |
| 273 | + | proxy_allowed_ips = [ | |
| 274 | + | "173.245.48.0/20", "103.21.244.0/22", "103.22.200.0/22", | |
| 275 | + | "103.31.4.0/22", "141.101.64.0/18", "108.162.192.0/18", | |
| 276 | + | "190.93.240.0/20", "188.114.96.0/20", "197.234.240.0/22", | |
| 277 | + | "198.41.128.0/17", "162.158.0.0/15", "104.16.0.0/13", | |
| 278 | + | "104.24.0.0/14", "172.64.0.0/13", "131.0.72.0/22", | |
| 279 | + | ] | |
| 280 | + | ``` | |
| 281 | + | ||
| 282 | + | Without this setting, Cloudflare traffic receives `403 Forbidden: Only certificate onboarding is available over HTTP`. | |
| 283 | + | ||
| 284 | + | > **Note:** This is separate from `[api.rate_limit] trusted_proxies`, which controls IP extraction from `X-Forwarded-For`. Both should list your proxy IPs. See [Proxy Origin IP Allowlist](./config/server.md#proxy-origin-ip-allowlist) for details. | |
| 285 | + | ||
| 263 | 286 | ## Verify Installation | |
| 264 | 287 | ||
| 265 | 288 | ```bash | |
| @@ -258,8 +258,31 @@ Gordon serves HTTP by default. Cloudflare must connect to your origin over HTTP | |||||
| 258 | 258 | ||||
| 259 | Wrong mode causes: **521** (Cloudflare can't connect) or **525** (TLS handshake failed). | 259 | Wrong mode causes: **521** (Cloudflare can't connect) or **525** (TLS handshake failed). | ||
| 260 | 260 | ||||
| 261 | + | > **Important:** You must also set `proxy_allowed_ips` with Cloudflare edge IPs — see [Proxy Origin Allowlist](#proxy-origin-allowlist) below. | |||
| 262 | + | ||||
| 261 | > **Rootless note:** Unprivileged users can't bind port 80. Forward port 80→8088 (or your configured port) via firewall — see the firewall section above. | 263 | > **Rootless note:** Unprivileged users can't bind port 80. Forward port 80→8088 (or your configured port) via firewall — see the firewall section above. | ||
| 262 | 264 | ||||
| 265 | + | ## Proxy Origin Allowlist | |||
| 266 | + | ||||
| 267 | + | When Gordon's internal CA is enabled (default: `tls_port = 8443`), HTTP requests from non-localhost IPs are restricted to certificate onboarding paths only. Cloudflare and other reverse proxies must be listed in `proxy_allowed_ips` to reach your applications. | |||
| 268 | + | ||||
| 269 | + | Add Cloudflare edge IPs to your `gordon.toml`: | |||
| 270 | + | ||||
| 271 | + | ```toml | |||
| 272 | + | [server] | |||
| 273 | + | proxy_allowed_ips = [ | |||
| 274 | + | "173.245.48.0/20", "103.21.244.0/22", "103.22.200.0/22", | |||
| 275 | + | "103.31.4.0/22", "141.101.64.0/18", "108.162.192.0/18", | |||
| 276 | + | "190.93.240.0/20", "188.114.96.0/20", "197.234.240.0/22", | |||
| 277 | + | "198.41.128.0/17", "162.158.0.0/15", "104.16.0.0/13", | |||
| 278 | + | "104.24.0.0/14", "172.64.0.0/13", "131.0.72.0/22", | |||
| 279 | + | ] | |||
| 280 | + | ``` | |||
| 281 | + | ||||
| 282 | + | Without this setting, Cloudflare traffic receives `403 Forbidden: Only certificate onboarding is available over HTTP`. | |||
| 283 | + | ||||
| 284 | + | > **Note:** This is separate from `[api.rate_limit] trusted_proxies`, which controls IP extraction from `X-Forwarded-For`. Both should list your proxy IPs. See [Proxy Origin IP Allowlist](./config/server.md#proxy-origin-ip-allowlist) for details. | |||
| 285 | + | ||||
| 263 | ## Verify Installation | 286 | ## Verify Installation | ||
| 264 | 287 | ||||
| 265 | ```bash | 288 | ```bash | ||
M docs/upgrading.md +17 -0
| @@ -33,6 +33,23 @@ sudo firewall-cmd --reload | |||
| 33 | 33 | ||
| 34 | 34 | Gordon now includes an internal CA for automatic on-demand TLS. Set `tls_port = 0` to disable. See [Server Configuration](./config/server.md#internal-ca-and-tls) for details. | |
| 35 | 35 | ||
| 36 | + | ### Required for Cloudflare/Proxy Setups: `proxy_allowed_ips` | |
| 37 | + | ||
| 38 | + | The internal CA's HTTP onboarding gate rejects non-localhost HTTP requests by default. If Gordon sits behind Cloudflare or another reverse proxy, add the proxy's edge IPs to `proxy_allowed_ips`: | |
| 39 | + | ||
| 40 | + | ```toml | |
| 41 | + | [server] | |
| 42 | + | proxy_allowed_ips = [ | |
| 43 | + | "173.245.48.0/20", "103.21.244.0/22", "103.22.200.0/22", | |
| 44 | + | "103.31.4.0/22", "141.101.64.0/18", "108.162.192.0/18", | |
| 45 | + | "190.93.240.0/20", "188.114.96.0/20", "197.234.240.0/22", | |
| 46 | + | "198.41.128.0/17", "162.158.0.0/15", "104.16.0.0/13", | |
| 47 | + | "104.24.0.0/14", "172.64.0.0/13", "131.0.72.0/22", | |
| 48 | + | ] | |
| 49 | + | ``` | |
| 50 | + | ||
| 51 | + | Without this, all proxied HTTP traffic returns `403 Forbidden`. Set `tls_port = 0` to disable the internal CA and skip this requirement. | |
| 52 | + | ||
| 36 | 53 | ## v2.16.0 to v2.30.0 | |
| 37 | 54 | ||
| 38 | 55 | ### Breaking: Password Authentication Removed | |
| @@ -33,6 +33,23 @@ sudo firewall-cmd --reload | |||||
| 33 | 33 | ||||
| 34 | Gordon now includes an internal CA for automatic on-demand TLS. Set `tls_port = 0` to disable. See [Server Configuration](./config/server.md#internal-ca-and-tls) for details. | 34 | Gordon now includes an internal CA for automatic on-demand TLS. Set `tls_port = 0` to disable. See [Server Configuration](./config/server.md#internal-ca-and-tls) for details. | ||
| 35 | 35 | ||||
| 36 | + | ### Required for Cloudflare/Proxy Setups: `proxy_allowed_ips` | |||
| 37 | + | ||||
| 38 | + | The internal CA's HTTP onboarding gate rejects non-localhost HTTP requests by default. If Gordon sits behind Cloudflare or another reverse proxy, add the proxy's edge IPs to `proxy_allowed_ips`: | |||
| 39 | + | ||||
| 40 | + | ```toml | |||
| 41 | + | [server] | |||
| 42 | + | proxy_allowed_ips = [ | |||
| 43 | + | "173.245.48.0/20", "103.21.244.0/22", "103.22.200.0/22", | |||
| 44 | + | "103.31.4.0/22", "141.101.64.0/18", "108.162.192.0/18", | |||
| 45 | + | "190.93.240.0/20", "188.114.96.0/20", "197.234.240.0/22", | |||
| 46 | + | "198.41.128.0/17", "162.158.0.0/15", "104.16.0.0/13", | |||
| 47 | + | "104.24.0.0/14", "172.64.0.0/13", "131.0.72.0/22", | |||
| 48 | + | ] | |||
| 49 | + | ``` | |||
| 50 | + | ||||
| 51 | + | Without this, all proxied HTTP traffic returns `403 Forbidden`. Set `tls_port = 0` to disable the internal CA and skip this requirement. | |||
| 52 | + | ||||
| 36 | ## v2.16.0 to v2.30.0 | 53 | ## v2.16.0 to v2.30.0 | ||
| 37 | 54 | ||||
| 38 | ### Breaking: Password Authentication Removed | 55 | ### Breaking: Password Authentication Removed | ||