				mod_geoip 1.3.4
				---------------

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

mod_geoip is an Apache 1.3 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 2.0 mod_geoip2 module, see:
http://www.maxmind.com/download/geoip/api/mod_geoip2/

======== 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_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".  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.
You can also retrieve the Continent code from the "GEOIP_CONTINENT_CODE"
note or environment variable.

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

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.

Another MemoryCache option is MMapCache.

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.

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

  GeoIPEnableUTF8 On

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

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

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.

Another troubleshooting tip is to 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.

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


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

# no geoIP info inside /yyy
<Location /yyy>
  GeoIPEnable Off
</Location>

# no geoIP info inside /zzz
<Location /zzz>
</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.3.0 on. If you choose 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 ( or aapchectl 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/1.3/mod/core.html#filesmatch

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

Copyright 2008 MaxMind, Inc
