| <?xml version='1.0' encoding='UTF-8' ?> |
| <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <manualpage metafile="intro.xml.meta"> |
| <parentdocument href="./">Rewrite</parentdocument> |
| |
| <title>Apache mod_rewrite Introduction</title> |
| |
| <summary> |
| <p>This document supplements the <module>mod_rewrite</module> |
| <a href="../mod/mod_rewrite.html">reference documentation</a>. It |
| describes the basic concepts necessary for use of |
| <module>mod_rewrite</module>. Other documents go into greater detail, |
| but this doc should help the beginner get their feet wet. |
| </p> |
| </summary> |
| |
| <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso> |
| <!-- <seealso><a href="intro.html">mod_rewrite introduction</a></seealso> --> |
| <seealso><a href="remapping.html">Redirection and remapping</a></seealso> |
| <seealso><a href="access.html">Controlling access</a></seealso> |
| <seealso><a href="vhosts.html">Virtual hosts</a></seealso> |
| <seealso><a href="proxy.html">Proxying</a></seealso> |
| <seealso><a href="rewritemap.html">Using RewriteMap</a></seealso> |
| <seealso><a href="advanced.html">Advanced techniques</a></seealso> |
| <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso> |
| |
| <section id="introduction"><title>Introduction</title> |
| <p>The Apache module <module>mod_rewrite</module> is a very powerful and |
| sophisticated module which provides a way to do URL manipulations. With |
| it, you can do nearly all types of URL rewriting that you may need. It |
| is, however, somewhat complex, and may be intimidating to the beginner. |
| There is also a tendency to treat rewrite rules as magic incantation, |
| using them without actually understanding what they do.</p> |
| |
| <p>This document attempts to give sufficient background so that what |
| follows is understood, rather than just copied blindly. |
| </p> |
| |
| <p>Remember that many common URL-manipulation tasks don't require the |
| full power and complexity of <module>mod_rewrite</module>. For simple |
| tasks, see <module>mod_alias</module> and the documentation |
| on <a href="../urlmapping.html">mapping URLs to the |
| filesystem</a>.</p> |
| |
| <p>Finally, before proceeding, be sure to configure |
| <module>mod_rewrite</module>'s log level to one of the trace levels using |
| the <directive module="core">LogLevel</directive> directive. Although this |
| can give an overwhelming amount of information, it is indispensable in |
| debugging problems with <module>mod_rewrite</module> configuration, since |
| it will tell you exactly how each rule is processed.</p> |
| |
| </section> |
| |
| <section id="regex"><title>Regular Expressions</title> |
| |
| <p>mod_rewrite uses the <a href="http://pcre.org/">Perl Compatible |
| Regular Expression</a> vocabulary. In this document, we do not attempt |
| to provide a detailed reference to regular expressions. For that, we |
| recommend the <a href="http://pcre.org/pcre.txt">PCRE man pages</a>, the |
| <a href="http://perldoc.perl.org/perlre.html">Perl regular |
| expression man page</a>, and <a |
| href="http://shop.oreilly.com/product/9780596528126.do">Mastering |
| Regular Expressions, by Jeffrey Friedl</a>.</p> |
| |
| <p>In this document, we attempt to provide enough of a regex vocabulary |
| to get you started, without being overwhelming, in the hope that |
| <directive module="mod_rewrite">RewriteRule</directive>s will be scientific |
| formulae, rather than magical incantations.</p> |
| |
| <section id="regexvocab"><title>Regex vocabulary</title> |
| |
| <p>The following are the minimal building blocks you will need, in order |
| to write regular expressions and <directive |
| module="mod_rewrite">RewriteRule</directive>s. They certainly do not |
| represent a complete regular expression vocabulary, but they are a good |
| place to start, and should help you read basic regular expressions, as |
| well as write your own.</p> |
| |
| <table> |
| <tr> |
| <th>Character</th> |
| <th>Meaning</th> |
| <th>Example</th> |
| </tr> |
| |
| <tr><td><code>.</code></td><td>Matches any single |
| character</td><td><code>c.t</code> will match <code>cat</code>, |
| <code>cot</code>, <code>cut</code>, etc.</td></tr> |
| <tr><td><code>+</code></td><td>Repeats the previous match one or more |
| times</td><td><code>a+</code> matches <code>a</code>, <code>aa</code>, |
| <code>aaa</code>, etc</td></tr> |
| <tr><td><code>*</code></td><td>Repeats the previous match zero or more |
| times.</td><td><code>a*</code> matches all the same things |
| <code>a+</code> matches, but will also match an empty string.</td></tr> |
| <tr><td><code>?</code></td><td>Makes the match optional.</td><td> |
| <code>colou?r</code> will match <code>color</code> and <code>colour</code>.</td> |
| </tr> |
| <tr><td><code>^</code></td><td>Called an anchor, matches the beginning |
| of the string</td><td><code>^a</code> matches a string that begins with |
| <code>a</code></td></tr> |
| <tr><td><code>$</code></td><td>The other anchor, this matches the end of |
| the string.</td><td><code>a$</code> matches a string that ends with |
| <code>a</code>.</td></tr> |
| <tr><td><code>( )</code></td><td>Groups several characters into a single |
| unit, and captures a match for use in a backreference.</td><td><code>(ab)+</code> |
| matches <code>ababab</code> - that is, the <code>+</code> applies to the group. |
| For more on backreferences see <a href="#InternalBackRefs">below</a>.</td></tr> |
| <tr><td><code>[ ]</code></td><td>A character class - matches one of the |
| characters</td><td><code>c[uoa]t</code> matches <code>cut</code>, |
| <code>cot</code> or <code>cat</code>.</td></tr> |
| <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> |
| </table> |
| |
| <p>In <module>mod_rewrite</module> the <code>!</code> character can be |
| used before a regular expression to negate it. This is, a string will |
| be considered to have matched only if it does not match the rest of |
| the expression.</p> |
| |
| </section> |
| |
| <section id="InternalBackRefs"><title>Regex Back-Reference Availability</title> |
| |
| <p>One important thing here has to be remembered: Whenever you |
| use parentheses in <em>Pattern</em> or in one of the |
| <em>CondPattern</em>, back-references are internally created |
| which can be used with the strings <code>$N</code> and |
| <code>%N</code> (see below). These are available for creating |
| the strings <em>Substitution</em> and <em>TestString</em> as |
| outlined in the following chapters. Figure 1 shows to which |
| locations the back-references are transferred for expansion as |
| well as illustrating the flow of the RewriteRule, RewriteCond |
| matching. In the next chapters, we will be exploring how to use |
| these back-references, so do not fret if it seems a bit alien |
| to you at first. |
| </p> |
| |
| <p class="figure"> |
| <img src="../images/rewrite_backreferences.png" |
| alt="Flow of RewriteRule and RewriteCond matching" /><br /> |
| <dfn>Figure 1:</dfn> The back-reference flow through a rule.<br /> |
| 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>. |
| </p> |
| |
| </section> |
| </section> |
| |
| <section id="rewriterule"><title>RewriteRule Basics</title> |
| <p>A <directive module="mod_rewrite">RewriteRule</directive> consists |
| of three arguments separated by spaces. The arguments are</p> |
| <ol> |
| <li><var>Pattern</var>: which incoming URLs should be affected by the rule;</li> |
| <li><var>Substitution</var>: where should the matching requests be sent;</li> |
| <li><var>[flags]</var>: options affecting the rewritten request.</li> |
| </ol> |
| |
| <p>The <var>Pattern</var> is a <a href="#regex">regular expression</a>. |
| It is initially (for the first rewrite rule or until a substitution occurs) |
| matched against the URL-path of the incoming request (the part after the |
| hostname but before any question mark indicating the beginning of a query |
| string) or, in per-directory context, against the request's path relative |
| to the directory for which the rule is defined. Once a substitution has |
| occurred, the rules that follow are matched against the substituted |
| value. |
| </p> |
| |
| <p class="figure"> |
| <img src="../images/syntax_rewriterule.png" |
| alt="Syntax of the RewriteRule directive" /><br /> |
| <dfn>Figure 2:</dfn> Syntax of the RewriteRule directive. |
| </p> |
| |
| |
| <p>The <var>Substitution</var> can itself be one of three things:</p> |
| |
| <dl> |
| <dt>1. A full filesystem path to a resource</dt> |
| <dd> |
| <highlight language="config"> |
| RewriteRule "^/games" "/usr/local/games/web/puzzles.html" |
| </highlight> |
| <p>This maps a request to an arbitrary location on your filesystem, much |
| like the <directive module="mod_alias">Alias</directive> directive.</p> |
| </dd> |
| |
| <dt>2. A web-path to a resource</dt> |
| <dd> |
| <highlight language="config"> |
| RewriteRule "^/games$" "/puzzles.html" |
| </highlight> |
| <p>If <directive module="core">DocumentRoot</directive> is set |
| to <code>/usr/local/apache2/htdocs</code>, then this directive would |
| map requests for <code>http://example.com/games</code> to the |
| path <code>/usr/local/apache2/htdocs/puzzles.html</code>.</p> |
| |
| </dd> |
| |
| <dt>3. An absolute URL</dt> |
| <dd> |
| <example> |
| RewriteRule ^/product/view$ http://site2.example.com/seeproduct.html [R] |
| </example> |
| <p>This tells the client to make a new request for the specified URL.</p> |
| </dd> |
| </dl> |
| |
| <note type="warning">Note that <strong>1</strong> and <strong>2</strong> have exactly the same syntax. The difference between them is that in the case of <strong>1</strong>, the top level of the target path (i.e., <code>/usr/</code>) exists on the filesystem, where as in the case of <strong>2</strong>, it does not. (i.e., there's no <code>/bar/</code> as a root-level directory in the filesystem.)</note> |
| |
| <p>The <var>Substitution</var> can also |
| contain <em>back-references</em> to parts of the incoming URL-path |
| matched by the <var>Pattern</var>. Consider the following:</p> |
| <example> |
| RewriteRule ^/product/(.*)/view$ /var/web/productdb/$1 |
| </example> |
| <p>The variable <code>$1</code> will be replaced with whatever text |
| was matched by the expression inside the parenthesis in |
| the <var>Pattern</var>. For example, a request |
| for <code>http://example.com/product/r14df/view</code> will be mapped |
| to the path <code>/var/web/productdb/r14df</code>.</p> |
| |
| <p>If there is more than one expression in parenthesis, they are |
| available in order in the |
| variables <code>$1</code>, <code>$2</code>, <code>$3</code>, and so |
| on.</p> |
| |
| |
| </section> |
| |
| <section id="flags"><title>Rewrite Flags</title> |
| <p>The behavior of a <directive |
| module="mod_rewrite">RewriteRule</directive> can be modified by the |
| application of one or more flags to the end of the rule. For example, the |
| matching behavior of a rule can be made case-insensitive by the |
| application of the <code>[NC]</code> flag: |
| </p> |
| <example> |
| RewriteRule ^puppy.html smalldog.html [NC] |
| </example> |
| |
| <p>For more details on the available flags, their meanings, and |
| examples, see the <a href="flags.html">Rewrite Flags</a> document.</p> |
| |
| </section> |
| |
| |
| <section id="rewritecond"><title>Rewrite Conditions</title> |
| <p>One or more <directive module="mod_rewrite">RewriteCond</directive> |
| directives can be used to restrict the types of requests that will be |
| subject to the |
| following <directive module="mod_rewrite">RewriteRule</directive>. The |
| first argument is a variable describing a characteristic of the |
| request, the second argument is a <a href="#regex">regular |
| expression</a> that must match the variable, and a third optional |
| argument is a list of flags that modify how the match is evaluated.</p> |
| |
| <p class="figure"> |
| <img src="../images/syntax_rewritecond.png" |
| alt="Syntax of the RewriteCond directive" /><br /> |
| <dfn>Figure 3:</dfn> Syntax of the RewriteCond directive |
| </p> |
| |
| <p>For example, to send all requests from a particular IP range to a |
| different server, you could use:</p> |
| <example> |
| RewriteCond %{REMOTE_ADDR} ^10\.2\.<br /> |
| RewriteRule (.*) http://intranet.example.com$1 |
| </example> |
| |
| <p>When more than |
| one <directive module="mod_rewrite">RewriteCond</directive> is |
| specified, they must all match for |
| the <directive module="mod_rewrite">RewriteRule</directive> to be |
| applied. For example, to deny requests that contain the word "hack" in |
| their query string, unless they also contain a cookie containing |
| the word "go", you could use:</p> |
| <example> |
| RewriteCond %{QUERY_STRING} hack<br /> |
| RewriteCond %{HTTP_COOKIE} !go<br /> |
| RewriteRule .* - [F] |
| </example> |
| <p>Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".</p> |
| |
| <p>Matches in the regular expressions contained in |
| the <directive module="mod_rewrite">RewriteCond</directive>s can be |
| used as part of the <var>Substitution</var> in |
| the <directive module="mod_rewrite">RewriteRule</directive> using the |
| variables <code>%1</code>, <code>%2</code>, etc. For example, this |
| will direct the request to a different directory depending on the |
| hostname used to access the site:</p> |
| <example> |
| RewriteCond %{HTTP_HOST} (.*)<br /> |
| RewriteRule ^/(.*) /sites/%1/$1 |
| </example> |
| <p>If the request was for <code>http://example.com/foo/bar</code>, |
| then <code>%1</code> would contain <code>example.com</code> |
| and <code>$1</code> would contain <code>foo/bar</code>.</p> |
| |
| |
| |
| </section> |
| |
| <section id="rewritemap"><title>Rewrite maps</title> |
| |
| <p>The <directive module="mod_rewrite">RewriteMap</directive> directive |
| provides a way to call an external function, so to speak, to do your |
| rewriting for you. This is discussed in greater detail in the <a |
| href="rewritemap.html">RewriteMap supplementary documentation</a>.</p> |
| </section> |
| |
| <section id="htaccess"><title>.htaccess files</title> |
| |
| <p>Rewriting is typically configured in the main server configuration |
| setting (outside any <directive type="section" |
| module="core">Directory</directive> section) or |
| inside <directive type="section" module="core">VirtualHost</directive> |
| containers. This is the easiest way to do rewriting and is |
| recommended. It is possible, however, to do rewriting |
| inside <directive type="section" module="core">Directory</directive> |
| sections or <a href="../howto/htaccess.html"><code>.htaccess</code> |
| files</a> at the expense of some additional complexity. This technique |
| is called per-directory rewrites.</p> |
| |
| <p>The main difference with per-server rewrites is that the path |
| prefix of the directory containing the <code>.htaccess</code> file is |
| stripped before matching in |
| 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> |
| |
| </section> |
| |
| </manualpage> |
| |
| |