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