Smart Proxy Headers¶
Your backend applications need to know the real client IP address, not Charon's. Standard headers like X-Real-IP, X-Forwarded-For, and X-Forwarded-Proto are added automatically.
Overview¶
When traffic passes through a reverse proxy, your backend loses visibility into the original client connection. Without proxy headers, every request appears to come from Charon's IP address, breaking logging, rate limiting, geolocation, and security features.
Standard Proxy Headers¶
| Header | Purpose | Example Value |
|---|---|---|
| X-Real-IP | Original client IP address | 203.0.113.42 |
| X-Forwarded-For | Chain of proxy IPs | 203.0.113.42, 10.0.0.1 |
| X-Forwarded-Proto | Original protocol (HTTP/HTTPS) | https |
| X-Forwarded-Host | Original host header | example.com |
| X-Forwarded-Port | Original port number | 443 |
Why These Headers Matter¶
Client IP Detection¶
Without X-Real-IP, your application sees Charon's internal IP for every request:
- Logging: All logs show the same IP, making debugging impossible
- Rate Limiting: Cannot throttle abusive clients
- Geolocation: Location services return proxy location, not user location
- Analytics: Traffic analytics become meaningless
HTTPS Enforcement¶
X-Forwarded-Proto tells your backend the original protocol:
- Redirect Loops: Backend sees HTTP, redirects to HTTPS, Charon proxies as HTTP, infinite loop
- Secure Cookies: Applications need to know when to set
Secureflag - Mixed Content: Helps applications generate correct absolute URLs
Virtual Host Routing¶
X-Forwarded-Host preserves the original domain:
- Multi-tenant Apps: Route requests to correct tenant
- URL Generation: Generate correct links in emails, redirects
Configuration¶
Default Behavior¶
| Host Type | Proxy Headers |
|---|---|
| New hosts | Enabled by default |
| Existing hosts (pre-upgrade) | Disabled (preserves existing behavior) |
Enabling/Disabling¶
- Navigate to Hosts → Select your host
- Go to Advanced tab
- Toggle Proxy Headers on or off
- Click Save
Backend Configuration Requirements¶
Your backend must trust proxy headers from Charon. Common configurations:
Node.js/Express:
Django:
Rails:
PHP/Laravel:
Proxy Hosts That Point Back at Charon¶
If a proxy host's destination is Charon itself (on Charon's own port, such as localhost:8080), Charon handles the headers for you. The real visitor address, the original web address, and whether the visit used HTTPS all arrive correctly with no extra setup. See Trusted Proxies.
Sign-in cookies are marked Secure whenever the visitor is on HTTPS or is not on a private network, so browsers only send them over protected connections.
When to Enable vs Disable¶
Enable When¶
- Backend needs real client IP for logging or security
- Application generates absolute URLs
- Using secure cookies with HTTPS termination at proxy
- Rate limiting or geolocation features are needed
Disable When¶
- Backend is an external service you don't control
- Proxying to another reverse proxy that handles headers
- Legacy application that misinterprets forwarded headers
- Security policy requires hiding internal topology
Security Considerations¶
Trusted Proxies¶
Only trust proxy headers from known sources. If your backend blindly trusts X-Forwarded-For, attackers can spoof their IP by injecting fake headers.
Charon follows the same rule. It reads a visitor's address from a forwarded note only when the proxy that sent it is on your trusted list (loopback is always trusted). Otherwise it uses the address of the connection itself. The X-Real-IP header that Charon sends to your app holds that visitor address. Set up the list on the Security page, or with CHARON_TRUSTED_PROXIES. See Trusted Proxies.
On a host that uses a country list, Charon also rewrites the X-Forwarded-For note it sends to your app. Your app then receives the visitor's address followed by the address of the proxy that passed it on.
Header Injection Prevention¶
Charon sanitizes incoming proxy headers before adding its own, preventing header injection attacks where malicious clients send fake forwarded headers.
IP Chain Verification¶
When multiple proxies exist, verify the entire X-Forwarded-For chain rather than trusting only the first or last IP.
Troubleshooting¶
| Issue | Likely Cause | Solution |
|---|---|---|
| Backend shows wrong IP | Headers not enabled | Enable proxy headers for host |
| Redirect loop | Backend doesn't trust X-Forwarded-Proto | Configure backend trust settings |
| Wrong URLs in emails | Missing X-Forwarded-Host trust | Enable host header forwarding |
Related¶
- Security Headers - Browser security headers
- SSL Certificates - HTTPS configuration
- Back to Features