Apache HTTP Server Version 2.5
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
+ 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.
Logging
trace2 only for debugging!
- LogLevel alert rewrite:trace3
-
LogLevel alert rewrite:trace3+
Those familiar with earlier versions of @@ -112,38 +114,36 @@ URLs on the fly
The RewriteBase directive explicitly
- sets the base URL-path (not filesystem directory path!) for per-directory rewrites
- that result in the substitution of a relative path.
- 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 (or the
- RewriteBase when set) back on to the substitution
- before handing it back to the core of the server as if it were the original
- URL.
This directive is required for per-directory rewrites whose context
- is a directory made available via the Alias
- directive, when the substitution uses a relative path.
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.
+ Most are documented here
+ or elsewhere in the Manual or in the CGI specification.
SERVER_NAME and SERVER_PORT depend on the values of
UseCanonicalName and
@@ -287,14 +295,6 @@ RewriteRule ^index\.html$ newsite.html
Those that are special to mod_rewrite include those below.
IS_SUBREQAPI_VERSIONTHE_REQUESTCONN_REMOTE_ADDRGET
- /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.mod_remoteip module).REQUEST_URIHTTPSQUERY_STRING.mod_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.
-
- HTTPSmod_ssl is loaded).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.
+
REQUEST_SCHEMEServerName.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 a
- ap_expr.
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:
@@ -401,7 +425,7 @@ RewriteRule ^index\.html$ newsite.html the value of the HTTP header ``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.
@@ -410,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
@@ -582,13 +607,18 @@ RewriteRule ^index\.html$ newsite.html
whether or not it exists, and is a regular file with size greater
than zero.'-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 a
+ CondPattern will be treated as an
ap_expr.
@@ -617,10 +647,9 @@ RewriteRule ^index\.html$ newsite.html to block unwanted hotlinking.
-
- RewriteCond expr "! %{HTTP_REFERER} -strmatch '*://%{HTTP_HOST}/*'"
- RewriteRule ^/images - [F]
-
RewriteCond expr "! %{HTTP_REFERER} -strmatch '*://%{HTTP_HOST}/*'"
+ RewriteRule ^/images - [F]
+
-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. + @@ -717,8 +736,8 @@ RewriteRule ^/$ /homepage.std.html [L] all. It does not even update theSCRIPT_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 @@ -740,8 +759,6 @@ RewriteRule ^/$ /homepage.std.html [L]
The RewriteMap directive defines a
Rewriting Map which can be used inside rule
@@ -774,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:
@@ -830,8 +845,6 @@ Apache HTTP Server 2.0.41 and laterMaxRedirects is no longer available in version 2.1 and
-laterThe RewriteOptions directive sets some
@@ -867,10 +880,39 @@ later
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
@@ -882,10 +924,49 @@ later
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 (%-decoded) - URL-path of the request; - subsequent patterns are applied to the output of the last matched - RewriteRule.
+ expression. On the first RewriteRule, it is matched against + the (%-decoded) URL-path (or + file-path, depending + on the context) of the request. Subsequent patterns are matched against the + output of the last matching RewriteRule.In VirtualHost context,
@@ -921,7 +1003,7 @@ later
In Directory and htaccess context,
the Pattern will initially be matched against the
- filesystem path, after removing the prefix that lead the server
+ 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).
RewriteBase
directive for more information regarding what prefix will be added back to
-relative substitions.
+relative substitutions.
%{REQUEST_URI} variable in
@@ -1000,7 +1082,7 @@ cannot use $N in the substitution string!
to be delivered to the client. Substitutions are only
treated as a file-system path when the rule is configured in
server (virtualhost) context and the first component of the
- path in the substitution is exists in the file-system
+ path in the substitution exists in the file-system
$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
@@ -1037,7 +1121,7 @@ cannot use $N in the substitution string!
- In addition to plain text, the Substition string can include
+In addition to plain text, the Substitution string can include
$N) to the RewriteRule
@@ -1065,7 +1149,7 @@ cannot use $N in the substitution string!
Rewrite rules are applied to the results of previous rewrite
rules, in the order in which they are defined
- in the config file. The URI or file path (see "What is matched?", above) is completely
+ 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 an
@@ -1092,128 +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 ... | |
| discardpath|DPI | Causes the PATH_INFO portion of the rewritten URI to be discarded. 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 ... | +|
| env|E=[!]VAR[:VAL] | Causes an environment variable VAR to be set (to the value VAL if provided). The form !VAR causes - the environment variable VAR to be unset.details ... | + 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 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 ... | |
| 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 @@ -1236,68 +1326,55 @@ directive.
/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 |