0a146bb31945dd13e6f7ad35818f6842ec91ff53nd<?xml version="1.0"?>

0a146bb31945dd13e6f7ad35818f6842ec91ff53nd<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

0a146bb31945dd13e6f7ad35818f6842ec91ff53nd<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

0a146bb31945dd13e6f7ad35818f6842ec91ff53nd

ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd<modulesynopsis metafile="mod_alias.xml.meta">

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd

0a146bb31945dd13e6f7ad35818f6842ec91ff53nd<name>mod_alias</name>

0a146bb31945dd13e6f7ad35818f6842ec91ff53nd<description>Provides for mapping different parts of the host

bcb3a46ccb6553019068f7bb2a7ac8548a3f72cfslive filesystem in the document tree and for URL redirection</description>

bcb3a46ccb6553019068f7bb2a7ac8548a3f72cfslive<status>Base</status>

bcb3a46ccb6553019068f7bb2a7ac8548a3f72cfslive<sourcefile>mod_alias.c</sourcefile>

5a58787efeb02a1c3f06569d019ad81fd2efa06end<identifier>alias_module</identifier>

5a58787efeb02a1c3f06569d019ad81fd2efa06end

5a58787efeb02a1c3f06569d019ad81fd2efa06end<summary>

5a58787efeb02a1c3f06569d019ad81fd2efa06end <p>The directives contained in this module allow for manipulation

5a58787efeb02a1c3f06569d019ad81fd2efa06end and control of URLs as requests arrive at the server. The

5a58787efeb02a1c3f06569d019ad81fd2efa06end <directive module="mod_alias">Alias</directive> and <directive

5a58787efeb02a1c3f06569d019ad81fd2efa06end module="mod_alias">ScriptAlias</directive> directives are used to

bcb3a46ccb6553019068f7bb2a7ac8548a3f72cfslive map between URLs and filesystem paths. This allows for content

bcb3a46ccb6553019068f7bb2a7ac8548a3f72cfslive which is not directly under the <directive

bcb3a46ccb6553019068f7bb2a7ac8548a3f72cfslive module="core">DocumentRoot</directive> served as part of the web

bcb3a46ccb6553019068f7bb2a7ac8548a3f72cfslive document tree. The <directive

bcb3a46ccb6553019068f7bb2a7ac8548a3f72cfslive module="mod_alias">ScriptAlias</directive> directive has the

3a5c8a7c39f03520463a70cf3f90091dc3a1eb32nd additional effect of marking the target directory as containing

bcb3a46ccb6553019068f7bb2a7ac8548a3f72cfslive only CGI scripts.</p>

5a58787efeb02a1c3f06569d019ad81fd2efa06end

5a58787efeb02a1c3f06569d019ad81fd2efa06end <p>The <directive module="mod_alias">Redirect</directive>

5a58787efeb02a1c3f06569d019ad81fd2efa06end directives are used to instruct clients to make a new request with

bcb3a46ccb6553019068f7bb2a7ac8548a3f72cfslive a different URL. They are often used when a resource has moved to

0a146bb31945dd13e6f7ad35818f6842ec91ff53nd a new location.</p>

0a146bb31945dd13e6f7ad35818f6842ec91ff53nd

5a58787efeb02a1c3f06569d019ad81fd2efa06end <p><module>mod_alias</module> is designed to handle simple URL

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd manipulation tasks. For more complicated tasks such as

ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd manipulating the query string, use the tools provided by

ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd <module>mod_rewrite</module>.</p>

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd

b95ae799514ad86a15610ad75808d7065e9847c9kess</summary>

5a58787efeb02a1c3f06569d019ad81fd2efa06end

5a58787efeb02a1c3f06569d019ad81fd2efa06end<seealso><module>mod_rewrite</module></seealso> <seealso><a

href="/urlmapping.html">Mapping URLs to the filesystem</a></seealso>

<section id="order"><title>Order of Processing</title>

<p>Aliases and Redirects occurring in different contexts are processed

