<chapter id="config"><title>Configuration</title>
    <!--=================================================================================-->
    <para>
	mod_variety offers only a few configuration directives. They should be placed inside a &lt;Directory&gt; or a
	&lt;Location&gt; configuration block.
    </para>

    <para>
	You should prefer to configure mod_variety in a &lt;Directory&gt; block. If mod_variety was configured inside a
	&lt;Location&gt; block, and the requested file exists, mod_variety will not be run.
    </para>
    <!--=================================================================================-->
    <section id="config-load"><title>Loading the Module</title>
	<para>
	    You will need to add the following line to your Apache configuration file to load the mod_variety module.
	    <screen>LoadModule variety_module modules/mod_variety.so</screen>
	</para>
    </section>
    <!--=================================================================================-->
    <section id="config-on"><title>Enabling the Module</title>
	<para>
	    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.
	</para>

	<example id="config-on-ex"><title>Using the Variety Configuration Directive</title>
	    <para>Turn on mod_variety for the <filename>/manual</filename> location.</para>
	    <screen>
<![CDATA[
<Location /manual>
    Variety On
</Location>
]]>
	    </screen>
	</example>

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

	<para>
	    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 &lt;Location&gt; block that does not have a matching directory, mod_variety can't open a
	    directory to pick files from.
	</para>

	<example id="config-on-dir-ex"><title>Detailed Variety Example</title>
	    <para>Make Apache return a random icon when any file from <filename>/icons</filename> is requested.</para>
	    <screen>
<![CDATA[
<Directory "/usr/local/apache/icons">
    Options Indexes MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all

    Variety On
</Directory>
]]>
	    </screen>
	</example>
    </section>
    <!--=================================================================================-->
    <section id="config-cookies"><title>Using HTTP Cookies</title>
	<para>
	    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.
	</para>

	<para>
	    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.
	</para>

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

	<example id="config-cookie-ex"><title>Using the VarietyCookies Configuration Directive</title>
	    <para>Turn on variety cookies for the <filename>/manual</filename> location.</para>
	    <screen>
<![CDATA[
<Location /manual>
    Variety On
    VarietyCookies On
</Location>
]]>
	    </screen>
	</example>
    </section>
    <!--=================================================================================-->
    <section id="config-match"><title>Selecting Files Using a Regular Expression</title>
	<para>
	    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 <command>VarietyMatch</command> configuration directive.
	</para>

	<example id="config-match-ex"><title>Using the VarietyMatch Configuration Directive</title>
	    <para>Only serve icon files that end in <constant>gif</constant>.</para>
	    <screen>
<![CDATA[
<Directory "/usr/local/apache/icons">
    Options Indexes MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all

    Variety On
    VarietyMatch [Gg][Ii][Ff]$
</Directory>
]]>
	    </screen>
	</example>
    </section>
    <!--=================================================================================-->
    <section id="config-exclude"><title>Excluding Files Using a Regular Expression</title>
	<para>
	    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 <command>VarietyExclude</command> directive.
	</para>

	<example id="config-exclude-ex"><title>Using the VarietyExclude Configuration Directive</title>
	    <para>Don't serve any files that end in <constant>png</constant>.</para>
	    <screen>
<![CDATA[
<Directory "/usr/local/apache/icons">
    Options Indexes MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all

    Variety On
    VarietyExclude [Pp][Nn][Gg]$
</Directory>
]]>
	    </screen>
	</example>

	<note>
	    <para>
		You can use the <command>VarietyMatch</command> and <command>VarietyExclude</command> at the same time to have a
		complex way of selecting files for mod_variety to choose from.
	    </para>
	</note>
    </section>
    <!--=================================================================================-->
    <section id="config-dirmax"><title>Limiting Resource Usage</title>
	<para>
	    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 <command>VarietyDirMax</command>
	    directive.
	</para>

	<para>
	    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 <filename>one.jpg</filename> and <filename>two.jpg</filename> require 14 bytes of
	    data in mod_variety. The default limit is 1024 bytes per directory.
	</para>

	<example id="config-dirmax-ex"><title>Using the VarietyExclude Configuration Directive</title>
	    <para>Raise the memory usage limit for <filename>/usr/local/apache/icons</filename> to 4096 bytes.</para>
	    <screen>
<![CDATA[
<Directory "/usr/local/apache/icons">
    Options Indexes MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all

    Variety On
    VarietyDirMax 4096
</Directory>
]]>
	    </screen>
	</example>
    </section>
    <!--=================================================================================-->
</chapter>
<!--
    vim:ft=docbk:tw=130
-->