Using mod_variety

An Apache Administrators Guide

Peter Jones

pjones@pmade.org
    

Copyright © 2002, 2003 by Peter Jones (http://pmade.org/pjones/)

This book provides instructions on how to install and use the mod_variety
Apache module.

The latest version of this book can be found at http://pmade.org/pjones/
software/mod_variety/.

Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML,
HTML, PDF, PostScript, RTF and so forth) with or without modification, are
permitted provided that the following conditions are met:

 1. Redistributions of source code (SGML DocBook) must retain the above
    copyright notice, this list of conditions and the following disclaimer
    as the first lines of this file unmodified.
   
 2. Redistributions in compiled form (transformed to other DTDs, converted
    to PDF, PostScript, RTF and other formats) must reproduce the above
    copyright notice, this list of conditions and the following disclaimer
    in the documentation and/or other materials provided with the
    distribution.
   
    Important: THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR "AS IS" AND ANY
    EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
    STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
    IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGE.
   
---------------------------------------------------------------------------

Table of Contents
1. Introduction
2. Building and Installing
3. Configuration
   
    3.1. Loading the Module
    3.2. Enabling the Module
    3.3. Using HTTP Cookies
    3.4. Selecting Files Using a Regular Expression
    3.5. Excluding Files Using a Regular Expression
    3.6. Limiting Resource Usage
   
A. Revision History
   
    A.1. Version 0.2.1
    A.2. Version 0.2.0
    A.3. Version 0.1.0
   
B. Credits
   
    B.1. Maintainers
   
List of Examples
3-1. Using the Variety Configuration Directive
3-2. Detailed Variety Example
3-3. Using the VarietyCookies Configuration Directive
3-4. Using the VarietyMatch Configuration Directive
3-5. Using the VarietyExclude Configuration Directive
3-6. Using the VarietyExclude Configuration Directive

---------------------------------------------------------------------------

Chapter 1. Introduction

mod_variety is an Apache 2.x module for serving random files. When a
request comes in for a directory or location that mod_variety has been
configured to handle, it will read the contents of the directory and choose
a random file to serve.

You can choose which files will be considered for random selection using
two regular expressions. One allows you to give a regular expression that
files must match to be considered. The other allows you to give a regular
expression that files must not match to be considered.

---------------------------------------------------------------------------

Chapter 2. Building and Installing

This section will show you how to install mod_variety using the supplied
Makefile.

  * Make sure that apxs is either in your path or make sure that you give
    it to make like this:
   
        make APXS=/path/to/apxs
   
   
  * From the top directory, run make. This must be GNU make and on some
    systems it is called gmake.
   
  * After everything is done compiling you can run make install.
   
  * Update your Apache configuration file. Information about the available
    mod_variety configuration directives is presented in the following
    chapter.
   
---------------------------------------------------------------------------

Chapter 3. Configuration

mod_variety offers only a few configuration directives. They should be
placed inside a <Directory> or a <Location> configuration block.

You should prefer to configure mod_variety in a <Directory> block. If
mod_variety was configured inside a <Location> block, and the requested
file exists, mod_variety will not be run.

---------------------------------------------------------------------------

3.1. Loading the Module

You will need to add the following line to your Apache configuration file
to load the mod_variety module.

    LoadModule variety_module modules/mod_variety.so


---------------------------------------------------------------------------

3.2. Enabling the Module

If you have a directory that contains files and you want mod_variety to
serve a random file from that directory, you first need to enable
mod_variety for that directory.

Example 3-1. Using the Variety Configuration Directive

Turn on mod_variety for the /manual location.

    <Location /manual>
        Variety On
    </Location>
           

You can also turn mod_variety off without having to remove all
configuration directives for it. This is done by using Variety Off
directive.

One thing to note here is that mod_variety can only work if the current URL
maps to a physical directory on the server. If you use a <Location> block
that does not have a matching directory, mod_variety can't open a directory
to pick files from.

