NGINX GeoIP: The Complete Guide

Introduction

NGINX is a high-performance web server that also works as a reverse proxy, load balancer, and HTTP cache. One of its many powerful extensions is the GeoIP module which allows you to configure NGINX to use the geographic location of a client when processing requests. This functionality is useful for a variety of reasons including content personalization, targeted advertising, restricted content, or security measures.

In this comprehensive guide, we will discuss what NGINX GeoIP is, how you can set it up, and utilize it effectively. We’ll go through installing the GeoIP databases, configuring NGINX to use them, and writing rules based on location data. We’ll also cover some advanced use cases and troubleshooting tips.

Prerequisites

• An operating system running Linux.
• NGINX installed on your server. If it’s not installed, you should follow official NGINX installation guidelines.
• Basic knowledge of Linux servers and terminal commands.

Installing the GeoIP Module

To work with GeoIP, NGINX must be compiled with the GeoIP module. Depending on your Linux distribution, this might already be included or you might have to compile NGINX from source with the GeoIP flag. On a Debian-based system, you can install the module using the following commands:

sudo apt-get update
sudo apt-get install libnginx-mod-http-geoip

Installing GeoIP Databases

MaxMind provides GeoLite2 databases for free, which you can use with the GeoIP module.

cd /usr/share/GeoIP/
wget http://geolite.maxmind.com/download/geoip/database/GeoLite2-Country.tar.gz
wget http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.tar.gz
tar -xvzf GeoLite2-Country.tar.gz
tar -xvzf GeoLite2-City.tar.gz

Note that these URLs may change and MaxMind now requires you to register an account before downloading the databases due to latest privacy policies.

After downloading the databases, you will need to configure NGINX to use them. This is done within your NGINX configuration file (typically called nginx.conf).

Configuring NGINX

The GeoIP module provides multiple directives for configuration. Add these directives within the http block of your nginx.conf:

geoip_country /usr/share/GeoIP/GeoLite2-Country.mmdb;
geoip_city /usr/share/GeoIP/GeoLite2-City.mmdb;

With this configuration in place, NGINX has access to the GeoIP databases and can retrieve location data about clients.

Using GeoIP data in NGINX

Let’s look into how you can use GeoIP data to restrict access to your website from certain countries. In your server block or within a specific location block, you need to set up a condition to test the client’s country:

if ($geoip_country_code != 'US') {
    return 403;
}

This rule will block all traffic not originating from the United States by returning a 403 Forbidden status code.

Advanced Usage

Advanced configurations may involve setting up variables for use in NGINX logs, rewriting URLs based on country codes, or implementing more complex conditions for security purposes.

map $geoip_country_code $allowed_country {
    default no;
    US yes;
}

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

This map block creates a variable based on the country code and then the if block uses this variable to control access.

Testing Your Configuration

Use the nginx -t command to test your configuration for syntax errors. Once there are no errors detected, you can safely reload NGINX to apply the changes.

sudo nginx -t 
sudo systemctl reload nginx

GeoIP Directives and Variables

The GeoIP module offers a variety of directives and variables that you can use in your NGINX configuration. Some useful variables include:

• $geoip_country_code: ISO country code
• $geoip_country_name: Country name
• $geoip_city_country_code: City ISO country code
• $geoip_city_country_name: City name

You can consult the official NGINX documentation for a complete list of GeoIP directives and their descriptions.

Debugging and Troubleshooting

If you are encountering issues with the GeoIP module, first check your NGINX error log for clues:

sudo tail /var/log/nginx/error.log

Ensure that the paths to your GeoIP databases are correct and that the database files are not corrupted. Additionally, make certain that all GeoIP directives are placed correctly in the http or server block of your NGINX configuration file.

Conclusion

By leveraging the power of GeoIP with NGINX, you can enhance your web server’s capabilities and tailor content or security measures according to the geographic location of your visitors. This tutorial guides you through installing and configuring NGINX to use GeoIP, alongside some practical examples and troubleshooting steps for common problems.