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 7 --> 8<title>Apache mod_rewrite Introduction - 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" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body id="manual-page"><div id="page-header"> 17<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.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> 18<p class="apache">Apache HTTP Server Version 2.2</p> 19<img alt="" src="/images/feather.gif" /></div> 20<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 21<div id="path"> 22<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.2</a> > <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Introduction</h1> 23<div class="toplang"> 24<p><span>Available Languages: </span><a href="/en/rewrite/intro.html" title="English"> en </a> | 25<a href="/fr/rewrite/intro.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p> 26</div> 27 28<p>This document supplements the <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> 29<a href="/mod/mod_rewrite.html">reference documentation</a>. It 30describes the basic concepts necessary for use of 31<code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>. Other documents go into greater detail, 32but this doc should help the beginner get their feet wet. 33</p> 34</div> 35<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li> 36<li><img alt="" src="/images/down.gif" /> <a href="#regex">Regular Expressions</a></li> 37<li><img alt="" src="/images/down.gif" /> <a href="#rewriterule">RewriteRule Basics</a></li> 38<li><img alt="" src="/images/down.gif" /> <a href="#flags">Rewrite Flags</a></li> 39<li><img alt="" src="/images/down.gif" /> <a href="#rewritecond">Rewrite Conditions</a></li> 40<li><img alt="" src="/images/down.gif" /> <a href="#rewritemap">Rewrite maps</a></li> 41<li><img alt="" src="/images/down.gif" /> <a href="#htaccess">.htaccess files</a></li> 42</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></ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 43<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 44<div class="section"> 45<h2><a name="introduction" id="introduction">Introduction</a></h2> 46<p>The Apache module <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> is a very powerful and 47sophisticated module which provides a way to do URL manipulations. With 48it, you can do nearly all types of URL rewriting that you may need. It 49is, however, somewhat complex, and may be intimidating to the beginner. 50There is also a tendency to treat rewrite rules as magic incantation, 51using them without actually understanding what they do.</p> 52 53<p>This document attempts to give sufficient background so that what 54follows is understood, rather than just copied blindly. 55</p> 56 57<p>Remember that many common URL-manipulation tasks don't require the 58full power and complexity of <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>. For simple 59tasks, see <code class="module"><a href="/mod/mod_alias.html">mod_alias</a></code> and the documentation 60on <a href="/urlmapping.html">mapping URLs to the 61filesystem</a>.</p> 62 63<p>Finally, before proceeding, be sure to configure 64<code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>'s log level to one of the trace levels using 65the <code class="directive"><a href="/mod/core.html#loglevel">LogLevel</a></code> directive. Although this 66can give an overwhelming amount of information, it is indispensable in 67debugging problems with <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> configuration, since 68it will tell you exactly how each rule is processed.</p> 69 70</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 71<div class="section"> 72<h2><a name="regex" id="regex">Regular Expressions</a></h2> 73 74<p>mod_rewrite uses the <a href="http://pcre.org/">Perl Compatible 75Regular Expression</a> vocabulary. In this document, we do not attempt 76to provide a detailed reference to regular expressions. For that, we 77recommend the <a href="http://pcre.org/pcre.txt">PCRE man pages</a>, the 78<a href="http://perldoc.perl.org/perlre.html">Perl regular 79expression man page</a>, and <a href="http://shop.oreilly.com/product/9780596528126.do">Mastering 80Regular Expressions, by Jeffrey Friedl</a>.</p> 81 82<p>In this document, we attempt to provide enough of a regex vocabulary 83to get you started, without being overwhelming, in the hope that 84<code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s will be scientific 85formulae, rather than magical incantations.</p> 86 87<h3><a name="regexvocab" id="regexvocab">Regex vocabulary</a></h3> 88 89<p>The following are the minimal building blocks you will need, in order 90to write regular expressions and <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s. They certainly do not 91represent a complete regular expression vocabulary, but they are a good 92place to start, and should help you read basic regular expressions, as 93well as write your own.</p> 94 95<table> 96<tr> 97<th>Character</th> 98<th>Meaning</th> 99<th>Example</th> 100</tr> 101 102<tr><td><code>.</code></td><td>Matches any single 103character</td><td><code>c.t</code> will match <code>cat</code>, 104<code>cot</code>, <code>cut</code>, etc.</td></tr> 105<tr><td><code>+</code></td><td>Repeats the previous match one or more 106times</td><td><code>a+</code> matches <code>a</code>, <code>aa</code>, 107<code>aaa</code>, etc</td></tr> 108<tr><td><code>*</code></td><td>Repeats the previous match zero or more 109times.</td><td><code>a*</code> matches all the same things 110<code>a+</code> matches, but will also match an empty string.</td></tr> 111<tr><td><code>?</code></td><td>Makes the match optional.</td><td> 112<code>colou?r</code> will match <code>color</code> and <code>colour</code>.</td> 113</tr> 114<tr><td><code>^</code></td><td>Called an anchor, matches the beginning 115of the string</td><td><code>^a</code> matches a string that begins with 116<code>a</code></td></tr> 117<tr><td><code>$</code></td><td>The other anchor, this matches the end of 118the string.</td><td><code>a$</code> matches a string that ends with 119<code>a</code>.</td></tr> 120<tr><td><code>( )</code></td><td>Groups several characters into a single 121unit, and captures a match for use in a backreference.</td><td><code>(ab)+</code> 122matches <code>ababab</code> - that is, the <code>+</code> applies to the group. 123For more on backreferences see <a href="#InternalBackRefs">below</a>.</td></tr> 124<tr><td><code>[ ]</code></td><td>A character class - matches one of the 125characters</td><td><code>c[uoa]t</code> matches <code>cut</code>, 126<code>cot</code> or <code>cat</code>.</td></tr> 127<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> 128</table> 129 130<p>In <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> the <code>!</code> character can be 131used before a regular expression to negate it. This is, a string will 132be considered to have matched only if it does not match the rest of 133the expression.</p> 134 135 136 137<h3><a name="InternalBackRefs" id="InternalBackRefs">Regex Back-Reference Availability</a></h3> 138 139 <p>One important thing here has to be remembered: Whenever you 140 use parentheses in <em>Pattern</em> or in one of the 141 <em>CondPattern</em>, back-references are internally created 142 which can be used with the strings <code>$N</code> and 143 <code>%N</code> (see below). These are available for creating 144 the strings <em>Substitution</em> and <em>TestString</em> as 145 outlined in the following chapters. Figure 1 shows to which 146 locations the back-references are transferred for expansion as 147 well as illustrating the flow of the RewriteRule, RewriteCond 148 matching. In the next chapters, we will be exploring how to use 149 these back-references, so do not fret if it seems a bit alien 150 to you at first. 151 </p> 152 153<p class="figure"> 154 <img src="/images/rewrite_backreferences.png" alt="Flow of RewriteRule and RewriteCond matching" /><br /> 155 <dfn>Figure 1:</dfn> The back-reference flow through a rule.<br /> 156 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>. 157</p> 158 159 160</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 161<div class="section"> 162<h2><a name="rewriterule" id="rewriterule">RewriteRule Basics</a></h2> 163<p>A <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> consists 164of three arguments separated by spaces. The arguments are</p> 165<ol> 166<li><var>Pattern</var>: which incoming URLs should be affected by the rule;</li> 167<li><var>Substitution</var>: where should the matching requests be sent;</li> 168<li><var>[flags]</var>: options affecting the rewritten request.</li> 169</ol> 170 171<p>The <var>Pattern</var> is a <a href="#regex">regular expression</a>. 172It is initially (for the first rewrite rule or until a substitution occurs) 173matched against the URL-path of the incoming request (the part after the 174hostname but before any question mark indicating the beginning of a query 175string) or, in per-directory context, against the request's path relative 176to the directory for which the rule is defined. Once a substitution has 177occurred, the rules that follow are matched against the substituted 178value. 179</p> 180 181<p class="figure"> 182 <img src="/images/syntax_rewriterule.png" alt="Syntax of the RewriteRule directive" /><br /> 183 <dfn>Figure 2:</dfn> Syntax of the RewriteRule directive. 184</p> 185 186 187<p>The <var>Substitution</var> can itself be one of three things:</p> 188 189<dl> 190<dt>A full filesystem path to a resource</dt> 191<dd> 192<div class="example"><p><code> 193RewriteRule ^/games.* /usr/local/games/web 194</code></p></div> 195<p>This maps a request to an arbitrary location on your filesystem, much 196like the <code class="directive"><a href="/mod/mod_alias.html#alias">Alias</a></code> directive.</p> 197</dd> 198 199<dt>A web-path to a resource</dt> 200<dd> 201<div class="example"><p><code> 202RewriteRule ^/foo$ /bar 203</code></p></div> 204<p>If <code class="directive"><a href="/mod/core.html#documentroot">DocumentRoot</a></code> is set 205to <code>/usr/local/apache2/htdocs</code>, then this directive would 206map requests for <code>http://example.com/foo</code> to the 207path <code>/usr/local/apache2/htdocs/bar</code>.</p> 208</dd> 209 210<dt>An absolute URL</dt> 211<dd> 212<div class="example"><p><code> 213RewriteRule ^/product/view$ http://site2.example.com/seeproduct.html [R] 214</code></p></div> 215<p>This tells the client to make a new request for the specified URL.</p> 216</dd> 217</dl> 218 219<p>The <var>Substitution</var> can also 220contain <em>back-references</em> to parts of the incoming URL-path 221matched by the <var>Pattern</var>. Consider the following:</p> 222<div class="example"><p><code> 223RewriteRule ^/product/(.*)/view$ /var/web/productdb/$1 224</code></p></div> 225<p>The variable <code>$1</code> will be replaced with whatever text 226was matched by the expression inside the parenthesis in 227the <var>Pattern</var>. For example, a request 228for <code>http://example.com/product/r14df/view</code> will be mapped 229to the path <code>/var/web/productdb/r14df</code>.</p> 230 231<p>If there is more than one expression in parenthesis, they are 232available in order in the 233variables <code>$1</code>, <code>$2</code>, <code>$3</code>, and so 234on.</p> 235 236 237</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 238<div class="section"> 239<h2><a name="flags" id="flags">Rewrite Flags</a></h2> 240<p>The behavior of a <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> can be modified by the 241application of one or more flags to the end of the rule. For example, the 242matching behavior of a rule can be made case-insensitive by the 243application of the <code>[NC]</code> flag: 244</p> 245<div class="example"><p><code> 246RewriteRule ^puppy.html smalldog.html [NC] 247</code></p></div> 248 249<p>For more details on the available flags, their meanings, and 250examples, see the <a href="flags.html">Rewrite Flags</a> document.</p> 251 252</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 253<div class="section"> 254<h2><a name="rewritecond" id="rewritecond">Rewrite Conditions</a></h2> 255<p>One or more <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> 256directives can be used to restrict the types of requests that will be 257subject to the 258following <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. The 259first argument is a variable describing a characteristic of the 260request, the second argument is a <a href="#regex">regular 261expression</a> that must match the variable, and a third optional 262argument is a list of flags that modify how the match is evaluated.</p> 263 264<p class="figure"> 265 <img src="/images/syntax_rewritecond.png" alt="Syntax of the RewriteCond directive" /><br /> 266 <dfn>Figure 3:</dfn> Syntax of the RewriteCond directive 267</p> 268 269<p>For example, to send all requests from a particular IP range to a 270different server, you could use:</p> 271<div class="example"><p><code> 272RewriteCond %{REMOTE_ADDR} ^10\.2\.<br /> 273RewriteRule (.*) http://intranet.example.com$1 274</code></p></div> 275 276<p>When more than 277one <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> is 278specified, they must all match for 279the <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be 280applied. For example, to deny requests that contain the word "hack" in 281their query string, unless they also contain a cookie containing 282the word "go", you could use:</p> 283<div class="example"><p><code> 284RewriteCond %{QUERY_STRING} hack<br /> 285RewriteCond %{HTTP_COOKIE} !go<br /> 286RewriteRule .* - [F] 287</code></p></div> 288<p>Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".</p> 289 290<p>Matches in the regular expressions contained in 291the <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>s can be 292used as part of the <var>Substitution</var> in 293the <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> using the 294variables <code>%1</code>, <code>%2</code>, etc. For example, this 295will direct the request to a different directory depending on the 296hostname used to access the site:</p> 297<div class="example"><p><code> 298RewriteCond %{HTTP_HOST} (.*)<br /> 299RewriteRule ^/(.*) /sites/%1/$1 300</code></p></div> 301<p>If the request was for <code>http://example.com/foo/bar</code>, 302then <code>%1</code> would contain <code>example.com</code> 303and <code>$1</code> would contain <code>foo/bar</code>.</p> 304 305 306 307</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 308<div class="section"> 309<h2><a name="rewritemap" id="rewritemap">Rewrite maps</a></h2> 310 311<p>The <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive 312provides a way to call an external function, so to speak, to do your 313rewriting for you. This is discussed in greater detail in the <a href="rewritemap.html">RewriteMap supplementary documentation</a>.</p> 314</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 315<div class="section"> 316<h2><a name="htaccess" id="htaccess">.htaccess files</a></h2> 317 318<p>Rewriting is typically configured in the main server configuration 319setting (outside any <code class="directive"><a href="/mod/core.html#directory"><Directory></a></code> section) or 320inside <code class="directive"><a href="/mod/core.html#virtualhost"><VirtualHost></a></code> 321containers. This is the easiest way to do rewriting and is 322recommended. It is possible, however, to do rewriting 323inside <code class="directive"><a href="/mod/core.html#directory"><Directory></a></code> 324sections or <a href="/howto/htaccess.html"><code>.htaccess</code> 325files</a> at the expense of some additional complexity. This technique 326is called per-directory rewrites.</p> 327 328<p>The main difference with per-server rewrites is that the path 329prefix of the directory containing the <code>.htaccess</code> file is 330stripped before matching in 331the <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> 332 333</div></div> 334<div class="bottomlang"> 335<p><span>Available Languages: </span><a href="/en/rewrite/intro.html" title="English"> en </a> | 336<a href="/fr/rewrite/intro.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p> 337</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> 338<script type="text/javascript"><!--//--><![CDATA[//><!-- 339var comments_shortname = 'httpd'; 340var comments_identifier = 'http://httpd.apache.org/docs/2.2/rewrite/intro.html'; 341(function(w, d) { 342 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 343 d.write('<div id="comments_thread"><\/div>'); 344 var s = d.createElement('script'); 345 s.type = 'text/javascript'; 346 s.async = true; 347 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 348 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 349 } 350 else { 351 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 352 } 353})(window, document); 354//--><!]]></script></div><div id="footer"> 355<p class="apache">Copyright 2013 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> 356<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.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[//><!-- 357if (typeof(prettyPrint) !== 'undefined') { 358 prettyPrint(); 359} 360//--><!]]></script> 361</body></html>