mod_rewrite.xml revision 06d3a46db9574ad55b65fed36b856fee72bd71a7
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<!-- $LastChangedRevision$ -->
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher Licensed to the Apache Software Foundation (ASF) under one or more
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher contributor license agreements. See the NOTICE file distributed with
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher this work for additional information regarding copyright ownership.
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher The ASF licenses this file to You under the Apache License, Version 2.0
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher (the "License"); you may not use this file except in compliance with
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher the License. You may obtain a copy of the License at
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher http://www.apache.org/licenses/LICENSE-2.0
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher Unless required by applicable law or agreed to in writing, software
7b58d637c20f87e1e49ffc1d49a4de8b25ef06bbJakub Hrozek distributed under the License is distributed on an "AS IS" BASIS,
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher See the License for the specific language governing permissions and
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher limitations under the License.
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<modulesynopsis metafile="mod_rewrite.xml.meta">
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<description>Provides a rule-based rewriting engine to rewrite requested
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen GallagherURLs on the fly</description>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<compatibility>Available in Apache 1.3 and later</compatibility>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>This module uses a rule-based rewriting engine (based on a
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher regular-expression parser) to rewrite requested URLs on the
133ee2239498b4c4fd95e509b72f2e9ef2620584Justin Stephenson fly. It supports an unlimited number of rules and an
133ee2239498b4c4fd95e509b72f2e9ef2620584Justin Stephenson unlimited number of attached rule conditions for each rule, to
133ee2239498b4c4fd95e509b72f2e9ef2620584Justin Stephenson provide a really flexible and powerful URL manipulation
346d6d8bf5fdb446921d754c07c8a7d913a048d5René Genz mechanism. The URL manipulations can depend on various tests,
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher of server variables, environment variables, HTTP
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher headers, or time stamps. Even external database lookups in
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher various formats can be used to achieve highly granular URL
728a1812b7c5f70febb522342c5b357da598acfeJakub Hrozek <p>This module operates on the full URLs (including the
f20c082881ba287c5de415b983c1e54fee987b4bDan Lavu path-info part) both in per-server context
f20c082881ba287c5de415b983c1e54fee987b4bDan Lavu (<code>httpd.conf</code>) and per-directory context
f20c082881ba287c5de415b983c1e54fee987b4bDan Lavu (<code>.htaccess</code>) and can generate query-string
f20c082881ba287c5de415b983c1e54fee987b4bDan Lavu parts on result. The rewritten result can lead to internal
728a1812b7c5f70febb522342c5b357da598acfeJakub Hrozek sub-processing, external request redirection or even to an
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher internal proxy throughput.</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>Further details, discussion, and examples, are provided in the
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <a href="/rewrite/">detailed mod_rewrite documentation</a>.</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<seealso><a href="#rewriteflags">Rewrite Flags</a></seealso>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<section id="quoting"><title>Quoting Special Characters</title>
6e27e8572f671de575d9ac2a34a677d9efc24fbcJustin Stephenson <p>As of Apache 1.3.20, special characters in
6e27e8572f671de575d9ac2a34a677d9efc24fbcJustin Stephenson <em>TestString</em> and <em>Substitution</em> strings can be
6e27e8572f671de575d9ac2a34a677d9efc24fbcJustin Stephenson escaped (that is, treated as normal characters without their
6e27e8572f671de575d9ac2a34a677d9efc24fbcJustin Stephenson usual special meaning) by prefixing them with a slash ('\')
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher character. In other words, you can include an actual
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher dollar-sign character in a <em>Substitution</em> string by
6e27e8572f671de575d9ac2a34a677d9efc24fbcJustin Stephenson using '<code>\$</code>'; this keeps mod_rewrite from trying
6e27e8572f671de575d9ac2a34a677d9efc24fbcJustin Stephenson to treat it as a backreference.</p>
6e27e8572f671de575d9ac2a34a677d9efc24fbcJustin Stephenson<section id="EnvVar"><title>Environment Variables</title>
03b859510dc13a13a456ca4aa94c0561a0e9684cJakub Hrozek <p>This module keeps track of two additional (non-standard)
03b859510dc13a13a456ca4aa94c0561a0e9684cJakub Hrozek CGI/SSI environment variables named <code>SCRIPT_URL</code>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher and <code>SCRIPT_URI</code>. These contain the
89ed594e8800fdb288248006e8867a077a57bc6fJakub Hrozek <em>logical</em> Web-view to the current resource, while the
89ed594e8800fdb288248006e8867a077a57bc6fJakub Hrozek standard CGI/SSI variables <code>SCRIPT_NAME</code> and
89ed594e8800fdb288248006e8867a077a57bc6fJakub Hrozek <code>SCRIPT_FILENAME</code> contain the <em>physical</em>
89ed594e8800fdb288248006e8867a077a57bc6fJakub Hrozek System-view. </p>
89ed594e8800fdb288248006e8867a077a57bc6fJakub Hrozek <p>Notice: These variables hold the URI/URL <em>as they were
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher initially requested</em>, that is, <em>before</em> any
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher rewriting. This is important to note because the rewriting process is
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher primarily used to rewrite logical URLs to physical
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher pathnames.</p>
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen GallagherSCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
346d6d8bf5fdb446921d754c07c8a7d913a048d5René Genz<section id="vhosts"><title>Rewriting in Virtual Hosts</title>
a72919af8347b5bbc65a3b1fb3e5d31447240b24Jakub Hrozek <p>By default, <module>mod_rewrite</module> configuration
4ab8734cc45fab2d1a0e690b566da1bda63df76cFabiano Fidêncio settings from the main server context are not inherited by
4ab8734cc45fab2d1a0e690b566da1bda63df76cFabiano Fidêncio virtual hosts. To make the main server settings apply to virtual
4ab8734cc45fab2d1a0e690b566da1bda63df76cFabiano Fidêncio hosts, you must place the following directives in each <directive
4343b618051d295cbb1a805a85feb117a91c6945Jakub Hrozek module="core" type="section">VirtualHost</directive> section:</p>
c7a4383b3b5549d0627c21bb02bd5f0bd46a3531Jakub Hrozek RewriteEngine On<br />
c7a4383b3b5549d0627c21bb02bd5f0bd46a3531Jakub Hrozek RewriteOptions Inherit
65a8e6e655c22027d3e02ea697972111f2a33e33Jakub Hrozek<section id="Solutions"><title>Practical Solutions</title>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>For numerous examples of common, and not-so-common, uses for
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher mod_rewrite, see the <a href="/rewrite/rewrite_guide.html">Rewrite
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher href="/rewrite/rewrite_guide_advanced.html">Advanced Rewrite
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<directivesynopsis>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<description>Enables or disables runtime rewriting engine</description>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<contextlist><context>server config</context><context>virtual host</context>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<context>directory</context><context>.htaccess</context></contextlist>
4cdaf239d4504966bed8ecd5e3fa07def74c7302Sumit Bose <p>The <directive>RewriteEngine</directive> directive enables or
4cdaf239d4504966bed8ecd5e3fa07def74c7302Sumit Bose disables the runtime rewriting engine. If it is set to
4cdaf239d4504966bed8ecd5e3fa07def74c7302Sumit Bose <code>off</code> this module does no runtime processing at
4cdaf239d4504966bed8ecd5e3fa07def74c7302Sumit Bose all. It does not even update the <code>SCRIPT_URx</code>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher environment variables.</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>Use this directive to disable the module instead of
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech commenting out all the <directive
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech module="mod_rewrite">RewriteRule</directive> directives!</p>
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech <p>Note that rewrite configurations are not
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech inherited by virtual hosts. This means that you need to have a
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech <code>RewriteEngine on</code> directive for each virtual host
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech in which you wish to use rewrite rules.</p>
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech</directivesynopsis>
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech<directivesynopsis>
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech<description>Sets some special options for the rewrite engine</description>
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech<contextlist><context>server config</context><context>virtual host</context>
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech<context>directory</context><context>.htaccess</context></contextlist>
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech<compatibility><code>MaxRedirects</code> is no longer available in version 2.1 and
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cechlater</compatibility>
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech <p>The <directive>RewriteOptions</directive> directive sets some
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech special options for the current per-server or per-directory
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech configuration. The <em>Option</em> string can currently
d6342c92c226becbdd254f90a0005b8c00c300dcPetr Cech only be one of the following:</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <dd>This forces the current configuration to inherit the
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher configuration of the parent. In per-virtual-server context,
02ec52b73c1714b877b0b7bc43fbc8d36ad8ca40Jakub Hrozek this means that the maps, conditions and rules of the main
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher server are inherited. In per-directory context this means
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher that conditions and rules of the parent directory's
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <code>.htaccess</code> configuration are inherited.</dd>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher</directivesynopsis>
c0d9babd59c81c12ca182ab3a72176d4fae494a4Yuri Chornoivan<directivesynopsis>
f20c082881ba287c5de415b983c1e54fee987b4bDan Lavu<description>Sets the name of the file used for logging rewrite engine
f20c082881ba287c5de415b983c1e54fee987b4bDan Lavuprocessing</description>
f20c082881ba287c5de415b983c1e54fee987b4bDan Lavu<contextlist><context>server config</context><context>virtual host</context>
f20c082881ba287c5de415b983c1e54fee987b4bDan Lavu</contextlist>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>The <directive>RewriteLog</directive> directive sets the name
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher of the file to which the server logs any rewriting actions it
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher performs. If the name does not begin with a slash
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher ('<code>/</code>') then it is assumed to be relative to the
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <em>Server Root</em>. The directive should occur only once per
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher server config.</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<note> To disable the logging of
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher rewriting actions it is not recommended to set
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <em>Filename</em> to <code>/dev/null</code>, because
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher although the rewriting engine does not then output to a
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher logfile it still creates the logfile output internally.
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <strong>This will slow down the server with no advantage
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher to the administrator!</strong> To disable logging either
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher remove or comment out the <directive>RewriteLog</directive>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher directive or use <code>RewriteLogLevel 0</code>!
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina<note type="securitywarning"><title>Security</title>
a679f0167b646cffdae86546ed77e105576991b0Pavel BřezinaSee the <a href="/misc/security_tips.html">Apache Security Tips</a>
a679f0167b646cffdae86546ed77e105576991b0Pavel Březinadocument for details on how your security could be compromised if the
a679f0167b646cffdae86546ed77e105576991b0Pavel Březinadirectory where logfiles are stored is writable by anyone other than
a679f0167b646cffdae86546ed77e105576991b0Pavel Březinathe user that starts the server.
a679f0167b646cffdae86546ed77e105576991b0Pavel BřezinaRewriteLog "/usr/local/var/apache/logs/rewrite.log"
de4ce3477497c20416c6397adb520bb60f3c6d28Jakub Hrozek</directivesynopsis>
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina<directivesynopsis>
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina<description>Sets the verbosity of the log file used by the rewrite
a679f0167b646cffdae86546ed77e105576991b0Pavel Březinaengine</description>
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina<syntax>RewriteLogLevel <em>Level</em></syntax>
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina<contextlist><context>server config</context><context>virtual host</context>
8a05fd320a44636d120a18eb7e9956c7b35b3138Jakub Hrozek</contextlist>
8a05fd320a44636d120a18eb7e9956c7b35b3138Jakub Hrozek <p>The <directive>RewriteLogLevel</directive> directive sets the
8a05fd320a44636d120a18eb7e9956c7b35b3138Jakub Hrozek verbosity level of the rewriting logfile. The default level 0
8a05fd320a44636d120a18eb7e9956c7b35b3138Jakub Hrozek means no logging, while 9 or more means that practically all
8a05fd320a44636d120a18eb7e9956c7b35b3138Jakub Hrozek actions are logged.</p>
8a05fd320a44636d120a18eb7e9956c7b35b3138Jakub Hrozek <p>To disable the logging of rewriting actions simply set
8a05fd320a44636d120a18eb7e9956c7b35b3138Jakub Hrozek <em>Level</em> to 0. This disables all rewrite action
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek<note> Using a high value for
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek <em>Level</em> will slow down your Apache server
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek dramatically! Use the rewriting logfile at a
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek <em>Level</em> greater than 2 only for debugging!
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub HrozekRewriteLogLevel 3
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek</directivesynopsis>
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek<directivesynopsis>
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek<description>Sets the name of the lock file used for <directive
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozeksynchronization</description>
cf5357ae83cc9fe2240038b8bdccec2cb98991fcMike Ely<contextlist><context>server config</context></contextlist>
cf5357ae83cc9fe2240038b8bdccec2cb98991fcMike Ely <p>This directive sets the filename for a synchronization
cf5357ae83cc9fe2240038b8bdccec2cb98991fcMike Ely lockfile which mod_rewrite needs to communicate with <directive
cf5357ae83cc9fe2240038b8bdccec2cb98991fcMike Ely <em>programs</em>. Set this lockfile to a local path (not on a
cf5357ae83cc9fe2240038b8bdccec2cb98991fcMike Ely NFS-mounted device) when you want to use a rewriting
cf5357ae83cc9fe2240038b8bdccec2cb98991fcMike Ely map-program. It is not required for other types of rewriting
cf5357ae83cc9fe2240038b8bdccec2cb98991fcMike Ely</directivesynopsis>
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek<directivesynopsis>
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek<description>Defines a mapping function for key-lookup</description>
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek<syntax>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek<contextlist><context>server config</context><context>virtual host</context>
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek</contextlist>
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek<compatibility>The choice of different dbm types is available in
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub HrozekApache 2.0.41 and later</compatibility>
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek <p>The <directive>RewriteMap</directive> directive defines a
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek <em>Rewriting Map</em> which can be used inside rule
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek substitution strings by the mapping-functions to
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek insert/substitute fields through a key lookup. The source of
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek this lookup can be of various types.</p>
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
1ce58f139699dd26b8888f4131c996263b6a80a5Jakub Hrozek the name of the map and will be used to specify a
cf5357ae83cc9fe2240038b8bdccec2cb98991fcMike Ely mapping-function for the substitution strings of a rewriting
cf5357ae83cc9fe2240038b8bdccec2cb98991fcMike Ely rule via one of the following constructs:</p>
8a05fd320a44636d120a18eb7e9956c7b35b3138Jakub Hrozek <strong><code>${</code> <em>MapName</em> <code>:</code>
8a05fd320a44636d120a18eb7e9956c7b35b3138Jakub Hrozek <code>${</code> <em>MapName</em> <code>:</code>
8a05fd320a44636d120a18eb7e9956c7b35b3138Jakub Hrozek <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
b22e0da9e644f5eb84ee0c8986979fec3fe7eb56Pavel Reichl <p>When such a construct occurs, the map <em>MapName</em> is
b22e0da9e644f5eb84ee0c8986979fec3fe7eb56Pavel Reichl consulted and the key <em>LookupKey</em> is looked-up. If the
b22e0da9e644f5eb84ee0c8986979fec3fe7eb56Pavel Reichl key is found, the map-function construct is substituted by
b22e0da9e644f5eb84ee0c8986979fec3fe7eb56Pavel Reichl <em>SubstValue</em>. If the key is not found then it is
b22e0da9e644f5eb84ee0c8986979fec3fe7eb56Pavel Reichl substituted by <em>DefaultValue</em> or by the empty string
b22e0da9e644f5eb84ee0c8986979fec3fe7eb56Pavel Reichl <p>For example, you might define a
b22e0da9e644f5eb84ee0c8986979fec3fe7eb56Pavel Reichl RewriteMap examplemap txt:/path/to/file/map.txt
ba4a81e933deebb416603369b447ead6ebaa040dJakub Hrozek <p>You would then be able to use this map in a
ba4a81e933deebb416603369b447ead6ebaa040dJakub Hrozek <directive>RewriteRule</directive> as follows:</p>
fdaaf2525e333af04ee9b48429b6766b5fd6cab6Jakub Hrozek RewriteRule ^/ex/(.*) ${examplemap:$1}
fdaaf2525e333af04ee9b48429b6766b5fd6cab6Jakub Hrozek <p>The following combinations for <em>MapType</em> and
fdaaf2525e333af04ee9b48429b6766b5fd6cab6Jakub Hrozek MapType: <code>txt</code>, MapSource: Unix filesystem
fdaaf2525e333af04ee9b48429b6766b5fd6cab6Jakub Hrozek path to valid regular file
fdaaf2525e333af04ee9b48429b6766b5fd6cab6Jakub Hrozek <p>This is the standard rewriting map feature where the
ba4a81e933deebb416603369b447ead6ebaa040dJakub Hrozek <em>MapSource</em> is a plain ASCII file containing
ba4a81e933deebb416603369b447ead6ebaa040dJakub Hrozek either blank lines, comment lines (starting with a '#'
ba4a81e933deebb416603369b447ead6ebaa040dJakub Hrozek character) or pairs like the following - one per
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley## map.txt -- rewriting map
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir ElleyRalf.S.Engelschall rse # Bastard Operator From Hell
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir ElleyMr.Joe.Average joe # Mr. Average
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir ElleyRewriteMap real-to-user txt:/path/to/file/map.txt
6c1661d2f4e860d1b547d6188a4fe2bd564e87cfMichal Židek MapType: <code>rnd</code>, MapSource: Unix filesystem
6c1661d2f4e860d1b547d6188a4fe2bd564e87cfMichal Židek path to valid regular file
6c1661d2f4e860d1b547d6188a4fe2bd564e87cfMichal Židek <p>This is identical to the Standard Plain Text variant
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley above but with a special post-processing feature: After
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley looking up a value it is parsed according to contained
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley ``<code>|</code>'' characters which have the meaning of
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley ``or''. In other words they indicate a set of
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley alternatives from which the actual returned value is
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley chosen randomly. For example, you might use the following map
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley file and directives to provide a random load balancing between
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley several back-end server, via a reverse-proxy. Images are sent
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley to one of the servers in the 'static' pool, while everything
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley else is sent to one of the 'dynamic' pool.</p>
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley## map.txt -- rewriting map
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elleystatic www1|www2|www3|www4
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elleydynamic www5|www6
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley<example><title>Configuration directives</title>
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir ElleyRewriteMap servers rnd:/path/to/file/map.txt<br />
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir ElleyRewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley[NC,P,L]<br />
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir ElleyRewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley <code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley path to valid regular file
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley <p>Here the source is a binary format DBM file containing
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley the same contents as a <em>Plain Text</em> format file, but
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley in a special representation which is optimized for really
772464c842968d6e544118ae1aa7c49a7cda2ad6Stephen Gallagher fast lookups. The <em>type</em> can be sdbm, gdbm, ndbm, or
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley db depending on <a href="/install.html#dbm">compile-time
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley settings</a>. If the <em>type</em> is omitted, the
772464c842968d6e544118ae1aa7c49a7cda2ad6Stephen Gallagher compile-time default will be chosen.</p>
772464c842968d6e544118ae1aa7c49a7cda2ad6Stephen Gallagher <p>To create a dbm file from a source text file, use the <a
60cab26b12df9a2153823972cde0c38ca86e01b9Yassir Elley href="/programs/httxt2dbm.html">httxt2dbm</a> utility.</p>
ff4b603cc14ea6ea15caaf89a03e927920124af4Yassir Elley MapType: <code>int</code>, MapSource: Internal Apache
ff4b603cc14ea6ea15caaf89a03e927920124af4Yassir Elley <p>Here, the source is an internal Apache function.
ff4b603cc14ea6ea15caaf89a03e927920124af4Yassir Elley Currently you cannot create your own, but the following
ff4b603cc14ea6ea15caaf89a03e927920124af4Yassir Elley functions already exist:</p>
ff4b603cc14ea6ea15caaf89a03e927920124af4Yassir Elley Converts the key to all upper case.</li>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley Converts the key to all lower case.</li>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley Translates special characters in the key to
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley hex-encodings.</li>
01fa6711add8c52aa1a8474cf34af67d1e555c91Dan Lavu Translates hex-encodings in the key back to
ab11b2573a9582fa211ef68713ba50fd28dbb75fJakub Hrozek special characters.</li>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <strong>External Rewriting Program</strong><br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley MapType: <code>prg</code>, MapSource: Unix filesystem
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley path to valid regular file
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <p>Here the source is a program, not a map file. To
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley create it you can use a language of your choice, but
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley the result has to be an executable program (either
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley object-code or a script with the magic cookie trick
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley '<code>#!/path/to/interpreter</code>' as the first
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <p>This program is started once, when the Apache server
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley is started, and then communicates with the rewriting engine
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley via its <code>stdin</code> and <code>stdout</code>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley file-handles. For each map-function lookup it will
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley receive the key to lookup as a newline-terminated string
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley on <code>stdin</code>. It then has to give back the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley looked-up value as a newline-terminated string on
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <code>stdout</code> or the four-character string
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley is no corresponding value for the given key). A trivial
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley program which will implement a 1:1 map (<em>i.e.</em>,
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley key == value) could be:</p>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elleywhile (<STDIN>) {
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley # ...put here any transformations or lookups...
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <li>``<em>Keep it simple, stupid</em>'' (KISS).
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley If this program hangs, it will cause Apache to hang
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley when trying to use the relevant rewrite rule.</li>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <li>A common mistake is to use buffered I/O on
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <code>stdout</code>. Avoid this, as it will cause a deadloop!
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley ``<code>$|=1</code>'' is used above, to prevent this.</li>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley module="mod_rewrite">RewriteLock</directive> directive can
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley be used to define a lockfile which mod_rewrite can use to synchronize
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley communication with the mapping program. By default no such
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen Gallagher synchronization takes place.</li>
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen Gallagher MapType: <code>dbd</code> or <code>fastdbd</code>,
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen Gallagher MapSource: An SQL SELECT statement that takes a single
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen Gallagher argument and returns a single value.</p>
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen Gallagher <p>This uses <module>mod_dbd</module> to implement a rewritemap
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen Gallagher by lookup in an SQL database. There are two forms:
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen Gallagher <code>fastdbd</code> caches database lookups internally,
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen Gallagher <code>dbd</code> doesn't. So <code>dbd</code> incurs a
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen Gallagher performance penalty but responds immediately if the database
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen Gallagher contents are updated, while <code>fastdbd</code> is more
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen Gallagher efficient but won't re-read database contents until server
89376da80b2250b82d256ea85ec349ce29fe5b51Stephen Gallagher <p>If a query returns more than one row, a random row from
89376da80b2250b82d256ea85ec349ce29fe5b51Stephen Gallagher the result set is used.</p>
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen GallagherRewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
293cf52a00c9c67f0ad8f264027f81c020854f66Stephen Gallagher <p>The <directive>RewriteMap</directive> directive can occur more than
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley once. For each mapping-function use one
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <directive>RewriteMap</directive> directive to declare its rewriting
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley mapfile. While you cannot <strong>declare</strong> a map in
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley per-directory context it is of course possible to
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <strong>use</strong> this map in per-directory context. </p>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley<note><title>Note</title> For plain text and DBM format files the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elleylooked-up keys are cached in-core until the <code>mtime</code> of the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elleymapfile changes or the server does a restart. This way you can have
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elleymap-functions in rules which are used for <strong>every</strong>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elleyrequest. This is no problem, because the external lookup only happens
01fa6711add8c52aa1a8474cf34af67d1e555c91Dan Lavu</directivesynopsis>
01fa6711add8c52aa1a8474cf34af67d1e555c91Dan Lavu<directivesynopsis>
01fa6711add8c52aa1a8474cf34af67d1e555c91Dan Lavu<description>Sets the base URL for per-directory rewrites</description>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley<contextlist><context>directory</context><context>.htaccess</context>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley</contextlist>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <p>The <directive>RewriteBase</directive> directive explicitly
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley sets the base URL for per-directory rewrites. As you will see
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley below, <directive module="mod_rewrite">RewriteRule</directive>
ecf9e7a870945ecfba8eb751d344de3601de9424Lukas Slebodnik can be used in per-directory config files
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley (<code>.htaccess</code>). In such a case, it will act locally,
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley stripping the local directory prefix before processing, and applying
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley rewrite rules only to the remainder. When processing is complete, the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley prefix is automatically added back to the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley path. The default setting is; <directive>RewriteBase</directive> <em>physical-directory-path</em></p>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <p>When a substitution occurs for a new URL, this module has
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley to re-inject the URL into the server processing. To be able
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley to do this it needs to know what the corresponding URL-prefix
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley or URL-base is. By default this prefix is the corresponding
0e799bc491f636c69657d1678af13d23bf7b7c10Stephen Gallagher filepath itself. <strong>However, for most websites, URLs are NOT
0e799bc491f636c69657d1678af13d23bf7b7c10Stephen Gallagher directly related to physical filename paths, so this
0e799bc491f636c69657d1678af13d23bf7b7c10Stephen Gallagher assumption will often be wrong!</strong> Therefore, you can
0e799bc491f636c69657d1678af13d23bf7b7c10Stephen Gallagher use the <code>RewriteBase</code> directive to specify the
0e799bc491f636c69657d1678af13d23bf7b7c10Stephen Gallagher correct URL-prefix.</p>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley<note> If your webserver's URLs are <strong>not</strong> directly
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elleyrelated to physical file paths, you will need to use
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley<directive>RewriteBase</directive> in every <code>.htaccess</code>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elleyfile where you want to use <directive
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elleymodule="mod_rewrite">RewriteRule</directive> directives.
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <p> For example, assume the following per-directory config file:</p>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley# /abc/def/.htaccess -- per-dir config file for directory /abc/def
ab11b2573a9582fa211ef68713ba50fd28dbb75fJakub Hrozek# Remember: /abc/def is the physical path of /xyz, <em>i.e.</em>, the server
ab11b2573a9582fa211ef68713ba50fd28dbb75fJakub Hrozek# has a 'Alias /xyz /abc/def' directive <em>e.g.</em>
ab11b2573a9582fa211ef68713ba50fd28dbb75fJakub HrozekRewriteEngine On
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley# let the server know that we were reached via /xyz and not
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir ElleyRewriteBase /xyz
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley# now the rewriting rules
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir ElleyRewriteRule ^oldstuff\.html$ newstuff.html
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <p>In the above example, a request to
ecf9e7a870945ecfba8eb751d344de3601de9424Lukas Slebodnik <code>/xyz/oldstuff.html</code> gets correctly rewritten to
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley the physical file <code>/abc/def/newstuff.html</code>.</p>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley<p>The following list gives detailed information about
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley the internal processing steps:</p>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir ElleyInternal Processing:
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias)
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule)
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase)
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias)
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <p>This seems very complicated, but is in fact
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley correct Apache internal processing. Because the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley per-directory rewriting comes late in the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley process, the rewritten request
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley has to be re-injected into the Apache kernel.
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley This is not the serious overhead it may seem to be -
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley this re-injection is completely internal to the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley Apache server (and the same procedure is used by
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley many other operations within Apache).</p>
ab11b2573a9582fa211ef68713ba50fd28dbb75fJakub Hrozek</directivesynopsis>
ab11b2573a9582fa211ef68713ba50fd28dbb75fJakub Hrozek<directivesynopsis>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley<description>Defines a condition under which rewriting will take place
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley</description>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley<syntax> RewriteCond
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <em>TestString</em> <em>CondPattern</em></syntax>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley<contextlist><context>server config</context><context>virtual host</context>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley<context>directory</context><context>.htaccess</context></contextlist>
ecf9e7a870945ecfba8eb751d344de3601de9424Lukas Slebodnik <p>The <directive>RewriteCond</directive> directive defines a
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley rule condition. One or more <directive>RewriteCond</directive>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley can precede a <directive module="mod_rewrite">RewriteRule</directive>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley directive. The following rule is then only used if both
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley the current state of the URI matches its pattern, <strong
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <p><em>TestString</em> is a string which can contain the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley following expanded constructs in addition to plain text:</p>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <strong>RewriteRule backreferences</strong>: These are
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley backreferences of the form <strong><code>$N</code></strong>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley (0 <= N <= 9), which provide access to the grouped
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley parts (in parentheses) of the pattern, from the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <code>RewriteRule</code> which is subject to the current
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <strong>RewriteCond backreferences</strong>: These are
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley backreferences of the form <strong><code>%N</code></strong>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley (1 <= N <= 9), which provide access to the grouped
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley parts (again, in parentheses) of the pattern, from the last matched
ab11b2573a9582fa211ef68713ba50fd28dbb75fJakub Hrozek of conditions.
ab11b2573a9582fa211ef68713ba50fd28dbb75fJakub Hrozek <strong>RewriteMap expansions</strong>: These are
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley RewriteMap</a> for more details.
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <strong>Server-Variables</strong>: These are variables of
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <strong><code>%{</code> <em>NAME_OF_VARIABLE</em>
ecf9e7a870945ecfba8eb751d344de3601de9424Lukas Slebodnik where <em>NAME_OF_VARIABLE</em> can be a string taken
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley from the following list:
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <columnspec><column width=".3"/><column width=".3"/>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <th>HTTP headers:</th> <th>connection & request:</th> <th></th>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley HTTP_USER_AGENT<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley HTTP_REFERER<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley HTTP_COOKIE<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley HTTP_FORWARDED<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley HTTP_HOST<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley HTTP_PROXY_CONNECTION<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley HTTP_ACCEPT<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley REMOTE_ADDR<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley REMOTE_HOST<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley REMOTE_PORT<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley REMOTE_USER<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley REMOTE_IDENT<br />
ecf9e7a870945ecfba8eb751d344de3601de9424Lukas Slebodnik REQUEST_METHOD<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley SCRIPT_FILENAME<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley PATH_INFO<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley QUERY_STRING<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley AUTH_TYPE<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <th>server internals:</th> <th>date and time:</th> <th>specials:</th>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley DOCUMENT_ROOT<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley SERVER_ADMIN<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley SERVER_NAME<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley SERVER_ADDR<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley SERVER_PORT<br />
b49c6abe12721ee8442be1c1bd6c15443b518ca2Pavel Reichl SERVER_PROTOCOL<br />
b49c6abe12721ee8442be1c1bd6c15443b518ca2Pavel Reichl SERVER_SOFTWARE<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley TIME_YEAR<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley TIME_MON<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley TIME_DAY<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley TIME_HOUR<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley TIME_MIN<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley TIME_SEC<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley TIME_WDAY<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley API_VERSION<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley THE_REQUEST<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley REQUEST_URI<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley REQUEST_FILENAME<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley IS_SUBREQ<br />
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <p>These variables all
ecf9e7a870945ecfba8eb751d344de3601de9424Lukas Slebodnik correspond to the similarly named HTTP
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley MIME-headers, C variables of the Apache server or
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <code>struct tm</code> fields of the Unix system.
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley Most are documented elsewhere in the Manual or in
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley the CGI specification. Those that are special to
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley mod_rewrite include those below.</p>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <dd>Will contain the text "true" if the request
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley currently being processed is a sub-request,
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley "false" otherwise. Sub-requests may be generated
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley by modules that need to resolve additional files
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley or URIs in order to complete their tasks.</dd>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <dd>This is the version of the Apache module API
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley (the internal interface between server and
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley module) in the current httpd build, as defined in
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley corresponds to the version of Apache in use (in
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley the release version of Apache 1.3.14, for
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley instance, it is 19990320:10), but is mainly of
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley interest to module authors.</dd>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <dd>The full HTTP request line sent by the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley include any additional headers sent by the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley browser.</dd>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <dd>The resource requested in the HTTP request
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley line. (In the example above, this would be
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <dd>The full local filesystem path to the file or
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley script matching the request.</dd>
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <dd>Will contain the text "on" if the connection is
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley using SSL/TLS, or "off" otherwise. (This variable
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley can be safely used regardless of whether or not
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <li>The variables SCRIPT_FILENAME and REQUEST_FILENAME
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley contain the same value - the value of the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <code>request_rec</code> structure of the Apache server.
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley The first name is the commonly known CGI variable name
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley while the second is the appropriate counterpart of
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley REQUEST_URI (which contains the value of the
f2b40ec8a4158fec75873828e4980965abbe7f66Yassir Elley <code>uri</code> field of <code>request_rec</code>).</li>
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose <code>%{ENV:variable}</code>, where <em>variable</em> can be
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose any environment variable, is also available.
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose This is looked-up via internal
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose Apache structures and (if not found there) via
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose <code>getenv()</code> from the Apache server process.</li>
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose <code>%{SSL:variable}</code>, where <em>variable</em> is the
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose name of an <a href="mod_ssl.html#envvars">SSL environment
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose variable</a>, can be used whether or not
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose <module>mod_ssl</module> is loaded, but will always expand to
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose the empty string if it is not. Example:
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose <code>%{SSL:SSL_CIPHER_USEKEYSIZE}</code> may expand to
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose <code>%{HTTP:header}</code>, where <em>header</em> can be
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose any HTTP MIME-header name, can always be used to obtain the
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose value of a header sent in the HTTP request.
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose Example: <code>%{HTTP:Proxy-Connection}</code> is
ba2fb2c7b74a5247737da051b38e7889b7b44d5dYuri Chornoivan the value of the HTTP header
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose <p>If a HTTP header is used in a condition this header is added to
77e5c3fc26085f18277a70ffbd6351a8130963e7Yuri Chornoivan the Vary header of the response in case the condition evaluates to
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose to true for the request. It is <strong>not</strong> added if the
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose condition evaluates to false for the request. Adding the HTTP header
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose to the Vary header of the response is needed for proper caching.</p>
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose <p>It has to be kept in mind that conditions follow a short circuit
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose logic in the case of the '<strong><code>ornext|OR</code></strong>' flag
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose so that certain conditions might not be evaluated at all.</p></li>
5f7cd30c865046a7ea69944f7e07c85b4c43465aSumit Bose <code>%{LA-U:variable}</code> can be used for look-aheads which perform
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek an internal (URL-based) sub-request to determine the final
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek value of <em>variable</em>. This can be used to access
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek variable for rewriting which is not available at the current
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek stage, but will be set in a later phase.
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <p>For instance, to rewrite according to the
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <code>REMOTE_USER</code> variable from within the
31c1f3a2e699fad82258aab83d756e1e7ca923a2Jakub Hrozek per-server context (<code>httpd.conf</code> file) you must
31c1f3a2e699fad82258aab83d756e1e7ca923a2Jakub Hrozek variable is set by the authorization phases, which come
593c4a91596640eafe798e8aac700d0f3ce7ba37Ondrej Kos <em>after</em> the URL translation phase (during which mod_rewrite
593c4a91596640eafe798e8aac700d0f3ce7ba37Ondrej Kos operates).</p>
593c4a91596640eafe798e8aac700d0f3ce7ba37Ondrej Kos <p>On the other hand, because mod_rewrite implements
593c4a91596640eafe798e8aac700d0f3ce7ba37Ondrej Kos its per-directory context (<code>.htaccess</code> file) via
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek the Fixup phase of the API and because the authorization
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek phases come <em>before</em> this phase, you just can use
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <code>%{REMOTE_USER}</code> in that context.</p></li>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <code>%{LA-F:variable}</code> can be used to perform an internal
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek (filename-based) sub-request, to determine the final value
ad1be6fd04234f61f108773ff39aa7485abda47cJakub Hrozek of <em>variable</em>. Most of the time, this is the same as
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek LA-U above.</li>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <p><em>CondPattern</em> is the condition pattern,
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek a regular expression which is applied to the
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <em>TestString</em> is first evaluated, before being matched against
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <p><strong>Remember:</strong> <em>CondPattern</em> is a
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <em>perl compatible regular expression</em> with some
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek additions:</p>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <li>You can prefix the pattern string with a
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek '<code>!</code>' character (exclamation mark) to specify a
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek There are some special variants of <em>CondPatterns</em>.
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek Instead of real regular expression strings you can also
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek use one of the following:
038b9ba28a618e3e553803da632116a040b94034Pavel Reichl <li>'<strong><CondPattern</strong>' (lexicographically
0a26e92fb2a4dd9704a0578f90241997e2aed269Pavel Reichl precedes)<br />
0a26e92fb2a4dd9704a0578f90241997e2aed269Pavel Reichl Treats the <em>CondPattern</em> as a plain string and
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek compares it lexicographically to <em>TestString</em>. True if
702176303382b5a385e90fe68ad2c32bd708ebf1Pavel Reichl <li>'<strong>>CondPattern</strong>' (lexicographically
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek follows)<br />
038b9ba28a618e3e553803da632116a040b94034Pavel Reichl Treats the <em>CondPattern</em> as a plain string and
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek compares it lexicographically to <em>TestString</em>. True if
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <li>'<strong>=CondPattern</strong>' (lexicographically
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek equal)<br />
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek Treats the <em>CondPattern</em> as a plain string and
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek compares it lexicographically to <em>TestString</em>. True if
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <em>TestString</em> is lexicographically equal to
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <em>CondPattern</em> (the two strings are exactly
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek equal, character for character). If <em>CondPattern</em>
dfbbe39f49ba3f7ff64370fecef971f091214d47Amith Kumar compares <em>TestString</em> to the empty string.</li>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek Treats the <em>TestString</em> as a pathname and tests
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek whether or not it exists, and is a directory.</li>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek Treats the <em>TestString</em> as a pathname and tests
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek whether or not it exists, and is a regular file.</li>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <li>'<strong>-s</strong>' (is regular file, with
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek Treats the <em>TestString</em> as a pathname and tests
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek whether or not it exists, and is a regular file with size greater
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek than zero.</li>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek Treats the <em>TestString</em> as a pathname and tests
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek whether or not it exists, and is a symbolic link.</li>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <li>'<strong>-x</strong>' (has e<strong>x</strong>ecutable
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek permissions)<br />
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek Treats the <em>TestString</em> as a pathname and tests
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek whether or not it exists, and has executable permissions.
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek These permissions are determined according to
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek the underlying OS.</li>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <li>'<strong>-F</strong>' (is existing file, via
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek subrequest)<br />
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek Checks whether or not <em>TestString</em> is a valid file,
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek accessible via all the server's currently-configured
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek access controls for that path. This uses an internal
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek subrequest to do the check, so use it with care -
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek it can impact your server's performance!</li>
5424b90e870cf2b9d379df185cb6893c7f8b040cJustin Stephenson <li>'<strong>-U</strong>' (is existing URL, via
5424b90e870cf2b9d379df185cb6893c7f8b040cJustin Stephenson subrequest)<br />
5424b90e870cf2b9d379df185cb6893c7f8b040cJustin Stephenson Checks whether or not <em>TestString</em> is a valid URL,
5424b90e870cf2b9d379df185cb6893c7f8b040cJustin Stephenson accessible via all the server's currently-configured
5424b90e870cf2b9d379df185cb6893c7f8b040cJustin Stephenson access controls for that path. This uses an internal
5424b90e870cf2b9d379df185cb6893c7f8b040cJustin Stephenson subrequest to do the check, so use it with care -
5424b90e870cf2b9d379df185cb6893c7f8b040cJustin Stephenson it can impact your server's performance!</li>
5424b90e870cf2b9d379df185cb6893c7f8b040cJustin Stephenson All of these tests can
5424b90e870cf2b9d379df185cb6893c7f8b040cJustin Stephenson also be prefixed by an exclamation mark ('!') to
5424b90e870cf2b9d379df185cb6893c7f8b040cJustin Stephenson negate their meaning.
8145ab51b05aa86b2f1a21b49383f55e50b0a2e3Jakub Hrozek <li>You can also set special flags for
8145ab51b05aa86b2f1a21b49383f55e50b0a2e3Jakub Hrozek <strong><code>[</code><em>flags</em><code>]</code></strong>
8145ab51b05aa86b2f1a21b49383f55e50b0a2e3Jakub Hrozek as the third argument to the <code>RewriteCond</code>
8145ab51b05aa86b2f1a21b49383f55e50b0a2e3Jakub Hrozek directive, where <em>flags</em> is a comma-separated list of any of the
8145ab51b05aa86b2f1a21b49383f55e50b0a2e3Jakub Hrozek following flags:
8145ab51b05aa86b2f1a21b49383f55e50b0a2e3Jakub Hrozek (<strong>n</strong>o <strong>c</strong>ase)<br />
8145ab51b05aa86b2f1a21b49383f55e50b0a2e3Jakub Hrozek This makes the test case-insensitive - differences
7c3cc1ee2914bc7b38a992c1af254fc76af5a1adPavel Reichl between 'A-Z' and 'a-z' are ignored, both in the
7c3cc1ee2914bc7b38a992c1af254fc76af5a1adPavel Reichl expanded <em>TestString</em> and the <em>CondPattern</em>.
7c3cc1ee2914bc7b38a992c1af254fc76af5a1adPavel Reichl This flag is effective only for comparisons between
7c3cc1ee2914bc7b38a992c1af254fc76af5a1adPavel Reichl <em>TestString</em> and <em>CondPattern</em>. It has no
7c3cc1ee2914bc7b38a992c1af254fc76af5a1adPavel Reichl effect on filesystem and subrequest checks.</li>
8145ab51b05aa86b2f1a21b49383f55e50b0a2e3Jakub Hrozek Use this to combine rule conditions with a local OR
8145ab51b05aa86b2f1a21b49383f55e50b0a2e3Jakub Hrozek instead of the implicit AND. Typical example:
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit BoseRewriteCond %{REMOTE_HOST} ^host1.* [OR]
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit BoseRewriteCond %{REMOTE_HOST} ^host2.* [OR]
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit BoseRewriteCond %{REMOTE_HOST} ^host3.*
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit BoseRewriteRule ...some special stuff for any of these hosts...
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit Bose Without this flag you would have to write the condition/rule
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit Bose pair three times.
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit Bose (<strong>n</strong>o <strong>v</strong>ary)<br />
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit Bose If a HTTP header is used in the condition, this flag prevents
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit Bose this header from being added to the Vary header of the response. <br />
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit Bose Using this flag might break proper caching of the response if
4fa184e2c60b377fd71e0115a618bd68dc73627dSumit Bose the representation of this response varies on the value of this header.
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher So this flag should be only used if the meaning of the Vary header
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher is well understood.
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>To rewrite the Homepage of a site according to the
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher ``<code>User-Agent:</code>'' header of the request, you can
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher use the following: </p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen GallagherRewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen GallagherRewriteRule ^/$ /homepage.max.html [L]
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen GallagherRewriteCond %{HTTP_USER_AGENT} ^Lynx.*
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen GallagherRewriteRule ^/$ /homepage.min.html [L]
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen GallagherRewriteRule ^/$ /homepage.std.html [L]
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>Explanation: If you use a browser which identifies itself
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher get the max homepage (which could include frames, or other special
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher If you use the Lynx browser (which is terminal-based), then
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher you get the min homepage (which could be a version designed for
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek easy, text-only browsing).
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek If neither of these conditions apply (you use any other browser,
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek or your browser identifies itself as something non-standard), you get
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek the std (standard) homepage.</p>
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek</directivesynopsis>
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek<directivesynopsis>
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek<description>Defines rules for the rewriting engine</description>
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek<syntax>RewriteRule
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</syntax>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<contextlist><context>server config</context><context>virtual host</context>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<context>directory</context><context>.htaccess</context></contextlist>
b3f56d9e4bd065590383eb1f812a3b77e3c56f24Jakub Hrozek <p>The <directive>RewriteRule</directive> directive is the real
b3f56d9e4bd065590383eb1f812a3b77e3c56f24Jakub Hrozek rewriting workhorse. The directive can occur more than once,
b3f56d9e4bd065590383eb1f812a3b77e3c56f24Jakub Hrozek with each instance defining a single rewrite rule. The
b3f56d9e4bd065590383eb1f812a3b77e3c56f24Jakub Hrozek order in which these rules are defined is important - this is the order
8cc00c355862f5573f884efe828aa4c0f855376aJakub Hrozek in which they will be applied at run-time.</p>
03b859510dc13a13a456ca4aa94c0561a0e9684cJakub Hrozek <p><a id="patterns" name="patterns"><em>Pattern</em></a> is
03b859510dc13a13a456ca4aa94c0561a0e9684cJakub Hrozek a perl compatible <a id="regexp" name="regexp">regular
2580e0853b7c64b52147bf661abd7c315097caefPavel Březina expression</a>. On the first RewriteRule it is applied to the
03b859510dc13a13a456ca4aa94c0561a0e9684cJakub Hrozek <a href="/directive-dict.html#Syntax">URL-path</a> of the request;
03b859510dc13a13a456ca4aa94c0561a0e9684cJakub Hrozek subsequent patterns are applied to the output of the last matched
03b859510dc13a13a456ca4aa94c0561a0e9684cJakub Hrozek RewriteRule.</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>The <em>Pattern</em> will initially be matched against the part of the
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher URL after the hostname and port, and before the query string. If you wish
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher to match against the hostname, port, or query string, use a
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <directive module="mod_rewrite">RewriteCond</directive> with the
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
<dt>'<code>cookie|CO=</code><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>[:<em>secure</em>[:<em>httponly</em>]]]]'
^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
^/somepath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported
^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo
^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
^localpath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported