granicus.if.org Git - apache/blob - docs/manual/rewrite/tech.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 Technical Details - 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 Technical Details</h1>
  25 <div class="toplang">
  26 <p><span>Available Languages: </span><a href="../en/rewrite/tech.html" title="English">&nbsp;en&nbsp;</a> |
  27 <a href="../fr/rewrite/tech.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
  28 </div>
  29
  30 <p>This document discusses some of the technical details of mod_rewrite
  31 and URL matching.</p>
  32 </div>
  33 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#InternalAPI">API Phases</a></li>
  34 <li><img alt="" src="../images/down.gif" /> <a href="#InternalRuleset">Ruleset Processing</a></li>
  35 </ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</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>
  36 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  37 <div class="section">
  38 <h2><a name="InternalAPI" id="InternalAPI">API Phases</a></h2>
  39
  40     <p>The Apache HTTP Server handles requests in several phases. At
  41     each of these phases, one or more modules may be called upon to
  42     handle that portion of the request lifecycle. Phases include things
  43     like URL-to-filename translation, authentication, authorization,
  44     content, and logging. (This is not an exhaustive list.)</p>
  45
  46     <p>mod_rewrite acts in two of these phases (or "hooks", as they are
  47     often called) to influence how URLs may be rewritten.</p>
  48
  49     <p>First, it uses the URL-to-filename translation hook, which occurs
  50     after the HTTP request has been read, but before any authorization
  51     starts. Secondly, it uses the Fixup hook, which is after the
  52     authorization phases, and after per-directory configuration files
  53     (<code>.htaccess</code> files) have been read, but before the
  54     content handler is called.</p>
  55
  56     <p>After a request comes in and a corresponding server or
  57     virtual host has been determined, the rewriting engine starts
  58     processing any <code>mod_rewrite</code> directives appearing in the
  59     per-server configuration. (i.e., in the main server configuration file
  60     and <code class="directive"><a href="../mod/core.html#virtualhost">&lt;Virtualhost&gt;</a></code>
  61     sections.) This happens in the URL-to-filename phase.</p>
  62
  63     <p>A few steps later, once the final data directories have been found,
  64     the per-directory configuration directives (<code>.htaccess</code>
  65     files and <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> blocks) are applied. This
  66     happens in the Fixup phase.</p>
  67
  68     <p>In each of these cases, mod_rewrite rewrites the
  69     <code>REQUEST_URI</code> either to a new URL, or to a filename.</p>
  70
  71     <p>In per-directory context (i.e., within <code>.htaccess</code> files
  72     and <code>Directory</code> blocks), these rules are being applied
  73     after a URL has already been translated to a filename. Because of
  74     this, the URL-path that mod_rewrite initially compares <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives against
  75     is the full filesystem path to the translated filename with the current
  76     directories path (including a trailing slash) removed from the front.</p>
  77
  78     <p> To illustrate: If rules are in /var/www/foo/.htaccess and a request
  79     for /foo/bar/baz is being processed, an expression like ^bar/baz$ would
  80     match.</p>
  81
  82     <p> If a substitution is made in per-directory context, a new internal
  83     subrequest is issued with the new URL, which restarts processing of the
  84     request phases. If the substitution is a relative path, the <code class="directive"><a href="../mod/mod_rewrite.html#rewritebase">RewriteBase</a></code> directive
  85     determines the URL-path prefix prepended to the substitution.
  86     In per-directory context, care must be taken to
  87     create rules which will eventually (in some future "round" of per-directory
  88     rewrite processing) not perform a substitution to avoid looping.
  89     (See <a href="http://wiki.apache.org/httpd/RewriteLooping">RewriteLooping</a>
  90     for further discussion of this problem.)</p>
  91
  92     <p>Because of this further manipulation of the URL in per-directory
  93     context, you'll need to take care to craft your rewrite rules
  94     differently in that context. In particular, remember that the
  95     leading directory path will be stripped off of the URL that your
  96     rewrite rules will see. Consider the examples below for further
  97     clarification.</p>
  98
  99     <table class="bordered">
 100
 101         <tr>
 102             <th>Location of rule</th>
 103             <th>Rule</th>
 104         </tr>
 105
 106         <tr>
 107             <td>VirtualHost section</td>
 108             <td>RewriteRule "^/images/(.+)\.jpg" "/images/$1.gif"</td>
 109         </tr>
 110
 111         <tr>
 112             <td>.htaccess file in document root</td>
 113             <td>RewriteRule "^images/(.+)\.jpg" "images/$1.gif"</td>
 114         </tr>
 115
 116         <tr>
 117             <td>.htaccess file in images directory</td>
 118             <td>RewriteRule "^(.+)\.jpg" "$1.gif"</td>
 119         </tr>
 120
 121     </table>
 122
 123     <p>For even more insight into how mod_rewrite manipulates URLs in
 124     different contexts, you should consult the <a href="../mod/mod_rewrite.html#logging">log entries</a> made during
 125     rewriting.</p>
 126
 127 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 128 <div class="section">
 129 <h2><a name="InternalRuleset" id="InternalRuleset">Ruleset Processing</a></h2>
 130
 131       <p>Now when mod_rewrite is triggered in these two API phases, it
 132       reads the configured rulesets from its configuration
 133       structure (which itself was either created on startup for
 134       per-server context or during the directory walk of the Apache
 135       kernel for per-directory context). Then the URL rewriting
 136       engine is started with the contained ruleset (one or more
 137       rules together with their conditions). The operation of the
 138       URL rewriting engine itself is exactly the same for both
 139       configuration contexts. Only the final result processing is
 140       different.</p>
 141
 142       <p>The order of rules in the ruleset is important because the
 143       rewriting engine processes them in a special (and not very
 144       obvious) order. The rule is this: The rewriting engine loops
 145       through the ruleset rule by rule (<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives) and
 146       when a particular rule matches it optionally loops through
 147       existing corresponding conditions (<code>RewriteCond</code>
 148       directives). For historical reasons the conditions are given
 149       first, and so the control flow is a little bit long-winded. See
 150       Figure 1 for more details.</p>
 151 <p class="figure">
 152       <img src="../images/rewrite_process_uri.png" alt="Flow of RewriteRule and RewriteCond matching" /><br />
 153       <dfn>Figure 1:</dfn>The control flow through the rewriting ruleset
 154 </p>
 155       <p>First the URL is matched against the
 156       <em>Pattern</em> of each rule. If it fails, mod_rewrite
 157       immediately stops processing this rule, and continues with the
 158       next rule. If the <em>Pattern</em> matches, mod_rewrite looks
 159       for corresponding rule conditions (RewriteCond directives,
 160       appearing immediately above the RewriteRule in the configuration).
 161       If none are present, it substitutes the URL with a new value, which is
 162       constructed from the string <em>Substitution</em>, and goes on
 163       with its rule-looping. But if conditions exist, it starts an
 164       inner loop for processing them in the order that they are
 165       listed. For conditions, the logic is different: we don't match
 166       a pattern against the current URL. Instead we first create a
 167       string <em>TestString</em> by expanding variables,
 168       back-references, map lookups, <em>etc.</em> and then we try
 169       to match <em>CondPattern</em> against it. If the pattern
 170       doesn't match, the complete set of conditions and the
 171       corresponding rule fails. If the pattern matches, then the
 172       next condition is processed until no more conditions are
 173       available. If all conditions match, processing is continued
 174       with the substitution of the URL with
 175       <em>Substitution</em>.</p>
 176
 177 </div></div>
 178 <div class="bottomlang">
 179 <p><span>Available Languages: </span><a href="../en/rewrite/tech.html" title="English">&nbsp;en&nbsp;</a> |
 180 <a href="../fr/rewrite/tech.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 181 </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>
 182 <script type="text/javascript"><!--//--><![CDATA[//><!--
 183 var comments_shortname = 'httpd';
 184 var comments_identifier = 'http://httpd.apache.org/docs/trunk/rewrite/tech.html';
 185 (function(w, d) {
 186     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 187         d.write('<div id="comments_thread"><\/div>');
 188         var s = d.createElement('script');
 189         s.type = 'text/javascript';
 190         s.async = true;
 191         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 192         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 193     }
 194     else {
 195         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 196     }
 197 })(window, document);
 198 //--><!]]></script></div><div id="footer">
 199 <p class="apache">Copyright 2017 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>
 200 <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[//><!--
 201 if (typeof(prettyPrint) !== 'undefined') {
 202     prettyPrint();
 203 }
 204 //--><!]]></script>
 205 </body></html>