From bff3be8216a04344fa6da2fce99c55476d469c57 Mon Sep 17 00:00:00 2001 From: Henning Brauer Date: Mon, 17 Nov 2003 19:05:48 +0000 Subject: this is historic as of 1.3.29 --- usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html | 2117 --------------------- 1 file changed, 2117 deletions(-) delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html (limited to 'usr.sbin') diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html b/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html deleted file mode 100644 index 341426057cc..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html +++ /dev/null @@ -1,2117 +0,0 @@ - - - - - - - - - - Apache module mod_rewrite - - - - -
- -
- [APACHE DOCUMENTATION] - -

Apache HTTP Server Version 1.3

-
- -
- - -

Module mod_rewrite
- URL Rewriting Engine

- -

This module provides a rule-based rewriting engine to - rewrite requested URLs on the fly.

- -

Status: Extension
- Source File: - mod_rewrite.c
- Module Identifier: - rewrite_module
- Compatibility: Available in - Apache 1.2 and later.

-
-
- - -

Summary

- -
-
-
- ``The great thing about mod_rewrite is it gives you - all the configurability and flexibility of Sendmail. - The downside to mod_rewrite is that it gives you all - the configurability and flexibility of Sendmail.'' - - -
- -- Brian Behlendorf
- Apache Group -
-
-
-
- -
-
-
- `` Despite the tons of examples and docs, - mod_rewrite is voodoo. Damned cool voodoo, but still - voodoo. '' - -
- -- Brian Moore
- bem@news.cmc.net -
-
-
-
- Welcome to mod_rewrite, the Swiss Army Knife of URL - manipulation! - -

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 - 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 - 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 - parts on result. The rewritten result can lead to internal - sub-processing, external request redirection or even to an - internal proxy throughput.

- -

But all this functionality and flexibility has its - drawback: complexity. So don't expect to understand this - entire module in just one day.

- -

This module was invented and originally written in April - 1996
- and gifted exclusively to the The Apache Group in July 1997 - by

- -
- Ralf S. - Engelschall
- rse@engelschall.com
- www.engelschall.com -
-
- -

Table Of Contents

- -

Internal Processing

- - - -

Configuration Directives

- - - Miscellaneous - - -
- -
-

Internal - Processing

-
-
- -

The internal processing of this module is very complex but - needs to be explained once even to the average user to avoid - common mistakes and to let you exploit its full - functionality.

- -

API - Phases

- -

First you have to understand that when Apache processes a - HTTP request it does this in phases. A hook for each of these - phases is provided by the Apache API. Mod_rewrite uses two of - these hooks: the URL-to-filename translation hook which is - used after the HTTP request has been read but before any - authorization starts and the Fixup hook which is triggered - after the authorization phases and after the per-directory - config files (.htaccess) have been read, but - before the content handler is activated.

- -

So, after a request comes in and Apache has determined the - corresponding server (or virtual server) the rewriting engine - starts processing of all mod_rewrite directives from the - per-server configuration in the URL-to-filename phase. A few - steps later when the final data directories are found, the - per-directory configuration directives of mod_rewrite are - triggered in the Fixup phase. In both situations mod_rewrite - rewrites URLs either to new URLs or to filenames, although - there is no obvious distinction between them. This is a usage - of the API which was not intended to be this way when the API - was designed, but as of Apache 1.x this is the only way - mod_rewrite can operate. To make this point more clear - remember the following two points:

- -
    -
  1. Although mod_rewrite rewrites URLs to URLs, URLs to - filenames and even filenames to filenames, the API - currently provides only a URL-to-filename hook. In Apache - 2.0 the two missing hooks will be added to make the - processing more clear. But this point has no drawbacks for - the user, it is just a fact which should be remembered: - Apache does more in the URL-to-filename hook than the API - intends for it.
    2. - -
  2. - Unbelievably mod_rewrite provides URL manipulations in - per-directory context, i.e., within - .htaccess files, although these are reached - a very long time after the URLs have been translated to - filenames. It has to be this way because - .htaccess files live in the filesystem, so - processing has already reached this stage. In other - words: According to the API phases at this time it is too - late for any URL manipulations. To overcome this chicken - and egg problem mod_rewrite uses a trick: When you - manipulate a URL/filename in per-directory context - mod_rewrite first rewrites the filename back to its - corresponding URL (which is usually impossible, but see - the RewriteBase directive below for the - trick to achieve this) and then initiates a new internal - sub-request with the new URL. This restarts processing of - the API phases. - -

    Again mod_rewrite tries hard to make this complicated - step totally transparent to the user, but you should - remember here: While URL manipulations in per-server - context are really fast and efficient, per-directory - rewrites are slow and inefficient due to this chicken and - egg problem. But on the other hand this is the only way - mod_rewrite can provide (locally restricted) URL - manipulations to the average user.

    -
    3. -
