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><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 than <code>trace2</code> only for debugging!
71 <example><title>Example</title>
72 LogLevel rewrite:trace3
78 <name>RewriteEngine</name>
79 <description>Enables or disables runtime rewriting engine</description>
80 <syntax>RewriteEngine on|off</syntax>
81 <default>RewriteEngine off</default>
82 <contextlist><context>server config</context><context>virtual host</context>
83 <context>directory</context><context>.htaccess</context></contextlist>
84 <override>FileInfo</override>
88 <p>The <directive>RewriteEngine</directive> directive enables or
89 disables the runtime rewriting engine. If it is set to
90 <code>off</code> this module does no runtime processing at
91 all. It does not even update the <code>SCRIPT_URx</code>
92 environment variables.</p>
94 <p>Use this directive to disable the module instead of
95 commenting out all the <directive
96 module="mod_rewrite">RewriteRule</directive> directives!</p>
98 <p>Note that rewrite configurations are not
99 inherited by virtual hosts. This means that you need to have a
100 <code>RewriteEngine on</code> directive for each virtual host
101 in which you wish to use rewrite rules.</p>
103 <p><directive>RewriteMap</directive> directives of the type <code>prg</code>
104 are not started during server initialization if they're defined in a
105 context that does not have <directive>RewriteEngine</directive> set to
112 <name>RewriteOptions</name>
113 <description>Sets some special options for the rewrite engine</description>
114 <syntax>RewriteOptions <var>Options</var></syntax>
115 <contextlist><context>server config</context><context>virtual host</context>
116 <context>directory</context><context>.htaccess</context></contextlist>
117 <override>FileInfo</override>
118 <compatibility><code>MaxRedirects</code> is no longer available in version 2.1 and
119 later</compatibility>
122 <p>The <directive>RewriteOptions</directive> directive sets some
123 special options for the current per-server or per-directory
124 configuration. The <em>Option</em> string can currently
125 only be one of the following:</p>
128 <dt><code>inherit</code></dt>
129 <dd>This forces the current configuration to inherit the
130 configuration of the parent. In per-virtual-server context,
131 this means that the maps, conditions and rules of the main
132 server are inherited. In per-directory context this means
133 that conditions and rules of the parent directory's
134 <code>.htaccess</code> configuration or
135 <directive type="section" module="core">Directory</directive>
136 sections are inherited. The inherited rules are virtually copied
137 to the section where this directive is being used. If used in
138 combination with local rules, the inherited rules are copied behind
139 the local rules. The position of this directive - below or above
140 of local rules - has no influence on this behavior. If local
141 rules forced the rewriting to stop, the inherited rules won't
149 <name>RewriteMap</name>
150 <description>Defines a mapping function for key-lookup</description>
151 <syntax>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
153 <contextlist><context>server config</context><context>virtual host</context>
155 <compatibility>The choice of different dbm types is available in
156 Apache HTTP Server 2.0.41 and later</compatibility>
159 <p>The <directive>RewriteMap</directive> directive defines a
160 <em>Rewriting Map</em> which can be used inside rule
161 substitution strings by the mapping-functions to
162 insert/substitute fields through a key lookup. The source of
163 this lookup can be of various types.</p>
165 <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
166 the name of the map and will be used to specify a
167 mapping-function for the substitution strings of a rewriting
168 rule via one of the following constructs:</p>
171 <strong><code>${</code> <em>MapName</em> <code>:</code>
172 <em>LookupKey</em> <code>}</code><br />
173 <code>${</code> <em>MapName</em> <code>:</code>
174 <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
175 <code>}</code></strong>
178 <p>When such a construct occurs, the map <em>MapName</em> is
179 consulted and the key <em>LookupKey</em> is looked-up. If the
180 key is found, the map-function construct is substituted by
181 <em>SubstValue</em>. If the key is not found then it is
182 substituted by <em>DefaultValue</em> or by the empty string
183 if no <em>DefaultValue</em> was specified.</p>
185 <p>For example, you might define a
186 <directive>RewriteMap</directive> as:</p>
189 RewriteMap examplemap txt:/path/to/file/map.txt
192 <p>You would then be able to use this map in a
193 <directive>RewriteRule</directive> as follows:</p>
196 RewriteRule ^/ex/(.*) ${examplemap:$1}
199 <p>The following combinations for <em>MapType</em> and
200 <em>MapSource</em> can be used:</p>
205 <dd>A plain text file containing space-separated key-value
206 pairs, one per line. (<a href="../rewrite/rewritemap.html#txt">Details ...</a>)</dd>
209 <dd>Randomly selects an entry from a plain text file (<a href="../rewrite/rewritemap.html#rnd">Details ...</a>)</dd>
212 <dd>Looks up an entry in a dbm file containing name, value
213 pairs. Hash is constructed from a plain text file format using
214 the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code>
215 utility. (<a href="../rewrite/rewritemap.html#dbm">Details ...</a>)</dd>
218 <dd>One of the four available internal functions provided by
219 <code>RewriteMap</code>: toupper, tolower, escape or
220 unescape. (<a href="../rewrite/rewritemap.html#int">Details ...</a>)</dd>
223 <dd>Calls an external program or script to process the
224 rewriting. (<a href="../rewrite/rewritemap.html#prg">Details ...</a>)</dd>
226 <dt>dbd or fastdbd</dt>
227 <dd>A SQL SELECT statement to be performed to look up the
228 rewrite target. (<a href="../rewrite/rewritemap.html#dbd">Details ...</a>)</dd>
231 <p>Further details, and numerous examples, may be found in the <a
232 href="../rewrite/rewritemap.html">RewriteMap HowTo</a></p>
238 <name>RewriteBase</name>
239 <description>Sets the base URL for per-directory rewrites</description>
240 <syntax>RewriteBase <em>URL-path</em></syntax>
241 <default>None</default>
242 <contextlist><context>directory</context><context>.htaccess</context>
244 <override>FileInfo</override>
247 <p>The <directive>RewriteBase</directive> directive explicitly
248 sets the base URL-path (not filesystem directory path!) for per-directory rewrites.
249 When you use a <directive module="mod_rewrite">RewriteRule</directive>
250 in a <code>.htaccess</code> file, <module>mod_rewrite</module> strips off
251 the local directory prefix before processing, then rewrites the rest of
252 the URL. When the rewrite is completed, <module>mod_rewrite</module>
253 automatically adds the local directory prefix back on to the path.</p>
255 <p>This directive is <em>required</em> for per-directory rewrites whose context
256 is a directory made available via the <directive module="mod_alias">Alias</directive>
259 <p>If your URL path does not exist verbatim on the filesystem,
260 or isn't directly under your <directive module="core">DocumentRoot</directive>,
261 you must use <directive>RewriteBase</directive> in every
262 <code>.htaccess</code> file where you want to use <directive
263 module="mod_rewrite">RewriteRule</directive> directives.</p>
265 <p>The example below demonstrates how to map
266 http://example.com/myapp/index.html to
267 /home/www/example/newsite.html, in a <code>.htaccess</code> file. This
268 assumes that the content available at
269 http://example.com/ is on disk at /home/www/example/</p>
273 # The URL-path used to get to this context, not the filesystem path
275 RewriteRule ^index\.html$ newsite.html
284 <name>RewriteCond</name>
285 <description>Defines a condition under which rewriting will take place
288 <em>TestString</em> <em>CondPattern</em></syntax>
289 <contextlist><context>server config</context><context>virtual host</context>
290 <context>directory</context><context>.htaccess</context></contextlist>
291 <override>FileInfo</override>
294 <p>The <directive>RewriteCond</directive> directive defines a
295 rule condition. One or more <directive>RewriteCond</directive>
296 can precede a <directive module="mod_rewrite">RewriteRule</directive>
297 directive. The following rule is then only used if both
298 the current state of the URI matches its pattern, <strong
299 >and</strong> if these conditions are met.</p>
301 <p><em>TestString</em> is a string which can contain the
302 following expanded constructs in addition to plain text:</p>
306 <strong>RewriteRule backreferences</strong>: These are
307 backreferences of the form <strong><code>$N</code></strong>
308 (0 <= N <= 9). $1 to $9 provide access to the grouped
309 parts (in parentheses) of the pattern, from the
310 <code>RewriteRule</code> which is subject to the current
311 set of <code>RewriteCond</code> conditions. $0 provides
312 access to the whole string matched by that pattern.
315 <strong>RewriteCond backreferences</strong>: These are
316 backreferences of the form <strong><code>%N</code></strong>
317 (0 <= N <= 9). %1 to %9 provide access to the grouped
318 parts (again, in parentheses) of the pattern, from the last matched
319 <code>RewriteCond</code> in the current set
320 of conditions. %0 provides access to the whole string matched by
324 <strong>RewriteMap expansions</strong>: These are
325 expansions of the form <strong><code
326 >${mapname:key|default}</code></strong>.
327 See <a href="#mapfunc">the documentation for
328 RewriteMap</a> for more details.
331 <strong>Server-Variables</strong>: These are variables of
333 <strong><code>%{</code> <em>NAME_OF_VARIABLE</em>
334 <code>}</code></strong>
335 where <em>NAME_OF_VARIABLE</em> can be a string taken
336 from the following list:
339 <columnspec><column width=".3"/><column width=".3"/>
340 <column width=".3"/></columnspec>
342 <th>HTTP headers:</th> <th>connection & request:</th> <th></th>
347 HTTP_USER_AGENT<br />
352 HTTP_PROXY_CONNECTION<br />
363 SCRIPT_FILENAME<br />
373 <th>server internals:</th> <th>date and time:</th> <th>specials:</th>
383 SERVER_PROTOCOL<br />
384 SERVER_SOFTWARE<br />
402 REQUEST_FILENAME<br />
409 <p>These variables all
410 correspond to the similarly named HTTP
411 MIME-headers, C variables of the Apache HTTP Server or
412 <code>struct tm</code> fields of the Unix system.
413 Most are documented elsewhere in the Manual or in
414 the CGI specification. Those that are special to
415 mod_rewrite include those below.</p>
418 <dt><code>IS_SUBREQ</code></dt>
420 <dd>Will contain the text "true" if the request
421 currently being processed is a sub-request,
422 "false" otherwise. Sub-requests may be generated
423 by modules that need to resolve additional files
424 or URIs in order to complete their tasks.</dd>
426 <dt><code>API_VERSION</code></dt>
428 <dd>This is the version of the Apache httpd module API
429 (the internal interface between server and
430 module) in the current httpd build, as defined in
431 include/ap_mmn.h. The module API version
432 corresponds to the version of Apache httpd in use (in
433 the release version of Apache httpd 1.3.14, for
434 instance, it is 19990320:10), but is mainly of
435 interest to module authors.</dd>
437 <dt><code>THE_REQUEST</code></dt>
439 <dd>The full HTTP request line sent by the
440 browser to the server (e.g., "<code>GET
441 /index.html HTTP/1.1</code>"). This does not
442 include any additional headers sent by the
445 <dt><code>REQUEST_URI</code></dt>
447 <dd>The resource requested in the HTTP request
448 line. (In the example above, this would be
451 <dt><code>REQUEST_FILENAME</code></dt>
453 <dd>The full local filesystem path to the file or
454 script matching the request, if this has already
455 been determined by the server at the time
456 <code>REQUEST_FILENAME</code> is referenced. Otherwise,
457 such as when used in virtual host context, the same
458 value as <code>REQUEST_URI</code>.</dd>
460 <dt><code>HTTPS</code></dt>
462 <dd>Will contain the text "on" if the connection is
463 using SSL/TLS, or "off" otherwise. (This variable
464 can be safely used regardless of whether or not
465 <module>mod_ssl</module> is loaded).</dd>
472 <p>Other things you should be aware of:</p>
476 <p>The variables SCRIPT_FILENAME and REQUEST_FILENAME
477 contain the same value - the value of the
478 <code>filename</code> field of the internal
479 <code>request_rec</code> structure of the Apache HTTP Server.
480 The first name is the commonly known CGI variable name
481 while the second is the appropriate counterpart of
482 REQUEST_URI (which contains the value of the
483 <code>uri</code> field of <code>request_rec</code>).</p>
484 <p>If a substitution occurred and the rewriting continues,
485 the value of both variables will be updated accordingly.</p>
486 <p>If used in per-server context (<em>i.e.</em>, before the
487 request is mapped to the filesystem) SCRIPT_FILENAME and
488 REQUEST_FILENAME cannot contain the full local filesystem
489 path since the path is unknown at this stage of processing.
490 Both variables will initially contain the value of REQUEST_URI
491 in that case. In order to obtain the full local filesystem
492 path of the request in per-server context, use an URL-based
493 look-ahead <code>%{LA-U:REQUEST_FILENAME}</code> to determine
494 the final value of REQUEST_FILENAME.</p></li>
497 <code>%{ENV:variable}</code>, where <em>variable</em> can be
498 any environment variable, is also available.
499 This is looked-up via internal
500 Apache httpd structures and (if not found there) via
501 <code>getenv()</code> from the Apache httpd server process.</li>
504 <code>%{SSL:variable}</code>, where <em>variable</em> is the
505 name of an <a href="mod_ssl.html#envvars">SSL environment
506 variable</a>, can be used whether or not
507 <module>mod_ssl</module> is loaded, but will always expand to
508 the empty string if it is not. Example:
509 <code>%{SSL:SSL_CIPHER_USEKEYSIZE}</code> may expand to
510 <code>128</code>.</li>
513 <code>%{HTTP:header}</code>, where <em>header</em> can be
514 any HTTP MIME-header name, can always be used to obtain the
515 value of a header sent in the HTTP request.
516 Example: <code>%{HTTP:Proxy-Connection}</code> is
517 the value of the HTTP header
518 ``<code>Proxy-Connection:</code>''.
519 <p>If a HTTP header is used in a condition this header is added to
520 the Vary header of the response in case the condition evaluates to
521 to true for the request. It is <strong>not</strong> added if the
522 condition evaluates to false for the request. Adding the HTTP header
523 to the Vary header of the response is needed for proper caching.</p>
524 <p>It has to be kept in mind that conditions follow a short circuit
525 logic in the case of the '<strong><code>ornext|OR</code></strong>' flag
526 so that certain conditions might not be evaluated at all.</p></li>
529 <code>%{LA-U:variable}</code> can be used for look-aheads which perform
530 an internal (URL-based) sub-request to determine the final
531 value of <em>variable</em>. This can be used to access
532 variable for rewriting which is not available at the current
533 stage, but will be set in a later phase.
534 <p>For instance, to rewrite according to the
535 <code>REMOTE_USER</code> variable from within the
536 per-server context (<code>httpd.conf</code> file) you must
537 use <code>%{LA-U:REMOTE_USER}</code> - this
538 variable is set by the authorization phases, which come
539 <em>after</em> the URL translation phase (during which mod_rewrite
541 <p>On the other hand, because mod_rewrite implements
542 its per-directory context (<code>.htaccess</code> file) via
543 the Fixup phase of the API and because the authorization
544 phases come <em>before</em> this phase, you just can use
545 <code>%{REMOTE_USER}</code> in that context.</p></li>
548 <code>%{LA-F:variable}</code> can be used to perform an internal
549 (filename-based) sub-request, to determine the final value
550 of <em>variable</em>. Most of the time, this is the same as
554 <p><em>CondPattern</em> is the condition pattern,
555 a regular expression which is applied to the
556 current instance of the <em>TestString</em>.
557 <em>TestString</em> is first evaluated, before being matched against
558 <em>CondPattern</em>.</p>
560 <p><strong>Remember:</strong> <em>CondPattern</em> is a
561 <em>perl compatible regular expression</em> with some
565 <li>You can prefix the pattern string with a
566 '<code>!</code>' character (exclamation mark) to specify a
567 <strong>non</strong>-matching pattern.</li>
570 There are some special variants of <em>CondPatterns</em>.
571 Instead of real regular expression strings you can also
572 use one of the following:
575 <li>'<strong><CondPattern</strong>' (lexicographically
577 Treats the <em>CondPattern</em> as a plain string and
578 compares it lexicographically to <em>TestString</em>. True if
579 <em>TestString</em> lexicographically precedes
580 <em>CondPattern</em>.</li>
582 <li>'<strong>>CondPattern</strong>' (lexicographically
584 Treats the <em>CondPattern</em> as a plain string and
585 compares it lexicographically to <em>TestString</em>. True if
586 <em>TestString</em> lexicographically follows
587 <em>CondPattern</em>.</li>
589 <li>'<strong>=CondPattern</strong>' (lexicographically
591 Treats the <em>CondPattern</em> as a plain string and
592 compares it lexicographically to <em>TestString</em>. True if
593 <em>TestString</em> is lexicographically equal to
594 <em>CondPattern</em> (the two strings are exactly
595 equal, character for character). If <em>CondPattern</em>
596 is <code>""</code> (two quotation marks) this
597 compares <em>TestString</em> to the empty string.</li>
599 <li>'<strong>-d</strong>' (is
600 <strong>d</strong>irectory)<br />
601 Treats the <em>TestString</em> as a pathname and tests
602 whether or not it exists, and is a directory.</li>
604 <li>'<strong>-f</strong>' (is regular
605 <strong>f</strong>ile)<br />
606 Treats the <em>TestString</em> as a pathname and tests
607 whether or not it exists, and is a regular file.</li>
609 <li>'<strong>-s</strong>' (is regular file, with
610 <strong>s</strong>ize)<br />
611 Treats the <em>TestString</em> as a pathname and tests
612 whether or not it exists, and is a regular file with size greater
615 <li>'<strong>-l</strong>' (is symbolic
616 <strong>l</strong>ink)<br />
617 Treats the <em>TestString</em> as a pathname and tests
618 whether or not it exists, and is a symbolic link.</li>
620 <li>'<strong>-x</strong>' (has e<strong>x</strong>ecutable
622 Treats the <em>TestString</em> as a pathname and tests
623 whether or not it exists, and has executable permissions.
624 These permissions are determined according to
625 the underlying OS.</li>
627 <li>'<strong>-F</strong>' (is existing file, via
629 Checks whether or not <em>TestString</em> is a valid file,
630 accessible via all the server's currently-configured
631 access controls for that path. This uses an internal
632 subrequest to do the check, so use it with care -
633 it can impact your server's performance!</li>
635 <li>'<strong>-U</strong>' (is existing URL, via
637 Checks whether or not <em>TestString</em> is a valid URL,
638 accessible via all the server's currently-configured
639 access controls for that path. This uses an internal
640 subrequest to do the check, so use it with care -
641 it can impact your server's performance!</li>
644 <note><title>Note:</title>
645 All of these tests can
646 also be prefixed by an exclamation mark ('!') to
647 negate their meaning.
651 <li>You can also set special flags for
652 <em>CondPattern</em> by appending
653 <strong><code>[</code><em>flags</em><code>]</code></strong>
654 as the third argument to the <code>RewriteCond</code>
655 directive, where <em>flags</em> is a comma-separated list of any of the
659 <li>'<strong><code>nocase|NC</code></strong>'
660 (<strong>n</strong>o <strong>c</strong>ase)<br />
661 This makes the test case-insensitive - differences
662 between 'A-Z' and 'a-z' are ignored, both in the
663 expanded <em>TestString</em> and the <em>CondPattern</em>.
664 This flag is effective only for comparisons between
665 <em>TestString</em> and <em>CondPattern</em>. It has no
666 effect on filesystem and subrequest checks.</li>
669 '<strong><code>ornext|OR</code></strong>'
670 (<strong>or</strong> next condition)<br />
671 Use this to combine rule conditions with a local OR
672 instead of the implicit AND. Typical example:
676 RewriteCond %{REMOTE_HOST} ^host1.* [OR]
677 RewriteCond %{REMOTE_HOST} ^host2.* [OR]
678 RewriteCond %{REMOTE_HOST} ^host3.*
679 RewriteRule ...some special stuff for any of these hosts...
683 Without this flag you would have to write the condition/rule
687 <li>'<strong><code>novary|NV</code></strong>'
688 (<strong>n</strong>o <strong>v</strong>ary)<br />
689 If a HTTP header is used in the condition, this flag prevents
690 this header from being added to the Vary header of the response. <br />
691 Using this flag might break proper caching of the response if
692 the representation of this response varies on the value of this header.
693 So this flag should be only used if the meaning of the Vary header
700 <p><strong>Example:</strong></p>
702 <p>To rewrite the Homepage of a site according to the
703 ``<code>User-Agent:</code>'' header of the request, you can
704 use the following: </p>
708 RewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
709 RewriteRule ^/$ /homepage.max.html [L]
711 RewriteCond %{HTTP_USER_AGENT} ^Lynx.*
712 RewriteRule ^/$ /homepage.min.html [L]
714 RewriteRule ^/$ /homepage.std.html [L]
718 <p>Explanation: If you use a browser which identifies itself
719 as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you
720 get the max homepage (which could include frames, or other special
722 If you use the Lynx browser (which is terminal-based), then
723 you get the min homepage (which could be a version designed for
724 easy, text-only browsing).
725 If neither of these conditions apply (you use any other browser,
726 or your browser identifies itself as something non-standard), you get
727 the std (standard) homepage.</p>
734 <name>RewriteRule</name>
735 <description>Defines rules for the rewriting engine</description>
737 <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</syntax>
738 <contextlist><context>server config</context><context>virtual host</context>
739 <context>directory</context><context>.htaccess</context></contextlist>
740 <override>FileInfo</override>
743 <p>The <directive>RewriteRule</directive> directive is the real
744 rewriting workhorse. The directive can occur more than once,
745 with each instance defining a single rewrite rule. The
746 order in which these rules are defined is important - this is the order
747 in which they will be applied at run-time.</p>
749 <p><a id="patterns" name="patterns"><em>Pattern</em></a> is
750 a perl compatible <a id="regexp" name="regexp">regular
751 expression</a>. On the first RewriteRule it is applied to the (%-encoded)
752 <a href="./directive-dict.html#Syntax">URL-path</a> of the request;
753 subsequent patterns are applied to the output of the last matched
756 <note><title>What is matched?</title>
757 <p>The <em>Pattern</em> will initially be matched against the part of the
758 URL after the hostname and port, and before the query string.</p>
760 <p>When the RewriteRule appears in per-directory (htaccess) context, the
761 <em>Pattern</em> is matched against what remains of the URL after removing
762 the prefix that lead Apache httpd to the current rules (see the
763 <directive module="mod_rewrite">RewriteBase</directive>). The removed prefix
764 always ends with a slash, meaning the matching occurs against a string which
765 never has a leading slash. A <em>Pattern</em> with <code>^/</code> never
766 matches in per-directory context.</p>
768 <p>If you wish to match against the hostname, port, or query string, use a
769 <directive module="mod_rewrite">RewriteCond</directive> with the
770 <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
771 <code>%{QUERY_STRING}</code> variables respectively. If you wish to
772 match against the full URL-path in a per-directory (htaccess) RewriteRule,
773 use the <code>%{REQUEST_URI}</code> variable.</p>
777 <p>For some hints on <glossary ref="regex">regular
778 expressions</glossary>, see
779 the <a href="../rewrite/intro.html#regex">mod_rewrite
780 Introduction</a>.</p>
782 <p>In mod_rewrite, the NOT character
783 ('<code>!</code>') is also available as a possible pattern
784 prefix. This enables you to negate a pattern; to say, for instance:
785 ``<em>if the current URL does <strong>NOT</strong> match this
786 pattern</em>''. This can be used for exceptional cases, where
787 it is easier to match the negative pattern, or as a last
790 <note><title>Note</title>
791 When using the NOT character to negate a pattern, you cannot include
792 grouped wildcard parts in that pattern. This is because, when the
793 pattern does NOT match (ie, the negation matches), there are no
794 contents for the groups. Thus, if negated patterns are used, you
795 cannot use <code>$N</code> in the substitution string!
798 <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
799 rewrite rule is the string that replaces the original URL-path that
800 was matched by <em>Pattern</em>. The <em>Substitution</em> may
805 <dt>file-system path</dt>
807 <dd>Designates the location on the file-system of the resource
808 to be delivered to the client.</dd>
813 module="core">DocumentRoot</directive>-relative path to the
814 resource to be served. Note that <module>mod_rewrite</module>
815 tries to guess whether you have specified a file-system path
816 or a URL-path by checking to see if the first segment of the
817 path exists at the root of the file-system. For example, if
818 you specify a <em>Substitution</em> string of
819 <code>/www/file.html</code>, then this will be treated as a
820 URL-path <em>unless</em> a directory named <code>www</code>
821 exists at the root or your file-system, in which case it will
822 be treated as a file-system path. If you wish other
823 URL-mapping directives (such as <directive
824 module="mod_alias">Alias</directive>) to be applied to the
825 resulting URL-path, use the <code>[PT]</code> flag as
826 described below.</dd>
828 <dt>Absolute URL</dt>
830 <dd>If an absolute URL is specified,
831 <module>mod_rewrite</module> checks to see whether the
832 hostname matches the current host. If it does, the scheme and
833 hostname are stripped out and the resulting path is treated as
834 a URL-path. Otherwise, an external redirect is performed for
835 the given URL. To force an external redirect back to the
836 current host, see the <code>[R]</code> flag below.</dd>
838 <dt><code>-</code> (dash)</dt>
840 <dd>A dash indicates that no substitution should be performed
841 (the existing path is passed through untouched). This is used
842 when a flag (see below) needs to be applied without changing
847 <p>In addition to plain text, the <em>Substition</em> string can include</p>
850 <li>back-references (<code>$N</code>) to the RewriteRule
853 <li>back-references (<code>%N</code>) to the last matched
854 RewriteCond pattern</li>
856 <li>server-variables as in rule condition test-strings
857 (<code>%{VARNAME}</code>)</li>
859 <li><a href="#mapfunc">mapping-function</a> calls
860 (<code>${mapname:key|default}</code>)</li>
863 <p>Back-references are identifiers of the form
864 <code>$</code><strong>N</strong>
865 (<strong>N</strong>=0..9), which will be replaced
866 by the contents of the <strong>N</strong>th group of the
867 matched <em>Pattern</em>. The server-variables are the same
868 as for the <em>TestString</em> of a <code>RewriteCond</code>
869 directive. The mapping-functions come from the
870 <code>RewriteMap</code> directive and are explained there.
871 These three types of variables are expanded in the order above.</p>
873 <p>As already mentioned, all rewrite rules are
874 applied to the <em>Substitution</em> (in the order in which
876 in the config file). The URL is <strong>completely
877 replaced</strong> by the <em>Substitution</em> and the
878 rewriting process continues until all rules have been applied,
879 or it is explicitly terminated by a
880 <code><strong>L</strong></code> flag.</p>
882 <note><title>Modifying the Query String</title>
883 <p>By default, the query string is passed through unchanged. You
884 can, however, create URLs in the substitution string containing
885 a query string part. Simply use a question mark inside the
886 substitution string to indicate that the following text should
887 be re-injected into the query string. When you want to erase an
888 existing query string, end the substitution string with just a
889 question mark. To combine new and old query strings, use the
890 <code>[QSA]</code> flag.</p>
893 <p>Additionally you can set special <a name="rewriteflags"
894 id="rewriteflags">actions</a> to be performed by
895 appending <strong><code>[</code><em>flags</em><code>]</code></strong>
896 as the third argument to the <code>RewriteRule</code>
897 directive. <em>Flags</em> is a comma-separated list, surround by square
898 brackets, of any of the flags in the following table. More
899 details, and examples, for each flag, are available in the <a
900 href="../rewrite/flags.html">Rewrite Flags document</a>.</p>
903 <tr><th>Flag and syntax</th>
908 <td>Escape non-alphanumeric characters <em>before</em> applying
909 the transformation. <em><a
910 href="../rewrite/flags.html#flag_b">details ...</a></em></td>
914 <td>Rule is chained to the following rule. If the rule fails,
915 the rule(s) chained to it will be skipped. <em><a
916 href="../rewrite/flags.html#flag_c">details ...</a></em></td>
919 <td>cookie|CO=<em>NAME</em>:<em>VAL</em></td>
920 <td>Sets a cookie in the client browser. Full syntax is:
921 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>
925 <td>discardpathinfo|DPI</td>
926 <td>Causes the PATH_INFO portion of the rewritten URI to be
927 discarded. <em><a href="../rewrite/flags.html#flag_dpi">details
931 <td>env|E=<em>VAR</em>:<em>VAL</em></td>
932 <td>Causes an environment variable <em>VAR</em> to be set to the
933 value <em>VAL</em>. <em><a
934 href="../rewrite/flags.html#flag_e">details ...</a></em></td>
938 <td>Returns a 403 FORBIDDEN response to the client browser.
939 <em><a href="../rewrite/flags.html#flag_f">details ...</a></em></td>
943 <td>Returns a 410 GONE response to the client browser. <em><a
944 href="../rewrite/flags.html#flag_g">details ...</a></em></td>
947 <td>Handler|H=<em>Content-handler</em></td>
948 <td>Causes the resulting URI to be sent to the specified
949 <em>Content-handler</em> for processing. <em><a
950 href="../rewrite/flags.html#flag_h">details ...</a></em></td>
954 <td>Stop the rewriting process immediately and don't apply any
955 more rules. Especially note caveats for per-directory and
956 .htaccess context. <em><a
957 href="../rewrite/flags.html#flag_l">details ...</a></em></td>
961 <td>Re-run the rewriting process, starting again with the first
962 rule, using the result of the ruleset so far as a starting
963 point. <em><a href="../rewrite/flags.html#flag_n">details
968 <td>Makes the pattern pattern comparison case-insensitive.
969 <em><a href="../rewrite/flags.html#flag_nc">details ...</a></em></td>
973 <td>Prevent mod_rewrite from applying hexcode escaping of
974 special characters in the result of the rewrite. <em><a
975 href="../rewrite/flags.html#flag_ne">details ...</a></em></td>
979 <td>Causes a rule to be skipped if the current request is an
980 internal sub-request. <em><a
981 href="../rewrite/flags.html#flag_ns">details ...</a></em></td>
985 <td>Force the substitution URL to be internally sent as a proxy
986 request. <em><a href="../rewrite/flags.html#flag_p">details
990 <td>passthrough|PT</td>
991 <td>Forces the resulting URI to be passed back to the URL
992 mapping engine for processing of other URI-to-filename
993 translators, such as <code>Alias</code> or
994 <code>Redirect</code>. <em><a
995 href="../rewrite/flags.html#flag_pt">details ...</a></em></td>
998 <td>qsappend|QSA</td>
999 <td>Appends any query string created in the rewrite target to
1000 any query string that was in the original request URL. <em><a
1001 href="../rewrite/flags.html#flag_qsa">details ...</a></em></td>
1004 <td>qsdiscard|QSD</td>
1005 <td>Discard any query string attached to the incoming URI.
1006 <em><a href="../rewrite/flags.html#flag_qsd">details
1010 <td>redirect|R[=<em>code</em>]</td>
1011 <td>Forces an external redirect, optionally with the specified
1012 HTTP status code. <em><a
1013 href="../rewrite/flags.html#flag_r">details ...</a></em>
1017 <td>skip|S=<em>num</em></td>
1018 <td>Tells the rewriting engine to skip the next <em>num</em>
1019 rules if the current rule matches. <em><a
1020 href="../rewrite/flags.html#flag_s">details ...</a></em></td>
1023 <td>tyle|T=<em>MIME-type</em></td>
1024 <td>Force the <glossary>MIME-type</glossary> of the target file
1025 to be the specified type. <em><a
1026 href="../rewrite/flags.html#flag_t">details ...</a></em></td>
1030 <note><title>Home directory expansion</title>
1031 <p> When the substitution string begins with a string
1032 resembling "/~user" (via explicit text or backreferences), mod_rewrite performs
1033 home directory expansion independent of the presence or configuration
1034 of <module>mod_userdir</module>.</p>
1036 <p> This expansion does not occur when the <em>PT</em>
1037 flag is used on the <directive module="mod_rewrite">RewriteRule</directive>
1041 <note><title>Per-directory Rewrites</title>
1043 <p>The rewrite engine may be used in <a
1044 href="../howto/htaccess.html">.htaccess</a> files. To enable the
1045 rewrite engine for these files you need to set
1046 "<code>RewriteEngine On</code>" <strong>and</strong>
1047 "<code>Options FollowSymLinks</code>" must be enabled. If your
1048 administrator has disabled override of <code>FollowSymLinks</code> for
1049 a user's directory, then you cannot use the rewrite engine. This
1050 restriction is required for security reasons.</p>
1052 <p>When using the rewrite engine in <code>.htaccess</code> files the
1053 per-directory prefix (which always is the same for a specific
1054 directory) is automatically <em>removed</em> for the pattern matching
1055 and automatically <em>added</em> after the substitution has been
1056 done. This feature is essential for many sorts of rewriting; without
1057 this, you would always have to match the parent directory, which is
1058 not always possible. There is one exception: If a substitution string
1059 starts with <code>http://</code>, then the directory prefix will
1060 <strong>not</strong> be added, and an external redirect (or proxy
1061 throughput, if using flag <strong>P</strong>) is forced. See the
1062 <directive module="mod_rewrite">RewriteBase</directive> directive for
1063 more information.</p>
1065 <p>The rewrite engine may also be used in <directive type="section"
1066 module="core">Directory</directive> sections with the same
1067 prefix-matching rules as would be applied to <code>.htaccess</code>
1068 files. It is usually simpler, however, to avoid the prefix substitution
1069 complication by putting the rewrite rules in the main server or
1070 virtual host context, rather than in a <directive type="section"
1071 module="core">Directory</directive> section.</p>
1073 <p>Although rewrite rules are syntactically permitted in <directive
1074 type="section" module="core">Location</directive> and <directive
1075 type="section" module="core">Files</directive> sections, this
1076 should never be necessary and is unsupported.</p>
1080 <p>Here are all possible substitution combinations and their
1083 <p><strong>Inside per-server configuration
1084 (<code>httpd.conf</code>)<br />
1085 for request ``<code>GET
1086 /somepath/pathinfo</code>'':</strong><br />
1090 <strong>Given Rule</strong> <strong>Resulting Substitution</strong>
1091 ---------------------------------------------- ----------------------------------
1092 ^/somepath(.*) otherpath$1 invalid, not supported
1094 ^/somepath(.*) otherpath$1 [R] invalid, not supported
1096 ^/somepath(.*) otherpath$1 [P] invalid, not supported
1097 ---------------------------------------------- ----------------------------------
1098 ^/somepath(.*) /otherpath$1 /otherpath/pathinfo
1100 ^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
1101 via external redirection
1103 ^/somepath(.*) /otherpath$1 [P] doesn't make sense, not supported
1104 ---------------------------------------------- ----------------------------------
1105 ^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
1107 ^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
1108 via external redirection
1110 ^/somepath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported
1111 ---------------------------------------------- ----------------------------------
1112 ^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
1113 via external redirection
1115 ^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
1116 via external redirection
1117 (the [R] flag is redundant)
1119 ^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
1123 <p><strong>Inside per-directory configuration for
1124 <code>/somepath</code><br />
1125 (<code>/physical/path/to/somepath/.htacccess</code>, with
1126 <code>RewriteBase /somepath</code>)<br />
1127 for request ``<code>GET
1128 /somepath/localpath/pathinfo</code>'':</strong><br />
1132 <strong>Given Rule</strong> <strong>Resulting Substitution</strong>
1133 ---------------------------------------------- ----------------------------------
1134 ^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo
1136 ^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo
1137 via external redirection
1139 ^localpath(.*) otherpath$1 [P] doesn't make sense, not supported
1140 ---------------------------------------------- ----------------------------------
1141 ^localpath(.*) /otherpath$1 /otherpath/pathinfo
1143 ^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
1144 via external redirection
1146 ^localpath(.*) /otherpath$1 [P] doesn't make sense, not supported
1147 ---------------------------------------------- ----------------------------------
1148 ^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
1150 ^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
1151 via external redirection
1153 ^localpath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported
1154 ---------------------------------------------- ----------------------------------
1155 ^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
1156 via external redirection
1158 ^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
1159 via external redirection
1160 (the [R] flag is redundant)
1162 ^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
1166 </directivesynopsis>