Trusted Proxies

Configure trusted proxies to correctly handle client IPs and headers when PteroCA is behind a proxy, load balancer, or CDN.

Overview

When PteroCA is behind a proxy (like Cloudflare, NGINX, or a load balancer), the application sees the proxy's IP address instead of the actual client IP. Configuring trusted proxies tells Symfony to trust certain headers from specific proxies.

When You Need This

Configure trusted proxies if you're using:

• Cloudflare or other CDN

• Reverse proxy (NGINX, Apache, HAProxy)

• Load balancer

• Docker with reverse proxy

• Any proxy that forwards requests

Configuration

Step 1: Identify Proxy IPs

Determine which IP addresses should be trusted as proxies.

Cloudflare:

• Use official IP ranges from https://www.cloudflare.com/ips/

NGINX/Apache reverse proxy:

• Use the proxy server's IP address

• If on same server: 127.0.0.1

• If on different server: proxy's private/public IP

Load balancer:

• Use all load balancer IP addresses

Docker:

• Use Docker network gateway IP (usually 172.17.0.1 or similar)

Step 2: Configure in .env

Add the TRUSTED_PROXIES variable to your .env file:

nano /var/www/pteroca/.env

Add one of the following configurations:

Single proxy:

TRUSTED_PROXIES=127.0.0.1

Multiple proxies:

TRUSTED_PROXIES=127.0.0.1,192.168.1.100,10.0.1.50

IP range (CIDR notation):

TRUSTED_PROXIES=192.168.1.0/24,10.0.0.0/8

Cloudflare (all IPv4 ranges):

TRUSTED_PROXIES=173.245.48.0/20,103.21.244.0/22,103.22.200.0/22,103.31.4.0/22,141.101.64.0/18,108.162.192.0/18,190.93.240.0/20,188.114.96.0/20,197.234.240.0/22,198.41.128.0/17,162.158.0/15,104.16.0.0/13,104.24.0.0/14,172.64.0.0/13,131.0.72.0/22

Trust all (testing only):

TRUSTED_PROXIES=0.0.0.0/0

⚠️ Warning: Only use 0.0.0.0/0 for testing. This trusts all IPs and is insecure.

Step 3: Clear Cache

After updating .env, clear the cache:

cd /var/www/pteroca
php bin/console cache:clear

Common Scenarios

Scenario 1: Cloudflare CDN

Setup: Domain → Cloudflare → Your server → PteroCA

Configuration:

# Use all Cloudflare IP ranges
TRUSTED_PROXIES=173.245.48.0/20,103.21.244.0/22,103.22.200.0/22,103.31.4.0/22,141.101.64.0/18,108.162.192.0/18,190.93.240.0/20,188.114.96.0/20,197.234.240.0/22,198.41.128.0/17,162.158.0/15,104.16.0.0/13,104.24.0.0/14,172.64.0.0/13,131.0.72.0/22

# Also configure trusted hosts
TRUSTED_HOSTS=^panel\.example\.com$

Get current Cloudflare IPs:

# IPv4
curl https://www.cloudflare.com/ips-v4

# IPv6
curl https://www.cloudflare.com/ips-v6

Scenario 2: NGINX Reverse Proxy

Setup: Client → NGINX (proxy) → PteroCA

NGINX Configuration:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

PteroCA Configuration:

# If NGINX is on same server
TRUSTED_PROXIES=127.0.0.1

# If NGINX is on different server (e.g., 192.168.1.100)
TRUSTED_PROXIES=192.168.1.100

Scenario 3: Docker with Reverse Proxy

Setup: Docker network with NGINX proxy container

Find Docker gateway IP:

docker network inspect bridge | grep Gateway

Configuration:

# Common Docker gateway
TRUSTED_PROXIES=172.17.0.1

# Or trust entire Docker network
TRUSTED_PROXIES=172.17.0.0/16

Scenario 4: Load Balancer

Setup: Client → Load Balancer → Multiple PteroCA instances

Configuration:

# Trust all load balancer IPs
TRUSTED_PROXIES=10.0.1.10,10.0.1.11,10.0.1.12