like other directives according to standard <a

href="/sections.html#mergin">merging rules</a>. But when multiple

Aliases or Redirects occur in the same context (for example, in the

same <directive type="section" module="core">VirtualHost</directive>

section) they are processed in a particular order.</p>

<p>First, all Redirects are processed before Aliases are processed,

and therefore a request that matches a <directive

module="mod_alias">Redirect</directive> or <directive

module="mod_alias">RedirectMatch</directive> will never have Aliases

applied. Second, the Aliases and Redirects are processed in the order

they appear in the configuration files, with the first match taking

precedence.</p>

<p>For this reason, when two or more of these directives apply to the

same sub-path, you must list the most specific path first in order for

all the directives to have an effect. For example, the following

configuration will work as expected:</p>

<highlight language="config">

Alias /foo/bar /baz

Alias /foo /gaq

</highlight>

<p>But if the above two directives were reversed in order, the

<code>/foo</code> <directive module="mod_alias">Alias</directive>

would always match before the <code>/foo/bar</code> <directive

module="mod_alias">Alias</directive>, so the latter directive would be

ignored.</p>

</section>

<directivesynopsis>

<name>Alias</name>

<description>Maps URLs to filesystem locations</description>

<syntax>Alias <var>URL-path</var>

<var>file-path</var>|<var>directory-path</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

<p>The <directive>Alias</directive> directive allows documents to

be stored in the local filesystem other than under the

<directive module="core">DocumentRoot</directive>. URLs with a

(%-decoded) path beginning with <var>URL-path</var> will be mapped

to local files beginning with <var>directory-path</var>. The

<var>URL-path</var> is case-sensitive, even on case-insensitive

file systems.</p>

<highlight language="config">

Alias /image /ftp/pub/image

</highlight>

<p>A request for <code>http://example.com/image/foo.gif</code> would cause

the server to return the file <code>/ftp/pub/image/foo.gif</code>. Only

complete path segments are matched, so the above alias would not match a

request for <code>http://example.com/imagefoo.gif</code>. For more complex

matching using regular expressions, see the <directive module="mod_alias"

>AliasMatch</directive> directive.</p>

<p>Note that if you include a trailing / on the

<var>URL-path</var> then the server will require a trailing / in

order to expand the alias. That is, if you use</p>

<dl><dd><code>Alias /icons/ /usr/local/apache/icons/</code></dd></dl>

<p>then the url <code>/icons</code> will not be aliased, as it lacks

that trailing /. Likewise, if you omit the slash on the

<var>URL-path</var> then you must also omit it from the

<var>file-path</var>.</p>

<p>Note that you may need to specify additional <directive

type="section" module="core">Directory</directive> sections which

cover the <em>destination</em> of aliases. Aliasing occurs before

<directive type="section" module="core">Directory</directive> sections

are checked, so only the destination of aliases are affected.

(Note however <directive type="section" module="core">Location</directive>

sections are run through once before aliases are performed, so

they will apply.)</p>

<p>In particular, if you are creating an <code>Alias</code> to a

directory outside of your <directive

module="core">DocumentRoot</directive>, you may need to explicitly

permit access to the target directory.</p>

<highlight language="config">

Alias /image /ftp/pub/image

&lt;Directory /ftp/pub/image&gt;

Require all granted

&lt;/Directory&gt;

</highlight>

<p>Any number of leading slashes in the <var>URL-path</var> parameter

matches any number of leading slashes in the requested URL-path.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AliasMatch</name>

<description>Maps URLs to filesystem locations using regular

expressions</description>

<syntax>AliasMatch <var>regex</var>

<var>file-path</var>|<var>directory-path</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

<p>This directive is equivalent to <directive

module="mod_alias">Alias</directive>, but makes use of

<glossary ref="regex">regular expressions</glossary>,

instead of simple prefix matching. The

supplied regular expression is matched against the URL-path, and

if it matches, the server will substitute any parenthesized

matches into the given string and use it as a filename. For

