granicus.if.org Git - apache/blob - docs/manual/rewrite/intro.html.en

   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" />
   5 <!--
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7               This file is generated from xml source: DO NOT EDIT
   8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   9       -->
  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">
  15 </script>
  16
  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="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  23 <div id="path">
  24 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Introduction</h1>
  25 <div class="toplang">
  26 <p><span>Available Languages: </span><a href="../en/rewrite/intro.html" title="English">&nbsp;en&nbsp;</a> |
  27 <a href="../fr/rewrite/intro.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
  28 </div>
  29
  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.
  35 </p>
  36 </div>
  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>
  46 <div class="section">
  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>
  54
  55 <p>This document attempts to give sufficient background so that what
  56 follows is understood, rather than just copied blindly.
  57 </p>
  58
  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
  63 filesystem</a>.</p>
  64
  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>
  71
  72 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  73 <div class="section">
  74 <h2><a name="regex" id="regex">Regular Expressions</a></h2>
  75
  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>
  83
  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>
  88
  89 <h3><a name="regexvocab" id="regexvocab">Regex vocabulary</a></h3>
  90
  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>
  96
  97 <table>
  98 <tr>
  99 <th>Character</th>
 100 <th>Meaning</th>
 101 <th>Example</th>
 102 </tr>
 103
 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>
 115 </tr>
 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>
 130 </table>
 131
 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
 135 the expression.</p>
 136
 137
 138
 139 <h3><a name="InternalBackRefs" id="InternalBackRefs">Regex Back-Reference Availability</a></h3>
 140
 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
 151        all preceding
 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>
 155
 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
 161       to you at first.
 162       </p>
 163
 164 <p class="figure">
 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&amp;id=1234&amp;host=admin.example.com</code>.
 168 </p>
 169
 170
 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>
 176 <ol>
 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>
 180 </ol>
 181
 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
 189 value.
 190 </p>
 191
 192 <p class="figure">
 193       <img src="../images/syntax_rewriterule.png" alt="Syntax of the RewriteRule directive" /><br />
 194       <dfn>Figure 2:</dfn> Syntax of the RewriteRule directive.
 195 </p>
 196
 197
 198 <p>The <var>Substitution</var> can itself be one of three things:</p>
 199
 200 <dl>
 201 <dt>A full filesystem path to a resource</dt>
 202 <dd>
 203 <pre class="prettyprint lang-config">RewriteRule "^/games" "/usr/local/games/web"</pre>
 204
 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>
 207 </dd>
 208
 209 <dt>A web-path to a resource</dt>
 210 <dd>
 211 <pre class="prettyprint lang-config">RewriteRule "^/foo$" "/bar"</pre>
 212
 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>
 217 </dd>
 218
 219 <dt>An absolute URL</dt>
 220 <dd>
 221 <pre class="prettyprint lang-config">RewriteRule "^/product/view$" "http://site2.example.com/seeproduct.html" [R]</pre>
 222
 223 <p>This tells the client to make a new request for the specified URL.</p>
 224 </dd>
 225 </dl>
 226
 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>
 231
 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>
 237
 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
 241 on.</p>
 242
 243
 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:
 251 </p>
 252 <pre class="prettyprint lang-config">RewriteRule "^puppy.html" "smalldog.html" [NC]</pre>
 253
 254
 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>
 257
 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
 263 subject to the
 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>
 269
 270 <p class="figure">
 271       <img src="../images/syntax_rewritecond.png" alt="Syntax of the RewriteCond directive" /><br />
 272       <dfn>Figure 3:</dfn> Syntax of the RewriteCond directive
 273 </p>
 274
 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>
 279
 280
 281 <p>When more than
 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>
 291
 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>
 293
 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>
 303
 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>
 307
 308
 309
 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>
 313
 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>
 320
 321 <p>Rewriting is typically configured in the main server configuration
 322 setting (outside any <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> section) or
 323 inside <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</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">&lt;Directory&gt;</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>
 330
 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>
 335
 336 </div></div>
 337 <div class="bottomlang">
 338 <p><span>Available Languages: </span><a href="../en/rewrite/intro.html" title="English">&nbsp;en&nbsp;</a> |
 339 <a href="../fr/rewrite/intro.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</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&amp;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';
 344 (function(w, d) {
 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';
 349         s.async = true;
 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);
 352     }
 353     else {
 354         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 355     }
 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') {
 361     prettyPrint();
 362 }
 363 //--><!]]></script>
 364 </body></html>