1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type" />
<!--
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-->
<title>Apache mod_rewrite Introduction - Apache HTTP Server Version 2.4</title>
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
<script src="../style/scripts/prettify.min.js" type="text/javascript">
</script>
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
<body id="manual-page"><div id="page-header">
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
<p class="apache">Apache HTTP Server Version 2.4</p>
<img alt="" src="../images/feather.png" /></div>
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
<div id="path">
<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Introduction</h1>
<div class="toplang">
<p><span>Available Languages: </span><a href="../en/rewrite/intro.html" title="English"> en </a> |
<a href="../fr/rewrite/intro.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
</div>
<p>This document supplements the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
<a href="../mod/mod_rewrite.html">reference documentation</a>. It
describes the basic concepts necessary for use of
<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. Other documents go into greater detail,
but this doc should help the beginner get their feet wet.
</p>
</div>
<div id="quickview"><a href="https://www.apache.org/foundation/contributing.html" class="badge"><img src="https://www.apache.org/images/SupportApache-small.png" alt="Support Apache!" /></a><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#regex">Regular Expressions</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#rewriterule">RewriteRule Basics</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#flags">Rewrite Flags</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">Rewrite Conditions</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#rewritemap">Rewrite maps</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#htaccess">.htaccess files</a></li>
</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="rewritemap.html">Using RewriteMap</a></li><li><a href="advanced.html">Advanced techniques</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="introduction" id="introduction">Introduction</a></h2>
<p>The Apache module <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> is a very powerful and
sophisticated module which provides a way to do URL manipulations. With
it, you can do nearly all types of URL rewriting that you may need. It
is, however, somewhat complex, and may be intimidating to the beginner.
There is also a tendency to treat rewrite rules as magic incantation,
using them without actually understanding what they do.</p>
<p>This document attempts to give sufficient background so that what
follows is understood, rather than just copied blindly.
</p>
<p>Remember that many common URL-manipulation tasks don't require the
full power and complexity of <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. For simple
tasks, see <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and the documentation
on <a href="../urlmapping.html">mapping URLs to the
filesystem</a>.</p>
<p>Finally, before proceeding, be sure to configure
<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>'s log level to one of the trace levels using
the <code class="directive"><a href="../mod/core.html#loglevel">LogLevel</a></code> directive. Although this
can give an overwhelming amount of information, it is indispensable in
debugging problems with <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> configuration, since
it will tell you exactly how each rule is processed.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="regex" id="regex">Regular Expressions</a></h2>
<p><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> uses the <a href="http://pcre.org/">Perl Compatible
Regular Expression</a> vocabulary. In this document, we do not attempt
to provide a detailed reference to regular expressions. For that, we
recommend the <a href="http://pcre.org/pcre.txt">PCRE man pages</a>, the
<a href="http://perldoc.perl.org/perlre.html">Perl regular
expression man page</a>, and <a href="http://shop.oreilly.com/product/9780596528126.do">Mastering
Regular Expressions, by Jeffrey Friedl</a>.</p>
<p>In this document, we attempt to provide enough of a regex vocabulary
to get you started, without being overwhelming, in the hope that
<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s will be scientific
formulae, rather than magical incantations.</p>
<h3><a name="regexvocab" id="regexvocab">Regex vocabulary</a></h3>
<p>The following are the minimal building blocks you will need, in order
to write regular expressions and <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s. They certainly do not
represent a complete regular expression vocabulary, but they are a good
place to start, and should help you read basic regular expressions, as
well as write your own.</p>
<table>
<tr>
<th>Character</th>
<th>Meaning</th>
<th>Example</th>
</tr>
<tr>
<td><code>.</code></td>
<td>Matches any single character</td>
<td><code>c.t</code> will match <code>cat</code>, <code>cot</code>,
<code>cut</code>, etc</td>
</tr>
<tr>
<td><code>+</code></td>
<td>Repeats the previous match one or more times</td>
<td><code>a+</code> matches <code>a</code>, <code>aa</code>,
<code>aaa</code>, etc</td>
</tr>
<tr>
<td><code>*</code></td>
<td>Repeats the previous match zero or more times</td>
<td><code>a*</code> matches all the same things <code>a+</code> matches,
but will also match an empty string</td>
</tr>
<tr>
<td><code>?</code></td>
<td>Makes the match optional</td>
<td><code>colou?r</code> will match <code>color</code> and
<code>colour</code></td>
</tr>
<tr>
<td><code>\</code></td>
<td>Escape the next character</td>
<td><code>\.</code> will match <code>.</code> (dot) and not <em>any single
character</em> as explain above</td>
</tr>
<tr>
<td><code>^</code></td>
<td>Called an anchor, matches the beginning of the string</td>
<td><code>^a</code> matches a string that begins with <code>a</code></td>
</tr>
<tr>
<td><code>$</code></td>
<td>The other anchor, this matches the end of the string</td>
<td><code>a$</code> matches a string that ends with <code>a</code></td>
</tr>
<tr>
<td><code>( )</code></td>
<td>Groups several characters into a single unit, and captures a match
for use in a backreference</td>
<td><code>(ab)+</code> matches <code>ababab</code> - that is, the
<code>+</code> applies to the group. For more on backreferences see
<a href="#InternalBackRefs">below</a></td>
</tr>
<tr>
<td><code>[ ]</code></td>
<td>A character class - matches one of the characters</td>
<td><code>c[uoa]t</code> matches <code>cut</code>, <code>cot</code> or
<code>cat</code></td>
</tr>
<tr>
<td><code>[^ ]</code></td>
<td>Negative character class - matches any character not specified</td>
<td><code>c[^/]t</code> matches <code>cat</code> or <code>c=t</code> but
not <code>c/t</code></td></tr>
</table>
<p>In <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> the <code>!</code> character can be
used before a regular expression to negate it. This is, a string will
be considered to have matched only if it does not match the rest of
the expression.</p>
<h3><a name="InternalBackRefs" id="InternalBackRefs">Regex Back-Reference Availability</a></h3>
<p>One important thing here has to be remembered: Whenever you
use parentheses in <em>Pattern</em> or in one of the
<em>CondPattern</em>, back-references are internally created
which can be used with the strings <code>$N</code> and
<code>%N</code> (see below). These are available for creating
the <em>Substitution</em> parameter of a
<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or
the <em>TestString</em> parameter of a
<code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>.</p>
<p> Captures in the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> patterns are (counterintuitively) available to
all preceding
<code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directives,
because the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>
expression is evaluated before the individual conditions.</p>
<p>Figure 1 shows to which
locations the back-references are transferred for expansion as
well as illustrating the flow of the RewriteRule, RewriteCond
matching. In the next chapters, we will be exploring how to use
these back-references, so do not fret if it seems a bit alien
to you at first.
</p>
<p class="figure">
<img src="../images/rewrite_backreferences.png" alt="Flow of RewriteRule and RewriteCond matching" /><br />
<dfn>Figure 1:</dfn> The back-reference flow through a rule.<br />
In this example, a request for <code>/test/1234</code> would be transformed into <code>/admin.foo?page=test&id=1234&host=admin.example.com</code>.
</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="rewriterule" id="rewriterule">RewriteRule Basics</a></h2>
<p>A <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> consists
of three arguments separated by spaces. The arguments are</p>
<ol>
<li><var>Pattern</var>: which incoming URLs should be affected by the rule;</li>
<li><var>Substitution</var>: where should the matching requests be sent;</li>
<li><var>[flags]</var>: options affecting the rewritten request.</li>
</ol>
<p>The <var>Pattern</var> is a <a href="#regex">regular expression</a>.
It is initially (for the first rewrite rule or until a substitution occurs)
matched against the URL-path of the incoming request (the part after the
hostname but before any question mark indicating the beginning of a query
string) or, in per-directory context, against the request's path relative
to the directory for which the rule is defined. Once a substitution has
occurred, the rules that follow are matched against the substituted
value.
</p>
<p class="figure">
<img src="../images/syntax_rewriterule.png" alt="Syntax of the RewriteRule directive" /><br />
<dfn>Figure 2:</dfn> Syntax of the RewriteRule directive.
</p>
<p>The <var>Substitution</var> can itself be one of three things:</p>
<dl>
<dt>1. A full filesystem path to a resource</dt>
<dd>
<pre class="prettyprint lang-config">RewriteRule "^/games" "/usr/local/games/web/puzzles.html"</pre>
<p>This maps a request to an arbitrary location on your filesystem, much
like the <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> directive.</p>
</dd>
<dt>2. A web-path to a resource</dt>
<dd>
<pre class="prettyprint lang-config">RewriteRule "^/games$" "/puzzles.html"</pre>
<p>If <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> is set
to <code>/usr/local/apache2/htdocs</code>, then this directive would
map requests for <code>http://example.com/games</code> to the
path <code>/usr/local/apache2/htdocs/puzzles.html</code>.</p>
</dd>
<dt>3. An absolute URL</dt>
<dd>
<pre class="prettyprint lang-config">RewriteRule "^/product/view$" "http://site2.example.com/seeproduct.html" [R]</pre>
<p>This tells the client to make a new request for the specified URL.</p>
</dd>
</dl>
<div class="warning">Note that <strong>1</strong> and <strong>2</strong> have exactly the same syntax. The difference between them is that in the case of <strong>1</strong>, the top level of the target path (i.e., <code>/usr/</code>) exists on the filesystem, where as in the case of <strong>2</strong>, it does not. (i.e., there's no <code>/bar/</code> as a root-level directory in the filesystem.)</div>
<p>The <var>Substitution</var> can also
contain <em>back-references</em> to parts of the incoming URL-path
matched by the <var>Pattern</var>. Consider the following:</p>
<pre class="prettyprint lang-config">RewriteRule "^/product/(.*)/view$" "/var/web/productdb/$1"</pre>
<p>The variable <code>$1</code> will be replaced with whatever text
was matched by the expression inside the parenthesis in
the <var>Pattern</var>. For example, a request
for <code>http://example.com/product/r14df/view</code> will be mapped
to the path <code>/var/web/productdb/r14df</code>.</p>
<p>If there is more than one expression in parenthesis, they are
available in order in the
variables <code>$1</code>, <code>$2</code>, <code>$3</code>, and so
on.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="flags" id="flags">Rewrite Flags</a></h2>
<p>The behavior of a <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> can be modified by the
application of one or more flags to the end of the rule. For example, the
matching behavior of a rule can be made case-insensitive by the
application of the <code>[NC]</code> flag:
</p>
<pre class="prettyprint lang-config">RewriteRule "^puppy.html" "smalldog.html" [NC]</pre>
<p>For more details on the available flags, their meanings, and
examples, see the <a href="flags.html">Rewrite Flags</a> document.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="rewritecond" id="rewritecond">Rewrite Conditions</a></h2>
<p>One or more <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>
directives can be used to restrict the types of requests that will be
subject to the
following <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. The
first argument is a variable describing a characteristic of the
request, the second argument is a <a href="#regex">regular
expression</a> that must match the variable, and a third optional
argument is a list of flags that modify how the match is evaluated.</p>
<p class="figure">
<img src="../images/syntax_rewritecond.png" alt="Syntax of the RewriteCond directive" /><br />
<dfn>Figure 3:</dfn> Syntax of the RewriteCond directive
</p>
<p>For example, to send all requests from a particular IP range to a
different server, you could use:</p>
<pre class="prettyprint lang-config">RewriteCond "%{REMOTE_ADDR}" "^10\.2\."
RewriteRule "(.*)" "http://intranet.example.com$1"</pre>
<p>When more than
one <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> is
specified, they must all match for
the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be
applied. For example, to deny requests that contain the word "hack" in
their query string, unless they also contain a cookie containing
the word "go", you could use:</p>
<pre class="prettyprint lang-config">RewriteCond "%{QUERY_STRING}" "hack"
RewriteCond "%{HTTP_COOKIE}" !go
RewriteRule "." "-" [F]</pre>
<p>Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".</p>
<p>Matches in the regular expressions contained in
the <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>s can be
used as part of the <var>Substitution</var> in
the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> using the
variables <code>%1</code>, <code>%2</code>, etc. For example, this
will direct the request to a different directory depending on the
hostname used to access the site:</p>
<pre class="prettyprint lang-config">RewriteCond "%{HTTP_HOST}" "(.*)"
RewriteRule "^/(.*)" "/sites/%1/$1"</pre>
<p>If the request was for <code>http://example.com/foo/bar</code>,
then <code>%1</code> would contain <code>example.com</code>
and <code>$1</code> would contain <code>foo/bar</code>.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="rewritemap" id="rewritemap">Rewrite maps</a></h2>
<p>The <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
provides a way to call an external function, so to speak, to do your
rewriting for you. This is discussed in greater detail in the <a href="rewritemap.html">RewriteMap supplementary documentation</a>.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="htaccess" id="htaccess">.htaccess files</a></h2>
<p>Rewriting is typically configured in the main server configuration
setting (outside any <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section) or
inside <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code>
containers. This is the easiest way to do rewriting and is
recommended. It is possible, however, to do rewriting
inside <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>
sections or <a href="../howto/htaccess.html"><code>.htaccess</code>
files</a> at the expense of some additional complexity. This technique
is called per-directory rewrites.</p>
<p>The main difference with per-server rewrites is that the path
prefix of the directory containing the <code>.htaccess</code> file is
stripped before matching in
the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. In addition, the <code class="directive"><a href="../mod/mod_rewrite.html#rewritebase">RewriteBase</a></code> should be used to assure the request is properly mapped.</p>
</div></div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/rewrite/intro.html" title="English"> en </a> |
<a href="../fr/rewrite/intro.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Libera.chat, or sent to our <a href="https://httpd.apache.org/lists.html">mailing lists</a>.</div>
<script type="text/javascript"><!--//--><![CDATA[//><!--
var comments_shortname = 'httpd';
var comments_identifier = 'http://httpd.apache.org/docs/2.4/rewrite/intro.html';
(function(w, d) {
if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
d.write('<div id="comments_thread"><\/div>');
var s = d.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
}
else {
d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
}
})(window, document);
//--><!]]></script></div><div id="footer">
<p class="apache">Copyright 2023 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
if (typeof(prettyPrint) !== 'undefined') {
prettyPrint();
}
//--><!]]></script>
</body></html>
|
