mod_rewrite.xml revision 36088d24dae5b2cc8124264fc6a9ba349ba81adc
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<!-- $LastChangedRevision$ -->
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess Copyright 2002-2005 The Apache Software Foundation or its licensors, as
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess applicable.
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess Licensed under the Apache License, Version 2.0 (the "License");
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess you may not use this file except in compliance with the License.
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess You may obtain a copy of the License at
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess Unless required by applicable law or agreed to in writing, software
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess distributed under the License is distributed on an "AS IS" BASIS,
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess See the License for the specific language governing permissions and
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess limitations under the License.
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<description>Provides a rule-based rewriting engine to rewrite requested
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessURLs on the fly</description>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<compatibility>Available in Apache 1.3 and later</compatibility>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>This module uses a rule-based rewriting engine (based on a
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess regular-expression parser) to rewrite requested URLs on the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess fly. It supports an unlimited number of rules and an
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess unlimited number of attached rule conditions for each rule to
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess provide a really flexible and powerful URL manipulation
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess mechanism. The URL manipulations can depend on various tests,
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess for instance server variables, environment variables, HTTP
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess headers, time stamps and even external database lookups in
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess various formats can be used to achieve a really granular URL
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess matching.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>This module operates on the full URLs (including the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess path-info part) both in per-server context
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess (<code>.htaccess</code>) and can even generate query-string
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess parts on result. The rewritten result can lead to internal
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess sub-processing, external request redirection or even to an
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess internal proxy throughput.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>Further details, discussion, and examples, are provided in the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <a href="/rewrite/">detailed mod_rewrite documentation</a>.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<section id="quoting"><title>Quoting Special Characters</title>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>As of Apache 1.3.20, special characters in
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <em>TestString</em> and <em>Substitution</em> strings can be
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess escaped (that is, treated as normal characters without their
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess usual special meaning) by prefixing them with a slash ('\')
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess character. In other words, you can include an actual
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess dollar-sign character in a <em>Substitution</em> string by
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess using '<code>\$</code>'; this keeps mod_rewrite from trying
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess to treat it as a backreference.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<section id="EnvVar"><title>Environment Variables</title>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>This module keeps track of two additional (non-standard)
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess CGI/SSI environment variables named <code>SCRIPT_URL</code>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <em>logical</em> Web-view to the current resource, while the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess standard CGI/SSI variables <code>SCRIPT_NAME</code> and
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <code>SCRIPT_FILENAME</code> contain the <em>physical</em>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess System-view. </p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>Notice: These variables hold the URI/URL <em>as they were
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess initially requested</em>, <em>i.e.</em>, <em>before</em> any
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess rewriting. This is important because the rewriting process is
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess primarily used to rewrite logical URLs to physical
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess pathnames.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessSCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<section id="Solutions"><title>Practical Solutions</title>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>For numerous examples of common, and not-so-common, uses for
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess mod_rewrite, see the <a href="/rewrite/rewrite_guide.html">Rewrite
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess href="/rewrite/rewrite_guide_advanced.html">Advanced Rewrite
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<description>Enables or disables runtime rewriting engine</description>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<contextlist><context>server config</context><context>virtual host</context>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<context>directory</context><context>.htaccess</context></contextlist>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>The <directive>RewriteEngine</directive> directive enables or
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess disables the runtime rewriting engine. If it is set to
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <code>off</code> this module does no runtime processing at
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess all. It does not even update the <code>SCRIPT_URx</code>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess environment variables.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>Use this directive to disable the module instead of
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess commenting out all the <directive
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess module="mod_rewrite">RewriteRule</directive> directives!</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>Note that, by default, rewrite configurations are not
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess inherited. This means that you need to have a
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <code>RewriteEngine on</code> directive for each virtual host
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess in which you wish to use it.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess</directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<description>Sets some special options for the rewrite engine</description>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<contextlist><context>server config</context><context>virtual host</context>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<context>directory</context><context>.htaccess</context></contextlist>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<compatibility><code>MaxRedirects</code> is no longer available in version 2.1 and
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kesslater</compatibility>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>The <directive>RewriteOptions</directive> directive sets some
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess special options for the current per-server or per-directory
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess configuration. The <em>Option</em> string can be currently only one:</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <dd>This forces the current configuration to inherit the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess configuration of the parent. In per-virtual-server context
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess this means that the maps, conditions and rules of the main
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess server are inherited. In per-directory context this means
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess that conditions and rules of the parent directory's
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <code>.htaccess</code> configuration are inherited.</dd>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess</directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<description>Sets the name of the file used for logging rewrite engine
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessprocessing</description>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<contextlist><context>server config</context><context>virtual host</context>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess</contextlist>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>The <directive>RewriteLog</directive> directive sets the name
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess of the file to which the server logs any rewriting actions it
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess performs. If the name does not begin with a slash
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess ('<code>/</code>') then it is assumed to be relative to the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <em>Server Root</em>. The directive should occur only once per
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess server config.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<note> To disable the logging of
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess rewriting actions it is not recommended to set
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess although the rewriting engine does not then output to a
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess logfile it still creates the logfile output internally.
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <strong>This will slow down the server with no advantage
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess to the administrator!</strong> To disable logging either
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess remove or comment out the <directive>RewriteLog</directive>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessSee the <a href="/misc/security_tips.html">Apache Security Tips</a>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessdocument for details on why your security could be compromised if the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessdirectory where logfiles are stored is writable by anyone other than
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessthe user that starts the server.
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess</directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<description>Sets the verbosity of the log file used by the rewrite
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessengine</description>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<contextlist><context>server config</context><context>virtual host</context>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess</contextlist>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>The <directive>RewriteLogLevel</directive> directive sets the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess verbosity level of the rewriting logfile. The default level 0
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess means no logging, while 9 or more means that practically all
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess actions are logged.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>To disable the logging of rewriting actions simply set
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<note> Using a high value for
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess dramatically! Use the rewriting logfile at a
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessRewriteLogLevel 3
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess</directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<description>Sets the name of the lock file used for <directive
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kesssynchronization</description>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<contextlist><context>server config</context></contextlist>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>This directive sets the filename for a synchronization
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess lockfile which mod_rewrite needs to communicate with <directive
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <em>programs</em>. Set this lockfile to a local path (not on a
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess NFS-mounted device) when you want to use a rewriting
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess map-program. It is not required for other types of rewriting
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess</directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<description>Defines a mapping function for key-lookup</description>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<syntax>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<contextlist><context>server config</context><context>virtual host</context>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess</contextlist>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<compatibility>The choice of different dbm types is available in
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessApache 2.0.41 and later</compatibility>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>The <directive>RewriteMap</directive> directive defines a
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess substitution strings by the mapping-functions to
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess insert/substitute fields through a key lookup. The source of
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess this lookup can be of various types.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess the name of the map and will be used to specify a
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess mapping-function for the substitution strings of a rewriting
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess rule via one of the following constructs:</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <strong><code>${</code> <em>MapName</em> <code>:</code>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>When such a construct occurs the map <em>MapName</em> is
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess consulted and the key <em>LookupKey</em> is looked-up. If the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess key is found, the map-function construct is substituted by
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <em>SubstValue</em>. If the key is not found then it is
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess substituted by <em>DefaultValue</em> or by the empty string
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>For example, you might define a
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess </example>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>You would then be able to use this map in a
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess RewriteRule ^/ex/(.*) ${examplemap:$1}
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess </example>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess path to valid regular file
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>This is the standard rewriting map feature where the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess either blank lines, comment lines (starting with a '#'
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess character) or pairs like the following - one per
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess## map.txt -- rewriting map
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessRalf.S.Engelschall rse # Bastard Operator From Hell
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessMr.Joe.Average joe # Mr. Average
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess path to valid regular file
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>This is identical to the Standard Plain Text variant
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess above but with a special post-processing feature: After
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess looking up a value it is parsed according to contained
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess ``<code>|</code>'' characters which have the meaning of
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess ``or''. In other words they indicate a set of
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess alternatives from which the actual returned value is
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess chosen randomly. For example, you might use the following map
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess file and directives to provide a random load balancing between
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess several back-end server, via a reverse-proxy. Images are sent
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess to one of the servers in the 'static' pool, while everything
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess else is sent to one of the 'dynamic' pool.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess## map.txt -- rewriting map
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessstatic www1|www2|www3|www4
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessdynamic www5|www6
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessRewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess[NC,P,L]<br />
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessRewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess path to valid regular file
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>Here the source is a binary format DBM file containing
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess the same contents as a <em>Plain Text</em> format file, but
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess in a special representation which is optimized for really
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess fast lookups. The <em>type</em> can be sdbm, gdbm, ndbm, or
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess db depending on <a href="/install.html#dbm">compile-time
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess compile-time default will be chosen. You can create such a
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess file with any DBM tool or with the following Perl
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess script. Be sure to adjust it to create the appropriate
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess type of DBM. The example creates an NDBM file.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess## txt2dbm -- convert txt map to dbm format
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessuse NDBM_File;
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess($txtmap, $dbmmap) = @ARGV;
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessopen(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n";
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kesstie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644)
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess or die "Couldn't create $dbmmap!\n";
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kesswhile (<TXT>) {
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess next if (/^\s*#/ or /^\s*$/);
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess $DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/);
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessclose(TXT);
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>Here the source is an internal Apache function.
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess Currently you cannot create your own, but the following
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess functions already exists:</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess Converts the looked up key to all upper case.</li>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess Converts the looked up key to all lower case.</li>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess Translates special characters in the looked up key to
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess hex-encodings.</li>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess Translates hex-encodings in the looked up key back to
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess special characters.</li>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess path to valid regular file
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>Here the source is a program, not a map file. To
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess create it you can use the language of your choice, but
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess the result has to be a executable (<em>i.e.</em>, either
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess object-code or a script with the magic cookie trick
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess line).</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>This program is started once at startup of the Apache
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess servers and then communicates with the rewriting engine
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess file-handles. For each map-function lookup it will
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess receive the key to lookup as a newline-terminated string
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess looked-up value as a newline-terminated string on
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess is no corresponding value for the given key). A trivial
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess key == value) could be:</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kesswhile (<STDIN>) {
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess # ...put here any transformations or lookups...
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <li>``<em>Keep it simple, stupid</em>'' (KISS), because
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess if this program hangs it will hang the Apache server
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess when the rule occurs.</li>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <li>Avoid one common mistake: never do buffered I/O on
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess module="mod_rewrite">RewriteLock</directive> directive to
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess define a lockfile mod_rewrite can use to synchronize the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess communication to the program. By default no such
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess synchronization takes place.</li>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>The <directive>RewriteMap</directive> directive can occur more than
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess once. For each mapping-function use one
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <directive>RewriteMap</directive> directive to declare its rewriting
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess mapfile. While you cannot <strong>declare</strong> a map in
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess per-directory context it is of course possible to
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <strong>use</strong> this map in per-directory context. </p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<note><title>Note</title> For plain text and DBM format files the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kesslooked-up keys are cached in-core until the <code>mtime</code> of the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessmapfile changes or the server does a restart. This way you can have
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessmap-functions in rules which are used for <strong>every</strong>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessrequest. This is no problem, because the external lookup only happens
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess</directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<directivesynopsis>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<description>Sets the base URL for per-directory rewrites</description>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<contextlist><context>directory</context><context>.htaccess</context>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess</contextlist>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>The <directive>RewriteBase</directive> directive explicitly
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess sets the base URL for per-directory rewrites. As you will see
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess below, <directive module="mod_rewrite">RewriteRule</directive>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess can be used in per-directory config files
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <em>i.e.</em>, the local directory prefix is stripped at this
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess stage of processing and your rewriting rules act only on the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess remainder. At the end it is automatically added back to the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess path. The default setting is; <directive>RewriteBase</directive> <em>physical-directory-path</em></p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p>When a substitution occurs for a new URL, this module has
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess to re-inject the URL into the server processing. To be able
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess to do this it needs to know what the corresponding URL-prefix
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess or URL-base is. By default this prefix is the corresponding
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess filepath itself. <strong>But at most websites URLs are NOT
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess directly related to physical filename paths, so this
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess assumption will usually be wrong!</strong> There you have to
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess use the <code>RewriteBase</code> directive to specify the
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess correct URL-prefix.</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<note> If your webserver's URLs are <strong>not</strong> directly
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessrelated to physical file paths, you have to use
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess<directive>RewriteBase</directive> in every <code>.htaccess</code>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessfiles where you want to use <directive
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kessmodule="mod_rewrite">RewriteRule</directive> directives.
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess <p> For example, assume the following per-directory config file:</p>
fefb8b844b6286bfc41bb2e0c4cc003b8e7d4ff2kess# /abc/def/.htaccess -- per-dir config file for directory /abc/def
RewriteRule ^oldstuff\.html$ newstuff.html
RewriteRule ...some special stuff for any of these hosts...
RewriteRule ^/$ /homepage.max.html [L]
RewriteRule ^/$ /homepage.min.html [L]
RewriteRule ^/$ /homepage.std.html [L]
href="http://www.perldoc.com/perl5.6.1/pod/perlre.html">perldoc
'<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
^/somepath(.*) http://thishost/otherpath$1 [P] not supported, because silly!
^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo
^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
^localpath(.*) http://thishost/otherpath$1 [P] not supported, because silly!