README

				mod_geoip2 1.2.7
				----------------

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

mod_geoip2 is an Apache 2.x 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.4.3 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.  This will call the GeoIP Country
database from its default location (e.g. /usr/local/share/GeoIP/GeoIP.dat)

If you want to specify the a non-default location for the database file(s),
or what to use other databases besides GeoIP Country, or to pass options,
use:

  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 possible values for GeoIPFlag are:

The default GeoIPFlag is Standard, 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:

  GeoIPDBFile /path/to/GeoIP.dat MemoryCache

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.

If you would like to enable checking for GeoIP updates, use

  GeoIPDBFile /path/to/GeoIP.dat 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:

  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 - 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.

You may change the output charset fom latin1 ( iso-8859-1 ) to utf8 with:

  GeoIPEnableUTF8 On


Output variables set:

GEOIP_ADDR is the address used to calculate the geoip information. Either the ipaddress you came 
from, or if you use GeoIPScanProxyHeaders On,  the first defined environment 
variable HTTP_CLIENT_IP, HTTP_X_FORWARDED_FOR, the http header X-Forwarded-For or the environment 
variable HTTP_REMOTE_ADDR.

GEOIP_ADDR is always exported, when mod_geoip is used.


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". 
You can also retrieve the Continent code from the "GEOIP_CONTINENT_CODE" note or environment variable.
Possible continent codes are AF, AS, EU, NA, OC, SA for Africa, Asia, Europe, North America, Oceania
and South America.
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, GEOIP_REGION_NAME and GEOIP_REGION

GeoIP City Edition:
Sets GEOIP_CONTINENT_CODE, GEOIP_COUNTRY_CODE, GEOIP_REGION, 
	GEOIP_REGION_NAME, GEOIP_CITY, GEOIP_METRO_CODE,
        GEOIP_AREA_CODE, GEOIP_LATITUDE, GEOIP_LONGITUDE
	and 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

GeoIPv6 Edition ( experimental )
Sets GEOIP_CONTINENT_CODE_V6, GEOIP_COUNTRY_CODE_V6,
        GEOIP_COUNTRY_NAME_V6

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)

========= 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

========= 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

GeoIPScanProxyHeaders On

This only works if the first IP in the HTTP_X_FORWARDED_FOR list is the
actual clientIP that you want to lookup.

GeoIPUseLastXForwardedForIP On

Use the last IP from the HTTP_X_FORWARDED_FOR header instead of the first one.
GeoIPScanProxyHeaders must be enabled ( On ) otherwise
GeoIPUseLastXForwardedForIP is ignored.

========= Server vs Directory context =========

All directives expect GeoIPEnable are server config only.
ie: 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:

##
## Example 1 GeoIP is only avail for creation parts of our server
##

<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 /xxx>
  GeoIPEnable On
</Location>



##
## Example 2 GeoIP is avail for every request
##

<IfModule mod_geoip.c>
  GeoIPEnable On
  GeoIPEnableUTF8 On
  GeoIPOutput Env
  GeoIPDBFile /usr/local/share/GeoIP/GeoIP.dat MemoryCache
</IfModule>

<Location /xxx>
  GeoIPEnable On
</Location>

## geoip information is also avail inside /yyy since it is enabled serverwide!!!
<Location /yyy>
  GeoIPEnable Off
</Location>

======== preformance -- getting fast =======

To get really fast, add the MemoryCache option to the GeoIPDBFile directive or
the MMapCache with very similar results.

========= saving memory =========

Every apache child share the same database over all childs.
From mod_geoip version 1.2.1 on. If you choice to use MemoryCache or MMapCache.
Doing so reduce the child database loading time to zero and the memoryusage
is about the database filesize. No matter how many childs apache spawns. The
only thing to remember is ask apache to update, if your the database change. 
Use httpd -k graceful to do so without stopping apache.

========= 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

========= troubleshooting =======

If the module is not working, make sure that the httpd user (e.g. nobody)
has read access to the GeoIP.dat file, by running the chown or chmod command.

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 only reports the country of external IP addresses.

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

Copyright 2007 MaxMind LLC
support@maxmind.com