User Tools

Site Tools


apache:mod_rewrite

mod_rewrite

Logical rewrite process

Regular Expression Syntax

^ 	        Start of string
$ 	        End of string
. 	        Any single character
(a|b) 	        a or b
(...) 	        Group section
[abc] 	        Item in range (a or b or c)
[^abc] 	        Not in range (not a or b or c)
a? 	        Zero or one of a
a* 	        Zero or more of a
a+ 	        One or more of a
a{3} 	        Exactly 3 of a
a{3,} 	        3 or more of a
a{3,6} 	        Between 3 and 6 of a
!(pattern) 	"Not" prefix. Apply rule when URL does not match pattern

Flags

'chain|C' (chained with next rule)

This flag chains the current rule with the next rule (which itself can be chained with the following rule, and so on). This has the following effect: if a rule matches, then processing continues as usual - the flag has no effect. If the rule does not match, then all following chained rules are skipped. For instance, it can be used to remove the ``.www part, inside a per-directory rule set, when you let an external redirect happen (where the ``.www part should not occur!).

This sets a cookie in the client's browser. The cookie's name is specified by NAME and the value is VAL. The domain field is the domain of the cookie, such as '.apache.org', the optional lifetime is the lifetime of the cookie in minutes, and the optional path is the path of the cookie

'env|E=VAR:VAL' (set environment variable)

This forces an environment variable named VAR to be set to the value VAL, where VAL can contain regexp backreferences ($N and %N) which will be expanded. You can use this flag more than once, to set more than one variable. The variables can later be dereferenced in many situations, most commonly from within XSSI (via <!–#echo var=“VAR”–>) or CGI ($ENV{'VAR'}). You can also dereference the variable in a later RewriteCond pattern, using %{ENV:VAR}. Use this to strip information from URLs, while maintaining a record of that information.

'forbidden|F' (force URL to be forbidden)

This forces the current URL to be forbidden - it immediately sends back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with appropriate RewriteConds to conditionally block some URLs.

'gone|G' (force URL to be gone)

This forces the current URL to be gone - it immediately sends back a HTTP response of 410 (GONE). Use this flag to mark pages which no longer exist as gone.

'last|L' (last rule)

Stop the rewriting process here and don't apply any more rewrite rules. This corresponds to the Perl last command or the break command in C. Use this flag to prevent the currently rewritten URL from being rewritten further by following rules. For example, use it to rewrite the root-path URL ('/') to a real one, e.g., '/e/www/'.

'next|N' (next round)

Re-run the rewriting process (starting again with the first rewriting rule). This time, the URL to match is no longer the original URL, but rather the URL returned by the last rewriting rule. This corresponds to the Perl next command or the continue command in C. Use this flag to restart the rewriting process - to immediately go to the top of the loop. Be careful not to create an infinite loop!

'nocase|NC' (no case)

This makes the Pattern case-insensitive, ignoring difference between 'A-Z' and 'a-z' when Pattern is matched against the current URL.

'noescape|NE' (no URI escaping of output)

This flag prevents mod_rewrite from applying the usual URI escaping rules to the result of a rewrite. Ordinarily, special characters (such as '%', '$', ';', and so on) will be escaped into their hexcode equivalents ('%25', '%24', and '%3B', respectively); this flag prevents this from happening. This allows percent symbols to appear in the output, as in

RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]

which would turn '/foo/zed' into a safe request for '/bar?arg=P1=zed'.

'nosubreq|NS' ( not for internal sub-requests)

This flag forces the rewrite engine to skip a rewrite rule if the current request is an internal sub-request. For instance, sub-requests occur internally in Apache when mod_include tries to find out information about possible directory default files (index.xxx). On sub-requests it is not always useful, and can even cause errors, if the complete set of rules are applied. Use this flag to exclude some rules. To decide whether or not to use this rule: if you prefix URLs with CGI-scripts, to force them to be processed by the CGI-script, it's likely that you will run into problems (or significant overhead) on sub-requests. In these cases, use this flag.

'proxy|P' (force proxy)

This flag forces the substitution part to be internally sent as a proxy request and immediately (rewrite processing stops here) put through the proxy module. You must make sure that the substitution string is a valid URI (typically starting with http://hostname) which can be handled by the Apache proxy module. If not, you will get an error from the proxy module. Use this flag to achieve a more powerful implementation of the ProxyPass directive, to map remote content into the namespace of the local server. Note: mod_proxy must be enabled in order to use this flag.

'passthrough|PT' (pass through to next handler)

This flag forces the rewrite engine to set the uri field of the internal request_rec structure to the value of the filename field. This flag is just a hack to enable post-processing of the output of RewriteRule directives, using Alias, ScriptAlias, Redirect, and other directives from various URI-to-filename translators. For example, to rewrite /abc to /def using mod_rewrite, and then /def to /ghi using mod_alias:

RewriteRule ^/abc(.*) /def$1 [PT]

Alias /def /ghi If you omit the PT flag, mod_rewrite will rewrite uri=/abc/… to filename=/def/… as a full API-compliant URI-to-filename translator should do. Then mod_alias will try to do a URI-to-filename transition, which will fail. Note: You must use this flag if you want to mix directives from different modules which allow URL-to-filename translators. The typical example is the use of mod_alias and mod_rewrite.

'qsappend|QSA' (query string append)

This flag forces the rewrite engine to append a query string part of the substitution string to the existing string, instead of replacing it. Use this when you want to add more data to the query string via a rewrite rule.

'redirect|R [=code]' (force redirect)

Prefix Substitution with http://thishost[:thisport]/ (which makes the new URL a URI) to force a external redirection. If no code is given, a HTTP response of 302 (MOVED TEMPORARILY) will be returned. If you want to use other response codes in the range 300-400, simply specify the appropriate number or use one of the following symbolic names: temp (default), permanent, seeother. Use this for rules to canonicalize the URL and return it to the client - to translate ``/~ into ``/u/, or to always append a slash to /u/user, etc. Note: When you use this flag, make sure that the substitution field is a valid URL! Otherwise, you will be redirecting to an invalid location. Remember that this flag on its own will only prepend http://thishost[:thisport]/ to the URL, and rewriting will continue. Usually, you will want to stop rewriting at this point, and redirect immediately. To stop rewriting, you should add the 'L' flag.

'skip|S=num' (skip next rule(s))

This flag forces the rewriting engine to skip the next num rules in sequence, if the current rule matches. Use this to make pseudo if-then-else constructs: The last rule of the then-clause becomes skip=N, where N is the number of rules in the else-clause. (This is not the same as the 'chain|C' flag!)

'type|T=MIME-type' (force MIME type)

Force the MIME-type of the target file to be MIME-type. This can be used to set up the content-type based on some conditions. For example, the following snippet allows .php files to be displayed by mod_php if they are called with the .phps extension:

RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]

