This FAQ details the few different use cases and configurations when using a proxy in Matomo (Piwik).

If Matomo is behind a reverse proxy

If you install Matomo, connecting through a reverse proxy (https-to-http), the following line should be automatically added to your config/config.ini.php file during the Matomo installation:

[General]
assume_secure_protocol = 1

If you install Matomo from behind the reverse proxy (where Matomo can’t detect https will be used), you should set the above manually. Also, depending on your proxy server, the Visitor IP is set in a different HTTP Header which should also be automatically detected on install and added to your config/config.ini.php:

[General]
; Uncomment line below if you use a standard proxy
;proxy_client_headers[] = HTTP_X_FORWARDED_FOR
;proxy_host_headers[] = HTTP_X_FORWARDED_HOST

; Uncomment line below if you use CloudFlare
;proxy_client_headers[] = HTTP_CF_CONNECTING_IP

; Uncomment line below if you use another proxy (that sets Client-IP header)
;proxy_client_headers[] = HTTP_CLIENT_IP

If Matomo was unable to detect your proxy configuration, you may add these lines manually in your Matomo config.ini.php file (remove the leading « ; » character to enable the setting).

Be aware that PHP applies some transforms to headers: uppercases them, prefixes HTTP_ and converts dashes to underscores. So if your reverse proxy is sending X-Forwarded-For, it should be entered in the config as HTTP_X_FORWARDED_FOR.

It is also possible to check multiple proxy_client_headers, which will be checked in order until a header value is found. For example, with the config below:

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

This 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. The array[] syntax is shorthand in PHP for array_push so adds to the existing array.

You can exclude internal IPs (e.g. LoadBalancer IPs) from being used from these headers using the proxy_ips[] config to exclude certain ranges of IP addresses. For example the following config will ignore commonly used internal IP address ranges:

proxy_ips[] = 192.168.*.*/16
proxy_ips[] = 10.40.*.*/16

It is also possible to debug this to list the exact details in the Matomo log file.

Notes:

  • If your server runs IIS reverse proxy, HTTP_X_FORWARDED_HOST needs to be added manually to « Allowed Server Variables » and added to the inbound rewrite rule and set to {HTTP_HOST} so that it passes through the original HTTP_HOST value provided by the client to Matomo. Learn more.

  • If you use Apache 2.4 or Apache 2.5, there is an alternative solution, you could use mod_remoteip to override the client IP with the IP as provided by a proxy or load balancer. Then you won’t need to specify these Matomo config settings.

If Matomo is behind a reverse proxy and installed in a sub-path

If you’re using Matomo behind a reverse proxy with a different path such as rewrite ^/piwik/(.*)$ /$1 break; (in nginx.conf when Matomo is installed in the /piwik path), you would need to:

1) configure your web server to provide a header HTTP_X_FORWARDED_URI. For example on NGINX, when Matomo is installed in /piwik path, you would set proxy_set_header X-Forwarded-Uri /piwik; in your nginx.conf.
2) configure Matomo to read this HTTP_X_FORWARDED_URI to construct correct URLs. In Matomo config/config.ini.php in the [General] section add:

 [General]
 ; Use the header HTTP_X_FORWARDED_URI to construct the current script name
 proxy_uri_header = 1

Matomo is behind an outgoing proxy

If your server is configured behind an outgoing proxy, check out this FAQ: outgoing Proxy easy setup in Matomo.

You might also be interested in…