How do I configure Matomo when the server is installed behind a proxy?
This FAQ details the few different use cases and configurations when using a proxy in Matomo.
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
It is highly recommended that when you configure this setting, you also add force_ssl:
[General]
force_ssl = 1 ;please add this as well
assume_secure_protocol = 1 ;if you add this
It will ensure your emails are sent with https:// links as well as ensure all other secure content settings related to SSL (https://) work as expected.
In particular, all http:// links will be redirected to https://. See Force Matomo to use SSL for more information.
Set visitor IP via HTTP Headers from Reverse Proxy (Including Cloudflare)
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.
Security consideration
From version 5, Matomo will read the last IP from the proxy header by default. This improves protection from spoofed X-Forwarded-For headers, for example a custom X-Forwarded-For header sent by the client to fake an IP address. This could be used to pretend to have an IP from your organisation and bypass specific allow or deny lists of IP addresses.
Earlier Matomo versions followed the RFC7239 implementation and always read the first IP from a proxy header.
Depending on your set up, you may prefer to change this behaviour to read the first or the last IP by setting below configuration.
[General]
proxy_ip_read_last_in_list = 0
This configuration option is available in Matomo 4.4 or newer.
If after upgrading to Matomo 5 you’re seeing visits with local IP addresses then you may need to set proxy_ip_read_last_in_list = 0
Notes
-
If your server runs IIS reverse proxy,
HTTP_X_FORWARDED_HOSTneeds 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_remoteipto 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 ^/matomo/(.*)$ /$1 break; (in nginx.conf when Matomo is installed in the /matomo 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 /matomo path, you would set proxy_set_header X-Forwarded-Uri /matomo; 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.