Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/thinker0/mod_geoip2

Maxmid mod_geoip2
https://github.com/thinker0/mod_geoip2

Last synced: 10 days ago
JSON representation

Maxmid mod_geoip2

Awesome Lists containing this project

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.



  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



GeoIPEnable is useful in server or directory context. For example:



##

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

##



  GeoIPEnable Off

  GeoIPEnableUTF8 On

  GeoIPOutput Env

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



# GeoIP information is avail only inside /xxx



  GeoIPEnable On



##

## Example 2 GeoIP is avail for every request

##



  GeoIPEnable On

  GeoIPEnableUTF8 On

  GeoIPOutput Env

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



  GeoIPEnable On



## geoip information is also avail inside /yyy since it is enabled serverwide!!!



  GeoIPEnable Off



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

,  or  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

[email protected]