Apache2::Geo::Mirror - Find closest Mirror


 # 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 ""
 # file Apache2::HelloMirror
 use Apache2::Geo::Mirror;
 use strict;
 use Apache2::Const -compile => 'OK';
 sub handler {
   my $r = Apache2::Geo::Mirror->new(shift);
   my $mirror = $r->find_mirror_by_addr();


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.


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 ""
    PerlSetVar GeoIPFresh 2
    # other directives

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         us     fr

An optional third field may be specified, such as    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 ""

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.


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.


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 ""
    PerlResponseHandler Apache2::Geo::Mirror->auto_redirect

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.


Geo::IP, Geo::Mirror, and Apache2::RequestRec.


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, < >, New York, NY, USA. See for details. The mod_perl interface is Copyright (c) 2002, 2009 Randy Kobes < >.

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