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. AUTHORS Matthew Darwin, email@example.com Randy Kobes, firstname.lastname@example.org 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.