				mod_geoip 1.2.6
				---------------

======== OVERVIEW =========

mod_geoip is an Apache module for finding the country that a web request
originated from.  It uses the GeoIP library and database to perform
the lookup.  It is free software, licensed under the Apache license.
It requires the C API, version 1.3.4 and above, see:
http://www.maxmind.com/app/c

======== USAGE ============

To use, see the instructions in INSTALL on how to install the module,
then make sure that

  GeoIPEnable On

is set in your Apache configuration file.

If you want to specify the a non-default location for the database file(s),
use

  GeoIPDBFile /path/to/GeoIP.dat

For example

GeoIPDBFile /usr/local/share/GeoIP/GeoIP.dat MemoryCache
GeoIPDBFile /usr/local/share/GeoIP/GeoIPOrg.dat Standard

GeoIP Country Edition:
You can retrieve the ISO 3166 Country code from the Apache notes table
under the "GEOIP_COUNTRY_CODE" key, or from the environment variable
"GEOIP_COUNTRY_CODE".  It also sets the GEOIP_COUNTRY_NAME note and
environment variable.

GeoIP Region Edition:
Sets GEOIP_COUNTRY_CODE and GEOIP_REGION

GeoIP City Edition:
Sets GEOIP_COUNTRY_CODE, GEOIP_REGION, and GEOIP_CITY, GEOIP_DMA_CODE,
	GEOIP_AREA_CODE, GEOIP_LATITUDE, GEOIP_LONGITUDE, GEOIP_POSTAL_CODE

GeoIP ISP Edition:
Sets GEOIP_ISP
(Note to ISP edition subscribers, requires non-standard database - contact support@maxmind.com
for details)

GeoIP Organization Edition:
Sets GEOIP_ORGANIZATION

GeoIP Netspeed Edition:
Sets GEOIP_NETSPEED

By default it sets both the notes table and environment variable.
For performance reasons you may want to only set the one you use, to
do so use the "GeoIPOutput" configuration directive:

  GeoIPOutput Notes   # Sets Apache notes table only
  GeoIPOutput Env     # Sets Environmental Variable only
  GeoIPOutput All     # Sets both (current default behaviour)

By default it uses GEOIP_STANDARD mode, which does not perform
any memory caching (it is the most memory efficient).  To turn
on memory caching (warning can be memory intensive since
it is used across all Apache children) use:

  GeoIPFlags MemoryCache

We recommend that you use Memory Caching only for the smaller
database files, such as GeoIP Country and GeoIP ISP.

If you would like to enable checking for updates in the memory cache, use

  GeoIPFlags CheckCache

Before making a call to the database, geoip will check the GeoIP.dat file
to see if there is an updated database before making the call.  This way
you shouldn't have to restart the Apache server after updating the GeoIP
data files.

========= redirection with mod_geoip and mod_rewrite ========

Below is an example of how to do redirection with mod_geoip and
mod_rewrite:

GeoIPEnable On
GeoIPDBFile /path/to/GeoIP.dat

RewriteEngine on
RewriteCond %{ENV:GEOIP_COUNTRY_CODE} ^CA$
RewriteRule ^(.*)$ http://www.canada.com [L]

======== Blocking unwanted countries ==========

# note this code is untested - please send any feedback to support@maxmind.com

# This blocks traffic from China and Russia

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

========= notes ===========

We have received feedback that suexec cleans environment variables that
it deems to be unsafe, including the variables mod_geoip sets.  One workaround
is to modify mod_geoip.c to set HTTP_GEOIP_COUNTRY_CODE and HTTP_GEOIP_COUNTRY_NAME
instead of GEOIP_COUNTRY_CODE and GEOIP_COUNTRY_NAME.  We would like to handle
this more cleanly, comments welcome.

Also we have received reports of segfaults when using the GeoIP configuration
directives in .htaccess.  Removing the GeoIPEnable, etc from .htaccess and
placing it in httpd.conf fixes the problem.  Not sure why there is an issue
with .htaccess, comments and suggestions welcome.

We have also received reports of segfaults when using the redirect rule
with R.  Changing from R to L fixes the problem.

========= proxies =========

If you have a backend server in front of a proxy server, and the client IP is in
the HTTP_X_FORWARDED_FOR variable, then use

GeoIPXForwardedFor On

Note that if your proxy appends IP addresses so that the HTTP_X_FORWARDED_FOR may
contain multiple IP address separated by commas, the lookup will fail.  Patches
welcome.  Also we need to generalize this so it can pick up on HTTP_CLIENT_IP
and others.

========= contact =========

Please send any comments or suggestions to support@maxmind.com
