Install GeoIP2 NGINX Module on Rocky Linux, AlmaLinux, CentOS & RHEL

📅 Updated: January 28, 2026 (Originally published: May 15, 2019)

The GeoLite Legacy databases were discontinued in January 2019. All users should migrate to GeoLite2 databases, which are still available for free with monthly updates.

The GeoIP2 NGINX module enables geolocation-based access control, redirects, and logging. Install it from the GetPageSpeed repository on any RHEL-based system.

Install GeoIP2 NGINX Module

Step 1. Add GetPageSpeed Repository

For Rocky Linux, AlmaLinux, CentOS 8/9, or Fedora:

sudo dnf -y install https://extras.getpagespeed.com/release-latest.rpm

For CentOS/RHEL 7:

sudo yum -y install https://extras.getpagespeed.com/release-latest.rpm

Note: An active NGINX Extras subscription is required for RHEL-based systems. Fedora users have free access.

Step 2. Install NGINX and GeoIP2 Module

For Rocky Linux, AlmaLinux, CentOS 8/9, or Fedora:

sudo dnf install -y nginx nginx-module-geoip2

For CentOS/RHEL 7:

sudo yum install -y nginx nginx-module-geoip2

Step 3. Enable the Module

Add the following at the top of /etc/nginx/nginx.conf:

load_module modules/ngx_http_geoip2_module.so;

Reload NGINX:

sudo systemctl reload nginx

Download GeoLite2 Databases

The GeoIP2 module requires MaxMind database files. Install the database updater:

For Rocky Linux, AlmaLinux, CentOS 8/9:

sudo dnf install -y geoipupdate geoipupdate-cron

For CentOS/RHEL 7:

sudo yum install -y geoipupdate geoipupdate-cron

Configure MaxMind Account

1. Sign up for a MaxMind account (free)
2. Create a license key in your account settings
3. Edit /etc/GeoIP.conf:

AccountID YOUR_ACCOUNT_ID
LicenseKey YOUR_LICENSE_KEY
EditionIDs GeoLite2-Country GeoLite2-City

1. Download the databases:

sudo geoipupdate

The databases are saved to /usr/share/GeoIP/. The weekly cron job keeps them updated automatically.

Test Geolocation Lookup

Install the lookup tool and test:

sudo dnf install -y libmaxminddb-devel
mmdblookup --file /usr/share/GeoIP/GeoLite2-Country.mmdb --ip 8.8.8.8 country names en

Configure GeoIP2 in NGINX

Add the database configuration to your nginx.conf in the http block:

http {
    geoip2 /usr/share/GeoIP/GeoLite2-Country.mmdb {
        auto_reload 5m;
        $geoip2_metadata_country_build metadata build_epoch;
        $geoip2_data_country_code default=US country iso_code;
        $geoip2_data_country_name country names en;
    }

    geoip2 /usr/share/GeoIP/GeoLite2-City.mmdb {
        $geoip2_data_city_name default=London city names en;
    }

    # Pass to PHP-FPM
    fastcgi_param COUNTRY_CODE $geoip2_data_country_code;
    fastcgi_param COUNTRY_NAME $geoip2_data_country_name;
    fastcgi_param CITY_NAME    $geoip2_data_city_name;
}

Verify GeoIP2 Works

Add a temporary header to any server block:

add_header X-Country $geoip2_data_country_name;

Test with curl:

curl -IL https://example.com/

Look for x-country: Your Country Name in the response.

Use Cases

Whitelist Countries

Allow access only from specific countries:

map $geoip2_data_country_code $allowed_country {
    default no;
    CA yes;
    US yes;
}

server {
    if ($allowed_country = no) {
        return 403;
    }
}

Blacklist Countries

Block specific countries:

map $geoip2_data_country_code $blocked_country {
    default no;
    SG yes;
}

server {
    if ($blocked_country = yes) {
        return 403;
    }
}

Country-Specific Redirects

Redirect visitors to country-specific domains:

map $geoip2_data_country_code $redirect_domain {
    default no;
    SE 'se.example.com';
    CA 'ca.example.com';
}

server {
    server_name example.com;
    if ($redirect_domain != no) {
        return 302 https://${redirect_domain}$request_uri;
    }
}

Exclude IPs from Redirects

Allow developers to bypass country redirects:

geo $exclude_redirect {
    default no;
    1.2.3.4 yes;  # Developer IP
}

map $geoip2_data_country_code:$exclude_redirect $redirect_domain {
    default no;
    SE:no 'se.example.com';
    CA:no 'ca.example.com';
}

Log Country Codes

Add country codes to your access log:

log_format main
    '$remote_addr - $remote_user [$time_local] "$request" '
    '$status $body_bytes_sent "$http_referer" '
    '"$http_user_agent" $geoip2_data_country_code';

Country Codes Reference

Find two-letter country codes at the GeoNames country list.