ngx_stream_geoip_module

Client country and city variables for stream servers

dynamic moduleBSD-2-Clausesource docs

Overview

ngx_stream_geoip_module (1.11.3) creates variables whose values depend on the client IP address, looked up in the precompiled legacy MaxMind databases. geoip_country provides $geoip_country_code, $geoip_country_code3 and $geoip_country_name, geoip_city adds region, city, postal code, continent and coordinates, and geoip_org provides $geoip_org.

The directives are set once in the stream context and the variables are then available in every stream server, most often through a map that picks an upstream by $geoip_country_code or $geoip_city_continent_code. With IPv6-enabled databases, IPv4 clients are looked up as IPv4-mapped IPv6 addresses. The legacy GeoIP databases it reads have been discontinued by MaxMind, so new deployments should use the GeoIP2 module at /modules/geoip2/ instead.

It is an official nginx module that upstream does not build by default; it needs --with-stream_geoip_module and the MaxMind GeoIP library. The n.wtf packages build it as a dynamic module shipped in libnginx-mod-stream-geoip, which depends on libnginx-mod-stream and is pulled in by the nginx-extras metapackage. The typical use is steering TCP sessions to the nearest region while an existing legacy database is still in service.

Key directives

geoip_countryDatabase file used to determine the country of the client address; stream context only.

geoip_cityDatabase file that yields country, region, city, postal code, continent code, latitude and longitude.

geoip_orgDatabase file that sets $geoip_org to the organization name for the client address.

$geoip_country_codeTwo-letter country code such as US or DE; $geoip_country_code3 gives the three-letter form.

$geoip_city_continent_codeTwo-letter continent code such as EU or NA from the city database, handy for choosing a regional upstream.

Example

nginx.conf

stream { geoip_country /usr/share/GeoIP/GeoIP.dat; # send clients to a regional backend by country map $geoip_country_code $backend { default us.example.com:12345; DE eu.example.com:12345; FR eu.example.com:12345; JP ap.example.com:12345; } server { listen 12345; proxy_pass $backend; } }

Availability

Ships as a dynamic module in libnginx-mod-stream-geoip, installed with nginx-extras. The package drops a load_module config into /etc/nginx/modules-enabled/, so it loads on start.