<!-- TODO: Add discussion here of why we have !^$ in there. -->
-<example>
-RewriteCond %{HTTP_REFERER} <strong>!^$</strong><br />
-RewriteCond %{HTTP_REFERER} !www.example.com [NC]<br />
+<highlight language="config">
+RewriteCond %{HTTP_REFERER} <strong>!^$</strong>
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]
RewriteRule <strong>\.(gif|jpg|png)$</strong> - [F,NC]
-</example>
+</highlight>
<p>In this second example, instead of failing the request, we display
an alternate image instead.</p>
-<example>
-RewriteCond %{HTTP_REFERER} <strong>!^$</strong><br />
-RewriteCond %{HTTP_REFERER} !www.example.com [NC]<br />
+<highlight language="config">
+RewriteCond %{HTTP_REFERER} <strong>!^$</strong>
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]
RewriteRule <strong>\.(gif|jpg|png)$</strong> /images/go-away.png [R,NC]
-</example>
+</highlight>
<p>In the third example, we redirect the request to an image on some
other site.</p>
-<example>
-RewriteCond %{HTTP_REFERER} <strong>!^$</strong><br />
-RewriteCond %{HTTP_REFERER} !www.example.com [NC]<br />
+<highlight language="config">
+RewriteCond %{HTTP_REFERER} <strong>!^$</strong>
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]
RewriteRule <strong>\.(gif|jpg|png)$</strong> http://other.example.com/image.gif [R,NC]
-</example>
+</highlight>
<p>Of these techniques, the last two tend to be the most effective
in getting people to stop hotlinking your images, because they will
than redirecting that request elsewhere, this can be
accomplished without the use of mod_rewrite:</p>
- <example>
- SetEnvIf Referer example\.com localreferer<br />
- <FilesMatch \.(jpg|png|gif)$><br />
- Order deny,allow<br />
- Deny from all<br />
- Allow from env=localreferer<br />
- </FilesMatch>
- </example>
+ <highlight language="config">
+SetEnvIf Referer example\.com localreferer
+<FilesMatch \.(jpg|png|gif)$>
+ Order deny,allow
+ Deny from all
+ Allow from env=localreferer
+</FilesMatch>
+ </highlight>
</dd>
</dl>
range, if you are trying to block that user agent only from the
particular source.</p>
-<example>
-RewriteCond %{HTTP_USER_AGENT} ^<strong>NameOfBadRobot</strong><br />
-RewriteCond %{REMOTE_ADDR} =<strong>123\.45\.67\.[8-9]</strong><br />
+<highlight language="config">
+RewriteCond %{HTTP_USER_AGENT} ^<strong>NameOfBadRobot</strong>
+RewriteCond %{REMOTE_ADDR} =<strong>123\.45\.67\.[8-9]</strong>
RewriteRule ^<strong>/secret/files/</strong> - [<strong>F</strong>]
-</example>
+</highlight>
</dd>
<dt>Discussion:</dt>
Rather than using mod_rewrite for this, you can accomplish the
same end using alternate means, as illustrated here:
</p>
- <example>
- SetEnvIfNoCase User-Agent ^NameOfBadRobot goaway<br />
- <Location /secret/files><br />
- Order allow,deny<br />
- Allow from all<br />
- Deny from env=goaway<br />
- </Location>
- </example>
+ <highlight language="config">
+SetEnvIfNoCase User-Agent ^NameOfBadRobot goaway
+<Location /secret/files>
+ Order allow,deny
+ Allow from all
+ Deny from env=goaway
+</Location>
+ </highlight>
<p>
As noted above, this technique is trivial to circumvent, by simply
modifying the <code>USER_AGENT</code> request header. If you
<dt>Solution:</dt>
<dd>
-<example>
-RewriteEngine on<br />
-RewriteMap hosts-deny txt:/path/to/hosts.deny<br />
-RewriteCond ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND [OR]<br />
-RewriteCond ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND<br />
+<highlight language="config">
+RewriteEngine on
+RewriteMap hosts-deny txt:/path/to/hosts.deny
+RewriteCond ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND [OR]
+RewriteCond ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND
RewriteRule ^ - [F]
-</example>
+</highlight>
<example>
##<br />
<p>The following ruleset uses a map file to associate each Referer
with a redirection target.</p>
-<example>
-RewriteMap deflector txt:/path/to/deflector.map<br />
-<br />
-RewriteCond %{HTTP_REFERER} !=""<br />
-RewriteCond ${deflector:%{HTTP_REFERER}} =-<br />
-RewriteRule ^ %{HTTP_REFERER} [R,L]<br />
-<br />
-RewriteCond %{HTTP_REFERER} !=""<br />
-RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND<br />
+<highlight language="config">
+RewriteMap deflector txt:/path/to/deflector.map
+
+RewriteCond %{HTTP_REFERER} !=""
+RewriteCond ${deflector:%{HTTP_REFERER}} =-
+RewriteRule ^ %{HTTP_REFERER} [R,L]
+
+RewriteCond %{HTTP_REFERER} !=""
+RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND
RewriteRule ^ ${deflector:%{HTTP_REFERER}} [R,L]
-</example>
+</highlight>
<p>The map file lists redirection targets for each referer, or, if
we just wish to redirect back to where they came from, a "-" is
files assuming that server0 is a default server which will be used if
a user has no entry in the map:</p>
-<example>
-RewriteEngine on<br />
-<br />
-RewriteMap users-to-hosts txt:/path/to/map.users-to-hosts<br />
-<br />
+<highlight language="config">
+RewriteEngine on
+
+RewriteMap users-to-hosts txt:/path/to/map.users-to-hosts
+
RewriteRule ^/u/<strong>([^/]+)</strong>/?(.*) http://<strong>${users-to-hosts:$1|server0}</strong>/u/$1/$2
-</example>
+</highlight>
</dd>
</dl>
<dd>
This is done via the following ruleset:
-<example>
-# This example is valid in per-directory context only<br />
-RewriteCond %{REQUEST_URI} <strong>!-U</strong><br />
+<highlight language="config">
+# This example is valid in per-directory context only
+RewriteCond %{REQUEST_URI} <strong>!-U</strong>
RewriteRule ^(.+)\.html$ /regenerate_page.cgi [PT,L]
-</example>
+</highlight>
<p>The <code>-U</code> operator determines whether the test string
(in this case, <code>REQUEST_URI</code>) is a valid URL. It does
module="mod_rewrite">RewriteMap</directive> and a list of servers
to accomplish this.</p>
-<example>
-RewriteEngine on<br />
-RewriteMap lb rnd:/path/to/serverlist.txt<br />
-<br />
+<highlight language="config">
+RewriteEngine on
+RewriteMap lb rnd:/path/to/serverlist.txt
+
RewriteRule ^/(.*) http://${lb:servers}/$1 [P,L]
-</example>
+</highlight>
<p><code>serverlist.txt</code> will contain a list of the servers:</p>
URL causes the 'page' to be refreshed every time it is
updated on the filesystem.</p>
-<example>
+<highlight language="config">
RewriteRule ^(/[uge]/[^/]+/?.*):refresh /internal/cgi/apache/nph-refresh?f=$1
-</example>
+</highlight>
<p>Now when we reference the URL</p>
one would usually say "left as an exercise to the reader"
;-) I will provide this, too.</p>
-<example><pre>
+<highlight language="perl">
#!/sw/bin/perl
##
## nph-refresh -- NPH/CGI script for auto refreshing pages
exit(0);
##EOF##
-</pre></example>
+</highlight>
</dd>
</dl>
<p>We use the following ruleset to expand the tilde URLs
into the above layout.</p>
-<example>
-RewriteEngine on<br />
+<highlight language="config">
+RewriteEngine on
RewriteRule ^/~(<strong>([a-z])</strong>[a-z0-9]+)(.*) /home/<strong>$2</strong>/$1/public_html$3
-</example>
+</highlight>
</dd>
</dl>
<code>>STRING</code> and <code>=STRING</code> we can
do time-dependent redirects:</p>
-<example>
-RewriteEngine on<br />
-RewriteCond %{TIME_HOUR}%{TIME_MIN} >0700<br />
-RewriteCond %{TIME_HOUR}%{TIME_MIN} <1900<br />
-RewriteRule ^foo\.html$ foo.day.html [L]<br />
+<highlight language="config">
+RewriteEngine on
+RewriteCond %{TIME_HOUR}%{TIME_MIN} >0700
+RewriteCond %{TIME_HOUR}%{TIME_MIN} <1900
+RewriteRule ^foo\.html$ foo.day.html [L]
RewriteRule ^foo\.html$ foo.night.html
-</example>
+</highlight>
<p>This provides the content of <code>foo.day.html</code>
under the URL <code>foo.html</code> from
<dd>
<p>Use the [E] flag to set an environment variable.</p>
-<example>
-RewriteEngine on<br />
+<highlight language="config">
+RewriteEngine on
RewriteRule ^/horse/(.*) /pony/$1 [E=<strong>rewritten:1</strong>]
-</example>
+</highlight>
<p>Later in your ruleset you might check for this environment
variable using a RewriteCond:</p>
-<example>
+<highlight language="config">
RewriteCond %{ENV:rewritten} =1
-</example>
+</highlight>
<p>Note that environment variables do not survive an external
redirect. You might consider using the [CO] flag to set a
<p>To redirect URLs under <code>/one</code> to
<code>http://one.example.com</code>, do the following:</p>
-<example>
-Redirect /one/ http://one.example.com/
-</example>
+<highlight language="config">Redirect /one/ http://one.example.com/</highlight>
<p>To redirect <code>http</code> URLs to <code>https</code>, do the
following:</p>
-<example>
+<highlight language="config">
<VirtualHost *:80>
-ServerName www.example.com<br />
-Redirect / https://www.example.com/<br />
+ ServerName www.example.com
+ Redirect / https://www.example.com/
</VirtualHost >
-<br />
+
<VirtualHost *:443>
-ServerName www.example.com<br />
-<br />
-# ... SSL configuration goes here<br />
+ ServerName www.example.com
+ # ... SSL configuration goes here
</VirtualHost >
-</example>
+</highlight>
<p>The use of <code>RewriteRule</code> to perform this task may be
appropriate if there are other <code>RewriteRule</code> directives in
and performance.</p>
<example><title>Using Alias</title>
-Alias /cats /var/www/virtualhosts/felines/htdocs
+<highlight language="config">Alias /cats /var/www/virtualhosts/felines/htdocs</highlight>
</example>
<p>
href="flags.html#flag_p">[P]</a> flag to pass rewritten URIs through
<module>mod_proxy</module>.</p>
-<example>
+<highlight language="config">
RewriteRule ^/?images(.*) http://imageserver.local/images$1 [P]
-</example>
+</highlight>
<p>However, in many cases, when there is no actual pattern matching
needed, as in the example shown above, the <directive
module="mod_proxy">ProxyPass</directive> directive is a better choice.
The example here could be rendered as:</p>
-<example>
+<highlight language="config">
ProxyPass /images/ http://imageserver.local/images/
-</example>
+</highlight>
<p>Note that whether you use <directive
module="mod_rewrite">RewriteRule</directive> or <directive
<directive module="mod_proxy">ProxyPassReverse</directive> directive to
catch redirects issued from the back-end server:</p>
-<example>
+<highlight language="config">
ProxyPassReverse /images/ http://imageserver.local/images/
-</example>
+</highlight>
<p>You may need to use <code>RewriteRule</code> instead when there are
other <code>RewriteRule</code>s in effect in the same scope, as a
<code>example.com</code>. This can be done using the <directive
module="core" type="section">If</directive> directive, as shown here:</p>
-<example>
-<If "$req{Host} != 'www.example.com'"><br />
-RedirectMatch (.*) http://www.example.com$1<br />
+<highlight language="config">
+<If "$req{Host} != 'www.example.com'">
+ RedirectMatch (.*) http://www.example.com$1
</If>
-</example>
+</highlight>
<p>This technique can be used to take actions based on any request
header, response header, or environment variable, replacing
its behavior modified by one or more flags. Flags are included in
square brackets at the end of the rule, and multiple flags are separated
by commas.</p>
-<example>
-RewriteRule pattern target [Flag1,Flag2,Flag3]
-</example>
+<highlight language="config">RewriteRule pattern target [Flag1,Flag2,Flag3]</highlight>
<p>The flags all have a short form, such as <code>CO</code>, as well as
a longer form, such as <code>cookie</code>. Some flags take one or more
Using the B flag, non-alphanumeric characters in backreferences
will be escaped. For example, consider the rule:</p>
-<example>
-RewriteRule ^search/(.*)$ /search.php?term=$1
-</example>
+<highlight language="config">RewriteRule ^search/(.*)$ /search.php?term=$1</highlight>
<p>Given a search term of 'x & y/z', a browser will encode it as
'x%20%26%20y%2Fz', making the request 'search/x%20%26%20y%2Fz'. Without the B
<p>Several examples are offered here:</p>
-<example>
-RewriteEngine On<br />
+<highlight language="config">
+RewriteEngine On
RewriteRule ^/index\.html - [CO=frontdoor:yes:.example.com:1440:/]
-</example>
+</highlight>
<p>In the example give, the rule doesn't rewrite the request.
The "-" rewrite target tells mod_rewrite to pass the request
environment variable is used to exclude those requests from the access
log.</p>
-<example>
-RewriteRule \.(png|gif|jpg) - [E=image:1]<br />
+<highlight language="config">
+RewriteRule \.(png|gif|jpg) - [E=image:1]
CustomLog logs/access_log combined env=!image
-</example>
+</highlight>
<p>Note that this same effect can be obtained using <directive
module="mod_setenvif">SetEnvIf</directive>. This technique is offered as
<p>The following rule will forbid <code>.exe</code> files from being
downloaded from your server.</p>
-<example>
-RewriteRule \.exe - [F]
-</example>
+<highlight language="config">RewriteRule \.exe - [F]</highlight>
<p>This example uses the "-" syntax for the rewrite target, which means
that the requested URI is not modified. There's no reason to rewrite to
<p>As with the [F] flag, you will typically use the "-" syntax for the
rewrite target when using the [G] flag:</p>
-<example>
-RewriteRule oldproduct - [G,NC]
-</example>
+<highlight language="config">RewriteRule oldproduct - [G,NC]</highlight>
<p>When using [G], an [L] is implied - that is, the response is returned
immediately, and no further rules are evaluated.</p>
handler. For example, one might use this to force all files without a
file extension to be parsed by the php handler:</p>
-<example>
-RewriteRule !\. - [H=application/x-httpd-php]
-</example>
+<highlight language="config">RewriteRule !\. - [H=application/x-httpd-php]</highlight>
<p>
The regular expression above - <code>!\.</code> - will match any request
<code>.php</code> files to be <em>displayed</em> by <code>mod_php</code>
if they are requested with the <code>.phps</code> extension:</p>
-<example>
+<highlight language="config">
RewriteRule ^(/source/.+\.php)s$ $1 [H=application/x-httpd-php-source]
-</example>
+</highlight>
<p>The regular expression above - <code>^(/source/.+\.php)s$</code> - will
match any request that starts with <code>/source/</code> followed by 1 or
is already for <code>index.php</code>, the <directive
module="mod_rewrite">RewriteRule</directive> will be skipped.</p>
-<example>
-RewriteBase /<br />
-RewriteCond %{REQUEST_URI} !=/index.php<br />
+<highlight language="config">
+RewriteBase /
+RewriteCond %{REQUEST_URI} !=/index.php
RewriteRule ^(.*) /index.php?req=$1 [L,PT]
-</example>
+</highlight>
</section>
<section id="flag_n"><title>N|next</title>
so until there are no more As to be replaced.
</p>
-<example>
-RewriteRule (.*)A(.*) $1B$2 [N]
-</example>
+<highlight language="config">RewriteRule (.*)A(.*) $1B$2 [N]</highlight>
<p>You can think of this as a <code>while</code> loop: While this
pattern still matches (i.e., while the URI still contains an
<code>.jpg</code> and <code>.JPG</code> files are both acceptable, for
example.</p>
-<example>
-RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC]
-</example>
+<highlight language="config">RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC]</highlight>
</section>
<section id="flag_ne"><title>NE|noescape</title>
equivalent. Using the [NE] flag prevents that from happening.
</p>
-<example>
-RewriteRule ^/anchor/(.+) /bigpage.html#$1 [NE,R]
-</example>
+<highlight language="config">RewriteRule ^/anchor/(.+) /bigpage.html#$1 [NE,R]</highlight>
<p>
The above example will redirect <code>/anchor/xyz</code> to
example, if you wanted all image requests to be handled by a back-end
image server, you might do something like the following:</p>
-<example>
-RewriteRule /(.*)\.(jpg|gif|png) http://images.example.com/$1.$2 [P]
-</example>
+<highlight language="config">RewriteRule /(.*)\.(jpg|gif|png) http://images.example.com/$1.$2 [P]</highlight>
<p>Use of the [P] flag implies [L] - that is, the request is immediately
pushed through the proxy, and any following rules will not be
<directive module="mod_alias">Alias</directive> is evaluated.
</p>
-<example>
-Alias /icons /usr/local/apache/icons<br />
+<highlight language="config">
+Alias /icons /usr/local/apache/icons
RewriteRule /pics/(.+)\.jpg /icons/$1.gif [PT]
-</example>
+</highlight>
<p>
Omission of the [PT] flag in this case will cause the Alias to be
<p>Consider the following rule:</p>
-<example>
-RewriteRule /pages/(.+) /page.php?page=$1 [QSA]
-</example>
+<highlight language="config">RewriteRule /pages/(.+) /page.php?page=$1 [QSA]</highlight>
<p>With the [QSA] flag, a request for <code>/pages/123?one=two</code> will be
mapped to <code>/page.php?page=123&one=two</code>. Without the [QSA]
to run the <directive module="mod_rewrite">RewriteRule</directive> if the
requested URI doesn't correspond with an actual file.</p>
-<example>
-# Is the request for a non-existent file?<br />
-RewriteCond %{REQUEST_FILENAME} !-f<br />
-RewriteCond %{REQUEST_FILENAME} !-d<br />
-# If so, skip these two RewriteRules<br />
-RewriteRule .? - [S=2]<br />
-<br />
-RewriteRule (.*\.gif) images.php?$1<br />
+<highlight language="config">
+# Is the request for a non-existent file?
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+# If so, skip these two RewriteRules
+RewriteRule .? - [S=2]
+
+RewriteRule (.*\.gif) images.php?$1
RewriteRule (.*\.html) docs.php?$1
-</example>
+</highlight>
<p>This technique is useful because a <directive
module="mod_rewrite">RewriteCond</directive> only applies to the
use this to make pseudo if-then-else constructs: The last rule of
the then-clause becomes <code>skip=N</code>, where N is the
number of rules in the else-clause:</p>
-<example>
-# Does the file exist?<br />
-RewriteCond %{REQUEST_FILENAME} !-f<br />
-RewriteCond %{REQUEST_FILENAME} !-d<br />
-# Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza.<br />
-RewriteRule .? - [S=3]<br />
-<br />
+<highlight language="config">
+# Does the file exist?
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+# Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza.
+RewriteRule .? - [S=3]
+
# IF the file exists, then:
-<indent>
- RewriteRule (.*\.gif) images.php?$1<br />
- RewriteRule (.*\.html) docs.php?$1<br />
- # Skip past the "else" stanza.<br />
- RewriteRule .? - [S=1]<br />
-</indent>
+ RewriteRule (.*\.gif) images.php?$1
+ RewriteRule (.*\.html) docs.php?$1
+ # Skip past the "else" stanza.
+ RewriteRule .? - [S=1]
# ELSE...
-<indent>
- RewriteRule (.*) 404.php?file=$1<br />
-</indent>
+ RewriteRule (.*) 404.php?file=$1
# END
-</example>
+</highlight>
<p>It is probably easier to accomplish this kind of configuration using
the <directive type="section">If</directive>, <directive
<p>For example, you might use the following technique to serve Perl
source code as plain text, if requested in a particular way:</p>
-<example>
-# Serve .pl files as plain text<br />
+<highlight language="config">
+# Serve .pl files as plain text
RewriteRule \.pl$ - [T=text/plain]
-</example>
+</highlight>
<p>Or, perhaps, if you have a camera that produces jpeg images without
file extensions, you could force those images to be served with the
correct MIME type by virtue of their file names:</p>
-<example>
-# Files with 'IMG' in the name are jpg images.<br />
+<highlight language="config">
+# Files with 'IMG' in the name are jpg images.
RewriteRule IMG - [T=image/jpg]
-</example>
+</highlight>
<p>Please note that this is a trivial example, and could be better done
using <directive type="section" module="core">FilesMatch</directive>
<p>To simply map a URL to another server, we use the [P] flag, as
follows:</p>
-<example>
-RewriteEngine on<br />
-RewriteBase /products/<br />
-RewriteRule ^<strong>widget/</strong>(.*)$ <strong>http://product.example.com/widget/</strong>$1 [<strong>P</strong>]<br />
+<highlight language="config">
+RewriteEngine on
+RewriteBase /products/
+RewriteRule ^<strong>widget/</strong>(.*)$ <strong>http://product.example.com/widget/</strong>$1 [<strong>P</strong>]
ProxyPassReverse /products/widget/ http://product.example.com/widget/
-</example>
+</highlight>
<p>In the second example, we proxy the request only if we can't find
the resource locally. This can be very useful when you're migrating
from one server to another, and you're not sure if all the content
has been migrated yet.</p>
-<example>
-RewriteCond %{REQUEST_FILENAME} <strong>!-f</strong><br />
-RewriteCond %{REQUEST_FILENAME} <strong>!-d</strong><br />
-RewriteRule ^/(.*) http://<strong>old</strong>.example.com/$1 [<strong>P</strong>]<br />
+<highlight language="config">
+RewriteCond %{REQUEST_FILENAME} <strong>!-f</strong>
+RewriteCond %{REQUEST_FILENAME} <strong>!-d</strong>
+RewriteRule ^/(.*) http://<strong>old</strong>.example.com/$1 [<strong>P</strong>]
ProxyPassReverse / http://old.example.com/
-</example>
+</highlight>
</dd>
<dt>Discussion:</dt>
<p>We rewrite the old URL to the new one internally via the
following rule:</p>
-<example>
-RewriteEngine on<br />
+<highlight language="config">
+RewriteEngine on
RewriteRule ^<strong>/old</strong>\.html$ <strong>/new</strong>.html [PT]
-</example>
+</highlight>
</dd>
</dl>
<p>We force a HTTP redirect to the new URL which leads to a
change of the browsers and thus the users view:</p>
-<example>
-RewriteEngine on<br />
+<highlight language="config">
+RewriteEngine on
RewriteRule ^<strong>/foo</strong>\.html$ <strong>bar</strong>.html [<strong>R</strong>]
-</example>
+</highlight>
</dd>
<dt>Discussion</dt>
use the Redirect directive. mod_rewrite was used in that earlier
example in order to hide the redirect from the client:</p>
- <example>
+ <highlight language="config">
Redirect /foo.html /bar.html
- </example>
+ </highlight>
</dd>
</dl>
to the new server, but you might also consider using the Redirect
or RedirectMatch directive.</p>
-<example><title>With mod_rewrite</title>
-RewriteEngine on<br />
+<highlight language="config"><strong>With mod_rewrite</strong>
+RewriteEngine on
RewriteRule ^/docs/(.+) http://new.example.com/docs/$1 [R,L]
-</example>
+</highlight>
-<example><title>With RedirectMatch</title>
+<highlight language="config"><strong>With RedirectMatch</strong>
RedirectMatch ^/docs/(.*) http://new.example.com/docs/$1
-</example>
+</highlight>
-<example><title>With Redirect</title>
+<highlight language="config"><strong>With Redirect</strong>
Redirect /docs/ http://new.example.com/docs/
-</example>
+</highlight>
</dd>
</dl>
internally leads to the invocation of
<code>/~quux/foo.cgi</code>.</p>
-<example>
-RewriteEngine on<br />
-RewriteBase /~quux/<br />
+<highlight language="config">
+RewriteEngine on
+RewriteBase /~quux/
RewriteRule ^foo\.<strong>html</strong>$ foo.<strong>cgi</strong> [H=<strong>cgi-script</strong>]
-</example>
+</highlight>
</dd>
</dl>
existence of the new extension. If it exists, we take
that name, else we rewrite the URL to its original state.</p>
-<example>
-# backward compatibility ruleset for<br />
-# rewriting document.html to document.php<br />
-# when and only when document.php exists<br />
-<Directory /var/www/htdocs><br />
+<highlight language="config">
+# backward compatibility ruleset for
+# rewriting document.html to document.php
+# when and only when document.php exists
+<Directory /var/www/htdocs>
<indent>
-RewriteEngine on<br />
-RewriteBase /var/www/htdocs<br />
-<br />
-RewriteCond $1.php -f<br />
-RewriteCond $1.html !-f<br />
-RewriteRule ^(.*).html$ $1.php<br />
+RewriteEngine on
+RewriteBase /var/www/htdocs
+
+RewriteCond $1.php -f
+RewriteCond $1.html !-f
+RewriteRule ^(.*).html$ $1.php
</indent>
</Directory>
-</example>
+</highlight>
</dd>
<dt>Discussion</dt>
directive placed in a virtual host for the non-canonical
hostname(s).</p>
-<example>
-<VirtualHost *:80><br />
-<indent>
- ServerName undesired.example.com<br />
- ServerAlias example.com notthis.example.com<br />
-<br />
- Redirect / http://www.example.com/<br />
-</indent>
-</VirtualHost><br />
-<br />
-<VirtualHost *:80><br />
-<indent>
- ServerName www.example.com<br />
-</indent>
+<highlight language="config">
+<VirtualHost *:80>
+ ServerName undesired.example.com
+ ServerAlias example.com notthis.example.com
+
+ Redirect / http://www.example.com/
</VirtualHost>
-</example>
+
+<VirtualHost *:80>
+ ServerName www.example.com
+</VirtualHost>
+</highlight>
<p>You can alternatively accomplish this using the
<directive module="core" type="section">If</directive>
directive:</p>
-<example>
-<If "%{HTTP_HOST} != 'www.example.com'"><br />
-<indent>
-Redirect / http://www.example.com/
-</indent>
+<highlight language="config">
+<If "%{HTTP_HOST} != 'www.example.com'">
+ Redirect / http://www.example.com/
</If>
-</example>
+</highlight>
<p>Or, for example, to redirect a portion of your site to HTTPS, you
might do the following:</p>
-<example>
-<If "%{SERVER_PROTOCOL} != 'HTTPS'"><br />
-<indent>
-Redirect /admin/ https://www.example.com/admin/
-</indent>
+<highlight language="config">
+<If "%{SERVER_PROTOCOL} != 'HTTPS'">
+ Redirect /admin/ https://www.example.com/admin/
</If>
-</example>
+</highlight>
<p>If, for whatever reason, you still want to use <code>mod_rewrite</code>
- if, for example, you need this to work with a larger set of RewriteRules -
you might use one of the recipes below.</p>
<p>For sites running on a port other than 80:</p>
-<example>
-RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]<br />
-RewriteCond %{HTTP_HOST} !^$<br />
-RewriteCond %{SERVER_PORT} !^80$<br />
+<highlight language="config">
+RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
+RewriteCond %{HTTP_HOST} !^$
+RewriteCond %{SERVER_PORT} !^80$
RewriteRule ^/?(.*) http://www.example.com:%{SERVER_PORT}/$1 [L,R,NE]
-</example>
+</highlight>
<p>And for a site running on port 80</p>
-<example>
-RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]<br />
-RewriteCond %{HTTP_HOST} !^$<br />
+<highlight language="config">
+RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
+RewriteCond %{HTTP_HOST} !^$
RewriteRule ^/?(.*) http://www.example.com/$1 [L,R,NE]
-</example>
+</highlight>
<p>
If you wanted to do this generically for all domain names - that
<strong>example.com</strong>, you could use the following
recipe:</p>
-<example>
-RewriteCond %{HTTP_HOST} !^www\. [NC]<br />
-RewriteCond %{HTTP_HOST} !^$<br />
+<highlight language="config">
+RewriteCond %{HTTP_HOST} !^www\. [NC]
+RewriteCond %{HTTP_HOST} !^$
RewriteRule ^/?(.*) http://www.%{HTTP_HOST}/$1 [L,R,NE]
-</example>
+</highlight>
<p>These rulesets will work either in your main server configuration
file, or in a <code>.htaccess</code> file placed in the <directive
resource, and, if not finding it in either place, will attempt to
just serve it out of the location requested.</p>
-<example>
-RewriteEngine on<br />
-<br />
-# first try to find it in dir1/...<br />
-# ...and if found stop and be happy:<br />
-RewriteCond %{DOCUMENT_ROOT}/<strong>dir1</strong>/%{REQUEST_URI} -f<br />
-RewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir1</strong>/$1 [L]<br />
-<br />
-# second try to find it in dir2/...<br />
-# ...and if found stop and be happy:<br />
-RewriteCond %{DOCUMENT_ROOT}/<strong>dir2</strong>/%{REQUEST_URI} -f<br />
-RewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir2</strong>/$1 [L]<br />
-<br />
-# else go on for other Alias or ScriptAlias directives,<br />
-# etc.<br />
+<highlight language="config">
+RewriteEngine on
+
+# first try to find it in dir1/...
+# ...and if found stop and be happy:
+RewriteCond %{DOCUMENT_ROOT}/<strong>dir1</strong>/%{REQUEST_URI} -f
+RewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir1</strong>/$1 [L]
+
+# second try to find it in dir2/...
+# ...and if found stop and be happy:
+RewriteCond %{DOCUMENT_ROOT}/<strong>dir2</strong>/%{REQUEST_URI} -f
+RewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir2</strong>/$1 [L]
+
+# else go on for other Alias or ScriptAlias directives,
+# etc.
RewriteRule ^ - [PT]
-</example>
+</highlight>
</dd>
</dl>
<p>We'll use a <directive module="mod_rewrite">RewriteMap</directive>
directive to build a list of servers that we wish to use.</p>
-<example>
-HostnameLookups on<br />
-RewriteEngine on<br />
-RewriteMap multiplex txt:/path/to/map.mirrors<br />
-RewriteCond %{REMOTE_HOST} ([a-z]+)$ [NC]<br />
+<highlight language="config">
+HostnameLookups on
+RewriteEngine on
+RewriteMap multiplex txt:/path/to/map.mirrors
+RewriteCond %{REMOTE_HOST} ([a-z]+)$ [NC]
RewriteRule ^/(.*)$ ${multiplex:<strong>%1</strong>|http://www.example.com/}$1 [R,L]
-</example>
+</highlight>
<example>
## map.mirrors -- Multiplexing Map<br />
All other browsers receive page <code>foo.32.html</code>.
This is done with the following ruleset:</p>
-<example>
-RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/3</strong>.*<br />
-RewriteRule ^foo\.html$ foo.<strong>NS</strong>.html [<strong>L</strong>]<br />
-<br />
-RewriteCond %{HTTP_USER_AGENT} ^<strong>Lynx/</strong> [OR]<br />
-RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/[12]</strong><br />
-RewriteRule ^foo\.html$ foo.<strong>20</strong>.html [<strong>L</strong>]<br />
-<br />
+<highlight language="config">
+RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/3</strong>.*
+RewriteRule ^foo\.html$ foo.<strong>NS</strong>.html [<strong>L</strong>]
+
+RewriteCond %{HTTP_USER_AGENT} ^<strong>Lynx/</strong> [OR]
+RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/[12]</strong>
+RewriteRule ^foo\.html$ foo.<strong>20</strong>.html [<strong>L</strong>]
+
RewriteRule ^foo\.html$ foo.<strong>32</strong>.html [<strong>L</strong>]
-</example>
+</highlight>
</dd>
</dl>
we replace <code>/puppies</code> and <code>/canines</code>
by the canonical <code>/dogs</code>.</p>
-<example>
-RewriteRule ^/(puppies|canines)/(.*) /dogs/$2 [R]
-</example>
+<highlight language="config">RewriteRule ^/(puppies|canines)/(.*) /dogs/$2 [R]</highlight>
</dd>
<dt>Discussion:</dt>
This should really be accomplished with Redirect or RedirectMatch
directives:
- <example>
- RedirectMatch ^/(puppies|canines)/(.*) /dogs/$2
- </example>
+ <highlight language="config"> RedirectMatch ^/(puppies|canines)/(.*) /dogs/$2 </highlight>
</dd>
</dl>
<code>/about/</code>:
</p>
-<example>
-RewriteEngine on<br />
+<highlight language="config">
+RewriteEngine on
RewriteRule <strong>^/$</strong> /about/ [<strong>R</strong>]
-</example>
+</highlight>
<p>Note that this can also be handled using the <directive
module="mod_alias">RedirectMatch</directive> directive:</p>
-<example>
-RedirectMatch ^/$ http://example.com/about/
-</example>
+<highlight language="config">RedirectMatch ^/$ http://example.com/about/</highlight>
<p>Note also that the example rewrites only the root URL. That is, it
rewrites a request for <code>http://example.com/</code>, but not a
<p>As of version 2.2.16, you should use the <directive
module="mod_dir">FallbackResource</directive> directive for this:</p>
-<example>
-<Directory /var/www/my_blog><br />
-<indent>
- FallbackResource index.php<br />
-</indent>
+<highlight language="config">
+<Directory /var/www/my_blog>
+ FallbackResource index.php
</Directory>
-</example>
+</highlight>
<p>However, in earlier versions of Apache, or if your needs are more
complicated than this, you can use a variation of the following rewrite
set to accomplish the same thing:</p>
-<example>
-<Directory /var/www/my_blog><br />
-<indent>
- RewriteBase /my_blog<br />
-<br />
- RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-f<br />
- RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-d<br />
- RewriteRule ^ index.php [PT]<br />
-</indent>
+<highlight language="config">
+<Directory /var/www/my_blog>
+ RewriteBase /my_blog
+
+ RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-f
+ RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-d
+ RewriteRule ^ index.php [PT]
</Directory>
-</example>
+</highlight>
<p>If, on the other hand, you wish to pass the requested URI as a query
string argument to index.php, you can replace that RewriteRule with:</p>
-<example>
- RewriteRule (.*) index.php?$1 [PT,QSA]
-</example>
+<highlight language="config">RewriteRule (.*) index.php?$1 [PT,QSA]</highlight>
<p>Note that these rulesets can be used in a <code>.htaccess</code>
file, as well as in a <Directory> block.</p>
<p>The syntax of the <code>RewriteMap</code> directive is as
follows:</p>
-<example>
-RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
-</example>
+<highlight language="config">RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em></highlight>
<p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
arbitray name that you assign to the map, and which you will use in
<p>For example, you might define a
<directive>RewriteMap</directive> as:</p>
- <example>
- RewriteMap examplemap txt:/path/to/file/map.txt
- </example>
+ <highlight language="config">RewriteMap examplemap txt:/path/to/file/map.txt</highlight>
<p>You would then be able to use this map in a
<directive>RewriteRule</directive> as follows:</p>
-<example>
- RewriteRule ^/ex/(.*) ${examplemap:$1}
-</example>
+<highlight language="config">RewriteRule ^/ex/(.*) ${examplemap:$1}</highlight>
<p>A default value can be specified in the event that nothing is found
in the map:</p>
-<example>
-RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
-</example>
+<highlight language="config">RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}</highlight>
<note><title>Per-directory and .htaccess context</title>
<p>
product IDs for easier-to-remember URLs, using the following
recipe:</p>
- <example><title>Product to ID configuration</title>
- RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
+ <highlight language="config"><strong>#Product to ID configuration</strong>
+ RewriteMap product2id txt:/etc/apache2/productmap.txt
RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
- </example>
+ </highlight>
<p>We assume here that the <code>prods.php</code> script knows what
to do when it received an argument of <code>id=NOTFOUND</code> when
scope. If you're planning to use this in a <code>.htaccess</code>
file, you'll need to remove the leading slash from the rewrite
pattern in order for it to match anything:
- <example>
- RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
- </example>
+ <highlight language="config">RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]</highlight>
</note>
<note><title>Cached lookups</title>
dynamic www5|www6
</example>
- <example><title>Configuration directives</title>
- RewriteMap servers rnd:/path/to/file/map.txt<br/>
- <br/>
- RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br/>
- RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
- </example>
+ <highlight language="config"><strong>#Configuration directives</strong>
+RewriteMap servers rnd:/path/to/file/map.txt
+
+RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]
+RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
+ </highlight>
<p>So, when an image is requested and the first of these rules is
matched, <code>RewriteMap</code> looks up the string
<p>You may optionally specify a particular dbm type:</p>
- <example>
- RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
- </example>
+ <highlight language="config">
+RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
+ </highlight>
<p>The type can be sdbm, gdbm, ndbm or db.
However, it is recommended that you just use the <a
<p>You can then reference the resulting file in your
<code>RewriteMap</code> directive:</p>
-<example>
+<highlight language="config">
RewriteMap mapname dbm:/etc/apache/mapfile.map
-</example>
+</highlight>
<note>
<p>Note that with some dbm types, more than one file is generated, with
the int function, and then use that in your <code>RewriteRule</code>:
</p>
- <example><title>Redirect a URI to an all-lowercase version of itself</title>
- RewriteMap lc int:tolower<br />
+ <highlight language="config"><strong>Redirect a URI to an all-lowercase version of itself</strong>
+ RewriteMap lc int:tolower
RewriteRule (.*?[A-Z]+.*) ${lc:$1} [R]
- </example>
+ </highlight>
<note>
<p>Please note that the example offered here is for
<p>A simple example is shown here which will replace all dashes with
underscores in a request URI.</p>
- <example><title>Rewrite configuration</title>
- RewriteMap d2u prg:/www/bin/dash2under.pl<br />
- RewriteRule - ${d2u:%{REQUEST_URI}}
- </example>
+ <highlight language="config"><strong>#Rewrite configuration</strong>
+RewriteMap d2u prg:/www/bin/dash2under.pl<br />
+RewriteRule - ${d2u:%{REQUEST_URI}}
+ </highlight>
- <example><title>dash2under.pl</title>
+ <p><strong>dash2under.pl</strong></p>
<highlight language="perl">
#!/usr/bin/perl
$| = 1; # Turn off I/O buffering
print $_;
}
</highlight>
- </example>
<note><title>Caution!</title>
<ul>
<p>If a query returns more than one row, a random row from
the result set is used.</p>
- <example><title>Example</title>
+ <highlight language="config"><strong>Example</strong>
RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
- </example>
+ </highlight>
</section>
<section id="summary">
<dd>
-<example>
-RewriteEngine on<br />
-<br />
-RewriteMap lowercase int:tolower<br />
-<br />
-RewriteCond %{lowercase:%{<strong>HTTP_HOST</strong>}} ^www\.<strong>([^.]+)</strong>\.example\.com$<br />
+<highlight language="config">
+RewriteEngine on
+
+RewriteMap lowercase int:tolower
+
+RewriteCond %{lowercase:%{<strong>HTTP_HOST</strong>}} ^www\.<strong>([^.]+)</strong>\.example\.com$
RewriteRule ^(.*) /home/<strong>%1</strong>/www$1
-</example></dd>
+</highlight></dd>
<dt>Discussion</dt>
<dd>
any <code>ScriptAlias</code> directives, we must have
<code>mod_rewrite</code> explicitly enact those mappings.</p>
-<example>
-# get the server name from the Host: header<br />
-UseCanonicalName Off<br />
-<br />
-# splittable logs<br />
-LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon<br />
-CustomLog logs/access_log vcommon<br />
-<br />
-<Directory /www/hosts><br />
-<indent>
- # ExecCGI is needed here because we can't force<br />
- # CGI execution in the way that ScriptAlias does<br />
- Options FollowSymLinks ExecCGI<br />
-</indent>
-</Directory><br />
-<br />
-RewriteEngine On<br />
-<br />
-# a ServerName derived from a Host: header may be any case at all<br />
-RewriteMap lowercase int:tolower<br />
-<br />
-## deal with normal documents first:<br />
-# allow Alias /icons/ to work - repeat for other aliases<br />
-RewriteCond %{REQUEST_URI} !^/icons/<br />
-# allow CGIs to work<br />
-RewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
-# do the magic<br />
-RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1<br />
-<br />
-## and now deal with CGIs - we have to force a handler<br />
-RewriteCond %{REQUEST_URI} ^/cgi-bin/<br />
-RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [H=cgi-script]<br />
-</example>
+<highlight language="config">
+# get the server name from the Host: header
+UseCanonicalName Off
+
+# splittable logs
+LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon
+CustomLog logs/access_log vcommon
+
+<Directory /www/hosts>
+ # ExecCGI is needed here because we can't force
+ # CGI execution in the way that ScriptAlias does
+ Options FollowSymLinks ExecCGI
+</Directory>
+
+RewriteEngine On
+
+# a ServerName derived from a Host: header may be any case at all
+RewriteMap lowercase int:tolower
+
+## deal with normal documents first:
+# allow Alias /icons/ to work - repeat for other aliases
+RewriteCond %{REQUEST_URI} !^/icons/
+# allow CGIs to work
+RewriteCond %{REQUEST_URI} !^/cgi-bin/
+# do the magic
+RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1
+
+## and now deal with CGIs - we have to force a handler
+RewriteCond %{REQUEST_URI} ^/cgi-bin/
+RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [H=cgi-script]
+</highlight>
</section>
<p>The <code>httpd.conf</code> should contain the following:</p>
-<example>
-RewriteEngine on<br />
-<br />
-RewriteMap lowercase int:tolower<br />
-<br />
-# define the map file<br />
-RewriteMap vhost txt:/www/conf/vhost.map<br />
-<br />
-# deal with aliases as above<br />
-RewriteCond %{REQUEST_URI} !^/icons/<br />
-RewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
-RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br />
-# this does the file-based remap<br />
-RewriteCond ${vhost:%1} ^(/.*)$<br />
-RewriteRule ^/(.*)$ %1/docs/$1<br />
-<br />
-RewriteCond %{REQUEST_URI} ^/cgi-bin/<br />
-RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br />
-RewriteCond ${vhost:%1} ^(/.*)$<br />
+<highlight language="config">
+RewriteEngine on
+
+RewriteMap lowercase int:tolower
+
+# define the map file
+RewriteMap vhost txt:/www/conf/vhost.map
+
+# deal with aliases as above
+RewriteCond %{REQUEST_URI} !^/icons/
+RewriteCond %{REQUEST_URI} !^/cgi-bin/
+RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$
+# this does the file-based remap
+RewriteCond ${vhost:%1} ^(/.*)$
+RewriteRule ^/(.*)$ %1/docs/$1
+
+RewriteCond %{REQUEST_URI} ^/cgi-bin/
+RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$
+RewriteCond ${vhost:%1} ^(/.*)$
RewriteRule ^/(.*)$ %1/cgi-bin/$1 [H=cgi-script]
-</example>
+</highlight>
</section>
projects / thirdparty / apache / httpd.git / commitdiff
