| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document url="index.html"> |
| |
| &project; |
| |
| <properties> |
| <author email="remm@apache.org">Remy Maucherat</author> |
| <title>The rewrite Valve</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Introduction"> |
| |
| <p>The rewrite valve implements URL rewrite functionality in a way that is |
| very similar to mod_rewrite from Apache HTTP Server.</p> |
| |
| </section> |
| |
| <section name="Configuration"> |
| |
| <p>The rewrite valve is configured as a valve using the <code>org.apache.catalina.valves.rewrite.RewriteValve</code> |
| class name.</p> |
| |
| <p>The rewrite valve can be configured as a valve added in a Host. |
| See <a href="config/host.html">virtual-server</a> documentation for |
| informations how to configure it. It will use a <code>rewrite.config</code> file |
| containing the rewrite directives, it must be placed in the Host configuration |
| folder. |
| </p> |
| |
| <p>It can also be in the context.xml of a webapp. |
| The valve will then use a <code>rewrite.config</code> file containing the |
| rewrite directives, it must be placed in the WEB-INF folder of the web application |
| </p> |
| |
| </section> |
| |
| <section name="Directives"> |
| |
| <p>The rewrite.config file contains a list of directives which closely |
| resemble the directives used by mod_rewrite, in particular the central |
| RewriteRule and RewriteCond directives. Lines that start with a |
| <code>#</code> character are treated as comments and will be ignored.</p> |
| |
| <p>Note: This section is a modified version of the mod_rewrite documentation, |
| which is Copyright 1995-2006 The Apache Software Foundation, and licensed under the |
| under the Apache License, Version 2.0.</p> |
| |
| <subsection name="RewriteCond"> |
| |
| <p>Syntax: <code>RewriteCond TestString CondPattern</code></p> |
| |
| <p>The RewriteCond directive defines a rule condition. One or more RewriteCond |
| can precede a RewriteRule directive. The following rule is then only used if both |
| the current state of the URI matches its pattern, and if these conditions are met.</p> |
| |
| <p><em>TestString</em> is a string which can contain the |
| following expanded constructs in addition to plain text:</p> |
| |
| <ul> |
| <li> |
| <strong>RewriteRule backreferences</strong>: These are |
| backreferences of the form <strong><code>$N</code></strong> |
| (0 <= N <= 9), which provide access to the grouped |
| parts (in parentheses) of the pattern, from the |
| <code>RewriteRule</code> which is subject to the current |
| set of <code>RewriteCond</code> conditions.. |
| </li> |
| <li> |
| <strong>RewriteCond backreferences</strong>: These are |
| backreferences of the form <strong><code>%N</code></strong> |
| (1 <= N <= 9), which provide access to the grouped |
| parts (again, in parentheses) of the pattern, from the last matched |
| <code>RewriteCond</code> in the current set |
| of conditions. |
| </li> |
| <li> |
| <strong>RewriteMap expansions</strong>: These are |
| expansions of the form <strong><code |
| >${mapname:key|default}</code></strong>. |
| See <a href="#mapfunc">the documentation for |
| RewriteMap</a> for more details. |
| </li> |
| <li> |
| <strong>Server-Variables</strong>: These are variables of |
| the form |
| <strong><code>%{</code> <em>NAME_OF_VARIABLE</em> |
| <code>}</code></strong> |
| where <em>NAME_OF_VARIABLE</em> can be a string taken |
| from the following list: |
| |
| <ul> |
| <li> |
| <p><b>HTTP headers:</b></p> |
| <p> |
| HTTP_USER_AGENT<br /> |
| HTTP_REFERER<br /> |
| HTTP_COOKIE<br /> |
| HTTP_FORWARDED<br /> |
| HTTP_HOST<br /> |
| HTTP_PROXY_CONNECTION<br /> |
| HTTP_ACCEPT<br /> |
| </p> |
| </li> |
| <li> |
| <p><b>connection & request:</b></p> |
| <p> |
| REMOTE_ADDR<br /> |
| REMOTE_HOST<br /> |
| REMOTE_PORT<br /> |
| REMOTE_USER<br /> |
| REMOTE_IDENT<br /> |
| REQUEST_METHOD<br /> |
| SCRIPT_FILENAME<br /> |
| REQUEST_PATH<br /> |
| CONTEXT_PATH<br /> |
| SERVLET_PATH<br /> |
| PATH_INFO<br /> |
| QUERY_STRING<br /> |
| AUTH_TYPE<br /> |
| </p> |
| </li> |
| <li> |
| <p><b>server internals:</b></p> |
| <p> |
| DOCUMENT_ROOT<br /> |
| SERVER_NAME<br /> |
| SERVER_ADDR<br /> |
| SERVER_PORT<br /> |
| SERVER_PROTOCOL<br /> |
| SERVER_SOFTWARE<br /> |
| </p> |
| </li> |
| <li> |
| <p><b>date and time:</b></p> |
| <p> |
| TIME_YEAR<br /> |
| TIME_MON<br /> |
| TIME_DAY<br /> |
| TIME_HOUR<br /> |
| TIME_MIN<br /> |
| TIME_SEC<br /> |
| TIME_WDAY<br /> |
| TIME<br /> |
| </p> |
| </li> |
| <li> |
| <p><b>specials:</b></p> |
| <p> |
| THE_REQUEST<br /> |
| REQUEST_URI<br /> |
| REQUEST_FILENAME<br /> |
| HTTPS<br /> |
| </p> |
| </li> |
| </ul> |
| |
| <p>These variables all |
| correspond to the similarly named HTTP |
| MIME-headers and Servlet API methods. |
| Most are documented elsewhere in the Manual or in |
| the CGI specification. Those that are special to |
| the rewrite valve include those below.</p> |
| |
| <dl> |
| |
| <dt><code>REQUEST_PATH</code></dt> |
| |
| <dd>Corresponds to the full path that is used for mapping.</dd> |
| |
| <dt><code>CONTEXT_PATH</code></dt> |
| |
| <dd>Corresponds to the path of the mapped context.</dd> |
| |
| <dt><code>SERVLET_PATH</code></dt> |
| |
| <dd>Corresponds to the servlet path.</dd> |
| |
| <dt><code>THE_REQUEST</code></dt> |
| |
| <dd>The full HTTP request line sent by the |
| browser to the server (e.g., "<code>GET |
| /index.html HTTP/1.1</code>"). This does not |
| include any additional headers sent by the |
| browser.</dd> |
| |
| <dt><code>REQUEST_URI</code></dt> |
| |
| <dd>The resource requested in the HTTP request |
| line. (In the example above, this would be |
| "/index.html".)</dd> |
| |
| <dt><code>REQUEST_FILENAME</code></dt> |
| |
| <dd>The full local file system path to the file or |
| script matching the request.</dd> |
| |
| <dt><code>HTTPS</code></dt> |
| |
| <dd>Will contain the text "on" if the connection is |
| using SSL/TLS, or "off" otherwise.</dd> |
| |
| </dl> |
| |
| </li> |
| </ul> |
| |
| <p>Other things you should be aware of:</p> |
| |
| <ol> |
| <li>The variables SCRIPT_FILENAME and REQUEST_FILENAME |
| contain the same value - the value of the |
| <code>filename</code> field of the internal |
| <code>request_rec</code> structure of the Apache server. |
| The first name is the commonly known CGI variable name |
| while the second is the appropriate counterpart of |
| REQUEST_URI (which contains the value of the |
| <code>uri</code> field of <code>request_rec</code>).</li> |
| |
| <li> |
| <code>%{ENV:variable}</code>, where <em>variable</em> can be |
| any Java system property, is also available.</li> |
| |
| <li> |
| <code>%{SSL:variable}</code>, where <em>variable</em> is the |
| name of an SSL environment |
| variable, are not implemented yet. Example: |
| <code>%{SSL:SSL_CIPHER_USEKEYSIZE}</code> may expand to |
| <code>128</code>.</li> |
| |
| <li> |
| <code>%{HTTP:header}</code>, where <em>header</em> can be |
| any HTTP MIME-header name, can always be used to obtain the |
| value of a header sent in the HTTP request. |
| Example: <code>%{HTTP:Proxy-Connection}</code> is |
| the value of the HTTP header |
| ``<code>Proxy-Connection:</code>''.</li> |
| |
| </ol> |
| |
| <p><em>CondPattern</em> is the condition pattern, |
| a regular expression which is applied to the |
| current instance of the <em>TestString</em>. |
| <em>TestString</em> is first evaluated, before being matched against |
| <em>CondPattern</em>.</p> |
| |
| <p><strong>Remember:</strong> <em>CondPattern</em> is a |
| <em>perl compatible regular expression</em> with some |
| additions:</p> |
| |
| <ol> |
| <li>You can prefix the pattern string with a |
| '<code>!</code>' character (exclamation mark) to specify a |
| <strong>non</strong>-matching pattern.</li> |
| |
| <li> |
| There are some special variants of <em>CondPatterns</em>. |
| Instead of real regular expression strings you can also |
| use one of the following: |
| |
| <ul> |
| <li>'<strong><CondPattern</strong>' (lexicographically |
| precedes)<br /> |
| Treats the <em>CondPattern</em> as a plain string and |
| compares it lexicographically to <em>TestString</em>. True if |
| <em>TestString</em> lexicographically precedes |
| <em>CondPattern</em>.</li> |
| |
| <li>'<strong>>CondPattern</strong>' (lexicographically |
| follows)<br /> |
| Treats the <em>CondPattern</em> as a plain string and |
| compares it lexicographically to <em>TestString</em>. True if |
| <em>TestString</em> lexicographically follows |
| <em>CondPattern</em>.</li> |
| |
| <li>'<strong>=CondPattern</strong>' (lexicographically |
| equal)<br /> |
| Treats the <em>CondPattern</em> as a plain string and |
| compares it lexicographically to <em>TestString</em>. True if |
| <em>TestString</em> is lexicographically equal to |
| <em>CondPattern</em> (the two strings are exactly |
| equal, character for character). If <em>CondPattern</em> |
| is <code>""</code> (two quotation marks) this |
| compares <em>TestString</em> to the empty string.</li> |
| |
| <li>'<strong>-d</strong>' (is |
| <strong>d</strong>irectory)<br /> |
| Treats the <em>TestString</em> as a pathname and tests |
| whether or not it exists, and is a directory.</li> |
| |
| <li>'<strong>-f</strong>' (is regular |
| <strong>f</strong>ile)<br /> |
| Treats the <em>TestString</em> as a pathname and tests |
| whether or not it exists, and is a regular file.</li> |
| |
| <li>'<strong>-s</strong>' (is regular file, with |
| <strong>s</strong>ize)<br /> |
| Treats the <em>TestString</em> as a pathname and tests |
| whether or not it exists, and is a regular file with size greater |
| than zero.</li> |
| |
| </ul> |
| |
| <strong>Note:</strong> |
| All of these tests can |
| also be prefixed by an exclamation mark ('!') to |
| negate their meaning. |
| |
| </li> |
| |
| <li>You can also set special flags for |
| <em>CondPattern</em> by appending |
| <strong><code>[</code><em>flags</em><code>]</code></strong> |
| as the third argument to the <code>RewriteCond</code> |
| directive, where <em>flags</em> is a comma-separated list of any of the |
| following flags: |
| |
| <ul> |
| <li>'<strong><code>nocase|NC</code></strong>' |
| (<strong>n</strong>o <strong>c</strong>ase)<br /> |
| This makes the test case-insensitive - differences |
| between 'A-Z' and 'a-z' are ignored, both in the |
| expanded <em>TestString</em> and the <em>CondPattern</em>. |
| This flag is effective only for comparisons between |
| <em>TestString</em> and <em>CondPattern</em>. It has no |
| effect on file system and subrequest checks.</li> |
| |
| <li> |
| '<strong><code>ornext|OR</code></strong>' |
| (<strong>or</strong> next condition)<br /> |
| Use this to combine rule conditions with a local OR |
| instead of the implicit AND. Typical example: |
| |
| <source>RewriteCond %{REMOTE_HOST} ^host1.* [OR] |
| RewriteCond %{REMOTE_HOST} ^host2.* [OR] |
| RewriteCond %{REMOTE_HOST} ^host3.* |
| RewriteRule ...some special stuff for any of these hosts...</source> |
| |
| Without this flag you would have to write the condition/rule |
| pair three times. |
| </li> |
| </ul> |
| </li> |
| </ol> |
| |
| <p><strong>Example:</strong></p> |
| |
| <p>To rewrite the Homepage of a site according to the |
| ``<code>User-Agent:</code>'' header of the request, you can |
| use the following: </p> |
| |
| <source>RewriteCond %{HTTP_USER_AGENT} ^Mozilla.* |
| RewriteRule ^/$ /homepage.max.html [L] |
| |
| RewriteCond %{HTTP_USER_AGENT} ^Lynx.* |
| RewriteRule ^/$ /homepage.min.html [L] |
| |
| RewriteRule ^/$ /homepage.std.html [L]</source> |
| |
| <p>Explanation: If you use a browser which identifies itself |
| as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you |
| get the max homepage (which could include frames, or other special |
| features). |
| If you use the Lynx browser (which is terminal-based), then |
| you get the min homepage (which could be a version designed for |
| easy, text-only browsing). |
| If neither of these conditions apply (you use any other browser, |
| or your browser identifies itself as something non-standard), you get |
| the std (standard) homepage.</p> |
| |
| </subsection> |
| |
| <subsection name="RewriteMap"> |
| |
| <p>Syntax: <code>RewriteMap name rewriteMapClassName optionalParameters</code></p> |
| |
| <p>The maps are implemented using an interface that users must implement. Its class |
| name is <code>org.apache.catalina.valves.rewrite.RewriteMap</code>, and its code is:</p> |
| |
| <source><![CDATA[package org.apache.catalina.valves.rewrite; |
| |
| public interface RewriteMap { |
| public String setParameters(String params); |
| public String lookup(String key); |
| }]]></source> |
| |
| </subsection> |
| |
| <subsection name="RewriteRule"> |
| |
| <p>Syntax: <code>RewriteRule Pattern Substitution</code></p> |
| |
| <p>The RewriteRule directive is the real |
| rewriting workhorse. The directive can occur more than once, |
| with each instance defining a single rewrite rule. The |
| order in which these rules are defined is important - this is the order |
| in which they will be applied at run-time.</p> |
| |
| <p>Pattern is a perl compatible regular |
| expression, which is applied to the current URL. |
| ``Current'' means the value of the URL when this rule is |
| applied. This may not be the originally requested URL, |
| which may already have matched a previous rule, and have been |
| altered.</p> |
| |
| <p>Some hints on the syntax of regular |
| expressions:</p> |
| |
| <!-- TODO: Why is the following pre-formatted non-wrappable text? --> |
| <pre> |
| <strong>Text:</strong> |
| <strong><code>.</code></strong> Any single character |
| <strong><code>[</code></strong>chars<strong><code>]</code></strong> Character class: Any character of the class ``chars'' |
| <strong><code>[^</code></strong>chars<strong><code>]</code></strong> Character class: Not a character of the class ``chars'' |
| text1<strong><code>|</code></strong>text2 Alternative: text1 or text2 |
| |
| <strong>Quantifiers:</strong> |
| <strong><code>?</code></strong> 0 or 1 occurrences of the preceding text |
| <strong><code>*</code></strong> 0 or N occurrences of the preceding text (N > 0) |
| <strong><code>+</code></strong> 1 or N occurrences of the preceding text (N > 1) |
| |
| <strong>Grouping:</strong> |
| <strong><code>(</code></strong>text<strong><code>)</code></strong> Grouping of text |
| (used either to set the borders of an alternative as above, or |
| to make backreferences, where the <strong>N</strong>th group can |
| be referred to on the RHS of a RewriteRule as <code>$</code><strong>N</strong>) |
| |
| <strong>Anchors:</strong> |
| <strong><code>^</code></strong> Start-of-line anchor |
| <strong><code>$</code></strong> End-of-line anchor |
| |
| <strong>Escaping:</strong> |
| <strong><code>\</code></strong>char escape the given char |
| (for instance, to specify the chars "<code>.[]()</code>" <em>etc.</em>) |
| </pre> |
| |
| <p>For more information about regular expressions, have a look at the |
| perl regular expression manpage ("<a |
| href="http://www.perldoc.com/perl5.6.1/pod/perlre.html">perldoc |
| perlre</a>"). If you are interested in more detailed |
| information about regular expressions and their variants |
| (POSIX regex etc.) the following book is dedicated to this topic:</p> |
| |
| <p class="indent"> |
| <em>Mastering Regular Expressions, 2nd Edition</em><br /> |
| Jeffrey E.F. Friedl<br /> |
| O'Reilly & Associates, Inc. 2002<br /> |
| ISBN 978-0-596-00289-3<br /> |
| </p> |
| |
| <p>In the rules, the NOT character |
| ('<code>!</code>') is also available as a possible pattern |
| prefix. This enables you to negate a pattern; to say, for instance: |
| ``<em>if the current URL does <strong>NOT</strong> match this |
| pattern</em>''. This can be used for exceptional cases, where |
| it is easier to match the negative pattern, or as a last |
| default rule.</p> |
| |
| <p> |
| Note: When using the NOT character to negate a pattern, you cannot include |
| grouped wildcard parts in that pattern. This is because, when the |
| pattern does NOT match (i.e., the negation matches), there are no |
| contents for the groups. Thus, if negated patterns are used, you |
| cannot use <code>$N</code> in the substitution string! |
| </p> |
| |
| <p>The <em id="rhs" >substitution</em> of a |
| rewrite rule is the string which is substituted for (or |
| replaces) the original URL which <em>Pattern</em> |
| matched. In addition to plain text, it can include</p> |
| |
| <ol> |
| <li>back-references (<code>$N</code>) to the RewriteRule |
| pattern</li> |
| |
| <li>back-references (<code>%N</code>) to the last matched |
| RewriteCond pattern</li> |
| |
| <li>server-variables as in rule condition test-strings |
| (<code>%{VARNAME}</code>)</li> |
| |
| <li><a href="#mapfunc">mapping-function</a> calls |
| (<code>${mapname:key|default}</code>)</li> |
| </ol> |
| <p>Back-references are identifiers of the form |
| <code>$</code><strong>N</strong> |
| (<strong>N</strong>=0..9), which will be replaced |
| by the contents of the <strong>N</strong>th group of the |
| matched <em>Pattern</em>. The server-variables are the same |
| as for the <em>TestString</em> of a <code>RewriteCond</code> |
| directive. The mapping-functions come from the |
| <code>RewriteMap</code> directive and are explained there. |
| These three types of variables are expanded in the order above.</p> |
| |
| <p>As already mentioned, all rewrite rules are |
| applied to the <em>Substitution</em> (in the order in which |
| they are defined |
| in the config file). The URL is <strong>completely |
| replaced</strong> by the <em>Substitution</em> and the |
| rewriting process continues until all rules have been applied, |
| or it is explicitly terminated by a |
| <code><strong>L</strong></code> flag.</p> |
| |
| <p>The special characters <code>$</code> and <code>%</code> can |
| be quoted by prepending them with a backslash character |
| <code>\</code>.</p> |
| |
| <p>There is a special substitution string named |
| '<code>-</code>' which means: <strong>NO |
| substitution</strong>! This is useful in providing |
| rewriting rules which <strong>only</strong> match |
| URLs but do not substitute anything for them. It is commonly used |
| in conjunction with the <strong>C</strong> (chain) flag, in order |
| to apply more than one pattern before substitution occurs.</p> |
| |
| <p>Unlike newer mod_rewrite versions, the Tomcat rewrite valve does |
| not automatically support absolute URLs (the specific redirect flag |
| must be used to be able to specify an absolute URLs, see below) |
| or direct file serving.</p> |
| |
| <p>Additionally you can set special <span |
| id="rewriteflags">flags</span> for <em>Substitution</em> by |
| appending <strong><code>[</code><em>flags</em><code>]</code></strong> |
| as the third argument to the <code>RewriteRule</code> |
| directive. <em>Flags</em> is a comma-separated list of any of the |
| following flags: </p> |
| |
| <ul> |
| <li>'<strong><code>chain|C</code></strong>' |
| (<strong>c</strong>hained with next rule)<br /> |
| This flag chains the current rule with the next rule |
| (which itself can be chained with the following rule, |
| and so on). This has the following effect: if a rule |
| matches, then processing continues as usual - |
| the flag has no effect. If the rule does |
| <strong>not</strong> match, then all following chained |
| rules are skipped. For instance, it can be used to remove the |
| ``<code>.www</code>'' part, inside a per-directory rule set, |
| when you let an external redirect happen (where the |
| ``<code>.www</code>'' part should not occur!).</li> |
| |
| <li> |
| '<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]' |
| (set <strong>co</strong>okie)<br /> |
| This sets a cookie in the client's browser. The cookie's name |
| is specified by <em>NAME</em> and the value is |
| <em>VAL</em>. The <em>domain</em> field is the domain of the |
| cookie, such as '.apache.org', the optional <em>lifetime</em> |
| is the lifetime of the cookie in minutes, and the optional |
| <em>path</em> is the path of the cookie</li> |
| |
| <li> |
| '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>' |
| (set <strong>e</strong>nvironment variable)<br /> |
| This forces a request attribute named <em>VAR</em> to |
| be set to the value <em>VAL</em>, where <em>VAL</em> can |
| contain regexp backreferences (<code>$N</code> and |
| <code>%N</code>) which will be expanded. You can use this |
| flag more than once, to set more than one variable.</li> |
| |
| <li>'<strong><code>forbidden|F</code></strong>' (force URL |
| to be <strong>f</strong>orbidden)<br /> |
| This forces the current URL to be forbidden - it immediately |
| sends back a HTTP response of 403 (FORBIDDEN). |
| Use this flag in conjunction with |
| appropriate RewriteConds to conditionally block some |
| URLs.</li> |
| |
| <li>'<strong><code>gone|G</code></strong>' (force URL to be |
| <strong>g</strong>one)<br /> |
| This forces the current URL to be gone - it |
| immediately sends back a HTTP response of 410 (GONE). Use |
| this flag to mark pages which no longer exist as gone.</li> |
| |
| <li> |
| '<strong><code>host|H</code></strong>=<em>Host</em>' |
| (apply rewriting to <strong>h</strong>ost)<br /> |
| Rather that rewrite the URL, the virtual host will be |
| rewritten.</li> |
| |
| <li>'<strong><code>last|L</code></strong>' |
| (<strong>l</strong>ast rule)<br /> |
| Stop the rewriting process here and don't apply any more |
| rewrite rules. This corresponds to the Perl |
| <code>last</code> command or the <code>break</code> command |
| in C. Use this flag to prevent the currently |
| rewritten URL from being rewritten further by following |
| rules. For example, use it to rewrite the root-path URL |
| ('<code>/</code>') to a real one, <em>e.g.</em>, |
| '<code>/e/www/</code>'.</li> |
| |
| <li>'<strong><code>next|N</code></strong>' |
| (<strong>n</strong>ext round)<br /> |
| Re-run the rewriting process (starting again with the |
| first rewriting rule). This time, the URL to match is no longer |
| the original URL, but rather the URL returned by the last rewriting rule. |
| This corresponds to the Perl <code>next</code> command or |
| the <code>continue</code> command in C. Use |
| this flag to restart the rewriting process - |
| to immediately go to the top of the loop.<br /> |
| <strong>Be careful not to create an infinite |
| loop!</strong></li> |
| |
| <li>'<strong><code>nocase|NC</code></strong>' |
| (<strong>n</strong>o <strong>c</strong>ase)<br /> |
| This makes the <em>Pattern</em> case-insensitive, |
| ignoring difference between 'A-Z' and |
| 'a-z' when <em>Pattern</em> is matched against the current |
| URL.</li> |
| |
| <li> |
| '<strong><code>noescape|NE</code></strong>' |
| (<strong>n</strong>o URI <strong>e</strong>scaping of |
| output)<br /> |
| This flag prevents the rewrite valve from applying the usual URI |
| escaping rules to the result of a rewrite. Ordinarily, |
| special characters (such as '%', '$', ';', and so on) |
| will be escaped into their hexcode equivalents ('%25', |
| '%24', and '%3B', respectively); this flag prevents this |
| from happening. This allows percent symbols to appear in |
| the output, as in |
| <source>RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]</source> |
| which would turn '<code>/foo/zed</code>' into a safe |
| request for '<code>/bar?arg=P1=zed</code>'. |
| </li> |
| |
| <!-- Not supported yet |
| <li> |
| '<strong><code>proxy|P</code></strong>' (force |
| <strong>p</strong>roxy)<br /> |
| This flag forces the substitution part to be internally |
| sent as a proxy request and immediately (rewrite |
| processing stops here) put through the <a |
| href="mod_proxy.html">proxy module</a>. You must make |
| sure that the substitution string is a valid URI |
| (typically starting with |
| <code>http://</code><em>hostname</em>) which can be |
| handled by the Apache proxy module. If not, you will get an |
| error from the proxy module. Use this flag to achieve a |
| more powerful implementation of the <a |
| href="mod_proxy.html#proxypass">ProxyPass</a> directive, |
| to map remote content into the namespace of the local |
| server. |
| |
| <p>Note: <module>mod_proxy</module> must be enabled in order |
| to use this flag.</p> |
| </li> |
| --> |
| |
| <li>'<strong><code>qsappend|QSA</code></strong>' |
| (<strong>q</strong>uery <strong>s</strong>tring |
| <strong>a</strong>ppend)<br /> |
| This flag forces the rewrite engine to append a query |
| string part of the substitution string to the existing string, |
| instead of replacing it. Use this when you want to add more |
| data to the query string via a rewrite rule.</li> |
| |
| <li>'<strong><code>redirect|R</code> |
| [=<em>code</em>]</strong>' (force <span id="redirect"> |
| <strong>r</strong>edirect</span>)<br /> |
| Prefix <em>Substitution</em> with |
| <code>http://thishost[:thisport]/</code> (which makes the |
| new URL a URI) to force a external redirection. If no |
| <em>code</em> is given, a HTTP response of 302 (FOUND, previously MOVED |
| TEMPORARILY) will be returned. If you want to use other response |
| codes in the range 300-399, simply specify the appropriate number |
| or use one of the following symbolic names: |
| <code>temp</code> (default), <code>permanent</code>, |
| <code>seeother</code>. Use this for rules to |
| canonicalize the URL and return it to the client - to |
| translate ``<code>/~</code>'' into |
| ``<code>/u/</code>'', or to always append a slash to |
| <code>/u/</code><em>user</em>, etc.<br /> |
| <strong>Note:</strong> When you use this flag, make |
| sure that the substitution field is a valid URL! Otherwise, |
| you will be redirecting to an invalid location. Remember |
| that this flag on its own will only prepend |
| <code>http://thishost[:thisport]/</code> to the URL, and rewriting |
| will continue. Usually, you will want to stop rewriting at this point, |
| and redirect immediately. To stop rewriting, you should add |
| the 'L' flag. |
| </li> |
| |
| <li>'<strong><code>skip|S</code></strong>=<em>num</em>' |
| (<strong>s</strong>kip next rule(s))<br /> |
| This flag forces the rewriting engine to skip the next |
| <em>num</em> rules in sequence, if the current rule |
| matches. Use this to make pseudo if-then-else constructs: |
| The last rule of the then-clause becomes |
| <code>skip=N</code>, where N is the number of rules in the |
| else-clause. (This is <strong>not</strong> the same as the |
| 'chain|C' flag!)</li> |
| |
| <li> |
| '<strong><code>type|T</code></strong>=<em>MIME-type</em>' |
| (force MIME <strong>t</strong>ype)<br /> |
| Force the MIME-type of the target file to be |
| <em>MIME-type</em>. This can be used to |
| set up the content-type based on some conditions. |
| For example, the following snippet allows <code>.php</code> files to |
| be <em>displayed</em> by <code>mod_php</code> if they are called with |
| the <code>.phps</code> extension: |
| <source>RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]</source> |
| </li> |
| </ul> |
| |
| </subsection> |
| |
| </section> |
| |
| </body> |
| </document> |
