1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>mod_rewrite - Apache HTTP Server</title>
9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
14 <div id="page-header">
15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
16 <p class="apache">Apache HTTP Server Version 2.0</p>
17 <img alt="" src="../images/feather.gif" /></div>
18 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
20 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Modules</a></div>
21 <div id="page-content">
22 <div id="preamble"><h1>Apache Module mod_rewrite</h1>
24 <p><span>Available Languages: </span><a href="../en/mod/mod_rewrite.html" title="English"> en </a></p>
26 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides a rule-based rewriting engine to rewrite requested
27 URLs on the fly</td></tr>
28 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
29 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>rewrite_module</td></tr>
30 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_rewrite.c</td></tr>
31 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 1.3 and later</td></tr></table>
34 <p>This module uses a rule-based rewriting engine (based on a
35 regular-expression parser) to rewrite requested URLs on the
36 fly. It supports an unlimited number of rules and an
37 unlimited number of attached rule conditions for each rule, to
38 provide a really flexible and powerful URL manipulation
39 mechanism. The URL manipulations can depend on various tests,
40 of server variables, environment variables, HTTP
41 headers, or time stamps. Even external database lookups in
42 various formats can be used to achieve highly granular URL
45 <p>This module operates on the full URLs (including the
46 path-info part) both in per-server context
47 (<code>httpd.conf</code>) and per-directory context
48 (<code>.htaccess</code>) and can generate query-string
49 parts on result. The rewritten result can lead to internal
50 sub-processing, external request redirection or even to an
51 internal proxy throughput.</p>
53 <p>Further details, discussion, and examples, are provided in the
54 <a href="../rewrite/">detailed mod_rewrite documentation</a>.</p>
56 <div id="quickview"><h3 class="directives">Directives</h3>
58 <li><img alt="" src="../images/down.gif" /> <a href="#rewritebase">RewriteBase</a></li>
59 <li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">RewriteCond</a></li>
60 <li><img alt="" src="../images/down.gif" /> <a href="#rewriteengine">RewriteEngine</a></li>
61 <li><img alt="" src="../images/down.gif" /> <a href="#rewritelock">RewriteLock</a></li>
62 <li><img alt="" src="../images/down.gif" /> <a href="#rewritelog">RewriteLog</a></li>
63 <li><img alt="" src="../images/down.gif" /> <a href="#rewriteloglevel">RewriteLogLevel</a></li>
64 <li><img alt="" src="../images/down.gif" /> <a href="#rewritemap">RewriteMap</a></li>
65 <li><img alt="" src="../images/down.gif" /> <a href="#rewriteoptions">RewriteOptions</a></li>
66 <li><img alt="" src="../images/down.gif" /> <a href="#rewriterule">RewriteRule</a></li>
70 <li><img alt="" src="../images/down.gif" /> <a href="#InternalAPI">API Phases</a></li>
71 <li><img alt="" src="../images/down.gif" /> <a href="#InternalRuleset">Ruleset Processing</a></li>
72 <li><img alt="" src="../images/down.gif" /> <a href="#InternalBackRefs">Regex Back-Reference Availability</a></li>
73 <li><img alt="" src="../images/down.gif" /> <a href="#quoting">Quoting Special Characters</a></li>
74 <li><img alt="" src="../images/down.gif" /> <a href="#EnvVar">Environment Variables</a></li>
75 <li><img alt="" src="../images/down.gif" /> <a href="#Solutions">Practical Solutions</a></li>
76 </ul><h3>See also</h3>
78 <li><a href="#rewriteflags">Rewrite Flags</a></li>
80 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
82 <h2><a name="InternalAPI" id="InternalAPI">API Phases</a></h2>
84 <p>Apache processes a HTTP request in several phases.
85 A hook for each of these
86 phases is provided by the Apache API. <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> uses two of
87 these hooks: the URL-to-filename translation hook
88 (used after the HTTP request has been read, but before any
89 authorization starts) and the Fixup hook (triggered
90 after the authorization phases, and after the per-directory
91 config files (<code>.htaccess</code>) have been read, but
92 before the content handler is activated).</p>
94 <p>Once a request comes in, and Apache has determined the
95 appropriate server (or virtual server), the rewrite engine
96 starts the URL-to-filename translation,
97 processing the mod_rewrite directives from the
98 per-server configuration. A few
99 steps later, when the final data directories are found, the
100 per-directory configuration directives of mod_rewrite are
101 triggered in the Fixup phase. </p>
103 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
104 <div class="section">
105 <h2><a name="InternalRuleset" id="InternalRuleset">Ruleset Processing</a></h2>
107 <p>When mod_rewrite is triggered during these two API phases, it
108 reads the relevant rulesets from its configuration
109 structure (which was either created on startup, for
110 per-server context, or during the directory traversal
111 for per-directory context). The URL rewriting
112 engine is started with the appropriate ruleset (one or more
113 rules together with their conditions), and its operation
114 is exactly the same for both
115 configuration contexts. Only the final result processing is
118 <p>The order of rules in the ruleset is important because the
119 rewrite engine processes them in a particular (not always
120 obvious) order, as follows: The rewrite engine loops
121 through the rulesets (each ruleset being made up of <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives, with or without
122 <code class="directive"><a href="#rewritecond">RewriteCond</a></code>s), rule by rule.
123 When a particular rule is matched, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
124 also checks the corresponding conditions (<code>RewriteCond</code>
125 directives). For historical reasons the conditions are given
126 first, making the control flow a little bit long-winded. See
127 Figure 1 for more details.</p>
129 <img src="../images/mod_rewrite_fig1.gif" width="428" height="385" alt="[Needs graphics capability to display]" /><br />
130 <dfn>Figure 1:</dfn>The control flow of the rewrite engine through a
133 <p>As above, first the URL is matched against the
134 <em>Pattern</em> of a rule. If it does not match, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> immediately stops processing that rule,
135 and goes on to the next rule. If the <em>Pattern</em> matches,
136 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> checks for rule conditions.
137 If none are present, the URL will be replaced with a new string,
138 constructed from the <em>Substitution</em> string, and <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> goes on to the next rule.</p>
139 <p>If <code class="directive">RewriteCond</code>s exist, an
140 inner loop is started, processing them in the order that they are
141 listed. Conditions are not matched against the current URL directly.
142 A <em>TestString</em> is constructed by expanding variables,
143 back-references, map lookups, etc., against which the
144 <em>CondPattern</em> is matched. If the pattern fails to match one
145 of the conditions, the complete set of rule and associated conditions
146 fails. If the pattern matches a given condition, then matching continues
147 to the next condition, until no more conditions are
148 available. If all conditions match, processing is continued
149 with the substitution of the <em>Substitution</em> string for the URL.</p>
151 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
152 <div class="section">
153 <h2><a name="InternalBackRefs" id="InternalBackRefs">Regex Back-Reference Availability</a></h2>
155 <p>Using parentheses in <em>Pattern</em> or in one of the
156 <em>CondPattern</em>s causes back-references to be internally
158 These can later be referenced using the strings <code>$N</code> and
159 <code>%N</code> (see below), for creating
160 the <em>Substitution</em> and <em>TestString</em> strings.
161 Figure 2 attempts to show how the back-references are
162 transferred through the process for later expansion.</p>
165 <img src="../images/mod_rewrite_fig2.gif" width="381" height="179" alt="[Needs graphics capability to display]" /><br />
166 <dfn>Figure 2:</dfn> The back-reference flow through a rule.
168 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
169 <div class="section">
170 <h2><a name="quoting" id="quoting">Quoting Special Characters</a></h2>
172 <p>As of Apache 1.3.20, special characters in
173 <em>TestString</em> and <em>Substitution</em> strings can be
174 escaped (that is, treated as normal characters without their
175 usual special meaning) by prefixing them with a backslash ('\')
176 character. In other words, you can include an actual
177 dollar-sign character in a <em>Substitution</em> string by
178 using '<code>\$</code>'; this keeps mod_rewrite from trying
179 to treat it as a backreference.</p>
180 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
181 <div class="section">
182 <h2><a name="EnvVar" id="EnvVar">Environment Variables</a></h2>
184 <p>This module keeps track of two additional (non-standard)
185 CGI/SSI environment variables named <code>SCRIPT_URL</code>
186 and <code>SCRIPT_URI</code>. These contain the
187 <em>logical</em> Web-view to the current resource, while the
188 standard CGI/SSI variables <code>SCRIPT_NAME</code> and
189 <code>SCRIPT_FILENAME</code> contain the <em>physical</em>
192 <p>Notice: These variables hold the URI/URL <em>as they were
193 initially requested</em>, that is, <em>before</em> any
194 rewriting. This is important to note because the rewriting process is
195 primarily used to rewrite logical URLs to physical
198 <div class="example"><h3>Example</h3><pre>
199 SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
200 SCRIPT_FILENAME=/u/rse/.www/index.html
202 SCRIPT_URI=http://en1.engelschall.com/u/rse/
205 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
206 <div class="section">
207 <h2><a name="Solutions" id="Solutions">Practical Solutions</a></h2>
209 <p>For numerous examples of common, and not-so-common, uses for
210 mod_rewrite, see the <a href="../rewrite/rewrite_guide.html">Rewrite
211 Guide</a>, and the <a href="../rewrite/rewrite_guide_advanced.html">Advanced Rewrite
212 Guide</a> documents.</p>
215 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
216 <div class="directive-section"><h2><a name="RewriteBase" id="RewriteBase">RewriteBase</a> <a name="rewritebase" id="rewritebase">Directive</a></h2>
217 <table class="directive">
218 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the base URL for per-directory rewrites</td></tr>
219 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteBase <em>URL-path</em></code></td></tr>
220 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>See usage for information.</code></td></tr>
221 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
222 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
223 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
224 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
226 <p>The <code class="directive">RewriteBase</code> directive explicitly
227 sets the base URL for per-directory rewrites. As you will see
228 below, <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
229 can be used in per-directory config files
230 (<code>.htaccess</code>). In such a case, it will act locally,
231 stripping the local directory prefix before processing, and applying
232 rewrite rules only to the remainder. When processing is complete, the
233 prefix is automatically added back to the
234 path. The default setting is; <code class="directive">RewriteBase</code> <em>physical-directory-path</em></p>
236 <p>When a substitution occurs for a new URL, this module has
237 to re-inject the URL into the server processing. To be able
238 to do this it needs to know what the corresponding URL-prefix
239 or URL-base is. By default this prefix is the corresponding
240 filepath itself. <strong>However, for most websites, URLs are NOT
241 directly related to physical filename paths, so this
242 assumption will often be wrong!</strong> Therefore, you can
243 use the <code>RewriteBase</code> directive to specify the
244 correct URL-prefix.</p>
246 <div class="note"> If your webserver's URLs are <strong>not</strong> directly
247 related to physical file paths, you will need to use
248 <code class="directive">RewriteBase</code> in every <code>.htaccess</code>
249 file where you want to use <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives.
252 <p> For example, assume the following per-directory config file:</p>
254 <div class="example"><pre>
256 # /abc/def/.htaccess -- per-dir config file for directory /abc/def
257 # Remember: /abc/def is the physical path of /xyz, <em>i.e.</em>, the server
258 # has a 'Alias /xyz /abc/def' directive <em>e.g.</em>
263 # let the server know that we were reached via /xyz and not
264 # via the physical path prefix /abc/def
267 # now the rewriting rules
268 RewriteRule ^oldstuff\.html$ newstuff.html
271 <p>In the above example, a request to
272 <code>/xyz/oldstuff.html</code> gets correctly rewritten to
273 the physical file <code>/abc/def/newstuff.html</code>.</p>
275 <div class="note"><h3>For Apache Hackers</h3>
276 <p>The following list gives detailed information about
277 the internal processing steps:</p>
283 /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias)
284 /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule)
285 /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase)
286 /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias)
289 /abc/def/newstuff.html
291 <p>This seems very complicated, but is in fact
292 correct Apache internal processing. Because the
293 per-directory rewriting comes late in the
294 process, the rewritten request
295 has to be re-injected into the Apache kernel, as if it
296 were a new request. (See <a href="../rewrite/rewrite_tech.html">mod_rewrite technical
298 This is not the serious overhead it may seem to be -
299 this re-injection is completely internal to the
300 Apache server (and the same procedure is used by
301 many other operations within Apache).</p>
306 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
307 <div class="directive-section"><h2><a name="RewriteCond" id="RewriteCond">RewriteCond</a> <a name="rewritecond" id="rewritecond">Directive</a></h2>
308 <table class="directive">
309 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a condition under which rewriting will take place
311 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> RewriteCond
312 <em>TestString</em> <em>CondPattern</em></code></td></tr>
313 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
314 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
315 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
316 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
318 <p>The <code class="directive">RewriteCond</code> directive defines a
319 rule condition. One or more <code class="directive">RewriteCond</code>
320 can precede a <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
321 directive. The following rule is then only used if both
322 the current state of the URI matches its pattern, <strong>and</strong> if these conditions are met.</p>
324 <p><em>TestString</em> is a string which can contain the
325 following expanded constructs in addition to plain text:</p>
329 <strong>RewriteRule backreferences</strong>: These are
330 backreferences of the form <strong><code>$N</code></strong>
331 (0 <= N <= 9), which provide access to the grouped
332 parts (in parentheses) of the pattern, from the
333 <code>RewriteRule</code> which is subject to the current
334 set of <code>RewriteCond</code> conditions..
337 <strong>RewriteCond backreferences</strong>: These are
338 backreferences of the form <strong><code>%N</code></strong>
339 (1 <= N <= 9), which provide access to the grouped
340 parts (again, in parentheses) of the pattern, from the last matched
341 <code>RewriteCond</code> in the current set
345 <strong>RewriteMap expansions</strong>: These are
346 expansions of the form <strong><code>${mapname:key|default}</code></strong>.
347 See <a href="#mapfunc">the documentation for
348 RewriteMap</a> for more details.
351 <strong>Server-Variables</strong>: These are variables of
353 <strong><code>%{</code> <em>NAME_OF_VARIABLE</em>
354 <code>}</code></strong>
355 where <em>NAME_OF_VARIABLE</em> can be a string taken
356 from the following list:
361 <th>HTTP headers:</th> <th>connection & request:</th> <th />
366 HTTP_USER_AGENT<br />
371 HTTP_PROXY_CONNECTION<br />
382 SCRIPT_FILENAME<br />
392 <th>server internals:</th> <th>system stuff:</th> <th>specials:</th>
402 SERVER_PROTOCOL<br />
403 SERVER_SOFTWARE<br />
421 REQUEST_FILENAME<br />
428 <p>These variables all
429 correspond to the similarly named HTTP
430 MIME-headers, C variables of the Apache server or
431 <code>struct tm</code> fields of the Unix system.
432 Most are documented elsewhere in the Manual or in
433 the CGI specification. Those that are special to
434 mod_rewrite include those below.</p>
437 <dt><code>IS_SUBREQ</code></dt>
439 <dd>Will contain the text "true" if the request
440 currently being processed is a sub-request,
441 "false" otherwise. Sub-requests may be generated
442 by modules that need to resolve additional files
443 or URIs in order to complete their tasks.</dd>
445 <dt><code>API_VERSION</code></dt>
447 <dd>This is the version of the Apache module API
448 (the internal interface between server and
449 module) in the current httpd build, as defined in
450 include/ap_mmn.h. The module API version
451 corresponds to the version of Apache in use (in
452 the release version of Apache 1.3.14, for
453 instance, it is 19990320:10), but is mainly of
454 interest to module authors.</dd>
456 <dt><code>THE_REQUEST</code></dt>
458 <dd>The full HTTP request line sent by the
459 browser to the server (e.g., "<code>GET
460 /index.html HTTP/1.1</code>"). This does not
461 include any additional headers sent by the
464 <dt><code>REQUEST_URI</code></dt>
466 <dd>The resource requested in the HTTP request
467 line. (In the example above, this would be
470 <dt><code>REQUEST_FILENAME</code></dt>
472 <dd>The full local filesystem path to the file or
473 script matching the request.</dd>
475 <dt><code>HTTPS</code></dt>
477 <dd>Will contain the text "on" if the connection is
478 using SSL/TLS, or "off" otherwise. (This variable
479 can be safely used regardless of whether or not
480 <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is loaded).</dd>
487 <p>Other things you should be aware of:</p>
490 <li>The variables SCRIPT_FILENAME and REQUEST_FILENAME
491 contain the same value - the value of the
492 <code>filename</code> field of the internal
493 <code>request_rec</code> structure of the Apache server.
494 The first name is the commonly known CGI variable name
495 while the second is the appropriate counterpart of
496 REQUEST_URI (which contains the value of the
497 <code>uri</code> field of <code>request_rec</code>).</li>
500 <code>%{ENV:variable}</code>, where <em>variable</em> can be
501 any environment variable, is also available.
502 This is looked-up via internal
503 Apache structures and (if not found there) via
504 <code>getenv()</code> from the Apache server process.</li>
507 <code>%{SSL:variable}</code>, where <em>variable</em> is the
508 name of an <a href="mod_ssl.html#envvars">SSL environment
509 variable</a>, can be used whether or not
510 <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is loaded, but will always expand to
511 the empty string if it is not. Example:
512 <code>%{SSL:SSL_CIPHER_USEKEYSIZE}</code> may expand to
513 <code>128</code>.</li>
516 <code>%{HTTP:header}</code>, where <em>header</em> can be
517 any HTTP MIME-header name, can always be used to obtain the
518 value of a header sent in the HTTP request.
519 Example: <code>%{HTTP:Proxy-Connection}</code> is
520 the value of the HTTP header
521 ``<code>Proxy-Connection:</code>''.</li>
524 <code>%{LA-U:variable}</code> can be used for look-aheads which perform
525 an internal (URL-based) sub-request to determine the final
526 value of <em>variable</em>. This can be used to access
527 variable for rewriting which is not available at the current
528 stage, but will be set in a later phase.
529 <p>For instance, to rewrite according to the
530 <code>REMOTE_USER</code> variable from within the
531 per-server context (<code>httpd.conf</code> file) you must
532 use <code>%{LA-U:REMOTE_USER}</code> - this
533 variable is set by the authorization phases, which come
534 <em>after</em> the URL translation phase (during which mod_rewrite
536 <p>On the other hand, because mod_rewrite implements
537 its per-directory context (<code>.htaccess</code> file) via
538 the Fixup phase of the API and because the authorization
539 phases come <em>before</em> this phase, you just can use
540 <code>%{REMOTE_USER}</code> in that context.</p></li>
543 <code>%{LA-F:variable}</code> can be used to perform an internal
544 (filename-based) sub-request, to determine the final value
545 of <em>variable</em>. Most of the time, this is the same as
549 <p><em>CondPattern</em> is the condition pattern,
550 a regular expression which is applied to the
551 current instance of the <em>TestString</em>.
552 <em>TestString</em> is first evaluated, before being matched against
553 <em>CondPattern</em>.</p>
555 <p><strong>Remember:</strong> <em>CondPattern</em> is a
556 <em>perl compatible regular expression</em> with some
560 <li>You can prefix the pattern string with a
561 '<code>!</code>' character (exclamation mark) to specify a
562 <strong>non</strong>-matching pattern.</li>
565 There are some special variants of <em>CondPatterns</em>.
566 Instead of real regular expression strings you can also
567 use one of the following:
571 <li>'<strong><CondPattern</strong>' (lexicographically
573 Treats the <em>CondPattern</em> as a plain string and
574 compares it lexicographically to <em>TestString</em>. True if
575 <em>TestString</em> lexicographically precedes
576 <em>CondPattern</em>.</li>
578 <li>'<strong>>CondPattern</strong>' (lexicographically
580 Treats the <em>CondPattern</em> as a plain string and
581 compares it lexicographically to <em>TestString</em>. True if
582 <em>TestString</em> lexicographically follows
583 <em>CondPattern</em>.</li>
585 <li>'<strong>=CondPattern</strong>' (lexicographically
587 Treats the <em>CondPattern</em> as a plain string and
588 compares it lexicographically to <em>TestString</em>. True if
589 <em>TestString</em> is lexicographically equal to
590 <em>CondPattern</em> (the two strings are exactly
591 equal, character for character). If <em>CondPattern</em>
592 is <code>""</code> (two quotation marks) this
593 compares <em>TestString</em> to the empty string.</li>
595 <li>'<strong>-d</strong>' (is
596 <strong>d</strong>irectory)<br />
597 Treats the <em>TestString</em> as a pathname and tests
598 whether or not it exists, and is a directory.</li>
600 <li>'<strong>-f</strong>' (is regular
601 <strong>f</strong>ile)<br />
602 Treats the <em>TestString</em> as a pathname and tests
603 whether or not it exists, and is a regular file.</li>
605 <li>'<strong>-s</strong>' (is regular file, with
606 <strong>s</strong>ize)<br />
607 Treats the <em>TestString</em> as a pathname and tests
608 whether or not it exists, and is a regular file with size greater
611 <li>'<strong>-l</strong>' (is symbolic
612 <strong>l</strong>ink)<br />
613 Treats the <em>TestString</em> as a pathname and tests
614 whether or not it exists, and is a symbolic link.</li>
616 <li>'<strong>-F</strong>' (is existing file, via
618 Checks whether or not <em>TestString</em> is a valid file,
619 accessible via all the server's currently-configured
620 access controls for that path. This uses an internal
621 subrequest to do the check, so use it with care -
622 it can impact your server's performance!</li>
624 <li>'<strong>-U</strong>' (is existing URL, via
626 Checks whether or not <em>TestString</em> is a valid URL,
627 accessible via all the server's currently-configured
628 access controls for that path. This uses an internal
629 subrequest to do the check, so use it with care -
630 it can impact your server's performance!</li>
633 <div class="note"><h3>Note</h3>
634 All of these tests can
635 also be prefixed by an exclamation mark ('!') to
636 negate their meaning.
640 <li>You can also set special flags for
641 <em>CondPattern</em> by appending
642 <strong><code>[</code><em>flags</em><code>]</code></strong>
643 as the third argument to the <code>RewriteCond</code>
644 directive, where <em>flags</em> is a comma-separated list of any of the
648 <li>'<strong><code>nocase|NC</code></strong>'
649 (<strong>n</strong>o <strong>c</strong>ase)<br />
650 This makes the test case-insensitive - differences
651 between 'A-Z' and 'a-z' are ignored, both in the
652 expanded <em>TestString</em> and the <em>CondPattern</em>.
653 This flag is effective only for comparisons between
654 <em>TestString</em> and <em>CondPattern</em>. It has no
655 effect on filesystem and subrequest checks.</li>
658 '<strong><code>ornext|OR</code></strong>'
659 (<strong>or</strong> next condition)<br />
660 Use this to combine rule conditions with a local OR
661 instead of the implicit AND. Typical example:
663 <div class="example"><pre>
664 RewriteCond %{REMOTE_HOST} ^host1.* [OR]
665 RewriteCond %{REMOTE_HOST} ^host2.* [OR]
666 RewriteCond %{REMOTE_HOST} ^host3.*
667 RewriteRule ...some special stuff for any of these hosts...
670 Without this flag you would have to write the condition/rule
677 <p><strong>Example:</strong></p>
679 <p>To rewrite the Homepage of a site according to the
680 ``<code>User-Agent:</code>'' header of the request, you can
681 use the following: </p>
683 <div class="example"><pre>
684 RewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
685 RewriteRule ^/$ /homepage.max.html [L]
687 RewriteCond %{HTTP_USER_AGENT} ^Lynx.*
688 RewriteRule ^/$ /homepage.min.html [L]
690 RewriteRule ^/$ /homepage.std.html [L]
693 <p>Explanation: If you use a browser which identifies itself
694 as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you
695 get the max homepage (which could include frames, or other special
697 If you use the Lynx browser (which is terminal-based), then
698 you get the min homepage (which could be a version designed for
699 easy, text-only browsing).
700 If neither of these conditions apply (you use any other browser,
701 or your browser identifies itself as something non-standard), you get
702 the std (standard) homepage.</p>
706 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
707 <div class="directive-section"><h2><a name="RewriteEngine" id="RewriteEngine">RewriteEngine</a> <a name="rewriteengine" id="rewriteengine">Directive</a></h2>
708 <table class="directive">
709 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables or disables runtime rewriting engine</td></tr>
710 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteEngine on|off</code></td></tr>
711 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteEngine off</code></td></tr>
712 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
713 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
714 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
715 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
718 <p>The <code class="directive">RewriteEngine</code> directive enables or
719 disables the runtime rewriting engine. If it is set to
720 <code>off</code> this module does no runtime processing at
721 all. It does not even update the <code>SCRIPT_URx</code>
722 environment variables.</p>
724 <p>Use this directive to disable the module instead of
725 commenting out all the <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives!</p>
727 <p>Note that, by default, rewrite configurations are not
728 inherited. This means that you need to have a
729 <code>RewriteEngine on</code> directive for each virtual host
730 in which you wish to use it.</p>
732 <p><code class="directive">RewriteMap</code> directives of the type <code>prg</code>
733 are not started during server initialization if they're defined in a
734 context that does not have <code class="directive">RewriteEngine</code> set to
739 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
740 <div class="directive-section"><h2><a name="RewriteLock" id="RewriteLock">RewriteLock</a> <a name="rewritelock" id="rewritelock">Directive</a></h2>
741 <table class="directive">
742 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of the lock file used for <code class="directive"><a href="#rewritemap">RewriteMap</a></code>
743 synchronization</td></tr>
744 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLock <em>file-path</em></code></td></tr>
745 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
746 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
747 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
749 <p>This directive sets the filename for a synchronization
750 lockfile which mod_rewrite needs to communicate with <code class="directive"><a href="#rewritemap">RewriteMap</a></code>
751 <em>programs</em>. Set this lockfile to a local path (not on a
752 NFS-mounted device) when you want to use a rewriting
753 map-program. It is not required for other types of rewriting
757 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
758 <div class="directive-section"><h2><a name="RewriteLog" id="RewriteLog">RewriteLog</a> <a name="rewritelog" id="rewritelog">Directive</a></h2>
759 <table class="directive">
760 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of the file used for logging rewrite engine
762 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLog <em>file-path</em></code></td></tr>
763 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
764 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
765 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
767 <p>The <code class="directive">RewriteLog</code> directive sets the name
768 of the file to which the server logs any rewriting actions it
769 performs. If the name does not begin with a slash
770 ('<code>/</code>') then it is assumed to be relative to the
771 <em>Server Root</em>. The directive should occur only once per
774 <div class="note"> To disable the logging of
775 rewriting actions it is not recommended to set
776 <em>Filename</em> to <code>/dev/null</code>, because
777 although the rewriting engine does not then output to a
778 logfile it still creates the logfile output internally.
779 <strong>This will slow down the server with no advantage
780 to the administrator!</strong> To disable logging either
781 remove or comment out the <code class="directive">RewriteLog</code>
782 directive or use <code>RewriteLogLevel 0</code>!
785 <div class="note"><h3>Security</h3>
787 See the <a href="../misc/security_tips.html">Apache Security Tips</a>
788 document for details on how your security could be compromised if the
789 directory where logfiles are stored is writable by anyone other than
790 the user that starts the server.
793 <div class="example"><h3>Example</h3><p><code>
794 RewriteLog "/usr/local/var/apache/logs/rewrite.log"
799 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
800 <div class="directive-section"><h2><a name="RewriteLogLevel" id="RewriteLogLevel">RewriteLogLevel</a> <a name="rewriteloglevel" id="rewriteloglevel">Directive</a></h2>
801 <table class="directive">
802 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the verbosity of the log file used by the rewrite
804 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLogLevel <em>Level</em></code></td></tr>
805 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteLogLevel 0</code></td></tr>
806 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
807 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
808 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
810 <p>The <code class="directive">RewriteLogLevel</code> directive sets the
811 verbosity level of the rewriting logfile. The default level 0
812 means no logging, while 9 or more means that practically all
813 actions are logged.</p>
815 <p>To disable the logging of rewriting actions simply set
816 <em>Level</em> to 0. This disables all rewrite action
819 <div class="note"> Using a high value for
820 <em>Level</em> will slow down your Apache server
821 dramatically! Use the rewriting logfile at a
822 <em>Level</em> greater than 2 only for debugging!
825 <div class="example"><h3>Example</h3><p><code>
831 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
832 <div class="directive-section"><h2><a name="RewriteMap" id="RewriteMap">RewriteMap</a> <a name="rewritemap" id="rewritemap">Directive</a></h2>
833 <table class="directive">
834 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a mapping function for key-lookup</td></tr>
835 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
837 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
838 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
839 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
840 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The choice of different dbm types is available in
841 Apache 2.0.41 and later</td></tr>
843 <p>The <code class="directive">RewriteMap</code> directive defines a
844 <em>Rewriting Map</em> which can be used inside rule
845 substitution strings by the mapping-functions to
846 insert/substitute fields through a key lookup. The source of
847 this lookup can be of various types.</p>
849 <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
850 the name of the map and will be used to specify a
851 mapping-function for the substitution strings of a rewriting
852 rule via one of the following constructs:</p>
855 <strong><code>${</code> <em>MapName</em> <code>:</code>
856 <em>LookupKey</em> <code>}</code><br />
857 <code>${</code> <em>MapName</em> <code>:</code>
858 <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
859 <code>}</code></strong>
862 <p>When such a construct occurs, the map <em>MapName</em> is
863 consulted and the key <em>LookupKey</em> is looked-up. If the
864 key is found, the map-function construct is substituted by
865 <em>SubstValue</em>. If the key is not found then it is
866 substituted by <em>DefaultValue</em> or by the empty string
867 if no <em>DefaultValue</em> was specified.</p>
869 <p>For example, you might define a
870 <code class="directive">RewriteMap</code> as:</p>
872 <div class="example"><p><code>
873 RewriteMap examplemap txt:/path/to/file/map.txt
876 <p>You would then be able to use this map in a
877 <code class="directive">RewriteRule</code> as follows:</p>
879 <div class="example"><p><code>
880 RewriteRule ^/ex/(.*) ${examplemap:$1}
883 <p>The following combinations for <em>MapType</em> and
884 <em>MapSource</em> can be used:</p>
888 <strong>Standard Plain Text</strong><br />
889 MapType: <code>txt</code>, MapSource: Unix filesystem
890 path to valid regular file
892 <p>This is the standard rewriting map feature where the
893 <em>MapSource</em> is a plain ASCII file containing
894 either blank lines, comment lines (starting with a '#'
895 character) or pairs like the following - one per
899 <strong><em>MatchingKey</em>
900 <em>SubstValue</em></strong>
903 <div class="example"><h3>Example</h3><pre>
905 ## map.txt -- rewriting map
908 Ralf.S.Engelschall rse # Bastard Operator From Hell
909 Mr.Joe.Average joe # Mr. Average
912 <div class="example"><p><code>
913 RewriteMap real-to-user txt:/path/to/file/map.txt
918 <strong>Randomized Plain Text</strong><br />
919 MapType: <code>rnd</code>, MapSource: Unix filesystem
920 path to valid regular file
922 <p>This is identical to the Standard Plain Text variant
923 above but with a special post-processing feature: After
924 looking up a value it is parsed according to contained
925 ``<code>|</code>'' characters which have the meaning of
926 ``or''. In other words they indicate a set of
927 alternatives from which the actual returned value is
928 chosen randomly. For example, you might use the following map
929 file and directives to provide a random load balancing between
930 several back-end server, via a reverse-proxy. Images are sent
931 to one of the servers in the 'static' pool, while everything
932 else is sent to one of the 'dynamic' pool.</p>
935 <div class="example"><h3>Rewrite map file</h3><pre>
937 ## map.txt -- rewriting map
940 static www1|www2|www3|www4
944 <div class="example"><h3>Configuration directives</h3><p><code>
945 RewriteMap servers rnd:/path/to/file/map.txt<br />
947 RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
949 RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
954 <strong>Hash File</strong><br /> MapType:
955 <code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem
956 path to valid regular file
958 <p>Here the source is a binary format DBM file containing
959 the same contents as a <em>Plain Text</em> format file, but
960 in a special representation which is optimized for really
961 fast lookups. The <em>type</em> can be sdbm, gdbm, ndbm, or
962 db depending on <a href="../install.html#dbm">compile-time
963 settings</a>. If the <em>type</em> is ommitted, the
964 compile-time default will be chosen. You can create such a
965 file with any DBM tool or with the following Perl
966 script. Be sure to adjust it to create the appropriate
967 type of DBM. The example creates an NDBM file.</p>
969 <div class="example"><pre>
972 ## txt2dbm -- convert txt map to dbm format
978 ($txtmap, $dbmmap) = @ARGV;
980 open(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n";
981 tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644)
982 or die "Couldn't create $dbmmap!\n";
984 while (<TXT>) {
985 next if (/^\s*#/ or /^\s*$/);
986 $DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/);
993 <div class="example"><p><code>
994 $ txt2dbm map.txt map.db
999 <strong>Internal Function</strong><br />
1000 MapType: <code>int</code>, MapSource: Internal Apache
1003 <p>Here, the source is an internal Apache function.
1004 Currently you cannot create your own, but the following
1005 functions already exist:</p>
1008 <li><strong>toupper</strong>:<br />
1009 Converts the key to all upper case.</li>
1011 <li><strong>tolower</strong>:<br />
1012 Converts the key to all lower case.</li>
1014 <li><strong>escape</strong>:<br />
1015 Translates special characters in the key to
1018 <li><strong>unescape</strong>:<br />
1019 Translates hex-encodings in the key back to
1020 special characters.</li>
1025 <strong>External Rewriting Program</strong><br />
1026 MapType: <code>prg</code>, MapSource: Unix filesystem
1027 path to valid regular file
1029 <p>Here the source is a program, not a map file. To
1030 create it you can use a language of your choice, but
1031 the result has to be an executable program (either
1032 object-code or a script with the magic cookie trick
1033 '<code>#!/path/to/interpreter</code>' as the first
1036 <p>This program is started once, when the Apache server
1037 is started, and then communicates with the rewriting engine
1038 via its <code>stdin</code> and <code>stdout</code>
1039 file-handles. For each map-function lookup it will
1040 receive the key to lookup as a newline-terminated string
1041 on <code>stdin</code>. It then has to give back the
1042 looked-up value as a newline-terminated string on
1043 <code>stdout</code> or the four-character string
1044 ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there
1045 is no corresponding value for the given key). A trivial
1046 program which will implement a 1:1 map (<em>i.e.</em>,
1047 key == value) could be:</p>
1049 <p>External rewriting programs are not started if they're defined in a
1050 context that does not have <code class="directive">RewriteEngine</code> set to
1051 <code>on</code></p>.
1053 <div class="example"><pre>
1056 while (<STDIN>) {
1057 # ...put here any transformations or lookups...
1062 <p>But be very careful:</p>
1065 <li>``<em>Keep it simple, stupid</em>'' (KISS).
1066 If this program hangs, it will cause Apache to hang
1067 when trying to use the relevant rewrite rule.</li>
1069 <li>A common mistake is to use buffered I/O on
1070 <code>stdout</code>. Avoid this, as it will cause a deadloop!
1071 ``<code>$|=1</code>'' is used above, to prevent this.</li>
1073 <li>The <code class="directive"><a href="#rewritelock">RewriteLock</a></code> directive can
1074 be used to define a lockfile which mod_rewrite can use to synchronize
1075 communication with the mapping program. By default no such
1076 synchronization takes place.</li>
1080 <p>The <code class="directive">RewriteMap</code> directive can occur more than
1081 once. For each mapping-function use one
1082 <code class="directive">RewriteMap</code> directive to declare its rewriting
1083 mapfile. While you cannot <strong>declare</strong> a map in
1084 per-directory context it is of course possible to
1085 <strong>use</strong> this map in per-directory context. </p>
1087 <div class="note"><h3>Note</h3> For plain text and DBM format files the
1088 looked-up keys are cached in-core until the <code>mtime</code> of the
1089 mapfile changes or the server does a restart. This way you can have
1090 map-functions in rules which are used for <strong>every</strong>
1091 request. This is no problem, because the external lookup only happens
1097 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1098 <div class="directive-section"><h2><a name="RewriteOptions" id="RewriteOptions">RewriteOptions</a> <a name="rewriteoptions" id="rewriteoptions">Directive</a></h2>
1099 <table class="directive">
1100 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets some special options for the rewrite engine</td></tr>
1101 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteOptions <var>Options</var></code></td></tr>
1102 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteOptions MaxRedirects=10</code></td></tr>
1103 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1104 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
1105 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1106 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
1107 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><code>MaxRedirects</code> is available in Apache 2.0.45 and
1111 <p>The <code class="directive">RewriteOptions</code> directive sets some
1112 special options for the current per-server or per-directory
1113 configuration. The <em>Option</em> strings can be one of the
1117 <dt><code>inherit</code></dt>
1118 <dd>This forces the current configuration to inherit the
1119 configuration of the parent. In per-virtual-server context
1120 this means that the maps, conditions and rules of the main
1121 server are inherited. In per-directory context this means
1122 that conditions and rules of the parent directory's
1123 <code>.htaccess</code> configuration are inherited.</dd>
1125 <dt><code>MaxRedirects=<var>number</var></code></dt>
1126 <dd>In order to prevent endless loops of internal redirects
1127 issued by per-directory <code class="directive"><a href="#rewriterule">RewriteRule</a></code>s, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> aborts
1128 the request after reaching a maximum number of such redirects and
1129 responds with an 500 Internal Server Error. If you really need
1130 more internal redirects than 10 per request, you may increase
1131 the default to the desired value.</dd>
1135 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1136 <div class="directive-section"><h2><a name="RewriteRule" id="RewriteRule">RewriteRule</a> <a name="rewriterule" id="rewriterule">Directive</a></h2>
1137 <table class="directive">
1138 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines rules for the rewriting engine</td></tr>
1139 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteRule
1140 <em>Pattern</em> <em>Substitution</em></code></td></tr>
1141 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1142 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
1143 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1144 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
1145 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The cookie-flag is available in Apache 2.0.40 and later.</td></tr>
1147 <p>The <code class="directive">RewriteRule</code> directive is the real
1148 rewriting workhorse. The directive can occur more than once, with
1149 each instance defining a single rewrite rule. The
1150 order in which these rules are defined is important - this is the order
1151 in which they will be applied at run-time.</p>
1153 <p><a id="patterns" name="patterns"><em>Pattern</em></a> is
1154 a perl compatible <a id="regexp" name="regexp">regular
1155 expression</a>, which is applied to the current URL.
1156 ``Current'' means the value of the URL when this rule is
1157 applied. This may not be the originally requested URL,
1158 which may already have matched a previous rule, and have
1161 <p>Some hints on the syntax of regular expressions:</p>
1163 <div class="note"><pre>
1164 <strong>Text:</strong>
1165 <strong><code>.</code></strong> Any single character
1166 <strong><code>[</code></strong>chars<strong><code>]</code></strong> Character class: Any character of the class ``chars''
1167 <strong><code>[^</code></strong>chars<strong><code>]</code></strong> Character class: Not a character of the class ``chars''
1168 text1<strong><code>|</code></strong>text2 Alternative: text1 or text2
1170 <strong>Quantifiers:</strong>
1171 <strong><code>?</code></strong> 0 or 1 occurrences of the preceding text
1172 <strong><code>*</code></strong> 0 or N occurrences of the preceding text (N > 0)
1173 <strong><code>+</code></strong> 1 or N occurrences of the preceding text (N > 1)
1175 <strong>Grouping:</strong>
1176 <strong><code>(</code></strong>text<strong><code>)</code></strong> Grouping of text
1177 (used either to set the borders of an alternative as above, or
1178 to make backreferences, where the <strong>N</strong>th group can
1179 be referred to on the RHS of a RewriteRule as <code>$</code><strong>N</strong>)
1181 <strong>Anchors:</strong>
1182 <strong><code>^</code></strong> Start-of-line anchor
1183 <strong><code>$</code></strong> End-of-line anchor
1185 <strong>Escaping:</strong>
1186 <strong><code>\</code></strong>char escape the given char
1187 (for instance, to specify the chars "<code>.[]()</code>" <em>etc.</em>)
1190 <p>For more information about regular expressions, have a look at the
1191 perl regular expression manpage ("<a href="http://perldoc.perl.org/perlre.html">perldoc
1192 perlre</a>"). If you are interested in more detailed
1193 information about regular expressions and their variants
1194 (POSIX regex etc.) the following book is dedicated to this topic:</p>
1197 <em>Mastering Regular Expressions, 2nd Edition</em><br />
1198 Jeffrey E.F. Friedl<br />
1199 O'Reilly & Associates, Inc. 2002<br />
1200 ISBN 0-596-00289-0<br />
1203 <p>In mod_rewrite, the NOT character
1204 ('<code>!</code>') is also available as a possible pattern
1205 prefix. This enables you to negate a pattern; to say, for instance:
1206 ``<em>if the current URL does <strong>NOT</strong> match this
1207 pattern</em>''. This can be used for exceptional cases, where
1208 it is easier to match the negative pattern, or as a last
1211 <div class="note"><h3>Note</h3>
1212 When using the NOT character to negate a pattern, you cannot include
1213 grouped wildcard parts in that pattern. This is because, when the
1214 pattern does NOT match (ie, the negation matches), there are no
1215 contents for the groups. Thus, if negated patterns are used, you
1216 cannot use <code>$N</code> in the substitution string!
1219 <p>The <a id="rhs" name="rhs"><em>substitution</em></a> of a
1220 rewrite rule is the string which is substituted for (or
1221 replaces) the original URL which <em>Pattern</em>
1222 matched. In addition to plain text, it 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 <code>RewriteCond</code>
1244 directive. The mapping-functions come from the
1245 <code>RewriteMap</code> directive and are explained there.
1246 These three types of variables are expanded in the order above.</p>
1248 <p>As already mentioned, all rewrite rules are
1249 applied to the <em>Substitution</em> (in the order in which
1251 in the config file). The URL is <strong>completely
1252 replaced</strong> by the <em>Substitution</em> and the
1253 rewriting process continues until all rules have been applied,
1254 or it is explicitly terminated by a
1255 <code><strong>L</strong></code> flag - see below.</p>
1257 <p>There is a special substitution string named
1258 '<code>-</code>' which means: <strong>NO
1259 substitution</strong>! This is useful in providing
1260 rewriting rules which <strong>only</strong> match
1261 URLs but do not substitute anything for them. It is commonly used
1262 in conjunction with the <strong>C</strong> (chain) flag, in order
1263 to apply more than one pattern before substitution occurs.</p>
1265 <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">flags</a> for <em>Substitution</em> by
1266 appending <strong><code>[</code><em>flags</em><code>]</code></strong>
1267 as the third argument to the <code>RewriteRule</code>
1268 directive. <em>Flags</em> is a comma-separated list of any of the
1269 following flags: </p>
1272 <li>'<strong><code>chain|C</code></strong>'
1273 (<strong>c</strong>hained with next rule)<br />
1274 This flag chains the current rule with the next rule
1275 (which itself can be chained with the following rule,
1276 and so on). This has the following effect: if a rule
1277 matches, then processing continues as usual -
1278 the flag has no effect. If the rule does
1279 <strong>not</strong> match, then all following chained
1280 rules are skipped. For instance, it can be used to remove the
1281 ``<code>.www</code>'' part, inside a per-directory rule set,
1282 when you let an external redirect happen (where the
1283 ``<code>.www</code>'' part should not occur!).</li>
1286 '<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
1287 (set <strong>co</strong>okie)<br />
1288 This sets a cookie in the client's browser. The cookie's name
1289 is specified by <em>NAME</em> and the value is
1290 <em>VAL</em>. The <em>domain</em> field is the domain of the
1291 cookie, such as '.apache.org', the optional <em>lifetime</em>
1292 is the lifetime of the cookie in minutes, and the optional
1293 <em>path</em> is the path of the cookie</li>
1296 '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>'
1297 (set <strong>e</strong>nvironment variable)<br />
1298 This forces an environment variable named <em>VAR</em> to
1299 be set to the value <em>VAL</em>, where <em>VAL</em> can
1300 contain regexp backreferences (<code>$N</code> and
1301 <code>%N</code>) which will be expanded. You can use this
1302 flag more than once, to set more than one variable. The
1303 variables can later be dereferenced in many situations, most commonly
1304 from within XSSI (via <code><!--#echo
1305 var="VAR"--></code>) or CGI (<code>$ENV{'VAR'}</code>).
1306 You can also dereference the variable in a later RewriteCond pattern, using
1307 <code>%{ENV:VAR}</code>. Use this to strip
1308 information from URLs, while maintaining a record of that information.</li>
1310 <li>'<strong><code>forbidden|F</code></strong>' (force URL
1311 to be <strong>f</strong>orbidden)<br />
1312 This forces the current URL to be forbidden - it immediately
1313 sends back a HTTP response of 403 (FORBIDDEN).
1314 Use this flag in conjunction with
1315 appropriate RewriteConds to conditionally block some
1318 <li>'<strong><code>gone|G</code></strong>' (force URL to be
1319 <strong>g</strong>one)<br />
1320 This forces the current URL to be gone - it
1321 immediately sends back a HTTP response of 410 (GONE). Use
1322 this flag to mark pages which no longer exist as gone.</li>
1324 <li>'<strong><code>last|L</code></strong>'
1325 (<strong>l</strong>ast rule)<br />
1326 Stop the rewriting process here and don't apply any more
1327 rewrite rules. This corresponds to the Perl
1328 <code>last</code> command or the <code>break</code> command
1329 in C. Use this flag to prevent the currently
1330 rewritten URL from being rewritten further by following
1331 rules. For example, use it to rewrite the root-path URL
1332 ('<code>/</code>') to a real one, <em>e.g.</em>,
1333 '<code>/e/www/</code>'.</li>
1335 <li>'<strong><code>next|N</code></strong>'
1336 (<strong>n</strong>ext round)<br />
1337 Re-run the rewriting process (starting again with the
1338 first rewriting rule). This time, the URL to match is no longer
1339 the original URL, but rather the URL returned by the last rewriting rule.
1340 This corresponds to the Perl <code>next</code> command or
1341 the <code>continue</code> command in C. Use
1342 this flag to restart the rewriting process -
1343 to immediately go to the top of the loop.<br />
1344 <strong>Be careful not to create an infinite
1347 <li>'<strong><code>nocase|NC</code></strong>'
1348 (<strong>n</strong>o <strong>c</strong>ase)<br />
1349 This makes the <em>Pattern</em> case-insensitive,
1350 ignoring difference between 'A-Z' and
1351 'a-z' when <em>Pattern</em> is matched against the current
1355 '<strong><code>noescape|NE</code></strong>'
1356 (<strong>n</strong>o URI <strong>e</strong>scaping of
1358 This flag prevents mod_rewrite from applying the usual URI
1359 escaping rules to the result of a rewrite. Ordinarily,
1360 special characters (such as '%', '$', ';', and so on)
1361 will be escaped into their hexcode equivalents ('%25',
1362 '%24', and '%3B', respectively); this flag prevents this
1363 from happening. This allows percent symbols to appear in
1365 <div class="example"><p><code>
1366 RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
1369 which would turn '<code>/foo/zed</code>' into a safe
1370 request for '<code>/bar?arg=P1=zed</code>'.
1374 '<strong><code>nosubreq|NS</code></strong>' (
1375 <strong>n</strong>ot for internal
1376 <strong>s</strong>ub-requests)<br />
1377 This flag forces the rewrite engine to skip a
1378 rewrite rule if the current request is an internal
1379 sub-request. For instance, sub-requests occur internally
1380 in Apache when <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> tries to find out
1381 information about possible directory default files
1382 (<code>index.xxx</code>). On sub-requests it is not
1383 always useful, and can even cause errors, if
1384 the complete set of rules are applied. Use this flag to
1385 exclude some rules.<br />
1386 To decide whether or not to use this rule: if you
1387 prefix URLs with CGI-scripts, to force them to be
1388 processed by the CGI-script, it's likely that you
1389 will run into problems (or significant overhead) on
1390 sub-requests. In these cases, use this flag.
1394 '<strong><code>proxy|P</code></strong>' (force
1395 <strong>p</strong>roxy)<br />
1396 This flag forces the substitution part to be internally
1397 sent as a proxy request and immediately (rewrite
1398 processing stops here) put through the <a href="mod_proxy.html">proxy module</a>. You must make
1399 sure that the substitution string is a valid URI
1400 (typically starting with
1401 <code>http://</code><em>hostname</em>) which can be
1402 handled by the Apache proxy module. If not, you will get an
1403 error from the proxy module. Use this flag to achieve a
1404 more powerful implementation of the <a href="mod_proxy.html#proxypass">ProxyPass</a> directive,
1405 to map remote content into the namespace of the local
1408 <p>Note: <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> must be enabled in order
1409 to use this flag.</p>
1413 '<strong><code>passthrough|PT</code></strong>'
1414 (<strong>p</strong>ass <strong>t</strong>hrough to next
1416 This flag forces the rewrite engine to set the
1417 <code>uri</code> field of the internal
1418 <code>request_rec</code> structure to the value of the
1419 <code>filename</code> field. This flag is just a hack to
1420 enable post-processing of the output of
1421 <code>RewriteRule</code> directives, using
1422 <code>Alias</code>, <code>ScriptAlias</code>,
1423 <code>Redirect</code>, and other directives from
1424 various URI-to-filename translators. For example, to rewrite
1425 <code>/abc</code> to <code>/def</code> using
1426 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>, and then
1427 <code>/def</code> to <code>/ghi</code> using
1428 <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code>:
1429 <div class="example"><p><code>
1430 RewriteRule ^/abc(.*) /def$1 [PT]<br />
1433 If you omit the <code>PT</code> flag,
1434 <code>mod_rewrite</code> will rewrite
1435 <code>uri=/abc/...</code> to
1436 <code>filename=/def/...</code> as a full API-compliant
1437 URI-to-filename translator should do. Then
1438 <code>mod_alias</code> will try to do a
1439 URI-to-filename transition, which will fail.
1441 <p>Note: <strong>You must use this flag if you want to
1442 mix directives from different modules which allow
1443 URL-to-filename translators</strong>. The typical example
1444 is the use of <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and
1445 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.</p>
1448 <li>'<strong><code>qsappend|QSA</code></strong>'
1449 (<strong>q</strong>uery <strong>s</strong>tring
1450 <strong>a</strong>ppend)<br />
1451 This flag forces the rewrite engine to append a query
1452 string part of the substitution string to the existing string,
1453 instead of replacing it. Use this when you want to add more
1454 data to the query string via a rewrite rule.</li>
1456 <li>'<strong><code>redirect|R</code>
1457 [=<em>code</em>]</strong>' (force <a id="redirect" name="redirect"><strong>r</strong>edirect</a>)<br />
1458 Prefix <em>Substitution</em> with
1459 <code>http://thishost[:thisport]/</code> (which makes the
1460 new URL a URI) to force a external redirection. If no
1461 <em>code</em> is given, a HTTP response of 302 (MOVED
1462 TEMPORARILY) will be returned. If you want to use other response
1463 codes in the range 300-400, simply specify the appropriate number
1464 or use one of the following symbolic names:
1465 <code>temp</code> (default), <code>permanent</code>,
1466 <code>seeother</code>. Use this for rules to
1467 canonicalize the URL and return it to the client - to
1468 translate ``<code>/~</code>'' into
1469 ``<code>/u/</code>'', or to always append a slash to
1470 <code>/u/</code><em>user</em>, etc.<br />
1471 <strong>Note:</strong> When you use this flag, make
1472 sure that the substitution field is a valid URL! Otherwise,
1473 you will be redirecting to an invalid location. Remember
1474 that this flag on its own will only prepend
1475 <code>http://thishost[:thisport]/</code> to the URL, and rewriting
1476 will continue. Usually, you will want to stop rewriting at this point,
1477 and redirect immediately. To stop rewriting, you should add
1481 <li>'<strong><code>skip|S</code></strong>=<em>num</em>'
1482 (<strong>s</strong>kip next rule(s))<br />
1483 This flag forces the rewriting engine to skip the next
1484 <em>num</em> rules in sequence, if the current rule
1485 matches. Use this to make pseudo if-then-else constructs:
1486 The last rule of the then-clause becomes
1487 <code>skip=N</code>, where N is the number of rules in the
1488 else-clause. (This is <strong>not</strong> the same as the
1489 'chain|C' flag!)</li>
1492 '<strong><code>type|T</code></strong>=<em>MIME-type</em>'
1493 (force MIME <strong>t</strong>ype)<br />
1494 Force the MIME-type of the target file to be
1495 <em>MIME-type</em>. This can be used to
1496 set up the content-type based on some conditions.
1497 For example, the following snippet allows <code>.php</code> files to
1498 be <em>displayed</em> by <code>mod_php</code> if they are called with
1499 the <code>.phps</code> extension:
1500 <div class="example"><p><code>
1501 RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]
1507 <div class="note"><h3>Home directory expansion</h3>
1508 <p> When the substitution string begins with a string
1509 resembling "/~user" (via explicit text or backreferences), mod_rewrite performs
1510 home directory expansion independent of the presence or configuration
1511 of <code class="module"><a href="../mod/mod_userdir.html">mod_userdir</a></code>.</p>
1513 <p> This expansion does not occur when the <em>PT</em>
1514 flag is used on the <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
1518 <div class="note"><h3>Note: Enabling rewrites in per-directory context</h3>
1519 To enable the rewriting engine
1520 for per-directory configuration files, you need to set
1521 ``<code>RewriteEngine On</code>'' in these files
1522 <strong>and</strong> ``<code>Options
1523 FollowSymLinks</code>'' must be enabled. If your
1524 administrator has disabled override of
1525 <code>FollowSymLinks</code> for a user's directory, then
1526 you cannot use the rewriting engine. This restriction is
1527 needed for security reasons.
1530 <div class="note"><h3>Note: Pattern matching in per-directory context</h3>
1531 Never forget that <em>Pattern</em> is
1532 applied to a complete URL in per-server configuration
1533 files. <strong>However, in per-directory configuration files, the
1534 per-directory prefix (which always is the same for a specific
1535 directory) is automatically <em>removed</em> for the pattern matching
1536 and automatically <em>added</em> after the substitution has been
1537 done.</strong> This feature is essential for many sorts of rewriting -
1538 without this, you would always have to match the parent
1539 directory which is not always possible.
1541 <p>There is one exception: If a substitution string
1542 starts with ``<code>http://</code>'', then the directory
1543 prefix will <strong>not</strong> be added, and an
1544 external redirect or proxy throughput (if flag
1545 <strong>P</strong> is used) is forced!</p>
1549 <div class="note"><h3>Note: Substitution of Absolute URLs</h3>
1550 <p>When you prefix a substitution field with
1551 <code>http://thishost[:thisport]</code>,
1552 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> will automatically strip that
1553 out. This auto-reduction on URLs with an implicit external redirect
1554 is most useful in combination with
1555 a mapping-function which generates the
1558 <p><strong>Remember:</strong> An unconditional external
1559 redirect to your own server will not work with the prefix
1560 <code>http://thishost</code> because of this feature. To
1561 achieve such a self-redirect, you have to use the
1562 <strong>R</strong>-flag.</p>
1565 <div class="note"><h3>Note: Query String</h3>
1566 <p>The <em>Pattern</em> will not be matched against the query string.
1567 Instead, you must use a <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
1568 <code>%{QUERY_STRING}</code> variable. You can, however, create
1569 URLs in the substitution string, containing a query string
1570 part. Simply use a question mark inside the substitution string, to
1571 indicate that the following text should be re-injected into the
1572 query string. When you want to erase an existing query string,
1573 end the substitution string with just a question mark. To
1574 combine a new query string with an old one, use the
1575 <code>[QSA]</code> flag.</p>
1578 <p>Here are all possible substitution combinations and their
1581 <p><strong>Inside per-server configuration
1582 (<code>httpd.conf</code>)<br />
1583 for request ``<code>GET
1584 /somepath/pathinfo</code>'':</strong><br />
1587 <div class="note"><pre>
1588 <strong>Given Rule</strong> <strong>Resulting Substitution</strong>
1589 ---------------------------------------------- ----------------------------------
1590 ^/somepath(.*) otherpath$1 invalid, not supported
1592 ^/somepath(.*) otherpath$1 [R] invalid, not supported
1594 ^/somepath(.*) otherpath$1 [P] invalid, not supported
1595 ---------------------------------------------- ----------------------------------
1596 ^/somepath(.*) /otherpath$1 /otherpath/pathinfo
1598 ^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
1599 via external redirection
1601 ^/somepath(.*) /otherpath$1 [P] doesn't make sense, not supported
1602 ---------------------------------------------- ----------------------------------
1603 ^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
1605 ^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
1606 via external redirection
1608 ^/somepath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported
1609 ---------------------------------------------- ----------------------------------
1610 ^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
1611 via external redirection
1613 ^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
1614 via external redirection
1615 (the [R] flag is redundant)
1617 ^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
1621 <p><strong>Inside per-directory configuration for
1622 <code>/somepath</code><br />
1623 (<code>/physical/path/to/somepath/.htacccess</code>, with
1624 <code>RewriteBase /somepath</code>)<br />
1625 for request ``<code>GET
1626 /somepath/localpath/pathinfo</code>'':</strong><br />
1629 <div class="note"><pre>
1630 <strong>Given Rule</strong> <strong>Resulting Substitution</strong>
1631 ---------------------------------------------- ----------------------------------
1632 ^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo
1634 ^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo
1635 via external redirection
1637 ^localpath(.*) otherpath$1 [P] doesn't make sense, not supported
1638 ---------------------------------------------- ----------------------------------
1639 ^localpath(.*) /otherpath$1 /otherpath/pathinfo
1641 ^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
1642 via external redirection
1644 ^localpath(.*) /otherpath$1 [P] doesn't make sense, not supported
1645 ---------------------------------------------- ----------------------------------
1646 ^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
1648 ^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
1649 via external redirection
1651 ^localpath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported
1652 ---------------------------------------------- ----------------------------------
1653 ^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
1654 via external redirection
1656 ^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
1657 via external redirection
1658 (the [R] flag is redundant)
1660 ^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
1666 <div class="bottomlang">
1667 <p><span>Available Languages: </span><a href="../en/mod/mod_rewrite.html" title="English"> en </a></p>
1668 </div><div id="footer">
1669 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
1670 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>