GeoIP2 (HTTP)

Install

Make sure you have the official nginx.org repository configured first. These packages require nginx from nginx.org, not the distro-bundled version.

Add the Blendbyte repository if you haven't already:

sudo install -d -m 0755 /etc/apt/keyrings

curl -fsSL https://apt.blendbyte.net/nginx/blendbyte-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/blendbyte.gpg >/dev/null

echo "deb [signed-by=/etc/apt/keyrings/blendbyte.gpg] https://apt.blendbyte.net/nginx $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/blendbyte.list

sudo apt update

Then install this module:

$ sudo apt install nginx-module-geoip2

Most modules auto-enable on install. If yours didn't, enable it manually:

$ sudo ln -s /etc/nginx/modules-available/50-mod-geoip2.conf \
  /etc/nginx/modules-enabled/
$ sudo nginx -t && sudo systemctl reload nginx

What it does

The GeoIP2 module reads MaxMind's binary database format and exposes geographic data as nginx variables. Country code, country name, city, continent, ASN: all available as $geoip2_* variables in your nginx config. Use them in access rules, upstream selection, conditional headers, logging, or rate limiting. The MaxMind GeoLite2 databases are free with a MaxMind account and updated weekly; paid databases offer higher accuracy. This is the HTTP module. It works in http {} and server {} blocks. If you need GeoIP2 lookups in TCP/UDP stream proxying, you want nginx-module-stream-geoip2.

When to use it

• Block or redirect traffic by country code in nginx access rules
• Route users to geographically close backend servers
• Serve localised content or different landing pages by region
• Restrict admin panels to specific countries
• Log geographic data alongside standard access logs

Configuration

A starting-point configuration. Adjust to your setup.

# geoip2 and map go in your http {} block; use the variables in server/location:
geoip2 /var/lib/GeoIP/GeoLite2-Country.mmdb {
  $geoip2_country_code country iso_code;
  $geoip2_country_name country names en;
}

map $geoip2_country_code $blocked_country {
  default 0;
  XX      1;
  YY      1;
}

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

# If you were using Sury, this upgrades in place:
sudo apt install nginx-module-geoip2

Upstream project

This module is packaged from the upstream open-source project. Bug reports about module behaviour (not packaging) should go upstream.

https://github.com/leev/ngx_http_geoip2_module ↗