				mod_geoip2 1.1.8
				----------------

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

mod_geoip2 is an Apache 2.0 module for finding the country and city
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

For the Apache 1.3 mod_geoip module, see:
http://www.maxmind.com/download/geoip/api/mod_geoip/

======== 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.  If GeoIP does not determine the country
for an IP address (for example if the IP address is missing
or is a private IP address), then it will not set the
GEOIP_COUNTRY_CODE and GEOIP_COUNTRY_NAME variables.

GeoIP Region Edition:
Sets GEOIP_COUNTRY_CODE and GEOIP_REGION

GeoIP City Edition:
Sets GEOIP_COUNTRY_CODE, GEOIP_REGION, 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 new format)

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 GeoIP updates, 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.

If you would like to turn on partial memory caching, use:

  GeoIPFlags 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 - useful for larger databases such as
GeoIP Organization and GeoIP City.  Note, for GeoIP Country, Region
and Netspeed databases, IndexCache is equivalent to MemoryCache.

Currently, multiple GeoIPFlags options can not be combined.  This
can be fixed by changing geoip_set_filename to ITERATE2, patches welcome.

========= 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 \.(gif|jpg|png|css)$ - [L] # don't redirect images and stylesheets
RewriteRule ^(.*)$ http://www.canada.com [L] # redirect everything else

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

# 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

# Optional - use if you want to allow a specific IP address from the country you denied
# See http://httpd.apache.org/docs/1.3/mod/mod_access.html for more details
# Allow from 10.1.2.3

========= performance =====

For improved performance, you may want to only enable mod_geoip
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_geoip is used,
place the GeoIPEnable on and associated directives inside a
<Location>, <Files> or <FilesMatch> directive, see:
http://httpd.apache.org/docs/2.0/sections.html

========= Copyright =========

Copyright 2006 MaxMind LLC
support@maxmind.com

