Apache mod_rewrite Flags

+Apache > HTTP Server > Documentation > Version 2.3

Apache mod_rewrite Flags

Available Languages: en

Available Languages:

This document discusses the flags which are available to the -RewriteRule directive, -providing more detailed explanations and examples of each.

+RewriteRule directive, +providing detailed explanations and examples. This is not necessarily +a comprehensive list of all flags available, so be sure to also +consult the reference documentation.

Introduction
The flags

Introduction
The flags

Introduction

RewriteRules can have +

RewriteRules 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.

@@ -44,7 +46,7 @@ RewriteRule pattern target [Flag1,Flag2,Flag3] a longer form, such as cookie. Some flags take one or more arguments. Flags are not case sensitive.

The flags

@@ -56,7 +58,7 @@ long form, so that you remember what each flag is supposed to do.

of how you might use them.

C|chain

The [C] or [chain] flag indicates that the RewriteRule is chained to the next +

The [C] or [chain] flag indicates that the RewriteRule 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 @@ -66,7 +68,7 @@ skipped.

CO|cookie

The [CO], or [cookie] flag, allows you to set a cookie when a -particular RewriteRule +particular RewriteRule matches. The argument consists of three required fields and two optional fields.

You must declare a name and value for the cookie to be set, and the @@ -109,14 +111,14 @@ RewriteRule \.(png|gif|jpg) - [E=image:1]
CustomLog logs/access_log combined env=!image

Note that this same effect can be obtained using SetEnvIf. This technique is offered as +

Note that this same effect can be obtained using SetEnvIf. This technique is offered as an example, not as a recommendation.

F|forbidden

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 Deny directive, this +the Deny directive, this allows more flexibility in assigning a Forbidden status.

The following rule will forbid .exe files from being @@ -161,25 +163,25 @@ that does not contain the literal . character.

L|last

The [L] flag causes mod_rewrite to stop processing +

The [L] flag causes mod_rewrite to stop processing the rule set. In most contexts, this means that if the rule matches, no further rules will be processed.

If you are using RewriteRule in either +

If you are using RewriteRule in either .htaccess files or in -<Directory> sections, +<Directory> 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 .htaccess file or -<Directory> section +<Directory> 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.

It is therefore important, if you are using RewriteRule directives in one of these +

It is therefore important, if you are using RewriteRule 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, as shown below.

@@ -217,7 +219,7 @@ pattern still matches, perform this substitution.

NC|nocase

Use of the [NC] flag causes the RewriteRule to be matched in a +

Use of the [NC] flag causes the RewriteRule 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.

@@ -265,7 +267,7 @@ requests.

P|proxy

Use of the [P] flag causes the request to be handled by -mod_proxy, and handled via a proxy request. For +mod_proxy, and handled via a proxy request. For example, if you wanted all image requests to be handled by a back-end image server, you might do something like the following:

@@ -285,17 +287,17 @@ considered.

The target (or substitution string) in a RewriteRule is assumed to be a file path, by default. The use of the [PT] flag causes it to be trated as a URI instead. That is to say, the -use of the [PT] flag causes the result of the RewriteRule to be passed back through -URL mapping, so that location-based mappings, such as Alias, for example, might have a chance to take +use of the [PT] flag causes the result of the RewriteRule to be passed back through +URL mapping, so that location-based mappings, such as Alias, for example, might have a chance to take effect.

If, for example, you have an -Alias -for /icons, and have a RewriteRule pointing there, you should +Alias +for /icons, and have a RewriteRule pointing there, you should use the [PT] flag to ensure that the -Alias is evaluated. +Alias is evaluated.

@@ -313,7 +315,7 @@ ignored, resulting in a 'File not found' error being returned.

`QSA|qsappend`


 
 When the replacement URI contains a query string, the default behavior
-of RewriteRule is to discard
+of RewriteRule is to discard
 the existing query string, and replace it with the newly generated one.
 Using the [QSA] flag causes the query strings to be combined.
 