# Or use CIDR range
TRUSTED_PROXIES=10.0.1.0/24

Scenario 5: Multiple Layers

Setup: Cloudflare → Load Balancer → NGINX → PteroCA

Configuration:

# Trust both Cloudflare and load balancer
TRUSTED_PROXIES=173.245.48.0/20,103.21.244.0/22,...,10.0.1.0/24,127.0.0.1

Headers Trusted

When a proxy is trusted, Symfony trusts these headers from it:

• X-Forwarded-For - Client IP address

• X-Forwarded-Host - Original host

• X-Forwarded-Proto - Protocol (HTTP/HTTPS)

• X-Forwarded-Port - Original port

Verifying Configuration

Check Current IP Detection

// In any controller or service
$request = $this->requestStack->getCurrentRequest();
$clientIp = $request->getClientIp();
// This should be the real client IP, not proxy IP

Test with curl

# Without proper proxy headers
curl http://your-domain.com

# With proxy headers (simulating Cloudflare)
curl -H "X-Forwarded-For: 1.2.3.4" http://your-domain.com

Check Logs

Verify logs show correct client IPs:

# Check PteroCA logs
tail -f var/log/prod.log

# Check NGINX logs
tail -f /var/log/nginx/access.log

Troubleshooting

Wrong IP Addresses in Logs

Symptom: Logs show proxy IP instead of client IP

Solutions:

1. Verify TRUSTED_PROXIES is set

   cat .env | grep TRUSTED_PROXIES

2. Check proxy is sending headers

   # In NGINX access log format, add:
   log_format detailed '$remote_addr - $http_x_forwarded_for ...';

3. Verify proxy IP is in trusted list

   • Get actual proxy IP from logs

   • Add to TRUSTED_PROXIES

4. Clear cache

   php bin/console cache:clear

CSRF Token Errors

Symptom: "Invalid CSRF token" when behind proxy

Cause: Proxy not trusted, so client IP changes between requests

Solution:

# Add proxy IPs to TRUSTED_PROXIES
TRUSTED_PROXIES=127.0.0.1,proxy_ip_here

See CSRF Protection for more details.

Rate Limiting Issues

Symptom: All users rate-limited together

Cause: Application sees all requests from proxy IP

Solution:

• Configure TRUSTED_PROXIES correctly

• Application will then use X-Forwarded-For for rate limiting

• Each user has separate rate limit

Security Considerations

Only Trust Known Proxies

Don't trust all IPs:

# ❌ NEVER in production
TRUSTED_PROXIES=0.0.0.0/0

# ✅ Only trust specific proxies
TRUSTED_PROXIES=192.168.1.100

Verify Proxy IPs Regularly

1. Cloudflare IPs change - Check quarterly

2. Proxy infrastructure changes - Update after infrastructure changes

3. Remove old entries - Clean up unused proxy IPs

Use Specific Ranges

# ✅ Good - Specific range
TRUSTED_PROXIES=10.0.1.0/24

# ❌ Bad - Too broad
TRUSTED_PROXIES=10.0.0.0/8

Validate Headers

Trusted proxies mean trusting their headers. Ensure:

• Proxy is under your control

• Proxy properly sanitizes headers

• Proxy doesn't allow header injection

Advanced Configuration

Symfony Configuration

For more control, edit config/packages/framework.yaml:

framework:
    trusted_proxies: '%env(TRUSTED_PROXIES)%'
    trusted_headers: ['x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-forwarded-port', 'x-forwarded-prefix']

Environment-Specific

Different proxies for different environments:

# .env.development
TRUSTED_PROXIES=127.0.0.1

# .env.staging
TRUSTED_PROXIES=192.168.1.0/24

# .env.production
TRUSTED_PROXIES=173.245.48.0/20,...  # Cloudflare IPs

IPv6 Support

Include both IPv4 and IPv6 ranges:

TRUSTED_PROXIES=173.245.48.0/20,103.21.244.0/22,2400:cb00::/32,2606:4700::/32

Related Guides

• CSRF Protection - CSRF configuration

• Web Server Configuration - NGINX/Apache setup

• Troubleshooting - Common issues