FAQ

Page Discussion History

HttpGeoipModule

(Redirected from HttpGeoIPModule)


WARNING: this article is obsoleted. Please refer to http://nginx.org/en/docs/ for the latest official documentation.

Contents

Synopsis

This module creates ngx_http_geoip_module variables based on the IP-address of the client matched against the MaxMind GeoIP binary files. This module appeared in nginx version 0.7.63 and 0.8.6.

Precondition

This module needs the geo databases and the library to read from the database.

There are several options:

  • Download the database yourself, e.g.:
  wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz
  
  • Install a package providing the database. For example in Debian the package is called geoip-database.
  aptitude install geoip-database
  
  • Install a port providing the database. For example in FreeBSD the port is called "GeoIP".
  cd /usr/ports/net/GeoIP
  make install clean
  

The FreeBSD port provides the GeoLite country database located at /usr/local/share/GeoIP/GeoIP.dat

Note that this is only the country database. You'll need to download the city database from Maxmind site:

wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz

To compile Nginx you'll need the library development files. In Debian they're in the package libgeoip-dev.

aptitude install libgeoip-dev

For systems where there's not a packaged version of the library you'll have to compile it from source:

wget http://geolite.maxmind.com/download/geoip/api/c/GeoIP.tar.gz

Follow the install instructions provided there.

Compile Nginx enabling Geo IP support:

./configure --with-http_geoip_module

You can check if your installed version of Nginx supports Geo IP with nginx -V. Watch for the --with-http_geoip_module. This means that Geo IP support is enabled.

Here'a a configuration example:

http {
    geoip_country  GeoIP.dat; # the country IP database
    geoip_city     GeoLiteCity.dat; # the city IP database
    (...)

You can mimic Apache's mod_geoip functionality with PHP-FPM by adding the following fastcgi_param values:

(From Mimic Apache mod_geoip in Nginx)

	fastcgi_param GEOIP_COUNTRY_CODE $geoip_country_code; 
	fastcgi_param GEOIP_COUNTRY_NAME $geoip_country_name;

Directives

geoip_country

Syntax: geoip_country file
Default:
Context: http
Reference:geoip_country


This directive specifies the full path to the Geo IP database .dat file that associates IP addresses with country geolocation information. This allows you to get the country corresponding to the given IP. It can be used to determine the visitor's country from the IP address of the client. When set the following variables are available:

  • $geoip_country_code — two-letter country code, for example, "RU", "US".
  • $geoip_country_code3 — three-letter country code, for example, "RUS", "USA".
  • $geoip_country_name — the (verbose) name of the country, for example, "Russian Federation", "United States", &c.

Nginx caches all supplied databases in memory. The country database is small, roughly 1.4M, therefore there's very little penalty in caching it. The city database is much bigger. Hence its memory footprint is larger.

geoip_city

Syntax: geoip_city file
Default:
Context: http
Reference:geoip_city


This directive specifies the full path to the Geo IP database .dat file that associates IP addresses with country, city and region geolocation information. This allows you to get that information corresponding to the given IP. It can be used to determine the visitor's geolocation from the IP address of the client. When set the following variables are available:

  • $geoip_city_country_code — two-letter country code, for example, "RU", "US".
  • $geoip_city_country_code3 — three-letter country code, for example, "RUS", "USA".
  • $geoip_city_country_name — the name of the country, for example, "Russian Federation", "United States" — if available.
  • $geoip_region — the name of region (province, region, state, province, federal land, and the like), for example, "Moscow City", "DC" — if available.
  • $geoip_city — the name of the city, for example, "Moscow", "Washington", "Lisbon", &c — if available.
  • $geoip_postal_code — zip code or postal code — if available.
  • $geoip_city_continent_code — if available.
  • $geoip_latitude — latitude — if available.
  • $geoip_longitude — longitude — if available.
  • $geoip_dma_code — DMA Code — if available.
  • $geoip_area_code — Area Code — if available.

geoip_proxy

Syntax: geoip_proxy address | CIDR
Default:
Context: http
Appeared in: 1.3.0
1.2.1
Reference:geoip_proxy


geoip_proxy_recursive

Syntax: geoip_proxy_recursive on | off
Default: off
Context: http
Appeared in: 1.3.0
1.2.1
Reference:geoip_proxy_recursive


References

Original Documentation