2024-01-11 | HowTo

NginX GeoIP Setup Guide

To expose GeoIP headers in Nginx similar to how Cloudflare does, you'll need to use the ngx_http_geoip2_module (or the older ngx_http_geoip_module) along with MaxMind's GeoIP2 database. This guide walks through configuring Nginx to inject GeoIP headers into requests so your PHP app can access them.

1. Install Dependencies

You'll need the geoip2 module and the MaxMind GeoIP database.

Debian/Ubuntu

sudo apt update
sudo apt install nginx libnginx-mod-http-geoip2 mmdb-bin

CentOS/RHEL

sudo yum install epel-release
sudo yum install nginx nginx-mod-http-geoip2

Alternatively, if you're compiling Nginx from source, include the module:

./configure --add-module=/path/to/ngx_http_geoip2_module
make && make install

2. Download and Install the GeoIP Database

MaxMind requires a free account to download their GeoLite2 database.

mkdir -p /usr/share/GeoIP
cd /usr/share/GeoIP
wget https://github.com/P3TERX/GeoLite.mmdb/raw/download/GeoLite2-Country.mmdb
wget https://github.com/P3TERX/GeoLite.mmdb/raw/download/GeoLite2-City.mmdb

Alternatively, use the official MaxMind API:

curl -L -O "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=YOUR_LICENSE_KEY&suffix=tar.gz"
tar -xvzf GeoLite2-City.tar.gz --strip-components=1

3. Configure Nginx to Inject GeoIP Headers

Edit your Nginx configuration, typically found at /etc/nginx/nginx.conf or inside /etc/nginx/conf.d/default.conf.

Add this inside the http block:

geoip2 /usr/share/GeoIP/GeoLite2-Country.mmdb {
    $geoip2_country_code country iso_code;
    $geoip2_country_name country names en;
}

geoip2 /usr/share/GeoIP/GeoLite2-City.mmdb {
    $geoip2_city_name city names en;
    $geoip2_region region subdivisions 0 names en;
    $geoip2_latitude location latitude;
    $geoip2_longitude location longitude;
}

map $geoip2_country_code $cf_country {
    default $geoip2_country_code;
}

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_set_header CF-IPCountry $cf_country;
        proxy_set_header X-Geo-Country $geoip2_country_code;
        proxy_set_header X-Geo-City $geoip2_city_name;
        proxy_set_header X-Geo-Region $geoip2_region;
        proxy_set_header X-Geo-Latitude $geoip2_latitude;
        proxy_set_header X-Geo-Longitude $geoip2_longitude;

        fastcgi_pass unix:/run/php/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

4. Restart Nginx

sudo systemctl restart nginx

5. Verify Headers in PHP

Create a simple PHP script (geo_test.php) to check if the headers are set:

<?php
echo "<pre>";
print_r($_SERVER);
echo "</pre>";
?>

Access http://yourdomain.com/geo_test.php and look for:

[HTTP_CF_IPCOUNTRY] => US
[HTTP_X_GEO_COUNTRY] => US
[HTTP_X_GEO_CITY] => Los Angeles
[HTTP_X_GEO_REGION] => California
[HTTP_X_GEO_LATITUDE] => 34.0522
[HTTP_X_GEO_LONGITUDE] => -118.2437

This setup replicates Cloudflare’s GeoIP headers locally. You can now use $_SERVER['HTTP_CF_IPCOUNTRY'] or similar in your PHP app.