Apache HTTP Server Version 2.3
+ +Apache HTTP Server Version 2.5
Apache HTTP Server Version 2.3
+ +Apache HTTP Server Version 2.5
The mod_rewrite module uses a rule-based rewriting
- engine, based on a regular-expression parser, to rewrite requested URLs on
- the fly. By default, mod_rewrite maps a URL to a filesystem
+
The mod_rewrite module uses a rule-based rewriting
+ engine, based on a PCRE regular-expression parser, to rewrite requested URLs on
+ the fly. By default, mod_rewrite maps a URL to a filesystem
path. However, it can also be used to redirect one URL to another URL, or
to invoke an internal proxy fetch.
mod_rewrite provides a flexible and powerful way to
- manipulate URLs using an unlimited number of rules. Each rule can have an
+
mod_rewrite provides a flexible and powerful way to
+ manipulate URLs using an unlimited number of rules. Each rule can have an
unlimited number of attached rule conditions, to allow you to rewrite URL
- based on server variables, environment variables, HTTP headers, or time
+ based on server variables, environment variables, HTTP headers, or time
stamps.
mod_rewrite operates on the full URL path, including the
- path-info section. A rewrite rule can be invoked in
- httpd.conf or in .htaccess. The path generated
- by a rewrite rule can include a query string, or can lead to internal
- sub-processing, external request redirection, or internal proxy
+ path-info section. A rewrite rule can be invoked in
+ httpd.conf or in .htaccess. The path generated
+ by a rewrite rule can include a query string, or can lead to internal
+ sub-processing, external request redirection, or internal proxy
throughput.
Further details, discussion, and examples, are provided in the @@ -63,7 +66,7 @@ URLs on the fly
Logging
trace2 only for debugging!
- LogLevel alert rewrite:trace3
-
LogLevel alert rewrite:trace3+
Those familiar with earlier versions of @@ -112,34 +114,36 @@ URLs on the fly
The RewriteBase directive explicitly
- sets the base URL-path (not filesystem directory path!) for per-directory rewrites.
- When you use a RewriteRule
- in a .htaccess file, mod_rewrite strips off
- the local directory prefix before processing, then rewrites the rest of
- the URL. When the rewrite is completed, mod_rewrite
- automatically adds the local directory prefix back on to the path.
This directive is required for per-directory rewrites whose context
- is a directory made available via the Alias
- directive.
If your URL path does not exist verbatim on the filesystem,
- or isn't directly under your DocumentRoot,
- you must use RewriteBase in every
- .htaccess file where you want to use RewriteRule directives.
The example below demonstrates how to map
- http://example.com/myapp/index.html to
- /home/www/example/newsite.html, in a .htaccess file. This
- assumes that the content available at
- http://example.com/ is on disk at /home/www/example/
-RewriteEngine On -# The URL-path used to get to this context, not the filesystem path -RewriteBase /myapp/ -RewriteRule ^index\.html$ newsite.html -
The RewriteBase directive specifies the
+ URL prefix to be used for per-directory (htaccess)
+ RewriteRule directives that substitute a relative
+ path.
This directive is required when you use a relative path + in a substitution in per-directory (htaccess) context unless either + of the following conditions are true:
+DocumentRoot
+ (as opposed to reachable by other means, such as
+ Alias).RewriteRule, suffixed by the relative
+ substitution is also valid as a URL path on the server
+ (this is rare). In the example below, RewriteBase is necessary
+ to avoid rewriting to http://example.com/opt/myapp-1.2.3/welcome.html
+ since the resource was not relative to the document root. This
+ misconfiguration would normally cause the server to look for an "opt"
+ directory under the document root.
DocumentRoot /var/www/example.com +Alias /myapp /opt/myapp-1.2.3 +<Directory /opt/myapp-1.2.3> + RewriteEngine On + RewriteBase /myapp/ + RewriteRule ^index\.html$ welcome.html +</Directory>
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 those below.
- IS_SUBREQSERVER_NAME and SERVER_PORT depend on the values of
+ UseCanonicalName and
+ UseCanonicalPhysicalPort
+ respectively.
Those that are special to mod_rewrite include those below.
+API_VERSIONTHE_REQUESTCONN_REMOTE_ADDRGET
- /index.html HTTP/1.1"). This does not
- include any additional headers sent by the
- browser.mod_remoteip module).REQUEST_URIHTTPSmod_ssl is loaded).IS_SUBREQREMOTE_ADDRmod_remoteip module).REQUEST_FILENAMEREQUEST_FILENAME is referenced. Otherwise,
- such as when used in virtual host context, the same
- value as REQUEST_URI.REQUEST_FILENAME is referenced. Otherwise,
+ such as when used in virtual host context, the same
+ value as REQUEST_URI. Depending on the value of
+ AcceptPathInfo, the
+ server may have only used some leading components of the
+ REQUEST_URI to map the request to a file.
+
- HTTPSREQUEST_SCHEMEmod_ssl is loaded).ServerName.REQUEST_URIQUERY_STRING.THE_REQUESTGET
+ /index.html HTTP/1.1"). This does not
+ include any additional headers sent by the
+ browser. This value has not been unescaped
+ (decoded), unlike most other variables below.If the TestString has the special value expr,
+ the CondPattern will be treated as an
+ ap_expr. HTTP headers referenced in the
+ expression will be added to the Vary header if the novary
+ flag is not given.
Other things you should be aware of:
Proxy-Connection:''.
If a HTTP header is used in a condition this header is added to - the Vary header of the response in case the condition evaluates to + the Vary header of the response in case the condition evaluates to true for the request. It is not added if the condition evaluates to false for the request. Adding the HTTP header to the Vary header of the response is needed for proper caching.
@@ -387,7 +434,8 @@ RewriteRule ^index\.html$ newsite.html so that certain conditions might not be evaluated at all.%{LA-U:variable} can be used 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. This can be used to access
variable for rewriting which is not available at the current
@@ -489,7 +537,7 @@ RewriteRule ^index\.html$ newsite.html
numerically compared to the CondPattern. True if
the TestString is numerically greater than or equal
to the CondPattern.'-U' (is existing URL, via
subrequest)
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 do the check, so use it with care -
- it can impact your server's performance!
This flag only returns information about things + like access control, authentication, and authorization. This flag + does not return information about the status code the + configured handler (static file, CGI, proxy, etc.) would have + returned.
If the TestString has the special value expr, the
+ CondPattern will be treated as an
+ ap_expr.
+ In the below example, -strmatch is used to
+ compare the REFERER against the site hostname,
+ to block unwanted hotlinking.
+
RewriteCond expr "! %{HTTP_REFERER} -strmatch '*://%{HTTP_HOST}/*'"
+ RewriteRule ^/images - [F]
+
+ [flags]
@@ -606,12 +675,11 @@ RewriteRule ^index\.html$ newsite.html
Use this to combine rule conditions with a local OR
instead of the implicit AND. Typical example:
-
-RewriteCond %{REMOTE_HOST} ^host1 [OR]
+RewriteCond %{REMOTE_HOST} ^host1 [OR]
RewriteCond %{REMOTE_HOST} ^host2 [OR]
RewriteCond %{REMOTE_HOST} ^host3
-RewriteRule ...some special stuff for any of these hosts...
-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} (iPhone|Blackberry|Android)
+RewriteRule ^/$ /homepage.mobile.html [L]
-RewriteCond %{HTTP_USER_AGENT} ^Lynx
-RewriteRule ^/$ /homepage.min.html [L]
+RewriteRule ^/$ /homepage.std.html [L]
-RewriteRule ^/$ /homepage.std.html [L]
-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.
+ as a mobile browser (note that the example is incomplete, as + there are many other mobile platforms), the mobile version of + the homepage is served. Otherwise, the standard page is served. +SCRIPT_URx
environment variables.
- Use this directive to disable the module instead of
- commenting out all the RewriteRule directives!
Use this directive to disable rules in a particular context,
+ rather than commenting out all the RewriteRule directives.
Note that rewrite configurations are not inherited by virtual hosts. This means that you need to have a @@ -700,8 +759,6 @@ RewriteRule ^/$ /homepage.std.html [L]
The RewriteMap directive defines a
Rewriting Map which can be used inside rule
@@ -734,16 +791,14 @@ Apache HTTP Server 2.0.41 and later
For example, you might define a
RewriteMap as:
- RewriteMap examplemap txt:/path/to/file/map.txt
-
RewriteMap examplemap txt:/path/to/file/map.txt+
You would then be able to use this map in a
RewriteRule as follows:
- RewriteRule ^/ex/(.*) ${examplemap:$1}
-
RewriteRule ^/ex/(.*) ${examplemap:$1}
+
The following combinations for MapType and MapSource can be used:
@@ -760,7 +815,7 @@ Apache HTTP Server 2.0.41 and laterhttxt2dbm
+ the httxt2dbm
utility. (Details ...)MaxRedirects is no longer available in version 2.1 and
-laterThe RewriteOptions directive sets some
@@ -802,7 +855,7 @@ later
InheritThis 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 @@ -817,7 +870,7 @@ later of local rules - has no influence on this behavior. If local rules forced the rewriting to stop, the inherited rules won't be processed.
- +InheritBefore Like Inherit above, but the rules from the parent scope
- are applied before rules specified in the child scope.
+ are applied before rules specified in the child scope.
Available in Apache HTTP Server 2.3.10 and later.
InheritDownIf this option is enabled, all child configurations will inherit
+ the configuration of the current configuration. It is equivalent to
+ specifying RewriteOptions Inherit in all child
+ configurations. See the Inherit option for more details
+ on how the parent-child relationships are handled.
+ Available in Apache HTTP Server 2.4.8 and later.
InheritDownBeforeLike InheritDown above, but the rules from the current
+ scope are applied before rules specified in any child's
+ scope.
+ Available in Apache HTTP Server 2.4.8 and later.
IgnoreInheritThis option forces the current and child configurations to ignore
+ all rules that would be inherited from a parent specifying
+ InheritDown or InheritDownBefore.
+ Available in Apache HTTP Server 2.4.8 and later.
AllowNoSlashBy default, mod_rewrite will ignore URLs that map to a
+ directory on disk but lack a trailing slash, in the expectation that
+ the mod_dir module will issue the client with a redirect to
+ the canonical URL with a trailing slash.
When the DirectorySlash directive
+ is set to off, the AllowNoSlash option can be enabled to ensure
+ that rewrite rules are no longer ignored. This option makes it possible to
+ apply rewrite rules within .htaccess files that match the directory without
+ a trailing slash, if so desired.
+ Available in Apache HTTP Server 2.4.0 and later.
AllowAnyURIWhen RewriteRule
+ is used in VirtualHost or server context with
+ version 2.2.22 or later of httpd, mod_rewrite
+ will only process the rewrite rules if the request URI is a URL-path. This avoids
+ some security issues where particular rules could allow
+ "surprising" pattern expansions (see CVE-2011-3368
+ and CVE-2011-4317).
+ To lift the restriction on matching a URL-path, the
+ AllowAnyURI option can be enabled, and
+ mod_rewrite will apply the rule set to any
+ request URI string, regardless of whether that string matches
+ the URL-path grammar required by the HTTP specification.
+ Available in Apache HTTP Server 2.4.3 and later.
Enabling this option will make the server vulnerable to
+ security issues if used with rewrite rules which are not
+ carefully authored. It is strongly recommended
+ that this option is not used. In particular, beware of input
+ strings containing the '@' character which could
+ change the interpretation of the transformed URI, as per the
+ above CVE names.
MergeBaseWith this option, the value of RewriteBase is copied from where it's explicitly defined
+ into any sub-directory or sub-location that doesn't define its own
+ RewriteBase. This was the
+ default behavior in 2.4.0 through 2.4.3, and the flag to restore it is
+ available Apache HTTP Server 2.4.4 and later.
Pattern is a perl compatible regular - expression. On the first RewriteRule it is applied to the (%-encoded) - URL-path of the request; - subsequent patterns are applied to the output of the last matched - RewriteRule.
- -The Pattern will initially be matched against the part of the - URL after the hostname and port, and before the query string.
- -When the RewriteRule appears in per-directory (htaccess) context, the
- Pattern is matched against what remains of the URL after removing
- the prefix that lead Apache httpd to the current rules (see the
- RewriteBase). The removed prefix
- always ends with a slash, meaning the matching occurs against a string which
- never has a leading slash. A Pattern with ^/ never
- matches in per-directory context.
In VirtualHost context,
+ The Pattern will initially be matched against the part of the
+ URL after the hostname and port, and before the query string (e.g. "/app1/index.html").
In Directory and htaccess context,
+ the Pattern will initially be matched against the
+ filesystem path, after removing the prefix that led the server
+ to the current RewriteRule (e.g. "app1/index.html"
+ or "index.html" depending on where the directives are defined).
If you wish to match against the hostname, port, or query string, use a
RewriteCond with the
%{HTTP_HOST}, %{SERVER_PORT}, or
- %{QUERY_STRING} variables respectively. If you wish to
- match against the full URL-path in a per-directory (htaccess) RewriteRule,
- use the %{REQUEST_URI} variable.
%{QUERY_STRING} variables respectively.
+<Directory> sections, with some additional
+complexity.RewriteEngine On" 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..htaccess files the
+per-directory prefix (which always is the same for a specific
+directory) is automatically removed for the RewriteRule pattern matching
+and automatically added after any relative (not starting with a
+slash or protocol name) substitution encounters the end of a rule set.
+See the RewriteBase
+directive for more information regarding what prefix will be added back to
+relative substitutions.%{REQUEST_URI} variable in
+a RewriteCond.^/ never
+matches in per-directory context.<Location> and <Files> sections, this
+should never be necessary and is unsupported.For some hints on regular
@@ -911,7 +1079,10 @@ cannot use In addition to plain text, the Substition string can include In addition to plain text, the Substitution string can include$N in the substitution string!
$N in the substitution string!
you specify a Substitution string of
/www/file.html, then this will be treated as a
URL-path unless a directory named www
- exists at the root or your file-system, in which case it will
+ exists at the root or your file-system (or, in the case of
+ using rewrites in a .htaccess file, relative to
+ your document root), in which case it will
be treated as a file-system path. If you wish other
URL-mapping directives (such as Alias) to be applied to the
resulting URL-path, use the [PT] flag as
@@ -948,7 +1121,7 @@ cannot use $N in the substitution string!
-
$N) to the RewriteRule
@@ -974,14 +1147,16 @@ cannot use $N in the substitution string!
RewriteMap directive and are explained there.
These three types of variables are expanded in the order above.
As already mentioned, all rewrite rules are
- applied to the Substitution (in the order in which
- they are defined
- in the config file). The URL is completely
+ Rewrite rules are applied to the results of previous rewrite
+ rules, in the order in which they are defined
+ in the config file. The URL-path or file-system path (see "What is matched?", above) is completely
replaced by the Substitution and the
rewriting process continues until all rules have been applied,
- or it is explicitly terminated by a
- L flag.L flag,
+ or other flag which implies immediate termination, such as
+ END or
+ F.
By default, the query string is passed through unchanged. You
@@ -1001,127 +1176,134 @@ cannot use $N in the substitution string!
brackets, of any of the flags in the following table. More
details, and examples, for each flag, are available in the Rewrite Flags document.
| Flag and syntax | +
|---|
| Flag and syntax | Function | |
|---|---|---|
| B | -Escape non-alphanumeric characters before applying - the transformation. details ... | +Escape non-alphanumeric characters in backreferences before + applying the transformation. details ... | +
| backrefnoplus|BNP | +If backreferences are being escaped, spaces should be escaped to + %20 instead of +. Useful when the backreference will be used in the + path component rather than the query string.details ... | |
| chain|C | Rule is chained to the following rule. If the rule fails, the rule(s) chained to it will be skipped. details ... | |
| cookie|CO=NAME:VAL | -Sets a cookie in the client browser. Full syntax is: - CO=NAME:VAL[:domain[:lifetime[:path[:secure[:httponly]]]]] details ... + | Sets a cookie in the client browser. Full syntax is: + CO=NAME:VAL:domain[:lifetime[:path[:secure[:httponly]]]] details ... |
| discardpathinfo|DPI | +||
| discardpath|DPI | Causes the PATH_INFO portion of the rewritten URI to be - discarded. details + discarded. details ... | |
| env|E=VAR[:VAL] | +||
| END | +Stop the rewriting process immediately and don't apply any + more rules. Also prevents further execution of rewrite rules + in per-directory and .htaccess context. (Available in 2.3.9 and later) + details ... | +|
| env|E=[!]VAR[:VAL] | Causes an environment variable VAR to be set (to the - value VAL if provided). details ... | + value VAL if provided). The form !VAR causes + the environment variable VAR to be unset. + details ...|
| forbidden|F | Returns a 403 FORBIDDEN response to the client browser. details ... | |
| gone|G | Returns a 410 GONE response to the client browser. details ... | |
| Handler|H=Content-handler | Causes the resulting URI to be sent to the specified Content-handler for processing. details ... | |
| last|L | Stop the rewriting process immediately and don't apply any more rules. Especially note caveats for per-directory and .htaccess context (see also the END flag). details ... | |
| next|N | Re-run the rewriting process, starting again with the first rule, using the result of the ruleset so far as a starting point. details ... | |
| nocase|NC | -Makes the pattern pattern comparison case-insensitive. + | Makes the pattern comparison case-insensitive. details ... |
| noescape|NE | Prevent mod_rewrite from applying hexcode escaping of special characters in the result of the rewrite. details ... | |
| nosubreq|NS | Causes a rule to be skipped if the current request is an internal sub-request. details ... | |
| proxy|P | Force the substitution URL to be internally sent as a proxy request. details ... | |
| passthrough|PT | Forces the resulting URI to be passed back to the URL
mapping engine for processing of other URI-to-filename
translators, such as Alias or
Redirect. details ... |
|
| qsappend|QSA | -Appends any query string created in the rewrite target to - any query string that was in the original request URL. details ... | +Appends any query string from the original request URL to + any query string created in the rewrite target.details ... |
| qsdiscard|QSD | Discard any query string attached to the incoming URI. details ... | |
| redirect|R[=code] | Forces an external redirect, optionally with the specified HTTP status code. details ... | |
| END | -Stop the rewriting process immediately and don't apply any - more rules. Also prevents further execution of rewrite rules - in per-directory and .htaccess context. (Available in 2.3.9 and later) - details ... | -|
| skip|S=num | Tells the rewriting engine to skip the next num rules if the current rule matches. details ... | |
| tyle|T=MIME-type | +||
| type|T=MIME-type | Force the MIME-type of the target file to be the specified type. details ... |
When the substitution string begins with a string
@@ -1134,39 +1316,6 @@ flag is used on the RewriteRule
The rewrite engine may be used in .htaccess files. To enable the
-rewrite engine for these files you need to set
-"RewriteEngine On" 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.
When using the rewrite engine in .htaccess 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; 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 using flag P) is forced. See the
-RewriteBase directive for
-more information.
The rewrite engine may also be used in <Directory> sections with the same
-prefix-matching rules as would be applied to .htaccess
-files. It is usually simpler, however, to avoid the prefix substitution
-complication by putting the rewrite rules in the main server or
-virtual host context, rather than in a <Directory> section.
Although rewrite rules are syntactically permitted in <Location> and <Files> sections, this
-should never be necessary and is unsupported.
Here are all possible substitution combinations and their meanings:
@@ -1177,68 +1326,55 @@ should never be necessary and is unsupported. /somepath/pathinfo'':| Given Rule | Resulting Substitution | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ^/somepath(.*) otherpath$1 | invalid, not supported | ||||||||||||||||||||||||
| ^/somepath(.*) otherpath$1 [R] | invalid, not supported | ||||||||||||||||||||||||
| ^/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] | 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] | doesn't make sense, not supported | ||||||||||||||||||||||||
| ^/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 |
| 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] | 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] | 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] | doesn't make sense, not supported |
| ^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 |