example, to activate the <code>/icons</code> directory, one might

use:</p>

<highlight language="config">

AliasMatch ^/icons(.*) /usr/local/apache/icons$1

</highlight>

<p>The full range of <glossary ref="regex">regular expression</glossary>

power is available. For example,

it is possible to construct an alias with case-insensitive

matching of the URL-path:</p>

<highlight language="config">

AliasMatch (?i)^/image(.*) /ftp/pub/image$1

</highlight>

<p>One subtle difference

between <directive module="mod_alias">Alias</directive>

and <directive module="mod_alias">AliasMatch</directive> is

that <directive module="mod_alias">Alias</directive> will

automatically copy any additional part of the URI, past the part

that matched, onto the end of the file path on the right side,

while <directive module="mod_alias">AliasMatch</directive> will

not. This means that in almost all cases, you will want the

regular expression to match the entire request URI from beginning

to end, and to use substitution on the right side.</p>

<p>In other words, just changing

<directive module="mod_alias">Alias</directive> to

<directive module="mod_alias">AliasMatch</directive> will not

have the same effect. At a minimum, you need to

add <code>^</code> to the beginning of the regular expression

and add <code>(.*)$</code> to the end, and add <code>$1</code> to

the end of the replacement.</p>

<p>For example, suppose you want to replace this with AliasMatch:</p>

<highlight language="config">

Alias /image/ /ftp/pub/image/

</highlight>

<p>This is NOT equivalent - don't do this! This will send all

requests that have /image/ anywhere in them to /ftp/pub/image/:</p>

<highlight language="config">

AliasMatch /image/ /ftp/pub/image/

</highlight>

<p>This is what you need to get the same effect:</p>

<highlight language="config">

AliasMatch ^/image/(.*)$ /ftp/pub/image/$1

</highlight>

<p>Of course, there's no point in

using <directive module="mod_alias">AliasMatch</directive>

where <directive module="mod_alias">Alias</directive> would

work. <directive module="mod_alias">AliasMatch</directive> lets

you do more complicated things. For example, you could

serve different kinds of files from different directories:</p>

<highlight language="config">

AliasMatch ^/image/(.*)\.jpg$ /files/jpg.images/$1.jpg<br/>

AliasMatch ^/image/(.*)\.gif$ /files/gif.images/$1.gif

</highlight>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>Redirect</name>

<description>Sends an external redirect asking the client to fetch

a different URL</description>

<syntax>Redirect [<var>status</var>] <var>URL-path</var>

<var>URL</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context></contextlist>

<override>FileInfo</override>

<usage>

<p>The Redirect directive maps an old URL into a new one by asking

the client to refetch the resource at the new location.</p>

<p>The old <em>URL-path</em> is a case-sensitive (%-decoded) path

beginning with a slash. A relative path is not allowed.</p>

<p>The new <em>URL</em> may be either an absolute URL beginning

with a scheme and hostname, or a URL-path beginning with a slash.

In this latter case the scheme and hostname of the current server will

be added.</p>

<p>Then any request beginning with <em>URL-Path</em> will return a

redirect request to the client at the location of the target

<em>URL</em>. Additional path information beyond the matched

<em>URL-Path</em> will be appended to the target URL.</p>

<highlight language="config">

# Redirect to a URL on a different host

Redirect /service http://foo2.example.com/service

# Redirect to a URL on the same host

Redirect /one /two

</highlight>

<p>If the client requests <code>http://example.com/service/foo.txt</code>,

it will be told to access

<code>http://foo2.example.com/service/foo.txt</code>

instead. This includes requests with <code>GET</code> parameters, such as

<code>http://example.com/service/foo.pl?q=23&amp;a=42</code>,

it will be redirected to

<code>http://foo2.example.com/service/foo.pl?q=23&amp;a=42</code>.

Note that <code>POST</code>s will be discarded.<br />

Only complete path segments are matched, so the above

example would not match a request for

