Configuring IP Whitelist/Blacklist and Geo‑Based Access Control in Nginx

IP Whitelist/Blacklist Access Configuration

Nginx offers several ways to restrict access by IP. Two common methods are demonstrated.

1. Using allow and deny directives

The allow and deny directives belong to the ngx_http_access_module , which is loaded by default.

Example of a simple whitelist/blacklist directly in the configuration file:

# Whitelist example
location / {
    allow 123.13.123.12;
    allow 23.53.32.1/100;
    deny all;
}

# Blacklist example
location / {
    deny 123.13.123.12;
}

# Whitelist for a specific directory
location /tree/list {
    allow 123.13.123.12;
    deny all;
}

You can also include an external file that contains the whitelist IPs:

location / {
    include /home/whitelist.conf;
    deny all;
}

Contents of /home/whitelist.conf :

# Whitelist IPs
allow 10.1.1.10;
allow 10.1.1.11;

2. Using ngx_http_geo_module

The ngx_http_geo_module (usually compiled in) allows IP‑based or country‑based restrictions. The configuration must be placed in the http context, outside any server block.

Simple IP list example:

geo $ip_list {
    default 0;
    192.168.1.0/24 1;
    10.1.0.0/16    1;
}
server {
    listen 8081;
    server_name 192.168.152.100;
    location / {
        root /var/www/test;
        if ($ip_list = 0) {
            proxy_pass http://192.168.152.100:8081;
        }
    }
}

The same module can read IP lists from a file:

geo $ip_list {
    default 0;
    include ip_white.conf;
}
server {
    listen 8081;
    server_name 192.168.152.100;
    location / {
        root /var/www/test;
        if ($ip_list = 0) {
            return 403;  /* deny access */
        }
    }
}

After creating /etc/nginx/ip_list.conf with the desired IPs, Nginx will treat those as the whitelist; all others receive a 403 response.

3. Extending ngx_http_geo_module for Load Balancing

The module can also direct traffic to different upstream groups based on IP ranges or custom labels (e.g., country codes).

geo $country {
    default default;
    111.11.11.0/24 uk;
    111.11.12.0/24 us;
}
upstream uk.server { server 122.11.11.11:9090; }
upstream us.server { server 133.11.12.22:9090; }
upstream default.server { server 144.11.11.33:9090; }
server {
    listen 9090;
    server_name 144.11.11.33;
    location / {
        root /var/www/html/;
        index index.html index.htm;
    }
}

Country/Region IP Restriction

Third‑party services like Cloudflare can also enforce geographic blocks, but this section focuses on native Nginx solutions.

1. Installing ngx_http_geoip_module

On Ubuntu, install the nginx-extras package which includes most modules:

sudo apt install nginx-extras

On CentOS, install the GeoIP module directly:

yum install nginx-module-geoip

2. Downloading IP Databases

The module requires MaxMind’s IP database (dat format). Although MaxMind no longer provides new dat files, legacy versions can be obtained from third‑party sources.

# Download country database
sudo wget https://dl.miyuru.lk/geoip/maxmind/country/maxmind.dat.gz
gunzip maxmind.dat.gz
sudo mv maxmind.dat /etc/nginx/GeoCountry.dat

# Download city database
sudo wget https://dl.miyuru.lk/geoip/maxmind/city/maxmind.dat.gz
gunzip maxmind.dat.gz
sudo mv maxmind.dat /etc/nginx/GeoCity.dat

3. Configuring Nginx with GeoIP

Example configuration that blocks access from China (country code CN):

geoip_country /etc/nginx/GeoCountry.dat;
geoip_city    /etc/nginx/GeoCity.dat;

server {
    listen 80;
    server_name 144.11.11.33;
    location / {
        root /var/www/html/;
        index index.html index.htm;
        if ($geoip_country_code = CN) {
            return 403;  # deny Chinese IPs
        }
    }
}

Additional GeoIP variables such as $geoip_country_name , $geoip_city , and latitude/longitude are also available for more granular logic.

Reference

[1] ngx_http_geo_module documentation: https://nginx.org/en/docs/http/ngx_http_geo_module.html

[2] ngx_http_geoip_module documentation: https://nginx.org/en/docs/http/ngx_http_geoip_module.html