- -

Don't forget these two points!

- -

Ruleset - Processing

- Now when mod_rewrite is triggered in these two API phases, it - reads the configured rulesets from its configuration - structure (which itself was either created on startup for - per-server context or during the directory walk of the Apache - kernel for per-directory context). Then the URL rewriting - engine is started with the contained ruleset (one or more - rules together with their conditions). The operation of the - URL rewriting engine itself is exactly the same for both - configuration contexts. Only the final result processing is - different. - -

The order of rules in the ruleset is important because the - rewriting engine processes them in a special (and not very - obvious) order. The rule is this: The rewriting engine loops - through the ruleset rule by rule (RewriteRule - directives) and when a particular rule matches it optionally - loops through existing corresponding conditions - (RewriteCond directives). For historical reasons - the conditions are given first, and so the control flow is a - little bit long-winded. See Figure 1 for more details.

- -
- - - - - - - - -
[Needs graphics capability to display]
Figure 1: The - control flow through the rewriting ruleset
-
- -

As you can see, first the URL is matched against the - Pattern of each rule. When it fails mod_rewrite - immediately stops processing this rule and continues with the - next rule. If the Pattern matches, mod_rewrite looks - for corresponding rule conditions. If none are present, it - just substitutes the URL with a new value which is - constructed from the string Substitution and goes on - with its rule-looping. But if conditions exist, it starts an - inner loop for processing them in the order that they are - listed. For conditions the logic is different: we don't match - a pattern against the current URL. Instead we first create a - string TestString by expanding variables, - back-references, map lookups, etc. and then we try - to match CondPattern against it. If the pattern - doesn't match, the complete set of conditions and the - corresponding rule fails. If the pattern matches, then the - next condition is processed until no more conditions are - available. If all conditions match, processing is continued - with the substitution of the URL with - Substitution.

- -

Quoting Special - Characters

- -

