Security

Return-Path: Delivered-To: apmail-httpd-cvs-archive@www.apache.org Received: (qmail 96350 invoked from network); 24 Jan 2006 10:32:36 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 24 Jan 2006 10:32:36 -0000 Received: (qmail 79355 invoked by uid 500); 24 Jan 2006 10:32:30 -0000 Delivered-To: apmail-httpd-cvs-archive@httpd.apache.org Received: (qmail 79152 invoked by uid 500); 24 Jan 2006 10:32:29 -0000 Mailing-List: contact cvs-help@httpd.apache.org; run by ezmlm Precedence: bulk Reply-To: dev@httpd.apache.org list-help: list-unsubscribe: List-Post: List-Id: Delivered-To: mailing list cvs@httpd.apache.org Received: (qmail 79140 invoked by uid 99); 24 Jan 2006 10:32:28 -0000 Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 24 Jan 2006 02:32:28 -0800 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194) by apache.org (qpsmtpd/0.29) with SMTP; Tue, 24 Jan 2006 02:32:26 -0800 Received: (qmail 95949 invoked by uid 65534); 24 Jan 2006 10:32:04 -0000 Message-ID: <20060124103204.95948.qmail@minotaur.apache.org> Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r371884 - /httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml Date: Tue, 24 Jan 2006 10:32:03 -0000 To: cvs@httpd.apache.org From: noirin@apache.org X-Mailer: svnmailer-1.0.5 X-Virus-Checked: Checked by ClamAV on apache.org X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N Author: noirin Date: Tue Jan 24 02:32:00 2006 New Revision: 371884 URL: http://svn.apache.org/viewcvs?rev=371884&view=rev Log: Language fixes for mod_rewrite reference manual Modified: httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml Modified: httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml URL: http://svn.apache.org/viewcvs/httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml?rev=371884&r1=371883&r2=371884&view=diff ============================================================================== --- httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml (original) +++ httpd/httpd/trunk/docs/manual/mod/mod_rewrite.xml Tue Jan 24 02:32:00 2006 @@ -36,18 +36,18 @@

This module uses a rule-based rewriting engine (based on a regular-expression parser) to rewrite requested URLs on the fly. It supports an unlimited number of rules and an - unlimited number of attached rule conditions for each rule to + unlimited number of attached rule conditions for each rule, to provide a really flexible and powerful URL manipulation mechanism. The URL manipulations can depend on various tests, - for instance server variables, environment variables, HTTP - headers, time stamps and even external database lookups in - various formats can be used to achieve a really granular URL + of server variables, environment variables, HTTP + headers, or time stamps. Even external database lookups in + various formats can be used to achieve highly granular URL matching.

This module operates on the full URLs (including the path-info part) both in per-server context (httpd.conf) and per-directory context - (.htaccess) and can even generate query-string + (.htaccess) and can generate query-string parts on result. The rewritten result can lead to internal sub-processing, external request redirection or even to an internal proxy throughput.

@@ -79,8 +79,8 @@ 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 + initially requested, that is, before any + rewriting. This is important to note because the rewriting process is primarily used to rewrite logical URLs to physical pathnames.

@@ -147,12 +147,13 @@

The RewriteOptions directive sets some special options for the current per-server or per-directory - configuration. The Option string can be currently only one:

+ configuration. The Option string can currently + only be one of the following:

inherit

This forces the current configuration to inherit the - configuration of the parent. In per-virtual-server context + configuration of the parent. In per-virtual-server context, this means that the maps, conditions and rules of the main server are inherited. In per-directory context this means that conditions and rules of the parent directory's @@ -192,7 +193,7 @@ Security See the Apache Security Tips -document for details on why your security could be compromised if the +document for details on how your security could be compromised if the directory where logfiles are stored is writable by anyone other than the user that starts the server. @@ -288,7 +289,7 @@ }

When such a construct occurs the map MapName is +

When such a construct occurs, the map MapName is consulted and the key LookupKey is looked-up. If the key is found, the map-function construct is substituted by SubstValue. If the key is not found then it is @@ -435,23 +436,23 @@ MapType: int, MapSource: Internal Apache function -

Here the source is an internal Apache function. +

Here, the source is an internal Apache function. Currently you cannot create your own, but the following - functions already exists:

+ functions already exist:

toupper:
- Converts the looked up key to all upper case.
tolower:
- Converts the looked up key to all lower case.
escape:
- Translates special characters in the looked up key to + Translates special characters in the key to hex-encodings.
unescape:
- Translates hex-encodings in the looked up key back to + Translates hex-encodings in the key back to special characters.

@@ -462,15 +463,15 @@ path to valid regular file

