path: root/docs/manual/mod/mod_alias.xml

<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

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

    <example><title>Example:</title>
        Alias /image /ftp/pub/image<br />
        &lt;Directory /ftp/pub/image&gt;<br />
        <indent>
            Require all granted<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>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>

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

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

    <example>
      Alias /image/ /ftp/pub/image/
    </example>

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

    <example>
      AliasMatch /image/ /ftp/pub/image/
    </example>

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

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

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

    <example>
      AliasMatch ^/image/(.*)\.jpg$ /files/jpg.images/$1.jpg<br/>
      AliasMatch ^/image/(.*)\.gif$ /files/gif.images/$1.gif
    </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.</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>

    <example><title>Example:</title>
      # Redirect to a URL on a different host<br />
      Redirect /service http://foo2.example.com/service<br />
      <br />
      # Redirect to a URL on the same host<br />
      Redirect /one /two
    </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. 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>

    <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://other.example.com$1.jpg
    </example>

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

    <example><title>Example:</title>
      ScriptAlias /cgi-bin/ /web/cgi-bin/
    </example>

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

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

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

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