As of Apache 1.3.20, special characters in - TestString and Substitution strings can be - escaped (that is, treated as normal characters without their - usual special meaning) by prefixing them with a slosh ('\') - character. In other words, you can include an actual - dollar-sign character in a Substitution string by - using '\$'; this keeps mod_rewrite from trying - to treat it as a backreference.

- -

Regex - Back-Reference Availability

- One important thing here has to be remembered: Whenever you - use parentheses in Pattern or in one of the - CondPattern, back-references are internally created - which can be used with the strings $N and - %N (see below). These are available for creating - the strings Substitution and TestString. - Figure 2 shows to which locations the back-references are - transfered for expansion. - -
- - - - - - - - -
[Needs graphics capability to display]
Figure 2: The - back-reference flow through a rule
-
- -

We know this was a crash course on mod_rewrite's internal - processing. But you will benefit from this knowledge when - reading the following documentation of the available - directives.

-
- -
-

Configuration Directives

-
-
- -

RewriteEngine

- Syntax: RewriteEngine - on|off
- Default: RewriteEngine - off
- Context: server config, - virtual host, directory, .htaccess
- Override: FileInfo
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache - 1.2
- - -

The RewriteEngine directive enables or - disables the runtime rewriting engine. If it is set to - off this module does no runtime processing at - all. It does not even update the SCRIPT_URx - environment variables.

- -

Use this directive to disable the module instead of - commenting out all the RewriteRule - directives!

- -

Note that, by default, rewrite configurations are not - inherited. This means that you need to have a - RewriteEngine on directive for each virtual host - in which you wish to use it.

-
- -

RewriteOptions

- Syntax: RewriteOptions - Option
- Default: RewriteOptions - MaxRedirects=10
- Context: server config, - virtual host, directory, .htaccess
- Override: FileInfo
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache - 1.2; MaxRedirects is available in Apache 1.3.28 and - later
- - -

The RewriteOptions directive sets some - special options for the current per-server or per-directory - configuration. The Option strings can be one of the - following:

- -
-
inherit
-
This forces the current configuration to inherit the - 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 - .htaccess configuration are inherited.
- -
MaxRedirects=number
-
In order to prevent endless loops of internal redirects - issued by per-directory RewriteRules, - mod_rewrite aborts the request after reaching a - maximum number of such redirects and responds with an 500 Internal - Server Error. If you really need more internal redirects than 10 - per request, you may increase the default to the desired value.
-
-
- -

RewriteLog

- Syntax: RewriteLog - file-path
- Default: None
- Context: server config, - virtual host
- Override: Not - applicable
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache - 1.2
- - -

The RewriteLog directive sets the name of the - file to which the server logs any rewriting actions it - performs. If the name does not begin with a slash - ('/') then it is assumed to be relative to the - Server Root. The directive should occur only once - per server config.

- - - - - -
Note: To disable the logging of - rewriting actions it is not recommended to set - file-path to /dev/null, because - although the rewriting engine does not then output to a - logfile it still creates the logfile output internally. - This will slow down the server with no advantage - to the administrator! To disable logging either - remove or comment out the RewriteLog - directive or use RewriteLogLevel 0!
- - - - - -
Security: See the Apache Security - Tips document for details on why your security could - be compromised if the directory where logfiles are stored - is writable by anyone other than the user that starts the - server.
- -

Example:

- -
-
-RewriteLog "/usr/local/var/apache/logs/rewrite.log"
-
-
-
- -

RewriteLogLevel

- Syntax: RewriteLogLevel - Level
- Default: - RewriteLogLevel 0
- Context: server config, - virtual host
- Override: Not - applicable
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache - 1.2
- - -

The RewriteLogLevel directive sets the - verbosity level of the rewriting logfile. The default level 0 - means no logging, while 9 or more means that practically all - actions are logged.

- -

To disable the logging of rewriting actions simply set - Level to 0. This disables all rewrite action - logs.

- - - - - -
Notice: Using a high value for - Level will slow down your Apache server - dramatically! Use the rewriting logfile at a - Level greater than 2 only for debugging!
- -

Example:

- -
-
-RewriteLogLevel 3
-
-
-
- -

RewriteLock

- Syntax: RewriteLock - file-path
- Default: None
- Context: server config
- Override: Not - applicable
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache - 1.3
- - -

This directive sets the filename for a synchronization - lockfile which mod_rewrite needs to communicate with - RewriteMap programs. Set this lockfile - to a local path (not on a NFS-mounted device) when you want - to use a rewriting map-program. It is not required for other - types of rewriting maps.

-
- -

RewriteMap

- Syntax: RewriteMap - MapName MapType:MapSource
- Default: not used per - default
- Context: server config, - virtual host
- Override: Not - applicable
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache 1.2 - (partially), Apache 1.3
- - -

The RewriteMap directive defines a - Rewriting Map which can be used inside rule - substitution strings by the mapping-functions to - insert/substitute fields through a key lookup. The source of - this lookup can be of various types.

- -

The MapName is - the name of the map and will be used to specify a - mapping-function for the substitution strings of a rewriting - rule via one of the following constructs:

- -
- ${ MapName : - LookupKey }
- ${ MapName : - LookupKey | DefaultValue - } -
- 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 - substituted by DefaultValue or by the empty string - if no DefaultValue was specified. - -

The following combinations for MapType and - MapSource can be used:

- - - The RewriteMap directive can occur more than - once. For each mapping-function use one - RewriteMap directive to declare its rewriting - mapfile. While you cannot declare a map in - per-directory context it is of course possible to - use this map in per-directory context. - - - - - -
Note: For plain text and DBM format - files the looked-up keys are cached in-core until the - mtime of the mapfile changes or the server - does a restart. This way you can have map-functions in - rules which are used for every request. - This is no problem, because the external lookup only - happens once!
-
- -

RewriteBase

- Syntax: RewriteBase - URL-path
- Default: default is the - physical directory path
- Context: directory, - .htaccess
- Override: - FileInfo
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache - 1.2
- - -

The RewriteBase directive explicitly 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 - 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 - directly related to physical filename paths, so this - assumption will usually be wrong! There you have to - use the RewriteBase directive to specify the - correct URL-prefix.

- - - - - -
Notice: If your webserver's URLs are - not directly related to physical file - paths, you have to use RewriteBase in every - .htaccess files where you want to use - RewriteRule directives.
- -

Example:

- -
- Assume the following per-directory config file: - - - - - -
-
-#
-#  /abc/def/.htaccess -- per-dir config file for directory /abc/def
-#  Remember: /abc/def is the physical path of /xyz, i.e., the server
-#            has a 'Alias /xyz /abc/def' directive e.g.
-#
-
-RewriteEngine On
-
-#  let the server know that we were reached via /xyz and not
-#  via the physical path prefix /abc/def
-RewriteBase   /xyz
-
-#  now the rewriting rules
-RewriteRule   ^oldstuff\.html$  newstuff.html
-
-
- -

In the above example, a request to - /xyz/oldstuff.html gets correctly rewritten to - the physical file /abc/def/newstuff.html.

- - - - - -
- Note - For Apache - hackers:
- The following list gives detailed information about - the internal processing steps: -
-Request:
-  /xyz/oldstuff.html
-
-Internal Processing:
-  /xyz/oldstuff.html     -> /abc/def/oldstuff.html  (per-server Alias)
-  /abc/def/oldstuff.html -> /abc/def/newstuff.html  (per-dir    RewriteRule)
-  /abc/def/newstuff.html -> /xyz/newstuff.html      (per-dir    RewriteBase)
-  /xyz/newstuff.html     -> /abc/def/newstuff.html  (per-server Alias)
-
-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. -
-
-
- -

RewriteCond

- Syntax: RewriteCond - TestString CondPattern
- Default: None
- Context: server config, - virtual host, directory, .htaccess
- Override: - FileInfo
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache 1.2 - (partially), Apache 1.3
- - -

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.

- -

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

- - - -

Special Notes:

- -
    -
  1. The variables SCRIPT_FILENAME and REQUEST_FILENAME - contain the same value, i.e., 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 - REQUEST_URI (which contains the value of the - uri field of request_rec).
    2. - -
  2. There is the special format: - %{ENV:variable} where variable can be - any environment variable. This is looked-up via internal - Apache structures and (if not found there) via - getenv() from the Apache server process.
    3. - -
  3. 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 - the value of the HTTP header - ``Proxy-Connection:''.
    4. - -
  4. There is the special format - %{LA-U:variable} 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 - 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 - 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.
    5. - -
  5. 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-U above.
    6. -
- -

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

- -

Remember: CondPattern is a - standard Extended Regular Expression with some - additions:

- -
    -
  1. You can prefix the pattern string with a - '!' character (exclamation mark) to specify a - non-matching pattern.
    2. - -
  2. - There are some special variants of CondPatterns. - Instead of real regular expression strings you can also - 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.
      • - -
    • '>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.
      • - -
    • '=CondPattern' (is lexically - 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 - 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 - size)
      - Treats the TestString as a pathname and tests - if 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.
      • - -
    • '-F' (is existing file via - subrequest)
      - Checks if TestString is a valid file and - 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 - subrequest)
      - Checks if TestString is a valid URL and - 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: All of these tests can - also be prefixed by an exclamation mark ('!') to - negate their meaning.
    -
    3. -
