2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_alias.xml.meta">
25 <name>mod_alias</name>
26 <description>Provides for mapping different parts of the host
27 filesystem in the document tree and for URL redirection</description>
29 <sourcefile>mod_alias.c</sourcefile>
30 <identifier>alias_module</identifier>
33 <p>The directives contained in this module allow for manipulation
34 and control of URLs as requests arrive at the server. The
35 <directive module="mod_alias">Alias</directive> and <directive
36 module="mod_alias">ScriptAlias</directive> directives are used to
37 map between URLs and filesystem paths. This allows for content
38 which is not directly under the <directive
39 module="core">DocumentRoot</directive> served as part of the web
40 document tree. The <directive
41 module="mod_alias">ScriptAlias</directive> directive has the
42 additional effect of marking the target directory as containing
45 <p>The <directive module="mod_alias">Redirect</directive>
46 directives are used to instruct clients to make a new request with
47 a different URL. They are often used when a resource has moved to
50 <p><module>mod_alias</module> is designed to handle simple URL
51 manipulation tasks. For more complicated tasks such as
52 manipulating the query string, use the tools provided by
53 <module>mod_rewrite</module>.</p>
57 <seealso><module>mod_rewrite</module></seealso> <seealso><a
58 href="../urlmapping.html">Mapping URLs to the filesystem</a></seealso>
60 <section id="order"><title>Order of Processing</title>
62 <p>Aliases and Redirects occurring in different contexts are processed
63 like other directives according to standard <a
64 href="../sections.html#mergin">merging rules</a>. But when multiple
65 Aliases or Redirects occur in the same context (for example, in the
66 same <directive type="section" module="core">VirtualHost</directive>
67 section) they are processed in a particular order.</p>
69 <p>First, all Redirects are processed before Aliases are processed,
70 and therefore a request that matches a <directive
71 module="mod_alias">Redirect</directive> or <directive
72 module="mod_alias">RedirectMatch</directive> will never have Aliases
73 applied. Second, the Aliases and Redirects are processed in the order
74 they appear in the configuration files, with the first match taking
77 <p>For this reason, when two or more of these directives apply to the
78 same sub-path, you must list the most specific path first in order for
79 all the directives to have an effect. For example, the following
80 configuration will work as expected:</p>
82 <highlight language="config">
87 <p>But if the above two directives were reversed in order, the
88 <code>/foo</code> <directive module="mod_alias">Alias</directive>
89 would always match before the <code>/foo/bar</code> <directive
90 module="mod_alias">Alias</directive>, so the latter directive would be
97 <description>Maps URLs to filesystem locations</description>
98 <syntax>Alias <var>URL-path</var>
99 <var>file-path</var>|<var>directory-path</var></syntax>
100 <contextlist><context>server config</context><context>virtual host</context>
105 <p>The <directive>Alias</directive> directive allows documents to
106 be stored in the local filesystem other than under the
107 <directive module="core">DocumentRoot</directive>. URLs with a
108 (%-decoded) path beginning with <var>URL-path</var> will be mapped
109 to local files beginning with <var>directory-path</var>. The
110 <var>URL-path</var> is case-sensitive, even on case-insensitive
113 <highlight language="config">
114 Alias /image /ftp/pub/image
117 <p>A request for <code>http://example.com/image/foo.gif</code> would cause
118 the server to return the file <code>/ftp/pub/image/foo.gif</code>. Only
119 complete path segments are matched, so the above alias would not match a
120 request for <code>http://example.com/imagefoo.gif</code>. For more complex
121 matching using regular expressions, see the <directive module="mod_alias"
122 >AliasMatch</directive> directive.</p>
124 <p>Note that if you include a trailing / on the
125 <var>URL-path</var> then the server will require a trailing / in
126 order to expand the alias. That is, if you use</p>
128 <dl><dd><code>Alias /icons/ /usr/local/apache/icons/</code></dd></dl>
130 <p>then the url <code>/icons</code> will not be aliased, as it lacks
131 that trailing /. Likewise, if you omit the slash on the
132 <var>URL-path</var> then you must also omit it from the
133 <var>file-path</var>.</p>
135 <p>Note that you may need to specify additional <directive
136 type="section" module="core">Directory</directive> sections which
137 cover the <em>destination</em> of aliases. Aliasing occurs before
138 <directive type="section" module="core">Directory</directive> sections
139 are checked, so only the destination of aliases are affected.
140 (Note however <directive type="section" module="core">Location</directive>
141 sections are run through once before aliases are performed, so
142 they will apply.)</p>
144 <p>In particular, if you are creating an <code>Alias</code> to a
145 directory outside of your <directive
146 module="core">DocumentRoot</directive>, you may need to explicitly
147 permit access to the target directory.</p>
149 <highlight language="config">
150 Alias /image /ftp/pub/image
151 <Directory /ftp/pub/image>
156 <p>Any number slashes in the <var>URL-path</var> parameter
157 matches any number of slashes in the requested URL-path.</p>
163 <name>AliasMatch</name>
164 <description>Maps URLs to filesystem locations using regular
165 expressions</description>
166 <syntax>AliasMatch <var>regex</var>
167 <var>file-path</var>|<var>directory-path</var></syntax>
168 <contextlist><context>server config</context><context>virtual host</context>
172 <p>This directive is equivalent to <directive
173 module="mod_alias">Alias</directive>, but makes use of
174 <glossary ref="regex">regular expressions</glossary>,
175 instead of simple prefix matching. The
176 supplied regular expression is matched against the URL-path, and
177 if it matches, the server will substitute any parenthesized
178 matches into the given string and use it as a filename. For
179 example, to activate the <code>/icons</code> directory, one might
182 <highlight language="config">
183 AliasMatch ^/icons(.*) /usr/local/apache/icons$1
186 <p>The full range of <glossary ref="regex">regular expression</glossary>
187 power is available. For example,
188 it is possible to construct an alias with case-insensitive
189 matching of the URL-path:</p>
191 <highlight language="config">
192 AliasMatch (?i)^/image(.*) /ftp/pub/image$1
195 <p>One subtle difference
196 between <directive module="mod_alias">Alias</directive>
197 and <directive module="mod_alias">AliasMatch</directive> is
198 that <directive module="mod_alias">Alias</directive> will
199 automatically copy any additional part of the URI, past the part
200 that matched, onto the end of the file path on the right side,
201 while <directive module="mod_alias">AliasMatch</directive> will
202 not. This means that in almost all cases, you will want the
203 regular expression to match the entire request URI from beginning
204 to end, and to use substitution on the right side.</p>
206 <p>In other words, just changing
207 <directive module="mod_alias">Alias</directive> to
208 <directive module="mod_alias">AliasMatch</directive> will not
209 have the same effect. At a minimum, you need to
210 add <code>^</code> to the beginning of the regular expression
211 and add <code>(.*)$</code> to the end, and add <code>$1</code> to
212 the end of the replacement.</p>
214 <p>For example, suppose you want to replace this with AliasMatch:</p>
216 <highlight language="config">
217 Alias /image/ /ftp/pub/image/
220 <p>This is NOT equivalent - don't do this! This will send all
221 requests that have /image/ anywhere in them to /ftp/pub/image/:</p>
223 <highlight language="config">
224 AliasMatch /image/ /ftp/pub/image/
227 <p>This is what you need to get the same effect:</p>
229 <highlight language="config">
230 AliasMatch ^/image/(.*)$ /ftp/pub/image/$1
233 <p>Of course, there's no point in
234 using <directive module="mod_alias">AliasMatch</directive>
235 where <directive module="mod_alias">Alias</directive> would
236 work. <directive module="mod_alias">AliasMatch</directive> lets
237 you do more complicated things. For example, you could
238 serve different kinds of files from different directories:</p>
240 <highlight language="config">
241 AliasMatch ^/image/(.*)\.jpg$ /files/jpg.images/$1.jpg<br/>
242 AliasMatch ^/image/(.*)\.gif$ /files/gif.images/$1.gif
245 <p>Multiple leading slashes in the requested URL are discarded
246 by the server before directives from this module compares
247 against the requested URL-path.
254 <name>Redirect</name>
255 <description>Sends an external redirect asking the client to fetch
256 a different URL</description>
257 <syntax>Redirect [<var>status</var>] <var>URL-path</var>
258 <var>URL</var></syntax>
259 <contextlist><context>server config</context><context>virtual host</context>
260 <context>directory</context><context>.htaccess</context></contextlist>
261 <override>FileInfo</override>
264 <p>The Redirect directive maps an old URL into a new one by asking
265 the client to refetch the resource at the new location.</p>
267 <p>The old <em>URL-path</em> is a case-sensitive (%-decoded) path
268 beginning with a slash. A relative path is not allowed.</p>
270 <p>The new <em>URL</em> may be either an absolute URL beginning
271 with a scheme and hostname, or a URL-path beginning with a slash.
272 In this latter case the scheme and hostname of the current server will
275 <p>Then any request beginning with <em>URL-Path</em> will return a
276 redirect request to the client at the location of the target
277 <em>URL</em>. Additional path information beyond the matched
278 <em>URL-Path</em> will be appended to the target URL.</p>
280 <highlight language="config">
281 # Redirect to a URL on a different host
282 Redirect /service http://foo2.example.com/service
284 # Redirect to a URL on the same host
288 <p>If the client requests <code>http://example.com/service/foo.txt</code>,
289 it will be told to access
290 <code>http://foo2.example.com/service/foo.txt</code>
291 instead. This includes requests with <code>GET</code> parameters, such as
292 <code>http://example.com/service/foo.pl?q=23&a=42</code>,
293 it will be redirected to
294 <code>http://foo2.example.com/service/foo.pl?q=23&a=42</code>.
295 Note that <code>POST</code>s will be discarded.<br />
296 Only complete path segments are matched, so the above
297 example would not match a request for
298 <code>http://example.com/servicefoo.txt</code>. For more complex matching
299 using regular expressions, see the <directive
300 module="mod_alias">RedirectMatch</directive> directive.</p>
303 <note><title>Note</title>
304 <p>Redirect directives take precedence over Alias and ScriptAlias
305 directives, irrespective of their ordering in the configuration
308 <p>If no <var>status</var> argument is given, the redirect will
309 be "temporary" (HTTP status 302). This indicates to the client
310 that the resource has moved temporarily. The <var>status</var>
311 argument can be used to return other HTTP status codes:</p>
316 <dd>Returns a permanent redirect status (301) indicating that
317 the resource has moved permanently.</dd>
321 <dd>Returns a temporary redirect status (302). This is the
326 <dd>Returns a "See Other" status (303) indicating that the
327 resource has been replaced.</dd>
331 <dd>Returns a "Gone" status (410) indicating that the
332 resource has been permanently removed. When this status is
333 used the <var>URL</var> argument should be omitted.</dd>
336 <p>Other status codes can be returned by giving the numeric
337 status code as the value of <var>status</var>. If the status is
338 between 300 and 399, the <var>URL</var> argument must be present.
339 If the status is <em>not</em> between 300 and 399, the
340 <var>URL</var> argument must be omitted. The status must be a valid
341 HTTP status code, known to the Apache HTTP Server (see the function
342 <code>send_error_response</code> in http_protocol.c).</p>
344 <highlight language="config">
345 Redirect permanent /one http://example.com/two
346 Redirect 303 /three http://example.com/other
353 <name>RedirectMatch</name>
354 <description>Sends an external redirect based on a regular expression match
355 of the current URL</description>
356 <syntax>RedirectMatch [<var>status</var>] <var>regex</var>
357 <var>URL</var></syntax>
358 <contextlist><context>server config</context><context>virtual host</context>
359 <context>directory</context><context>.htaccess</context></contextlist>
360 <override>FileInfo</override>
363 <p>This directive is equivalent to <directive
364 module="mod_alias">Redirect</directive>, but makes use of
365 <glossary ref="regex">regular expressions</glossary>,
366 instead of simple prefix matching. The
367 supplied regular expression is matched against the URL-path, and
368 if it matches, the server will substitute any parenthesized
369 matches into the given string and use it as a filename. For
370 example, to redirect all GIF files to like-named JPEG files on
371 another server, one might use:</p>
373 <highlight language="config">
374 RedirectMatch (.*)\.gif$ http://other.example.com$1.jpg
377 <p>The considerations related to the difference between
378 <directive module="mod_alias">Alias</directive> and
379 <directive module="mod_alias">AliasMatch</directive>
380 also apply to the difference between
381 <directive module="mod_alias">Redirect</directive> and
382 <directive module="mod_alias">RedirectMatch</directive>.
383 See <directive module="mod_alias">AliasMatch</directive> for
391 <name>RedirectTemp</name>
392 <description>Sends an external temporary redirect asking the client to fetch
393 a different URL</description>
394 <syntax>RedirectTemp <var>URL-path</var> <var>URL</var></syntax>
395 <contextlist><context>server config</context><context>virtual host</context>
396 <context>directory</context><context>.htaccess</context></contextlist>
397 <override>FileInfo</override>
400 <p>This directive makes the client know that the Redirect is
401 only temporary (status 302). Exactly equivalent to
402 <code>Redirect temp</code>.</p>
407 <name>RedirectPermanent</name>
408 <description>Sends an external permanent redirect asking the client to fetch
409 a different URL</description>
410 <syntax>RedirectPermanent <var>URL-path</var> <var>URL</var></syntax>
411 <contextlist><context>server config</context><context>virtual host</context>
412 <context>directory</context><context>.htaccess</context></contextlist>
413 <override>FileInfo</override>
416 <p>This directive makes the client know that the Redirect is
417 permanent (status 301). Exactly equivalent to <code>Redirect
418 permanent</code>.</p>
423 <name>ScriptAlias</name>
424 <description>Maps a URL to a filesystem location and designates the
425 target as a CGI script</description>
426 <syntax>ScriptAlias <var>URL-path</var>
427 <var>file-path</var>|<var>directory-path</var></syntax>
428 <contextlist><context>server config</context><context>virtual host</context>
432 <p>The <directive>ScriptAlias</directive> directive has the same
433 behavior as the <directive module="mod_alias">Alias</directive>
434 directive, except that in addition it marks the target directory
435 as containing CGI scripts that will be processed by <module
436 >mod_cgi</module>'s cgi-script handler. URLs with a case-sensitive
437 (%-decoded) path beginning with <var>URL-path</var> will be mapped
438 to scripts beginning with the second argument, which is a full
439 pathname in the local filesystem.</p>
441 <highlight language="config">
442 ScriptAlias /cgi-bin/ /web/cgi-bin/
445 <p>A request for <code>http://example.com/cgi-bin/foo</code> would cause the
446 server to run the script <code>/web/cgi-bin/foo</code>. This configuration
447 is essentially equivalent to:</p>
448 <highlight language="config">
449 Alias /cgi-bin/ /web/cgi-bin/
450 <Location /cgi-bin >
451 SetHandler cgi-script
456 <p><directive>ScriptAlias</directive> can also be used in conjunction with
457 a script or handler you have. For example:</p>
459 <highlight language="config">
460 ScriptAlias /cgi-bin/ /web/cgi-handler.pl
463 <p>In this scenario all files requested in <code>/cgi-bin/</code> will be
464 handled by the file you have configured, this allows you to use your own custom
465 handler. You may want to use this as a wrapper for CGI so that you can add
466 content, or some other bespoke action.</p>
468 <note type="warning">It is safer to avoid placing CGI scripts under the
469 <directive module="core">DocumentRoot</directive> in order to
470 avoid accidentally revealing their source code if the
471 configuration is ever changed. The
472 <directive>ScriptAlias</directive> makes this easy by mapping a
473 URL and designating CGI scripts at the same time. If you do
474 choose to place your CGI scripts in a directory already
475 accessible from the web, do not use
476 <directive>ScriptAlias</directive>. Instead, use <directive
477 module="core" type="section">Directory</directive>, <directive
478 module="core">SetHandler</directive>, and <directive
479 module="core">Options</directive> as in:
480 <highlight language="config">
481 <Directory /usr/local/apache2/htdocs/cgi-bin >
482 SetHandler cgi-script
486 This is necessary since multiple <var>URL-paths</var> can map
487 to the same filesystem location, potentially bypassing the
488 <directive>ScriptAlias</directive> and revealing the source code
489 of the CGI scripts if they are not restricted by a
490 <directive module="core">Directory</directive> section.</note>
493 <seealso><a href="../howto/cgi.html">CGI Tutorial</a></seealso>
497 <name>ScriptAliasMatch</name>
498 <description>Maps a URL to a filesystem location using a regular expression
499 and designates the target as a CGI script</description>
500 <syntax>ScriptAliasMatch <var>regex</var>
501 <var>file-path</var>|<var>directory-path</var></syntax>
502 <contextlist><context>server config</context><context>virtual host</context>
506 <p>This directive is equivalent to <directive module="mod_alias"
507 >ScriptAlias</directive>, but makes use of
508 <glossary ref="regex">regular expressions</glossary>,
509 instead of simple prefix matching. The
510 supplied regular expression is matched against the URL-path,
511 and if it matches, the server will substitute any parenthesized
512 matches into the given string and use it as a filename. For
513 example, to activate the standard <code>/cgi-bin</code>, one
516 <highlight language="config">
517 ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
520 <p>As for AliasMatch, the full range of <glossary ref="rexex">regular
521 expression</glossary> power is available.
522 For example, it is possible to construct an alias with case-insensitive
523 matching of the URL-path:</p>
525 <highlight language="config">
526 ScriptAliasMatch (?i)^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
529 <p>The considerations related to the difference between
530 <directive module="mod_alias">Alias</directive> and
531 <directive module="mod_alias">AliasMatch</directive>
532 also apply to the difference between
533 <directive module="mod_alias">ScriptAlias</directive> and
534 <directive module="mod_alias">ScriptAliasMatch</directive>.
535 See <directive module="mod_alias">AliasMatch</directive> for