NAME

Apache::RandomLocation - Perl extension for mod_perl to handle random locations.

SYNOPSIS

  You can use this in your Apache *.conf files to activate this module.

  <Location /scripts/random-image>
  SetHandler perl-script
  PerlSetVar BaseURL /images/
  PerlSetVar ConfigFile /usr/local/apache/etc/sponsors.txt
  PerlHandler Apache::RandomLocation
  </Location>

  <Location /scripts/CPAN>
  SetHandler perl-script
  PerlSetVar Type mirror
  PerlSetVar ConfigFile /usr/local/apache/etc/cpan_mirrors.txt
  PerlHandler Apache::RandomLocation
  </Location>

DESCRIPTION

Given a list of locations in ConfigFile, this module will instruct the browser to redirect to one of them. The locations in ConfigFile are listed one per line, with lines beginning with # being ignored. How the redirection is handled depends on the variable Type.

If Type is undefined or set to file, the locations are assumed to be files. BaseUrl, which can be a full or partial URL, gives the location of these files. This can be used to implement, for example, a banner in an HTML page: <IMG SRC="/scripts/random-image">. The file chosen is random. Since after one call this image gets cached by the client, to generate multiple random images on the same page, you could append different bogus paths after the calling URL, as in <IMG SRC="/scripts/random-image/1"> and <IMG SRC="/scripts/random-image/2">.

In this case, if BaseURL indicates the local server is being used, ConfigFile can contain a perl regular expression (enclosed by /, as in /\.gif$/) which will be used to match files in BaseURL. If ConfigFile is not defined, all files in BaseUrl will be read. If BaseUrl is undefined, the top level directory of the local server is assumed.

If type is set to mirror, the locations in ConfigFile are assumed to be mirror sites of some set of files, giving both the host name and the directory path (eg, ftp.mirror.edu/path/to/dir). In this mode the module acts like the CPAN muliplexer code of http://www.perl.com/CPAN; for example, http://my.host.edu/scripts/CPAN/src/latest.tar.gz will redirect to a nearby CPAN mirror to retrieve the file src/latest.tar.gz. Also like the CPAN multiplexer, a call to the URL http://my.host.edu/scripts/CPAN (without any trailing slash) will bring up a form from which one can manually choose a site to go to.

In this case, redirection is made to a random mirror site whose country code in the domain name matches that of the client. If no such mirror exists, a random mirror with country code matching (com|edu|net|org|us) is selected. For these purposes, clients with country codes com, edu, org, net, and us are considered equivalent. If a particular mirror site should be considered as having a different country code in this regard, add the desired code (separated by a space) to the end of the line containing the address of the mirror in ConfigFile. If the address of a mirror does not begin with http://, the ftp:// protocol is assumed.

Information on the locations is stored in a hash, which survives in each child's memory for the life of the child. This hash is uniquely associated with the given Location directive in *.conf, so that multiple uses of Apache::RandomLocation modules on one server with different Location directives is possible.

Like Apache's configuration files, if any changes are made in ConfigFile, the server must be restarted in order that the changes take immediate effect; otherwise, one must wait for the child processes to die in order that the new configuration file be read in.

Examples

These directives in access.conf:

  <Location /scripts/random-image>
  SetHandler perl-script
  PerlSetVar BaseURL /images/
  PerlSetVar ConfigFile /usr/local/apache/etc/sponsors.txt
  PerlHandler Apache::RandomLocation
  </Location>

with the following file /usr/local/apache/etc/sponsors.txt:

  apache.jpeg
  mod_perl.jpeg
  /\.gif$/

will use the image files apache.jpeg, mod_perl.jpeg, and any gif image in the server location /images. A random image will then be selected with a call to http://your.server.name/scripts/random-image.

These directives in access.conf:

  <Location /scripts/CPAN>
  SetHandler perl-script
  PerlSetVar Type mirror
  PerlSetVar ConfigFile /usr/local/apache/etc/cpan_mirrors.txt
  PerlHandler Apache::RandomLocation
  </Location>

with the following file /usr/local/apache/etc/cpan_mirrors.txt:

   ftp.funet.fi/pub/languages/perl/CPAN
   ftp.metronet.com/pub/perl
   http://www.perl.com/CPAN
   ftp.utilis.com/pub/perl/CPAN ca

can be used to redirect clients to a (hopefully) nearby random CPAN mirror: a call to http://your.server.name/scripts/CPAN/src/latest.tar.gz will grab the file latest.tar.gz under the $CPAN src/ directory of the mirror. The ftp:// protocol is assumed for all sites except www.perl.com, where http:// is used. For the purpose of matching the country code of the client with that of the mirrors, ftp.utilis.com is to be considered as having the country code of "ca".

If a LocationMatch directive is given as, for example,

  <LocationMatch "/(physics|chemistry|biology)/random-image">
    SetHandler perl-script
    PerlSetVar BaseURL ~/images/
    PerlSetVar ConfigFile ~/images/config.txt
    PerlHandler Apache::RandomLocation
  </LocationMatch>

then the tilde character will be interpreted as the corresponding home directory (relative to DocumentRoot). For example, with DocumentRoot equal to /usr/local/apache/htdocs, a request to /biology/random-image will use a BaseURL of /usr/local/apache/htdocs/biology/images/ and a ConfigFile of </usr/local/apache/htdocs/biology/images/config.txt>.

AUTHORS

Matthew Darwin, matthew@davin.ottawa.on.ca

Randy Kobes, randy@theory.uwinnipeg.ca

The mirror redirection code is based on the CPAN multiplexer code of Tom Christiansen and a similar script by Ulrich Pfeifer.

SEE ALSO

perl(1), Apache(3), mod_perl(3)

COPYRIGHT

Copyright 1998, Matthew Darwin, Randy Kobes

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