mod_rewrite - Apache HTTP Server Version 2.4
Modules | Directives | FAQ | Glossary | Sitemap | Report a bug Apache HTTP Server Version 2.4 Apache > HTTP Server > Documentation > Version 2.4 > Modules Apache Module mod_rewrite Available Languages: en | fr Description: Provides a rule-based rewriting engine to rewrite requested URLs on the fly Status: Extension Module Identifier: rewrite_module Source File: mod_rewrite.c Summary 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. It 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 URLs based on server variables (including HTTP headers, connection details, and timestamps), environment variables, or other request properties.
Rules can operate on the URL-path (including any trailing pathname information ) and can also alter the query string . A rewrite rule can be invoked in the server configuration files, or in per-directory context. The substitution string of a rewrite rule can include a query string, and a rule can lead to internal sub-processing, external request redirection, or internal proxy throughput. Further details, discussion, and examples, are provided in the detailed Guide to mod_rewrite .
Topics Logging Directives RewriteBase RewriteCond RewriteEngine RewriteMap RewriteOptions RewriteRule Bugfix checklist httpd changelog Known issues Report a bug See also Guide to mod_rewrite Logging ¶ mod_rewrite offers detailed logging of its actions at the trace1 to trace8 log levels. The log level can be set specifically for mod_rewrite using the LogLevel directive: Up to level debug , no actions are logged, while trace8 means that practically all actions are logged.
Using a high trace log level for mod_rewrite will slow down your Apache HTTP Server dramatically! Use a log level higher than trace2 only for debugging! Example LogLevel alert rewrite:trace3 RewriteLog Those familiar with earlier versions of mod_rewrite will no doubt be looking for the RewriteLog and RewriteLogLevel directives. Since the release of httpd 2.4, these directives have been replaced with the per-module logging configuration provided by LogLevel .
To get just the mod_rewrite -specific log messages, pipe the log file through grep: tail -f error_log|fgrep '[rewrite:' RewriteBase Directive ¶ Description: Sets the base URL for per-directory rewrites Syntax: RewriteBase URL-path Default: None Context: directory, .htaccess Override: FileInfo Status: Extension Module: mod_rewrite The RewriteBase directive specifies the URL prefix to be used for per-directory RewriteRule directives that substitute a relative path.
This directive is required when you use a relative path in a substitution in per-directory context unless any of the following conditions are true: The original request, and the substitution, are underneath the DocumentRoot (as opposed to reachable by other means, such as Alias ). The directory-path for which the RewriteRule applies, suffixed by the relative substitution, is also valid as a URL-path on the server (this is rare).
In Apache HTTP Server 2.4.16 and later, this directive may be omitted when the request is mapped via Alias or mod_userdir . RewriteCond Directive ¶ Description: Defines a condition under which rewriting will take place Syntax: RewriteCond TestString [!] CondPattern [ flags ] Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Extension Module: mod_rewrite The RewriteCond directive defines a rule condition.
One or more RewriteCond can precede a RewriteRule directive. The following rule is then only used if both the current state of the URI matches its pattern, and if these conditions are met. If the CondPattern is prefixed with a ! the condition is determined to be true only if the CondPattern does not match. TestString TestString is a string which can contain the following expanded constructs in addition to plain text: Backreferences $N — RewriteRule backreferences Backreferences of the form $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 — RewriteCond backreferences Backreferences of the form %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.
Backreferences are only defined if the pattern matches. Thus, if the pattern is prefixed with ! , no backreferences are ever defined. See How the Ruleset is Applied for more details on the order in which patterns are matched and backreferences populated. RewriteMap Expansions These are expansions of the form ${mapname:key|default} . See the documentation for RewriteMap for more details. Server and CGI Variables These are variables of the form %{ 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 in the Expressions doc , in the Environment Variables doc , or the CGI specification ( RFC 3875 ). SERVER_NAME and SERVER_PORT depend on the values of UseCanonicalName and UseCanonicalPhysicalPort respectively. 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.
Those that are special to mod_rewrite include those below. API_VERSION This is the version of the Apache httpd module API (the internal interface between server and module) in the current httpd build, as defined in include/ap_mmn.h. The module API version corresponds to the version of Apache httpd in use (in the release version of Apache httpd 1.3.14, for instance, it is 19990320:10), but is mainly of interest to module authors.
CONN_REMOTE_ADDR Since 2.4.8: The peer IP address of the connection (see the mod_remoteip module). HTTPS Will contain the text "on" if the connection is using SSL/TLS, or "off" otherwise. (This
The rest of this page is on the live site.