Could we add to the documentation how X-Forwarded-For type headers are transformed for when you want to set them up in config.ini.php when using proxy_client_headers?

Namely that the following transforms take place for the HTTP Header name:

• Header names are uppercased
• Header names are prefixes with HTTP_
• Dashes are converted to underscores

So if your server is sending X-Forwarded-For (like mod_proxy does for Apache for example) then this should be entered in the config as HTTP_X_FORWARDED_FOR.

Additionally it is possible to have multiple proxy_client_headers and they should be added to the config in order of preference. For example:

proxy_client_headers[] = HTTP_WAF_FORWARDED_FOR
proxy_client_headers[] = HTTP_LB_FORWARDED_FOR
proxy_client_headers[] = HTTP_X_FORWARDED_FOR

Means first try the HTTP_WAF_FORWARDED_FOR header and if that doesn’t exist, then try the HTTP_LB_FORWARDED_FOR and if neither exists then finally try HTTP_X_FORWARDED_FOR.

Within these, it is possible to have multiple IPs. The IPs are are used in reverse order and you can use proxy_ips config to exclude known IPs.

So if you have the following headers:

X-Forwarded-For: 123.456.78.9, 192.168.10.20
X-LB-Forwarded-For: 123.456.78.9

And the following set up in config.ini.php:

[General]
; Uncomment line below if you use a standard proxy
proxy_client_headers[] = HTTP_X_FORWARDED_FOR
proxy_client_headers[] = HTTP_LB_FORWARDED_FOR
proxy_ips[] = 192.168.*.*/16
proxy_ips[] = 10.40.*.*/16

Then it would first look at HTTP_X_FORWARDED_FOR and start at the right-most IP (192.168.10.20), which would be discarded as matches the proxy_ips[]. Next it would move left and find 123.456.78.9 which is what would be selected as the real ip.

It’s also possible to debug this to list all these details in the Matomo log file.

Some or all of this may be obvious to regular PHP developers (or regular Matomo administrators) but just spent quite a bit of time getting this setup on my server and I feel the documentation could be improved here to prevent future people making the same mistakes I initially did.