Example 3-2. Detailed Variety Example

Make Apache return a random icon when any file from /icons is requested.

    <Directory "/usr/local/apache/icons">
        Options Indexes MultiViews
        AllowOverride None
        Order allow,deny
        Allow from all
    
        Variety On
    </Directory>
           
---------------------------------------------------------------------------

3.3. Using HTTP Cookies

It is possible for mod_variety to use HTTP cookies. If variety cookies are
enabled, mod_variety will set an HTTP cookie when it serves a random file.
When a browser makes a request to mod_variety and requests a random file,
mod_variety will check for that cookie. If that cookie is set, mod_variety
will remove the selected file from the list of possible files to serve.

This effectively prevents the same browser from getting the same random
file twice in a row. It will make mod_variety appear to be more random.

In order to use variety cookies, you must enable them in the Apache
configuration file using the VarietyCookies On directive.

Example 3-3. Using the VarietyCookies Configuration Directive

Turn on variety cookies for the /manual location.

    <Location /manual>
        Variety On
        VarietyCookies On
    </Location>
           
---------------------------------------------------------------------------

3.4. Selecting Files Using a Regular Expression

If you have a directory full of files that you want to use mod_variety to
serve, but you only want mod_variety to select files that match a regular
expression, you can use the VarietyMatch configuration directive.

Example 3-4. Using the VarietyMatch Configuration Directive

Only serve icon files that end in gif.

    <Directory "/usr/local/apache/icons">
        Options Indexes MultiViews
        AllowOverride None
        Order allow,deny
        Allow from all
    
        Variety On
        VarietyMatch [Gg][Ii][Ff]$
    </Directory>
           
---------------------------------------------------------------------------

3.5. Excluding Files Using a Regular Expression

Just as you can select files by making them match a regular expression, you
can exclude files that match a regular expression. When a file is excluded,
it is removed from the list of files that mod_variety uses to choose a
random file to serve. You can exclude files using the VarietyExclude
directive.

Example 3-5. Using the VarietyExclude Configuration Directive

Don't serve any files that end in png.

    <Directory "/usr/local/apache/icons">
        Options Indexes MultiViews
        AllowOverride None
        Order allow,deny
        Allow from all
    
        Variety On
        VarietyExclude [Pp][Nn][Gg]$
    </Directory>
           

   
    Note: You can use the VarietyMatch and VarietyExclude at the same time
    to have a complex way of selecting files for mod_variety to choose
    from.
   
---------------------------------------------------------------------------

3.6. Limiting Resource Usage

If you have a directory with a very large number of files, it may take more
memory to select a random file than you would like. You can make
mod_variety stop searching a directory after it has used a specified amount
of memory, at which point it will select from the files it already has.
This is done using the VarietyDirMax directive.

The actual amount of memory mod_variety is going to use is based on the
name of the files in the directory. For example, two files with the names
one.jpg and two.jpg require 14 bytes of data in mod_variety. The default
limit is 1024 bytes per directory.

Example 3-6. Using the VarietyExclude Configuration Directive

Raise the memory usage limit for /usr/local/apache/icons to 4096 bytes.

    <Directory "/usr/local/apache/icons">
        Options Indexes MultiViews
        AllowOverride None
        Order allow,deny
        Allow from all
    
        Variety On
        VarietyDirMax 4096
    </Directory>
           
---------------------------------------------------------------------------

Appendix A. Revision History

A.1. Version 0.2.1

March 25, 2003

Fixed a bug that broke Apache ErrorDocument directives.

---------------------------------------------------------------------------

A.2. Version 0.2.0

March 19, 2003

Added support for HTTP cookies via VarietyCookies.

---------------------------------------------------------------------------

A.3. Version 0.1.0

January 17, 2003

First public release.

---------------------------------------------------------------------------

Appendix B. Credits

B.1. Maintainers

The following people currently maintain mod_variety.

  * Peter Jones - Author and main maintainer.
   
---------------------------------------------------------------------------