@@ -359,7 +361,7 @@ URI in request' warnings.
 S|skip
 The [S] flag is used to skip rules that you don't want to run. This
 can be thought of as a goto statement in your rewrite
-ruleset. In the following example, we only want to run the RewriteRule if the requested URI
+ruleset. In the following example, we only want to run the RewriteRule if the requested URI
 doesn't correspond with an actual file.
 
 
@@ -373,8 +375,8 @@ RewriteRule (.*\.gif) images.php?$1

 RewriteRule (.*\.html) docs.php?$1
 
 
-This technique is useful because a RewriteCond only applies to the
-RewriteRule immediately
+
This technique is useful because a RewriteCond only applies to the
+RewriteRule immediately
 following it. Thus, if you want to make a RewriteCond apply
 to several RewriteRules, one possible technique is to
 negate those conditions and use a [Skip] flag.
@@ -383,7 +385,7 @@ negate those conditions and use a [Skip] flag.
 
 T|type
 Sets the MIME type with which the resulting response will be
-sent. This has the same effect as the AddType directive.
+sent. This has the same effect as the AddType directive.
 
 For example, you might use the following technique to serve Perl
 source code as plain text, if requested in a particular way:
@@ -403,7 +405,7 @@ RewriteRule IMG - [T=image/jpg]

Please note that this is a trivial example, and could be better done -using <FilesMatch> +using <FilesMatch> instead. Always consider the alternate solutions to a problem before resorting to rewrite, which will invariably be a less efficient solution than the alternatives.

@@ -411,8 +413,8 @@ invariably be a less efficient solution than the alternatives.

diff --git a/docs/manual/rewrite/rewrite_intro.xml b/docs/manual/rewrite/rewrite_intro.xml index 92f6f17c7e5..760759303e9 100644 --- a/docs/manual/rewrite/rewrite_intro.xml +++ b/docs/manual/rewrite/rewrite_intro.xml @@ -53,6 +53,19 @@ using them without actually understanding what they do.

This document attempts to give sufficient background so that what follows is understood, rather than just copied blindly.

+ +

Remember that many common URL-manipulation tasks don't require the +full power and complexity of mod_rewrite. For simple +tasks, see mod_alias and the documentation +on mapping URLs to the +filesystem.

+ +

Finally, before proceding, be sure to configure +the RewriteLog. Although +this log file can give an overwhelming amount of information, it is +indispensable in debugging problems with mod_rewrite +configuration, since it will tell you exactly how each rule is +processed.

Regular Expressions @@ -140,10 +153,69 @@ ensures that it does not match.

RewriteRule basics -

-Basic anatomy of a RewriteRule, with exhaustively annotated simple -examples. -

A RewriteRule consists +of three arguments separated by spaces. The arguments are

Pattern: which incoming URLs should be affected by the rule;
Substitution: where should the matching requests be sent;
[flags]: options affecting the rewritten request.

+ +

The Pattern is always a regular +expression matched against the URL-Path of the incoming request +(the part after the hostname but before any question mark indicating +the beginning of a query string).

+ +

The Substitution can itself be one of three things:

+ +

A full filesystem path to a resource: + +RewriteRule ^/games.* /usr/local/games/web + +
This maps a request to an arbitrary location on your filesystem, much +like the Alias directive.
+
A web-path to a resource: + +RewriteRule ^/foo$ /bar + +
If DocumentRoot is set +to /usr/local/apache2/htdocs, then this directive would +map requests for http://example.com/foo to the +path /usr/local/apache2/htdocs/bar.
+
An absolute URL: + +RewriteRule ^/product/view$ http://site2.example.com/seeproduct.html [R] + +
This tells the client to make a new request for the specified URL.
+

+ +

The Substitution can also +contain back-references to parts of the incoming URL-path +matched by the Pattern. Consider the following:

+ +RewriteRule ^/product/(.*)/view$ /var/web/productdb/$1 + +

