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.min.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.4</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.4</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<pre class="prettyprint lang-config">RewriteRule ^/games /usr/local/games/web</pre> 193 194<p>This maps a request to an arbitrary location on your filesystem, much 195like the <code class="directive"><a href="/mod/mod_alias.html#alias">Alias</a></code> directive.</p> 196</dd> 197 198<dt>A web-path to a resource</dt> 199<dd> 200<pre class="prettyprint lang-config">RewriteRule ^/foo$ /bar</pre> 201 202<p>If <code class="directive"><a href="/mod/core.html#documentroot">DocumentRoot</a></code> is set 203to <code>/usr/local/apache2/htdocs</code>, then this directive would 204map requests for <code>http://example.com/foo</code> to the 205path <code>/usr/local/apache2/htdocs/bar</code>.</p> 206</dd> 207 208<dt>An absolute URL</dt> 209<dd> 210<pre class="prettyprint lang-config">RewriteRule ^/product/view$ http://site2.example.com/seeproduct.html [R]</pre> 211 212<p>This tells the client to make a new request for the specified URL.</p> 213</dd> 214</dl> 215 216<p>The <var>Substitution</var> can also 217contain <em>back-references</em> to parts of the incoming URL-path 218matched by the <var>Pattern</var>. Consider the following:</p> 219<pre class="prettyprint lang-config">RewriteRule ^/product/(.*)/view$ /var/web/productdb/$1</pre> 220 221<p>The variable <code>$1</code> will be replaced with whatever text 222was matched by the expression inside the parenthesis in 223the <var>Pattern</var>. For example, a request 224for <code>http://example.com/product/r14df/view</code> will be mapped 225to the path <code>/var/web/productdb/r14df</code>.</p> 226 227<p>If there is more than one expression in parenthesis, they are 228available in order in the 229variables <code>$1</code>, <code>$2</code>, <code>$3</code>, and so 230on.</p> 231 232 233</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 234<div class="section"> 235<h2><a name="flags" id="flags">Rewrite Flags</a></h2> 236<p>The behavior of a <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> can be modified by the 237application of one or more flags to the end of the rule. For example, the 238matching behavior of a rule can be made case-insensitive by the 239application of the <code>[NC]</code> flag: 240</p> 241<pre class="prettyprint lang-config">RewriteRule ^puppy.html smalldog.html [NC]</pre> 242 243 244<p>For more details on the available flags, their meanings, and 245examples, see the <a href="flags.html">Rewrite Flags</a> document.</p> 246 247</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 248<div class="section"> 249<h2><a name="rewritecond" id="rewritecond">Rewrite Conditions</a></h2> 250<p>One or more <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> 251directives can be used to restrict the types of requests that will be 252subject to the 253following <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. The 254first argument is a variable describing a characteristic of the 255request, the second argument is a <a href="#regex">regular 256expression</a> that must match the variable, and a third optional 257argument is a list of flags that modify how the match is evaluated.</p> 258 259<p class="figure"> 260 <img src="/images/syntax_rewritecond.png" alt="Syntax of the RewriteCond directive" /><br /> 261 <dfn>Figure 3:</dfn> Syntax of the RewriteCond directive 262</p> 263 264<p>For example, to send all requests from a particular IP range to a 265different server, you could use:</p> 266<pre class="prettyprint lang-config">RewriteCond %{REMOTE_ADDR} ^10\.2\. 267RewriteRule (.*) http://intranet.example.com$1</pre> 268 269 270<p>When more than 271one <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> is 272specified, they must all match for 273the <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be 274applied. For example, to deny requests that contain the word "hack" in 275their query string, unless they also contain a cookie containing 276the word "go", you could use:</p> 277<pre class="prettyprint lang-config">RewriteCond %{QUERY_STRING} hack 278RewriteCond %{HTTP_COOKIE} !go 279RewriteRule . - [F]</pre> 280 281<p>Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".</p> 282 283<p>Matches in the regular expressions contained in 284the <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>s can be 285used as part of the <var>Substitution</var> in 286the <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> using the 287variables <code>%1</code>, <code>%2</code>, etc. For example, this 288will direct the request to a different directory depending on the 289hostname used to access the site:</p> 290<pre class="prettyprint lang-config">RewriteCond %{HTTP_HOST} (.*) 291RewriteRule ^/(.*) /sites/%1/$1</pre> 292 293<p>If the request was for <code>http://example.com/foo/bar</code>, 294then <code>%1</code> would contain <code>example.com</code> 295and <code>$1</code> would contain <code>foo/bar</code>.</p> 296 297 298 299</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 300<div class="section"> 301<h2><a name="rewritemap" id="rewritemap">Rewrite maps</a></h2> 302 303<p>The <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive 304provides a way to call an external function, so to speak, to do your 305rewriting for you. This is discussed in greater detail in the <a href="rewritemap.html">RewriteMap supplementary documentation</a>.</p> 306</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 307<div class="section"> 308<h2><a name="htaccess" id="htaccess">.htaccess files</a></h2> 309 310<p>Rewriting is typically configured in the main server configuration 311setting (outside any <code class="directive"><a href="/mod/core.html#directory"><Directory></a></code> section) or 312inside <code class="directive"><a href="/mod/core.html#virtualhost"><VirtualHost></a></code> 313containers. This is the easiest way to do rewriting and is 314recommended. It is possible, however, to do rewriting 315inside <code class="directive"><a href="/mod/core.html#directory"><Directory></a></code> 316sections or <a href="/howto/htaccess.html"><code>.htaccess</code> 317files</a> at the expense of some additional complexity. This technique 318is called per-directory rewrites.</p> 319 320<p>The main difference with per-server rewrites is that the path 321prefix of the directory containing the <code>.htaccess</code> file is 322stripped before matching in 323the <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> 324 325</div></div> 326<div class="bottomlang"> 327<p><span>Available Languages: </span><a href="/en/rewrite/intro.html" title="English"> en </a> | 328<a href="/fr/rewrite/intro.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p> 329</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> 330<script type="text/javascript"><!--//--><![CDATA[//><!-- 331var comments_shortname = 'httpd'; 332var comments_identifier = 'http://httpd.apache.org/docs/2.4/rewrite/intro.html'; 333(function(w, d) { 334 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 335 d.write('<div id="comments_thread"><\/div>'); 336 var s = d.createElement('script'); 337 s.type = 'text/javascript'; 338 s.async = true; 339 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 340 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 341 } 342 else { 343 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 344 } 345})(window, document); 346//--><!]]></script></div><div id="footer"> 347<p class="apache">Copyright 2014 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> 348<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[//><!-- 349if (typeof(prettyPrint) !== 'undefined') { 350 prettyPrint(); 351} 352//--><!]]></script> 353</body></html>