NAME

Apache2::Geo::Mirror - Find closest Mirror

SYNOPSIS

            

              
              
# in httpd.conf
# PerlModule Apache2::HelloMirror
#<Location /mirror>
#   SetHandler perl-script
#   PerlResponseHandler Apache2::HelloMirror
#   PerlSetVar GeoIPDBFile "/usr/local/share/GeoIP/GeoIP.dat"
#   PerlSetVar GeoIPMirror "/usr/local/share/data/mirror.txt"
#   PerlSetVar GeoIPDefault "http://www.cpan.org/"
#</Location>
# file Apache2::HelloMirror
use Apache2::Geo::Mirror;
use strict;
use Apache2::Const -compile => 'OK';
sub handler {
  my $r = Apache2::Geo::Mirror->new(shift);
  $r->content_type('text/plain');
  my $mirror = $r->find_mirror_by_addr();
  $r->print($mirror);
  
  Apache2::Const::OK;
}
1;
            
          

DESCRIPTION

This module provides a mod_perl (version 2) interface to the Geo::Mirror module, which finds the closest mirror for an IP address. It uses Geo::IP to identify the country that the IP address originated from. If the country is not represented in the mirror list, then it finds the closest country using a latitude/longitude table.

CONFIGURATION

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

            

              
              
# file Apache2::HelloMirror
  
use Apache2::Geo::Mirror;
use strict;
sub handler {
   my $r = Apache2::Geo::Mirror->new(shift);
   # continue along
}
            
          

The PerlSetVar directives in httpd.conf are as follows:

            

              
              
<Location /mirror>
  PerlSetVar GeoIPDBFile "/usr/local/share/geoip/GeoIP.dat"
  PerlSetVar GeoIPMirror "/usr/local/share/data/mirror.txt"
  PerlSetVar GeoIPDefault "http://www.cpan.org/"
  PerlSetVar GeoIPFresh 2
  # other directives
</Location>
            
          

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

PerlSetVar GeoIPFresh 5

This specifies a minimum freshness that the chosen mirror must satisfy. If this is not specified, a value of 0 is assumed.

PerlSetVar GeoIPMirror "/path/to/mirror.txt"

This specifies the location of a file containing the list of available mirrors. No default location for this file is assumed. This file contains a list of mirror sites and the corresponding country code in the format

            

              
              
http://some.server.com/some/path         us
ftp://some.other.server.fr/somewhere     fr
            
          

An optional third field may be specified, such as

            

              
              
ftp://some.other.server.ca/somewhere    ca  3
            
          

where the third number indicates the freshness of the mirror. A default freshness of 0 is assumed when none is specified. When choosing a mirror, if the GeoIPFresh directive is specified, only those mirrors with a freshness equal to or above this value may be chosen.

PerlSetVar GeoIPDefault "http://some.where.org/"

This specifies the default url to be used if no nearby mirror is found. Multiple values may be specified using PerlAddVar; if more than one default is given, a random one will be chosen.

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.

$mirror = $r->find_mirror_by_country( [$country] );

Finds the nearest mirror by country code. If $country is not given, this defaults to the country as specified by a lookup of $r->connection->remote_ip.

$mirror = $r->find_mirror_by_addr( [$ipaddr] );

Finds the nearest mirror by 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.

$gm = $r->gm;

Returns the Geo::IP::Mirror object.

AUTOMATIC REDIRECTION

If Apache2::Geo::Mirror is used as

            

              
              
PerlModule Apache2::Geo::Mirror
<Location /CPAN>
  PerlSetVar GeoIPDBFile "/usr/local/share/geoip/GeoIP.dat"
  PerlSetVar GeoIPMirror "/usr/local/share/data/mirror.txt"
  PerlSetVar GeoIPDefault "http://www.cpan.org/"
  PerlResponseHandler Apache2::Geo::Mirror->auto_redirect
</Location>
            
          

then an automatic redirection is made. Within this, the directive

            

              
              
PerlSetVar GeoIPRobot "/path/to/a/robots.txt"
            
          

can be used to handle robots that honor a robots.txt file. This can be a physical file that exists on the system or, if it is set to the special value default, the string

            

              
              
User-agent: *
Disallow: /
            
          

will be used, which disallows robot access to anything.

Within automatic redirection, the X-Forwarded-For header wil be used to try to infer the IP address of the client.

SEE ALSO

Geo::IP, Geo::Mirror, 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.