<code>http://example.com/servicefoo.txt</code>. For more complex matching

using regular expressions, see the <directive

module="mod_alias">RedirectMatch</directive> directive.</p>

<note><title>Note</title>

<p>Redirect directives take precedence over Alias and ScriptAlias

directives, irrespective of their ordering in the configuration

file.</p></note>

<p>If no <var>status</var> argument is given, the redirect will

be "temporary" (HTTP status 302). This indicates to the client

that the resource has moved temporarily. The <var>status</var>

argument can be used to return other HTTP status codes:</p>

<dl>

<dt>permanent</dt>

<dd>Returns a permanent redirect status (301) indicating that

the resource has moved permanently.</dd>

<dt>temp</dt>

<dd>Returns a temporary redirect status (302). This is the

default.</dd>

<dt>seeother</dt>

<dd>Returns a "See Other" status (303) indicating that the

resource has been replaced.</dd>

<dt>gone</dt>

<dd>Returns a "Gone" status (410) indicating that the

resource has been permanently removed. When this status is

used the <var>URL</var> argument should be omitted.</dd>

</dl>

<p>Other status codes can be returned by giving the numeric

status code as the value of <var>status</var>. If the status is

between 300 and 399, the <var>URL</var> argument must be present.

If the status is <em>not</em> between 300 and 399, the

<var>URL</var> argument must be omitted. The status must be a valid

HTTP status code, known to the Apache HTTP Server (see the function

<code>send_error_response</code> in http_protocol.c).</p>

<highlight language="config">

Redirect permanent /one http://example.com/two

Redirect 303 /three http://example.com/other

</highlight>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>RedirectMatch</name>

<description>Sends an external redirect based on a regular expression match

of the current URL</description>

<syntax>RedirectMatch [<var>status</var>] <var>regex</var>

<var>URL</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context></contextlist>

<override>FileInfo</override>

<usage>

<p>This directive is equivalent to <directive

module="mod_alias">Redirect</directive>, but makes use of

<glossary ref="regex">regular expressions</glossary>,

instead of simple prefix matching. The

supplied regular expression is matched against the URL-path, and

if it matches, the server will substitute any parenthesized

matches into the given string and use it as a filename. For

example, to redirect all GIF files to like-named JPEG files on

another server, one might use:</p>

<highlight language="config">

RedirectMatch (.*)\.gif$ http://other.example.com$1.jpg

</highlight>

<p>The considerations related to the difference between

<directive module="mod_alias">Alias</directive> and

<directive module="mod_alias">AliasMatch</directive>

also apply to the difference between

<directive module="mod_alias">Redirect</directive> and

<directive module="mod_alias">RedirectMatch</directive>.

See <directive module="mod_alias">AliasMatch</directive> for

details.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>RedirectTemp</name>

<description>Sends an external temporary redirect asking the client to fetch

a different URL</description>

<syntax>RedirectTemp <var>URL-path</var> <var>URL</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context></contextlist>

<override>FileInfo</override>

<usage>

<p>This directive makes the client know that the Redirect is

only temporary (status 302). Exactly equivalent to

<code>Redirect temp</code>.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>RedirectPermanent</name>

<description>Sends an external permanent redirect asking the client to fetch

a different URL</description>

<syntax>RedirectPermanent <var>URL-path</var> <var>URL</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

<context>directory</context><context>.htaccess</context></contextlist>

<override>FileInfo</override>

<usage>

<p>This directive makes the client know that the Redirect is

permanent (status 301). Exactly equivalent to <code>Redirect

permanent</code>.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>ScriptAlias</name>

<description>Maps a URL to a filesystem location and designates the

target as a CGI script</description>

<syntax>ScriptAlias <var>URL-path</var>

<var>file-path</var>|<var>directory-path</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

<p>The <directive>ScriptAlias</directive> directive has the same

behavior as the <directive module="mod_alias">Alias</directive>

directive, except that in addition it marks the target directory

as containing CGI scripts that will be processed by <module

