home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F278107_mod_rewrite.html.en < prev    next >
Extensible Markup Language  |  2004-08-27  |  86KB  |  1,783 lines
  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>mod_rewrite - Apache HTTP Server</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" />
  12. <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13. <body>
  14. <div id="page-header">
  15. <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  16. <p class="apache">Apache HTTP Server Version 2.0</p>
  17. <img alt="" src="../images/feather.gif" /></div>
  18. <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
  19. <div id="path">
  20. <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Modules</a></div>
  21. <div id="page-content">
  22. <div id="preamble"><h1>Apache Module mod_rewrite</h1>
  23. <div class="toplang">
  24. <p><span>Available Languages: </span><a href="../en/mod/mod_rewrite.html" title="English"> en </a></p>
  25. </div>
  26. <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides a rule-based rewriting engine to rewrite requested
  27. URLs on the fly</td></tr>
  28. <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  29. <tr><th><a href="module-dict.html#ModuleIdentifier">ModuleáIdentifier:</a></th><td>rewrite_module</td></tr>
  30. <tr><th><a href="module-dict.html#SourceFile">SourceáFile:</a></th><td>mod_rewrite.c</td></tr>
  31. <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 1.3 and later</td></tr></table>
  32. <h3>Summary</h3>
  33.  
  34.       <blockquote>
  35.             <p>``The great thing about mod_rewrite is it gives you
  36.             all the configurability and flexibility of Sendmail.
  37.             The downside to mod_rewrite is that it gives you all
  38.             the configurability and flexibility of Sendmail.''</p>
  39.  
  40.             <p class="cite">-- <cite>Brian Behlendorf</cite><br />
  41.             Apache Group</p>
  42.  
  43.       </blockquote>
  44.  
  45.       <blockquote>
  46.             <p>`` Despite the tons of examples and docs,
  47.             mod_rewrite is voodoo. Damned cool voodoo, but still
  48.             voodoo. ''</p>
  49.  
  50.             <p class="cite">-- <cite>Brian Moore</cite><br />
  51.             bem@news.cmc.net</p>
  52.  
  53.       </blockquote>
  54.  
  55.  
  56.       <p>Welcome to mod_rewrite, the Swiss Army Knife of URL
  57.       manipulation!</p>
  58.  
  59.       <p>This module uses a rule-based rewriting engine (based on a
  60.       regular-expression parser) to rewrite requested URLs on the
  61.       fly. It supports an unlimited number of rules and an
  62.       unlimited number of attached rule conditions for each rule to
  63.       provide a really flexible and powerful URL manipulation
  64.       mechanism. The URL manipulations can depend on various tests,
  65.       for instance server variables, environment variables, HTTP
  66.       headers, time stamps and even external database lookups in
  67.       various formats can be used to achieve a really granular URL
  68.       matching.</p>
  69.  
  70.       <p>This module operates on the full URLs (including the
  71.       path-info part) both in per-server context
  72.       (<code>httpd.conf</code>) and per-directory context
  73.       (<code>.htaccess</code>) and can even generate query-string
  74.       parts on result. The rewritten result can lead to internal
  75.       sub-processing, external request redirection or even to an
  76.       internal proxy throughput.</p>
  77.  
  78.       <p>But all this functionality and flexibility has its
  79.       drawback: complexity. So don't expect to understand this
  80.       entire module in just one day.</p>
  81.  
  82.       <p>This module was invented and originally written in April
  83.       1996 and gifted exclusively to the The Apache Group in July 1997
  84.       by</p>
  85.  
  86.       <p class="indent">
  87.         <a href="http://www.engelschall.com/"><code>Ralf S.
  88.         Engelschall</code></a><br />
  89.          <a href="mailto:rse@engelschall.com"><code>rse@engelschall.com</code></a><br />
  90.          <a href="http://www.engelschall.com/"><code>www.engelschall.com</code></a>
  91.       </p>
  92. </div>
  93. <div id="quickview"><h3 class="directives">Directives</h3>
  94. <ul id="toc">
  95. <li><img alt="" src="../images/down.gif" /> <a href="#rewritebase">RewriteBase</a></li>
  96. <li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">RewriteCond</a></li>
  97. <li><img alt="" src="../images/down.gif" /> <a href="#rewriteengine">RewriteEngine</a></li>
  98. <li><img alt="" src="../images/down.gif" /> <a href="#rewritelock">RewriteLock</a></li>
  99. <li><img alt="" src="../images/down.gif" /> <a href="#rewritelog">RewriteLog</a></li>
  100. <li><img alt="" src="../images/down.gif" /> <a href="#rewriteloglevel">RewriteLogLevel</a></li>
  101. <li><img alt="" src="../images/down.gif" /> <a href="#rewritemap">RewriteMap</a></li>
  102. <li><img alt="" src="../images/down.gif" /> <a href="#rewriteoptions">RewriteOptions</a></li>
  103. <li><img alt="" src="../images/down.gif" /> <a href="#rewriterule">RewriteRule</a></li>
  104. </ul>
  105. <h3>Topics</h3>
  106. <ul id="topics">
  107. <li><img alt="" src="../images/down.gif" /> <a href="#Internal">Internal Processing</a></li>
  108. <li><img alt="" src="../images/down.gif" /> <a href="#EnvVar">Environment Variables</a></li>
  109. <li><img alt="" src="../images/down.gif" /> <a href="#Solutions">Practical Solutions</a></li>
  110. </ul></div>
  111. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  112. <div class="section">
  113. <h2><a name="Internal" id="Internal">Internal Processing</a></h2>
  114.  
  115.       <p>The internal processing of this module is very complex but
  116.       needs to be explained once even to the average user to avoid
  117.       common mistakes and to let you exploit its full
  118.       functionality.</p>
  119.  
  120. <h3><a name="InternalAPI" id="InternalAPI">API Phases</a></h3>
  121.  
  122.       <p>First you have to understand that when Apache processes a
  123.       HTTP request it does this in phases. A hook for each of these
  124.       phases is provided by the Apache API. Mod_rewrite uses two of
  125.       these hooks: the URL-to-filename translation hook which is
  126.       used after the HTTP request has been read but before any
  127.       authorization starts and the Fixup hook which is triggered
  128.       after the authorization phases and after the per-directory
  129.       config files (<code>.htaccess</code>) have been read, but
  130.       before the content handler is activated.</p>
  131.  
  132.       <p>So, after a request comes in and Apache has determined the
  133.       corresponding server (or virtual server) the rewriting engine
  134.       starts processing of all mod_rewrite directives from the
  135.       per-server configuration in the URL-to-filename phase. A few
  136.       steps later when the final data directories are found, the
  137.       per-directory configuration directives of mod_rewrite are
  138.       triggered in the Fixup phase. In both situations mod_rewrite
  139.       rewrites URLs either to new URLs or to filenames, although
  140.       there is no obvious distinction between them. This is a usage
  141.       of the API which was not intended to be this way when the API
  142.       was designed, but as of Apache 1.x this is the only way
  143.       mod_rewrite can operate. To make this point more clear
  144.       remember the following two points:</p>
  145.  
  146.       <ol>
  147.         <li>Although mod_rewrite rewrites URLs to URLs, URLs to
  148.         filenames and even filenames to filenames, the API
  149.         currently provides only a URL-to-filename hook. In Apache
  150.         2.0 the two missing hooks will be added to make the
  151.         processing more clear. But this point has no drawbacks for
  152.         the user, it is just a fact which should be remembered:
  153.         Apache does more in the URL-to-filename hook than the API
  154.         intends for it.</li>
  155.  
  156.         <li>
  157.           Unbelievably mod_rewrite provides URL manipulations in
  158.           per-directory context, <em>i.e.</em>, within
  159.           <code>.htaccess</code> files, although these are reached
  160.           a very long time after the URLs have been translated to
  161.           filenames. It has to be this way because
  162.           <code>.htaccess</code> files live in the filesystem, so
  163.           processing has already reached this stage. In other
  164.           words: According to the API phases at this time it is too
  165.           late for any URL manipulations. To overcome this chicken
  166.           and egg problem mod_rewrite uses a trick: When you
  167.           manipulate a URL/filename in per-directory context
  168.           mod_rewrite first rewrites the filename back to its
  169.           corresponding URL (which is usually impossible, but see
  170.           the <code>RewriteBase</code> directive below for the
  171.           trick to achieve this) and then initiates a new internal
  172.           sub-request with the new URL. This restarts processing of
  173.           the API phases. 
  174.  
  175.           <p>Again mod_rewrite tries hard to make this complicated
  176.           step totally transparent to the user, but you should
  177.           remember here: While URL manipulations in per-server
  178.           context are really fast and efficient, per-directory
  179.           rewrites are slow and inefficient due to this chicken and
  180.           egg problem. But on the other hand this is the only way
  181.           mod_rewrite can provide (locally restricted) URL
  182.           manipulations to the average user.</p>
  183.         </li>
  184.       </ol>
  185.  
  186.       <p>Don't forget these two points!</p>
  187.  
  188.  
  189. <h3><a name="InternalRuleset" id="InternalRuleset">Ruleset Processing</a></h3>
  190.  
  191.       <p>Now when mod_rewrite is triggered in these two API phases, it
  192.       reads the configured rulesets from its configuration
  193.       structure (which itself was either created on startup for
  194.       per-server context or during the directory walk of the Apache
  195.       kernel for per-directory context). Then the URL rewriting
  196.       engine is started with the contained ruleset (one or more
  197.       rules together with their conditions). The operation of the
  198.       URL rewriting engine itself is exactly the same for both
  199.       configuration contexts. Only the final result processing is
  200.       different. </p>
  201.  
  202.       <p>The order of rules in the ruleset is important because the
  203.       rewriting engine processes them in a special (and not very
  204.       obvious) order. The rule is this: The rewriting engine loops
  205.       through the ruleset rule by rule (<code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives) and
  206.       when a particular rule matches it optionally loops through
  207.       existing corresponding conditions (<code>RewriteCond</code>
  208.       directives). For historical reasons the conditions are given
  209.       first, and so the control flow is a little bit long-winded. See
  210.       Figure 1 for more details.</p>
  211. <p class="figure">
  212.       <img src="../images/mod_rewrite_fig1.gif" width="428" height="385" alt="[Needs graphics capability to display]" /><br />
  213.       <dfn>Figure 1:</dfn>The control flow through the rewriting ruleset
  214. </p>
  215.       <p>As you can see, first the URL is matched against the
  216.       <em>Pattern</em> of each rule. When it fails mod_rewrite
  217.       immediately stops processing this rule and continues with the
  218.       next rule. If the <em>Pattern</em> matches, mod_rewrite looks
  219.       for corresponding rule conditions. If none are present, it
  220.       just substitutes the URL with a new value which is
  221.       constructed from the string <em>Substitution</em> and goes on
  222.       with its rule-looping. But if conditions exist, it starts an
  223.       inner loop for processing them in the order that they are
  224.       listed. For conditions the logic is different: we don't match
  225.       a pattern against the current URL. Instead we first create a
  226.       string <em>TestString</em> by expanding variables,
  227.       back-references, map lookups, <em>etc.</em> and then we try
  228.       to match <em>CondPattern</em> against it. If the pattern
  229.       doesn't match, the complete set of conditions and the
  230.       corresponding rule fails. If the pattern matches, then the
  231.       next condition is processed until no more conditions are
  232.       available. If all conditions match, processing is continued
  233.       with the substitution of the URL with
  234.       <em>Substitution</em>.</p>
  235.  
  236.  
  237.  
  238. <h3><a name="quoting" id="quoting">Quoting Special Characters</a></h3>
  239.  
  240.       <p>As of Apache 1.3.20, special characters in
  241.       <em>TestString</em> and <em>Substitution</em> strings can be
  242.       escaped (that is, treated as normal characters without their
  243.       usual special meaning) by prefixing them with a slosh ('\')
  244.       character. In other words, you can include an actual
  245.       dollar-sign character in a <em>Substitution</em> string by
  246.       using '<code>\$</code>'; this keeps mod_rewrite from trying
  247.       to treat it as a backreference.</p>
  248.  
  249.  
  250. <h3><a name="InternalBackRefs" id="InternalBackRefs">Regex Back-Reference Availability</a></h3>
  251.  
  252.       <p>One important thing here has to be remembered: Whenever you
  253.       use parentheses in <em>Pattern</em> or in one of the
  254.       <em>CondPattern</em>, back-references are internally created
  255.       which can be used with the strings <code>$N</code> and
  256.       <code>%N</code> (see below). These are available for creating
  257.       the strings <em>Substitution</em> and <em>TestString</em>.
  258.       Figure 2 shows to which locations the back-references are
  259.       transfered for expansion.</p>
  260.  
  261. <p class="figure">
  262.       <img src="../images/mod_rewrite_fig2.gif" width="381" height="179" alt="[Needs graphics capability to display]" /><br />
  263.       <dfn>Figure 2:</dfn> The back-reference flow through a rule.
  264. </p>
  265.       <p>We know this was a crash course on mod_rewrite's internal
  266.       processing. But you will benefit from this knowledge when
  267.       reading the following documentation of the available
  268.       directives.</p>
  269.  
  270.  
  271. </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  272. <div class="section">
  273. <h2><a name="EnvVar" id="EnvVar">Environment Variables</a></h2>
  274.  
  275.       <p>This module keeps track of two additional (non-standard)
  276.       CGI/SSI environment variables named <code>SCRIPT_URL</code>
  277.       and <code>SCRIPT_URI</code>. These contain the
  278.       <em>logical</em> Web-view to the current resource, while the
  279.       standard CGI/SSI variables <code>SCRIPT_NAME</code> and
  280.       <code>SCRIPT_FILENAME</code> contain the <em>physical</em>
  281.       System-view. </p>
  282.  
  283.       <p>Notice: These variables hold the URI/URL <em>as they were
  284.       initially requested</em>, <em>i.e.</em>, <em>before</em> any
  285.       rewriting. This is important because the rewriting process is
  286.       primarily used to rewrite logical URLs to physical
  287.       pathnames.</p>
  288.  
  289. <div class="example"><h3>Example</h3><pre>
  290. SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
  291. SCRIPT_FILENAME=/u/rse/.www/index.html
  292. SCRIPT_URL=/u/rse/
  293. SCRIPT_URI=http://en1.engelschall.com/u/rse/
  294. </pre></div>
  295.  
  296. </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  297. <div class="section">
  298. <h2><a name="Solutions" id="Solutions">Practical Solutions</a></h2>
  299.  
  300.       <p>We also have an <a href="../misc/rewriteguide.html">URL
  301.       Rewriting Guide</a> available, which provides a collection of
  302.       practical solutions for URL-based problems. There you can
  303.       find real-life rulesets and additional information about
  304.       mod_rewrite.</p>
  305. </div>
  306. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  307. <div class="directive-section"><h2><a name="RewriteBase" id="RewriteBase">RewriteBase</a> <a name="rewritebase" id="rewritebase">Directive</a></h2>
  308. <table class="directive">
  309. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the base URL for per-directory rewrites</td></tr>
  310. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteBase <em>URL-path</em></code></td></tr>
  311. <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>See usage for information.</code></td></tr>
  312. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
  313. <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
  314. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  315. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  316. </table>
  317.       <p>The <code class="directive">RewriteBase</code> directive explicitly
  318.       sets the base URL for per-directory rewrites. As you will see
  319.       below, <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
  320.       can be used in per-directory config files
  321.       (<code>.htaccess</code>). There it will act locally,
  322.       <em>i.e.</em>, the local directory prefix is stripped at this
  323.       stage of processing and your rewriting rules act only on the
  324.       remainder. At the end it is automatically added back to the
  325.       path. The default setting is; <code class="directive">RewriteBase</code> <em>physical-directory-path</em></p>
  326.  
  327.       <p>When a substitution occurs for a new URL, this module has
  328.       to re-inject the URL into the server processing. To be able
  329.       to do this it needs to know what the corresponding URL-prefix
  330.       or URL-base is. By default this prefix is the corresponding
  331.       filepath itself. <strong>But at most websites URLs are NOT
  332.       directly related to physical filename paths, so this
  333.       assumption will usually be wrong!</strong> There you have to
  334.       use the <code>RewriteBase</code> directive to specify the
  335.       correct URL-prefix.</p>
  336.  
  337. <div class="note"> If your webserver's URLs are <strong>not</strong> directly
  338. related to physical file paths, you have to use
  339. <code class="directive">RewriteBase</code> in every <code>.htaccess</code>
  340. files where you want to use <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives.
  341. </div>
  342.  
  343.         <p> For example, assume the following per-directory config file:</p>
  344.  
  345. <div class="example"><pre>
  346. #
  347. #  /abc/def/.htaccess -- per-dir config file for directory /abc/def
  348. #  Remember: /abc/def is the physical path of /xyz, <em>i.e.</em>, the server
  349. #            has a 'Alias /xyz /abc/def' directive <em>e.g.</em>
  350. #
  351.  
  352. RewriteEngine On
  353.  
  354. #  let the server know that we were reached via /xyz and not
  355. #  via the physical path prefix /abc/def
  356. RewriteBase   /xyz
  357.  
  358. #  now the rewriting rules
  359. RewriteRule   ^oldstuff\.html$  newstuff.html
  360. </pre></div>
  361.  
  362.         <p>In the above example, a request to
  363.         <code>/xyz/oldstuff.html</code> gets correctly rewritten to
  364.         the physical file <code>/abc/def/newstuff.html</code>.</p>
  365.  
  366. <div class="note"><h3>For Apache Hackers</h3>
  367. <p>The following list gives detailed information about
  368.               the internal processing steps:</p>
  369. <pre>
  370. Request:
  371.   /xyz/oldstuff.html
  372.  
  373. Internal Processing:
  374.   /xyz/oldstuff.html     -> /abc/def/oldstuff.html  (per-server Alias)
  375.   /abc/def/oldstuff.html -> /abc/def/newstuff.html  (per-dir    RewriteRule)
  376.   /abc/def/newstuff.html -> /xyz/newstuff.html      (per-dir    RewriteBase)
  377.   /xyz/newstuff.html     -> /abc/def/newstuff.html  (per-server Alias)
  378.  
  379. Result:
  380.   /abc/def/newstuff.html
  381. </pre>
  382.               <p>This seems very complicated but is
  383.               the correct Apache internal processing, because the
  384.               per-directory rewriting comes too late in the
  385.               process. So, when it occurs the (rewritten) request
  386.               has to be re-injected into the Apache kernel! BUT:
  387.               While this seems like a serious overhead, it really
  388.               isn't, because this re-injection happens fully
  389.               internally to the Apache server and the same
  390.               procedure is used by many other operations inside
  391.               Apache. So, you can be sure the design and
  392.               implementation is correct.</p>
  393. </div>
  394.  
  395.  
  396. </div>
  397. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  398. <div class="directive-section"><h2><a name="RewriteCond" id="RewriteCond">RewriteCond</a> <a name="rewritecond" id="rewritecond">Directive</a></h2>
  399. <table class="directive">
  400. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a condition under which rewriting will take place
  401. </td></tr>
  402. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> RewriteCond
  403.       <em>TestString</em> <em>CondPattern</em></code></td></tr>
  404. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
  405. <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
  406. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  407. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  408. </table>
  409.       <p>The <code class="directive">RewriteCond</code> directive defines a
  410.       rule condition. Precede a <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directive with one
  411.       or more <code class="directive">RewriteCond</code> directives. The following
  412.       rewriting rule is only used if its pattern matches the current
  413.       state of the URI <strong>and</strong> if these additional
  414.       conditions apply too.</p>
  415.  
  416.       <p><em>TestString</em> is a string which can contains the
  417.       following expanded constructs in addition to plain text:</p>
  418.  
  419.       <ul>
  420.         <li>
  421.           <strong>RewriteRule backreferences</strong>: These are
  422.           backreferences of the form 
  423.  
  424.           <p class="indent">
  425.             <strong><code>$N</code></strong>
  426.           </p>
  427.           (0 <= N <= 9) which provide access to the grouped
  428.           parts (parenthesis!) of the pattern from the
  429.           corresponding <code>RewriteRule</code> directive (the one
  430.           following the current bunch of <code>RewriteCond</code>
  431.           directives).
  432.         </li>
  433.  
  434.         <li>
  435.           <strong>RewriteCond backreferences</strong>: These are
  436.           backreferences of the form 
  437.  
  438.           <p class="indent">
  439.             <strong><code>%N</code></strong>
  440.           </p>
  441.           (1 <= N <= 9) which provide access to the grouped
  442.           parts (parentheses!) of the pattern from the last matched
  443.           <code>RewriteCond</code> directive in the current bunch
  444.           of conditions.
  445.         </li>
  446.  
  447.         <li>
  448.           <strong>RewriteMap expansions</strong>: These are
  449.           expansions of the form 
  450.  
  451.           <p class="indent">
  452.             <strong><code>${mapname:key|default}</code></strong>
  453.           </p>
  454.           See <a href="#mapfunc">the documentation for
  455.           RewriteMap</a> for more details.
  456.         </li>
  457.  
  458.         <li>
  459.           <strong>Server-Variables</strong>: These are variables of
  460.           the form 
  461.  
  462.           <p class="indent">
  463.             <strong><code>%{</code> <em>NAME_OF_VARIABLE</em>
  464.             <code>}</code></strong>
  465.           </p>
  466.           where <em>NAME_OF_VARIABLE</em> can be a string taken
  467.           from the following list: 
  468.  
  469.           <table>
  470.           
  471.             <tr>
  472.               <th>HTTP headers:</th> <th>connection & request:</th> <th />
  473.         </tr>
  474.  
  475.             <tr>
  476.           <td>
  477.          HTTP_USER_AGENT<br />
  478.                  HTTP_REFERER<br />
  479.                  HTTP_COOKIE<br />
  480.                  HTTP_FORWARDED<br />
  481.                  HTTP_HOST<br />
  482.                  HTTP_PROXY_CONNECTION<br />
  483.                  HTTP_ACCEPT<br />
  484.               </td>
  485.  
  486.               <td>
  487.                  REMOTE_ADDR<br />
  488.                  REMOTE_HOST<br />
  489.                  REMOTE_USER<br />
  490.                  REMOTE_IDENT<br />
  491.                  REQUEST_METHOD<br />
  492.                  SCRIPT_FILENAME<br />
  493.                  PATH_INFO<br />
  494.                  QUERY_STRING<br />
  495.                  AUTH_TYPE<br />
  496.               </td>
  497.           
  498.           <td />
  499.             </tr>
  500.  
  501.             <tr>
  502.               <th>server internals:</th> <th>system stuff:</th> <th>specials:</th>
  503.         </tr>
  504.  
  505.             <tr>
  506.           <td>
  507.              DOCUMENT_ROOT<br />
  508.                  SERVER_ADMIN<br />
  509.                  SERVER_NAME<br />
  510.                  SERVER_ADDR<br />
  511.                  SERVER_PORT<br />
  512.                  SERVER_PROTOCOL<br />
  513.                  SERVER_SOFTWARE<br />
  514.               </td>
  515.  
  516.               <td>
  517.                  TIME_YEAR<br />
  518.                  TIME_MON<br />
  519.                  TIME_DAY<br />
  520.                  TIME_HOUR<br />
  521.                  TIME_MIN<br />
  522.                  TIME_SEC<br />
  523.                  TIME_WDAY<br />
  524.                  TIME<br />
  525.               </td>
  526.  
  527.               <td>
  528.                  API_VERSION<br />
  529.                  THE_REQUEST<br />
  530.                  REQUEST_URI<br />
  531.                  REQUEST_FILENAME<br />
  532.                  IS_SUBREQ<br />
  533.                  HTTPS<br />
  534.               </td>
  535.             </tr>
  536.           </table>
  537.  
  538. <div class="note">
  539.                 <p>These variables all
  540.                 correspond to the similarly named HTTP
  541.                 MIME-headers, C variables of the Apache server or
  542.                 <code>struct tm</code> fields of the Unix system.
  543.                 Most are documented elsewhere in the Manual or in
  544.                 the CGI specification. Those that are special to
  545.                 mod_rewrite include:</p>
  546.  
  547.                 <dl>
  548.                   <dt><code>IS_SUBREQ</code></dt>
  549.  
  550.                   <dd>Will contain the text "true" if the request
  551.                   currently being processed is a sub-request,
  552.                   "false" otherwise. Sub-requests may be generated
  553.                   by modules that need to resolve additional files
  554.                   or URIs in order to complete their tasks.</dd>
  555.  
  556.                   <dt><code>API_VERSION</code></dt>
  557.  
  558.                   <dd>This is the version of the Apache module API
  559.                   (the internal interface between server and
  560.                   module) in the current httpd build, as defined in
  561.                   include/ap_mmn.h. The module API version
  562.                   corresponds to the version of Apache in use (in
  563.                   the release version of Apache 1.3.14, for
  564.                   instance, it is 19990320:10), but is mainly of
  565.                   interest to module authors.</dd>
  566.  
  567.                   <dt><code>THE_REQUEST</code></dt>
  568.  
  569.                   <dd>The full HTTP request line sent by the
  570.                   browser to the server (e.g., "<code>GET
  571.                   /index.html HTTP/1.1</code>"). This does not
  572.                   include any additional headers sent by the
  573.                   browser.</dd>
  574.  
  575.                   <dt><code>REQUEST_URI</code></dt>
  576.  
  577.                   <dd>The resource requested in the HTTP request
  578.                   line. (In the example above, this would be
  579.                   "/index.html".)</dd>
  580.  
  581.                   <dt><code>REQUEST_FILENAME</code></dt>
  582.  
  583.                   <dd>The full local filesystem path to the file or
  584.                   script matching the request.</dd>
  585.  
  586.                   <dt><code>HTTPS</code></dt>
  587.  
  588.                   <dd>Will contain the text "on" if the connection is
  589.                   using SSL/TLS, or "off" otherwise.  (This variable
  590.                   can be safely used regardless of whether
  591.                   <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is loaded).</dd>
  592.  
  593.                 </dl>
  594. </div>
  595.         </li>
  596.       </ul>
  597.  
  598.       <p>Special Notes:</p>
  599.  
  600.       <ol>
  601.         <li>The variables SCRIPT_FILENAME and REQUEST_FILENAME
  602.         contain the same value, <em>i.e.</em>, the value of the
  603.         <code>filename</code> field of the internal
  604.         <code>request_rec</code> structure of the Apache server.
  605.         The first name is just the commonly known CGI variable name
  606.         while the second is the consistent counterpart to
  607.         REQUEST_URI (which contains the value of the
  608.         <code>uri</code> field of <code>request_rec</code>).</li>
  609.  
  610.         <li>There is the special format:
  611.         <code>%{ENV:variable}</code> where <em>variable</em> can be
  612.         any environment variable. This is looked-up via internal
  613.         Apache structures and (if not found there) via
  614.         <code>getenv()</code> from the Apache server process.</li>
  615.  
  616.         <li>There is the special format: 
  617.         <code>%{SSL:variable}</code> where <em>variable</em> is the
  618.         name of an <a href="mod_ssl.html#envvars">SSL environment
  619.         variable</a>; this can be used whether or not
  620.         <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is loaded, but will always expand to
  621.         the empty string if it is not.  Example:
  622.         <code>%{SSL:SSL_CIPHER_USEKEYSIZE}</code> may expand to
  623.         <code>128</code>.</li>
  624.  
  625.         <li>There is the special format:
  626.         <code>%{HTTP:header}</code> where <em>header</em> can be
  627.         any HTTP MIME-header name. This is looked-up from the HTTP
  628.         request. Example: <code>%{HTTP:Proxy-Connection}</code> is
  629.         the value of the HTTP header
  630.         ``<code>Proxy-Connection:</code>''.</li>
  631.  
  632.         <li>There is the special format
  633.         <code>%{LA-U:variable}</code> for look-aheads which perform
  634.         an internal (URL-based) sub-request to determine the final
  635.         value of <em>variable</em>. Use this when you want to use a
  636.         variable for rewriting which is actually set later in an
  637.         API phase and thus is not available at the current stage.
  638.         For instance when you want to rewrite according to the
  639.         <code>REMOTE_USER</code> variable from within the
  640.         per-server context (<code>httpd.conf</code> file) you have
  641.         to use <code>%{LA-U:REMOTE_USER}</code> because this
  642.         variable is set by the authorization phases which come
  643.         <em>after</em> the URL translation phase where mod_rewrite
  644.         operates. On the other hand, because mod_rewrite implements
  645.         its per-directory context (<code>.htaccess</code> file) via
  646.         the Fixup phase of the API and because the authorization
  647.         phases come <em>before</em> this phase, you just can use
  648.         <code>%{REMOTE_USER}</code> there.</li>
  649.  
  650.         <li>There is the special format:
  651.         <code>%{LA-F:variable}</code> which performs an internal
  652.         (filename-based) sub-request to determine the final value
  653.         of <em>variable</em>. Most of the time this is the same as
  654.         LA-U above.</li>
  655.       </ol>
  656.  
  657.       <p><em>CondPattern</em> is the condition pattern,
  658.       <em>i.e.</em>, a regular expression which is applied to the
  659.       current instance of the <em>TestString</em>, <em>i.e.</em>,
  660.       <em>TestString</em> is evaluated and then matched against
  661.       <em>CondPattern</em>.</p>
  662.  
  663.       <p><strong>Remember:</strong> <em>CondPattern</em> is a
  664.       <em>perl compatible regular expression</em> with some
  665.       additions:</p>
  666.  
  667.       <ol>
  668.         <li>You can prefix the pattern string with a
  669.         '<code>!</code>' character (exclamation mark) to specify a
  670.         <strong>non</strong>-matching pattern.</li>
  671.  
  672.         <li>
  673.           There are some special variants of <em>CondPatterns</em>.
  674.           Instead of real regular expression strings you can also
  675.           use one of the following: 
  676.  
  677.           <ul>
  678.             <li>'<strong><CondPattern</strong>' (is lexically
  679.             lower)<br />
  680.              Treats the <em>CondPattern</em> as a plain string and
  681.             compares it lexically to <em>TestString</em>. True if
  682.             <em>TestString</em> is lexically lower than
  683.             <em>CondPattern</em>.</li>
  684.  
  685.             <li>'<strong>>CondPattern</strong>' (is lexically
  686.             greater)<br />
  687.              Treats the <em>CondPattern</em> as a plain string and
  688.             compares it lexically to <em>TestString</em>. True if
  689.             <em>TestString</em> is lexically greater than
  690.             <em>CondPattern</em>.</li>
  691.  
  692.             <li>'<strong>=CondPattern</strong>' (is lexically
  693.             equal)<br />
  694.              Treats the <em>CondPattern</em> as a plain string and
  695.             compares it lexically to <em>TestString</em>. True if
  696.             <em>TestString</em> is lexically equal to
  697.             <em>CondPattern</em>, i.e the two strings are exactly
  698.             equal (character by character). If <em>CondPattern</em>
  699.             is just <code>""</code> (two quotation marks) this
  700.             compares <em>TestString</em> to the empty string.</li>
  701.  
  702.             <li>'<strong>-d</strong>' (is
  703.             <strong>d</strong>irectory)<br />
  704.              Treats the <em>TestString</em> as a pathname and tests
  705.             if it exists and is a directory.</li>
  706.  
  707.             <li>'<strong>-f</strong>' (is regular
  708.             <strong>f</strong>ile)<br />
  709.              Treats the <em>TestString</em> as a pathname and tests
  710.             if it exists and is a regular file.</li>
  711.  
  712.             <li>'<strong>-s</strong>' (is regular file with
  713.             <strong>s</strong>ize)<br />
  714.              Treats the <em>TestString</em> as a pathname and tests
  715.             if it exists and is a regular file with size greater
  716.             than zero.</li>
  717.  
  718.             <li>'<strong>-l</strong>' (is symbolic
  719.             <strong>l</strong>ink)<br />
  720.              Treats the <em>TestString</em> as a pathname and tests
  721.             if it exists and is a symbolic link.</li>
  722.  
  723.             <li>'<strong>-F</strong>' (is existing file via
  724.             subrequest)<br />
  725.              Checks if <em>TestString</em> is a valid file and
  726.             accessible via all the server's currently-configured
  727.             access controls for that path. This uses an internal
  728.             subrequest to determine the check, so use it with care
  729.             because it decreases your servers performance!</li>
  730.  
  731.             <li>'<strong>-U</strong>' (is existing URL via
  732.             subrequest)<br />
  733.              Checks if <em>TestString</em> is a valid URL and
  734.             accessible via all the server's currently-configured
  735.             access controls for that path. This uses an internal
  736.             subrequest to determine the check, so use it with care
  737.             because it decreases your server's performance!</li>
  738.           </ul>
  739.  
  740. <div class="note"><h3>Notice</h3>
  741.               All of these tests can
  742.               also be prefixed by an exclamation mark ('!') to
  743.               negate their meaning.
  744. </div>
  745.         </li>
  746.       </ol>
  747.  
  748.       <p>Additionally you can set special flags for
  749.       <em>CondPattern</em> by appending</p>
  750.  
  751.       <p class="indent">
  752.         <strong><code>[</code><em>flags</em><code>]</code></strong>
  753.       </p>
  754.  
  755.       <p>as the third argument to the <code>RewriteCond</code>
  756.       directive. <em>Flags</em> is a comma-separated list of the
  757.       following flags:</p>
  758.  
  759.       <ul>
  760.         <li>'<strong><code>nocase|NC</code></strong>'
  761.         (<strong>n</strong>o <strong>c</strong>ase)<br />
  762.          This makes the test case-insensitive, <em>i.e.</em>, there
  763.         is no difference between 'A-Z' and 'a-z' both in the
  764.         expanded <em>TestString</em> and the <em>CondPattern</em>.
  765.         This flag is effective only for comparisons between
  766.         <em>TestString</em> and <em>CondPattern</em>. It has no
  767.         effect on filesystem and subrequest checks.</li>
  768.  
  769.         <li>
  770.           '<strong><code>ornext|OR</code></strong>'
  771.           (<strong>or</strong> next condition)<br />
  772.            Use this to combine rule conditions with a local OR
  773.           instead of the implicit AND. Typical example: 
  774.  
  775. <div class="example"><pre>
  776. RewriteCond %{REMOTE_HOST}  ^host1.*  [OR]
  777. RewriteCond %{REMOTE_HOST}  ^host2.*  [OR]
  778. RewriteCond %{REMOTE_HOST}  ^host3.*
  779. RewriteRule ...some special stuff for any of these hosts...
  780. </pre></div>
  781.  
  782.           Without this flag you would have to write the cond/rule
  783.           three times.
  784.         </li>
  785.       </ul>
  786.  
  787.       <p><strong>Example:</strong></p>
  788.  
  789.        <p>To rewrite the Homepage of a site according to the
  790.         ``<code>User-Agent:</code>'' header of the request, you can
  791.         use the following: </p>
  792.  
  793. <div class="example"><pre>
  794. RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
  795. RewriteRule  ^/$                 /homepage.max.html  [L]
  796.  
  797. RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
  798. RewriteRule  ^/$                 /homepage.min.html  [L]
  799.  
  800. RewriteRule  ^/$                 /homepage.std.html  [L]
  801. </pre></div>
  802.  
  803.         <p>Interpretation: If you use Netscape Navigator as your
  804.         browser (which identifies itself as 'Mozilla'), then you
  805.         get the max homepage, which includes Frames, <em>etc.</em>
  806.         If you use the Lynx browser (which is Terminal-based), then
  807.         you get the min homepage, which contains no images, no
  808.         tables, <em>etc.</em> If you use any other browser you get
  809.         the standard homepage.</p>
  810.  
  811.  
  812. </div>
  813. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  814. <div class="directive-section"><h2><a name="RewriteEngine" id="RewriteEngine">RewriteEngine</a> <a name="rewriteengine" id="rewriteengine">Directive</a></h2>
  815. <table class="directive">
  816. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables or disables runtime rewriting engine</td></tr>
  817. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteEngine on|off</code></td></tr>
  818. <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteEngine off</code></td></tr>
  819. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
  820. <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
  821. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  822. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  823. </table>       
  824.  
  825.       <p>The <code class="directive">RewriteEngine</code> directive enables or
  826.       disables the runtime rewriting engine. If it is set to
  827.       <code>off</code> this module does no runtime processing at
  828.       all. It does not even update the <code>SCRIPT_URx</code>
  829.       environment variables.</p>
  830.  
  831.       <p>Use this directive to disable the module instead of
  832.       commenting out all the <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives!</p>
  833.  
  834.       <p>Note that, by default, rewrite configurations are not
  835.       inherited. This means that you need to have a
  836.       <code>RewriteEngine on</code> directive for each virtual host
  837.       in which you wish to use it.</p>
  838.  
  839. </div>
  840. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  841. <div class="directive-section"><h2><a name="RewriteLock" id="RewriteLock">RewriteLock</a> <a name="rewritelock" id="rewritelock">Directive</a></h2>
  842. <table class="directive">
  843. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of the lock file used for RewriteMap
  844. synchronization</td></tr>
  845. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLock <em>file-path</em></code></td></tr>
  846. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
  847. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  848. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  849. </table>
  850.       <p>This directive sets the filename for a synchronization
  851.       lockfile which mod_rewrite needs to communicate with <code class="directive"><a href="#rewritemap">RewriteMap</a></code>
  852.       <em>programs</em>. Set this lockfile to a local path (not on a
  853.       NFS-mounted device) when you want to use a rewriting
  854.       map-program. It is not required for other types of rewriting
  855.       maps.</p>
  856.  
  857. </div>
  858. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  859. <div class="directive-section"><h2><a name="RewriteLog" id="RewriteLog">RewriteLog</a> <a name="rewritelog" id="rewritelog">Directive</a></h2>
  860. <table class="directive">
  861. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of the file used for logging rewrite engine
  862. processing</td></tr>
  863. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLog <em>file-path</em></code></td></tr>
  864. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
  865. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  866. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  867. </table>
  868.       <p>The <code class="directive">RewriteLog</code> directive sets the name
  869.       of the file to which the server logs any rewriting actions it
  870.       performs. If the name does not begin with a slash
  871.       ('<code>/</code>') then it is assumed to be relative to the
  872.       <em>Server Root</em>. The directive should occur only once per
  873.       server config.</p>
  874.  
  875. <div class="note">    To disable the logging of
  876.           rewriting actions it is not recommended to set
  877.           <em>Filename</em> to <code>/dev/null</code>, because
  878.           although the rewriting engine does not then output to a
  879.           logfile it still creates the logfile output internally.
  880.           <strong>This will slow down the server with no advantage
  881.           to the administrator!</strong> To disable logging either
  882.           remove or comment out the <code class="directive">RewriteLog</code>
  883.           directive or use <code>RewriteLogLevel 0</code>!
  884. </div>
  885.  
  886. <div class="note"><h3>Security</h3>
  887.  
  888. See the <a href="../misc/security_tips.html">Apache Security Tips</a>
  889. document for details on why your security could be compromised if the
  890. directory where logfiles are stored is writable by anyone other than
  891. the user that starts the server.
  892. </div>
  893.  
  894. <div class="example"><h3>Example</h3><p><code>
  895. RewriteLog "/usr/local/var/apache/logs/rewrite.log"
  896. </code></p></div>
  897.  
  898.  
  899. </div>
  900. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  901. <div class="directive-section"><h2><a name="RewriteLogLevel" id="RewriteLogLevel">RewriteLogLevel</a> <a name="rewriteloglevel" id="rewriteloglevel">Directive</a></h2>
  902. <table class="directive">
  903. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the verbosity of the log file used by the rewrite
  904. engine</td></tr>
  905. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLogLevel <em>Level</em></code></td></tr>
  906. <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteLogLevel 0</code></td></tr>
  907. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
  908. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  909. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  910. </table>
  911.       <p>The <code class="directive">RewriteLogLevel</code> directive sets the
  912.       verbosity level of the rewriting logfile. The default level 0
  913.       means no logging, while 9 or more means that practically all
  914.       actions are logged.</p>
  915.  
  916.       <p>To disable the logging of rewriting actions simply set
  917.       <em>Level</em> to 0. This disables all rewrite action
  918.       logs.</p>
  919.  
  920. <div class="note"> Using a high value for
  921.           <em>Level</em> will slow down your Apache server
  922.           dramatically! Use the rewriting logfile at a
  923.           <em>Level</em> greater than 2 only for debugging!
  924. </div>
  925.  
  926. <div class="example"><h3>Example</h3><p><code>
  927. RewriteLogLevel 3
  928. </code></p></div>
  929.  
  930.  
  931. </div>
  932. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  933. <div class="directive-section"><h2><a name="RewriteMap" id="RewriteMap">RewriteMap</a> <a name="rewritemap" id="rewritemap">Directive</a></h2>
  934. <table class="directive">
  935. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a mapping function for key-lookup</td></tr>
  936. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
  937. </code></td></tr>
  938. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
  939. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  940. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  941. <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The choice of different dbm types is available in
  942. Apache 2.0.41 and later</td></tr>
  943. </table>
  944.       <p>The <code class="directive">RewriteMap</code> directive defines a
  945.       <em>Rewriting Map</em> which can be used inside rule
  946.       substitution strings by the mapping-functions to
  947.       insert/substitute fields through a key lookup. The source of
  948.       this lookup can be of various types.</p>
  949.  
  950.       <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
  951.       the name of the map and will be used to specify a
  952.       mapping-function for the substitution strings of a rewriting
  953.       rule via one of the following constructs:</p>
  954.  
  955.       <p class="indent">
  956.         <strong><code>${</code> <em>MapName</em> <code>:</code>
  957.         <em>LookupKey</em> <code>}</code><br />
  958.          <code>${</code> <em>MapName</em> <code>:</code>
  959.         <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
  960.         <code>}</code></strong>
  961.       </p>
  962.  
  963.       <p>When such a construct occurs the map <em>MapName</em> is
  964.       consulted and the key <em>LookupKey</em> is looked-up. If the
  965.       key is found, the map-function construct is substituted by
  966.       <em>SubstValue</em>. If the key is not found then it is
  967.       substituted by <em>DefaultValue</em> or by the empty string
  968.       if no <em>DefaultValue</em> was specified.</p>
  969.  
  970.       <p>The following combinations for <em>MapType</em> and
  971.       <em>MapSource</em> can be used:</p>
  972.  
  973.       <ul>
  974.         <li>
  975.           <strong>Standard Plain Text</strong><br />
  976.            MapType: <code>txt</code>, MapSource: Unix filesystem
  977.           path to valid regular file 
  978.  
  979.           <p>This is the standard rewriting map feature where the
  980.           <em>MapSource</em> is a plain ASCII file containing
  981.           either blank lines, comment lines (starting with a '#'
  982.           character) or pairs like the following - one per
  983.           line.</p>
  984.  
  985.           <p class="indent">
  986.             <strong><em>MatchingKey</em>
  987.             <em>SubstValue</em></strong>
  988.           </p>
  989.  
  990. <div class="example"><h3>Example</h3><pre>
  991. ##
  992. ##  map.txt -- rewriting map
  993. ##
  994.  
  995. Ralf.S.Engelschall    rse   # Bastard Operator From Hell
  996. Mr.Joe.Average        joe   # Mr. Average
  997. </pre></div>
  998.  
  999. <div class="example"><p><code>
  1000. RewriteMap real-to-user txt:/path/to/file/map.txt
  1001. </code></p></div>
  1002.         </li>
  1003.  
  1004.         <li>
  1005.           <strong>Randomized Plain Text</strong><br />
  1006.            MapType: <code>rnd</code>, MapSource: Unix filesystem
  1007.           path to valid regular file 
  1008.  
  1009.           <p>This is identical to the Standard Plain Text variant
  1010.           above but with a special post-processing feature: After
  1011.           looking up a value it is parsed according to contained
  1012.           ``<code>|</code>'' characters which have the meaning of
  1013.           ``or''. In other words they indicate a set of
  1014.           alternatives from which the actual returned value is
  1015.           chosen randomly. Although this sounds crazy and useless,
  1016.           it was actually designed for load balancing in a reverse
  1017.           proxy situation where the looked up values are server
  1018.           names. Example:</p>
  1019.  
  1020. <div class="example"><pre>
  1021. ##
  1022. ##  map.txt -- rewriting map
  1023. ##
  1024.  
  1025. static   www1|www2|www3|www4
  1026. dynamic  www5|www6
  1027. </pre></div>
  1028.  
  1029. <div class="example"><p><code>
  1030. RewriteMap servers rnd:/path/to/file/map.txt
  1031. </code></p></div>
  1032.         </li>
  1033.  
  1034.         <li>
  1035.           <strong>Hash File</strong><br /> MapType:
  1036.           <code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem
  1037.           path to valid regular file
  1038.  
  1039.           <p>Here the source is a binary format DBM file containing
  1040.           the same contents as a <em>Plain Text</em> format file, but
  1041.           in a special representation which is optimized for really
  1042.           fast lookups. The <em>type</em> can be sdbm, gdbm, ndbm, or
  1043.           db depending on <a href="../install.html#dbm">compile-time
  1044.           settings</a>.  If the <em>type</em> is ommitted, the
  1045.           compile-time default will be chosen. You can create such a
  1046.           file with any DBM tool or with the following Perl
  1047.           script.  Be sure to adjust it to create the appropriate
  1048.           type of DBM.  The example creates an NDBM file.</p>
  1049.  
  1050. <div class="example"><pre>
  1051. #!/path/to/bin/perl
  1052. ##
  1053. ##  txt2dbm -- convert txt map to dbm format
  1054. ##
  1055.  
  1056. use NDBM_File;
  1057. use Fcntl;
  1058.  
  1059. ($txtmap, $dbmmap) = @ARGV;
  1060.  
  1061. open(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n";
  1062. tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644)
  1063.   or die "Couldn't create $dbmmap!\n";
  1064.  
  1065. while (<TXT>) {
  1066.   next if (/^\s*#/ or /^\s*$/);
  1067.   $DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/);
  1068. }
  1069.  
  1070. untie %DB;
  1071. close(TXT);
  1072. </pre></div>
  1073.  
  1074. <div class="example"><p><code>
  1075. $ txt2dbm map.txt map.db
  1076. </code></p></div>
  1077.         </li>
  1078.  
  1079.         <li>
  1080.           <strong>Internal Function</strong><br />
  1081.            MapType: <code>int</code>, MapSource: Internal Apache
  1082.           function 
  1083.  
  1084.           <p>Here the source is an internal Apache function.
  1085.           Currently you cannot create your own, but the following
  1086.           functions already exists:</p>
  1087.  
  1088.           <ul>
  1089.             <li><strong>toupper</strong>:<br />
  1090.              Converts the looked up key to all upper case.</li>
  1091.  
  1092.             <li><strong>tolower</strong>:<br />
  1093.              Converts the looked up key to all lower case.</li>
  1094.  
  1095.             <li><strong>escape</strong>:<br />
  1096.              Translates special characters in the looked up key to
  1097.             hex-encodings.</li>
  1098.  
  1099.             <li><strong>unescape</strong>:<br />
  1100.              Translates hex-encodings in the looked up key back to
  1101.             special characters.</li>
  1102.           </ul>
  1103.         </li>
  1104.  
  1105.         <li>
  1106.           <strong>External Rewriting Program</strong><br />
  1107.            MapType: <code>prg</code>, MapSource: Unix filesystem
  1108.           path to valid regular file 
  1109.  
  1110.           <p>Here the source is a program, not a map file. To
  1111.           create it you can use the language of your choice, but
  1112.           the result has to be a executable (<em>i.e.</em>, either
  1113.           object-code or a script with the magic cookie trick
  1114.           '<code>#!/path/to/interpreter</code>' as the first
  1115.           line).</p>
  1116.  
  1117.           <p>This program is started once at startup of the Apache
  1118.           servers and then communicates with the rewriting engine
  1119.           over its <code>stdin</code> and <code>stdout</code>
  1120.           file-handles. For each map-function lookup it will
  1121.           receive the key to lookup as a newline-terminated string
  1122.           on <code>stdin</code>. It then has to give back the
  1123.           looked-up value as a newline-terminated string on
  1124.           <code>stdout</code> or the four-character string
  1125.           ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there
  1126.           is no corresponding value for the given key). A trivial
  1127.           program which will implement a 1:1 map (<em>i.e.</em>,
  1128.           key == value) could be:</p>
  1129.  
  1130. <div class="example"><pre>
  1131. #!/usr/bin/perl
  1132. $| = 1;
  1133. while (<STDIN>) {
  1134.     # ...put here any transformations or lookups...
  1135.     print $_;
  1136. }
  1137. </pre></div>
  1138.  
  1139.           <p>But be very careful:</p>
  1140.  
  1141.           <ol>
  1142.             <li>``<em>Keep it simple, stupid</em>'' (KISS), because
  1143.             if this program hangs it will hang the Apache server
  1144.             when the rule occurs.</li>
  1145.  
  1146.             <li>Avoid one common mistake: never do buffered I/O on
  1147.             <code>stdout</code>! This will cause a deadloop! Hence
  1148.             the ``<code>$|=1</code>'' in the above example...</li>
  1149.  
  1150.             <li>Use the <code class="directive"><a href="#rewritelock">RewriteLock</a></code> directive to
  1151.             define a lockfile mod_rewrite can use to synchronize the
  1152.             communication to the program. By default no such
  1153.             synchronization takes place.</li>
  1154.           </ol>
  1155.         </li>
  1156.       </ul>
  1157.       <p>The <code class="directive">RewriteMap</code> directive can occur more than
  1158.       once. For each mapping-function use one
  1159.       <code class="directive">RewriteMap</code> directive to declare its rewriting
  1160.       mapfile. While you cannot <strong>declare</strong> a map in
  1161.       per-directory context it is of course possible to
  1162.       <strong>use</strong> this map in per-directory context. </p>
  1163.  
  1164. <div class="note"><h3>Note</h3> For plain text and DBM format files the
  1165. looked-up keys are cached in-core until the <code>mtime</code> of the
  1166. mapfile changes or the server does a restart. This way you can have
  1167. map-functions in rules which are used for <strong>every</strong>
  1168. request.  This is no problem, because the external lookup only happens
  1169. once!
  1170. </div>
  1171.  
  1172.  
  1173. </div>
  1174. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  1175. <div class="directive-section"><h2><a name="RewriteOptions" id="RewriteOptions">RewriteOptions</a> <a name="rewriteoptions" id="rewriteoptions">Directive</a></h2>
  1176. <table class="directive">
  1177. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets some special options for the rewrite engine</td></tr>
  1178. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteOptions <var>Options</var></code></td></tr>
  1179. <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteOptions MaxRedirects=10</code></td></tr>
  1180. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
  1181. <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
  1182. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  1183. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  1184. <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><code>MaxRedirects</code> is available in Apache 2.0.45 and
  1185. later</td></tr>
  1186. </table>
  1187.  
  1188.       <p>The <code class="directive">RewriteOptions</code> directive sets some
  1189.       special options for the current per-server or per-directory
  1190.       configuration. The <em>Option</em> strings can be one of the
  1191.       following:</p>
  1192.  
  1193.       <dl>
  1194.       <dt><code>inherit</code></dt>
  1195.       <dd>This forces the current configuration to inherit the
  1196.       configuration of the parent. In per-virtual-server context
  1197.       this means that the maps, conditions and rules of the main
  1198.       server are inherited. In per-directory context this means
  1199.       that conditions and rules of the parent directory's
  1200.       <code>.htaccess</code> configuration are inherited.</dd>
  1201.  
  1202.       <dt><code>MaxRedirects=<var>number</var></code></dt>
  1203.       <dd>In order to prevent endless loops of internal redirects
  1204.       issued by per-directory <code class="directive"><a href="#rewriterule">RewriteRule</a></code>s, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> aborts
  1205.       the request after reaching a maximum number of such redirects and
  1206.       responds with an 500 Internal Server Error. If you really need
  1207.       more internal redirects than 10 per request, you may increase
  1208.       the default to the desired value.</dd>
  1209.       </dl>
  1210.  
  1211. </div>
  1212. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  1213. <div class="directive-section"><h2><a name="RewriteRule" id="RewriteRule">RewriteRule</a> <a name="rewriterule" id="rewriterule">Directive</a></h2>
  1214. <table class="directive">
  1215. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines rules for the rewriting engine</td></tr>
  1216. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteRule
  1217.       <em>Pattern</em> <em>Substitution</em></code></td></tr>
  1218. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
  1219. <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
  1220. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  1221. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  1222. <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The cookie-flag is available in Apache 2.0.40 and later.</td></tr>
  1223. </table>
  1224.       <p>The <code class="directive">RewriteRule</code> directive is the real
  1225.       rewriting workhorse. The directive can occur more than once.
  1226.       Each directive then defines one single rewriting rule. The
  1227.       <strong>definition order</strong> of these rules is
  1228.       <strong>important</strong>, because this order is used when
  1229.       applying the rules at run-time.</p>
  1230.  
  1231.       <p><a id="patterns" name="patterns"><em>Pattern</em></a> is
  1232.       a perl compatible <a id="regexp" name="regexp">regular
  1233.       expression</a> which gets applied to the current URL. Here
  1234.       ``current'' means the value of the URL when this rule gets
  1235.       applied. This may not be the originally requested URL,
  1236.       because any number of rules may already have matched and made
  1237.       alterations to it.</p>
  1238.  
  1239.       <p>Some hints about the syntax of regular expressions:</p>
  1240.  
  1241. <div class="note"><pre>
  1242. <strong>Text:</strong>
  1243.   <strong><code>.</code></strong>           Any single character
  1244.   <strong><code>[</code></strong>chars<strong><code>]</code></strong>     Character class: One  of chars
  1245.   <strong><code>[^</code></strong>chars<strong><code>]</code></strong>    Character class: None of chars
  1246.   text1<strong><code>|</code></strong>text2 Alternative: text1 or text2
  1247.  
  1248. <strong>Quantifiers:</strong>
  1249.   <strong><code>?</code></strong>           0 or 1 of the preceding text
  1250.   <strong><code>*</code></strong>           0 or N of the preceding text (N > 0)
  1251.   <strong><code>+</code></strong>           1 or N of the preceding text (N > 1)
  1252.  
  1253. <strong>Grouping:</strong>
  1254.   <strong><code>(</code></strong>text<strong><code>)</code></strong>      Grouping of text
  1255.               (either to set the borders of an alternative or
  1256.               for making backreferences where the <strong>N</strong>th group can 
  1257.               be used on the RHS of a RewriteRule with <code>$</code><strong>N</strong>)
  1258.  
  1259. <strong>Anchors:</strong>
  1260.   <strong><code>^</code></strong>           Start of line anchor
  1261.   <strong><code>$</code></strong>           End   of line anchor
  1262.  
  1263. <strong>Escaping:</strong>
  1264.   <strong><code>\</code></strong>char       escape that particular char
  1265.               (for instance to specify the chars "<code>.[]()</code>" <em>etc.</em>)
  1266. </pre></div>
  1267.  
  1268.       <p>For more information about regular expressions have a look at the
  1269.       perl regular expression manpage ("<a href="http://www.perldoc.com/perl5.6.1/pod/perlre.html">perldoc
  1270.       perlre</a>"). If you are interested in more detailed
  1271.       information about regular expressions and their variants
  1272.       (POSIX regex <em>etc.</em>) have a look at the
  1273.       following dedicated book on this topic:</p>
  1274.  
  1275.       <p class="indent">
  1276.         <em>Mastering Regular Expressions</em><br />
  1277.          Jeffrey E.F. Friedl<br />
  1278.          Nutshell Handbook Series<br />
  1279.          O'Reilly & Associates, Inc. 1997<br />
  1280.          ISBN 1-56592-257-3<br />
  1281.       </p>
  1282.  
  1283.       <p>Additionally in mod_rewrite the NOT character
  1284.       ('<code>!</code>') is a possible pattern prefix. This gives
  1285.       you the ability to negate a pattern; to say, for instance:
  1286.       ``<em>if the current URL does <strong>NOT</strong> match this
  1287.       pattern</em>''. This can be used for exceptional cases, where
  1288.       it is easier to match the negative pattern, or as a last
  1289.       default rule.</p>
  1290.  
  1291. <div class="note"><h3>Notice</h3>
  1292. When using the NOT character
  1293.           to negate a pattern you cannot have grouped wildcard
  1294.           parts in the pattern. This is impossible because when the
  1295.           pattern does NOT match, there are no contents for the
  1296.           groups. In consequence, if negated patterns are used, you
  1297.           cannot use <code>$N</code> in the substitution
  1298.           string!
  1299. </div>
  1300.  
  1301.       <p><a id="rhs" name="rhs"><em>Substitution</em></a> of a
  1302.       rewriting rule is the string which is substituted for (or
  1303.       replaces) the original URL for which <em>Pattern</em>
  1304.       matched. Beside plain text you can use</p>
  1305.  
  1306.       <ol>
  1307.         <li>back-references <code>$N</code> to the RewriteRule
  1308.         pattern</li>
  1309.  
  1310.         <li>back-references <code>%N</code> to the last matched
  1311.         RewriteCond pattern</li>
  1312.  
  1313.         <li>server-variables as in rule condition test-strings
  1314.         (<code>%{VARNAME}</code>)</li>
  1315.  
  1316.         <li><a href="#mapfunc">mapping-function</a> calls
  1317.         (<code>${mapname:key|default}</code>)</li>
  1318.       </ol>
  1319.       <p>Back-references are <code>$</code><strong>N</strong>
  1320.       (<strong>N</strong>=0..9) identifiers which will be replaced
  1321.       by the contents of the <strong>N</strong>th group of the
  1322.       matched <em>Pattern</em>. The server-variables are the same
  1323.       as for the <em>TestString</em> of a <code>RewriteCond</code>
  1324.       directive. The mapping-functions come from the
  1325.       <code>RewriteMap</code> directive and are explained there.
  1326.       These three types of variables are expanded in the order of
  1327.       the above list. </p>
  1328.  
  1329.       <p>As already mentioned above, all the rewriting rules are
  1330.       applied to the <em>Substitution</em> (in the order of
  1331.       definition in the config file). The URL is <strong>completely
  1332.       replaced</strong> by the <em>Substitution</em> and the
  1333.       rewriting process goes on until there are no more rules
  1334.       unless explicitly terminated by a
  1335.       <code><strong>L</strong></code> flag - see below.</p>
  1336.  
  1337.       <p>There is a special substitution string named
  1338.       '<code>-</code>' which means: <strong>NO
  1339.       substitution</strong>! Sounds silly? No, it is useful to
  1340.       provide rewriting rules which <strong>only</strong> match
  1341.       some URLs but do no substitution, <em>e.g.</em>, in
  1342.       conjunction with the <strong>C</strong> (chain) flag to be
  1343.       able to have more than one pattern to be applied before a
  1344.       substitution occurs.</p>
  1345.  
  1346. <div class="note"><h3>Query String</h3>
  1347.       <p>The <em>Pattern</em> will not match against the query string.
  1348.       Instead, you must use a <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
  1349.       <code>%{QUERY_STRING}</code> variable.  You can, however, create
  1350.       URLs in the substitution string containing a query string
  1351.       part. Just use a question mark inside the substitution string to
  1352.       indicate that the following stuff should be re-injected into the
  1353.       query string. When you want to erase an existing query string,
  1354.       end the substitution string with just the question mark.  To
  1355.       combine a new query string with an old one, use the
  1356.       <code>[QSA]</code> flag (see below).</p>
  1357. </div>
  1358.  
  1359. <div class="note"><h3>Substitution of Absolute URLs</h3>
  1360.           <p>There is a special feature:
  1361.           When you prefix a substitution field with
  1362.           <code>http://</code><em>thishost</em>[<em>:thisport</em>]
  1363.           then <strong>mod_rewrite</strong> automatically strips it
  1364.           out. This auto-reduction on implicit external redirect
  1365.           URLs is a useful and important feature when used in
  1366.           combination with a mapping-function which generates the
  1367.           hostname part. Have a look at the first example in the
  1368.           example section below to understand this.</p>
  1369.  
  1370.           <p><strong>Remember:</strong> An unconditional external
  1371.           redirect to your own server will not work with the prefix
  1372.           <code>http://thishost</code> because of this feature. To
  1373.           achieve such a self-redirect, you have to use the
  1374.           <strong>R</strong>-flag (see below).</p>
  1375. </div>
  1376.  
  1377.       <p>Additionally you can set special flags for
  1378.       <em>Substitution</em> by appending</p>
  1379.  
  1380.       <p class="indent">
  1381.         <strong><code>[</code><em>flags</em><code>]</code></strong>
  1382.       </p>
  1383.       <p>
  1384.       as the third argument to the <code>RewriteRule</code>
  1385.       directive. <em>Flags</em> is a comma-separated list of the
  1386.       following flags: </p>
  1387.  
  1388.       <ul>
  1389.         <li>
  1390.           '<strong><code>redirect|R</code>
  1391.           [=<em>code</em>]</strong>' (force <a id="redirect" name="redirect"><strong>r</strong>edirect</a>)<br />
  1392.            Prefix <em>Substitution</em> with
  1393.           <code>http://thishost[:thisport]/</code> (which makes the
  1394.           new URL a URI) to force a external redirection. If no
  1395.           <em>code</em> is given a HTTP response of 302 (MOVED
  1396.           TEMPORARILY) is used. If you want to use other response
  1397.           codes in the range 300-400 just specify them as a number
  1398.           or use one of the following symbolic names:
  1399.           <code>temp</code> (default), <code>permanent</code>,
  1400.           <code>seeother</code>. Use it for rules which should
  1401.           canonicalize the URL and give it back to the client,
  1402.           <em>e.g.</em>, translate ``<code>/~</code>'' into
  1403.           ``<code>/u/</code>'' or always append a slash to
  1404.           <code>/u/</code><em>user</em>, etc.<br />
  1405.            
  1406.  
  1407.           <p><strong>Note:</strong> When you use this flag, make
  1408.           sure that the substitution field is a valid URL! If not,
  1409.           you are redirecting to an invalid location! And remember
  1410.           that this flag itself only prefixes the URL with
  1411.           <code>http://thishost[:thisport]/</code>, rewriting
  1412.           continues. Usually you also want to stop and do the
  1413.           redirection immediately. To stop the rewriting you also
  1414.           have to provide the 'L' flag.</p>
  1415.         </li>
  1416.  
  1417.         <li>'<strong><code>forbidden|F</code></strong>' (force URL
  1418.         to be <strong>f</strong>orbidden)<br />
  1419.          This forces the current URL to be forbidden,
  1420.         <em>i.e.</em>, it immediately sends back a HTTP response of
  1421.         403 (FORBIDDEN). Use this flag in conjunction with
  1422.         appropriate RewriteConds to conditionally block some
  1423.         URLs.</li>
  1424.  
  1425.         <li>'<strong><code>gone|G</code></strong>' (force URL to be
  1426.         <strong>g</strong>one)<br />
  1427.          This forces the current URL to be gone, <em>i.e.</em>, it
  1428.         immediately sends back a HTTP response of 410 (GONE). Use
  1429.         this flag to mark pages which no longer exist as gone.</li>
  1430.  
  1431.         <li>
  1432.           '<strong><code>proxy|P</code></strong>' (force
  1433.           <strong>p</strong>roxy)<br />
  1434.            This flag forces the substitution part to be internally
  1435.           forced as a proxy request and immediately (<em>i.e.</em>,
  1436.           rewriting rule processing stops here) put through the <a href="mod_proxy.html">proxy module</a>. You have to make
  1437.           sure that the substitution string is a valid URI
  1438.           (<em>e.g.</em>, typically starting with
  1439.           <code>http://</code><em>hostname</em>) which can be
  1440.           handled by the Apache proxy module. If not you get an
  1441.           error from the proxy module. Use this flag to achieve a
  1442.           more powerful implementation of the <a href="mod_proxy.html#proxypass">ProxyPass</a> directive,
  1443.           to map some remote stuff into the namespace of the local
  1444.           server. 
  1445.  
  1446.           <p>Notice: To use this functionality make sure you have
  1447.           the proxy module compiled into your Apache server
  1448.           program. If you don't know please check whether
  1449.           <code>mod_proxy.c</code> is part of the ``<code>httpd
  1450.           -l</code>'' output. If yes, this functionality is
  1451.           available to mod_rewrite. If not, then you first have to
  1452.           rebuild the ``<code>httpd</code>'' program with mod_proxy
  1453.           enabled.</p>
  1454.         </li>
  1455.  
  1456.         <li>'<strong><code>last|L</code></strong>'
  1457.         (<strong>l</strong>ast rule)<br />
  1458.          Stop the rewriting process here and don't apply any more
  1459.         rewriting rules. This corresponds to the Perl
  1460.         <code>last</code> command or the <code>break</code> command
  1461.         from the C language. Use this flag to prevent the currently
  1462.         rewritten URL from being rewritten further by following
  1463.         rules. For example, use it to rewrite the root-path URL
  1464.         ('<code>/</code>') to a real one, <em>e.g.</em>,
  1465.         '<code>/e/www/</code>'.</li>
  1466.  
  1467.         <li>'<strong><code>next|N</code></strong>'
  1468.         (<strong>n</strong>ext round)<br />
  1469.          Re-run the rewriting process (starting again with the
  1470.         first rewriting rule). Here the URL to match is again not
  1471.         the original URL but the URL from the last rewriting rule.
  1472.         This corresponds to the Perl <code>next</code> command or
  1473.         the <code>continue</code> command from the C language. Use
  1474.         this flag to restart the rewriting process, <em>i.e.</em>,
  1475.         to immediately go to the top of the loop.<br />
  1476.          <strong>But be careful not to create an infinite
  1477.         loop!</strong></li>
  1478.  
  1479.         <li>'<strong><code>chain|C</code></strong>'
  1480.         (<strong>c</strong>hained with next rule)<br />
  1481.          This flag chains the current rule with the next rule
  1482.         (which itself can be chained with the following rule,
  1483.         <em>etc.</em>). This has the following effect: if a rule
  1484.         matches, then processing continues as usual, <em>i.e.</em>,
  1485.         the flag has no effect. If the rule does
  1486.         <strong>not</strong> match, then all following chained
  1487.         rules are skipped. For instance, use it to remove the
  1488.         ``<code>.www</code>'' part inside a per-directory rule set
  1489.         when you let an external redirect happen (where the
  1490.         ``<code>.www</code>'' part should not to occur!).</li>
  1491.  
  1492.         <li>
  1493.         '<strong><code>type|T</code></strong>=<em>MIME-type</em>'
  1494.         (force MIME <strong>t</strong>ype)<br />
  1495.          Force the MIME-type of the target file to be
  1496.         <em>MIME-type</em>. For instance, this can be used to
  1497.         simulate the <code>mod_alias</code> directive
  1498.         <code>ScriptAlias</code> which internally forces all files
  1499.         inside the mapped directory to have a MIME type of
  1500.         ``<code>application/x-httpd-cgi</code>''.</li>
  1501.  
  1502.         <li>
  1503.           '<strong><code>nosubreq|NS</code></strong>' (used only if
  1504.           <strong>n</strong>o internal
  1505.           <strong>s</strong>ub-request)<br />
  1506.            This flag forces the rewriting engine to skip a
  1507.           rewriting rule if the current request is an internal
  1508.           sub-request. For instance, sub-requests occur internally
  1509.           in Apache when <code>mod_include</code> tries to find out
  1510.           information about possible directory default files
  1511.           (<code>index.xxx</code>). On sub-requests it is not
  1512.           always useful and even sometimes causes a failure to if
  1513.           the complete set of rules are applied. Use this flag to
  1514.           exclude some rules.<br />
  1515.            
  1516.  
  1517.           <p>Use the following rule for your decision: whenever you
  1518.           prefix some URLs with CGI-scripts to force them to be
  1519.           processed by the CGI-script, the chance is high that you
  1520.           will run into problems (or even overhead) on
  1521.           sub-requests. In these cases, use this flag.</p>
  1522.         </li>
  1523.  
  1524.         <li>'<strong><code>nocase|NC</code></strong>'
  1525.         (<strong>n</strong>o <strong>c</strong>ase)<br />
  1526.          This makes the <em>Pattern</em> case-insensitive,
  1527.         <em>i.e.</em>, there is no difference between 'A-Z' and
  1528.         'a-z' when <em>Pattern</em> is matched against the current
  1529.         URL.</li>
  1530.  
  1531.         <li>'<strong><code>qsappend|QSA</code></strong>'
  1532.         (<strong>q</strong>uery <strong>s</strong>tring
  1533.         <strong>a</strong>ppend)<br />
  1534.          This flag forces the rewriting engine to append a query
  1535.         string part in the substitution string to the existing one
  1536.         instead of replacing it. Use this when you want to add more
  1537.         data to the query string via a rewrite rule.</li>
  1538.  
  1539.         <li>
  1540.           '<strong><code>noescape|NE</code></strong>'
  1541.           (<strong>n</strong>o URI <strong>e</strong>scaping of
  1542.           output)<br />
  1543.            This flag keeps mod_rewrite from applying the usual URI
  1544.           escaping rules to the result of a rewrite. Ordinarily,
  1545.           special characters (such as '%', '$', ';', and so on)
  1546.           will be escaped into their hexcode equivalents ('%25',
  1547.           '%24', and '%3B', respectively); this flag prevents this
  1548.           from being done. This allows percent symbols to appear in
  1549.           the output, as in 
  1550. <div class="example"><p><code>
  1551.     RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
  1552. </code></p></div>
  1553.  
  1554.           which would turn '<code>/foo/zed</code>' into a safe
  1555.           request for '<code>/bar?arg=P1=zed</code>'. 
  1556.         </li>
  1557.  
  1558.         <li>
  1559.           '<strong><code>passthrough|PT</code></strong>'
  1560.           (<strong>p</strong>ass <strong>t</strong>hrough to next
  1561.           handler)<br />
  1562.            This flag forces the rewriting engine to set the
  1563.           <code>uri</code> field of the internal
  1564.           <code>request_rec</code> structure to the value of the
  1565.           <code>filename</code> field. This flag is just a hack to
  1566.           be able to post-process the output of
  1567.           <code>RewriteRule</code> directives by
  1568.           <code>Alias</code>, <code>ScriptAlias</code>,
  1569.           <code>Redirect</code>, <em>etc.</em> directives from
  1570.           other URI-to-filename translators. A trivial example to
  1571.           show the semantics: If you want to rewrite
  1572.           <code>/abc</code> to <code>/def</code> via the rewriting
  1573.           engine of <code>mod_rewrite</code> and then
  1574.           <code>/def</code> to <code>/ghi</code> with
  1575.           <code>mod_alias</code>: 
  1576. <div class="example"><p><code>
  1577.     RewriteRule ^/abc(.*)  /def$1 [PT]<br />
  1578.     Alias       /def       /ghi
  1579. </code></p></div>
  1580.           If you omit the <code>PT</code> flag then
  1581.           <code>mod_rewrite</code> will do its job fine,
  1582.           <em>i.e.</em>, it rewrites <code>uri=/abc/...</code> to
  1583.           <code>filename=/def/...</code> as a full API-compliant
  1584.           URI-to-filename translator should do. Then
  1585.           <code>mod_alias</code> comes and tries to do a
  1586.           URI-to-filename transition which will not work. 
  1587.  
  1588.           <p>Note: <strong>You have to use this flag if you want to
  1589.           intermix directives of different modules which contain
  1590.           URL-to-filename translators</strong>. The typical example
  1591.           is the use of <code>mod_alias</code> and
  1592.           <code>mod_rewrite</code>..</p>
  1593.         </li>
  1594.  
  1595.         <li>'<strong><code>skip|S</code></strong>=<em>num</em>'
  1596.         (<strong>s</strong>kip next rule(s))<br />
  1597.          This flag forces the rewriting engine to skip the next
  1598.         <em>num</em> rules in sequence when the current rule
  1599.         matches. Use this to make pseudo if-then-else constructs:
  1600.         The last rule of the then-clause becomes
  1601.         <code>skip=N</code> where N is the number of rules in the
  1602.         else-clause. (This is <strong>not</strong> the same as the
  1603.         'chain|C' flag!)</li>
  1604.  
  1605.         <li>
  1606.         '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>'
  1607.         (set <strong>e</strong>nvironment variable)<br />
  1608.          This forces an environment variable named <em>VAR</em> to
  1609.         be set to the value <em>VAL</em>, where <em>VAL</em> can
  1610.         contain regexp backreferences <code>$N</code> and
  1611.         <code>%N</code> which will be expanded. You can use this
  1612.         flag more than once to set more than one variable. The
  1613.         variables can be later dereferenced in many situations, but
  1614.         usually from within XSSI (via <code><!--#echo
  1615.         var="VAR"--></code>) or CGI (<em>e.g.</em>
  1616.         <code>$ENV{'VAR'}</code>). Additionally you can dereference
  1617.         it in a following RewriteCond pattern via
  1618.         <code>%{ENV:VAR}</code>. Use this to strip but remember
  1619.         information from URLs.</li>
  1620.  
  1621.         <li>
  1622.         '<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
  1623.         (set <strong>co</strong>okie)<br />
  1624.         This sets a cookie on the client's browser.  The cookie's name
  1625.         is specified by <em>NAME</em> and the value is
  1626.         <em>VAL</em>. The <em>domain</em> field is the domain of the
  1627.         cookie, such as '.apache.org',the optional <em>lifetime</em>
  1628.     is the lifetime of the cookie in minutes, and the optional 
  1629.     <em>path</em> is the path of the cookie</li>
  1630.  
  1631.       </ul>
  1632.  
  1633. <div class="note"><h3>Note</h3> Never forget that <em>Pattern</em> is
  1634. applied to a complete URL in per-server configuration
  1635. files. <strong>But in per-directory configuration files, the
  1636. per-directory prefix (which always is the same for a specific
  1637. directory!) is automatically <em>removed</em> for the pattern matching
  1638. and automatically <em>added</em> after the substitution has been
  1639. done.</strong> This feature is essential for many sorts of rewriting,
  1640. because without this prefix stripping you have to match the parent
  1641. directory which is not always possible.
  1642.  
  1643.             <p>There is one exception: If a substitution string
  1644.             starts with ``<code>http://</code>'' then the directory
  1645.             prefix will <strong>not</strong> be added and an
  1646.             external redirect or proxy throughput (if flag
  1647.             <strong>P</strong> is used!) is forced!</p>
  1648. </div>
  1649.  
  1650. <div class="note"><h3>Note</h3>
  1651.  To enable the rewriting engine
  1652.           for per-directory configuration files you need to set
  1653.           ``<code>RewriteEngine On</code>'' in these files
  1654.           <strong>and</strong> ``<code>Options
  1655.           FollowSymLinks</code>'' must be enabled. If your
  1656.           administrator has disabled override of
  1657.           <code>FollowSymLinks</code> for a user's directory, then
  1658.           you cannot use the rewriting engine. This restriction is
  1659.           needed for security reasons.
  1660. </div>
  1661.  
  1662.       <p>Here are all possible substitution combinations and their
  1663.       meanings:</p>
  1664.  
  1665.       <p><strong>Inside per-server configuration
  1666.       (<code>httpd.conf</code>)<br />
  1667.        for request ``<code>GET
  1668.       /somepath/pathinfo</code>'':</strong><br />
  1669.       </p>
  1670.  
  1671. <div class="note"><pre>
  1672. <strong>Given Rule</strong>                                      <strong>Resulting Substitution</strong>
  1673. ----------------------------------------------  ----------------------------------
  1674. ^/somepath(.*) otherpath$1                      not supported, because invalid!
  1675.  
  1676. ^/somepath(.*) otherpath$1  [R]                 not supported, because invalid!
  1677.  
  1678. ^/somepath(.*) otherpath$1  [P]                 not supported, because invalid!
  1679. ----------------------------------------------  ----------------------------------
  1680. ^/somepath(.*) /otherpath$1                     /otherpath/pathinfo
  1681.  
  1682. ^/somepath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
  1683.                                                 via external redirection
  1684.  
  1685. ^/somepath(.*) /otherpath$1 [P]                 not supported, because silly!
  1686. ----------------------------------------------  ----------------------------------
  1687. ^/somepath(.*) http://thishost/otherpath$1      /otherpath/pathinfo
  1688.  
  1689. ^/somepath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
  1690.                                                 via external redirection
  1691.  
  1692. ^/somepath(.*) http://thishost/otherpath$1 [P]  not supported, because silly!
  1693. ----------------------------------------------  ----------------------------------
  1694. ^/somepath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
  1695.                                                 via external redirection
  1696.  
  1697. ^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
  1698.                                                 via external redirection
  1699.                                                 (the [R] flag is redundant)
  1700.  
  1701. ^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
  1702.                                                 via internal proxy
  1703. </pre></div>
  1704.  
  1705.       <p><strong>Inside per-directory configuration for
  1706.       <code>/somepath</code><br />
  1707.        (<em>i.e.</em>, file <code>.htaccess</code> in dir
  1708.       <code>/physical/path/to/somepath</code> containing
  1709.       <code>RewriteBase /somepath</code>)<br />
  1710.        for request ``<code>GET
  1711.       /somepath/localpath/pathinfo</code>'':</strong><br /> 
  1712.      </p>
  1713.  
  1714. <div class="note"><pre>
  1715. <strong>Given Rule</strong>                                      <strong>Resulting Substitution</strong>
  1716. ----------------------------------------------  ----------------------------------
  1717. ^localpath(.*) otherpath$1                      /somepath/otherpath/pathinfo
  1718.  
  1719. ^localpath(.*) otherpath$1  [R]                 http://thishost/somepath/otherpath/pathinfo
  1720.                                                 via external redirection
  1721.  
  1722. ^localpath(.*) otherpath$1  [P]                 not supported, because silly!
  1723. ----------------------------------------------  ----------------------------------
  1724. ^localpath(.*) /otherpath$1                     /otherpath/pathinfo
  1725.  
  1726. ^localpath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
  1727.                                                 via external redirection
  1728.  
  1729. ^localpath(.*) /otherpath$1 [P]                 not supported, because silly!
  1730. ----------------------------------------------  ----------------------------------
  1731. ^localpath(.*) http://thishost/otherpath$1      /otherpath/pathinfo
  1732.  
  1733. ^localpath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
  1734.                                                 via external redirection
  1735.  
  1736. ^localpath(.*) http://thishost/otherpath$1 [P]  not supported, because silly!
  1737. ----------------------------------------------  ----------------------------------
  1738. ^localpath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
  1739.                                                 via external redirection
  1740.  
  1741. ^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
  1742.                                                 via external redirection
  1743.                                                 (the [R] flag is redundant)
  1744.  
  1745. ^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
  1746.                                                 via internal proxy
  1747. </pre></div>
  1748.  
  1749.       <p><strong>Example:</strong></p>
  1750.  
  1751.       <p>We want to rewrite URLs of the form </p>
  1752.  
  1753.         <p class="indent">
  1754.           <code>/</code> <em>Language</em> <code>/~</code>
  1755.           <em>Realname</em> <code>/.../</code> <em>File</em>
  1756.         </p>
  1757.  
  1758.         <p>into </p>
  1759.  
  1760.         <p class="indent">
  1761.           <code>/u/</code> <em>Username</em> <code>/.../</code>
  1762.           <em>File</em> <code>.</code> <em>Language</em>
  1763.         </p>
  1764.  
  1765.         <p>We take the rewrite mapfile from above and save it under
  1766.         <code>/path/to/file/map.txt</code>. Then we only have to
  1767.         add the following lines to the Apache server configuration
  1768.         file:</p>
  1769.  
  1770. <div class="example"><pre>
  1771. RewriteLog   /path/to/file/rewrite.log
  1772. RewriteMap   real-to-user               txt:/path/to/file/map.txt
  1773. RewriteRule  ^/([^/]+)/~([^/]+)/(.*)$   /u/${real-to-user:$2|nobody}/$3.$1
  1774. </pre></div>
  1775.   
  1776. </div>
  1777. </div>
  1778. <div class="bottomlang">
  1779. <p><span>Available Languages: </span><a href="../en/mod/mod_rewrite.html" title="English"> en </a></p>
  1780. </div><div id="footer">
  1781. <p class="apache">Copyright 1999-2004 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>
  1782. <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
  1783. </body></html>