mod_geoip2 Apache module
The mod_geoip2 module embeds GeoIP database lookups into the Apache web server. It is only capable of looking up the IP of a client that connects to the web server, as opposed to looking up arbitrary addresses.
This module works with Apache 2. Please use mod_geoip with Apache 1.
Installation
You may download the latest release of mod_geoip2 or get the latest development version from GitHub. See the included INSTALL
file in the tarball for installation details.
Overview
The mod_geoip2 module uses the libGeoIP library to look up geolocation information for a client as part of the http request process. This module is free software, and is licensed under the Apache license.
To compile and install this module, you must first install libGeoIP 1.4.3 or newer.
The mod_geoip2 module takes effect either during request header parsing phase or the post read request phase, depending on whether it is configured for server-wide use or for a specific location/directory.
When enabled, the module looks at the incoming IP address and sets some variables which provide geolocation information for that IP. The variables it set depend on the specific GeoIP database being used (Country, City, ISP, etc.). These variables can be set in either the request notes table, the environment or both depending on the server configuration.
Configuration
GeoIP configuration directives can be placed in either an .htaccess
file or in the main server config. After installing the module, make sure that
GeoIPEnable On
is set in your Apache configuration file. This will call the GeoIP Country database from its default location (e.g. /usr/local/share/GeoIP/GeoIP.dat)
If you want to specify options, for example to use a different database or to pass caching options, you can use the GeoIPDBFile
directive:
File and Caching Directives
GeoIPDBFile /path/to/GeoIP.dat [GeoIPFlag]
For example:
GeoIPDBFile /usr/local/share/GeoIP/GeoIP.dat MemoryCache
GeoIPDBFile /usr/local/share/GeoIP/GeoIPOrg.dat Standard
The default GeoIPFlag value is Standard, which does not perform any caching, but uses the least memory. To turn on memory caching use:
GeoIPDBFile /path/to/GeoIP.dat MemoryCache
The memory cache option can use a large amount of memory. We recommend that you use Memory Caching only for the smaller database files, such as GeoIP Country and GeoIP ISP.
Another MemoryCache option is MMapCache, which uses the the mmap
system call to map the database file into memory.
If you would like the API to check to see if your local GeoIP files have been updated, set the CheckCache
flag:
GeoIPDBFile /path/to/GeoIP.dat CheckCache
Before making a call to the database, geoip will check the GeoIP.dat file to see if it has changed. If it has it, then it will reload the file. With this option, you do not have to restart Apache when you update your GeoIP databases.
If you would like to turn on partial memory caching, use the IndexCache
flag:
GeoIPDBFile /path/to/GeoIP.dat IndexCache
The IndexCache option caches the most frequently accessed index portion of the database, resulting in faster lookups than StandardCache, but less memory usage than MemoryCache. This is especially useful for larger databases such as GeoIP Organization and GeoIP City. For the GeoIP Country, Region and Netspeed databases, setting the IndexCache option just causes the C API to use the MemoryCache.
Currently, multiple GeoIPFlags options can not be combined.
Enabling UTF-8 Output
You may change the output charset from ISO-8859-1 (Latin-1) to UTF-8 with this directive:
GeoIPEnableUTF8 On
By default mod_geoip2 sets variables in both the notes table and environment. For performance reasons you may want to set only the one you use. To do so, use the GeoIPOutput
configuration directive:
Output Variable Location
GeoIPOutput Notes # Sets the Apache notes table only
GeoIPOutput Env # Sets environment variables only
GeoIPOutput All # Sets both (default behaviour)
Proxy-Related Directives
By default, this module will simply look at the IP address of the client. However, if the client is using a proxy, this will be the address of the proxy. You can use the GeoIPScanProxyHeaders
directive to look at proxy-related headers.
GeoIPScanProxyHeaders On
When this is set, the module will look at several other sources for the IP address, in this order:
- The
HTTP_CLIENT_IP
environment variable (set by Apache). - The
HTTP_X_FORWARDED_FOR
environment variable (set by Apache). - The
X-Forwarded-For
for header (set by a proxy). - The
HTTP_REMOTE_ADDR
environment variable (set by Apache).
This module will use the first IP address it finds in one of these locations instead of the IP address the client connected from.
Some of these variables may contain a comma-separate list of IP addresses (when a client goes through multiple proxies). In this case, the default behavior is to use the first IP address. You can set the GeoIPUseLastXForwardedForIP
directive to use the last address instead:
GeoIPUseLastXForwardedForIP On
Output Variables
As noted above, these variables can be set in either the Apache request notes table, the environment, or both. The specific variables which are set depend on the database you are using.
GeoIP Country Edition Output Variables
Name | Description |
---|---|
GEOIP_ADDR | The address used to calculate the GeoIP output. |
GEOIP_CONTINENT_CODE | A two-character code for the continent associated with the IP address. The possible codes are:
|
GEOIP_COUNTRY_CODE | A two-character ISO 3166-1 country code for the country associated with the IP address. In addition to the standard codes, we may also return one of the following:
The US country code is returned for IP addresses associated with overseas US military bases. |
GEOIP_COUNTRY_NAME | The country name associated with the IP address. |
GeoIP Region Edition Output Variables
Name | Description |
---|---|
GEOIP_ADDR | The address used to calculate the GeoIP output. |
GEOIP_COUNTRY_CODE | A two-character ISO 3166-1 country code for the country associated with the IP address. In addition to the standard codes, we may also return one of the following:
The US country code is returned for IP addresses associated with overseas US military bases. |
GEOIP_REGION_NAME | The region name associated with the IP address. |
GEOIP_REGION | A two character ISO-3166-2 or FIPS 10-4 code for the state/region associated with the IP address. For the US and Canada, we return an ISO-3166-2 code. In addition to the standard ISO codes, we may also return one of the following:
We return a FIPS code for all other countries. We provide a CSV file which maps our region codes to region names. The columns are ISO country code, region code (FIPS or ISO), and the region name. |
GeoIP City Edition Output Variables
Name | Description |
---|---|
GEOIP_ADDR | The address used to calculate the GeoIP output. |
GEOIP_CONTINENT_CODE | A two-character code for the continent associated with the IP address. The possible codes are:
|
GEOIP_COUNTRY_CODE | A two-character ISO 3166-1 country code for the country associated with the IP address. In addition to the standard codes, we may also return one of the following:
The US country code is returned for IP addresses associated with overseas US military bases. |
GEOIP_REGION | A two character ISO-3166-2 or FIPS 10-4 code for the state/region associated with the IP address. For the US and Canada, we return an ISO-3166-2 code. In addition to the standard ISO codes, we may also return one of the following:
We return a FIPS code for all other countries. We provide a CSV file which maps our region codes to region names. The columns are ISO country code, region code (FIPS or ISO), and the region name. |
GEOIP_REGION_NAME | The region name associated with the IP address. |
GEOIP_CITY | The city or town name associated with the IP address. See our list of cities to see all the possible return values. This list is updated on a regular basis. |
GEOIP_METRO_CODE | The metro code associated with the IP address. These are only available for IP addresses in the US. MaxMind returns the same metro codes as the Google AdWords API. |
GEOIP_AREA_CODE | The telephone area code associated with the IP address. These are only available for IP addresses in the US. This output is deprecated, and may not reflect newer area codes. |
GEOIP_LATITUDE | The latitude associated with the IP address. The latitude and longitude are near the center of the most granular location value returned: postal code, city, region, or country. |
GEOIP_LONGITUDE | The longitude associated with the IP address. |
GEOIP_POSTAL_CODE | The postal code associated with the IP address. These are available for some IP addresses in Australia, Canada, France, Germany, Italy, Spain, Switzerland, United Kingdom, and the US. We return the first 3 characters for Canadian postal codes. We return the the first 2-4 characters (outward code) for postal codes in the United Kingdom. |
GeoIP ISP Edition Output Variables
Name | Description |
---|---|
GEOIP_ADDR | The address used to calculate the GeoIP output. |
GEOIP_ISP | The name of the ISP associated with the IP address. |
GeoIP Organization Edition Output Variables
Name | Description |
---|---|
GEOIP_ADDR | The address used to calculate the GeoIP output. |
GEOIP_ORGANIZATION | The name of the organization associated with the IP address. |
GeoIP Netspeed Edition Output Variables
Name | Description |
---|---|
GEOIP_ADDR | The address used to calculate the GeoIP output. |
GEOIP_NETSPEED | The network speed associated with the IP address. This can be one of the following values:
|
GeoIPv6 Edition (experimental) Output Variables
Name | Description |
---|---|
GEOIP_ADDR | The address used to calculate the GeoIP output. |
GEOIP_CONTINENT_CODE_V6 | A two-character code for the continent associated with the IP address. The possible codes are:
|
GEOIP_COUNTRY_CODE_V6 | A two-character ISO 3166-1 country code for the country associated with the IP address. In addition to the standard codes, we may also return one of the following:
The US country code is returned for IP addresses associated with overseas US military bases. |
GEOIP_COUNTRY_NAME_V6 | The country name associated with the IP address. |
Examples
Here are some examples of how you can use mod_geoip2.
Redirecting a client based on country
This example show you how to redirect a client based on the country code that GeoIP sets.
GeoIPEnable On
GeoIPDBFile /path/to/GeoIP.dat
# Redirect one country
RewriteEngine on
RewriteCond %{ENV:GEOIP_COUNTRY_CODE} ^CA$
RewriteRule ^(.*)$ http://www.canada.com$1 [R,L]
# Redirect multiple countries to a single page
RewriteEngine on
RewriteCond %{ENV:GEOIP_COUNTRY_CODE} ^(CA|US|MX)$
RewriteRule ^(.*)$ http://www.northamerica.com$1 [R,L]
Blocking a client based on country
This example show you how to block clients based on the country code that GeoIP sets.
GeoIPEnable On
GeoIPDBFile /path/to/GeoIP.dat
SetEnvIf GEOIP_COUNTRY_CODE CN BlockCountry
SetEnvIf GEOIP_COUNTRY_CODE RU BlockCountry
# ... place more countries here
Deny from env=BlockCountry
Allowing clients based on country
This example show you how to allow only clients from specific countries.
GeoIPEnable On
GeoIPDBFile /path/to/GeoIP.dat
SetEnvIf GEOIP_COUNTRY_CODE US AllowCountry
SetEnvIf GEOIP_COUNTRY_CODE CA AllowCountry
SetEnvIf GEOIP_COUNTRY_CODE MX AllowCountry
# ... place more countries here
Deny from all
Allow from env=AllowCountry
Server vs Directory context
All directives except GeoIPEnable are server config only, i.e., you type it only once per server config. Otherwise the latest wins.
<IfModule mod_geoip.c>
GeoIPEnable Off
GeoIPEnableUTF8 On
GeoIPOutput Env
GeoIPDBFile /usr/local/share/GeoIP/GeoIP.dat MemoryCache
GeoIPDBFile /usr/local/share/GeoIP/GeoIPCity.dat MemoryCache
GeoIPDBFile /usr/local/share/GeoIP/GeoIPOrg.dat MemoryCache
</IfModule>
GeoIPEnable is useful in server or directory context. For example:
GeoIP is only available for a specific location:
<IfModule mod_geoip.c>
GeoIPEnable Off
GeoIPEnableUTF8 On
GeoIPOutput Env
GeoIPDBFile /usr/local/share/GeoIP/GeoIP.dat MemoryCache
</IfModule>
# GeoIP information is avail only inside /xxx
<Location /geoip-enabled>
GeoIPEnable On
...
</Location>
<Location /other>
...
</Location>
GeoIP is available for all locations:
<IfModule mod_geoip.c>
GeoIPEnable On
GeoIPEnableUTF8 On
GeoIPOutput Env
GeoIPDBFile /usr/local/share/GeoIP/GeoIP.dat MemoryCache
</IfModule>
# This doesn't work, because it's already been enabled in the server-wide
# config!
<Location /geoip-enabled>
GeoIPEnable On
</Location>
<Location /geoip-disabled>
GeoIPEnable Off
</Location>
Memory Usage
Starting at mod_geoip2 version 1.2.1, all Apache child processes share the same database when you set the MemoryCache or MMapCache flag.
Memory usage is about the same as the database file size, no matter how many child processes Apache spawns. The only thing to remember is ask Apache to update if your database changes. Use the graceful restart option to do so without stopping Apache.
Performance
For improved performance, you may want to enable mod_geoip only for specific HTML pages. If you want to use the mod_geoip module site-wide, you may still be able to only use it for HTML pages and not images. To restrict the pages where mod_geoip2 is used, place the GeoIPEnable On
directive inside a , or directive, see: httpd.apache.org/docs/2.0/sections.html
Troubleshooting
If the module is not working, make sure that the httpd user (e.g. nobody) has read access to the GeoIP database file(s) you are using.
If the GeoIP variables do not show up please make sure that the client IP address is not on a private network such as 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16. GeoIP can only look up public IP addresses.