mod_alias.xml revision db479b48bd4d75423ed4a45e15b75089d1a8ad72
d24d4c5159bcb11c25bb294926cfe7105c789ea9slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding Licensed to the Apache Software Foundation (ASF) under one or more
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding contributor license agreements. See the NOTICE file distributed with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding this work for additional information regarding copyright ownership.
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding The ASF licenses this file to You under the Apache License, Version 2.0
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding (the "License"); you may not use this file except in compliance with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding the License. You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
88f76f668542dcd72fc9d71577997967c6bf123bslive<description>Provides for mapping different parts of the host
88f76f668542dcd72fc9d71577997967c6bf123bslive filesystem in the document tree and for URL redirection</description>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>The directives contained in this module allow for manipulation
88f76f668542dcd72fc9d71577997967c6bf123bslive and control of URLs as requests arrive at the server. The
88f76f668542dcd72fc9d71577997967c6bf123bslive <directive module="mod_alias">Alias</directive> and <directive
88f76f668542dcd72fc9d71577997967c6bf123bslive module="mod_alias">ScriptAlias</directive> directives are used to
88f76f668542dcd72fc9d71577997967c6bf123bslive map between URLs and filesystem paths. This allows for content
88f76f668542dcd72fc9d71577997967c6bf123bslive which is not directly under the <directive
88f76f668542dcd72fc9d71577997967c6bf123bslive module="core">DocumentRoot</directive> served as part of the web
88f76f668542dcd72fc9d71577997967c6bf123bslive document tree. The <directive
88f76f668542dcd72fc9d71577997967c6bf123bslive module="mod_alias">ScriptAlias</directive> directive has the
88f76f668542dcd72fc9d71577997967c6bf123bslive additional effect of marking the target directory as containing
88f76f668542dcd72fc9d71577997967c6bf123bslive only CGI scripts.</p>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>The <directive module="mod_alias">Redirect</directive>
88f76f668542dcd72fc9d71577997967c6bf123bslive directives are used to instruct clients to make a new request with
88f76f668542dcd72fc9d71577997967c6bf123bslive a different URL. They are often used when a resource has moved to
88f76f668542dcd72fc9d71577997967c6bf123bslive a new location.</p>
ed213de6d7481be782a20ecc2675bc57fd4fac69slive <p><module>mod_alias</module> is designed to handle simple URL
ed213de6d7481be782a20ecc2675bc57fd4fac69slive manipulation tasks. For more complicated tasks such as
ed213de6d7481be782a20ecc2675bc57fd4fac69slive manipulating the query string, use the tools provided by
38677582e6ddf26e810728a68cbe560345486e48slive<seealso><module>mod_rewrite</module></seealso> <seealso><a
38677582e6ddf26e810728a68cbe560345486e48slivehref="/urlmapping.html">Mapping URLs to the filesystem</a></seealso>
7647551a51db086eef1f5b651b2d6f174dffb8b3slive<p>Aliases and Redirects occuring in different contexts are processed
7647551a51db086eef1f5b651b2d6f174dffb8b3slivelike other directives according to standard <a
7647551a51db086eef1f5b651b2d6f174dffb8b3slivehref="/sections.html#mergin">merging rules</a>. But when multiple
7647551a51db086eef1f5b651b2d6f174dffb8b3sliveAliases or Redirects occur in the same context (for example, in the
7647551a51db086eef1f5b651b2d6f174dffb8b3slivesame <directive type="section" module="core">VirtualHost</directive>
7647551a51db086eef1f5b651b2d6f174dffb8b3slivesection) they are processed in a particular order.</p>
7647551a51db086eef1f5b651b2d6f174dffb8b3slive<p>First, all Redirects are processed before Aliases are processed,
7647551a51db086eef1f5b651b2d6f174dffb8b3sliveand therefore a request that matches a <directive
7647551a51db086eef1f5b651b2d6f174dffb8b3slivemodule="mod_alias">RedirectMatch</directive> will never have Aliases
7647551a51db086eef1f5b651b2d6f174dffb8b3sliveapplied. Second, the Aliases and Redirects are processed in the order
7647551a51db086eef1f5b651b2d6f174dffb8b3slivethey appear in the configuration files, with the first match taking
7647551a51db086eef1f5b651b2d6f174dffb8b3sliveprecedence.</p>
7647551a51db086eef1f5b651b2d6f174dffb8b3slive<p>For this reason, when two or more of these directives apply to the
7647551a51db086eef1f5b651b2d6f174dffb8b3slivesame sub-path, you must list the most specific path first in order for
7647551a51db086eef1f5b651b2d6f174dffb8b3sliveall the directives to have an effect. For example, the following
7647551a51db086eef1f5b651b2d6f174dffb8b3sliveconfiguration will work as expected:</p>
7647551a51db086eef1f5b651b2d6f174dffb8b3sliveAlias /foo /gaq
7647551a51db086eef1f5b651b2d6f174dffb8b3slive<p>But if the above two directives were reversed in order, the
7647551a51db086eef1f5b651b2d6f174dffb8b3slive<code>/foo</code> <directive module="mod_alias">Alias</directive>
7647551a51db086eef1f5b651b2d6f174dffb8b3slivewould always match before the <code>/foo/bar</code> <directive
7647551a51db086eef1f5b651b2d6f174dffb8b3slivemodule="mod_alias">Alias</directive>, so the latter directive would be
7647551a51db086eef1f5b651b2d6f174dffb8b3sliveignored.</p>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<description>Maps URLs to filesystem locations</description>
88f76f668542dcd72fc9d71577997967c6bf123bslive<contextlist><context>server config</context><context>virtual host</context>
88f76f668542dcd72fc9d71577997967c6bf123bslive</contextlist>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>The <directive>Alias</directive> directive allows documents to
88f76f668542dcd72fc9d71577997967c6bf123bslive be stored in the local filesystem other than under the
88f76f668542dcd72fc9d71577997967c6bf123bslive <directive module="core">DocumentRoot</directive>. URLs with a
67a715b4352c3e25bff32fccad48350180393f5end (%-decoded) path beginning with <var>url-path</var> will be mapped
67a715b4352c3e25bff32fccad48350180393f5end to local files beginning with <var>directory-path</var>.</p>
67a715b4352c3e25bff32fccad48350180393f5end </example>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>A request for http://myserver/image/foo.gif would cause the
1dc8b93510d9b89f686e98b98a18cc436cefa7f2slive server to return the file /ftp/pub/image/foo.gif. Only complete
1dc8b93510d9b89f686e98b98a18cc436cefa7f2slive path segments are matched, so the above alias would not match a
1dc8b93510d9b89f686e98b98a18cc436cefa7f2slive request for http://myserver/imagefoo.gif. For more complex
1dc8b93510d9b89f686e98b98a18cc436cefa7f2slive matching using regular expressions, see the <directive
1dc8b93510d9b89f686e98b98a18cc436cefa7f2slive module="mod_alias">AliasMatch</directive> directive.</p>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>Note that if you include a trailing / on the
67a715b4352c3e25bff32fccad48350180393f5end <var>url-path</var> then the server will require a trailing / in
88f76f668542dcd72fc9d71577997967c6bf123bslive order to expand the alias. That is, if you use <code>Alias
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>Note that you may need to specify additional <directive
0dd298aa254f43fc223b1cc41e79d4a1fec308bcnd type="section" module="core">Directory</directive> sections which
0dd298aa254f43fc223b1cc41e79d4a1fec308bcnd cover the <em>destination</em> of aliases. Aliasing occurs before
0dd298aa254f43fc223b1cc41e79d4a1fec308bcnd <directive type="section" module="core">Directory</directive> sections
88f76f668542dcd72fc9d71577997967c6bf123bslive are checked, so only the destination of aliases are affected.
0dd298aa254f43fc223b1cc41e79d4a1fec308bcnd (Note however <directive type="section" module="core">Location</directive>
88f76f668542dcd72fc9d71577997967c6bf123bslive sections are run through once before aliases are performed, so
88f76f668542dcd72fc9d71577997967c6bf123bslive they will apply.)</p>
0287d5784a0533920978a7eb8f3cdeace17b467arbowen <p>In particular, if you are creating an <code>Alias</code> to a
0287d5784a0533920978a7eb8f3cdeace17b467arbowen directory outside of your <directive
52ebee778263c25c1b366f5e296d3f973fcb7aband module="core">DocumentRoot</directive>, you may need to explicitly
0287d5784a0533920978a7eb8f3cdeace17b467arbowen permit access to the target directory.</p>
2348633f2de9e8a3228db792f189d8b6ffdfdafand Order allow,deny<br />
2348633f2de9e8a3228db792f189d8b6ffdfdafand Allow from all<br />
0287d5784a0533920978a7eb8f3cdeace17b467arbowen </Directory>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<description>Maps URLs to filesystem locations using regular
88f76f668542dcd72fc9d71577997967c6bf123bsliveexpressions</description>
88f76f668542dcd72fc9d71577997967c6bf123bslive<contextlist><context>server config</context><context>virtual host</context>
88f76f668542dcd72fc9d71577997967c6bf123bslive</contextlist>
030108b1816bcda3d925df65357feabdce83bc94slive module="mod_alias">Alias</directive>, but makes use of
030108b1816bcda3d925df65357feabdce83bc94slive instead of simple prefix matching. The
88f76f668542dcd72fc9d71577997967c6bf123bslive supplied regular expression is matched against the URL-path, and
88f76f668542dcd72fc9d71577997967c6bf123bslive if it matches, the server will substitute any parenthesized
88f76f668542dcd72fc9d71577997967c6bf123bslive matches into the given string and use it as a filename. For
88f76f668542dcd72fc9d71577997967c6bf123bslive example, to activate the <code>/icons</code> directory, one might
67a715b4352c3e25bff32fccad48350180393f5end </example>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<description>Sends an external redirect asking the client to fetch
88f76f668542dcd72fc9d71577997967c6bf123bslivea different URL</description>
88f76f668542dcd72fc9d71577997967c6bf123bslive<contextlist><context>server config</context><context>virtual host</context>
88f76f668542dcd72fc9d71577997967c6bf123bslive<context>directory</context><context>.htaccess</context></contextlist>
82fedb7a2164fa01fe2870f080aeac6344503148slive <p>The Redirect directive maps an old URL into a new one by asking
82fedb7a2164fa01fe2870f080aeac6344503148slive the client to refetch the resource at the new location.</p>
82fedb7a2164fa01fe2870f080aeac6344503148slive <p>The old <em>URL-path</em> is a (%-decoded) path beginning with
82fedb7a2164fa01fe2870f080aeac6344503148slive a slash. A relative path is not allowed. The new <em>URL</em>
82fedb7a2164fa01fe2870f080aeac6344503148slive should be an absolute URL beginning with a scheme and hostname,
82fedb7a2164fa01fe2870f080aeac6344503148slive but a URL-path beginning with a slash may also be used, in which
82fedb7a2164fa01fe2870f080aeac6344503148slive case the scheme and hostname of the current server will be
82fedb7a2164fa01fe2870f080aeac6344503148slive <p>Then any request beginning with <em>URL-Path</em> will return a
82fedb7a2164fa01fe2870f080aeac6344503148slive redirect request to the client at the location of the target
82fedb7a2164fa01fe2870f080aeac6344503148slive <em>URL</em>. Additional path information beyond the matched
82fedb7a2164fa01fe2870f080aeac6344503148slive <em>URL-Path</em> will be appended to the target URL.</p>
82fedb7a2164fa01fe2870f080aeac6344503148slive Redirect /service http://foo2.example.com/service
67a715b4352c3e25bff32fccad48350180393f5end </example>
82fedb7a2164fa01fe2870f080aeac6344503148slive <p>If the client requests http://example.com/service/foo.txt, it
82fedb7a2164fa01fe2870f080aeac6344503148slive will be told to access http://foo2.example.com/service/foo.txt
1dc8b93510d9b89f686e98b98a18cc436cefa7f2slive instead. Only complete path segments are matched, so the above
1dc8b93510d9b89f686e98b98a18cc436cefa7f2slive example would not match a request for
1dc8b93510d9b89f686e98b98a18cc436cefa7f2slive http://example.com/servicefoo.txt. For more complex matching
1dc8b93510d9b89f686e98b98a18cc436cefa7f2slive using regular expressions, see the <directive
1dc8b93510d9b89f686e98b98a18cc436cefa7f2slive module="mod_alias">RedirectMatch</directive> directive.</p>
88f76f668542dcd72fc9d71577997967c6bf123bslive<note><title>Note</title> <p>Redirect directives take precedence over
88f76f668542dcd72fc9d71577997967c6bf123bsliveAlias and ScriptAlias directives, irrespective of their ordering in
67a715b4352c3e25bff32fccad48350180393f5end <p>If no <var>status</var> argument is given, the redirect will
88f76f668542dcd72fc9d71577997967c6bf123bslive be "temporary" (HTTP status 302). This indicates to the client
67a715b4352c3e25bff32fccad48350180393f5end that the resource has moved temporarily. The <var>status</var>
88f76f668542dcd72fc9d71577997967c6bf123bslive argument can be used to return other HTTP status codes:</p>
88f76f668542dcd72fc9d71577997967c6bf123bslive <dd>Returns a permanent redirect status (301) indicating that
88f76f668542dcd72fc9d71577997967c6bf123bslive the resource has moved permanently.</dd>
88f76f668542dcd72fc9d71577997967c6bf123bslive <dd>Returns a temporary redirect status (302). This is the
88f76f668542dcd72fc9d71577997967c6bf123bslive default.</dd>
88f76f668542dcd72fc9d71577997967c6bf123bslive <dd>Returns a "See Other" status (303) indicating that the
88f76f668542dcd72fc9d71577997967c6bf123bslive resource has been replaced.</dd>
88f76f668542dcd72fc9d71577997967c6bf123bslive <dd>Returns a "Gone" status (410) indicating that the
88f76f668542dcd72fc9d71577997967c6bf123bslive resource has been permanently removed. When this status is
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>Other status codes can be returned by giving the numeric
67a715b4352c3e25bff32fccad48350180393f5end status code as the value of <var>status</var>. If the status is
67a715b4352c3e25bff32fccad48350180393f5end between 300 and 399, the <var>URL</var> argument must be present,
88f76f668542dcd72fc9d71577997967c6bf123bslive otherwise it must be omitted. Note that the status must be
88f76f668542dcd72fc9d71577997967c6bf123bslive known to the Apache code (see the function
88f76f668542dcd72fc9d71577997967c6bf123bslive <code>send_error_response</code> in http_protocol.c).</p>
67a715b4352c3e25bff32fccad48350180393f5end Redirect 303 /three http://example.com/other
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis>
15ba1801088da1aad6d20609cf3f7b0b1eefce8aslive<description>Sends an external redirect based on a regular expression match
15ba1801088da1aad6d20609cf3f7b0b1eefce8asliveof the current URL</description>
67a715b4352c3e25bff32fccad48350180393f5end<syntax>RedirectMatch [<var>status</var>] <var>regex</var>
88f76f668542dcd72fc9d71577997967c6bf123bslive<contextlist><context>server config</context><context>virtual host</context>
88f76f668542dcd72fc9d71577997967c6bf123bslive<context>directory</context><context>.htaccess</context></contextlist>
030108b1816bcda3d925df65357feabdce83bc94slive module="mod_alias">Redirect</directive>, but makes use of
030108b1816bcda3d925df65357feabdce83bc94slive instead of simple prefix matching. The
88f76f668542dcd72fc9d71577997967c6bf123bslive supplied regular expression is matched against the URL-path, and
88f76f668542dcd72fc9d71577997967c6bf123bslive if it matches, the server will substitute any parenthesized
88f76f668542dcd72fc9d71577997967c6bf123bslive matches into the given string and use it as a filename. For
88f76f668542dcd72fc9d71577997967c6bf123bslive example, to redirect all GIF files to like-named JPEG files on
88f76f668542dcd72fc9d71577997967c6bf123bslive another server, one might use:</p>
67a715b4352c3e25bff32fccad48350180393f5end RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg
67a715b4352c3e25bff32fccad48350180393f5end </example>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<description>Sends an external temporary redirect asking the client to fetch
88f76f668542dcd72fc9d71577997967c6bf123bslivea different URL</description>
67a715b4352c3e25bff32fccad48350180393f5end<syntax>RedirectTemp <var>URL-path</var> <var>URL</var></syntax>
88f76f668542dcd72fc9d71577997967c6bf123bslive<contextlist><context>server config</context><context>virtual host</context>
88f76f668542dcd72fc9d71577997967c6bf123bslive<context>directory</context><context>.htaccess</context></contextlist>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>This directive makes the client know that the Redirect is
88f76f668542dcd72fc9d71577997967c6bf123bslive only temporary (status 302). Exactly equivalent to
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<description>Sends an external permanent redirect asking the client to fetch
88f76f668542dcd72fc9d71577997967c6bf123bslivea different URL</description>
67a715b4352c3e25bff32fccad48350180393f5end<syntax>RedirectPermanent <var>URL-path</var> <var>URL</var></syntax>
88f76f668542dcd72fc9d71577997967c6bf123bslive<contextlist><context>server config</context><context>virtual host</context>
88f76f668542dcd72fc9d71577997967c6bf123bslive<context>directory</context><context>.htaccess</context></contextlist>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>This directive makes the client know that the Redirect is
88f76f668542dcd72fc9d71577997967c6bf123bslive permanent (status 301). Exactly equivalent to <code>Redirect
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<description>Maps a URL to a filesystem location and designates the
88f76f668542dcd72fc9d71577997967c6bf123bslivetarget as a CGI script</description>
88f76f668542dcd72fc9d71577997967c6bf123bslive<contextlist><context>server config</context><context>virtual host</context>
88f76f668542dcd72fc9d71577997967c6bf123bslive</contextlist>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>The <directive>ScriptAlias</directive> directive has the same
88f76f668542dcd72fc9d71577997967c6bf123bslive behavior as the <directive module="mod_alias">Alias</directive>
88f76f668542dcd72fc9d71577997967c6bf123bslive directive, except that in addition it marks the target directory
88f76f668542dcd72fc9d71577997967c6bf123bslive as containing CGI scripts that will be processed by <module
88f76f668542dcd72fc9d71577997967c6bf123bslive >mod_cgi</module>'s cgi-script handler. URLs with a
67a715b4352c3e25bff32fccad48350180393f5end (%-decoded) path beginning with <var>URL-path</var> will be mapped
88f76f668542dcd72fc9d71577997967c6bf123bslive to scripts beginning with the second argument which is a full
88f76f668542dcd72fc9d71577997967c6bf123bslive pathname in the local filesystem.</p>
67a715b4352c3e25bff32fccad48350180393f5end </example>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>A request for <code>http://myserver/cgi-bin/foo</code> would cause the
88f76f668542dcd72fc9d71577997967c6bf123bslive server to run the script <code>/web/cgi-bin/foo</code>.</p>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<description>Maps a URL to a filesystem location using a regular expression
88f76f668542dcd72fc9d71577997967c6bf123bsliveand designates the target as a CGI script</description>
88f76f668542dcd72fc9d71577997967c6bf123bslive<contextlist><context>server config</context><context>virtual host</context>
88f76f668542dcd72fc9d71577997967c6bf123bslive</contextlist>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>This directive is equivalent to <directive module="mod_alias"
030108b1816bcda3d925df65357feabdce83bc94slive >ScriptAlias</directive>, but makes use of
030108b1816bcda3d925df65357feabdce83bc94slive instead of simple prefix matching. The
88f76f668542dcd72fc9d71577997967c6bf123bslive supplied regular expression is matched against the URL-path,
88f76f668542dcd72fc9d71577997967c6bf123bslive and if it matches, the server will substitute any parenthesized
88f76f668542dcd72fc9d71577997967c6bf123bslive matches into the given string and use it as a filename. For
88f76f668542dcd72fc9d71577997967c6bf123bslive example, to activate the standard <code>/cgi-bin</code>, one
88f76f668542dcd72fc9d71577997967c6bf123bslive might use:</p>
67a715b4352c3e25bff32fccad48350180393f5end ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
67a715b4352c3e25bff32fccad48350180393f5end </example>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive</modulesynopsis>