Trusted Proxies (Cloudflare)

When Proxima Gateway sits directly on the public internet, every connection's TCP peer address is the visitor — so the firewall, rate limiter, GeoIP blocker, and access logs all work correctly out of the box.

The moment you put Cloudflare (or any other reverse proxy) in front of the gateway, that breaks: every connection now arrives from a Cloudflare edge IP, so every request looks like it came from "Cloudflare" to the firewall. Real visitor IPs live inside HTTP headers — but blindly trusting headers would let anyone spoof their location by setting X-Forwarded-For themselves.

The Trusted Proxies panel solves both problems: tell the gateway which upstreams it should trust, and it will read the real visitor IP from their forwarded headers — and ignore those headers from anyone else.

How it works

1. A request arrives. The gateway looks at the TCP peer address (r.RemoteAddr).
2. Is the peer in the trusted set? The trusted set is the union of Cloudflare's published IP ranges (if the Cloudflare toggle is on) plus any custom CIDRs you've added.
3. If yes, the gateway tries these headers in order and uses the first valid IP:
   1. CF-Connecting-IP — Cloudflare's canonical header
   2. X-Forwarded-For — leftmost value if a chain is present
   3. X-Real-IP — nginx-style
4. If no, all headers are ignored and the peer address itself is treated as the visitor IP. This is the spoofing guard: an attacker that connects directly to your origin and sets CF-Connecting-IP: 8.8.8.8 will not bypass any country block or rate limit — they'll be tagged with their actual IP.

The derived IP is what every downstream check sees: bans, country blocking, rate limits, MAC protection, GeoIP logging, ASN routing.

Configuration

Open Configuration → Trusted Proxies in the dashboard.

Trust Cloudflare

Flip this on if your domain is proxied through Cloudflare.

• The gateway ships with a bundled snapshot of Cloudflare's published ranges (15 IPv4 CIDRs + 7 IPv6 CIDRs) — enough to work immediately without internet access at startup.
• Click Pull latest from Cloudflare anytime to fetch the live list from cloudflare.com/ips-v4 and cloudflare.com/ips-v6. The dashboard shows the last refresh timestamp and total CIDR count.
• Cloudflare updates their ranges rarely; pull if you've recently started seeing blocked legitimate traffic from CF edges.

Trust your own IPs / networks

Flip this on to trust additional upstreams — admin VPN gateways, internal load balancers, an nginx box that sits between Cloudflare and the gateway, etc.

• One entry per line. Bare IPs are accepted (192.168.1.50) and are treated as a single-host range. CIDR notation also works (10.0.0.0/8, 2001:db8::/32). Both IPv4 and IPv6 are supported.
• The custom set is additive — if both toggles are on, the gateway trusts Cloudflare's ranges and your custom entries.

Status strip

Above the toggles, a single line summarizes the active policy:

🛡️ Trusting N IPs — Cloudflare (22) · Custom (3)

If both toggles are off, it reads "No upstream trusted" and the gateway behaves identically to direct-internet deployment — peer IP is the visitor IP.

Common setups

Cloudflare proxy only. Flip on Trust Cloudflare, save. Done.

Cloudflare + admin VPN. Trust Cloudflare on. Trust your own IPs on, paste your VPN's CIDR (e.g. 10.8.0.0/16). Save.

Self-hosted nginx in front of the gateway. Trust your own IPs on, paste nginx's source IP (often 127.0.0.1 if same-host, otherwise the LAN IP). Make sure nginx is configured to set X-Forwarded-For.

Direct internet. Leave everything off. The gateway sees real peer IPs.

Security notes

• The gateway never trusts a forwarded header from a peer that isn't in the trusted set. Spoofing X-Forwarded-For from the open internet does not work — the request is tagged with its actual peer IP and goes through every check as usual.
• X-Forwarded-For is parsed as leftmost-wins: if Cloudflare sends X-Forwarded-For: 1.2.3.4, 5.6.7.8, the gateway treats 1.2.3.4 as the visitor. This matches the RFC 7239 convention and the behavior of most reverse proxies.
• The Cloudflare list ships bundled so a fresh install works without outbound HTTPS at startup. The Pull latest button is the only path that contacts cloudflare.com — it is gated by the same API secret as the rest of the dashboard's internal endpoints.

API

For headless / scripted setups, the relevant config keys are under trusted_proxies in shared-config/config.json:

{
  "trusted_proxies": {
    "trust_cloudflare": true,
    "trusted_cidrs": ["10.0.0.0/8", "192.168.1.50"],
    "cloudflare_cidrs": ["173.245.48.0/20", "..."],
    "cloudflare_refreshed_at": 1778795707
  }
}

Editing this file directly and signaling the proxy (or saving any change via the dashboard) reloads the trusted-CIDR set atomically — no restart required.

The dashboard exposes one endpoint specific to this feature:

• POST /internal/trusted-proxies/refresh — fetch the current Cloudflare list from cloudflare.com/ips-v4 and cloudflare.com/ips-v6, merge, persist, and reload. Requires the standard Authorization: Bearer <API_SECRET> header.