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.