2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_rewrite.xml.meta">
25 <name>mod_rewrite</name>
27 <description>Provides a rule-based rewriting engine to rewrite requested
28 URLs on the fly</description>
30 <status>Extension</status>
31 <sourcefile>mod_rewrite.c</sourcefile>
32 <identifier>rewrite_module</identifier>
35 <p>The <module>mod_rewrite</module> module uses a rule-based rewriting
36 engine, based on a PCRE regular-expression parser, to rewrite requested URLs on
37 the fly. By default, <module>mod_rewrite</module> maps a URL to a filesystem
38 path. However, it can also be used to redirect one URL to another URL, or
39 to invoke an internal proxy fetch.</p>
40 <p><module>mod_rewrite</module> provides a flexible and powerful way to
41 manipulate URLs using an unlimited number of rules. Each rule can have an
42 unlimited number of attached rule conditions, to allow you to rewrite URL
43 based on server variables, environment variables, HTTP headers, or time
45 <p><module>mod_rewrite</module> operates on the full URL path, including the
46 path-info section. A rewrite rule can be invoked in
47 <code>httpd.conf</code> or in <code>.htaccess</code>. The path generated
48 by a rewrite rule can include a query string, or can lead to internal
49 sub-processing, external request redirection, or internal proxy
52 <p>Further details, discussion, and examples, are provided in the
53 <a href="../rewrite/">detailed mod_rewrite documentation</a>.</p>
56 <section id="logging"><title>Logging</title>
58 <p><module>mod_rewrite</module> offers detailed logging of its actions
59 at the <code>trace1</code> to <code>trace8</code> log levels. The
60 log level can be set specifically for <module>mod_rewrite</module>
61 using the <directive module="core">LogLevel</directive> directive: Up to
62 level <code>debug</code>, no actions are logged, while <code>trace8</code>
63 means that practically all actions are logged.</p>
66 Using a high trace log level for <module>mod_rewrite</module>
67 will slow down your Apache HTTP Server dramatically! Use a log
68 level higher than <code>trace2</code> only for debugging!
71 <example><title>Example</title>
72 <highlight language="config">
73 LogLevel alert rewrite:trace3
77 <note><title>RewriteLog</title>
78 <p>Those familiar with earlier versions of
79 <module>mod_rewrite</module> will no doubt be looking for the
80 <code>RewriteLog</code> and <code>RewriteLogLevel</code>
81 directives. This functionality has been completely replaced by the
82 new per-module logging configuration mentioned above.
85 <p>To get just the <module>mod_rewrite</module>-specific log
86 messages, pipe the log file through grep:</p>
88 tail -f error_log|fgrep '[rewrite:'
95 <name>RewriteEngine</name>
96 <description>Enables or disables runtime rewriting engine</description>
97 <syntax>RewriteEngine on|off</syntax>
98 <default>RewriteEngine off</default>
99 <contextlist><context>server config</context><context>virtual host</context>
100 <context>directory</context><context>.htaccess</context></contextlist>
101 <override>FileInfo</override>
105 <p>The <directive>RewriteEngine</directive> directive enables or
106 disables the runtime rewriting engine. If it is set to
107 <code>off</code> this module does no runtime processing at
108 all. It does not even update the <code>SCRIPT_URx</code>
109 environment variables.</p>
111 <p>Use this directive to disable rules in a particular context,
112 rather than commenting out all the <directive
113 module="mod_rewrite">RewriteRule</directive> directives.</p>
115 <p>Note that rewrite configurations are not
116 inherited by virtual hosts. This means that you need to have a
117 <code>RewriteEngine on</code> directive for each virtual host
118 in which you wish to use rewrite rules.</p>
120 <p><directive module="mod_rewrite">RewriteMap</directive> directives
121 of the type <code>prg</code>
122 are not started during server initialization if they're defined in a
123 context that does not have <directive>RewriteEngine</directive> set to
130 <name>RewriteOptions</name>
131 <description>Sets some special options for the rewrite engine</description>
132 <syntax>RewriteOptions <var>Options</var></syntax>
133 <contextlist><context>server config</context><context>virtual host</context>
134 <context>directory</context><context>.htaccess</context></contextlist>
135 <override>FileInfo</override>
138 <p>The <directive>RewriteOptions</directive> directive sets some
139 special options for the current per-server or per-directory
140 configuration. The <em>Option</em> string can currently
141 only be one of the following:</p>
144 <dt><code>Inherit</code></dt>
147 <p>This forces the current configuration to inherit the
148 configuration of the parent. In per-virtual-server context,
149 this means that the maps, conditions and rules of the main
150 server are inherited. In per-directory context this means
151 that conditions and rules of the parent directory's
152 <code>.htaccess</code> configuration or
153 <directive type="section" module="core">Directory</directive>
154 sections are inherited. The inherited rules are virtually copied
155 to the section where this directive is being used. If used in
156 combination with local rules, the inherited rules are copied behind
157 the local rules. The position of this directive - below or above
158 of local rules - has no influence on this behavior. If local
159 rules forced the rewriting to stop, the inherited rules won't
162 <note type="warning">
163 Rules inherited from the parent scope are applied
164 <strong>after</strong> rules specified in the child scope.
168 <dt><code>InheritBefore</code></dt>
170 <p> Like <code>Inherit</code> above, but the rules from the parent scope
171 are applied <strong>before</strong> rules specified in the child scope.<br />
172 Available in Apache HTTP Server 2.3.10 and later.</p>
175 <dt><code>InheritDown</code></dt>
178 <p>If this option is enabled, all child configurations will inherit
179 the configuration of the current configuration. It is equivalent to
180 specifying <code>RewriteOptions Inherit</code> in all child
181 configurations. See the <code>Inherit</code> option for more details
182 on how the parent-child relationships are handled.<br />
183 Available in Apache HTTP Server 2.4.8 and later.</p>
186 <dt><code>InheritDownBefore</code></dt>
189 <p>Like <code>InheritDown</code> above, but the rules from the current
190 scope are applied <strong>before</strong> rules specified in any child's
192 Available in Apache HTTP Server 2.4.8 and later.</p>
195 <dt><code>IgnoreInherit</code></dt>
198 <p>This option forces the current and child configurations to ignore
199 all rules that would be inherited from a parent specifying
200 <code>InheritDown</code> or <code>InheritDownBefore</code>.<br />
201 Available in Apache HTTP Server 2.4.8 and later.</p>
204 <dt><code>AllowNoSlash</code></dt>
206 <p>By default, <module>mod_rewrite</module> will ignore URLs that map to a
207 directory on disk but lack a trailing slash, in the expectation that
208 the <module>mod_dir</module> module will issue the client with a redirect to
209 the canonical URL with a trailing slash.</p>
211 <p>When the <directive module="mod_dir">DirectorySlash</directive> directive
212 is set to off, the <code>AllowNoSlash</code> option can be enabled to ensure
213 that rewrite rules are no longer ignored. This option makes it possible to
214 apply rewrite rules within .htaccess files that match the directory without
215 a trailing slash, if so desired.<br />
216 Available in Apache HTTP Server 2.4.0 and later.</p>
219 <dt><code>AllowAnyURI</code></dt>
222 <p>When <directive module="mod_rewrite">RewriteRule</directive>
223 is used in <code>VirtualHost</code> or server context with
224 version 2.2.22 or later of httpd, <module>mod_rewrite</module>
225 will only process the rewrite rules if the request URI is a <a
226 href="directive-dict.html#Syntax">URL-path</a>. This avoids
227 some security issues where particular rules could allow
228 "surprising" pattern expansions (see <a
229 href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-3368">CVE-2011-3368</a>
231 href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-4317">CVE-2011-4317</a>).
232 To lift the restriction on matching a URL-path, the
233 <code>AllowAnyURI</code> option can be enabled, and
234 <module>mod_rewrite</module> will apply the rule set to any
235 request URI string, regardless of whether that string matches
236 the URL-path grammar required by the HTTP specification.<br />
237 Available in Apache HTTP Server 2.4.3 and later.</p>
239 <note type="warning">
240 <title>Security Warning</title>
242 <p>Enabling this option will make the server vulnerable to
243 security issues if used with rewrite rules which are not
244 carefully authored. It is <strong>strongly recommended</strong>
245 that this option is not used. In particular, beware of input
246 strings containing the '<code>@</code>' character which could
247 change the interpretation of the transformed URI, as per the
252 <dt><code>MergeBase</code></dt>
255 <p>With this option, the value of <directive module="mod_rewrite"
256 >RewriteBase</directive> is copied from where it's explicitly defined
257 into any sub-directory or sub-location that doesn't define its own
258 <directive module="mod_rewrite">RewriteBase</directive>. This was the
259 default behavior in 2.4.0 through 2.4.3, and the flag to restore it is
260 available Apache HTTP Server 2.4.4 and later.</p>
263 <dt><code>IgnoreContextInfo</code></dt>
266 <p>When a relative substitution is made
267 in directory (htaccess) context and <directive module="mod_rewrite"
268 >RewriteBase</directive> has not been set, this module uses some
269 extended URL and filesystem context information to change the
270 relative substitution back into a URL. Modules such as
271 <module>mod_userdir</module> and <module>mod_alias</module>
272 supply this extended context info. Available in 2.4.16 and later.</p>
276 <dt><code>LegacyPrefixDocRoot</code></dt>
279 <p>Prior to 2.4.26, if a substitution was an absolute URL that matched
280 the current virtual host, the URL might first be reduced to a URL-path
281 and then later reduced to a local path. Since the URL can be reduced
282 to a local path, the path should be prefixed with the document root.
283 This prevents a file such as /tmp/myfile from being accessed when a
284 request is made to http://host/file/myfile with the following
285 <directive module="mod_rewrite">RewriteRule</directive>.</p>
286 <highlight language="config">
287 RewriteRule /file/(.*) http://localhost/tmp/$1
289 <p>This option allows the old behavior to be used where the document
290 root is not prefixed to a local path that was reduced from a
291 URL. Available in 2.4.26 and later.</p>
294 <dt><code>LongURLOptimization</code></dt>
296 <p>This option reduces memory usage of long, unoptimized rule sets
297 that repeatedly expand long values in RewriteCond and RewriteRule
298 variables. Available in 2.5 and later.</p>
307 <name>RewriteMap</name>
308 <description>Defines a mapping function for key-lookup</description>
309 <syntax>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
310 [<em>MapTypeOptions</em>]
312 <contextlist><context>server config</context><context>virtual host</context>
314 <compatibility>The 3rd parameter, MapTypeOptions, in only available from Apache
315 2.4.29 and later</compatibility>
318 <p>The <directive>RewriteMap</directive> directive defines a
319 <em>Rewriting Map</em> which can be used inside rule
320 substitution strings by the mapping-functions to
321 insert/substitute fields through a key lookup. The source of
322 this lookup can be of various types.</p>
324 <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
325 the name of the map and will be used to specify a
326 mapping-function for the substitution strings of a rewriting
327 rule via one of the following constructs:</p>
330 <strong><code>${</code> <em>MapName</em> <code>:</code>
331 <em>LookupKey</em> <code>}</code><br />
332 <code>${</code> <em>MapName</em> <code>:</code>
333 <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
334 <code>}</code></strong>
337 <p>When such a construct occurs, the map <em>MapName</em> is
338 consulted and the key <em>LookupKey</em> is looked-up. If the
339 key is found, the map-function construct is substituted by
340 <em>SubstValue</em>. If the key is not found then it is
341 substituted by <em>DefaultValue</em> or by the empty string
342 if no <em>DefaultValue</em> was specified. Empty values
343 behave as if the key was absent, therefore it is not possible
344 to distinguish between empty-valued keys and absent keys.</p>
346 <p>For example, you might define a
347 <directive>RewriteMap</directive> as:</p>
349 <highlight language="config">
350 RewriteMap examplemap "txt:/path/to/file/map.txt"
353 <p>You would then be able to use this map in a
354 <directive module="mod_rewrite">RewriteRule</directive> as follows:</p>
356 <highlight language="config">
357 RewriteRule "^/ex/(.*)" "${examplemap:$1}"
360 <p>The meaning of the <em>MapTypeOptions</em> argument depends on
361 particular <em>MapType</em>. See the
362 <a href="../rewrite/rewritemap.html">Using RewriteMap</a> for
363 more information.</p>
365 <p>The following combinations for <em>MapType</em> and
366 <em>MapSource</em> can be used:</p>
371 <dd>A plain text file containing space-separated key-value
372 pairs, one per line. (<a href="../rewrite/rewritemap.html#txt">Details ...</a>)</dd>
375 <dd>Randomly selects an entry from a plain text file (<a href="../rewrite/rewritemap.html#rnd">Details ...</a>)</dd>
378 <dd>Looks up an entry in a dbm file containing name, value
379 pairs. Hash is constructed from a plain text file format using
380 the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code>
381 utility. (<a href="../rewrite/rewritemap.html#dbm">Details ...</a>)</dd>
384 <dd>One of the four available internal functions provided by
385 <code>RewriteMap</code>: toupper, tolower, escape or
386 unescape. (<a href="../rewrite/rewritemap.html#int">Details ...</a>)</dd>
389 <dd>Calls an external program or script to process the
390 rewriting. (<a href="../rewrite/rewritemap.html#prg">Details ...</a>)</dd>
392 <dt>dbd or fastdbd</dt>
393 <dd>A SQL SELECT statement to be performed to look up the
394 rewrite target. (<a href="../rewrite/rewritemap.html#dbd">Details ...</a>)</dd>
397 <p>Further details, and numerous examples, may be found in the <a
398 href="../rewrite/rewritemap.html">RewriteMap HowTo</a></p>
404 <name>RewriteBase</name>
405 <description>Sets the base URL for per-directory rewrites</description>
406 <syntax>RewriteBase <em>URL-path</em></syntax>
407 <default>None</default>
408 <contextlist><context>directory</context><context>.htaccess</context>
410 <override>FileInfo</override>
413 <p>The <directive>RewriteBase</directive> directive specifies the
414 URL prefix to be used for per-directory (htaccess)
415 <directive module="mod_rewrite">RewriteRule</directive> directives that
416 substitute a relative path.</p>
417 <p> This directive is <em>required</em> when you use a relative path
418 in a substitution in per-directory (htaccess) context unless any
419 of the following conditions are true:</p>
421 <li> The original request, and the substitution, are underneath the
422 <directive module="core">DocumentRoot</directive>
423 (as opposed to reachable by other means, such as
424 <directive module="mod_alias">Alias</directive>).</li>
425 <li> The <em>filesystem</em> path to the directory containing the
426 <directive module="mod_rewrite">RewriteRule</directive>,
427 suffixed by the relative
428 substitution is also valid as a URL path on the server
430 <li> In Apache HTTP Server 2.4.16 and later, this directive may be
431 omitted when the request is mapped via
432 <directive module="mod_alias">Alias</directive>
433 or <module>mod_userdir</module>.</li>
436 <p> In the example below, <directive>RewriteBase</directive> is necessary
437 to avoid rewriting to http://example.com/opt/myapp-1.2.3/welcome.html
438 since the resource was not relative to the document root. This
439 misconfiguration would normally cause the server to look for an "opt"
440 directory under the document root.</p>
441 <highlight language="config">
442 DocumentRoot "/var/www/example.com"
443 AliasMatch "^/myapp" "/opt/myapp-1.2.3"
444 <Directory "/opt/myapp-1.2.3">
446 RewriteBase "/myapp/"
447 RewriteRule "^index\.html$" "welcome.html"
456 <name>RewriteCond</name>
457 <description>Defines a condition under which rewriting will take place
460 <em>TestString</em> <em>CondPattern</em> [<em>flags</em>]</syntax>
461 <contextlist><context>server config</context><context>virtual host</context>
462 <context>directory</context><context>.htaccess</context></contextlist>
463 <override>FileInfo</override>
466 <p>The <directive>RewriteCond</directive> directive defines a
467 rule condition. One or more <directive>RewriteCond</directive>
468 can precede a <directive module="mod_rewrite">RewriteRule</directive>
469 directive. The following rule is then only used if both
470 the current state of the URI matches its pattern, <strong
471 >and</strong> if these conditions are met.</p>
473 <p><em>TestString</em> is a string which can contain the
474 following expanded constructs in addition to plain text:</p>
478 <strong>RewriteRule backreferences</strong>: These are
479 backreferences of the form <strong><code>$N</code></strong>
480 (0 <= N <= 9). $1 to $9 provide access to the grouped
481 parts (in parentheses) of the pattern, from the
482 <code>RewriteRule</code> which is subject to the current
483 set of <code>RewriteCond</code> conditions. $0 provides
484 access to the whole string matched by that pattern.
487 <strong>RewriteCond backreferences</strong>: These are
488 backreferences of the form <strong><code>%N</code></strong>
489 (0 <= N <= 9). %1 to %9 provide access to the grouped
490 parts (again, in parentheses) of the pattern, from the last matched
491 <code>RewriteCond</code> in the current set
492 of conditions. %0 provides access to the whole string matched by
496 <strong>RewriteMap expansions</strong>: These are
497 expansions of the form <strong><code
498 >${mapname:key|default}</code></strong>.
499 See <a href="#mapfunc">the documentation for
500 RewriteMap</a> for more details.
503 <strong>Server-Variables</strong>: These are variables of
505 <strong><code>%{</code> <em>NAME_OF_VARIABLE</em>
506 <code>}</code></strong>
507 where <em>NAME_OF_VARIABLE</em> can be a string taken
508 from the following list:
511 <columnspec><column width=".3"/><column width=".3"/>
512 <column width=".3"/></columnspec>
514 <th>HTTP headers:</th> <th>connection & request:</th> <th></th>
523 HTTP_PROXY_CONNECTION<br />
525 HTTP_USER_AGENT<br />
530 CONN_REMOTE_ADDR<br />
532 CONTEXT_DOCUMENT_ROOT<br />
542 SCRIPT_FILENAME<br />
549 <th>server internals:</th> <th>date and time:</th> <th>specials:</th>
561 SERVER_PROTOCOL<br />
562 SERVER_SOFTWARE<br />
578 CONN_REMOTE_ADDR<br />
582 REQUEST_FILENAME<br />
590 <p>These variables all
591 correspond to the similarly named HTTP
592 MIME-headers, C variables of the Apache HTTP Server or
593 <code>struct tm</code> fields of the Unix system.
594 Most are documented <a href="../expr.html#vars">here</a>
595 or elsewhere in the Manual or in the CGI specification.</p>
597 <p>SERVER_NAME and SERVER_PORT depend on the values of
598 <directive module="core">UseCanonicalName</directive> and
599 <directive module="core">UseCanonicalPhysicalPort</directive>
602 <p>Those that are special to <module>mod_rewrite</module> include those below.</p>
604 <dt><code>API_VERSION</code></dt>
606 <dd>This is the version of the Apache httpd module API
607 (the internal interface between server and
608 module) in the current httpd build, as defined in
609 include/ap_mmn.h. The module API version
610 corresponds to the version of Apache httpd in use (in
611 the release version of Apache httpd 1.3.14, for
612 instance, it is 19990320:10), but is mainly of
613 interest to module authors.</dd>
615 <dt><code>CONN_REMOTE_ADDR</code></dt>
617 <dd>Since 2.4.8: The peer IP address of the connection (see the
618 <module>mod_remoteip</module> module).</dd>
620 <dt><code>HTTPS</code></dt>
622 <dd>Will contain the text "on" if the connection is
623 using SSL/TLS, or "off" otherwise. (This variable
624 can be safely used regardless of whether or not
625 <module>mod_ssl</module> is loaded).</dd>
627 <dt><code>IS_SUBREQ</code></dt>
629 <dd>Will contain the text "true" if the request
630 currently being processed is a sub-request,
631 "false" otherwise. Sub-requests may be generated
632 by modules that need to resolve additional files
633 or URIs in order to complete their tasks.</dd>
635 <dt><code>REMOTE_ADDR</code></dt>
637 <dd>The IP address of the remote host (see the
638 <module>mod_remoteip</module> module).</dd>
640 <dt><code>REQUEST_FILENAME</code></dt>
642 <dd>The full local filesystem path to the file or
643 script matching the request, if this has already
644 been determined by the server at the time
645 <code>REQUEST_FILENAME</code> is referenced. Otherwise,
646 such as when used in virtual host context, the same
647 value as <code>REQUEST_URI</code>. Depending on the value of
648 <directive module="core">AcceptPathInfo</directive>, the
649 server may have only used some leading components of the
650 <code>REQUEST_URI</code> to map the request to a file.
653 <dt><code>REQUEST_SCHEME</code></dt>
655 <dd>Will contain the scheme of the request (usually
656 "http" or "https"). This value can be influenced with
657 <directive module="core">ServerName</directive>.</dd>
659 <dt><code>REQUEST_URI</code></dt>
661 <dd>The path component of the requested URI,
662 such as "/index.html". This notably excludes the
663 query string which is available as its own variable
664 named <code>QUERY_STRING</code>.</dd>
666 <dt><code>THE_REQUEST</code></dt>
668 <dd>The full HTTP request line sent by the
669 browser to the server (e.g., "<code>GET
670 /index.html HTTP/1.1</code>"). This does not
671 include any additional headers sent by the
672 browser. This value has not been unescaped
673 (decoded), unlike most other variables below.</dd>
679 <p>If the <em>TestString</em> has the special value <code>expr</code>,
680 the <em>CondPattern</em> will be treated as an
681 <a href="../expr.html">ap_expr</a>. HTTP headers referenced in the
682 expression will be added to the Vary header if the <code>novary</code>
683 flag is not given.</p>
685 <p>Other things you should be aware of:</p>
689 <p>The variables SCRIPT_FILENAME and REQUEST_FILENAME
690 contain the same value - the value of the
691 <code>filename</code> field of the internal
692 <code>request_rec</code> structure of the Apache HTTP Server.
693 The first name is the commonly known CGI variable name
694 while the second is the appropriate counterpart of
695 REQUEST_URI (which contains the value of the
696 <code>uri</code> field of <code>request_rec</code>).</p>
697 <p>If a substitution occurred and the rewriting continues,
698 the value of both variables will be updated accordingly.</p>
699 <p>If used in per-server context (<em>i.e.</em>, before the
700 request is mapped to the filesystem) SCRIPT_FILENAME and
701 REQUEST_FILENAME cannot contain the full local filesystem
702 path since the path is unknown at this stage of processing.
703 Both variables will initially contain the value of REQUEST_URI
704 in that case. In order to obtain the full local filesystem
705 path of the request in per-server context, use an URL-based
706 look-ahead <code>%{LA-U:REQUEST_FILENAME}</code> to determine
707 the final value of REQUEST_FILENAME.</p></li>
710 <code>%{ENV:variable}</code>, where <em>variable</em> can be
711 any environment variable, is also available.
712 This is looked-up via internal
713 Apache httpd structures and (if not found there) via
714 <code>getenv()</code> from the Apache httpd server process.</li>
717 <code>%{SSL:variable}</code>, where <em>variable</em> is the
718 name of an <a href="mod_ssl.html#envvars">SSL environment
719 variable</a>, can be used whether or not
720 <module>mod_ssl</module> is loaded, but will always expand to
721 the empty string if it is not. Example:
722 <code>%{SSL:SSL_CIPHER_USEKEYSIZE}</code> may expand to
723 <code>128</code>. These variables are available even without
724 setting the <code>StdEnvVars</code> option of the
725 <directive module="mod_ssl">SSLOptions</directive> directive.</li>
728 <code>%{HTTP:header}</code>, where <em>header</em> can be
729 any HTTP MIME-header name, can always be used to obtain the
730 value of a header sent in the HTTP request.
731 Example: <code>%{HTTP:Proxy-Connection}</code> is
732 the value of the HTTP header
733 ``<code>Proxy-Connection:</code>''.
734 <p>If a HTTP header is used in a condition this header is added to
735 the Vary header of the response in case the condition evaluates
736 to true for the request. It is <strong>not</strong> added if the
737 condition evaluates to false for the request. Adding the HTTP header
738 to the Vary header of the response is needed for proper caching.</p>
739 <p>It has to be kept in mind that conditions follow a short circuit
740 logic in the case of the '<strong><code>ornext|OR</code></strong>' flag
741 so that certain conditions might not be evaluated at all.</p></li>
744 <a id="LA-U" name="LA-U"><code>%{LA-U:variable}</code></a>
745 can be used for look-aheads which perform
746 an internal (URL-based) sub-request to determine the final
747 value of <em>variable</em>. This can be used to access
748 variable for rewriting which is not available at the current
749 stage, but will be set in a later phase.
750 <p>For instance, to rewrite according to the
751 <code>REMOTE_USER</code> variable from within the
752 per-server context (<code>httpd.conf</code> file) you must
753 use <code>%{LA-U:REMOTE_USER}</code> - this
754 variable is set by the authorization phases, which come
755 <em>after</em> the URL translation phase (during which
756 <module>mod_rewrite</module> operates).</p>
757 <p>On the other hand, because <module>mod_rewrite</module> implements
758 its per-directory context (<code>.htaccess</code> file) via
759 the Fixup phase of the API and because the authorization
760 phases come <em>before</em> this phase, you just can use
761 <code>%{REMOTE_USER}</code> in that context.</p></li>
764 <code>%{LA-F:variable}</code> can be used to perform an internal
765 (filename-based) sub-request, to determine the final value
766 of <em>variable</em>. Most of the time, this is the same as
770 <p><em>CondPattern</em> is the condition pattern,
771 a regular expression which is applied to the
772 current instance of the <em>TestString</em>.
773 <em>TestString</em> is first evaluated, before being matched against
774 <em>CondPattern</em>.</p>
776 <p><em>CondPattern</em> is usually a
777 <em>perl compatible regular expression</em>, but there is
778 additional syntax available to perform other useful tests against
779 the <em>Teststring</em>:</p>
782 <li>You can prefix the pattern string with a
783 '<code>!</code>' character (exclamation mark) to negate the result
784 of the condition, no matter what kind of <em>CondPattern</em> is used.
788 You can perform lexicographical string comparisons:
791 <dt><strong><CondPattern</strong></dt>
792 <dd>Lexicographically precedes<br />
793 Treats the <em>CondPattern</em> as a plain string and
794 compares it lexicographically to <em>TestString</em>. True if
795 <em>TestString</em> lexicographically precedes
796 <em>CondPattern</em>.</dd>
798 <dt><strong>>CondPattern</strong></dt>
799 <dd>Lexicographically follows<br />
800 Treats the <em>CondPattern</em> as a plain string and
801 compares it lexicographically to <em>TestString</em>. True if
802 <em>TestString</em> lexicographically follows
803 <em>CondPattern</em>.</dd>
805 <dt><strong>=CondPattern</strong></dt>
806 <dd>Lexicographically equal<br />
807 Treats the <em>CondPattern</em> as a plain string and
808 compares it lexicographically to <em>TestString</em>. True if
809 <em>TestString</em> is lexicographically equal to
810 <em>CondPattern</em> (the two strings are exactly
811 equal, character for character). If <em>CondPattern</em>
812 is <code>""</code> (two quotation marks) this
813 compares <em>TestString</em> to the empty string.</dd>
815 <dt><strong><=CondPattern</strong></dt>
816 <dd>Lexicographically less than or equal to<br />
817 Treats the <em>CondPattern</em> as a plain string and
818 compares it lexicographically to <em>TestString</em>. True
819 if <em>TestString</em> lexicographically precedes
820 <em>CondPattern</em>, or is equal to <em>CondPattern</em>
821 (the two strings are equal, character for character).</dd>
823 <dt><strong>>=CondPattern</strong></dt>
824 <dd>Lexicographically greater than or equal to<br />
825 Treats the <em>CondPattern</em> as a plain string and
826 compares it lexicographically to <em>TestString</em>. True
827 if <em>TestString</em> lexicographically follows
828 <em>CondPattern</em>, or is equal to <em>CondPattern</em>
829 (the two strings are equal, character for character).</dd>
834 You can perform integer comparisons:
837 <dt><strong>-eq</strong></dt>
838 <dd>Is numerically <strong>eq</strong>ual to<br />
839 The <em>TestString</em> is treated as an integer, and is
840 numerically compared to the <em>CondPattern</em>. True if
841 the two are numerically equal.</dd>
843 <dt><strong>-ge</strong></dt>
844 <dd>Is numerically <strong>g</strong>reater than or <strong>e</strong>qual to<br />
845 The <em>TestString</em> is treated as an integer, and is
846 numerically compared to the <em>CondPattern</em>. True if
847 the <em>TestString</em> is numerically greater than or equal
848 to the <em>CondPattern</em>.</dd>
850 <dt><strong>-gt</strong></dt>
851 <dd>Is numerically <strong>g</strong>reater <strong>t</strong>han<br />
852 The <em>TestString</em> is treated as an integer, and is
853 numerically compared to the <em>CondPattern</em>. True if
854 the <em>TestString</em> is numerically greater than
855 the <em>CondPattern</em>.</dd>
857 <dt><strong>-le</strong></dt>
858 <dd>Is numerically <strong>l</strong>ess than or <strong>e</strong>qual to<br />
859 The <em>TestString</em> is treated as an integer, and is
860 numerically compared to the <em>CondPattern</em>. True if
861 the <em>TestString</em> is numerically less than or equal
862 to the <em>CondPattern</em>. Avoid confusion with the
863 <strong>-l</strong> by using the <strong>-L</strong> or
864 <strong>-h</strong> variant.</dd>
866 <dt><strong>-lt</strong></dt>
867 <dd>Is numerically <strong>l</strong>ess <strong>t</strong>han<br />
868 The <em>TestString</em> is treated as an integer, and is
869 numerically compared to the <em>CondPattern</em>. True if
870 the <em>TestString</em> is numerically less than
871 the <em>CondPattern</em>. Avoid confusion with the
872 <strong>-l</strong> by using the <strong>-L</strong> or
873 <strong>-h</strong> variant.</dd>
875 <dt><strong>-ne</strong></dt>
876 <dd>Is numerically <strong>n</strong>ot <strong>e</strong>qual to<br />
877 The <em>TestString</em> is treated as an integer, and is
878 numerically compared to the <em>CondPattern</em>. True if
879 the two are numerically different. This is equivalent to
880 <code>!-eq</code>.</dd>
885 <li>You can perform various file attribute tests:
890 <dt><strong>-d</strong></dt>
892 <dd>Is <strong>d</strong>irectory.<br />
893 Treats the <em>TestString</em> as a pathname and tests
894 whether or not it exists, and is a directory.
897 <dt><strong>-f</strong></dt>
899 <dd>Is regular <strong>f</strong>ile.<br />
901 Treats the <em>TestString</em> as a pathname and tests
902 whether or not it exists, and is a regular file.
905 <dt><strong>-F</strong></dt>
907 <dd>Is existing file, via subrequest.<br />
908 Checks whether or not <em>TestString</em> is a valid file,
909 accessible via all the server's currently-configured
910 access controls for that path. This uses an internal
911 subrequest to do the check, so use it with care -
912 it can impact your server's performance!
915 <dt><strong>-h</strong></dt>
916 <dd>Is symbolic link, bash convention.<br />
917 See <strong>-l</strong>.
920 <dt><strong>-l</strong></dt>
922 <dd>Is symbolic <strong>l</strong>ink.<br />
923 Treats the <em>TestString</em> as a pathname and tests
924 whether or not it exists, and is a symbolic link. May also
925 use the bash convention of <strong>-L</strong> or
926 <strong>-h</strong> if there's a possibility of confusion
927 such as when using the <strong>-lt</strong> or
928 <strong>-le</strong> tests.
931 <dt><strong>-L</strong></dt>
932 <dd>Is symbolic link, bash convention.<br />
933 See <strong>-l</strong>.</dd>
935 <dt><strong>-s</strong></dt>
936 <dd>Is regular file, with <strong>s</strong>ize.<br />
937 Treats the <em>TestString</em> as a pathname and tests
938 whether or not it exists, and is a regular file with size greater
941 <dt><strong>-U</strong></dt>
942 <dd><p>Is existing URL, via subrequest.<br />
943 Checks whether or not <em>TestString</em> is a valid URL,
944 accessible via all the server's currently-configured
945 access controls for that path. This uses an internal
946 subrequest to do the check, so use it with care -
947 it can impact your server's performance!</p>
948 <p> This flag <em>only</em> returns information about things
949 like access control, authentication, and authorization. This flag
950 <em>does not</em> return information about the status code the
951 configured handler (static file, CGI, proxy, etc.) would have
954 <dt><strong>-x</strong></dt>
955 <dd>Has e<strong>x</strong>ecutable permissions.<br />
956 Treats the <em>TestString</em> as a pathname and tests
957 whether or not it exists, and has executable permissions.
958 These permissions are determined according to
959 the underlying OS.</dd>
965 <highlight language="config">
966 RewriteCond /var/www/%{REQUEST_URI} !-f
967 RewriteRule ^(.+) /other/archive/$1 [R]
973 <p>If the <em>TestString</em> has the special value <code>expr</code>, the
974 <em>CondPattern</em> will be treated as an
975 <a href="../expr.html">ap_expr</a>.</p>
978 In the below example, <code>-strmatch</code> is used to
979 compare the <code>REFERER</code> against the site hostname,
980 to block unwanted hotlinking.
983 <highlight language="config">
984 RewriteCond expr "! %{HTTP_REFERER} -strmatch '*://%{HTTP_HOST}/*'"
985 RewriteRule "^/images" "-" [F]
990 <p>You can also set special flags for <em>CondPattern</em> by appending
991 <strong><code>[</code><em>flags</em><code>]</code></strong>
992 as the third argument to the <directive>RewriteCond</directive>
993 directive, where <em>flags</em> is a comma-separated list of any of the
997 <li>'<strong><code>nocase|NC</code></strong>'
998 (<strong>n</strong>o <strong>c</strong>ase)<br />
999 This makes the test case-insensitive - differences
1000 between 'A-Z' and 'a-z' are ignored, both in the
1001 expanded <em>TestString</em> and the <em>CondPattern</em>.
1002 This flag is effective only for comparisons between
1003 <em>TestString</em> and <em>CondPattern</em>. It has no
1004 effect on filesystem and subrequest checks.</li>
1007 '<strong><code>ornext|OR</code></strong>'
1008 (<strong>or</strong> next condition)<br />
1009 Use this to combine rule conditions with a local OR
1010 instead of the implicit AND. Typical example:
1012 <highlight language="config">
1013 RewriteCond "%{REMOTE_HOST}" "^host1" [OR]
1014 RewriteCond "%{REMOTE_HOST}" "^host2" [OR]
1015 RewriteCond "%{REMOTE_HOST}" "^host3"
1016 RewriteRule ...some special stuff for any of these hosts...
1019 Without this flag you would have to write the condition/rule
1023 <li>'<strong><code>novary|NV</code></strong>'
1024 (<strong>n</strong>o <strong>v</strong>ary)<br />
1025 If a HTTP header is used in the condition, this flag prevents
1026 this header from being added to the Vary header of the response. <br />
1027 Using this flag might break proper caching of the response if
1028 the representation of this response varies on the value of this header.
1029 So this flag should be only used if the meaning of the Vary header
1034 <p><strong>Example:</strong></p>
1036 <p>To rewrite the Homepage of a site according to the
1037 ``<code>User-Agent:</code>'' header of the request, you can
1038 use the following: </p>
1040 <highlight language="config">
1041 RewriteCond "%{HTTP_USER_AGENT}" "(iPhone|Blackberry|Android)"
1042 RewriteRule "^/$" "/homepage.mobile.html" [L]
1044 RewriteRule "^/$" "/homepage.std.html" [L]
1047 <p>Explanation: If you use a browser which identifies itself
1048 as a mobile browser (note that the example is incomplete, as
1049 there are many other mobile platforms), the mobile version of
1050 the homepage is served. Otherwise, the standard page is served.
1055 </directivesynopsis>
1058 <name>RewriteRule</name>
1059 <description>Defines rules for the rewriting engine</description>
1061 <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</syntax>
1062 <contextlist><context>server config</context><context>virtual host</context>
1063 <context>directory</context><context>.htaccess</context></contextlist>
1064 <override>FileInfo</override>
1067 <p>The <directive>RewriteRule</directive> directive is the real
1068 rewriting workhorse. The directive can occur more than once,
1069 with each instance defining a single rewrite rule. The
1070 order in which these rules are defined is important - this is the order
1071 in which they will be applied at run-time.</p>
1073 <p><a id="patterns" name="patterns"><em>Pattern</em></a> is
1074 a perl compatible <a id="regexp" name="regexp">regular
1075 expression</a>. What this pattern is compared against varies depending
1076 on where the <directive>RewriteRule</directive> directive is defined. </p>
1078 <note><title><a id="what_is_matched" name="what_is_matched">What is matched?</a></title>
1081 <li><p>In <directive module="core">VirtualHost</directive> context,
1082 The <em>Pattern</em> will initially be matched against the part of the
1083 URL after the hostname and port, and before the query string (e.g. "/app1/index.html").
1084 This is the (%-decoded) <a href="directive-dict.html#Syntax">URL-path</a>.</p></li>
1086 <li><p>In per-directory context (<directive module="core">Directory</directive> and .htaccess),
1087 the <em>Pattern</em> is matched against only a partial path, for example a request
1088 of "/app1/index.html" may result in comparison against "app1/index.html"
1089 or "index.html" depending on where the <directive>RewriteRule</directive> is
1092 <p>The directory path where the rule is defined is stripped from the currently mapped
1093 filesystem path before comparison (up to and including a trailing slash).
1094 The net result of this per-directory prefix stripping is that rules in
1095 this context only match against the portion of the currently mapped filesystem path
1096 "below" where the rule is defined.</p>
1098 <p>Directives such as <directive module="core"
1099 >DocumentRoot</directive> and <directive module="mod_alias">Alias</directive>, or even the
1100 result of previous <directive>RewriteRule</directive> substitutions, determine
1101 the currently mapped filesystem path.
1105 <li><p>If you wish to match against the hostname, port, or query string, use a
1106 <directive module="mod_rewrite">RewriteCond</directive> with the
1107 <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
1108 <code>%{QUERY_STRING}</code> variables respectively.</p></li>
1112 <note><title>Per-directory Rewrites</title>
1114 <li>The rewrite engine may be used in <a
1115 href="../howto/htaccess.html">.htaccess</a> files and in <directive type="section"
1116 module="core">Directory</directive> sections, with some additional
1119 <li>To enable the rewrite engine in this context, you need to set
1120 "<code>RewriteEngine On</code>" <strong>and</strong>
1121 "<code>Options FollowSymLinks</code>" must be enabled. If your
1122 administrator has disabled override of <code>FollowSymLinks</code> for
1123 a user's directory, then you cannot use the rewrite engine. This
1124 restriction is required for security reasons.</li>
1126 <li>See the <directive module="mod_rewrite">RewriteBase</directive>
1127 directive for more information regarding what prefix will be added back to
1128 relative substitutions.</li>
1130 <li> If you wish to match against the full URL-path in a per-directory
1131 (htaccess) RewriteRule, use the <code>%{REQUEST_URI}</code> variable in
1132 a <directive module="mod_rewrite">RewriteCond</directive>.</li>
1134 <li>The removed prefix always ends with a slash, meaning the matching occurs against a string which
1135 <em>never</em> has a leading slash. Therefore, a <em>Pattern</em> with <code>^/</code> never
1136 matches in per-directory context.</li>
1138 <li>Although rewrite rules are syntactically permitted in <directive
1139 type="section" module="core">Location</directive> and <directive
1140 type="section" module="core">Files</directive> sections
1141 (including their regular expression counterparts), this
1142 should never be necessary and is unsupported. A likely feature
1143 to break in these contexts is relative substitutions.</li>
1147 <p>For some hints on <glossary ref="regex">regular
1148 expressions</glossary>, see
1149 the <a href="../rewrite/intro.html#regex">mod_rewrite
1150 Introduction</a>.</p>
1152 <p>In <module>mod_rewrite</module>, the NOT character
1153 ('<code>!</code>') is also available as a possible pattern
1154 prefix. This enables you to negate a pattern; to say, for instance:
1155 ``<em>if the current URL does <strong>NOT</strong> match this
1156 pattern</em>''. This can be used for exceptional cases, where
1157 it is easier to match the negative pattern, or as a last
1160 <note><title>Note</title>
1161 When using the NOT character to negate a pattern, you cannot include
1162 grouped wildcard parts in that pattern. This is because, when the
1163 pattern does NOT match (ie, the negation matches), there are no
1164 contents for the groups. Thus, if negated patterns are used, you
1165 cannot use <code>$N</code> in the substitution string!
1168 <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
1169 rewrite rule is the string that replaces the original URL-path that
1170 was matched by <em>Pattern</em>. The <em>Substitution</em> may
1175 <dt>file-system path</dt>
1177 <dd>Designates the location on the file-system of the resource
1178 to be delivered to the client. Substitutions are only
1179 treated as a file-system path when the rule is configured in
1180 server (virtualhost) context and the first component of the
1181 path in the substitution exists in the file-system</dd>
1186 module="core">DocumentRoot</directive>-relative path to the
1187 resource to be served. Note that <module>mod_rewrite</module>
1188 tries to guess whether you have specified a file-system path
1189 or a URL-path by checking to see if the first segment of the
1190 path exists at the root of the file-system. For example, if
1191 you specify a <em>Substitution</em> string of
1192 <code>/www/file.html</code>, then this will be treated as a
1193 URL-path <em>unless</em> a directory named <code>www</code>
1194 exists at the root or your file-system (or, in the case of
1195 using rewrites in a <code>.htaccess</code> file, relative to
1196 your document root), in which case it will
1197 be treated as a file-system path. If you wish other
1198 URL-mapping directives (such as <directive
1199 module="mod_alias">Alias</directive>) to be applied to the
1200 resulting URL-path, use the <code>[PT]</code> flag as
1201 described below.</dd>
1203 <dt>Absolute URL</dt>
1205 <dd>If an absolute URL is specified,
1206 <module>mod_rewrite</module> checks to see whether the
1207 hostname matches the current host. If it does, the scheme and
1208 hostname are stripped out and the resulting path is treated as
1209 a URL-path. Otherwise, an external redirect is performed for
1210 the given URL. To force an external redirect back to the
1211 current host, see the <code>[R]</code> flag below.</dd>
1213 <dt><code>-</code> (dash)</dt>
1215 <dd>A dash indicates that no substitution should be performed
1216 (the existing path is passed through untouched). This is used
1217 when a flag (see below) needs to be applied without changing
1222 <p>In addition to plain text, the <em>Substitution</em> string can include</p>
1225 <li>back-references (<code>$N</code>) to the RewriteRule
1228 <li>back-references (<code>%N</code>) to the last matched
1229 RewriteCond pattern</li>
1231 <li>server-variables as in rule condition test-strings
1232 (<code>%{VARNAME}</code>)</li>
1234 <li><a href="#mapfunc">mapping-function</a> calls
1235 (<code>${mapname:key|default}</code>)</li>
1238 <p>Back-references are identifiers of the form
1239 <code>$</code><strong>N</strong>
1240 (<strong>N</strong>=0..9), which will be replaced
1241 by the contents of the <strong>N</strong>th group of the
1242 matched <em>Pattern</em>. The server-variables are the same
1243 as for the <em>TestString</em> of a
1244 <directive module="mod_rewrite">RewriteCond</directive>
1245 directive. The mapping-functions come from the
1246 <directive module="mod_rewrite">RewriteMap</directive>
1247 directive and are explained there.
1248 These three types of variables are expanded in the order above.</p>
1250 <p>Rewrite rules are applied to the results of previous rewrite
1251 rules, in the order in which they are defined
1252 in the config file. The URL-path or file-system path (see <a
1253 href="#what_is_matched">"What is matched?"</a>, above) is <strong>completely
1254 replaced</strong> by the <em>Substitution</em> and the
1255 rewriting process continues until all rules have been applied,
1256 or it is explicitly terminated by an
1257 <a href="../rewrite/flags.html#flag_l"><code><strong>L</strong></code> flag</a>,
1258 or other flag which implies immediate termination, such as
1259 <code><strong>END</strong></code> or
1260 <code><strong>F</strong></code>.</p>
1262 <note><title>Modifying the Query String</title>
1263 <p>By default, the query string is passed through unchanged. You
1264 can, however, create URLs in the substitution string containing
1265 a query string part. Simply use a question mark inside the
1266 substitution string to indicate that the following text should
1267 be re-injected into the query string. When you want to erase an
1268 existing query string, end the substitution string with just a
1269 question mark. To combine new and old query strings, use the
1270 <code>[QSA]</code> flag.</p>
1273 <p>Additionally you can set special <a name="rewriteflags"
1274 id="rewriteflags">actions</a> to be performed by
1275 appending <strong><code>[</code><em>flags</em><code>]</code></strong>
1276 as the third argument to the <directive>RewriteRule</directive>
1277 directive. <em>Flags</em> is a comma-separated list, surround by square
1278 brackets, of any of the flags in the following table. More
1279 details, and examples, for each flag, are available in the <a
1280 href="../rewrite/flags.html">Rewrite Flags document</a>.</p>
1282 <table border="1" style="zebra">
1283 <tr><th>Flag and syntax</th>
1288 <td>Escape non-alphanumeric characters in backreferences <em>before</em>
1289 applying the transformation. <em><a
1290 href="../rewrite/flags.html#flag_b">details ...</a></em></td>
1293 <td>backrefnoplus|BNP</td>
1294 <td>If backreferences are being escaped, spaces should be escaped to
1295 %20 instead of +. Useful when the backreference will be used in the
1296 path component rather than the query string.<em><a
1297 href="../rewrite/flags.html#flag_bnp">details ...</a></em></td>
1302 <td>Rule is chained to the following rule. If the rule fails,
1303 the rule(s) chained to it will be skipped. <em><a
1304 href="../rewrite/flags.html#flag_c">details ...</a></em></td>
1307 <td>cookie|CO=<em>NAME</em>:<em>VAL</em></td>
1308 <td>Sets a cookie in the client browser. Full syntax is:
1309 CO=<em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>[:<em>secure</em>[:<em>httponly</em>]]]] <em><a href="../rewrite/flags.html#flag_co">details ...</a></em>
1313 <td>discardpath|DPI</td>
1314 <td>Causes the PATH_INFO portion of the rewritten URI to be
1315 discarded. <em><a href="../rewrite/flags.html#flag_dpi">details
1320 <td>Stop the rewriting process immediately and don't apply any
1321 more rules. Also prevents further execution of rewrite rules
1322 in per-directory and .htaccess context. (Available in 2.3.9 and later)
1323 <em><a href="../rewrite/flags.html#flag_end">details ...</a></em></td>
1326 <td>env|E=[!]<em>VAR</em>[:<em>VAL</em>]</td>
1327 <td>Causes an environment variable <em>VAR</em> to be set (to the
1328 value <em>VAL</em> if provided). The form !<em>VAR</em> causes
1329 the environment variable <em>VAR</em> to be unset.
1330 <em><a href="../rewrite/flags.html#flag_e">details ...</a></em></td>
1333 <td>forbidden|F</td>
1334 <td>Returns a 403 FORBIDDEN response to the client browser.
1335 <em><a href="../rewrite/flags.html#flag_f">details ...</a></em></td>
1339 <td>Returns a 410 GONE response to the client browser. <em><a
1340 href="../rewrite/flags.html#flag_g">details ...</a></em></td>
1343 <td>Handler|H=<em>Content-handler</em></td>
1344 <td>Causes the resulting URI to be sent to the specified
1345 <em>Content-handler</em> for processing. <em><a
1346 href="../rewrite/flags.html#flag_h">details ...</a></em></td>
1350 <td>Stop the rewriting process immediately and don't apply any
1351 more rules. Especially note caveats for per-directory and
1352 .htaccess context (see also the END flag). <em><a
1353 href="../rewrite/flags.html#flag_l">details ...</a></em></td>
1357 <td>Re-run the rewriting process, starting again with the first
1358 rule, using the result of the ruleset so far as a starting
1359 point. <em><a href="../rewrite/flags.html#flag_n">details
1364 <td>Makes the pattern comparison case-insensitive.
1365 <em><a href="../rewrite/flags.html#flag_nc">details ...</a></em></td>
1368 <td>noescape|NE</td>
1369 <td>Prevent mod_rewrite from applying hexcode escaping of
1370 special characters in the result of the rewrite. <em><a
1371 href="../rewrite/flags.html#flag_ne">details ...</a></em></td>
1374 <td>nosubreq|NS</td>
1375 <td>Causes a rule to be skipped if the current request is an
1376 internal sub-request. <em><a
1377 href="../rewrite/flags.html#flag_ns">details ...</a></em></td>
1381 <td>Force the substitution URL to be internally sent as a proxy
1382 request. <em><a href="../rewrite/flags.html#flag_p">details
1386 <td>passthrough|PT</td>
1387 <td>Forces the resulting URI to be passed back to the URL
1388 mapping engine for processing of other URI-to-filename
1389 translators, such as <code>Alias</code> or
1390 <code>Redirect</code>. <em><a
1391 href="../rewrite/flags.html#flag_pt">details ...</a></em></td>
1394 <td>qsappend|QSA</td>
1395 <td>Appends any query string from the original request URL to
1396 any query string created in the rewrite target.<em><a
1397 href="../rewrite/flags.html#flag_qsa">details ...</a></em></td>
1400 <td>qsdiscard|QSD</td>
1401 <td>Discard any query string attached to the incoming URI.
1402 <em><a href="../rewrite/flags.html#flag_qsd">details
1407 <td>Interpret the last (right-most) question mark as the query string
1408 delimiter, instead of the first (left-most) as normally used.
1409 Available in 2.4.19 and later.
1410 <em><a href="../rewrite/flags.html#flag_qsl">details
1415 <td>redirect|R[=<em>code</em>]</td>
1416 <td>Forces an external redirect, optionally with the specified
1417 HTTP status code. <em><a
1418 href="../rewrite/flags.html#flag_r">details ...</a></em>
1422 <td>skip|S=<em>num</em></td>
1423 <td>Tells the rewriting engine to skip the next <em>num</em>
1424 rules if the current rule matches. <em><a
1425 href="../rewrite/flags.html#flag_s">details ...</a></em></td>
1428 <td>type|T=<em>MIME-type</em></td>
1429 <td>Force the <glossary>MIME-type</glossary> of the target file
1430 to be the specified type. <em><a
1431 href="../rewrite/flags.html#flag_t">details ...</a></em></td>
1435 <note><title>Home directory expansion</title>
1436 <p> When the substitution string begins with a string
1437 resembling "/~user" (via explicit text or backreferences), <module>mod_rewrite</module> performs
1438 home directory expansion independent of the presence or configuration
1439 of <module>mod_userdir</module>.</p>
1441 <p> This expansion does not occur when the <em>PT</em>
1442 flag is used on the <directive module="mod_rewrite">RewriteRule</directive>
1447 <p>Here are all possible substitution combinations and their
1450 <p><strong>Inside per-server configuration
1451 (<code>httpd.conf</code>)<br />
1452 for request ``<code>GET
1453 /somepath/pathinfo</code>'':</strong><br />
1456 <table border="1" style="zebra">
1459 <th>Resulting Substitution</th>
1463 <td>^/somepath(.*) otherpath$1</td>
1464 <td>invalid, not supported</td>
1468 <td>^/somepath(.*) otherpath$1 [R]</td>
1469 <td>invalid, not supported</td>
1473 <td>^/somepath(.*) otherpath$1 [P]</td>
1474 <td>invalid, not supported</td>
1478 <td>^/somepath(.*) /otherpath$1</td>
1479 <td>/otherpath/pathinfo</td>
1483 <td>^/somepath(.*) /otherpath$1 [R]</td>
1484 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1488 <td>^/somepath(.*) /otherpath$1 [P]</td>
1489 <td>doesn't make sense, not supported</td>
1493 <td>^/somepath(.*) http://thishost/otherpath$1</td>
1494 <td>/otherpath/pathinfo</td>
1498 <td>^/somepath(.*) http://thishost/otherpath$1 [R]</td>
1499 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1503 <td>^/somepath(.*) http://thishost/otherpath$1 [P]</td>
1504 <td>doesn't make sense, not supported</td>
1508 <td>^/somepath(.*) http://otherhost/otherpath$1</td>
1509 <td>http://otherhost/otherpath/pathinfo via external redirection</td>
1513 <td>^/somepath(.*) http://otherhost/otherpath$1 [R]</td>
1514 <td>http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant)</td>
1518 <td>^/somepath(.*) http://otherhost/otherpath$1 [P]</td>
1519 <td>http://otherhost/otherpath/pathinfo via internal proxy</td>
1523 <p><strong>Inside per-directory configuration for
1524 <code>/somepath</code><br />
1525 (<code>/physical/path/to/somepath/.htaccess</code>, with
1526 <code>RewriteBase "/somepath"</code>)<br />
1527 for request ``<code>GET
1528 /somepath/localpath/pathinfo</code>'':</strong><br />
1531 <table border="1" style="zebra">
1535 <th>Resulting Substitution</th>
1539 <td>^localpath(.*) otherpath$1</td>
1540 <td>/somepath/otherpath/pathinfo</td>
1544 <td>^localpath(.*) otherpath$1 [R]</td>
1545 <td>http://thishost/somepath/otherpath/pathinfo via external
1550 <td>^localpath(.*) otherpath$1 [P]</td>
1551 <td>doesn't make sense, not supported</td>
1555 <td>^localpath(.*) /otherpath$1</td>
1556 <td>/otherpath/pathinfo</td>
1560 <td>^localpath(.*) /otherpath$1 [R]</td>
1561 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1565 <td>^localpath(.*) /otherpath$1 [P]</td>
1566 <td>doesn't make sense, not supported</td>
1570 <td>^localpath(.*) http://thishost/otherpath$1</td>
1571 <td>/otherpath/pathinfo</td>
1575 <td>^localpath(.*) http://thishost/otherpath$1 [R]</td>
1576 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1580 <td>^localpath(.*) http://thishost/otherpath$1 [P]</td>
1581 <td>doesn't make sense, not supported</td>
1585 <td>^localpath(.*) http://otherhost/otherpath$1</td>
1586 <td>http://otherhost/otherpath/pathinfo via external redirection</td>
1590 <td>^localpath(.*) http://otherhost/otherpath$1 [R]</td>
1591 <td>http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant)</td>
1595 <td>^localpath(.*) http://otherhost/otherpath$1 [P]</td>
1596 <td>http://otherhost/otherpath/pathinfo via internal proxy</td>
1602 </directivesynopsis>