granicus.if.org Git - apache/blob - docs/manual/rewrite/advanced.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>Advanced Techniques with mod_rewrite - 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>Advanced Techniques with mod_rewrite</h1>
  25 <div class="toplang">
  26 <p><span>Available Languages: </span><a href="../en/rewrite/advanced.html" title="English">&nbsp;en&nbsp;</a> |
  27 <a href="../fr/rewrite/advanced.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
  28 </div>
  29
  30
  31 <p>This document supplements the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
  32 <a href="../mod/mod_rewrite.html">reference documentation</a>. It provides
  33 a few advanced techniques using mod_rewrite.</p>
  34
  35
  36
  37 <div class="warning">Note that many of these examples won't work unchanged in your
  38 particular server configuration, so it's important that you understand
  39 them, rather than merely cutting and pasting the examples into your
  40 configuration.</div>
  41
  42 </div>
  43 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#sharding">URL-based sharding across multiple backends</a></li>
  44 <li><img alt="" src="../images/down.gif" /> <a href="#on-the-fly-content">On-the-fly Content-Regeneration</a></li>
  45 <li><img alt="" src="../images/down.gif" /> <a href="#load-balancing">Load Balancing</a></li>
  46 <li><img alt="" src="../images/down.gif" /> <a href="#structuredhomedirs">Structured Userdirs</a></li>
  47 <li><img alt="" src="../images/down.gif" /> <a href="#redirectanchors">Redirecting Anchors</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#time-dependent">Time-Dependent Rewriting</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#setenvvars">Set Environment Variables Based On URL Parts</a></li>
  50 </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="avoid.html">When not to use mod_rewrite</a></li><li><a href="#comments_section">Comments</a></li></ul></div>
  51 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  52 <div class="section">
  53 <h2><a name="sharding" id="sharding">URL-based sharding across multiple backends</a><a title="Permanent link" href="#sharding" class="permalink">&para;</a></h2>
  54
  55
  56
  57   <dl>
  58     <dt>Description:</dt>
  59
  60     <dd>
  61       <p>A common technique for distributing the burden of
  62       server load or storage space is called "sharding".
  63       When using this method, a front-end server will use the
  64       url to consistently "shard" users or objects to separate
  65       backend servers.</p>
  66     </dd>
  67
  68     <dt>Solution:</dt>
  69
  70     <dd>
  71       <p>A mapping is maintained, from users to target servers, in
  72       external map files. They look like:</p>
  73
  74 <div class="example"><p><code>
  75 user1  physical_host_of_user1<br />
  76 user2  physical_host_of_user2<br />
  77 :      :
  78 </code></p></div>
  79
  80   <p>We put this into a <code>map.users-to-hosts</code> file. The
  81     aim is to map;</p>
  82
  83 <div class="example"><p><code>
  84 /u/user1/anypath
  85 </code></p></div>
  86
  87   <p>to</p>
  88
  89 <div class="example"><p><code>
  90 http://physical_host_of_user1/u/user/anypath
  91 </code></p></div>
  92
  93       <p>thus every URL path need not be valid on every backend physical
  94       host. The following ruleset does this for us with the help of the map
  95       files assuming that server0 is a default server which will be used if
  96       a user has no entry in the map:</p>
  97
  98 <pre class="prettyprint lang-config">RewriteEngine on
  99 RewriteMap    users-to-hosts      "txt:/path/to/map.users-to-hosts"
 100 RewriteRule   "^/u/([^/]+)/?(.*)" "http://${users-to-hosts:$1|server0}/u/$1/$2"</pre>
 101
 102     </dd>
 103   </dl>
 104
 105   <p>See the <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code>
 106   documentation for more discussion of the syntax of this directive.</p>
 107
 108 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 109 <div class="section">
 110 <h2><a name="on-the-fly-content" id="on-the-fly-content">On-the-fly Content-Regeneration</a><a title="Permanent link" href="#on-the-fly-content" class="permalink">&para;</a></h2>
 111
 112
 113
 114   <dl>
 115     <dt>Description:</dt>
 116
 117     <dd>
 118       <p>We wish to dynamically generate content, but store it
 119       statically once it is generated. This rule will check for the
 120       existence of the static file, and if it's not there, generate
 121       it. The static files can be removed periodically, if desired (say,
 122       via cron) and will be regenerated on demand.</p>
 123     </dd>
 124
 125     <dt>Solution:</dt>
 126
 127     <dd>
 128       This is done via the following ruleset:
 129
 130 <pre class="prettyprint lang-config"># This example is valid in per-directory context only
 131 RewriteCond "%{REQUEST_URI}"   !-U
 132 RewriteRule "^(.+)\.html$"     "/regenerate_page.cgi"   [PT,L]</pre>
 133
 134
 135     <p>The <code>-U</code> operator determines whether the test string
 136     (in this case, <code>REQUEST_URI</code>) is a valid URL. It does
 137     this via a subrequest. In the event that this subrequest fails -
 138     that is, the requested resource doesn't exist - this rule invokes
 139     the CGI program <code>/regenerate_page.cgi</code>, which generates
 140     the requested resource and saves it into the document directory, so
 141     that the next time it is requested, a static copy can be served.</p>
 142
 143     <p>In this way, documents that are infrequently updated can be served in
 144     static form. if documents need to be refreshed, they can be deleted
 145     from the document directory, and they will then be regenerated the
 146     next time they are requested.</p>
 147     </dd>
 148   </dl>
 149
 150 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 151 <div class="section">
 152 <h2><a name="load-balancing" id="load-balancing">Load Balancing</a><a title="Permanent link" href="#load-balancing" class="permalink">&para;</a></h2>
 153
 154
 155
 156   <dl>
 157     <dt>Description:</dt>
 158
 159     <dd>
 160       <p>We wish to randomly distribute load across several servers
 161       using mod_rewrite.</p>
 162     </dd>
 163
 164     <dt>Solution:</dt>
 165
 166     <dd>
 167       <p>We'll use <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> and a list of servers
 168       to accomplish this.</p>
 169
 170 <pre class="prettyprint lang-config">RewriteEngine on
 171 RewriteMap  lb       "rnd:/path/to/serverlist.txt"
 172 RewriteRule "^/(.*)" "http://${lb:servers}/$1"     [P,L]</pre>
 173
 174
 175 <p><code>serverlist.txt</code> will contain a list of the servers:</p>
 176
 177 <div class="example"><p><code>
 178 ## serverlist.txt<br />
 179 <br />
 180 servers one.example.com|two.example.com|three.example.com<br />
 181 </code></p></div>
 182
 183 <p>If you want one particular server to get more of the load than the
 184 others, add it more times to the list.</p>
 185
 186    </dd>
 187
 188    <dt>Discussion</dt>
 189    <dd>
 190 <p>Apache comes with a load-balancing module -
 191 <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code> - which is far more flexible and
 192 featureful than anything you can cobble together using mod_rewrite.</p>
 193    </dd>
 194   </dl>
 195
 196 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 197 <div class="section">
 198 <h2><a name="structuredhomedirs" id="structuredhomedirs">Structured Userdirs</a><a title="Permanent link" href="#structuredhomedirs" class="permalink">&para;</a></h2>
 199
 200
 201
 202   <dl>
 203     <dt>Description:</dt>
 204
 205     <dd>
 206       <p>Some sites with thousands of users use a
 207       structured homedir layout, <em>i.e.</em> each homedir is in a
 208       subdirectory which begins (for instance) with the first
 209       character of the username. So, <code>/~larry/anypath</code>
 210       is <code>/home/<strong>l</strong>/larry/public_html/anypath</code>
 211       while <code>/~waldo/anypath</code> is
 212       <code>/home/<strong>w</strong>/waldo/public_html/anypath</code>.</p>
 213     </dd>
 214
 215     <dt>Solution:</dt>
 216
 217     <dd>
 218       <p>We use the following ruleset to expand the tilde URLs
 219       into the above layout.</p>
 220
 221 <pre class="prettyprint lang-config">RewriteEngine on
 222 RewriteRule   "^/~(<strong>([a-z])</strong>[a-z0-9]+)(.*)"  "/home/<strong>$2</strong>/$1/public_html$3"</pre>
 223
 224     </dd>
 225   </dl>
 226
 227 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 228 <div class="section">
 229 <h2><a name="redirectanchors" id="redirectanchors">Redirecting Anchors</a><a title="Permanent link" href="#redirectanchors" class="permalink">&para;</a></h2>
 230
 231
 232
 233   <dl>
 234     <dt>Description:</dt>
 235
 236     <dd>
 237     <p>By default, redirecting to an HTML anchor doesn't work,
 238     because mod_rewrite escapes the <code>#</code> character,
 239     turning it into <code>%23</code>. This, in turn, breaks the
 240     redirection.</p>
 241     </dd>
 242
 243     <dt>Solution:</dt>
 244
 245     <dd>
 246       <p>Use the <code>[NE]</code> flag on the
 247       <code>RewriteRule</code>. NE stands for No Escape.
 248       </p>
 249     </dd>
 250
 251     <dt>Discussion:</dt>
 252     <dd>This technique will of course also work with other
 253     special characters that mod_rewrite, by default, URL-encodes.</dd>
 254   </dl>
 255
 256 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 257 <div class="section">
 258 <h2><a name="time-dependent" id="time-dependent">Time-Dependent Rewriting</a><a title="Permanent link" href="#time-dependent" class="permalink">&para;</a></h2>
 259
 260
 261
 262   <dl>
 263     <dt>Description:</dt>
 264
 265     <dd>
 266       <p>We wish to use mod_rewrite to serve different content based on
 267       the time of day.</p>
 268     </dd>
 269
 270     <dt>Solution:</dt>
 271
 272     <dd>
 273       <p>There are a lot of variables named <code>TIME_xxx</code>
 274       for rewrite conditions. In conjunction with the special
 275       lexicographic comparison patterns <code>&lt;STRING</code>,
 276       <code>&gt;STRING</code> and <code>=STRING</code> we can
 277       do time-dependent redirects:</p>
 278
 279 <pre class="prettyprint lang-config">RewriteEngine on
 280 RewriteCond   "%{TIME_HOUR}%{TIME_MIN}" &gt;0700
 281 RewriteCond   "%{TIME_HOUR}%{TIME_MIN}" &lt;1900
 282 RewriteRule   "^foo\.html$"             "foo.day.html" [L]
 283 RewriteRule   "^foo\.html$"             "foo.night.html"</pre>
 284
 285
 286       <p>This provides the content of <code>foo.day.html</code>
 287       under the URL <code>foo.html</code> from
 288       <code>07:01-18:59</code> and at the remaining time the
 289       contents of <code>foo.night.html</code>.</p>
 290
 291       <div class="warning"><code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code>, intermediate proxies
 292       and browsers may each cache responses and cause the either page to be
 293       shown outside of the time-window configured.
 294       <code class="module"><a href="../mod/mod_expires.html">mod_expires</a></code> may be used to control this
 295       effect. You are, of course, much better off simply serving the
 296       content dynamically, and customizing it based on the time of day.</div>
 297
 298     </dd>
 299   </dl>
 300
 301 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 302 <div class="section">
 303 <h2><a name="setenvvars" id="setenvvars">Set Environment Variables Based On URL Parts</a><a title="Permanent link" href="#setenvvars" class="permalink">&para;</a></h2>
 304
 305
 306
 307   <dl>
 308     <dt>Description:</dt>
 309
 310     <dd>
 311       <p>At time, we want to maintain some kind of status when we
 312       perform a rewrite. For example, you want to make a note that
 313       you've done that rewrite, so that you can check later to see if a
 314       request can via that rewrite. One way to do this is by setting an
 315       environment variable.</p>
 316     </dd>
 317
 318     <dt>Solution:</dt>
 319
 320     <dd>
 321       <p>Use the [E] flag to set an environment variable.</p>
 322
 323 <pre class="prettyprint lang-config">RewriteEngine on
 324 RewriteRule   "^/horse/(.*)"   "/pony/$1" [E=<strong>rewritten:1</strong>]</pre>
 325
 326
 327     <p>Later in your ruleset you might check for this environment
 328     variable using a RewriteCond:</p>
 329
 330 <pre class="prettyprint lang-config">RewriteCond "%{ENV:rewritten}"  =1</pre>
 331
 332
 333     <p>Note that environment variables do not survive an external
 334     redirect. You might consider using the [CO] flag to set a
 335     cookie.</p>
 336
 337     </dd>
 338   </dl>
 339
 340 </div></div>
 341 <div class="bottomlang">
 342 <p><span>Available Languages: </span><a href="../en/rewrite/advanced.html" title="English">&nbsp;en&nbsp;</a> |
 343 <a href="../fr/rewrite/advanced.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 344 </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>
 345 <script type="text/javascript"><!--//--><![CDATA[//><!--
 346 var comments_shortname = 'httpd';
 347 var comments_identifier = 'http://httpd.apache.org/docs/trunk/rewrite/advanced.html';
 348 (function(w, d) {
 349     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 350         d.write('<div id="comments_thread"><\/div>');
 351         var s = d.createElement('script');
 352         s.type = 'text/javascript';
 353         s.async = true;
 354         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 355         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 356     }
 357     else {
 358         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 359     }
 360 })(window, document);
 361 //--><!]]></script></div><div id="footer">
 362 <p class="apache">Copyright 2018 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>
 363 <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[//><!--
 364 if (typeof(prettyPrint) !== 'undefined') {
 365     prettyPrint();
 366 }
 367 //--><!]]></script>
 368 </body></html>