http-ipdb

Client geolocation variables from ipip.net IPDB files

dynamic moduleGPL-2.0source

Overview

ngx_http_ipdb_module looks up the client address in an IPDB database file from ipip.net and exposes the result as nginx variables. It covers country, region, city, ISP, coordinates, timezone, and currency fields, each available as its own $ipdb_* variable.

Operators use it the same way as a GeoIP module: route or block traffic by location, pass geolocation headers to upstreams, or log where requests come from. IPDB data is notably detailed for networks in China, which is the common reason to pick it over MaxMind databases.

The module can resolve the real client address behind trusted proxies before the lookup. n.wtf builds this module from source in its own packaging; it is not part of the Debian nginx module set.

Key directives

ipdbSets the path to the IPDB database file and enables the lookup for the http block.

ipdb_languageSelects the result language, EN or CN, per http, server, or location context.

ipdb_proxyDeclares a trusted proxy address or CIDR so the lookup uses the address from X-Forwarded-For instead.

ipdb_proxy_recursiveWalks the X-Forwarded-For chain past multiple trusted proxies to find the original client address.

$ipdb_* variablesPer-request lookup results such as $ipdb_country_name, $ipdb_city_name, $ipdb_isp_domain, and the full record in $ipdb_raw.

Example

nginx.conf

load_module modules/ngx_http_ipdb_module.so; http { ipdb /etc/nginx/ipdb/city.free.ipdb; ipdb_language EN; server { listen 80; location / { proxy_set_header X-Country $ipdb_country_name; proxy_set_header X-City $ipdb_city_name; proxy_pass http://backend; } } }

Availability

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