- -

Additionally you can 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: - - - -

Example:

- -
- To rewrite the Homepage of a site according to the - ``User-Agent:'' header of the request, you can - use the following: - -
-
-RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
-RewriteRule  ^/$                 /homepage.max.html  [L]
-
-RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
-RewriteRule  ^/$                 /homepage.min.html  [L]
-
-RewriteRule  ^/$                 /homepage.std.html  [L]
-
-
- 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. -
-
- -

RewriteRule

- Syntax: RewriteRule - Pattern Substitution
- Default: None
- Context: server config, - virtual host, directory, .htaccess
- Override: - FileInfo
- Status: Extension
- Module: mod_rewrite.c
- Compatibility: Apache 1.2 - (partially), Apache 1.3
- - -

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.

- -

Pattern can - be (for Apache 1.1.x a System V8 and for Apache 1.2.x and - later a POSIX) regular - expression which gets applied to the current URL. Here - ``current'' means the value of the URL when this rule gets - applied. This may not be the originally requested URL, - because any number of rules may already - have matched and made alterations to it.

- -

Some hints about the syntax of regular expressions:

- - - - - -
-
-Text:
-  .           Any single character
-  [chars]     Character class: One  of chars
-  [^chars]    Character class: None of 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)
-
-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)
-
-Anchors:
-  ^           Start of line anchor
-  $           End   of line anchor
-
-Escaping:
-  \char       escape that particular char
-              (for instance to specify the chars ".[]()" etc.)
-
-
- -

