NGINX GeoIP2 module

NGINX module which creates variables with values from the MaxMind geoip2 databases based on the client IP (default) or from a specific variable (supports both IPv4 and IPv6).

For senior sysadmins and SREs, this module helps in identifying client location data for request handling and logging.

Why use this module

• Retrieve geographical information based on client IP addresses.
• Support for both IPv4 and IPv6 addresses.
• Automatic reloading of GeoIP2 databases when they change.
• Trusted proxy support for accurate client IP detection.
• Integration with both HTTP and Stream modules in NGINX.

Directives

• geoip2
• auto_reload
• geoip2_proxy
• geoip2_proxy_recursive

Quick start

To use the GeoIP2 module, ensure you have the ngx_http_geoip2_module.so dynamic module available and load it in your nginx.conf:

load_module modules/ngx_http_geoip2_module.so;

http {
    geoip2 /etc/maxmind-country.mmdb {
        auto_reload 5m;
        $geoip2_data_country_code default=US source=$remote_addr country iso_code;
        $geoip2_data_country_name country names en;
    }

    server {
        location / {
            fastcgi_param COUNTRY_CODE $geoip2_data_country_code;
            fastcgi_param COUNTRY_NAME $geoip2_data_country_name;
        }
    }
}

When NOT to use this module

• If you do not require geographical data for your application, adding this module introduces unnecessary complexity.
• For environments where database updates are not feasible, as the module relies on up-to-date MaxMind databases for accuracy.

See also

• Examples
• Troubleshooting
• Related modules