What is the X-Forwarded-For header?
Definition
X-Forwarded-For is a de facto request header to which each proxy appends the address of the client it received the request from.
Anything that was already in the header when it reached your own proxy was written by someone you cannot check. That is the single fact worth remembering about it, and the easiest one to forget once the header is feeding logs, rate limits or access control.
Watching a proxy append to it
On 21 October 2026 we put Squid 6.13 in front of a local server that echoes the request headers it receives, then sent the same request three ways with curl 8.7.1. Only the relevant lines of each response are shown.
$ curl -s -x http://127.0.0.1:3139 http://127.0.0.1:8091/
Via: 1.1 squid-test (squid/6.13)
X-Forwarded-For: 127.0.0.1
$ curl -s -x http://127.0.0.1:3139 -H "X-Forwarded-For: 203.0.113.7" http://127.0.0.1:8091/
Via: 1.1 squid-test (squid/6.13)
X-Forwarded-For: 203.0.113.7, 127.0.0.1
$ curl -sk -x http://127.0.0.1:3139 -H "X-Forwarded-For: 203.0.113.7" https://127.0.0.1:8460/
X-Forwarded-For: 203.0.113.7
The second request shows the problem in one line. Squid kept the forged entry and appended the real address after it, so the leftmost value is whatever the client chose to type. The third went through a CONNECT tunnel to an HTTPS server. Squid never saw the header inside the tunnel, so it could neither add the real address nor remove the forgery.
What the proxy can be told to do
Squid’s forwarded_for directive controls the behaviour, and its default is on. We repeated the forged request under each setting:
forwarded_for |
Header the server received | Proxy-list label it would earn |
|---|---|---|
on (default) |
203.0.113.7, 127.0.0.1 |
Transparent: the client’s address is disclosed |
off |
203.0.113.7, unknown |
Anonymous: a proxy is visible, the client is not |
truncate |
127.0.0.1 |
Transparent, with the forged entry discarded |
delete, with via off |
No X-Forwarded-For and no Via | Elite or high anonymity |
Squid’s documentation adds a fifth value, transparent, which passes the header on unchanged. The labels in the last column come from proxy lists and checkers, not from any specification. They describe one configuration line on one server, which is why a transparent proxy in this sense has nothing to do with the networking meaning of the term.
Reading it on your own server
Count from the right. Each entry was appended by the hop that received the request from the address it records, so only the entries added by proxies you operate are observations. Strip those, take the next one, and treat everything further left as a claim. Using the leftmost value for rate limiting lets any client choose its own address.
nginx’s realip module does the counting for you, provided you tell it which peers to trust. This follows the module’s documentation; we did not run nginx for this entry.
set_real_ip_from 10.0.0.0/8; # your load balancers
real_ip_header X-Forwarded-For;
real_ip_recursive on; # walk from the right past trusted hops
With real_ip_recursive off, the default, nginx takes the last address in the header. Behind more than one of your own proxies, that is one of your proxies rather than the client. With it on, nginx skips trusted addresses from the right and uses the first one it does not trust.
RFC 7239 standardised the same idea as Forwarded, which can also record the protocol and the receiving interface. Its own conversion example turns X-Forwarded-For: 192.0.2.43, 2001:db8:cafe::17 into Forwarded: for=192.0.2.43, for="[2001:db8:cafe::17]", and it notes that the older header remains in wide use. A proxy may send both. The forgery problem is identical for both, since a client can send either one itself.
When you are the client
An HTTPS request through a proxy travels in a tunnel, and in a tunnel the proxy cannot add the header at all. What the destination sees is the exit address and nothing else from the proxy, as the guide explains under what the destination sees. Plain HTTP is different, so if any of your traffic is unencrypted, test that path separately against an echo service, with a control request made without the proxy. Verifying the exit address shows the commands.
Choose the echo service with care. Through the same Squid, httpbin.org’s /headers endpoint showed neither Via nor X-Forwarded-For, because its own front end removes them before the application sees the request. The only trace left was Cache-Control: max-age=259200, a header curl never sends. For what a client sends before any proxy touches it, see what HTTP clients send before you configure anything. The Via header is the standardised counterpart: it records the path, while X-Forwarded-For records the origin.