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