diff options
Diffstat (limited to 'docs/manual/rewrite/flags.html.en')
| -rw-r--r-- | docs/manual/rewrite/flags.html.en | 212 |
1 files changed, 120 insertions, 92 deletions
diff --git a/docs/manual/rewrite/flags.html.en b/docs/manual/rewrite/flags.html.en index bfa09528..ecb2e93d 100644 --- a/docs/manual/rewrite/flags.html.en +++ b/docs/manual/rewrite/flags.html.en @@ -8,10 +8,13 @@ <title>RewriteRule Flags - Apache HTTP Server</title> <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> -<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /> +<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" /> +<script src="../style/scripts/prettify.js" type="text/javascript"> +</script> + <link href="../images/favicon.ico" rel="shortcut icon" /></head> <body id="manual-page"><div id="page-header"> -<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> +<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p> <p class="apache">Apache HTTP Server Version 2.4</p> <img alt="" src="../images/feather.gif" /></div> <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div> @@ -48,7 +51,7 @@ providing detailed explanations and examples.</p> <li><img alt="" src="../images/down.gif" /> <a href="#flag_r">R|redirect</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#flag_s">S|skip</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#flag_t">T|type</a></li> -</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="rewritemap.html">Using RewriteMap</a></li><li><a href="advanced.html">Advanced techniques</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li></ul></div> +</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="rewritemap.html">Using RewriteMap</a></li><li><a href="advanced.html">Advanced techniques</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li></ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="section"> <h2><a name="introduction" id="introduction">Introduction</a></h2> @@ -56,9 +59,8 @@ providing detailed explanations and examples.</p> its behavior modified by one or more flags. Flags are included in square brackets at the end of the rule, and multiple flags are separated by commas.</p> -<div class="example"><p><code> -RewriteRule pattern target [Flag1,Flag2,Flag3] -</code></p></div> +<pre class="prettyprint lang-config">RewriteRule pattern target [Flag1,Flag2,Flag3]</pre> + <p>The flags all have a short form, such as <code>CO</code>, as well as a longer form, such as <code>cookie</code>. Some flags take one or more @@ -88,9 +90,8 @@ so backreferences will be unescaped at the time they are applied. Using the B flag, non-alphanumeric characters in backreferences will be escaped. For example, consider the rule:</p> -<div class="example"><p><code> -RewriteRule ^search/(.*)$ /search.php?term=$1 -</code></p></div> +<pre class="prettyprint lang-config">RewriteRule ^search/(.*)$ /search.php?term=$1</pre> + <p>Given a search term of 'x & y/z', a browser will encode it as 'x%20%26%20y%2Fz', making the request 'search/x%20%26%20y%2Fz'. Without the B @@ -174,10 +175,11 @@ browsers that support this feature.</dd> <p>Several examples are offered here:</p> -<div class="example"><p><code> -RewriteEngine On<br /> +<pre class="prettyprint lang-config"> +RewriteEngine On RewriteRule ^/index\.html - [CO=frontdoor:yes:.example.com:1440:/] -</code></p></div> +</pre> + <p>In the example give, the rule doesn't rewrite the request. The "-" rewrite target tells mod_rewrite to pass the request @@ -262,10 +264,11 @@ value of '1' if the requested URI is an image file. Then, that environment variable is used to exclude those requests from the access log.</p> -<div class="example"><p><code> -RewriteRule \.(png|gif|jpg) - [E=image:1]<br /> +<pre class="prettyprint lang-config"> +RewriteRule \.(png|gif|jpg)$ - [E=image:1] CustomLog logs/access_log combined env=!image -</code></p></div> +</pre> + <p>Note that this same effect can be obtained using <code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code>. This technique is offered as an example, not as a recommendation.</p> @@ -289,9 +292,8 @@ allows more flexibility in assigning a Forbidden status.</p> <p>The following rule will forbid <code>.exe</code> files from being downloaded from your server.</p> -<div class="example"><p><code> -RewriteRule \.exe - [F] -</code></p></div> +<pre class="prettyprint lang-config">RewriteRule \.exe - [F]</pre> + <p>This example uses the "-" syntax for the rewrite target, which means that the requested URI is not modified. There's no reason to rewrite to @@ -310,9 +312,8 @@ longer available.</p> <p>As with the [F] flag, you will typically use the "-" syntax for the rewrite target when using the [G] flag:</p> -<div class="example"><p><code> -RewriteRule oldproduct - [G,NC] -</code></p></div> +<pre class="prettyprint lang-config">RewriteRule oldproduct - [G,NC]</pre> + <p>When using [G], an [L] is implied - that is, the response is returned immediately, and no further rules are evaluated.</p> @@ -324,9 +325,8 @@ immediately, and no further rules are evaluated.</p> handler. For example, one might use this to force all files without a file extension to be parsed by the php handler:</p> -<div class="example"><p><code> -RewriteRule !\. - [H=application/x-httpd-php] -</code></p></div> +<pre class="prettyprint lang-config">RewriteRule !\. - [H=application/x-httpd-php]</pre> + <p> The regular expression above - <code>!\.</code> - will match any request @@ -338,9 +338,10 @@ For example, the following snippet used in per-server context allows <code>.php</code> files to be <em>displayed</em> by <code>mod_php</code> if they are requested with the <code>.phps</code> extension:</p> -<div class="example"><p><code> +<pre class="prettyprint lang-config"> RewriteRule ^(/source/.+\.php)s$ $1 [H=application/x-httpd-php-source] -</code></p></div> +</pre> + <p>The regular expression above - <code>^(/source/.+\.php)s$</code> - will match any request that starts with <code>/source/</code> followed by 1 or @@ -387,11 +388,12 @@ redirects.</p> argument to <code>index.php</code>, however, the <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> ensures that if the request is already for <code>index.php</code>, the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> will be skipped.</p> -<div class="example"><p><code> -RewriteBase /<br /> -RewriteCond %{REQUEST_URI} !=/index.php<br /> +<pre class="prettyprint lang-config"> +RewriteBase / +RewriteCond %{REQUEST_URI} !=/index.php RewriteRule ^(.*) /index.php?req=$1 [L,PT] -</code></p></div> +</pre> + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="section"> <h2><a name="flag_n" id="flag_n">N|next</a></h2> @@ -407,9 +409,8 @@ will replace A with B everywhere in a request, and will continue doing so until there are no more As to be replaced. </p> -<div class="example"><p><code> -RewriteRule (.*)A(.*) $1B$2 [N] -</code></p></div> +<pre class="prettyprint lang-config">RewriteRule (.*)A(.*) $1B$2 [N]</pre> + <p>You can think of this as a <code>while</code> loop: While this pattern still matches (i.e., while the URI still contains an @@ -428,9 +429,8 @@ to your dedicated image server. The match is case-insensitive, so that <code>.jpg</code> and <code>.JPG</code> files are both acceptable, for example.</p> -<div class="example"><p><code> -RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC] -</code></p></div> +<pre class="prettyprint lang-config">RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC]</pre> + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="section"> <h2><a name="flag_ne" id="flag_ne">NE|noescape</a></h2> @@ -439,9 +439,8 @@ RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC] equivalent. Using the [NE] flag prevents that from happening. </p> -<div class="example"><p><code> -RewriteRule ^/anchor/(.+) /bigpage.html#$1 [NE,R] -</code></p></div> +<pre class="prettyprint lang-config">RewriteRule ^/anchor/(.+) /bigpage.html#$1 [NE,R]</pre> + <p> The above example will redirect <code>/anchor/xyz</code> to @@ -482,9 +481,8 @@ requests. example, if you wanted all image requests to be handled by a back-end image server, you might do something like the following:</p> -<div class="example"><p><code> -RewriteRule /(.*)\.(jpg|gif|png) http://images.example.com/$1.$2 [P] -</code></p></div> +<pre class="prettyprint lang-config">RewriteRule /(.*)\.(jpg|gif|png)$ http://images.example.com/$1.$2 [P]</pre> + <p>Use of the [P] flag implies [L] - that is, the request is immediately pushed through the proxy, and any following rules will not be @@ -507,6 +505,15 @@ and hostname part of the URL is either fixed, or does not allow the client undue influence.</p> </div> +<div class="warning"> +<h3>Performance warning</h3> +<p>Using this flag triggers the use of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, without handling of persistent connections. This +means the performance of your proxy will be better if you set it up with <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> or +<code class="directive"><a href="../mod/mod_proxy.html#proxypassmatch">ProxyPassMatch</a></code></p> +<p>This is because this flag triggers the use of the default worker, which does not handle connection pooling.</p> +<p>Avoid using this flag and prefer those directives, whenever you can.</p> +</div> + <p>Note: <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> must be enabled in order to use this flag.</p> @@ -531,10 +538,11 @@ use the [PT] flag to ensure that the <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> is evaluated. </p> -<div class="example"><p><code> -Alias /icons /usr/local/apache/icons<br /> -RewriteRule /pics/(.+)\.jpg /icons/$1.gif [PT] -</code></p></div> +<pre class="prettyprint lang-config"> +Alias /icons /usr/local/apache/icons +RewriteRule /pics/(.+)\.jpg$ /icons/$1.gif [PT] +</pre> + <p> Omission of the [PT] flag in this case will cause the Alias to be @@ -563,9 +571,8 @@ Using the [QSA] flag causes the query strings to be combined. <p>Consider the following rule:</p> -<div class="example"><p><code> -RewriteRule /pages/(.+) /page.php?page=$1 [QSA] -</code></p></div> +<pre class="prettyprint lang-config">RewriteRule /pages/(.+) /page.php?page=$1 [QSA]</pre> + <p>With the [QSA] flag, a request for <code>/pages/123?one=two</code> will be mapped to <code>/page.php?page=123&one=two</code>. Without the [QSA] @@ -611,10 +618,8 @@ will be used to generate the URL sent with the redirect. <em>Any</em> valid HTTP response status code may be specified, using the syntax [R=305], with a 302 status code being used by default if none is specified. The status code specified need not -necessarily be a redirect (3xx) status code. -</p> - -<p>If a status code is outside the redirect range (300-399) then the +necessarily be a redirect (3xx) status code. However, +if a status code is outside the redirect range (300-399) then the substitution string is dropped entirely, and rewriting is stopped as if the <code>L</code> were used.</p> @@ -633,21 +638,24 @@ URI in request' warnings. </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="section"> <h2><a name="flag_s" id="flag_s">S|skip</a></h2> -<p>The [S] flag is used to skip rules that you don't want to run. This -can be thought of as a <code>goto</code> statement in your rewrite -ruleset. In the following example, we only want to run the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> if the requested URI -doesn't correspond with an actual file.</p> - -<div class="example"><p><code> -# Is the request for a non-existent file?<br /> -RewriteCond %{REQUEST_FILENAME} !-f<br /> -RewriteCond %{REQUEST_FILENAME} !-d<br /> -# If so, skip these two RewriteRules<br /> -RewriteRule .? - [S=2]<br /> -<br /> -RewriteRule (.*\.gif) images.php?$1<br /> +<p>The [S] flag is used to skip rules that you don't want to run. The +syntax of the skip flag is [S=<em>N</em>], where <em>N</em> signifies +the number of rules to skip. This can be thought of as a <code>goto</code> +statement in your rewrite ruleset. In the following example, we only want +to run the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> if the +requested URI doesn't correspond with an actual file.</p> + +<pre class="prettyprint lang-config"> +# Is the request for a non-existent file? +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_FILENAME} !-d +# If so, skip these two RewriteRules +RewriteRule .? - [S=2] + +RewriteRule (.*\.gif) images.php?$1 RewriteRule (.*\.html) docs.php?$1 -</code></p></div> +</pre> + <p>This technique is useful because a <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> only applies to the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> immediately @@ -657,26 +665,23 @@ negate those conditions and add a <code>RewriteRule</code> with a [Skip] flag. Y 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:</p> -<div class="example"><p><code> -# Does the file exist?<br /> -RewriteCond %{REQUEST_FILENAME} !-f<br /> -RewriteCond %{REQUEST_FILENAME} !-d<br /> -# Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza.<br /> -RewriteRule .? - [S=3]<br /> -<br /> +<pre class="prettyprint lang-config"> +# Does the file exist? +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_FILENAME} !-d +# Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza. +RewriteRule .? - [S=3] + # IF the file exists, then: -<span class="indent"> - RewriteRule (.*\.gif) images.php?$1<br /> - RewriteRule (.*\.html) docs.php?$1<br /> - # Skip past the "else" stanza.<br /> - RewriteRule .? - [S=1]<br /> -</span> + RewriteRule (.*\.gif) images.php?$1 + RewriteRule (.*\.html) docs.php?$1 + # Skip past the "else" stanza. + RewriteRule .? - [S=1] # ELSE... -<span class="indent"> - RewriteRule (.*) 404.php?file=$1<br /> -</span> + RewriteRule (.*) 404.php?file=$1 # END -</code></p></div> +</pre> + <p>It is probably easier to accomplish this kind of configuration using the <code class="directive"><If></code>, <code class="directive"><ElseIf></code>, and <code class="directive"><Else></code> directives instead.</p> @@ -690,19 +695,21 @@ sent. This has the same effect as the <code class="directive"><a href="../mod/mo <p>For example, you might use the following technique to serve Perl source code as plain text, if requested in a particular way:</p> -<div class="example"><p><code> -# Serve .pl files as plain text<br /> +<pre class="prettyprint lang-config"> +# Serve .pl files as plain text RewriteRule \.pl$ - [T=text/plain] -</code></p></div> +</pre> + <p>Or, perhaps, if you have a camera that produces jpeg images without file extensions, you could force those images to be served with the correct MIME type by virtue of their file names:</p> -<div class="example"><p><code> -# Files with 'IMG' in the name are jpg images.<br /> +<pre class="prettyprint lang-config"> +# Files with 'IMG' in the name are jpg images. RewriteRule IMG - [T=image/jpg] -</code></p></div> +</pre> + <p>Please note that this is a trivial example, and could be better done using <code class="directive"><a href="../mod/core.html#filesmatch"><FilesMatch></a></code> @@ -722,7 +729,28 @@ The <code>L</code> flag can be useful in this context to end the <div class="bottomlang"> <p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English"> en </a> | <a href="../fr/rewrite/flags.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p> -</div><div id="footer"> +</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> +<script type="text/javascript"><!--//--><![CDATA[//><!-- +var comments_shortname = 'httpd'; +var comments_identifier = 'http://httpd.apache.org/docs/2.4/rewrite/flags.html'; +(function(w, d) { + if (w.location.hostname.toLowerCase() == "httpd.apache.org") { + d.write('<div id="comments_thread"><\/div>'); + var s = d.createElement('script'); + s.type = 'text/javascript'; + s.async = true; + s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; + (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); + } + else { + d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); + } +})(window, document); +//--><!]]></script></div><div id="footer"> <p class="apache">Copyright 2012 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> -<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> +<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- +if (typeof(prettyPrint) !== 'undefined') { + prettyPrint(); +} +//--><!]]></script> </body></html>
\ No newline at end of file |