Here the source is a program, not a map file. To - create it you can use the language of your choice, but - the result has to be a executable (i.e., either + create it you can use a language of your choice, but + the result has to be an executable program (either object-code or a script with the magic cookie trick '#!/path/to/interpreter' as the first line).

This program is started once at startup of the Apache - servers and then communicates with the rewriting engine - over its stdin and stdout +

This program is started once, when the Apache server + is started, and then communicates with the rewriting engine + via its stdin and stdout file-handles. For each map-function lookup it will receive the key to lookup as a newline-terminated string on stdin. It then has to give back the @@ -495,18 +496,18 @@

But be very careful:

``Keep it simple, stupid'' (KISS), because - if this program hangs it will hang the Apache server - when the rule occurs.
Avoid one common mistake: never do buffered I/O on - stdout! This will cause a deadloop! Hence - the ``$|=1'' in the above example...
Use the RewriteLock directive to - define a lockfile mod_rewrite can use to synchronize the - communication to the program. By default no such +
``Keep it simple, stupid'' (KISS). + If this program hangs, it will cause Apache to hang + when trying to use the relevant rewrite rule.
A common mistake is to use buffered I/O on + stdout. Avoid this, as it will cause a deadloop! + ``$|=1'' is used above, to prevent this.
The RewriteLock directive can + be used to define a lockfile which mod_rewrite can use to synchronize + communication with the mapping program. By default no such synchronization takes place.

@@ -543,26 +544,26 @@ sets the base URL for per-directory rewrites. As you will see below, RewriteRule can be used in per-directory config files - (.htaccess). There it will act locally, - i.e., the local directory prefix is stripped at this - stage of processing and your rewriting rules act only on the - remainder. At the end it is automatically added back to the + (.htaccess). In such a case, it will act locally, + stripping the local directory prefix before processing, and applying + rewrite rules only to the remainder. When processing is complete, the + prefix is automatically added back to the path. The default setting is; RewriteBase physical-directory-path

When a substitution occurs for a new URL, this module has to re-inject the URL into the server processing. To be able to do this it needs to know what the corresponding URL-prefix or URL-base is. By default this prefix is the corresponding - filepath itself. But at most websites URLs are NOT + filepath itself. However, for most websites, URLs are NOT directly related to physical filename paths, so this - assumption will usually be wrong! There you have to + assumption will often be wrong! Therefore, you can use the RewriteBase directive to specify the correct URL-prefix.

If your webserver's URLs are not directly -related to physical file paths, you have to use +related to physical file paths, you will need to use RewriteBase in every .htaccess -files where you want to use RewriteRule directives. @@ -607,17 +608,15 @@ Result: /abc/def/newstuff.html -

This seems very complicated but is - the correct Apache internal processing, because the - per-directory rewriting comes too late in the - process. So, when it occurs the (rewritten) request - has to be re-injected into the Apache kernel! BUT: - While this seems like a serious overhead, it really - isn't, because this re-injection happens fully - internally to the Apache server and the same - procedure is used by many other operations inside - Apache. So, you can be sure the design and - implementation is correct.

This seems very complicated, but is in fact + correct Apache internal processing. Because the + per-directory rewriting comes late in the + process, the rewritten request + has to be re-injected into the Apache kernel. + This is not the serious overhead it may seem to be - + this re-injection is completely internal to the + Apache server (and the same procedure is used by + many other operations within Apache).

@@ -636,63 +635,44 @@

The RewriteCond directive defines a - rule condition. Precede a RewriteRule directive with one - or more RewriteCond directives. The following - rewriting rule is only used if its pattern matches the current - state of the URI and if these additional - conditions apply too.

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

TestString is a string which can contains the +

TestString is a string which can contain the following expanded constructs in addition to plain text:

RewriteRule backreferences: These are - backreferences of the form - -
- $N -
- (0 <= N <= 9) which provide access to the grouped - parts (parenthesis!) of the pattern from the - corresponding RewriteRule directive (the one - following the current bunch of RewriteCond - directives). + backreferences of the form $N + (0 <= N <= 9), which provide access to the grouped + parts (in parentheses) of the pattern, from the + RewriteRule which is subject to the current + set of RewriteCond conditions..
RewriteCond backreferences: These are - backreferences of the form - -
- %N -
- (1 <= N <= 9) which provide access to the grouped - parts (parentheses!) of the pattern from the last matched - RewriteCond directive in the current bunch + backreferences of the form %N + (1 <= N <= 9), which provide access to the grouped + parts (again, in parentheses) of the pattern, from the last matched + RewriteCond in the current set of conditions.
RewriteMap expansions: These are - expansions of the form - -
- ${mapname:key|default} -
+ expansions of the form ${mapname:key|default}. See the documentation for RewriteMap for more details.
Server-Variables: These are variables of the form - -
%{ NAME_OF_VARIABLE } -
where NAME_OF_VARIABLE can be a string taken from the following list: @@ -767,15 +747,14 @@ -
These variables all correspond to the similarly named HTTP MIME-headers, C variables of the Apache server or struct tm fields of the Unix system. Most are documented elsewhere in the Manual or in the CGI specification. Those that are special to - mod_rewrite include:
- + mod_rewrite include those below.
+

IS_SUBREQ
@@ -819,7 +798,7 @@
Will contain the text "on" if the connection is using SSL/TLS, or "off" otherwise. (This variable - can be safely used regardless of whether + can be safely used regardless of whether or not mod_ssl is loaded).

@@ -827,69 +806,72 @@

Special Notes:

Other things you should be aware of:

The variables SCRIPT_FILENAME and REQUEST_FILENAME - contain the same value, i.e., the value of the + contain the same value - the value of the filename field of the internal request_rec structure of the Apache server. - The first name is just the commonly known CGI variable name - while the second is the consistent counterpart to + 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 uri field of request_rec).
There is the special format: - %{ENV:variable} where variable can be - any environment variable. This is looked-up via internal +
+ %{ENV:variable}, where variable can be + any environment variable, is also available. + This is looked-up via internal Apache structures and (if not found there) via getenv() from the Apache server process.
There is the special format: - %{SSL:variable} where variable is the +
+ %{SSL:variable}, where variable is the name of an SSL environment - variable; this can be used whether or not + variable, can be used whether or not mod_ssl is loaded, but will always expand to the empty string if it is not. Example: %{SSL:SSL_CIPHER_USEKEYSIZE} may expand to 128.
There is the special format: - %{HTTP:header} where header can be - any HTTP MIME-header name. This is looked-up from the HTTP - request. Example: %{HTTP:Proxy-Connection} is +
+ %{HTTP:header}, where header can be + any HTTP MIME-header name, can always be used to obtain the + value of a header sent in the HTTP request. + Example: %{HTTP:Proxy-Connection} is the value of the HTTP header ``Proxy-Connection:''.
There is the special format - %{LA-U:variable} for look-aheads which perform +
+ %{LA-U:variable} can be used for look-aheads which perform an internal (URL-based) sub-request to determine the final - value of variable. Use this when you want to use a - variable for rewriting which is actually set later in an - API phase and thus is not available at the current stage. - For instance when you want to rewrite according to the + value of variable. This can be used to access + variable for rewriting which is not available at the current + stage, but will be set in a later phase. +
For instance, to rewrite according to the REMOTE_USER variable from within the - per-server context (httpd.conf file) you have - to use %{LA-U:REMOTE_USER} because this - variable is set by the authorization phases which come - after the URL translation phase where mod_rewrite - operates. On the other hand, because mod_rewrite implements + per-server context (httpd.conf file) you must + use %{LA-U:REMOTE_USER} - this + variable is set by the authorization phases, which come + after the URL translation phase (during which mod_rewrite + operates).
+
On the other hand, because mod_rewrite implements its per-directory context (.htaccess file) via the Fixup phase of the API and because the authorization phases come before this phase, you just can use - %{REMOTE_USER} there.