The variable $1 will be replaced with whatever text +was matched by the expression inside the parenthesis in +the Pattern. For example, a request +for http://example.com/product/r14df/view will be mapped +to the path /var/web/productdbr14df.

+ +

If there is more than one expression in parenthesis, they are +available in order in the +variables $1, $2, $3, and so +on.

+ +

Rewrite Flags @@ -158,53 +230,82 @@ RewriteRule ^puppy.html smalldog.html [NC]

For more details on the available flags, their meanings, and -examples, see the Rewrite Flags document.

+examples, see the Rewrite Flags document.

Rewrite conditions -

The RewriteCond directive -allows a condition to be applied to a RewriteRule. -

One or more RewriteCond +directives can be used to restrict the types of requests that will be +subject to the +following RewriteRule. The +first argument is a variable describing a characteristic of the +request, the second argument is a regular +expression that must match the variable, and a third optional +argument is a list of flags that modify how the match is evaluated.

+ +

For example, to send all requests from a particular IP range to a +different server, you could use:

+ +RewriteCond %{REMOTE_ADDR} ^10\2.
+RewriteRule (.*) http://intranet.example.com$1 + + +

When more than +one RewriteCond is +specified, they must all match for +the RewriteRule to be +applied. For example, to deny requests that contain the word "hack" in +their query string, except if they also contain a cookie containing +the word "go", you could use:

+ +RewriteCond %{QUERY_STRING} hack
+RewriteCond %{HTTP_COOKIE} !go
+RewriteRule .* - [F] + +

Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".

+ +

Matches in the regular expressions contained in +the RewriteConds can be +used as part of the Substitution in +the RewriteRule using the +variables %1, %2, etc. For example, this +will direct the request to a different directory depending on the +hostname used to access the site:

+ +RewriteCond %{HTTP_HOST} (.*)
+RewriteRule ^/(.*) /sites/%1/$1 + +

If the request was for http://example.com/foo/bar, +then %1 would contain example.com +and $1 would contain foo/bar.

+ +

Rewrite maps -

Discussion of RewriteMap, including simple, but heavily annotated, -examples.

See RewriteMap.

.htaccess files -

Discussion of the differences between rewrite rules in httpd.conf and -in .htaccess files.

Environment Variables - -

This module keeps track of two additional (non-standard) -CGI/SSI environment variables named SCRIPT_URL -and SCRIPT_URI. These contain the -logical Web-view to the current resource, while the -standard CGI/SSI variables SCRIPT_NAME and -SCRIPT_FILENAME contain the physical -System-view.

- -

Notice: These variables hold the URI/URL as they were -initially requested, i.e., before any -rewriting. This is important because the rewriting process is -primarily used to rewrite logical URLs to physical -pathnames.

- -Example -

-SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
-SCRIPT_FILENAME=/u/rse/.www/index.html
-SCRIPT_URL=/u/rse/
-SCRIPT_URI=http://en1.engelschall.com/u/rse/
-

- +

Rewriting is typically configured in the main server configuration +setting (outside any Directory section) or +inside VirtualHost +containers. This is the easiest way to do rewriting and is +recommended. It is possible, however, to do rewriting +inside Directory +sections or .htaccess +files at the expense of some additional complexity. This technique +is called per-directory rewrites.

+ +

The main difference with per-directory rewrites is that the path +prefix of the directory containing the .htaccess file is +stripped before matching in +the RewriteRule. In addition, the RewriteBase should be used to assure the request is properly mapped.

-- 2.47.2

See also

See also

Documentation

Apache mod_rewrite Flags

Apache mod_rewrite Flags

See also

Introduction

The flags

C|chain

CO|cookie

F|forbidden

L|last

NC|nocase

P|proxy

`QSA|qsappend`

S|skip

T|type

See also

Regular Expressions

RewriteRule basics

Rewrite Flags

Rewrite conditions

Rewrite maps

.htaccess files

Environment Variables

Example