RewriteCond FLAGS

NC Case insensitive OR Allows a rule to apply if one of a series of conditions are true. Redirection Header Codes 301 Moved permanently 302 Moved temporarily 403 Forbidden 404 Not found 410 Gone

RewriteCond FLAGS

NC Case insensitive OR Allows a rule to apply if one of a series of conditions are true. Redirection Header Codes 301 Moved permanently 302 Moved temporarily 403 Forbidden 404 Not found 410 Gone

Server Variables

Format

	%{NAME_OF_VAR}

HTTP Headers

	HTTP_USER_AGENT
	HTTP_REFERER
	HTTP_COOKIE
	HTTP_FORWARDED
	HTTP_HOST
	HTTP_PROXY_CONNECTION
	HTTP_ACCEPT

Request

	REMOTE_ADDR
	REMOTE_HOST
	REMOTE_USER
	REMOTE_IDENT
	REQUEST_METHOD
	SCRIPT_FILENAME
	PATH_INFO
	QUERY_STRING
	AUTH_TYPE

Server

	DOCUMENT_ROOT
	SERVER_ADMIN
	SERVER_NAME
	SERVER_ADDR
	SERVER_PORT
	SERVER_PROTOCOL
	SERVER_SOFTWARE

Time

	TIME_YEAR
	TIME_MON
	TIME_DAY
	TIME_HOUR
	TIME_MIN
	TIME_SEC
	TIME_WDAY
	TIME

Special

	API_VERSION
	THE_REQUEST
	REQUEST_URI
	REQUEST_FILENAME
	IS_SUBREQ

Directives

	RewriteEngine
	RewriteOptions
	RewriteLog
	RewriteLogLevel
	RewriteLock
	RewriteMap
	RewriteBase
	RewriteCond
	RewriteRule

Examples

# Site has permanently moved to new domain
# domain.com to domain2.com
RewriteCond   %{HTTP_HOST}   ^www.domain.com$   [NC]
RewriteRule   ^(.*)$   http://www.domain2.com/$1   [R=301,L]
# Page has moved temporarily
# domain.com/page.html to domain.com/new_page.html
RewriteRule   ^page.html$   new_page.html   [R,NC,L]
# Nice looking URLs (no query string)
# domain.com/category-name-1/ to domain.com/categories.php?name=category-name-1
RewriteRule   ^([A-Za-z0-9-]+)/?$   categories.php?name=$1 [L]
# Nice looking URLs (no query string) with pagination
# domain.com/articles/title/5 to domain.com/article.php?name=title&page=5
RewriteRule   ^articles/([A-Za-z0-9-]+)/([0-9]+)/?$   article.php?name=$1&page=$2 [L]
# Block referrer spam
RewriteCond  %{HTTP_REFERRER}  (weight)  [NC,OR]
RewriteCond  %{HTTP_REFERRER}  (drugs)  [NC]
RewriteRule  .*  -  [F]

Direct Redirection

Redirect all traffic requests from www.example.com to www.example.com/special

<VirtualHost *:80>
  ServerName www.example.com
  RedirectMatch 302 ^/.* http://www.exaple.com/special
</VirtualHost>

Virtual hosts with rewrite rules

Everytime the site site is called by an URL different from www.example.com mod_rewrite changes the request to www.example.com.

Configuration of the virtual host:

<VirtualHost *:80>
  ServerName www.example.com
  ServerAlias example.com
  DocumentRoot /var/www/example.com/htdocs"
  CustomLog logs/example.com-access_log combined
  ErrorLog logs/example.com-error_log
 
  <IfModule mod_rewrite.c>
     RewriteEngine On
     RewriteCond %{HTTP_HOST}   !^www\.example\.com [NC]
     RewriteCond %{HTTP_HOST}   !^$
     RewriteRule ^/(.*)         http://www.example.com/$1 [L,R]
  </IfModule>
</VirtualHost>

Redirect all requests to SSL

<VirtualHost *:80 *:443>
# other directives
RewriteCond %{HTTPS} off
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]
# other directives
</VirtualHost>

Debugging

In order to simplify the debbuging of rewrite rule, you can activate logging:

RewriteLog "/myfolder/mylogfile.log" 
RewriteLogLevel 3
Don't activate Rewrite Logging on a productive system, it's hurting performance!
/srv/wiki.niwos.com/data/pages/apache/mod_rewrite.txt · Last modified: 2009/08/15 19:41 (external edit)