%{REMOTE_USER}

There is the special format: - %{LA-F:variable} which performs an internal - (filename-based) sub-request to determine the final value - of variable. Most of the time this is the same as +
+ %{LA-F:variable} can be used to perform an internal + (filename-based) sub-request, to determine the final value + of variable. Most of the time, this is the same as LA-U above.

CondPattern is the condition pattern, - i.e., a regular expression which is applied to the - current instance of the TestString, i.e., - TestString is evaluated and then matched against + a regular expression which is applied to the + current instance of the TestString. + TestString is first evaluated, before being matched against CondPattern.

Remember: CondPattern is a @@ -907,98 +889,94 @@ use one of the following:

'<CondPattern' (is lexically - lower)
- Treats the CondPattern as a plain string and - compares it lexically to TestString. True if - TestString is lexically lower than +
'<CondPattern' (lexicographically + precedes)
+ Treats the CondPattern as a plain string and + compares it lexicographically to TestString. True if + TestString lexicographically precedes CondPattern.
'>CondPattern' (is lexically - greater)
- Treats the CondPattern as a plain string and - compares it lexically to TestString. True if - TestString is lexically greater than +
'>CondPattern' (lexicographically + follows)
+ Treats the CondPattern as a plain string and + compares it lexicographically to TestString. True if + TestString lexicographically follows CondPattern.
'=CondPattern' (is lexically +
'=CondPattern' (lexicographically equal)
- Treats the CondPattern as a plain string and - compares it lexically to TestString. True if - TestString is lexically equal to - CondPattern, i.e the two strings are exactly - equal (character by character). If CondPattern - is just "" (two quotation marks) this + Treats the CondPattern as a plain string and + compares it lexicographically to TestString. True if + TestString is lexicographically equal to + CondPattern (the two strings are exactly + equal, character for character). If CondPattern + is "" (two quotation marks) this compares TestString to the empty string.
'-d' (is directory)
Treats the TestString as a pathname and tests - if it exists and is a directory.
'-f' (is regular file)
Treats the TestString as a pathname and tests - if it exists and is a regular file.
'-s' (is regular file with +
'-s' (is regular file, with size)
- Treats the TestString as a pathname and tests - if it exists and is a regular file with size greater + Treats the TestString as a pathname and tests + whether or not it exists, and is a regular file with size greater than zero.
'-l' (is symbolic link)
- Treats the TestString as a pathname and tests - if it exists and is a symbolic link.

TestString

'-x' (has executable permissions)
Treats the TestString as a pathname and tests - if it exists and has execution permissions. These permissions - are determined depending on the underlying OS.
'-F' (is existing file via +
'-F' (is existing file, via subrequest)
- Checks if TestString is a valid file and + Checks whether or not TestString is a valid file, accessible via all the server's currently-configured access controls for that path. This uses an internal - subrequest to determine the check, so use it with care - because it decreases your servers performance!
'-U' (is existing URL via +
'-U' (is existing URL, via subrequest)
- Checks if TestString is a valid URL and + Checks whether or not TestString is a valid URL, accessible via all the server's currently-configured access controls for that path. This uses an internal - subrequest to determine the check, so use it with care - because it decreases your server's performance!

-Notice +Note: All of these tests can also be prefixed by an exclamation mark ('!') to negate their meaning. - - -

Additionally you can set special flags for - CondPattern by appending

You can also set special flags for + CondPattern by appending [flags] -

- -

as the third argument to the RewriteCond - directive. Flags is a comma-separated list of the - following flags:

+ as the third argument to the RewriteCond + directive, where flags is a comma-separated list of any of the + following flags:

'nocase|NC' (no case)
- This makes the test case-insensitive, i.e., there - is no difference between 'A-Z' and 'a-z' both in the + This makes the test case-insensitive - differences + between 'A-Z' and 'a-z' are ignored, both in the expanded TestString and the CondPattern. This flag is effective only for comparisons between TestString and CondPattern. It has no @@ -1007,7 +985,7 @@
'ornext|OR' (or next condition)
- Use this to combine rule conditions with a local OR + Use this to combine rule conditions with a local OR instead of the implicit AND. Typical example: @@ -1019,10 +997,11 @@ - Without this flag you would have to write the cond/rule - three times. + Without this flag you would have to write the condition/rule + pair three times.

Example:

@@ -1042,13 +1021,16 @@ -

Interpretation: If you use Netscape Navigator as your - browser (which identifies itself as 'Mozilla'), then you - get the max homepage, which includes Frames, etc. - If you use the Lynx browser (which is Terminal-based), then - you get the min homepage, which contains no images, no - tables, etc. If you use any other browser you get - the standard homepage.

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.

@@ -1066,57 +1048,55 @@

The RewriteRule directive is the real - rewriting workhorse. The directive can occur more than once. - Each directive then defines one single rewriting rule. The - definition order of these rules is - important, because this order is used when - applying the rules at run-time.

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

Pattern is a perl compatible regular - expression which gets applied to the current URL. Here - ``current'' means the value of the URL when this rule gets + 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, - because any number of rules may already have matched and made - alterations to it.

+ which may already have matched a previous rule, and have been + altered.

Some hints about the syntax of regular +

Some hints on the syntax of regular expressions:

 Text:
   .           Any single character
-  [chars]     Character class: One  of chars
-  [^chars]    Character class: None of chars
+  [chars]     Character class: Any character of the class ``chars''
+  [^chars]    Character class: Not a character of the class ``chars''
   text1|text2 Alternative: text1 or text2
 
 Quantifiers:
-  ?           0 or 1 of the preceding text
-  *           0 or N of the preceding text (N > 0)
-  +           1 or N of the preceding text (N > 1)
+  ?           0 or 1 occurrences of the preceding text
+  *           0 or N occurrences of the preceding text (N > 0)
+  +           1 or N occurrences of the preceding text (N > 1)
 
 Grouping:
   (text)      Grouping of text
-              (either to set the borders of an alternative or
-              for making backreferences where the Nth group can 
-              be used on the RHS of a RewriteRule with $N)
+              (used either to set the borders of an alternative as above, or
+              to make backreferences, where the Nth group can 
+              be referred to on the RHS of a RewriteRule as $N)
 
 Anchors:
-  ^           Start of line anchor
-  $           End   of line anchor
+  ^           Start-of-line anchor
+  $           End-of-line anchor
 
 Escaping:
-  \char       escape that particular char
-              (for instance to specify the chars ".[]()" etc.)
+  \char       escape the given char
+              (for instance, to specify the chars ".[]()" etc.)

For more information about regular expressions have a look at the +

For more information about regular expressions, have a look at the perl regular expression manpage ("perldoc perlre"). If you are interested in more detailed information about regular expressions and their variants - (POSIX regex etc.) have a look at the - following dedicated book on this topic:

+ (POSIX regex etc.) the following book is dedicated to this topic:

Mastering Regular Expressions, 2nd Edition
@@ -1125,34 +1105,32 @@ ISBN 0-596-00289-0

Additionally in mod_rewrite the NOT character - ('!') is a possible pattern prefix. This gives - you the ability to negate a pattern; to say, for instance: +

In mod_rewrite, the NOT character + ('!') is also available as a possible pattern + prefix. This enables you to negate a pattern; to say, for instance: ``if the current URL does NOT match this pattern''. This can be used for exceptional cases, where it is easier to match the negative pattern, or as a last default rule.

-Notice -When using the NOT character - to negate a pattern you cannot have grouped wildcard - parts in the pattern. This is impossible because when the - pattern does NOT match, there are no contents for the - groups. In consequence, if negated patterns are used, you - cannot use $N in the substitution - string! +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 (ie, the negation matches), there are no +contents for the groups. Thus, if negated patterns are used, you +cannot use $N in the substitution string! -

Substitution of a - rewriting rule is the string which is substituted for (or - replaces) the original URL for which Pattern - matched. Beside plain text you can use

The substitution of a + rewrite rule is the string which is substituted for (or + replaces) the original URL which Pattern + matched. In addition to plain text, it can include

back-references $N to the RewriteRule +
back-references ($N) to the RewriteRule pattern
back-references %N to the last matched +
back-references (%N) to the last matched RewriteCond pattern
server-variables as in rule condition test-strings @@ -1161,75 +1139,38 @@
mapping-function calls (${mapname:key|default})

Back-references are $N - (N=0..9) identifiers which will be replaced +

Back-references are identifiers of the form + $N + (N=0..9), which will be replaced by the contents of the Nth group of the matched Pattern. The server-variables are the same as for the TestString of a RewriteCond directive. The mapping-functions come from the RewriteMap directive and are explained there. - These three types of variables are expanded in the order of - the above list.

+ These three types of variables are expanded in the order above.

As already mentioned above, all the rewriting rules are - applied to the Substitution (in the order of - definition in the config file). The URL is completely +

As already mentioned, all rewrite rules are + applied to the Substitution (in the in which they are defined + in the config file). The URL is completely replaced by the Substitution and the - rewriting process goes on until there are no more rules - unless explicitly terminated by a + rewriting process continues until all rules have been applied, + or it is explicitly terminated by a L flag - see below.

There is a special substitution string named '-' which means: NO - substitution! Sounds silly? No, it is useful to - provide rewriting rules which only match - some URLs but do no substitution, e.g., in - conjunction with the C (chain) flag to be - able to have more than one pattern to be applied before a - substitution occurs.
- -Query String -
The Pattern will not match against the query string. - Instead, you must use a RewriteCond with the - %{QUERY_STRING} variable. You can, however, create - URLs in the substitution string containing a query string - part. Just use a question mark inside the substitution string to - indicate that the following stuff should be re-injected into the - query string. When you want to erase an existing query string, - end the substitution string with just the question mark. To - combine a new query string with an old one, use the - [QSA] flag (see below).
- + substitution! This is useful in providing + rewriting rules which only match + URLs but do not substitute anything for them. It is commonly used + in conjunction with the C (chain) flag, in order + to apply more than one pattern before substitution occurs.

-Substitution of Absolute URLs -

There is a special feature: - When you prefix a substitution field with - http://thishost[:thisport] - then mod_rewrite automatically strips it - out. This auto-reduction on implicit external redirect - URLs is a useful and important feature when used in - combination with a mapping-function which generates the - hostname part. Have a look at the first example in the - example section below to understand this.

- -

Remember: An unconditional external - redirect to your own server will not work with the prefix - http://thishost because of this feature. To - achieve such a self-redirect, you have to use the - R-flag (see below).

Additionally you can set special flags for Substitution by - appending

- -

- [flags] -

+ appending [flags] as the third argument to the RewriteRule - directive. Flags is a comma-separated list of the + directive. Flags is a comma-separated list of any of the following flags:

etc.

i.e.

not

.www

'cookie|CO=NAME:VAL:domain[:lifetime[:path]]' (set cookie)
- This sets a cookie on the client's browser. The cookie's name + This sets a cookie in the client's browser. The cookie's name is specified by NAME and the value is VAL. The domain field is the domain of the - cookie, such as '.apache.org',the optional lifetime + cookie, such as '.apache.org', the optional lifetime is the lifetime of the cookie in minutes, and the optional path is the path of the cookie
'env|E=VAR:VAL' (set environment variable)
- This forces an environment variable named VAR to + This forces an environment variable named VAR to be set to the value VAL, where VAL can - contain regexp backreferences $N and - %N which will be expanded. You can use this - flag more than once to set more than one variable. The - variables can be later dereferenced in many situations, but - usually from within XSSI (via ) or CGI (e.g. - $ENV{'VAR'}). Additionally you can dereference - it in a following RewriteCond pattern via - %{ENV:VAR}. Use this to strip but remember - information from URLs.

$N

%N

<!--#echo
+        var="VAR"-->

$ENV{'VAR'}

%{ENV:VAR}

'forbidden|F' (force URL to be forbidden)
- This forces the current URL to be forbidden, - i.e., it immediately sends back a HTTP response of - 403 (FORBIDDEN). Use this flag in conjunction with + 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.
'gone|G' (force URL to be gone)
- This forces the current URL to be gone, i.e., it + 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.

Content-handler

mod_alias

ScriptAlias

mod_alias

ScriptAlias

cgi-script

'last|L' (last rule)
- Stop the rewriting process here and don't apply any more - rewriting rules. This corresponds to the Perl + Stop the rewriting process here and don't apply any more + rewrite rules. This corresponds to the Perl last command or the break command - from the C language. Use this flag to prevent the currently + 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 ('/') to a real one, e.g., @@ -1309,20 +1250,20 @@
'next|N' (next round)
- Re-run the rewriting process (starting again with the - first rewriting rule). Here the URL to match is again not - the original URL but the URL from the last rewriting rule. + 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 next command or - the continue command from the C language. Use - this flag to restart the rewriting process, i.e., + the continue command in C. Use + this flag to restart the rewriting process - to immediately go to the top of the loop.
- But be careful not to create an infinite + Be careful not to create an infinite loop!

'nocase|NC' (no case)
- This makes the Pattern case-insensitive, - i.e., there is no difference between 'A-Z' and + This makes the Pattern case-insensitive, + ignoring difference between 'A-Z' and 'a-z' when Pattern is matched against the current URL.
@@ -1330,61 +1271,58 @@ 'noescape|NE' (no URI escaping of output)
- This flag keeps mod_rewrite from applying the usual URI + This flag prevents mod_rewrite 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 being done. This allows percent symbols to appear in + from happening. This allows percent symbols to appear in the output, as in RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE] - which would turn '/foo/zed' into a safe request for '/bar?arg=P1=zed'.
- 'nosubreq|NS' (used only if - no internal - sub-request)
- This flag forces the rewriting engine to skip a + 'nosubreq|NS' + (not for internal + sub-requests)
+ This flag forces the rewriting engine to skip a rewriting rule if the current request is an internal sub-request. For instance, sub-requests occur internally - in Apache when mod_include tries to find out + in Apache when mod_include tries to find out information about possible directory default files - (index.xxx). On sub-requests it is not - always useful and even sometimes causes a failure to if + (index.xxx files). On sub-requests it is not + always useful, and can even cause errors, if the complete set of rules are applied. Use this flag to exclude some rules.
- - -
Use the following rule for your decision: whenever you - prefix some URLs with CGI-scripts to force them to be - processed by the CGI-script, the chance is high that you - will run into problems (or even overhead) on - sub-requests. In these cases, use this flag.
+ To decide whether or not to use this rule: if you + prefix URLs with CGI-scripts, to force them to be + processed by the CGI-script, it's likely that you + will run into problems (or significant overhead) on + sub-requests. In these cases, use this flag.

'proxy|P' (force proxy)
- This flag forces the substitution part to be internally - forced as a proxy request and immediately (i.e., - rewriting rule processing stops here) put through the proxy module. You have to make + This flag forces the substitution part to be internally + sent as a proxy request and immediately (rewrite + processing stops here) put through the proxy module. You must make sure that the substitution string is a valid URI - (e.g., typically starting with + (typically starting with http://hostname) which can be - handled by the Apache proxy module. If not you get an + 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 ProxyPass directive, - to map some remote stuff into the namespace of the local + to map remote content into the namespace of the local server. -
Notice: mod_proxy must be enabled in order +
Note: mod_proxy must be enabled in order to use this flag.

@@ -1392,82 +1330,80 @@ 'passthrough|PT' (pass through to next handler)
- This flag forces the rewriting engine to set the + This flag forces the rewrite engine to set the uri field of the internal request_rec structure to the value of the filename field. This flag is just a hack to - be able to post-process the output of - RewriteRule directives by + enable post-processing of the output of + RewriteRule directives, using Alias, ScriptAlias, - Redirect, etc. directives from - other URI-to-filename translators. A trivial example to - show the semantics: If you want to rewrite - /abc to /def via the rewriting - engine of mod_rewrite and then - /def to /ghi with - mod_alias: + Redirect, and other directives from + various URI-to-filename translators. For example, to rewrite + /abc to /def using + mod_rewrite, and then + /def to /ghi using + mod_alias: RewriteRule ^/abc(.*) /def$1 [PT]
Alias /def /ghi - If you omit the PT flag then - mod_rewrite will do its job fine, - i.e., it rewrites uri=/abc/... to + If you omit the PT flag, + mod_rewrite will rewrite + uri=/abc/... to filename=/def/... as a full API-compliant URI-to-filename translator should do. Then - mod_alias comes and tries to do a - URI-to-filename transition which will not work. + mod_alias will try to do a + URI-to-filename transition, which will fail. -
Note: You have to use this flag if you want to - intermix directives of different modules which contain +
Note: You must use this flag if you want to + mix directives from different modules which allow URL-to-filename translators. The typical example - is the use of mod_alias and - mod_rewrite..
+ is the use of mod_alias and + mod_rewrite.

'qsappend|QSA' (query string append)
- This flag forces the rewriting engine to append a query - string part in the substitution string to the existing one + This flag forces the rewrit 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.

'redirect|R [=code]' (force redirect)
- Prefix Substitution with + Prefix Substitution with http://thishost[:thisport]/ (which makes the new URL a URI) to force a external redirection. If no - code is given a HTTP response of 302 (MOVED - TEMPORARILY) is used. If you want to use other response - codes in the range 300-400 just specify them as a number + code is given, a HTTP response of 302 (MOVED + TEMPORARILY) will be returned. If you want to use other response + codes in the range 300-400, simply specify the appropriate number or use one of the following symbolic names: temp (default), permanent, - seeother. Use it for rules which should - canonicalize the URL and give it back to the client, - e.g., translate ``/~'' into - ``/u/'' or always append a slash to + seeother. Use this for rules to + canonicalize the URL and return it to the client - to + translate ``/~'' into + ``/u/'', or to always append a slash to /u/user, etc.
-
Note: When you use this flag, make - sure that the substitution field is a valid URL! If not, - you are redirecting to an invalid location! And remember - that this flag itself only prefixes the URL with - http://thishost[:thisport]/, rewriting - continues. Usually you also want to stop and do the - redirection immediately. To stop the rewriting you also - have to provide the 'L' flag.
+ 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 + http://thishost[:thisport]/ 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.

'skip|S=num' (skip next rule(s))
- This flag forces the rewriting engine to skip the next - num rules in sequence when the current rule + This flag forces the rewriting engine to skip the next + num 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 - skip=N where N is the number of rules in the + skip=N, where N is the number of rules in the else-clause. (This is not the same as the 'chain|C' flag!)
@@ -1475,8 +1411,8 @@ 'type|T=MIME-type' (force MIME type)
Force the MIME-type of the target file to be - MIME-type. For instance, this can be used to - setup the content-type based on some conditions. + MIME-type. This can be used to + set up the content-type based on some conditions. For example, the following snippet allows .php files to be displayed by mod_php if they are called with the .phps extension: @@ -1484,40 +1420,70 @@ RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source] - -

-Note Never forget that Pattern is +Note: Enabling rewrites in per-directory context + To enable the rewrite engine + for per-directory configuration files you need to set + ``RewriteEngine On'' in these files + and ``Options + FollowSymLinks'' must be enabled. If your + administrator has disabled override of + FollowSymLinks for a user's directory, then + you cannot use the rewrite engine. This restriction is + required for security reasons. + + +Note: Pattern matching in per-directory context + Never forget that Pattern is applied to a complete URL in per-server configuration -files. But in per-directory configuration files, the +files. However, in per-directory configuration files, the per-directory prefix (which always is the same for a specific -directory!) is automatically removed for the pattern matching +directory) is automatically removed for the pattern matching and automatically added after the substitution has been -done. This feature is essential for many sorts of rewriting, -because without this prefix stripping you have to match the parent -directory which is not always possible. +done. This feature is essential for many sorts of rewriting - +without this, you would always have to match the parent +directory, which is not always possible.
There is one exception: If a substitution string - starts with ``http://'' then the directory - prefix will not be added and an - external redirect or proxy throughput (if flag - P is used!) is forced!
+ starts with ``http://'', then the directory + prefix will not be added ,and an + external redirect (or proxy throughput, if using flag + P) is forced!
-Note - To enable the rewriting engine - for per-directory configuration files you need to set - ``RewriteEngine On'' in these files - and ``Options - FollowSymLinks'' must be enabled. If your - administrator has disabled override of - FollowSymLinks for a user's directory, then - you cannot use the rewriting engine. This restriction is - needed for security reasons. +Note: Substitution of Absolute URLs +
+ When you prefix a substitution field with + http://thishost[:thisport], mod_rewrite will automatically strip that + out. This auto-reduction on URLs with an implicit + external redirect is most useful in + combination with a mapping-function which generates the + hostname part.
+ +
Remember: An unconditional external + redirect to your own server will not work with the prefix + http://thishost because of this feature. To + achieve such a self-redirect, you have to use the + R-flag (see below).
+ + +Note: Query String +
The Pattern will not be matched against the query string. + To do this, you must use a RewriteCond with the + %{QUERY_STRING} variable. You can, however, create + URLs in the substitution string, containing a query string + part. Simply use a question mark inside the substitution string, to + indicate that the following text should be re-injected into the + query string. When you want to erase an existing query string, + end the substitution string with just a question mark. To + combine new and old query strings, use the + [QSA] flag (see above).
-
Here are all possible substitution combinations and their +
Here are all possible substitution combinations and their meanings:

Inside per-server configuration @@ -1529,25 +1495,25 @@
Given Rule Resulting Substitution ---------------------------------------------- ---------------------------------- -^/somepath(.*) otherpath$1 not supported, because invalid! +^/somepath(.*) otherpath$1 invalid, not supported -^/somepath(.*) otherpath$1 [R] not supported, because invalid! +^/somepath(.*) otherpath$1 [R] invalid, not supported -^/somepath(.*) otherpath$1 [P] not supported, because invalid! +^/somepath(.*) otherpath$1 [P] invalid, not supported ---------------------------------------------- ---------------------------------- ^/somepath(.*) /otherpath$1 /otherpath/pathinfo ^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo via external redirection -^/somepath(.*) /otherpath$1 [P] not supported, because silly! +^/somepath(.*) /otherpath$1 [P] doesn't make sense, not supported ---------------------------------------------- ---------------------------------- ^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo ^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo via external redirection -^/somepath(.*) http://thishost/otherpath$1 [P] not supported, because silly! +^/somepath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported ---------------------------------------------- ---------------------------------- ^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo via external redirection @@ -1562,8 +1528,7 @@
Inside per-directory configuration for /somepath
- (i.e., file .htaccess in dir - /physical/path/to/somepath containing + (/physical/path/to/somepath/.htacccess, with RewriteBase /somepath)
for request ``GET /somepath/localpath/pathinfo'':
@@ -1577,21 +1542,21 @@ ^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo via external redirection -^localpath(.*) otherpath$1 [P] not supported, because silly! +^localpath(.*) otherpath$1 [P] doesn't make sense, not supported ---------------------------------------------- ---------------------------------- ^localpath(.*) /otherpath$1 /otherpath/pathinfo ^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo via external redirection -^localpath(.*) /otherpath$1 [P] not supported, because silly! +^localpath(.*) /otherpath$1 [P] doesn't make sense, not supported ---------------------------------------------- ---------------------------------- ^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo ^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo via external redirection -^localpath(.*) http://thishost/otherpath$1 [P] not supported, because silly! +^localpath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported ---------------------------------------------- ---------------------------------- ^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo via external redirection @@ -1603,35 +1568,6 @@ ^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo via internal proxy
- -
Example:
- -
We want to rewrite URLs of the form
- -
- / Language /~ - Realname /.../ File -
- -
into
- -
- /u/ Username /.../ - File . Language -
- -
We take the rewrite mapfile from above and save it under - /path/to/file/map.txt. Then we only have to - add the following lines to the Apache server configuration - file:
- - -
-RewriteLog /path/to/file/rewrite.log -RewriteMap real-to-user txt:/path/to/file/map.txt -RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1 -
-