<?xml version="1.0"?>

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

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

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

<name>mod_alias</name>

<description>Provides for mapping different parts of the host

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

<status>Base</status>

<sourcefile>mod_alias.c</sourcefile>

<identifier>alias_module</identifier>

<summary>

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

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

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

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

map between URLs and filesystem paths. This allows for content

which is not directly under the <directive

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

document tree. The <directive

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

additional effect of marking the target directory as containing

only CGI scripts.</p>

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

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

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

a new location.</p>

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

manipulation tasks. For more complicated tasks such as

manipulating the query string, use the tools provided by

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

</summary>

<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 occuring 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>

<example>

Alias /foo/bar /baz<br />

Alias /foo /gaq

</example>

<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>

<example><title>Example:</title>

Alias /image /ftp/pub/image

</example>

<p>A request for <code>http://myserver/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://myserver/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.</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>

<example><title>Example:</title>

Alias /image /ftp/pub/image<br />

&lt;Directory /ftp/pub/image&gt;<br />

<indent>

Order allow,deny<br />

Allow from all<br />

</indent>

&lt;/Directory&gt;

</example>

</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>

<example>

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

</example>

<p>It is also possible to construct an alias with case-insensitive

matching of the url-path:</p>

<example>

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

</example>

</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. The new

<em>URL</em> should be an absolute URL beginning with a scheme and

hostname, but a URL-path beginning with a slash may also be used,

in which 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>

<example><title>Example:</title>

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

</example>

<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. 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,

otherwise it must be omitted. Note that the status must be

known to the Apache code (see the function

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

<example><title>Example:</title>

Redirect permanent /one http://example.com/two<br />

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

</example>

</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>

<example>

RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg

</example>

</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>

<example><title>Example:</title>

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

</example>

<p>A request for <code>http://myserver/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>

<example>

Alias /cgi-bin/ /web/cgi-bin/<br />

&lt;Location /cgi-bin &gt;<br />

<indent>

SetHandler cgi-script<br />

Options +ExecCGI<br />

</indent>

&lt;/Location&gt;

</example>

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

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

<example>

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

</example>

<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:

<example>

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

<indent>

SetHandler cgi-script<br />

Options ExecCGI<br />

</indent>

&lt;/Directory&gt;

</example>

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>

<example>

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

</example>

</usage>

</directivesynopsis>

</modulesynopsis>