For more information about regular expressions either have - a look at your local regex(3) manpage or its - src/regex/regex.3 copy in the Apache 1.3 - distribution. If you are interested in more detailed - information about regular expressions and their variants - (POSIX regex, Perl regex, etc.) have a look at the - following dedicated book on this topic:

- -
- Mastering Regular Expressions
- Jeffrey E.F. Friedl
- Nutshell Handbook Series
- O'Reilly & Associates, Inc. 1997
- ISBN 1-56592-257-3
-
- -

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: - ``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!
- -

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

- -
    -
  1. back-references $N to the RewriteRule - pattern
    2. - -
  2. back-references %N to the last matched - RewriteCond pattern
    3. - -
  3. server-variables as in rule condition test-strings - (%{VARNAME})
    4. - -
  4. mapping-function calls - (${mapname:key|default})
    5. -
- Back-references are $N - (N=0..9) identifiers 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. - -

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 - replaced by the Substitution and the - rewriting process goes on until there are no more rules - unless 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.

- -

One more note: You can even 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.

- - - - - -
Note: 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] -
- as the third argument to the RewriteRule - directive. Flags is a comma-separated list of the - following flags: - - - - - - - -
- Note: Never forget that - Pattern is applied to a complete URL in - per-server configuration files. But 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 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. - -

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!

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

Here are all possible substitution combinations and their - meanings:

- -

Inside per-server configuration - (httpd.conf)
- for request ``GET - /somepath/pathinfo'':
-

- - - - - -
-
-Given Rule                                      Resulting Substitution
-----------------------------------------------  ----------------------------------
-^/somepath(.*) otherpath$1                      not supported, because invalid!
-
-^/somepath(.*) otherpath$1  [R]                 not supported, because invalid!
-
-^/somepath(.*) otherpath$1  [P]                 not supported, because invalid!
-----------------------------------------------  ----------------------------------
-^/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(.*) 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://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
-                                                via external redirection
-
-^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
-                                                via external redirection
-                                                (the [R] flag is redundant)
-
-^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
-                                                via internal proxy
-
-
- -

Inside per-directory configuration for - /somepath
- (i.e., file .htaccess in dir - /physical/path/to/somepath containing - RewriteBase /somepath)
- for request ``GET - /somepath/localpath/pathinfo'':
-

- - - - - -
-
-Given Rule                                      Resulting Substitution
-----------------------------------------------  ----------------------------------
-^localpath(.*) otherpath$1                      /somepath/otherpath/pathinfo
-
-^localpath(.*) otherpath$1  [R]                 http://thishost/somepath/otherpath/pathinfo
-                                                via external redirection
-
-^localpath(.*) otherpath$1  [P]                 not supported, because silly!
-----------------------------------------------  ----------------------------------
-^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(.*) 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://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
-                                                via external redirection
-
-^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
-                                                via external redirection
-                                                (the [R] flag is redundant)
-
-^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
-
-
-
-
- -
-

Miscellaneous

-
-
- -

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/
-
-
-
- -

Practical - Solutions

- We also have an URL - Rewriting Guide available, which provides a collection of - practical solutions for URL-based problems. There you can - find real-life rulesets and additional information about - mod_rewrite. -
-
- -

Apache HTTP Server Version 1.3

- Index - Home - - - - - - -- cgit v1.2.3