>mod_cgi</module>'s cgi-script handler. URLs with a case-sensitive

(%-decoded) path beginning with <var>URL-path</var> will be mapped

to scripts beginning with the second argument, which is a full

pathname in the local filesystem.</p>

<highlight language="config">

ScriptAlias /cgi-bin/ /web/cgi-bin/

</highlight>

<p>A request for <code>http://example.com/cgi-bin/foo</code> would cause the

server to run the script <code>/web/cgi-bin/foo</code>. This configuration

is essentially equivalent to:</p>

<highlight language="config">

Alias /cgi-bin/ /web/cgi-bin/

&lt;Location /cgi-bin &gt;

SetHandler cgi-script

Options +ExecCGI

&lt;/Location&gt;

</highlight>

<p><directive>ScriptAlias</directive> can also be used in conjunction with

a script or handler you have. For example:</p>

<highlight language="config">

ScriptAlias /cgi-bin/ /web/cgi-handler.pl

</highlight>

<p>In this scenario all files requested in <code>/cgi-bin/</code> will be

handled by the file you have configured, this allows you to use your own custom

handler. You may want to use this as a wrapper for CGI so that you can add

content, or some other bespoke action.</p>

<note type="warning">It is safer to avoid placing CGI scripts under the

<directive module="core">DocumentRoot</directive> in order to

avoid accidentally revealing their source code if the

configuration is ever changed. The

<directive>ScriptAlias</directive> makes this easy by mapping a

URL and designating CGI scripts at the same time. If you do

choose to place your CGI scripts in a directory already

accessible from the web, do not use

<directive>ScriptAlias</directive>. Instead, use <directive

module="core" type="section">Directory</directive>, <directive

module="core">SetHandler</directive>, and <directive

module="core">Options</directive> as in:

<highlight language="config">

&lt;Directory /usr/local/apache2/htdocs/cgi-bin &gt;

SetHandler cgi-script

Options ExecCGI

&lt;/Directory&gt;

</highlight>

This is necessary since multiple <var>URL-paths</var> can map

to the same filesystem location, potentially bypassing the

<directive>ScriptAlias</directive> and revealing the source code

of the CGI scripts if they are not restricted by a

<directive module="core">Directory</directive> section.</note>

</usage>

<seealso><a href="/howto/cgi.html">CGI Tutorial</a></seealso>

</directivesynopsis>

<directivesynopsis>

<name>ScriptAliasMatch</name>

<description>Maps a URL to a filesystem location using a regular expression

and designates the target as a CGI script</description>

<syntax>ScriptAliasMatch <var>regex</var>

<var>file-path</var>|<var>directory-path</var></syntax>

<contextlist><context>server config</context><context>virtual host</context>

</contextlist>

<usage>

<p>This directive is equivalent to <directive module="mod_alias"

>ScriptAlias</directive>, but makes use of

<glossary ref="regex">regular expressions</glossary>,

instead of simple prefix matching. The

supplied regular expression is matched against the URL-path,

and if it matches, the server will substitute any parenthesized

matches into the given string and use it as a filename. For

example, to activate the standard <code>/cgi-bin</code>, one

might use:</p>

<highlight language="config">

ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1

</highlight>

<p>As for AliasMatch, the full range of <glossary ref="rexex">regular

expression</glossary> power is available.

For example, it is possible to construct an alias with case-insensitive

matching of the URL-path:</p>

<highlight language="config">

ScriptAliasMatch (?i)^/cgi-bin(.*) /usr/local/apache/cgi-bin$1

</highlight>

<p>The considerations related to the difference between

<directive module="mod_alias">Alias</directive> and

<directive module="mod_alias">AliasMatch</directive>

also apply to the difference between

<directive module="mod_alias">ScriptAlias</directive> and

<directive module="mod_alias">ScriptAliasMatch</directive>.

See <directive module="mod_alias">AliasMatch</directive> for

details.</p>

</usage>

</directivesynopsis>

</modulesynopsis>