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 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
7 This file is generated from xml source: DO NOT EDIT
8 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
10 <title>Apache mod_rewrite Introduction - Apache HTTP Server Version 2.5</title>
11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
18 <body id="manual-page"><div id="page-header">
19 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
20 <p class="apache">Apache HTTP Server Version 2.5</p>
21 <img alt="" src="../images/feather.png" /></div>
22 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
24 <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.5</a> > <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Introduction</h1>
26 <p><span>Available Languages: </span><a href="../en/rewrite/intro.html" title="English"> en </a> |
27 <a href="../fr/rewrite/intro.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
30 <p>This document supplements the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
31 <a href="../mod/mod_rewrite.html">reference documentation</a>. It
32 describes the basic concepts necessary for use of
33 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. Other documents go into greater detail,
34 but this doc should help the beginner get their feet wet.
37 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li>
38 <li><img alt="" src="../images/down.gif" /> <a href="#regex">Regular Expressions</a></li>
39 <li><img alt="" src="../images/down.gif" /> <a href="#rewriterule">RewriteRule Basics</a></li>
40 <li><img alt="" src="../images/down.gif" /> <a href="#flags">Rewrite Flags</a></li>
41 <li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">Rewrite Conditions</a></li>
42 <li><img alt="" src="../images/down.gif" /> <a href="#rewritemap">Rewrite maps</a></li>
43 <li><img alt="" src="../images/down.gif" /> <a href="#htaccess">.htaccess files</a></li>
44 </ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="rewritemap.html">Using RewriteMap</a></li><li><a href="advanced.html">Advanced techniques</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li><li><a href="#comments_section">Comments</a></li></ul></div>
45 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
47 <h2><a name="introduction" id="introduction">Introduction</a></h2>
48 <p>The Apache module <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> 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 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. For simple
61 tasks, see <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and the documentation
62 on <a href="../urlmapping.html">mapping URLs to the
65 <p>Finally, before proceeding, be sure to configure
66 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>'s log level to one of the trace levels using
67 the <code class="directive"><a href="../mod/core.html#loglevel">LogLevel</a></code> directive. Although this
68 can give an overwhelming amount of information, it is indispensable in
69 debugging problems with <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> configuration, since
70 it will tell you exactly how each rule is processed.</p>
72 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
74 <h2><a name="regex" id="regex">Regular Expressions</a></h2>
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 href="http://shop.oreilly.com/product/9780596528126.do">Mastering
82 Regular Expressions, by Jeffrey Friedl</a>.</p>
84 <p>In this document, we attempt to provide enough of a regex vocabulary
85 to get you started, without being overwhelming, in the hope that
86 <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s will be scientific
87 formulae, rather than magical incantations.</p>
89 <h3><a name="regexvocab" id="regexvocab">Regex vocabulary</a></h3>
91 <p>The following are the minimal building blocks you will need, in order
92 to write regular expressions and <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s. They certainly do not
93 represent a complete regular expression vocabulary, but they are a good
94 place to start, and should help you read basic regular expressions, as
95 well as write your own.</p>
104 <tr><td><code>.</code></td><td>Matches any single
105 character</td><td><code>c.t</code> will match <code>cat</code>,
106 <code>cot</code>, <code>cut</code>, etc.</td></tr>
107 <tr><td><code>+</code></td><td>Repeats the previous match one or more
108 times</td><td><code>a+</code> matches <code>a</code>, <code>aa</code>,
109 <code>aaa</code>, etc</td></tr>
110 <tr><td><code>*</code></td><td>Repeats the previous match zero or more
111 times.</td><td><code>a*</code> matches all the same things
112 <code>a+</code> matches, but will also match an empty string.</td></tr>
113 <tr><td><code>?</code></td><td>Makes the match optional.</td><td>
114 <code>colou?r</code> will match <code>color</code> and <code>colour</code>.</td>
116 <tr><td><code>^</code></td><td>Called an anchor, matches the beginning
117 of the string</td><td><code>^a</code> matches a string that begins with
118 <code>a</code></td></tr>
119 <tr><td><code>$</code></td><td>The other anchor, this matches the end of
120 the string.</td><td><code>a$</code> matches a string that ends with
121 <code>a</code>.</td></tr>
122 <tr><td><code>( )</code></td><td>Groups several characters into a single
123 unit, and captures a match for use in a backreference.</td><td><code>(ab)+</code>
124 matches <code>ababab</code> - that is, the <code>+</code> applies to the group.
125 For more on backreferences see <a href="#InternalBackRefs">below</a>.</td></tr>
126 <tr><td><code>[ ]</code></td><td>A character class - matches one of the
127 characters</td><td><code>c[uoa]t</code> matches <code>cut</code>,
128 <code>cot</code> or <code>cat</code>.</td></tr>
129 <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>
132 <p>In <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> the <code>!</code> character can be
133 used before a regular expression to negate it. This is, a string will
134 be considered to have matched only if it does not match the rest of
139 <h3><a name="InternalBackRefs" id="InternalBackRefs">Regex Back-Reference Availability</a></h3>
141 <p>One important thing here has to be remembered: Whenever you
142 use parentheses in <em>Pattern</em> or in one of the
143 <em>CondPattern</em>, back-references are internally created
144 which can be used with the strings <code>$N</code> and
145 <code>%N</code> (see below). These are available for creating
146 the <em>Substitution</em> parameter of a
147 <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or
148 the <em>TestString</em> parameter of a
149 <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>.</p>
150 <p> Captures in the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> patterns are (counterintuitively) available to
152 <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directives,
153 because the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>
154 expression is evaluated before the individual conditions.</p>
156 <p>Figure 1 shows to which
157 locations the back-references are transferred for expansion as
158 well as illustrating the flow of the RewriteRule, RewriteCond
159 matching. In the next chapters, we will be exploring how to use
160 these back-references, so do not fret if it seems a bit alien
165 <img src="../images/rewrite_backreferences.png" alt="Flow of RewriteRule and RewriteCond matching" /><br />
166 <dfn>Figure 1:</dfn> The back-reference flow through a rule.<br />
167 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>.
171 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
172 <div class="section">
173 <h2><a name="rewriterule" id="rewriterule">RewriteRule Basics</a></h2>
174 <p>A <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> consists
175 of three arguments separated by spaces. The arguments are</p>
177 <li><var>Pattern</var>: which incoming URLs should be affected by the rule;</li>
178 <li><var>Substitution</var>: where should the matching requests be sent;</li>
179 <li><var>[flags]</var>: options affecting the rewritten request.</li>
182 <p>The <var>Pattern</var> is a <a href="#regex">regular expression</a>.
183 It is initially (for the first rewrite rule or until a substitution occurs)
184 matched against the URL-path of the incoming request (the part after the
185 hostname but before any question mark indicating the beginning of a query
186 string) or, in per-directory context, against the request's path relative
187 to the directory for which the rule is defined. Once a substitution has
188 occurred, the rules that follow are matched against the substituted
193 <img src="../images/syntax_rewriterule.png" alt="Syntax of the RewriteRule directive" /><br />
194 <dfn>Figure 2:</dfn> Syntax of the RewriteRule directive.
198 <p>The <var>Substitution</var> can itself be one of three things:</p>
201 <dt>A full filesystem path to a resource</dt>
203 <pre class="prettyprint lang-config">RewriteRule "^/games" "/usr/local/games/web"</pre>
205 <p>This maps a request to an arbitrary location on your filesystem, much
206 like the <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> directive.</p>
209 <dt>A web-path to a resource</dt>
211 <pre class="prettyprint lang-config">RewriteRule "^/foo$" "/bar"</pre>
213 <p>If <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> is set
214 to <code>/usr/local/apache2/htdocs</code>, then this directive would
215 map requests for <code>http://example.com/foo</code> to the
216 path <code>/usr/local/apache2/htdocs/bar</code>.</p>
219 <dt>An absolute URL</dt>
221 <pre class="prettyprint lang-config">RewriteRule "^/product/view$" "http://site2.example.com/seeproduct.html" [R]</pre>
223 <p>This tells the client to make a new request for the specified URL.</p>
227 <p>The <var>Substitution</var> can also
228 contain <em>back-references</em> to parts of the incoming URL-path
229 matched by the <var>Pattern</var>. Consider the following:</p>
230 <pre class="prettyprint lang-config">RewriteRule "^/product/(.*)/view$" "/var/web/productdb/$1"</pre>
232 <p>The variable <code>$1</code> will be replaced with whatever text
233 was matched by the expression inside the parenthesis in
234 the <var>Pattern</var>. For example, a request
235 for <code>http://example.com/product/r14df/view</code> will be mapped
236 to the path <code>/var/web/productdb/r14df</code>.</p>
238 <p>If there is more than one expression in parenthesis, they are
239 available in order in the
240 variables <code>$1</code>, <code>$2</code>, <code>$3</code>, and so
244 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
245 <div class="section">
246 <h2><a name="flags" id="flags">Rewrite Flags</a></h2>
247 <p>The behavior of a <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> can be modified by the
248 application of one or more flags to the end of the rule. For example, the
249 matching behavior of a rule can be made case-insensitive by the
250 application of the <code>[NC]</code> flag:
252 <pre class="prettyprint lang-config">RewriteRule "^puppy.html" "smalldog.html" [NC]</pre>
255 <p>For more details on the available flags, their meanings, and
256 examples, see the <a href="flags.html">Rewrite Flags</a> document.</p>
258 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
259 <div class="section">
260 <h2><a name="rewritecond" id="rewritecond">Rewrite Conditions</a></h2>
261 <p>One or more <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>
262 directives can be used to restrict the types of requests that will be
264 following <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. The
265 first argument is a variable describing a characteristic of the
266 request, the second argument is a <a href="#regex">regular
267 expression</a> that must match the variable, and a third optional
268 argument is a list of flags that modify how the match is evaluated.</p>
271 <img src="../images/syntax_rewritecond.png" alt="Syntax of the RewriteCond directive" /><br />
272 <dfn>Figure 3:</dfn> Syntax of the RewriteCond directive
275 <p>For example, to send all requests from a particular IP range to a
276 different server, you could use:</p>
277 <pre class="prettyprint lang-config">RewriteCond "%{REMOTE_ADDR}" "^10\.2\."
278 RewriteRule "(.*)" "http://intranet.example.com$1"</pre>
282 one <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> is
283 specified, they must all match for
284 the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be
285 applied. For example, to deny requests that contain the word "hack" in
286 their query string, unless they also contain a cookie containing
287 the word "go", you could use:</p>
288 <pre class="prettyprint lang-config">RewriteCond "%{QUERY_STRING}" "hack"
289 RewriteCond "%{HTTP_COOKIE}" !go
290 RewriteRule "." "-" [F]</pre>
292 <p>Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".</p>
294 <p>Matches in the regular expressions contained in
295 the <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>s can be
296 used as part of the <var>Substitution</var> in
297 the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> using the
298 variables <code>%1</code>, <code>%2</code>, etc. For example, this
299 will direct the request to a different directory depending on the
300 hostname used to access the site:</p>
301 <pre class="prettyprint lang-config">RewriteCond "%{HTTP_HOST}" "(.*)"
302 RewriteRule "^/(.*)" "/sites/%1/$1"</pre>
304 <p>If the request was for <code>http://example.com/foo/bar</code>,
305 then <code>%1</code> would contain <code>example.com</code>
306 and <code>$1</code> would contain <code>foo/bar</code>.</p>
310 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
311 <div class="section">
312 <h2><a name="rewritemap" id="rewritemap">Rewrite maps</a></h2>
314 <p>The <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
315 provides a way to call an external function, so to speak, to do your
316 rewriting for you. This is discussed in greater detail in the <a href="rewritemap.html">RewriteMap supplementary documentation</a>.</p>
317 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
318 <div class="section">
319 <h2><a name="htaccess" id="htaccess">.htaccess files</a></h2>
321 <p>Rewriting is typically configured in the main server configuration
322 setting (outside any <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section) or
323 inside <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code>
324 containers. This is the easiest way to do rewriting and is
325 recommended. It is possible, however, to do rewriting
326 inside <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>
327 sections or <a href="../howto/htaccess.html"><code>.htaccess</code>
328 files</a> at the expense of some additional complexity. This technique
329 is called per-directory rewrites.</p>
331 <p>The main difference with per-server rewrites is that the path
332 prefix of the directory containing the <code>.htaccess</code> file is
333 stripped before matching in
334 the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. In addition, the <code class="directive"><a href="../mod/mod_rewrite.html#rewritebase">RewriteBase</a></code> should be used to assure the request is properly mapped.</p>
337 <div class="bottomlang">
338 <p><span>Available Languages: </span><a href="../en/rewrite/intro.html" title="English"> en </a> |
339 <a href="../fr/rewrite/intro.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
340 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
341 <script type="text/javascript"><!--//--><![CDATA[//><!--
342 var comments_shortname = 'httpd';
343 var comments_identifier = 'http://httpd.apache.org/docs/trunk/rewrite/intro.html';
345 if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
346 d.write('<div id="comments_thread"><\/div>');
347 var s = d.createElement('script');
348 s.type = 'text/javascript';
350 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
351 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
354 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
356 })(window, document);
357 //--><!]]></script></div><div id="footer">
358 <p class="apache">Copyright 2016 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>
359 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
360 if (typeof(prettyPrint) !== 'undefined') {