/ 
Apache-GeoIP-1.99
River stage zero No dependents
/ Apache::Geo::IP

NAME

Apache::Geo::IP - Look up country by IP address

SYNOPSIS

# in httpd.conf
#<Location /ip>
#   SetHandler perl-script
#   PerlHandler Apache::HelloIP
#   PerlSetVar GeoIPDBFile "/usr/local/share/GeoIP/GeoIP.dat"
#   PerlSetVar GeoIPFlag Standard
#   PerlSetVar GeoIPXForwardedFor 1
#</Location>

# file Apache::HelloIP
 
use Apache::Geo::IP;
use strict;

use Apache::Constants qw(REMOTE_HOST);

sub handler {
  my $r = Apache::Geo::IP->new(shift);
  $r->content_type('text/plain');
  my $country = uc($r->country_code_by_addr());
 
  $r->print($country);
 
  return OK;
}
1;

DESCRIPTION

This module constitutes a mod_perl (version 2) interface to the Geo::IP module, which looks up in a database a country of origin of an IP address. This database simply contains IP blocks as keys, and countries as values. This database should be more complete and accurate than reverse DNS lookups.

This module can be used to automatically select the geographically closest mirror, to analyze your web server logs to determine the countries of your visiters, for credit card fraud detection, and for software export controls.

To find a country for an IP address, this module a finds the Network that contains the IP address, then returns the country the Network is assigned to.

CONFIGURATION

This module subclasses Apache2::RequestRec, and can be used as follows in an Apache module.

 # file Apache::HelloIP
 
 use Apache::Geo::IP;
 use strict;

 sub handler {
    my $r = Apache::Geo::IP->new(shift);
    # continue along
 }

The directives in httpd.conf are as follows:

 <Location /ip>
   PerlSetVar GeoIPDBFile "/usr/local/share/GeoIP/GeoIP.dat"
   PerlSetVar GeoIPFlag Standard
   # other directives
 </Location>

The PerlSetVar directives available are

PerlSetVar GeoIPDBFile "/path/to/GeoIP.dat"

This specifies the location of the GeoIP.dat file. If not given, it defaults to the location specified upon installing the Geo::IP module.

PerlSetVar GeoIPFlag Standard

Flags can be set to either STANDARD, or for faster performance (at a cost of using more memory), MEMORY_CACHE. When using memory cache you can force a reload if the file is updated by setting CHECK_CACHE. INDEX_CACHE caches the most frequently accessed index portion of the database, resulting in faster lookups than STANDARD, but less memory usage than MEMORY_CACHE - this is useful for larger databases such as GeoIP Organization and GeoIP City. Note, for GeoIP Country, Region and Netspeed databases, INDEX_CACHE is equivalent to MEMORY_CACHE.

Multiple values of GeoIPFlag can be set by specifying them using PerlAddVar. If no values are specified, STANDARD is used.

PerlSetVar GeoIPType CITY_EDITION_REV1

This specifies the type of database file to be used. See the Geo::IP documentation for the various types that are supported.

PerlSetVar GeoIPXForwardedFor 1

If this directive is set to something true, the X-Forwarded-For header will be used to try to identify the originating IP address; this is useful for clients connecting to a web server through an HTTP proxy or load balancer. If this header is not present, $r->connection->remote_ip will be used.

METHODS

The available methods are as follows.

$code = $r->country_code_by_addr( [$ipaddr] );

Returns the ISO 3166 country code for an IP address. If $ipaddr is not given, the value obtained by examining the X-Forwarded-For header will be used, if GeoIPXForwardedFor is used, or else $r->connection->remote_ip is used

$code = $r->country_code_by_name( [$ipname] );

Returns the ISO 3166 country code for a hostname. If $ipname is not given, the value obtained by $r->get_remote_host(REMOTE_HOST) is used.

$code = $r->country_code3_by_addr( [$ipaddr] );

Returns the 3 letter country code for an IP address. If $ipaddr is not given, the value obtained by examining the X-Forwarded-For header will be used, if GeoIPXForwardedFor is used, or else $r->connection->remote_ip is used.

$code = $r->country_code3_by_name( [$ipname] );

Returns the 3 letter country code for a hostname. If $ipname is not given, the value obtained by $r->get_remote_host(REMOTE_HOST) is used.

$org = $r->org_by_addr( [$ipaddr] );

Returns the Organization, ISP name or Domain Name for an IP address. If $ipaddr is not given, the value obtained by examining the X-Forwarded-For header will be used, if GeoIPXForwardedFor is used, or else $r->connection->remote_ip is used.

$org = $r->org_by_name( [$ipname] );

Returns the Organization, ISP name or Domain Name for a hostname. If $ipname is not given, the value obtained by $r->get_remote_host(REMOTE_HOST) is used.

( $country, $region ) = $r->region_by_addr( [$ipaddr] );

Returns a list containing country and region for an IP address. If the region and/or country is unknown, undef is returned. This works only for region databases. If $ipaddr is not given, the value obtained by examining the X-Forwarded-For header will be used, if GeoIPXForwardedFor is used, or else $r->connection->remote_ip is used.

( $country, $region ) = $r->region_by_name( [$ipname] );

Returns a list containing country and region for a hostname. If the region and/or country is unknown, undef is returned. This works only for region databases. If $ipname is not given, the value obtained by examining the X-Forwarded-For header will be used, if GeoIPXForwardedFor is used, or else $r->get_remote_host(REMOTE_HOST) is used.

$gi = $r->gi

Returns the Geo::IP object.

Geo::IP::Record

A Geo::IP::Record object can be created by two ways:

$record = $r->record_by_addr( [$ipaddr] );

Returns a Geo::IP::Record object containing city location an IP address. If $ipaddr is not given, the value obtained by examining the X-Forwarded-For header will be used, if GeoIPXForwardedFor is used, or else $r->connection->remote_ip is used.

$record = $r->record_by_name( [$ipname] );

Returns a Geo::IP::Record object containing city location for a hostname. If $ipname is not given, the value obtained by $r->get_remote_host(REMOTE_HOST) is used.

The information contained in this object can be accessed as:

$code = $record->country_code;

Returns the ISO 3166 country code from the location object.

$code3 = $record->country_code3;

Returns the ISO 3166 3 letter country code from the location object.

$name = $record->country_name;

Returns the country name from the location object.

$region = $record->region;

Returns the region code from the location object.

$region = $record->region_name;

Returns the region name from the location object.

$city = $record->city;

Returns the city from the location object.

$postal_code = $record->postal_code;

Returns the postal code from the location object.

$lat = $record->latitude;

Returns the latitude from the location object.

$lon = $record->longitude;

Returns the longitude from the location object.

$time_zone = $record->time_zone;

Returns the time zone from the location object.

$area_code = $record->area_code;

Returns the area code from the location object (for city-level US locations only)

$metro_code = $record->metro_code;

Returns the metro code from the location object (for city-level US locations only)

$continent_code = $record->continent_code;

Returns the continent code from the location object. Possible continent codes are AF, AS, EU, NA, OC, SA for Africa, Asia, Europe, North America, Oceania and South America.

SEE ALSO

Geo::IP and Apache2::RequestRec.

AUTHOR

The look-up code for associating a country with an IP address is based on the GeoIP library and the Geo::IP Perl module, and is Copyright (c) 2002, T.J. Mather, < tjmather@tjmather.com > New York, NY, USA. See http://www.maxmind.com/ for details. The mod_perl interface is Copyright (c) 2002, 2009 Randy Kobes < randy.kobes@gmail.com >.

All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.