1 <?xml version='1.0' encoding='UTF-8' ?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.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 <manualpage metafile="intro.xml.meta">
24 <parentdocument href="./">Rewrite</parentdocument>
26 <title>Apache mod_rewrite Introduction</title>
29 <p>This document supplements the <module>mod_rewrite</module>
30 <a href="../mod/mod_rewrite.html">reference documentation</a>. It
31 describes the basic concepts necessary for use of
32 <module>mod_rewrite</module>. Other documents go into greater detail,
33 but this doc should help the beginner get their feet wet.
37 <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
38 <!-- <seealso><a href="intro.html">mod_rewrite introduction</a></seealso> -->
39 <seealso><a href="remapping.html">Redirection and remapping</a></seealso>
40 <seealso><a href="access.html">Controlling access</a></seealso>
41 <seealso><a href="vhosts.html">Virtual hosts</a></seealso>
42 <seealso><a href="proxy.html">Proxying</a></seealso>
43 <seealso><a href="rewritemap.html">Using RewriteMap</a></seealso>
44 <seealso><a href="advanced.html">Advanced techniques</a></seealso>
45 <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
47 <section id="introduction"><title>Introduction</title>
48 <p>The Apache module <module>mod_rewrite</module> is a very powerful and
49 sophisticated module which provides a way to do URL manipulations. With
50 it, you can do nearly all types of URL rewriting that you may need. It
51 is, however, somewhat complex, and may be intimidating to the beginner.
52 There is also a tendency to treat rewrite rules as magic incantation,
53 using them without actually understanding what they do.</p>
55 <p>This document attempts to give sufficient background so that what
56 follows is understood, rather than just copied blindly.
59 <p>Remember that many common URL-manipulation tasks don't require the
60 full power and complexity of <module>mod_rewrite</module>. For simple
61 tasks, see <module>mod_alias</module> and the documentation
62 on <a href="../urlmapping.html">mapping URLs to the
65 <p>Finally, before proceeding, be sure to configure
66 <module>mod_rewrite</module>'s log level to one of the trace levels using
67 the <directive module="core">LogLevel</directive> directive. Although this
68 can give an overwhelming amount of information, it is indispensable in
69 debugging problems with <module>mod_rewrite</module> configuration, since
70 it will tell you exactly how each rule is processed.</p>
74 <section id="regex"><title>Regular Expressions</title>
76 <p>mod_rewrite uses the <a href="http://pcre.org/">Perl Compatible
77 Regular Expression</a> vocabulary. In this document, we do not attempt
78 to provide a detailed reference to regular expressions. For that, we
79 recommend the <a href="http://pcre.org/pcre.txt">PCRE man pages</a>, the
80 <a href="http://perldoc.perl.org/perlre.html">Perl regular
81 expression man page</a>, and <a
82 href="http://shop.oreilly.com/product/9780596528126.do">Mastering
83 Regular Expressions, by Jeffrey Friedl</a>.</p>
85 <p>In this document, we attempt to provide enough of a regex vocabulary
86 to get you started, without being overwhelming, in the hope that
87 <directive module="mod_rewrite">RewriteRule</directive>s will be scientific
88 formulae, rather than magical incantations.</p>
90 <section id="regexvocab"><title>Regex vocabulary</title>
92 <p>The following are the minimal building blocks you will need, in order
93 to write regular expressions and <directive
94 module="mod_rewrite">RewriteRule</directive>s. They certainly do not
95 represent a complete regular expression vocabulary, but they are a good
96 place to start, and should help you read basic regular expressions, as
97 well as write your own.</p>
106 <tr><td><code>.</code></td><td>Matches any single
107 character</td><td><code>c.t</code> will match <code>cat</code>,
108 <code>cot</code>, <code>cut</code>, etc.</td></tr>
109 <tr><td><code>+</code></td><td>Repeats the previous match one or more
110 times</td><td><code>a+</code> matches <code>a</code>, <code>aa</code>,
111 <code>aaa</code>, etc</td></tr>
112 <tr><td><code>*</code></td><td>Repeats the previous match zero or more
113 times.</td><td><code>a*</code> matches all the same things
114 <code>a+</code> matches, but will also match an empty string.</td></tr>
115 <tr><td><code>?</code></td><td>Makes the match optional.</td><td>
116 <code>colou?r</code> will match <code>color</code> and <code>colour</code>.</td>
118 <tr><td><code>^</code></td><td>Called an anchor, matches the beginning
119 of the string</td><td><code>^a</code> matches a string that begins with
120 <code>a</code></td></tr>
121 <tr><td><code>$</code></td><td>The other anchor, this matches the end of
122 the string.</td><td><code>a$</code> matches a string that ends with
123 <code>a</code>.</td></tr>
124 <tr><td><code>( )</code></td><td>Groups several characters into a single
125 unit, and captures a match for use in a backreference.</td><td><code>(ab)+</code>
126 matches <code>ababab</code> - that is, the <code>+</code> applies to the group.
127 For more on backreferences see <a href="#InternalBackRefs">below</a>.</td></tr>
128 <tr><td><code>[ ]</code></td><td>A character class - matches one of the
129 characters</td><td><code>c[uoa]t</code> matches <code>cut</code>,
130 <code>cot</code> or <code>cat</code>.</td></tr>
131 <tr><td><code>[^ ]</code></td><td>Negative character class - matches any character not specified</td><td><code>c[^/]t</code> matches <code>cat</code> or <code>c=t</code> but not <code>c/t</code></td></tr>
134 <p>In <module>mod_rewrite</module> the <code>!</code> character can be
135 used before a regular expression to negate it. This is, a string will
136 be considered to have matched only if it does not match the rest of
141 <section id="InternalBackRefs"><title>Regex Back-Reference Availability</title>
143 <p>One important thing here has to be remembered: Whenever you
144 use parentheses in <em>Pattern</em> or in one of the
145 <em>CondPattern</em>, back-references are internally created
146 which can be used with the strings <code>$N</code> and
147 <code>%N</code> (see below). These are available for creating
148 the <em>Substitution</em> parameter of a
149 <directive module="mod_rewrite">RewriteRule</directive> or
150 the <em>TestString</em> parameter of a
151 <directive module="mod_rewrite">RewriteCond</directive>.</p>
152 <p> Captures in the <directive module="mod_rewrite"
153 >RewriteRule</directive> patterns are (counterintuitively) available to
155 <directive module="mod_rewrite">RewriteCond</directive> directives,
156 because the <directive module="mod_rewrite">RewriteRule</directive>
157 expression is evaluated before the individual conditions.</p>
159 <p>Figure 1 shows to which
160 locations the back-references are transferred for expansion as
161 well as illustrating the flow of the RewriteRule, RewriteCond
162 matching. In the next chapters, we will be exploring how to use
163 these back-references, so do not fret if it seems a bit alien
168 <img src="../images/rewrite_backreferences.png"
169 alt="Flow of RewriteRule and RewriteCond matching" /><br />
170 <dfn>Figure 1:</dfn> The back-reference flow through a rule.<br />
171 In this example, a request for <code>/test/1234</code> would be transformed into <code>/admin.foo?page=test&id=1234&host=admin.example.com</code>.
177 <section id="rewriterule"><title>RewriteRule Basics</title>
178 <p>A <directive module="mod_rewrite">RewriteRule</directive> consists
179 of three arguments separated by spaces. The arguments are</p>
181 <li><var>Pattern</var>: which incoming URLs should be affected by the rule;</li>
182 <li><var>Substitution</var>: where should the matching requests be sent;</li>
183 <li><var>[flags]</var>: options affecting the rewritten request.</li>
186 <p>The <var>Pattern</var> is a <a href="#regex">regular expression</a>.
187 It is initially (for the first rewrite rule or until a substitution occurs)
188 matched against the URL-path of the incoming request (the part after the
189 hostname but before any question mark indicating the beginning of a query
190 string) or, in per-directory context, against the request's path relative
191 to the directory for which the rule is defined. Once a substitution has
192 occurred, the rules that follow are matched against the substituted
197 <img src="../images/syntax_rewriterule.png"
198 alt="Syntax of the RewriteRule directive" /><br />
199 <dfn>Figure 2:</dfn> Syntax of the RewriteRule directive.
203 <p>The <var>Substitution</var> can itself be one of three things:</p>
206 <dt>A full filesystem path to a resource</dt>
208 <highlight language="config">
209 RewriteRule "^/games" "/usr/local/games/web"
211 <p>This maps a request to an arbitrary location on your filesystem, much
212 like the <directive module="mod_alias">Alias</directive> directive.</p>
215 <dt>A web-path to a resource</dt>
217 <highlight language="config">
218 RewriteRule "^/foo$" "/bar"
220 <p>If <directive module="core">DocumentRoot</directive> is set
221 to <code>/usr/local/apache2/htdocs</code>, then this directive would
222 map requests for <code>http://example.com/foo</code> to the
223 path <code>/usr/local/apache2/htdocs/bar</code>.</p>
226 <dt>An absolute URL</dt>
228 <highlight language="config">
229 RewriteRule "^/product/view$" "http://site2.example.com/seeproduct.html" [R]
231 <p>This tells the client to make a new request for the specified URL.</p>
235 <p>The <var>Substitution</var> can also
236 contain <em>back-references</em> to parts of the incoming URL-path
237 matched by the <var>Pattern</var>. Consider the following:</p>
238 <highlight language="config">
239 RewriteRule "^/product/(.*)/view$" "/var/web/productdb/$1"
241 <p>The variable <code>$1</code> will be replaced with whatever text
242 was matched by the expression inside the parenthesis in
243 the <var>Pattern</var>. For example, a request
244 for <code>http://example.com/product/r14df/view</code> will be mapped
245 to the path <code>/var/web/productdb/r14df</code>.</p>
247 <p>If there is more than one expression in parenthesis, they are
248 available in order in the
249 variables <code>$1</code>, <code>$2</code>, <code>$3</code>, and so
255 <section id="flags"><title>Rewrite Flags</title>
256 <p>The behavior of a <directive
257 module="mod_rewrite">RewriteRule</directive> can be modified by the
258 application of one or more flags to the end of the rule. For example, the
259 matching behavior of a rule can be made case-insensitive by the
260 application of the <code>[NC]</code> flag:
262 <highlight language="config">
263 RewriteRule "^puppy.html" "smalldog.html" [NC]
266 <p>For more details on the available flags, their meanings, and
267 examples, see the <a href="flags.html">Rewrite Flags</a> document.</p>
272 <section id="rewritecond"><title>Rewrite Conditions</title>
273 <p>One or more <directive module="mod_rewrite">RewriteCond</directive>
274 directives can be used to restrict the types of requests that will be
276 following <directive module="mod_rewrite">RewriteRule</directive>. The
277 first argument is a variable describing a characteristic of the
278 request, the second argument is a <a href="#regex">regular
279 expression</a> that must match the variable, and a third optional
280 argument is a list of flags that modify how the match is evaluated.</p>
283 <img src="../images/syntax_rewritecond.png"
284 alt="Syntax of the RewriteCond directive" /><br />
285 <dfn>Figure 3:</dfn> Syntax of the RewriteCond directive
288 <p>For example, to send all requests from a particular IP range to a
289 different server, you could use:</p>
290 <highlight language="config">
291 RewriteCond "%{REMOTE_ADDR}" "^10\.2\."
292 RewriteRule "(.*)" "http://intranet.example.com$1"
296 one <directive module="mod_rewrite">RewriteCond</directive> is
297 specified, they must all match for
298 the <directive module="mod_rewrite">RewriteRule</directive> to be
299 applied. For example, to deny requests that contain the word "hack" in
300 their query string, unless they also contain a cookie containing
301 the word "go", you could use:</p>
302 <highlight language="config">
303 RewriteCond "%{QUERY_STRING}" "hack"
304 RewriteCond "%{HTTP_COOKIE}" !go
305 RewriteRule "." "-" [F]
307 <p>Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".</p>
309 <p>Matches in the regular expressions contained in
310 the <directive module="mod_rewrite">RewriteCond</directive>s can be
311 used as part of the <var>Substitution</var> in
312 the <directive module="mod_rewrite">RewriteRule</directive> using the
313 variables <code>%1</code>, <code>%2</code>, etc. For example, this
314 will direct the request to a different directory depending on the
315 hostname used to access the site:</p>
316 <highlight language="config">
317 RewriteCond "%{HTTP_HOST}" "(.*)"
318 RewriteRule "^/(.*)" "/sites/%1/$1"
320 <p>If the request was for <code>http://example.com/foo/bar</code>,
321 then <code>%1</code> would contain <code>example.com</code>
322 and <code>$1</code> would contain <code>foo/bar</code>.</p>
328 <section id="rewritemap"><title>Rewrite maps</title>
330 <p>The <directive module="mod_rewrite">RewriteMap</directive> directive
331 provides a way to call an external function, so to speak, to do your
332 rewriting for you. This is discussed in greater detail in the <a
333 href="rewritemap.html">RewriteMap supplementary documentation</a>.</p>
336 <section id="htaccess"><title>.htaccess files</title>
338 <p>Rewriting is typically configured in the main server configuration
339 setting (outside any <directive type="section"
340 module="core">Directory</directive> section) or
341 inside <directive type="section" module="core">VirtualHost</directive>
342 containers. This is the easiest way to do rewriting and is
343 recommended. It is possible, however, to do rewriting
344 inside <directive type="section" module="core">Directory</directive>
345 sections or <a href="../howto/htaccess.html"><code>.htaccess</code>
346 files</a> at the expense of some additional complexity. This technique
347 is called per-directory rewrites.</p>
349 <p>The main difference with per-server rewrites is that the path
350 prefix of the directory containing the <code>.htaccess</code> file is
351 stripped before matching in
352 the <directive module="mod_rewrite">RewriteRule</directive>. In addition, the <directive module="mod_rewrite">RewriteBase</directive> should be used to assure the request is properly mapped.</p>