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 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 LogLevel alert rewrite:trace3
75 <note><title>RewriteLog</title>
76 <p>Those familiar with earlier versions of
77 <module>mod_rewrite</module> will no doubt be looking for the
78 <code>RewriteLog</code> and <code>RewriteLogLevel</code>
79 directives. This functionality has been completely replaced by the
80 new per-module logging configuration mentioned above.
83 <p>To get just the <module>mod_rewrite</module>-specific log
84 messages, pipe the log file through grep:</p>
86 tail -f error_log|fgrep '[rewrite:'
93 <name>RewriteEngine</name>
94 <description>Enables or disables runtime rewriting engine</description>
95 <syntax>RewriteEngine on|off</syntax>
96 <default>RewriteEngine off</default>
97 <contextlist><context>server config</context><context>virtual host</context>
98 <context>directory</context><context>.htaccess</context></contextlist>
99 <override>FileInfo</override>
103 <p>The <directive>RewriteEngine</directive> directive enables or
104 disables the runtime rewriting engine. If it is set to
105 <code>off</code> this module does no runtime processing at
106 all. It does not even update the <code>SCRIPT_URx</code>
107 environment variables.</p>
109 <p>Use this directive to disable the module instead of
110 commenting out all the <directive
111 module="mod_rewrite">RewriteRule</directive> directives!</p>
113 <p>Note that rewrite configurations are not
114 inherited by virtual hosts. This means that you need to have a
115 <code>RewriteEngine on</code> directive for each virtual host
116 in which you wish to use rewrite rules.</p>
118 <p><directive>RewriteMap</directive> directives of the type <code>prg</code>
119 are not started during server initialization if they're defined in a
120 context that does not have <directive>RewriteEngine</directive> set to
127 <name>RewriteOptions</name>
128 <description>Sets some special options for the rewrite engine</description>
129 <syntax>RewriteOptions <var>Options</var></syntax>
130 <contextlist><context>server config</context><context>virtual host</context>
131 <context>directory</context><context>.htaccess</context></contextlist>
132 <override>FileInfo</override>
133 <compatibility><code>MaxRedirects</code> is no longer available in version 2.1 and
134 later</compatibility>
137 <p>The <directive>RewriteOptions</directive> directive sets some
138 special options for the current per-server or per-directory
139 configuration. The <em>Option</em> string can currently
140 only be one of the following:</p>
143 <dt><code>Inherit</code></dt>
146 <p>This forces the current configuration to inherit the
147 configuration of the parent. In per-virtual-server context,
148 this means that the maps, conditions and rules of the main
149 server are inherited. In per-directory context this means
150 that conditions and rules of the parent directory's
151 <code>.htaccess</code> configuration or
152 <directive type="section" module="core">Directory</directive>
153 sections are inherited. The inherited rules are virtually copied
154 to the section where this directive is being used. If used in
155 combination with local rules, the inherited rules are copied behind
156 the local rules. The position of this directive - below or above
157 of local rules - has no influence on this behavior. If local
158 rules forced the rewriting to stop, the inherited rules won't
161 <note type="warning">
162 Rules inherited from the parent scope are applied
163 <strong>after</strong> rules specified in the child scope.
167 <dt><code>InheritBefore</code></dt>
169 <p> Like <code>Inherit</code> above, but the rules from the parent scope
170 are applied <strong>before</strong> rules specified in the child scope.
171 Available in Apache HTTP Server 2.3.10 and later.</p>
181 <name>RewriteMap</name>
182 <description>Defines a mapping function for key-lookup</description>
183 <syntax>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
185 <contextlist><context>server config</context><context>virtual host</context>
187 <compatibility>The choice of different dbm types is available in
188 Apache HTTP Server 2.0.41 and later</compatibility>
191 <p>The <directive>RewriteMap</directive> directive defines a
192 <em>Rewriting Map</em> which can be used inside rule
193 substitution strings by the mapping-functions to
194 insert/substitute fields through a key lookup. The source of
195 this lookup can be of various types.</p>
197 <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
198 the name of the map and will be used to specify a
199 mapping-function for the substitution strings of a rewriting
200 rule via one of the following constructs:</p>
203 <strong><code>${</code> <em>MapName</em> <code>:</code>
204 <em>LookupKey</em> <code>}</code><br />
205 <code>${</code> <em>MapName</em> <code>:</code>
206 <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
207 <code>}</code></strong>
210 <p>When such a construct occurs, the map <em>MapName</em> is
211 consulted and the key <em>LookupKey</em> is looked-up. If the
212 key is found, the map-function construct is substituted by
213 <em>SubstValue</em>. If the key is not found then it is
214 substituted by <em>DefaultValue</em> or by the empty string
215 if no <em>DefaultValue</em> was specified. Empty values
216 behave as if the key was absent, therefore it is not possible
217 to distinguish between empty-valued keys and absent keys.</p>
219 <p>For example, you might define a
220 <directive>RewriteMap</directive> as:</p>
223 RewriteMap examplemap txt:/path/to/file/map.txt
226 <p>You would then be able to use this map in a
227 <directive>RewriteRule</directive> as follows:</p>
230 RewriteRule ^/ex/(.*) ${examplemap:$1}
233 <p>The following combinations for <em>MapType</em> and
234 <em>MapSource</em> can be used:</p>
239 <dd>A plain text file containing space-separated key-value
240 pairs, one per line. (<a href="../rewrite/rewritemap.html#txt">Details ...</a>)</dd>
243 <dd>Randomly selects an entry from a plain text file (<a href="../rewrite/rewritemap.html#rnd">Details ...</a>)</dd>
246 <dd>Looks up an entry in a dbm file containing name, value
247 pairs. Hash is constructed from a plain text file format using
248 the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code>
249 utility. (<a href="../rewrite/rewritemap.html#dbm">Details ...</a>)</dd>
252 <dd>One of the four available internal functions provided by
253 <code>RewriteMap</code>: toupper, tolower, escape or
254 unescape. (<a href="../rewrite/rewritemap.html#int">Details ...</a>)</dd>
257 <dd>Calls an external program or script to process the
258 rewriting. (<a href="../rewrite/rewritemap.html#prg">Details ...</a>)</dd>
260 <dt>dbd or fastdbd</dt>
261 <dd>A SQL SELECT statement to be performed to look up the
262 rewrite target. (<a href="../rewrite/rewritemap.html#dbd">Details ...</a>)</dd>
265 <p>Further details, and numerous examples, may be found in the <a
266 href="../rewrite/rewritemap.html">RewriteMap HowTo</a></p>
272 <name>RewriteBase</name>
273 <description>Sets the base URL for per-directory rewrites</description>
274 <syntax>RewriteBase <em>URL-path</em></syntax>
275 <default>None</default>
276 <contextlist><context>directory</context><context>.htaccess</context>
278 <override>FileInfo</override>
281 <p>The <directive>RewriteBase</directive> directive explicitly
282 sets the base URL-path (not filesystem directory path!) for per-directory rewrites
283 that result in the substitution of a relative path.
284 When you use a <directive module="mod_rewrite">RewriteRule</directive>
285 in a <code>.htaccess</code> file, <module>mod_rewrite</module> strips off
286 the local directory prefix before processing, then rewrites the rest of
287 the URL. When the rewrite is completed, <module>mod_rewrite</module>
288 automatically adds the local directory prefix (or the
289 <directive>RewriteBase</directive> when set) back on to the substitution
290 before handing it back to the core of the server as if it were the original
293 <p>This directive is <em>required</em> for per-directory rewrites whose context
294 is a directory made available via the <directive module="mod_alias">Alias</directive>
295 directive, when the substitution uses a relative path.</p>
297 <p>If your URL path does not exist verbatim on the filesystem,
298 or isn't directly under your <directive module="core">DocumentRoot</directive>,
299 you must use <directive>RewriteBase</directive> in every
300 <code>.htaccess</code> file where you want to use <directive
301 module="mod_rewrite">RewriteRule</directive> directives.</p>
303 <p>The example below demonstrates how to map
304 http://example.com/myapp/index.html to
305 /home/www/example/newsite.html, in a <code>.htaccess</code> file. This
306 assumes that the content available at
307 http://example.com/ is on disk at /home/www/example/</p>
311 # The URL-path used to get to this context, not the filesystem path
313 RewriteRule ^index\.html$ newsite.html
322 <name>RewriteCond</name>
323 <description>Defines a condition under which rewriting will take place
326 <em>TestString</em> <em>CondPattern</em></syntax>
327 <contextlist><context>server config</context><context>virtual host</context>
328 <context>directory</context><context>.htaccess</context></contextlist>
329 <override>FileInfo</override>
332 <p>The <directive>RewriteCond</directive> directive defines a
333 rule condition. One or more <directive>RewriteCond</directive>
334 can precede a <directive module="mod_rewrite">RewriteRule</directive>
335 directive. The following rule is then only used if both
336 the current state of the URI matches its pattern, <strong
337 >and</strong> if these conditions are met.</p>
339 <p><em>TestString</em> is a string which can contain the
340 following expanded constructs in addition to plain text:</p>
344 <strong>RewriteRule backreferences</strong>: These are
345 backreferences of the form <strong><code>$N</code></strong>
346 (0 <= N <= 9). $1 to $9 provide access to the grouped
347 parts (in parentheses) of the pattern, from the
348 <code>RewriteRule</code> which is subject to the current
349 set of <code>RewriteCond</code> conditions. $0 provides
350 access to the whole string matched by that pattern.
353 <strong>RewriteCond backreferences</strong>: These are
354 backreferences of the form <strong><code>%N</code></strong>
355 (0 <= N <= 9). %1 to %9 provide access to the grouped
356 parts (again, in parentheses) of the pattern, from the last matched
357 <code>RewriteCond</code> in the current set
358 of conditions. %0 provides access to the whole string matched by
362 <strong>RewriteMap expansions</strong>: These are
363 expansions of the form <strong><code
364 >${mapname:key|default}</code></strong>.
365 See <a href="#mapfunc">the documentation for
366 RewriteMap</a> for more details.
369 <strong>Server-Variables</strong>: These are variables of
371 <strong><code>%{</code> <em>NAME_OF_VARIABLE</em>
372 <code>}</code></strong>
373 where <em>NAME_OF_VARIABLE</em> can be a string taken
374 from the following list:
377 <columnspec><column width=".3"/><column width=".3"/>
378 <column width=".3"/></columnspec>
380 <th>HTTP headers:</th> <th>connection & request:</th> <th></th>
385 HTTP_USER_AGENT<br />
390 HTTP_PROXY_CONNECTION<br />
401 SCRIPT_FILENAME<br />
411 <th>server internals:</th> <th>date and time:</th> <th>specials:</th>
421 SERVER_PROTOCOL<br />
422 SERVER_SOFTWARE<br />
440 REQUEST_FILENAME<br />
448 <p>These variables all
449 correspond to the similarly named HTTP
450 MIME-headers, C variables of the Apache HTTP Server or
451 <code>struct tm</code> fields of the Unix system.
452 Most are documented elsewhere in the Manual or in
453 the CGI specification.</p>
455 <p>SERVER_NAME and SERVER_PORT depend on the values of
456 <directive module="core">UseCanonicalName</directive> and
457 <directive module="core">UseCanonicalPhysicalPort</directive>
460 <p>Those that are special to mod_rewrite include those below.</p>
463 <dt><code>IS_SUBREQ</code></dt>
465 <dd>Will contain the text "true" if the request
466 currently being processed is a sub-request,
467 "false" otherwise. Sub-requests may be generated
468 by modules that need to resolve additional files
469 or URIs in order to complete their tasks.</dd>
471 <dt><code>API_VERSION</code></dt>
473 <dd>This is the version of the Apache httpd module API
474 (the internal interface between server and
475 module) in the current httpd build, as defined in
476 include/ap_mmn.h. The module API version
477 corresponds to the version of Apache httpd in use (in
478 the release version of Apache httpd 1.3.14, for
479 instance, it is 19990320:10), but is mainly of
480 interest to module authors.</dd>
482 <dt><code>THE_REQUEST</code></dt>
484 <dd>The full HTTP request line sent by the
485 browser to the server (e.g., "<code>GET
486 /index.html HTTP/1.1</code>"). This does not
487 include any additional headers sent by the
488 browser. This value has not been unescaped
489 (decoded), unlike most other variables below.</dd>
491 <dt><code>REQUEST_URI</code></dt>
493 <dd>The resource requested in the HTTP request
494 line. (In the example above, this would be
497 <dt><code>REQUEST_FILENAME</code></dt>
499 <dd>The full local filesystem path to the file or
500 script matching the request, if this has already
501 been determined by the server at the time
502 <code>REQUEST_FILENAME</code> is referenced. Otherwise,
503 such as when used in virtual host context, the same
504 value as <code>REQUEST_URI</code>.</dd>
506 <dt><code>HTTPS</code></dt>
508 <dd>Will contain the text "on" if the connection is
509 using SSL/TLS, or "off" otherwise. (This variable
510 can be safely used regardless of whether or not
511 <module>mod_ssl</module> is loaded).</dd>
513 <dt><code>REQUEST_SCHEME</code></dt>
515 <dd>Will contain the scheme of the request (ususally
516 "http" or "https"). This value can be influenced with
517 <directive module="core">ServerName</directive>.</dd>
524 <p>If the <em>TestString</em> has the special value <code>expr</code>, the
525 <em>CondPattern</em> will be treated as a
526 <a href="../expr.html">ap_expr</a>.</p>
528 <p>Other things you should be aware of:</p>
532 <p>The variables SCRIPT_FILENAME and REQUEST_FILENAME
533 contain the same value - the value of the
534 <code>filename</code> field of the internal
535 <code>request_rec</code> structure of the Apache HTTP Server.
536 The first name is the commonly known CGI variable name
537 while the second is the appropriate counterpart of
538 REQUEST_URI (which contains the value of the
539 <code>uri</code> field of <code>request_rec</code>).</p>
540 <p>If a substitution occurred and the rewriting continues,
541 the value of both variables will be updated accordingly.</p>
542 <p>If used in per-server context (<em>i.e.</em>, before the
543 request is mapped to the filesystem) SCRIPT_FILENAME and
544 REQUEST_FILENAME cannot contain the full local filesystem
545 path since the path is unknown at this stage of processing.
546 Both variables will initially contain the value of REQUEST_URI
547 in that case. In order to obtain the full local filesystem
548 path of the request in per-server context, use an URL-based
549 look-ahead <code>%{LA-U:REQUEST_FILENAME}</code> to determine
550 the final value of REQUEST_FILENAME.</p></li>
553 <code>%{ENV:variable}</code>, where <em>variable</em> can be
554 any environment variable, is also available.
555 This is looked-up via internal
556 Apache httpd structures and (if not found there) via
557 <code>getenv()</code> from the Apache httpd server process.</li>
560 <code>%{SSL:variable}</code>, where <em>variable</em> is the
561 name of an <a href="mod_ssl.html#envvars">SSL environment
562 variable</a>, can be used whether or not
563 <module>mod_ssl</module> is loaded, but will always expand to
564 the empty string if it is not. Example:
565 <code>%{SSL:SSL_CIPHER_USEKEYSIZE}</code> may expand to
566 <code>128</code>.</li>
569 <code>%{HTTP:header}</code>, where <em>header</em> can be
570 any HTTP MIME-header name, can always be used to obtain the
571 value of a header sent in the HTTP request.
572 Example: <code>%{HTTP:Proxy-Connection}</code> is
573 the value of the HTTP header
574 ``<code>Proxy-Connection:</code>''.
575 <p>If a HTTP header is used in a condition this header is added to
576 the Vary header of the response in case the condition evaluates to
577 to true for the request. It is <strong>not</strong> added if the
578 condition evaluates to false for the request. Adding the HTTP header
579 to the Vary header of the response is needed for proper caching.</p>
580 <p>It has to be kept in mind that conditions follow a short circuit
581 logic in the case of the '<strong><code>ornext|OR</code></strong>' flag
582 so that certain conditions might not be evaluated at all.</p></li>
585 <code>%{LA-U:variable}</code> can be used for look-aheads which perform
586 an internal (URL-based) sub-request to determine the final
587 value of <em>variable</em>. This can be used to access
588 variable for rewriting which is not available at the current
589 stage, but will be set in a later phase.
590 <p>For instance, to rewrite according to the
591 <code>REMOTE_USER</code> variable from within the
592 per-server context (<code>httpd.conf</code> file) you must
593 use <code>%{LA-U:REMOTE_USER}</code> - this
594 variable is set by the authorization phases, which come
595 <em>after</em> the URL translation phase (during which mod_rewrite
597 <p>On the other hand, because mod_rewrite implements
598 its per-directory context (<code>.htaccess</code> file) via
599 the Fixup phase of the API and because the authorization
600 phases come <em>before</em> this phase, you just can use
601 <code>%{REMOTE_USER}</code> in that context.</p></li>
604 <code>%{LA-F:variable}</code> can be used to perform an internal
605 (filename-based) sub-request, to determine the final value
606 of <em>variable</em>. Most of the time, this is the same as
610 <p><em>CondPattern</em> is the condition pattern,
611 a regular expression which is applied to the
612 current instance of the <em>TestString</em>.
613 <em>TestString</em> is first evaluated, before being matched against
614 <em>CondPattern</em>.</p>
616 <p><em>CondPattern</em> is usually a
617 <em>perl compatible regular expression</em>, but there is
618 additional syntax available to perform other useful tests against
619 the <em>Teststring</em>:</p>
622 <li>You can prefix the pattern string with a
623 '<code>!</code>' character (exclamation mark) to specify a
624 <strong>non</strong>-matching pattern.</li>
627 You can perform lexicographical string comparisons:
630 <li>'<strong><CondPattern</strong>' (lexicographically
632 Treats the <em>CondPattern</em> as a plain string and
633 compares it lexicographically to <em>TestString</em>. True if
634 <em>TestString</em> lexicographically precedes
635 <em>CondPattern</em>.</li>
637 <li>'<strong>>CondPattern</strong>' (lexicographically
639 Treats the <em>CondPattern</em> as a plain string and
640 compares it lexicographically to <em>TestString</em>. True if
641 <em>TestString</em> lexicographically follows
642 <em>CondPattern</em>.</li>
644 <li>'<strong>=CondPattern</strong>' (lexicographically
646 Treats the <em>CondPattern</em> as a plain string and
647 compares it lexicographically to <em>TestString</em>. True if
648 <em>TestString</em> is lexicographically equal to
649 <em>CondPattern</em> (the two strings are exactly
650 equal, character for character). If <em>CondPattern</em>
651 is <code>""</code> (two quotation marks) this
652 compares <em>TestString</em> to the empty string.</li>
654 <li>'<strong><=CondPattern</strong>' (lexicographically
655 less than or equal to)<br />
656 Treats the <em>CondPattern</em> as a plain string and
657 compares it lexicographically to <em>TestString</em>. True
658 if <em>TestString</em> lexicographically precedes
659 <em>CondPattern</em>, or is equal to <em>CondPattern</em>
660 (the two strings are equal, character for character).</li>
662 <li>'<strong>>=CondPattern</strong>' (lexicographically
663 greater than or equal to)<br />
664 Treats the <em>CondPattern</em> as a plain string and
665 compares it lexicographically to <em>TestString</em>. True
666 if <em>TestString</em> lexicographically follows
667 <em>CondPattern</em>, or is equal to <em>CondPattern</em>
668 (the two strings are equal, character for character).</li>
672 You can perform integer comparisons:
675 <li>'<strong>-eq</strong>' (is numerically
676 <strong>eq</strong>ual to)<br />
677 The <em>TestString</em> is treated as an integer, and is
678 numerically compared to the <em>CondPattern</em>. True if
679 the two are numerically equal.</li>
681 <li>'<strong>-ge</strong>' (is numerically
682 <strong>g</strong>reater than or <strong>e</strong>qual to)<br />
683 The <em>TestString</em> is treated as an integer, and is
684 numerically compared to the <em>CondPattern</em>. True if
685 the <em>TestString</em> is numerically greater than or equal
686 to the <em>CondPattern</em>.</li>
688 <li>'<strong>-gt</strong>' (is numerically
689 <strong>g</strong>reater <strong>t</strong>han)<br />
690 The <em>TestString</em> is treated as an integer, and is
691 numerically compared to the <em>CondPattern</em>. True if
692 the <em>TestString</em> is numerically greater than
693 the <em>CondPattern</em>.</li>
695 <li>'<strong>-le</strong>' (is numerically
696 <strong>l</strong>ess than or <strong>e</strong>qual to)<br />
697 The <em>TestString</em> is treated as an integer, and is
698 numerically compared to the <em>CondPattern</em>. True if
699 the <em>TestString</em> is numerically less than or equal
700 to the <em>CondPattern</em>. Avoid confusion with the
701 <strong>-l</strong> by using the <strong>-L</strong> or
702 <strong>-h</strong> variant.</li>
704 <li>'<strong>-lt</strong>' (is numerically
705 <strong>l</strong>ess <strong>t</strong>han)<br />
706 The <em>TestString</em> is treated as an integer, and is
707 numerically compared to the <em>CondPattern</em>. True if
708 the <em>TestString</em> is numerically less than
709 the <em>CondPattern</em>. Avoid confusion with the
710 <strong>-l</strong> by using the <strong>-L</strong> or
711 <strong>-h</strong> variant.</li>
716 <li>You can perform various file attribute tests:
718 <li>'<strong>-d</strong>' (is
719 <strong>d</strong>irectory)<br />
720 Treats the <em>TestString</em> as a pathname and tests
721 whether or not it exists, and is a directory.</li>
723 <li>'<strong>-f</strong>' (is regular
724 <strong>f</strong>ile)<br />
725 Treats the <em>TestString</em> as a pathname and tests
726 whether or not it exists, and is a regular file.</li>
728 <li>'<strong>-F</strong>' (is existing file, via
730 Checks whether or not <em>TestString</em> is a valid file,
731 accessible via all the server's currently-configured
732 access controls for that path. This uses an internal
733 subrequest to do the check, so use it with care -
734 it can impact your server's performance!</li>
736 <li>'<strong>-H</strong>' (is symbolic link, bash convention)<br />
737 See <strong>-l</strong>.</li>
739 <li>'<strong>-l</strong>' (is symbolic
740 <strong>l</strong>ink)<br />
741 Treats the <em>TestString</em> as a pathname and tests
742 whether or not it exists, and is a symbolic link. May also
743 use the bash convention of <strong>-L</strong> or
744 <strong>-h</strong> if there's a possibility of confusion
745 such as when using the <strong>-lt</strong> or
746 <strong>-le</strong> tests.</li>
748 <li>'<strong>-L</strong>' (is symbolic link, bash convention)<br />
749 See <strong>-l</strong>.</li>
751 <li>'<strong>-s</strong>' (is regular file, with
752 <strong>s</strong>ize)<br />
753 Treats the <em>TestString</em> as a pathname and tests
754 whether or not it exists, and is a regular file with size greater
757 <li>'<strong>-U</strong>' (is existing URL, via
759 Checks whether or not <em>TestString</em> is a valid URL,
760 accessible via all the server's currently-configured
761 access controls for that path. This uses an internal
762 subrequest to do the check, so use it with care -
763 it can impact your server's performance!</li>
765 <li>'<strong>-x</strong>' (has e<strong>x</strong>ecutable
767 Treats the <em>TestString</em> as a pathname and tests
768 whether or not it exists, and has executable permissions.
769 These permissions are determined according to
770 the underlying OS.</li>
774 <note><title>Note:</title>
775 All of these tests can
776 also be prefixed by an exclamation mark ('!') to
777 negate their meaning.
782 <p>If the <em>TestString</em> has the special value <code>expr</code>, the
783 <em>CondPattern</em> will be treated as a
784 <a href="../expr.html">ap_expr</a>.</p>
787 In the below example, <code>-strmatch</code> is used to
788 compare the <code>REFERER</code> against the site hostname,
789 to block unwanted hotlinking.
793 RewriteCond expr "! %{HTTP_REFERER} -strmatch '*://%{HTTP_HOST}/*'"<br />
794 RewriteRule ^/images - [F]
798 <li>You can also set special flags for
799 <em>CondPattern</em> by appending
800 <strong><code>[</code><em>flags</em><code>]</code></strong>
801 as the third argument to the <code>RewriteCond</code>
802 directive, where <em>flags</em> is a comma-separated list of any of the
806 <li>'<strong><code>nocase|NC</code></strong>'
807 (<strong>n</strong>o <strong>c</strong>ase)<br />
808 This makes the test case-insensitive - differences
809 between 'A-Z' and 'a-z' are ignored, both in the
810 expanded <em>TestString</em> and the <em>CondPattern</em>.
811 This flag is effective only for comparisons between
812 <em>TestString</em> and <em>CondPattern</em>. It has no
813 effect on filesystem and subrequest checks.</li>
816 '<strong><code>ornext|OR</code></strong>'
817 (<strong>or</strong> next condition)<br />
818 Use this to combine rule conditions with a local OR
819 instead of the implicit AND. Typical example:
823 RewriteCond %{REMOTE_HOST} ^host1 [OR]
824 RewriteCond %{REMOTE_HOST} ^host2 [OR]
825 RewriteCond %{REMOTE_HOST} ^host3
826 RewriteRule ...some special stuff for any of these hosts...
830 Without this flag you would have to write the condition/rule
834 <li>'<strong><code>novary|NV</code></strong>'
835 (<strong>n</strong>o <strong>v</strong>ary)<br />
836 If a HTTP header is used in the condition, this flag prevents
837 this header from being added to the Vary header of the response. <br />
838 Using this flag might break proper caching of the response if
839 the representation of this response varies on the value of this header.
840 So this flag should be only used if the meaning of the Vary header
847 <p><strong>Example:</strong></p>
849 <p>To rewrite the Homepage of a site according to the
850 ``<code>User-Agent:</code>'' header of the request, you can
851 use the following: </p>
855 RewriteCond %{HTTP_USER_AGENT} ^Mozilla
856 RewriteRule ^/$ /homepage.max.html [L]
858 RewriteCond %{HTTP_USER_AGENT} ^Lynx
859 RewriteRule ^/$ /homepage.min.html [L]
861 RewriteRule ^/$ /homepage.std.html [L]
865 <p>Explanation: If you use a browser which identifies itself
866 as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you
867 get the max homepage (which could include frames, or other special
869 If you use the Lynx browser (which is terminal-based), then
870 you get the min homepage (which could be a version designed for
871 easy, text-only browsing).
872 If neither of these conditions apply (you use any other browser,
873 or your browser identifies itself as something non-standard), you get
874 the std (standard) homepage.</p>
881 <name>RewriteRule</name>
882 <description>Defines rules for the rewriting engine</description>
884 <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</syntax>
885 <contextlist><context>server config</context><context>virtual host</context>
886 <context>directory</context><context>.htaccess</context></contextlist>
887 <override>FileInfo</override>
890 <p>The <directive>RewriteRule</directive> directive is the real
891 rewriting workhorse. The directive can occur more than once,
892 with each instance defining a single rewrite rule. The
893 order in which these rules are defined is important - this is the order
894 in which they will be applied at run-time.</p>
896 <p><a id="patterns" name="patterns"><em>Pattern</em></a> is
897 a perl compatible <a id="regexp" name="regexp">regular
898 expression</a>. On the first RewriteRule it is applied to the (%-decoded)
899 <a href="./directive-dict.html#Syntax">URL-path</a> of the request;
900 subsequent patterns are applied to the output of the last matched
903 <note><title>What is matched?</title>
904 <p>In <directive module="core">VirtualHost</directive> context,
905 The <em>Pattern</em> will initially be matched against the part of the
906 URL after the hostname and port, and before the query string (e.g. "/app1/index.html").</p>
908 <p>In <directive module="core">Directory</directive> and htaccess context,
909 the <em>Pattern</em> will initially be matched against the
910 <em>filesystem</em> path, after removing the prefix that lead the server
911 to the current <directive>RewriteRule</directive> (e.g. "app1/index.html"
912 or "index.html" depending on where the directives are defined).</p>
914 <p>If you wish to match against the hostname, port, or query string, use a
915 <directive module="mod_rewrite">RewriteCond</directive> with the
916 <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
917 <code>%{QUERY_STRING}</code> variables respectively.</p>
921 <note><title>Per-directory Rewrites</title>
923 <li>The rewrite engine may be used in <a
924 href="../howto/htaccess.html">.htaccess</a> files and in <directive type="section"
925 module="core">Directory</directive> sections, with some additional
928 <li>To enable the rewrite engine in this context, you need to set
929 "<code>RewriteEngine On</code>" <strong>and</strong>
930 "<code>Options FollowSymLinks</code>" must be enabled. If your
931 administrator has disabled override of <code>FollowSymLinks</code> for
932 a user's directory, then you cannot use the rewrite engine. This
933 restriction is required for security reasons.</li>
935 <li>When using the rewrite engine in <code>.htaccess</code> files the
936 per-directory prefix (which always is the same for a specific
937 directory) is automatically <em>removed</em> for the RewriteRule pattern matching
938 and automatically <em>added</em> after any relative (not starting with a
939 slash or protocol name) substitution encounters the end of a rule set.
940 See the <directive module="mod_rewrite">RewriteBase</directive>
941 directive for more information regarding what prefix will be added back to
942 relative substutions.</li>
944 <li> If you wish to match against the full URL-path in a per-directory
945 (htaccess) RewriteRule, use the <code>%{REQUEST_URI}</code> variable in
946 a <directive>RewriteCond</directive>.</li>
948 <li>The removed prefix always ends with a slash, meaning the matching occurs against a string which
949 <em>never</em> has a leading slash. Therefore, a <em>Pattern</em> with <code>^/</code> never
950 matches in per-directory context.</li>
952 <li>Although rewrite rules are syntactically permitted in <directive
953 type="section" module="core">Location</directive> and <directive
954 type="section" module="core">Files</directive> sections, this
955 should never be necessary and is unsupported.</li>
959 <p>For some hints on <glossary ref="regex">regular
960 expressions</glossary>, see
961 the <a href="../rewrite/intro.html#regex">mod_rewrite
962 Introduction</a>.</p>
964 <p>In mod_rewrite, the NOT character
965 ('<code>!</code>') is also available as a possible pattern
966 prefix. This enables you to negate a pattern; to say, for instance:
967 ``<em>if the current URL does <strong>NOT</strong> match this
968 pattern</em>''. This can be used for exceptional cases, where
969 it is easier to match the negative pattern, or as a last
972 <note><title>Note</title>
973 When using the NOT character to negate a pattern, you cannot include
974 grouped wildcard parts in that pattern. This is because, when the
975 pattern does NOT match (ie, the negation matches), there are no
976 contents for the groups. Thus, if negated patterns are used, you
977 cannot use <code>$N</code> in the substitution string!
980 <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
981 rewrite rule is the string that replaces the original URL-path that
982 was matched by <em>Pattern</em>. The <em>Substitution</em> may
987 <dt>file-system path</dt>
989 <dd>Designates the location on the file-system of the resource
990 to be delivered to the client.</dd>
995 module="core">DocumentRoot</directive>-relative path to the
996 resource to be served. Note that <module>mod_rewrite</module>
997 tries to guess whether you have specified a file-system path
998 or a URL-path by checking to see if the first segment of the
999 path exists at the root of the file-system. For example, if
1000 you specify a <em>Substitution</em> string of
1001 <code>/www/file.html</code>, then this will be treated as a
1002 URL-path <em>unless</em> a directory named <code>www</code>
1003 exists at the root or your file-system, in which case it will
1004 be treated as a file-system path. If you wish other
1005 URL-mapping directives (such as <directive
1006 module="mod_alias">Alias</directive>) to be applied to the
1007 resulting URL-path, use the <code>[PT]</code> flag as
1008 described below.</dd>
1010 <dt>Absolute URL</dt>
1012 <dd>If an absolute URL is specified,
1013 <module>mod_rewrite</module> checks to see whether the
1014 hostname matches the current host. If it does, the scheme and
1015 hostname are stripped out and the resulting path is treated as
1016 a URL-path. Otherwise, an external redirect is performed for
1017 the given URL. To force an external redirect back to the
1018 current host, see the <code>[R]</code> flag below.</dd>
1020 <dt><code>-</code> (dash)</dt>
1022 <dd>A dash indicates that no substitution should be performed
1023 (the existing path is passed through untouched). This is used
1024 when a flag (see below) needs to be applied without changing
1029 <p>In addition to plain text, the <em>Substition</em> string can include</p>
1032 <li>back-references (<code>$N</code>) to the RewriteRule
1035 <li>back-references (<code>%N</code>) to the last matched
1036 RewriteCond pattern</li>
1038 <li>server-variables as in rule condition test-strings
1039 (<code>%{VARNAME}</code>)</li>
1041 <li><a href="#mapfunc">mapping-function</a> calls
1042 (<code>${mapname:key|default}</code>)</li>
1045 <p>Back-references are identifiers of the form
1046 <code>$</code><strong>N</strong>
1047 (<strong>N</strong>=0..9), which will be replaced
1048 by the contents of the <strong>N</strong>th group of the
1049 matched <em>Pattern</em>. The server-variables are the same
1050 as for the <em>TestString</em> of a <code>RewriteCond</code>
1051 directive. The mapping-functions come from the
1052 <code>RewriteMap</code> directive and are explained there.
1053 These three types of variables are expanded in the order above.</p>
1055 <p>As already mentioned, all rewrite rules are
1056 applied to the <em>Substitution</em> (in the order in which
1058 in the config file). The URL is <strong>completely
1059 replaced</strong> by the <em>Substitution</em> and the
1060 rewriting process continues until all rules have been applied,
1061 or it is explicitly terminated by a
1062 <code><strong>L</strong></code> flag.</p>
1064 <note><title>Modifying the Query String</title>
1065 <p>By default, the query string is passed through unchanged. You
1066 can, however, create URLs in the substitution string containing
1067 a query string part. Simply use a question mark inside the
1068 substitution string to indicate that the following text should
1069 be re-injected into the query string. When you want to erase an
1070 existing query string, end the substitution string with just a
1071 question mark. To combine new and old query strings, use the
1072 <code>[QSA]</code> flag.</p>
1075 <p>Additionally you can set special <a name="rewriteflags"
1076 id="rewriteflags">actions</a> to be performed by
1077 appending <strong><code>[</code><em>flags</em><code>]</code></strong>
1078 as the third argument to the <code>RewriteRule</code>
1079 directive. <em>Flags</em> is a comma-separated list, surround by square
1080 brackets, of any of the flags in the following table. More
1081 details, and examples, for each flag, are available in the <a
1082 href="../rewrite/flags.html">Rewrite Flags document</a>.</p>
1085 <tr><th>Flag and syntax</th>
1090 <td>Escape non-alphanumeric characters <em>before</em> applying
1091 the transformation. <em><a
1092 href="../rewrite/flags.html#flag_b">details ...</a></em></td>
1096 <td>Rule is chained to the following rule. If the rule fails,
1097 the rule(s) chained to it will be skipped. <em><a
1098 href="../rewrite/flags.html#flag_c">details ...</a></em></td>
1101 <td>cookie|CO=<em>NAME</em>:<em>VAL</em></td>
1102 <td>Sets a cookie in the client browser. Full syntax is:
1103 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>
1107 <td>discardpath|DPI</td>
1108 <td>Causes the PATH_INFO portion of the rewritten URI to be
1109 discarded. <em><a href="../rewrite/flags.html#flag_dpi">details
1113 <td>env|E=[!]<em>VAR</em>[:<em>VAL</em>]</td>
1114 <td>Causes an environment variable <em>VAR</em> to be set (to the
1115 value <em>VAL</em> if provided). The form !<em>VAR</em> causes
1116 the environment variable <em>VAR</em> to be unset.<em><a
1117 href="../rewrite/flags.html#flag_e">details ...</a></em></td>
1120 <td>forbidden|F</td>
1121 <td>Returns a 403 FORBIDDEN response to the client browser.
1122 <em><a href="../rewrite/flags.html#flag_f">details ...</a></em></td>
1126 <td>Returns a 410 GONE response to the client browser. <em><a
1127 href="../rewrite/flags.html#flag_g">details ...</a></em></td>
1130 <td>Handler|H=<em>Content-handler</em></td>
1131 <td>Causes the resulting URI to be sent to the specified
1132 <em>Content-handler</em> for processing. <em><a
1133 href="../rewrite/flags.html#flag_h">details ...</a></em></td>
1137 <td>Stop the rewriting process immediately and don't apply any
1138 more rules. Especially note caveats for per-directory and
1139 .htaccess context (see also the END flag). <em><a
1140 href="../rewrite/flags.html#flag_l">details ...</a></em></td>
1144 <td>Re-run the rewriting process, starting again with the first
1145 rule, using the result of the ruleset so far as a starting
1146 point. <em><a href="../rewrite/flags.html#flag_n">details
1151 <td>Makes the pattern pattern comparison case-insensitive.
1152 <em><a href="../rewrite/flags.html#flag_nc">details ...</a></em></td>
1155 <td>noescape|NE</td>
1156 <td>Prevent mod_rewrite from applying hexcode escaping of
1157 special characters in the result of the rewrite. <em><a
1158 href="../rewrite/flags.html#flag_ne">details ...</a></em></td>
1161 <td>nosubreq|NS</td>
1162 <td>Causes a rule to be skipped if the current request is an
1163 internal sub-request. <em><a
1164 href="../rewrite/flags.html#flag_ns">details ...</a></em></td>
1168 <td>Force the substitution URL to be internally sent as a proxy
1169 request. <em><a href="../rewrite/flags.html#flag_p">details
1173 <td>passthrough|PT</td>
1174 <td>Forces the resulting URI to be passed back to the URL
1175 mapping engine for processing of other URI-to-filename
1176 translators, such as <code>Alias</code> or
1177 <code>Redirect</code>. <em><a
1178 href="../rewrite/flags.html#flag_pt">details ...</a></em></td>
1181 <td>qsappend|QSA</td>
1182 <td>Appends any query string created in the rewrite target to
1183 any query string that was in the original request URL. <em><a
1184 href="../rewrite/flags.html#flag_qsa">details ...</a></em></td>
1187 <td>qsdiscard|QSD</td>
1188 <td>Discard any query string attached to the incoming URI.
1189 <em><a href="../rewrite/flags.html#flag_qsd">details
1193 <td>redirect|R[=<em>code</em>]</td>
1194 <td>Forces an external redirect, optionally with the specified
1195 HTTP status code. <em><a
1196 href="../rewrite/flags.html#flag_r">details ...</a></em>
1201 <td>Stop the rewriting process immediately and don't apply any
1202 more rules. Also prevents further execution of rewrite rules
1203 in per-directory and .htaccess context. (Available in 2.3.9 and later)
1204 <em><a href="../rewrite/flags.html#flag_l">details ...</a></em></td>
1207 <td>skip|S=<em>num</em></td>
1208 <td>Tells the rewriting engine to skip the next <em>num</em>
1209 rules if the current rule matches. <em><a
1210 href="../rewrite/flags.html#flag_s">details ...</a></em></td>
1213 <td>type|T=<em>MIME-type</em></td>
1214 <td>Force the <glossary>MIME-type</glossary> of the target file
1215 to be the specified type. <em><a
1216 href="../rewrite/flags.html#flag_t">details ...</a></em></td>
1220 <note><title>Home directory expansion</title>
1221 <p> When the substitution string begins with a string
1222 resembling "/~user" (via explicit text or backreferences), mod_rewrite performs
1223 home directory expansion independent of the presence or configuration
1224 of <module>mod_userdir</module>.</p>
1226 <p> This expansion does not occur when the <em>PT</em>
1227 flag is used on the <directive module="mod_rewrite">RewriteRule</directive>
1232 <p>Here are all possible substitution combinations and their
1235 <p><strong>Inside per-server configuration
1236 (<code>httpd.conf</code>)<br />
1237 for request ``<code>GET
1238 /somepath/pathinfo</code>'':</strong><br />
1244 <th>Resulting Substitution</th>
1248 <td>^/somepath(.*) otherpath$1</td>
1249 <td>invalid, not supported</td>
1253 <td>^/somepath(.*) otherpath$1 [R]</td>
1254 <td>invalid, not supported</td>
1258 <td>^/somepath(.*) otherpath$1 [P]</td>
1259 <td>invalid, not supported</td>
1263 <td>^/somepath(.*) /otherpath$1</td>
1264 <td>/otherpath/pathinfo</td>
1268 <td>^/somepath(.*) /otherpath$1 [R]</td>
1269 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1273 <td>^/somepath(.*) /otherpath$1 [P]</td>
1274 <td>doesn't make sense, not supported</td>
1278 <td>^/somepath(.*) http://thishost/otherpath$1</td>
1279 <td>/otherpath/pathinfo</td>
1283 <td>^/somepath(.*) http://thishost/otherpath$1 [R]</td>
1284 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1288 <td>^/somepath(.*) http://thishost/otherpath$1 [P]</td>
1289 <td>doesn't make sense, not supported</td>
1293 <td>^/somepath(.*) http://otherhost/otherpath$1</td>
1294 <td>http://otherhost/otherpath/pathinfo via external redirection</td>
1298 <td>^/somepath(.*) http://otherhost/otherpath$1 [R]</td>
1299 <td>http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant)</td>
1303 <td>^/somepath(.*) http://otherhost/otherpath$1 [P]</td>
1304 <td>http://otherhost/otherpath/pathinfo via internal proxy</td>
1308 <p><strong>Inside per-directory configuration for
1309 <code>/somepath</code><br />
1310 (<code>/physical/path/to/somepath/.htacccess</code>, with
1311 <code>RewriteBase /somepath</code>)<br />
1312 for request ``<code>GET
1313 /somepath/localpath/pathinfo</code>'':</strong><br />
1320 <th>Resulting Substitution</th>
1324 <td>^localpath(.*) otherpath$1</td>
1325 <td>/somepath/otherpath/pathinfo</td>
1329 <td>^localpath(.*) otherpath$1 [R]</td>
1330 <td>http://thishost/somepath/otherpath/pathinfo via external
1335 <td>^localpath(.*) otherpath$1 [P]</td>
1336 <td>doesn't make sense, not supported</td>
1340 <td>^localpath(.*) /otherpath$1</td>
1341 <td>/otherpath/pathinfo</td>
1345 <td>^localpath(.*) /otherpath$1 [R]</td>
1346 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1350 <td>^localpath(.*) /otherpath$1 [P]</td>
1351 <td>doesn't make sense, not supported</td>
1355 <td>^localpath(.*) http://thishost/otherpath$1</td>
1356 <td>/otherpath/pathinfo</td>
1360 <td>^localpath(.*) http://thishost/otherpath$1 [R]</td>
1361 <td>http://thishost/otherpath/pathinfo via external redirection</td>
1365 <td>^localpath(.*) http://thishost/otherpath$1 [P]</td>
1366 <td>doesn't make sense, not supported</td>
1370 <td>^localpath(.*) http://otherhost/otherpath$1</td>
1371 <td>http://otherhost/otherpath/pathinfo via external redirection</td>
1375 <td>^localpath(.*) http://otherhost/otherpath$1 [R]</td>
1376 <td>http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant)</td>
1380 <td>^localpath(.*) http://otherhost/otherpath$1 [P]</td>
1381 <td>http://otherhost/otherpath/pathinfo via internal proxy</td>
1387 </directivesynopsis>