mod_alias.html revision 19571734da8573ce05afdaf0d33e67b41400215d
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE>Apache module mod_alias</TITLE>
</HEAD>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>
<!--#include virtual="header.html" -->
<H1 ALIGN="CENTER">Module mod_alias</H1>
<P>
This module provides for mapping different parts of the
host filesystem in the document tree, and for URL redirection.
</P>
<P><A
HREF="module-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Base
<BR>
<A
HREF="module-dict.html#SourceFile"
REL="Help"
><STRONG>Source File:</STRONG></A> mod_alias.c
<BR>
<A
HREF="module-dict.html#ModuleIdentifier"
REL="Help"
><STRONG>Module Identifier:</STRONG></A> alias_module
</P>
<H2>Summary</H2>
<P>The directives contained in this module allow for manipulation and
control of URLs as requests arrive at the server. The
<CODE>Alias</CODE> and <CODE>ScriptAlias</CODE> directives are used to
map between URLs and filesystem paths. This allows for content which
is not directly under the <A
HREF="core.html#documentroot"><CODE>DocumentRoot</CODE></A> to be
served as part of the web document tree. The <CODE>ScriptAlias</CODE>
directive has the additional effect of marking the target directory as
containing only CGI scripts.
<P>The <CODE>Redirect</CODE> 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>A more powerful and flexible set of directives for manipulating
URLs is contained in the <A
HREF="mod_rewrite.html"><CODE>mod_rewrite</CODE></A> module.
<H2>Directives</H2>
<UL>
<LI><A HREF="#alias">Alias</A>
<LI><A HREF="#aliasmatch">AliasMatch</A>
<LI><A HREF="#redirect">Redirect</A>
<LI><A HREF="#redirectmatch">RedirectMatch</A>
<LI><A HREF="#redirecttemp">RedirectTemp</A>
<LI><A HREF="#redirectperm">RedirectPermanent</A>
<LI><A HREF="#scriptalias">ScriptAlias</A>
<LI><A HREF="#scriptaliasmatch">ScriptAliasMatch</A>
</UL>
<HR>
<H2><A NAME="alias">Alias directive</A></H2>
<P>
<!--%plaintext &lt;?INDEX {\tt Alias} directive&gt; -->
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A> Alias <EM>URL-path file-path</em>|<em>directory-path</EM><BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> server config, virtual host<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Base<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_alias
</P>
<P>
The Alias directive allows documents to be stored in the local filesystem
other than under the <A HREF="core.html#documentroot">DocumentRoot</A>.
URLs with a (%-decoded) path beginning with <EM>url-path</EM> will be
mapped to local files beginning with <EM>directory-filename</EM>.
<P>
Example:
</P>
<BLOCKQUOTE><CODE>Alias /image /ftp/pub/image</CODE></BLOCKQUOTE>
<P>
A request for http://myserver/image/foo.gif would cause the server to
return the file /ftp/pub/image/foo.gif.
</P>
<P>
Note that if you include a trailing / on the <EM>url-path</EM> then the
server will require a trailing / in order to expand the alias. That is,
if you use <CODE>Alias /icons/ /usr/local/apache/icons/</CODE> then
the url <CODE>/icons</CODE> will not be aliased.
</P>
<P>
Note that you may need to specify additional
<A HREF="core.html#directory"><CODE>&lt;Directory&gt;</CODE></A> sections
which cover the <EM>destination</EM> of aliases. Aliasing occurs
before <CODE>&lt;Directory&gt;</CODE> sections are checked, so only
the destination of aliases are affected. (Note however
<A HREF="core.html#location"><CODE>&lt;Location&gt;</CODE></A>
sections are run through once before aliases are performed, so they
will apply.)
<P>
See also <A HREF="#scriptalias">ScriptAlias</A>.
</P>
<HR>
<H2><A NAME="aliasmatch">AliasMatch</A></H2>
<P>
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A> AliasMatch <EM>regex file-path</em>|<em>directory-path</EM><BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> server config, virtual host<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Base<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_alias
</P>
<P>This directive is equivalent to <A HREF="#alias">Alias</A>, but
makes use of standard regular expressions, 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:
<PRE>
AliasMatch ^/icons(.*) /usr/local/apache/icons$1
</PRE>
</P>
<HR>
<H2><A NAME="redirect">Redirect directive</A></H2>
<P>
<!--%plaintext &lt;?INDEX {\tt Redirect} directive&gt; -->
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A> Redirect [<EM>status</EM>]
<EM>URL-path URL</EM><BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> server config, virtual host, directory,
.htaccess<BR>
<A
HREF="directive-dict.html#Override"
REL="Help"
><STRONG>Override:</STRONG></A> FileInfo<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Base<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_alias
</P>
<P>
The Redirect directive maps an old URL into a new one. The new URL is returned
to the client which attempts to fetch it again with the new address.
<EM>URL-path</EM> a (%-decoded) path; any requests for documents beginning with
this path will be returned a redirect error to a new (%-encoded) URL
beginning with <EM>URL</EM>.
</P>
<P>
Example:
</P>
<BLOCKQUOTE><CODE>Redirect /service
http://foo2.bar.com/service</CODE></BLOCKQUOTE>
<P>
If the client requests http://myserver/service/foo.txt, it will be told to
access http://foo2.bar.com/service/foo.txt instead.
</P>
<P>
<STRONG>Note:</STRONG> Redirect directives take precedence over Alias
and ScriptAlias
directives, irrespective of their ordering in the configuration file. Also,
<EM>URL-path</EM> must be an absolute path, not a relative path, even
when used with .htaccess files or inside of &lt;Directory&gt; sections.
</P>
<P>
If no <EM>status</EM> argument is given, the redirect will be
&quot;temporary&quot; (HTTP status 302). This indicates to the client that the
resource has moved temporarily. The <EM>status</EM>
argument can be used to return other HTTP status codes:
<P>
<DL>
<DT>permanent
<DD>Returns a permanent redirect status (301) indicating that
the resource has moved permanently.
<DT>temp
<DD>Returns a temporary redirect status (302). This is the
default.
<DT>seeother
<DD>Returns a "See Other" status (303) indicating that
the resource has been replaced.
<DT>gone
<DD>Returns a "Gone" status (410) indicating that the resource
has been permanently removed. When this status is used the <EM>url</EM>
argument should be omitted.
</DL>
<P>
Other status codes can be returned by giving the numeric status code
as the value of <EM>status</EM>. If the status is between 300 and 399,
the <EM>url</EM> 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>
<HR>
<H2><A NAME="redirectmatch">RedirectMatch</A></H2>
<P>
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A>
RedirectMatch [<EM>status</EM>] <EM>regex URL</EM>
<BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> server config, virtual host, directory,
.htaccess<BR>
<A
HREF="directive-dict.html#Override"
REL="Help"
><STRONG>Override:</STRONG></A> FileInfo<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Base<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_alias
</P>
<P>This directive is equivalent to <A HREF="#redirect">Redirect</A>,
but makes use of standard regular expressions, 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:
<PRE>
RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg
</PRE>
</P>
<HR>
<H2><A NAME="redirecttemp">RedirectTemp directive</A></H2>
<P>
<!--%plaintext &lt;?INDEX {\tt Redirect} directive&gt; -->
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A> RedirectTemp <EM>URL-path URL</EM><BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> server config, virtual host, directory,
.htaccess<BR>
<A
HREF="directive-dict.html#Override"
REL="Help"
><STRONG>Override:</STRONG></A> FileInfo<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Base<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_alias
</P>
<P>
This directive makes the client know that the Redirect is only
temporary (status 302). Exactly equivalent to <CODE>Redirect
temp</CODE>.
</P>
<HR>
<H2><A NAME="redirectperm">RedirectPermanent directive</A></H2>
<P>
<!--%plaintext &lt;?INDEX {\tt Redirect} directive&gt; -->
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A> RedirectPermanent <EM>URL-path URL</EM><BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> server config, virtual host, directory,
.htaccess<BR>
<A
HREF="directive-dict.html#Override"
REL="Help"
><STRONG>Override:</STRONG></A> FileInfo<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Base<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_alias
</P>
<P>
This directive makes the client know that the Redirect is permanent
(status 301). Exactly equivalent to <CODE>Redirect permanent</CODE>.
</P>
<HR>
<H2><A NAME="scriptalias">ScriptAlias directive</A></H2>
<P>
<!--%plaintext &lt;?INDEX {\tt ScriptAlias} directive&gt; -->
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A> ScriptAlias <EM>URL-path file-path</em>|<em>directory-path</em>
<BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> server config, virtual host<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Base<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_alias
</P>
<P>
The ScriptAlias directive has the same behavior as the
<A HREF="#alias">Alias</A> directive, except that in addition it
marks the target directory as containing CGI scripts.
URLs with a (%-decoded) path beginning with <EM>URL-path</EM> will be
mapped to scripts beginning with the second argument which is a full
pathname in the local filesystem.
<P>
Example:
</P>
<BLOCKQUOTE><CODE>ScriptAlias /cgi-bin/ /web/cgi-bin/</CODE></BLOCKQUOTE>
<P>
A request for http://myserver/cgi-bin/foo would cause the server to
run the script /web/cgi-bin/foo.
</P>
<HR>
<H2><A NAME="scriptaliasmatch">ScriptAliasMatch</A></H2>
<P>
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A> ScriptAliasMatch
<EM>regex file-path</em>|<em>directory-path</EM><BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> server config, virtual host<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Base<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_alias
</P>
<P>This directive is equivalent to <A
HREF="#scriptalias">ScriptAlias</A>, but makes use of standard regular
expressions, 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:
<PRE>
ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
</PRE>
</P>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>