mirror of
https://github.com/apache/httpd.git
synced 2025-05-31 12:21:16 +03:00
cefab4660c
H, specifically. Also adds an example for the [NE] flag. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@565212 13f79535-47bb-0310-9956-ffa450edef68
293 lines
14 KiB
XML
293 lines
14 KiB
XML
<?xml version="1.0" encoding="ISO-8859-1"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
|
|
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
|
This file is generated from xml source: DO NOT EDIT
|
|
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
|
-->
|
|
<title>Apache mod_rewrite 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="../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="apache">Apache HTTP Server Version 2.3</p>
|
|
<img alt="" src="../images/feather.gif" /></div>
|
|
<div class="up"><a href="./index.html"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
|
|
<div id="path">
|
|
<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.3</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Flags</h1>
|
|
<div class="toplang">
|
|
<p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English"> en </a></p>
|
|
</div>
|
|
|
|
<p>This document discusses the flags which are available to the
|
|
<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive,
|
|
providing more detailed explanations and examples of each.</p>
|
|
</div>
|
|
<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flags">The flags</a></li>
|
|
</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="rewrite_tech.html">Technical details</a></li><li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li><li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide -
|
|
advanced useful examples</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>
|
|
<p><code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s can have
|
|
their 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>
|
|
|
|
<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
|
|
arguments. Flags are not case sensitive.</p>
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flags" id="flags">The flags</a></h2>
|
|
|
|
<p>Each flag has a long and short form. While it is most common to use
|
|
the short form, it is recommended that you familiarize yourself with the
|
|
long form, so that you remember what each flag is supposed to do.</p>
|
|
|
|
<p>Presented here are each of the available flags, along with an example
|
|
of how you might use them.</p>
|
|
|
|
<h3><a name="flag_c" id="flag_c">C|chain</a></h3>
|
|
<p>The [C] or [chain] flag indicates that the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is chained to the next
|
|
rule. That is, if the rule matches, then it is processed as usual and
|
|
control moves on to the next rule. However, if it does not match, then
|
|
the next rule, and any other rules that are chained together, will be
|
|
skipped.</p>
|
|
|
|
|
|
|
|
<h3><a name="flag_co" id="flag_co">CO|cookie</a></h3>
|
|
<p>The [CO], or [cookie] flag, allows you to set a cookie when a
|
|
particular <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>
|
|
matches. The argument consists of three required fields and two optional
|
|
fields.</p>
|
|
<p>You must declare a name and value for the cookie to be set, and the
|
|
domain for which you wish the cookie to be valid. You may optionally set
|
|
the lifetime of the cookie, and the path for which it should be
|
|
returned.</p>
|
|
<p>By default, the lifetime of the cookie is the current browser
|
|
session.</p>
|
|
<p>By default, the path for which the cookie will be valid is "/" - that
|
|
is, the entire website.</p>
|
|
<p>Several examples are offered here:</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteEngine On<br />
|
|
RewriteRule ^/index.html - [CO=frontdoor:yes:.apache.org:1440:/]
|
|
</code></p></div>
|
|
|
|
<p>This rule doesn't rewrite the request (the "-" rewrite target tells
|
|
mod_rewrite to pass the request through unchanged) but sets a cookie
|
|
called 'frontdoor' to a value of 'yes'. The cookie is valid for any host
|
|
in the <code>.apache.org</code> domain. It will be set to expire in 1440
|
|
minutes (24 hours) and will be returned for all URIs.</p>
|
|
|
|
|
|
|
|
<h3><a name="flag_e" id="flag_e">E|env</a></h3>
|
|
<p>With the [E], or [env] flag, you can set the value of an environment
|
|
variable. Note that some environment variables may be set after the rule
|
|
is run, thus unsetting what you have set. See <a href="../env.html">the
|
|
Environment Variables document</a> for more details on how Environment
|
|
variables work.</p>
|
|
|
|
<p>The following example sets an evironment variable called 'image' to a
|
|
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 />
|
|
CustomLog logs/access_log combined env=!image
|
|
</code></p></div>
|
|
|
|
<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>
|
|
|
|
|
|
<h3><a name="flag_f" id="flag_f">F|forbidden</a></h3>
|
|
<p>Using the [F] flag causes Apache to return a 403 Forbidden status
|
|
code to the client. While the same behavior can be accomplished using
|
|
the <code class="directive"><a href="../mod/mod_access.html#deny">Deny</a></code> directive, this
|
|
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>
|
|
|
|
<p>This example uses the "-" syntax for the rewrite target, which means
|
|
that the requested URI is not modified.</p>
|
|
|
|
|
|
|
|
<h3><a name="flag_g" id="flag_g">G|gone</a></h3>
|
|
<p>The [G] flag forces Apache to return a 410 Gone status with the
|
|
response. This indicates that a resource used to be available, but is no
|
|
longer available.</p>
|
|
|
|
|
|
<h3><a name="flag_h" id="flag_h">H|handler</a></h3>
|
|
<p>Forces the resulting request to be handled with the specified
|
|
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>
|
|
|
|
<p>
|
|
The regular expression above - <code>!\.</code> - will match any request
|
|
that does not contain the literal <code>.</code> character.
|
|
</p>
|
|
|
|
|
|
<h3><a name="flag_l" id="flag_l">L|last</a></h3>
|
|
<p>The [L] flag causes <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to stop processing
|
|
the rule set. In most contexts, this means that if the rule matches, no
|
|
further rules will be processed.</p>
|
|
|
|
<p>If you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> in either
|
|
<code>.htaccess</code> files or in
|
|
<code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> sections,
|
|
it is important to have some understanding of how the rules are
|
|
processed. The simplified form of this is that once the rules have been
|
|
processed, the rewritten request is handed back to the URL parsing
|
|
engine to do what it may with it. It is possible that as the rewritten
|
|
request is handled, the <code>.htaccess</code> file or
|
|
<code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section
|
|
may be encountered again, and thus the ruleset may be run again from the
|
|
start. Most commonly this will happen if one of the rules causes a
|
|
redirect - either internal or external - causing the request process to
|
|
start over.</p>
|
|
|
|
<p>It is therefore important, if you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives in one of these
|
|
context that you take explicit steps to avoid rules looping, and not
|
|
count solely on the [L] flag to terminate execution of a series of
|
|
rules.</p>
|
|
|
|
|
|
<h3><a name="flag_n" id="flag_n">N|next</a></h3>
|
|
<p>
|
|
The [N] flag causes the ruleset to start over again from the top. Use
|
|
with extreme caution, as it may result in loop.
|
|
</p>
|
|
<p>
|
|
The [Next] flag could be used, for example, if you wished to replace a
|
|
certain string or letter repeatedly in a request.
|
|
</p>
|
|
|
|
|
|
|
|
<h3><a name="flag_nc" id="flag_nc">NC|nocase</a></h3>
|
|
<p>Use of the [NC] flag causes the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be matched in a
|
|
case-insensitive manner. That is, it doesn't care whether letters appear
|
|
as upper-case or lower-case in the matched URI.</p>
|
|
|
|
<p>In the example below, any request for an image file will be proxied
|
|
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>
|
|
|
|
|
|
<h3><a name="flag_ne" id="flag_ne">NE|noescape</a></h3>
|
|
<p>By default, special characters, such as <code>&</code> and
|
|
<code>?</code>, for example, will be converted to their hexcode
|
|
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>
|
|
|
|
<p>
|
|
The above example will redirect <code>/anchor/xyz</code> to
|
|
<code>/bigpage.html#xyz</code>. Omitting the [NE] will result in the #
|
|
being converted to its hexcode equivalent, <code>%23</code>.
|
|
</p>
|
|
|
|
|
|
|
|
<h3><a name="flag_ns" id="flag_ns">NS|nosubreq</a></h3>
|
|
<p>No internal subrequest flag</p>
|
|
|
|
|
|
<h3><a name="flag_p" id="flag_p">P|proxy</a></h3>
|
|
<p>Proxy flag</p>
|
|
|
|
|
|
<h3><a name="flag_pt" id="flag_pt">PT|passthrough</a></h3>
|
|
<p>Passthrough flag</p>
|
|
|
|
|
|
<h3><a name="flag_qsa" id="flag_qsa">QSA|qsappend</a></h3>
|
|
<p>Query String Append flag</p>
|
|
|
|
|
|
<h3><a name="flag_r" id="flag_r">R|redirect</a></h3>
|
|
<p>Redirect flag</p>
|
|
|
|
|
|
<h3><a name="flag_s" id="flag_s">S|skip</a></h3>
|
|
<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>
|
|
RewriteCond %{REQUEST_FILENAME} !-f<br />
|
|
RewriteCond %{REQUEST_FILENAME} !-d<br />
|
|
RewriteRule .? - [S=2]<br />
|
|
<br />
|
|
RewriteRule (.*\.gif) images.php?$1<br />
|
|
RewriteRule (.*\.html) docs.php?$1
|
|
</code></p></div>
|
|
|
|
<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
|
|
following it. Thus, if you want to make a <code>RewriteCond</code> apply
|
|
to several <code>RewriteRule</code>s, one possible technique is to
|
|
negate those conditions and use a [Skip] flag.</p>
|
|
|
|
|
|
|
|
<h3><a name="flag_t" id="flag_t">T|type</a></h3>
|
|
<p>Sets the MIME type with which the resulting response will be
|
|
sent. This has the same effect as the <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> directive.</p>
|
|
|
|
<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>
|
|
# Files with 'IMG' in the name are gif images.
|
|
RewriteRule IMG - [T=image/gif]
|
|
</code></p></div>
|
|
|
|
<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>
|
|
instead. Always consider the alternate
|
|
solutions to a problem before resorting to rewrite, which will
|
|
invariably be a less efficient solution than the alternatives.</p>
|
|
|
|
|
|
</div></div>
|
|
<div class="bottomlang">
|
|
<p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English"> en </a></p>
|
|
</div><div id="footer">
|
|
<p class="apache">Copyright 2006 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>
|
|
</body></html> |