The
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 detailed mod_rewrite documentation.
trace1
to trace8
log levels. The
log level can be set specifically for debug
, no actions are logged, while trace8
means that practically all actions are logged.
trace2
only for debugging!
Those familiar with earlier versions of
RewriteLog
and RewriteLogLevel
directives. This functionality has been completely replaced by the
new per-module logging configuration mentioned above.
To get just the
The off
this module does no runtime processing at
all. It does not even update the SCRIPT_URx
environment variables.
Use this directive to disable rules in a particular context,
rather than commenting out all the
Note that rewrite configurations are not
inherited by virtual hosts. This means that you need to have a
RewriteEngine on
directive for each virtual host
in which you wish to use rewrite rules.
prg
are not started during server initialization if they're defined in a
context that does not have on
The
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 or
InheritBefore
Like Inherit
above, but the rules from the parent scope
are applied before rules specified in the child scope.
Available in Apache HTTP Server 2.3.10 and later.
InheritDown
If 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.
InheritDownBefore
Like 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.
IgnoreInherit
This 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.
AllowNoSlash
By default,
When 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.
AllowAnyURI
When VirtualHost
or server context with
version 2.2.22 or later of httpd, AllowAnyURI
option can be enabled, and
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.
MergeBase
With this option, the value of
IgnoreContextInfo
When a relative substitution is made
in directory (htaccess) context and
LegacyPrefixDocRoot
Prior to 2.4.26, if a substitution was an absolute URL that matched
the current virtual host, the URL might first be reduced to a URL-path
and then later reduced to a local path. Since the URL can be reduced
to a local path, the path should be prefixed with the document root.
This prevents a file such as /tmp/myfile from being accessed when a
request is made to http://host/file/myfile with the following
This option allows the old behavior to be used where the document root is not prefixed to a local path that was reduced from a URL. Available in 2.4.26 and later.
LongURLOptimization
This option reduces memory usage of long, unoptimized rule sets that repeatedly expand long values in RewriteCond and RewriteRule variables. Available in 2.5 and later.
The
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. Empty values behave as if the key was absent, therefore it is not possible to distinguish between empty-valued keys and absent keys.
For example, you might define a
You would then be able to use this map in a
The meaning of the MapTypeOptions argument depends on particular MapType. See the Using RewriteMap for more information.
The following combinations for MapType and MapSource can be used:
httxt2dbm
utility. (Details ...)RewriteMap
: toupper, tolower, escape or
unescape. (Details ...)Further details, and numerous examples, may be found in the RewriteMap HowTo
The
This directive is required when you use a relative path in a substitution in per-directory (htaccess) context unless any of the following conditions are true:
In the example below,
The
TestString is a string which can contain the following expanded constructs in addition to plain text:
$N
(0 <= N <= 9). $1 to $9 provide access to the grouped
parts (in parentheses) of the pattern, from the
RewriteRule
which is subject to the current
set of RewriteCond
conditions. $0 provides
access to the whole string matched by that pattern.
%N
(0 <= N <= 9). %1 to %9 provide access to the grouped
parts (again, in parentheses) of the pattern, from the last matched
RewriteCond
in the current set
of conditions. %0 provides access to the whole string matched by
that pattern.
${mapname:key|default}
.
See the documentation for
RewriteMap for more details.
%{
NAME_OF_VARIABLE
}
where NAME_OF_VARIABLE can be a string taken
from the following list:
HTTP headers: | connection & request: | |
---|---|---|
HTTP_ACCEPT HTTP_COOKIE HTTP_FORWARDED HTTP_HOST HTTP_PROXY_CONNECTION HTTP_REFERER HTTP_USER_AGENT |
AUTH_TYPE CONN_REMOTE_ADDR CONTEXT_PREFIX CONTEXT_DOCUMENT_ROOT IPV6 PATH_INFO QUERY_STRING REMOTE_ADDR REMOTE_HOST REMOTE_IDENT REMOTE_PORT REMOTE_USER REQUEST_METHOD SCRIPT_FILENAME |
|
server internals: | date and time: | specials: |
DOCUMENT_ROOT SCRIPT_GROUP SCRIPT_USER SERVER_ADDR SERVER_ADMIN SERVER_NAME SERVER_PORT SERVER_PROTOCOL SERVER_SOFTWARE |
TIME_YEAR TIME_MON TIME_DAY TIME_HOUR TIME_MIN TIME_SEC TIME_WDAY TIME |
API_VERSION CONN_REMOTE_ADDR HTTPS IS_SUBREQ REMOTE_ADDR REQUEST_FILENAME REQUEST_SCHEME REQUEST_URI THE_REQUEST |
These variables all
correspond to the similarly named HTTP
MIME-headers, C variables of the Apache HTTP Server or
struct tm
fields of the Unix system.
Most are documented here
or elsewhere in the Manual or in the CGI specification.
SERVER_NAME and SERVER_PORT depend on the values of
Those that are special to
API_VERSION
CONN_REMOTE_ADDR
HTTPS
IS_SUBREQ
REMOTE_ADDR
REQUEST_FILENAME
REQUEST_FILENAME
is referenced. Otherwise,
such as when used in virtual host context, the same
value as REQUEST_URI
. Depending on the value of
REQUEST_URI
to map the request to a file.
REQUEST_SCHEME
REQUEST_URI
QUERY_STRING
.THE_REQUEST
GET
/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:
The variables SCRIPT_FILENAME and REQUEST_FILENAME
contain the same value - the value of the
filename
field of the internal
request_rec
structure of the Apache HTTP Server.
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
).
If a substitution occurred and the rewriting continues, the value of both variables will be updated accordingly.
If used in per-server context (i.e., before the
request is mapped to the filesystem) SCRIPT_FILENAME and
REQUEST_FILENAME cannot contain the full local filesystem
path since the path is unknown at this stage of processing.
Both variables will initially contain the value of REQUEST_URI
in that case. In order to obtain the full local filesystem
path of the request in per-server context, use an URL-based
look-ahead %{LA-U:REQUEST_FILENAME}
to determine
the final value of REQUEST_FILENAME.
%{ENV:variable}
, where variable can be
any environment variable, is also available.
This is looked-up via internal
Apache httpd structures and (if not found there) via
getenv()
from the Apache httpd server process.%{SSL:variable}
, where variable is the
name of an SSL environment
variable, can be used whether or not
%{SSL:SSL_CIPHER_USEKEYSIZE}
may expand to
128
. These variables are available even without
setting the StdEnvVars
option of the
%{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:
''.
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 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.
It has to be kept in mind that conditions follow a short circuit
logic in the case of the 'ornext|OR
' flag
so that certain conditions might not be evaluated at all.
%{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
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 must
use %{LA-U:REMOTE_USER}
- this
variable is set by the authorization phases, which come
after the URL translation phase (during which
On the other hand, because .htaccess
file) via
the Fixup phase of the API and because the authorization
phases come before this phase, you just can use
%{REMOTE_USER}
in that context.
%{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, a regular expression which is applied to the current instance of the TestString. TestString is first evaluated, before being matched against CondPattern.
CondPattern is usually a perl compatible regular expression, but there is additional syntax available to perform other useful tests against the Teststring:
!
' character (exclamation mark) to negate the result
of the condition, no matter what kind of CondPattern is used.
""
(two quotation marks) this
compares TestString to the empty string.!-eq
.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.
You can also set special flags for CondPattern by appending
[
flags]
as the third argument to the
nocase|NC
'
(no case)ornext|OR
'
(or next condition)novary|NV
'
(no vary)Example:
To rewrite the Homepage of a site according to the
``User-Agent:
'' header of the request, you can
use the following:
Explanation: If you use a browser which identifies itself 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.
The
Pattern is
a perl compatible regular
expression. What this pattern is compared against varies depending
on where the
In
In per-directory context (
The directory path where the rule is defined is stripped from the currently mapped filesystem path before comparison (up to and including a trailing slash). The net result of this per-directory prefix stripping is that rules in this context only match against the portion of the currently mapped filesystem path "below" where the rule is defined.
Directives such as
If you wish to match against the hostname, port, or query string, use a
%{HTTP_HOST}
, %{SERVER_PORT}
, or
%{QUERY_STRING}
variables respectively.
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.%{REQUEST_URI}
variable in
a ^/
never
matches in per-directory context.For some hints on
In !
') 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.
$N
in the substitution string!
The Substitution of a rewrite rule is the string that replaces the original URL-path that was matched by Pattern. The Substitution may be a:
/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 (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 [PT]
flag as
described below.[R]
flag below.-
(dash)In addition to plain text, the Substitution string can include
$N
) to the RewriteRule
pattern%N
) to the last matched
RewriteCond pattern%{VARNAME}
)${mapname:key|default}
)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
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 an
L
flag,
or other flag which implies immediate termination, such as
END
or
F
.
By default, the query string is passed through unchanged. 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.
Additionally you can set special actions to be performed by
appending [
flags]
as the third argument to the
Flag and syntax | Function |
---|---|
B | 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 ... |
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 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 ... |
qslast|QSL | Interpret the last (right-most) question mark as the query string delimiter, instead of the first (left-most) as normally used. Available in 2.4.19 and later. details ... |
redirect|R[=code] | Forces an external redirect, optionally with the specified HTTP status code. 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 |
When the substitution string begins with a string
resembling "/~user" (via explicit text or backreferences),
This expansion does not occur when the PT
flag is used on the
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 | 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 |
Inside per-directory configuration for
/somepath
(/physical/path/to/somepath/.htaccess
, with
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] | 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 |