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>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin <p>When the <directive module="mod_alias">Alias</directive>,
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <directive module="mod_alias">ScriptAlias</directive> and
291eb44b3adaf8247425286615b4f4b69fbea274minfrin <directive module="mod_alias">Redirect</directive> directives are used
291eb44b3adaf8247425286615b4f4b69fbea274minfrin within a <directive type="section" module="core">Location</directive>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin or <directive type="section" module="core">LocationMatch</directive>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin section, <a href="/expr.html">expression syntax</a> can be used
291eb44b3adaf8247425286615b4f4b69fbea274minfrin to manipulate the destination path or URL.
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>
6e87cc731ab01e065173ae8cc7152751d0387122humbedooh <p>Aliases and Redirects occurring in different contexts are processed
0222f4c188bbd414e293e0b78a8e350e3054322anilgun like other directives according to standard <a
0222f4c188bbd414e293e0b78a8e350e3054322anilgun href="/sections.html#mergin">merging rules</a>. But when multiple
0222f4c188bbd414e293e0b78a8e350e3054322anilgun Aliases or Redirects occur in the same context (for example, in the
0222f4c188bbd414e293e0b78a8e350e3054322anilgun same <directive type="section" module="core">VirtualHost</directive>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun section) they are processed in a particular order.</p>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <p>First, all Redirects are processed before Aliases are processed,
0222f4c188bbd414e293e0b78a8e350e3054322anilgun and therefore a request that matches a <directive
0222f4c188bbd414e293e0b78a8e350e3054322anilgun module="mod_alias">Redirect</directive> or <directive
0222f4c188bbd414e293e0b78a8e350e3054322anilgun module="mod_alias">RedirectMatch</directive> will never have Aliases
0222f4c188bbd414e293e0b78a8e350e3054322anilgun applied. Second, the Aliases and Redirects are processed in the order
0222f4c188bbd414e293e0b78a8e350e3054322anilgun they appear in the configuration files, with the first match taking
0222f4c188bbd414e293e0b78a8e350e3054322anilgun precedence.</p>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <p>For this reason, when two or more of these directives apply to the
0222f4c188bbd414e293e0b78a8e350e3054322anilgun same sub-path, you must list the most specific path first in order for
0222f4c188bbd414e293e0b78a8e350e3054322anilgun all the directives to have an effect. For example, the following
0222f4c188bbd414e293e0b78a8e350e3054322anilgun configuration will work as expected:</p>
b475917ddf898282aa51ce31b3275c2c4783ce98coarAlias "/foo" "/gaq"
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <p>But if the above two directives were reversed in order, the
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <code>/foo</code> <directive module="mod_alias">Alias</directive>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun would always match before the <code>/foo/bar</code> <directive
0222f4c188bbd414e293e0b78a8e350e3054322anilgun module="mod_alias">Alias</directive>, so the latter directive would be
0222f4c188bbd414e293e0b78a8e350e3054322anilgun ignored.</p>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin <p>When the <directive module="mod_alias">Alias</directive>,
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <directive module="mod_alias">ScriptAlias</directive> and
291eb44b3adaf8247425286615b4f4b69fbea274minfrin <directive module="mod_alias">Redirect</directive> directives are used
291eb44b3adaf8247425286615b4f4b69fbea274minfrin within a <directive type="section" module="core">Location</directive>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin or <directive type="section" module="core">LocationMatch</directive>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin section, these directives will take precedence over any globally
291eb44b3adaf8247425286615b4f4b69fbea274minfrin defined <directive module="mod_alias">Alias</directive>,
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <directive module="mod_alias">ScriptAlias</directive> and
291eb44b3adaf8247425286615b4f4b69fbea274minfrin <directive module="mod_alias">Redirect</directive> directives.</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
0222f4c188bbd414e293e0b78a8e350e3054322anilgun be stored in the local filesystem other than under the
88f76f668542dcd72fc9d71577997967c6bf123bslive <directive module="core">DocumentRoot</directive>. URLs with a
bb5f801a009c899d5678dad7177aaac3a02349a5humbedooh (%-decoded) path beginning with <var>URL-path</var> will be mapped
0222f4c188bbd414e293e0b78a8e350e3054322anilgun to local files beginning with <var>directory-path</var>. The
bb5f801a009c899d5678dad7177aaac3a02349a5humbedooh <var>URL-path</var> is case-sensitive, even on case-insensitive
aa997d6b651a6ac262d708b7f807a080d57c3844slive file systems.</p>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
39b600973267f27982523479ea58fd57414acd1ecovener <p>A request for <code>http://example.com/image/foo.gif</code> would cause
0222f4c188bbd414e293e0b78a8e350e3054322anilgun the server to return the file <code>/ftp/pub/image/foo.gif</code>. Only
0222f4c188bbd414e293e0b78a8e350e3054322anilgun complete path segments are matched, so the above alias would not match a
39b600973267f27982523479ea58fd57414acd1ecovener request for <code>http://example.com/imagefoo.gif</code>. For more complex
0222f4c188bbd414e293e0b78a8e350e3054322anilgun matching using regular expressions, see the <directive module="mod_alias"
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>Note that if you include a trailing / on the
bb5f801a009c899d5678dad7177aaac3a02349a5humbedooh <var>URL-path</var> then the server will require a trailing / in
0222f4c188bbd414e293e0b78a8e350e3054322anilgun order to expand the alias. That is, if you use</p>
2e539be4c778979088a05a6f164d47db200f73abnd </highlight>
7bd130b92562a79fa13eb163ce47d8a708c70425rbowen <p>then the url <code>/icons</code> will not be aliased, as it lacks
7bd130b92562a79fa13eb163ce47d8a708c70425rbowen that trailing /. Likewise, if you omit the slash on the
bb5f801a009c899d5678dad7177aaac3a02349a5humbedooh <var>URL-path</var> then you must also omit it from the
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>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh Require all granted
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh</Directory>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <p>Any number slashes in the <var>URL-path</var> parameter
a502eaab6c03ce460caec304e249f013d6ed8a91covener matches any number of slashes in the requested URL-path.</p>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin <p>If the <directive>Alias</directive> directive is used within a
291eb44b3adaf8247425286615b4f4b69fbea274minfrin <directive type="section" module="core">Location</directive>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin or <directive type="section" module="core">LocationMatch</directive>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin section the URL-path is omitted, and the file-path is interpreted
291eb44b3adaf8247425286615b4f4b69fbea274minfrin using <a href="/expr.html">expression syntax</a>.</p>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<Location "/image">
291eb44b3adaf8247425286615b4f4b69fbea274minfrin</Location>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<LocationMatch "/error/(?<NUMBER>[0-9]+)">
b475917ddf898282aa51ce31b3275c2c4783ce98coar Alias "/usr/local/apache/errors/%{env:MATCH_NUMBER}.html"
291eb44b3adaf8247425286615b4f4b69fbea274minfrin</LocationMatch>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin </highlight>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun<description>Maps URLs to filesystem locations using regular
88f76f668542dcd72fc9d71577997967c6bf123bsliveexpressions</description>
88f76f668542dcd72fc9d71577997967c6bf123bslive<contextlist><context>server config</context><context>virtual host</context>
88f76f668542dcd72fc9d71577997967c6bf123bslive</contextlist>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun module="mod_alias">Alias</directive>, but makes use of
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <glossary ref="regex">regular expressions</glossary>,
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
b475917ddf898282aa51ce31b3275c2c4783ce98coarAliasMatch "^/icons(/|$)(.*)" "/usr/local/apache/icons$1$2"
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <p>The full range of <glossary ref="regex">regular expression</glossary>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier power is available. For example,
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier it is possible to construct an alias with case-insensitive
bb5f801a009c899d5678dad7177aaac3a02349a5humbedooh matching of the URL-path:</p>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <p>One subtle difference
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier between <directive module="mod_alias">Alias</directive>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier and <directive module="mod_alias">AliasMatch</directive> is
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier that <directive module="mod_alias">Alias</directive> will
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier automatically copy any additional part of the URI, past the part
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier that matched, onto the end of the file path on the right side,
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier while <directive module="mod_alias">AliasMatch</directive> will
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier not. This means that in almost all cases, you will want the
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier regular expression to match the entire request URI from beginning
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier to end, and to use substitution on the right side.</p>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>In other words, just changing
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <directive module="mod_alias">AliasMatch</directive> will not
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier have the same effect. At a minimum, you need to
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier add <code>^</code> to the beginning of the regular expression
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier and add <code>(.*)$</code> to the end, and add <code>$1</code> to
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier the end of the replacement.</p>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <p>For example, suppose you want to replace this with AliasMatch:</p>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <p>This is NOT equivalent - don't do this! This will send all
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier requests that have /image/ anywhere in them to /ftp/pub/image/:</p>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <p>This is what you need to get the same effect:</p>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <p>Of course, there's no point in
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier using <directive module="mod_alias">AliasMatch</directive>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier where <directive module="mod_alias">Alias</directive> would
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier work. <directive module="mod_alias">AliasMatch</directive> lets
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier you do more complicated things. For example, you could
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier serve different kinds of files from different directories:</p>
b475917ddf898282aa51ce31b3275c2c4783ce98coarAliasMatch "^/image/(.*)\.jpg$" "/files/jpg.images/$1.jpg"<br/>
b475917ddf898282aa51ce31b3275c2c4783ce98coarAliasMatch "^/image/(.*)\.gif$" "/files/gif.images/$1.gif"
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
4130ea2bd87f049953016c594cb11aea02b7f9bacovener <p>Multiple leading slashes in the requested URL are discarded
4130ea2bd87f049953016c594cb11aea02b7f9bacovener by the server before directives from this module compares
4130ea2bd87f049953016c594cb11aea02b7f9bacovener against the requested URL-path.
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<description>Sends an external redirect asking the client to fetch
88f76f668542dcd72fc9d71577997967c6bf123bslivea different URL</description>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin<syntax>Redirect [<var>status</var>] [<var>URL-path</var>]
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>
aa997d6b651a6ac262d708b7f807a080d57c3844slive <p>The old <em>URL-path</em> is a case-sensitive (%-decoded) path
e32abf00422bf50d92c28c448f60b951c8fa42earbowen beginning with a slash. A relative path is not allowed.</p>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>The new <em>URL</em> may be either an absolute URL beginning
e32abf00422bf50d92c28c448f60b951c8fa42earbowen with a scheme and hostname, or a URL-path beginning with a slash.
e32abf00422bf50d92c28c448f60b951c8fa42earbowen In this latter case the scheme and hostname of the current server will
aa997d6b651a6ac262d708b7f807a080d57c3844slive be added.</p>
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>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh# Redirect to a URL on a different host
b475917ddf898282aa51ce31b3275c2c4783ce98coarRedirect "/service" "http://foo2.example.com/service"
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh# Redirect to a URL on the same host
b475917ddf898282aa51ce31b3275c2c4783ce98coarRedirect "/one" "/two"
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <p>If the client requests <code>http://example.com/service/foo.txt</code>,
0222f4c188bbd414e293e0b78a8e350e3054322anilgun it will be told to access
b2bdfa03847b3d5edc094516de5d30189ab7667digalic instead. This includes requests with <code>GET</code> parameters, such as
b2bdfa03847b3d5edc094516de5d30189ab7667digalic <code>http://example.com/service/foo.pl?q=23&a=42</code>,
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim it will be redirected to
b2bdfa03847b3d5edc094516de5d30189ab7667digalic <code>http://foo2.example.com/service/foo.pl?q=23&a=42</code>.
b2bdfa03847b3d5edc094516de5d30189ab7667digalic Note that <code>POST</code>s will be discarded.<br />
b2bdfa03847b3d5edc094516de5d30189ab7667digalic Only complete path segments are matched, so the above
1dc8b93510d9b89f686e98b98a18cc436cefa7f2slive example would not match a request for
291eb44b3adaf8247425286615b4f4b69fbea274minfrin <code>http://example.com/servicefoo.txt</code>. For more complex matching
291eb44b3adaf8247425286615b4f4b69fbea274minfrin using the <a href="/expr.html">expression syntax</a>, omit the URL-path
291eb44b3adaf8247425286615b4f4b69fbea274minfrin argument as described below. Alternatively, for matching using regular
291eb44b3adaf8247425286615b4f4b69fbea274minfrin expressions, see the <directive
1dc8b93510d9b89f686e98b98a18cc436cefa7f2slive module="mod_alias">RedirectMatch</directive> directive.</p>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <p>Redirect directives take precedence over Alias and ScriptAlias
0222f4c188bbd414e293e0b78a8e350e3054322anilgun directives, irrespective of their ordering in the configuration
291eb44b3adaf8247425286615b4f4b69fbea274minfrin file. Redirect directives inside a Location take precedence over
291eb44b3adaf8247425286615b4f4b69fbea274minfrin Redirect and Alias directives with an URL-path.</p></note>
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
5244cea61e02ab62f43c36a30693a91844b77d2drbowen between 300 and 399, the <var>URL</var> argument must be present.
5244cea61e02ab62f43c36a30693a91844b77d2drbowen If the status is <em>not</em> between 300 and 399, the
f57336f481f784131918fbcab13d5e4d5f4a1be1rbowen <var>URL</var> argument must be omitted. The status must be a valid
5244cea61e02ab62f43c36a30693a91844b77d2drbowen HTTP status code, known to the Apache HTTP Server (see the function
88f76f668542dcd72fc9d71577997967c6bf123bslive <code>send_error_response</code> in http_protocol.c).</p>
b475917ddf898282aa51ce31b3275c2c4783ce98coarRedirect permanent "/one" "http://example.com/two"
b475917ddf898282aa51ce31b3275c2c4783ce98coarRedirect 303 "/three" "http://example.com/other"
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin <p>If the <directive>Redirect</directive> directive is used within a
291eb44b3adaf8247425286615b4f4b69fbea274minfrin <directive type="section" module="core">Location</directive>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin or <directive type="section" module="core">LocationMatch</directive>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin section with the URL-path omitted, then the URL parameter will be
291eb44b3adaf8247425286615b4f4b69fbea274minfrin interpreted using <a href="/expr.html">expression syntax</a>.</p>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<Location "/one">
b475917ddf898282aa51ce31b3275c2c4783ce98coar Redirect permanent "http://example.com/two"
291eb44b3adaf8247425286615b4f4b69fbea274minfrin</Location><br />
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<Location "/three">
291eb44b3adaf8247425286615b4f4b69fbea274minfrin</Location><br />
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<LocationMatch "/error/(?<NUMBER>[0-9]+)">
b475917ddf898282aa51ce31b3275c2c4783ce98coar Redirect permanent "http://example.com/errors/%{env:MATCH_NUMBER}.html"
291eb44b3adaf8247425286615b4f4b69fbea274minfrin</LocationMatch><br />
291eb44b3adaf8247425286615b4f4b69fbea274minfrin </highlight>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun<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>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun module="mod_alias">Redirect</directive>, but makes use of
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <glossary ref="regex">regular expressions</glossary>,
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>
b475917ddf898282aa51ce31b3275c2c4783ce98coarRedirectMatch "(.*)\.gif$" "http://other.example.com$1.jpg"
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <p>The considerations related to the difference between
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <directive module="mod_alias">AliasMatch</directive>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier also apply to the difference between
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <directive module="mod_alias">Redirect</directive> and
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <directive module="mod_alias">RedirectMatch</directive>.
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier See <directive module="mod_alias">AliasMatch</directive> for
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier details.</p>
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
aa997d6b651a6ac262d708b7f807a080d57c3844slive >mod_cgi</module>'s cgi-script handler. URLs with a case-sensitive
67a715b4352c3e25bff32fccad48350180393f5end (%-decoded) path beginning with <var>URL-path</var> will be mapped
aa997d6b651a6ac262d708b7f807a080d57c3844slive to scripts beginning with the second argument, which is a full
88f76f668542dcd72fc9d71577997967c6bf123bslive pathname in the local filesystem.</p>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
39b600973267f27982523479ea58fd57414acd1ecovener <p>A request for <code>http://example.com/cgi-bin/foo</code> would cause the
aa997d6b651a6ac262d708b7f807a080d57c3844slive server to run the script <code>/web/cgi-bin/foo</code>. This configuration
aa997d6b651a6ac262d708b7f807a080d57c3844slive is essentially equivalent to:</p>
b475917ddf898282aa51ce31b3275c2c4783ce98coar<Location "/cgi-bin">
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh SetHandler cgi-script
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh Options +ExecCGI
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh</Location>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
e54ed2ca7730f513417f7ddbb2c85a49a8063cdbpctony <p><directive>ScriptAlias</directive> can also be used in conjunction with
e54ed2ca7730f513417f7ddbb2c85a49a8063cdbpctony a script or handler you have. For example:</p>
b475917ddf898282aa51ce31b3275c2c4783ce98coar </highlight>
e54ed2ca7730f513417f7ddbb2c85a49a8063cdbpctony <p>In this scenario all files requested in <code>/cgi-bin/</code> will be
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim handled by the file you have configured, this allows you to use your own custom
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim handler. You may want to use this as a wrapper for CGI so that you can add
e54ed2ca7730f513417f7ddbb2c85a49a8063cdbpctony content, or some other bespoke action.</p>
48981ff8ae4c9f2d7ac18c320727de9c36480d0fslive <note type="warning">It is safer to avoid placing CGI scripts under the
aa997d6b651a6ac262d708b7f807a080d57c3844slive <directive module="core">DocumentRoot</directive> in order to
aa997d6b651a6ac262d708b7f807a080d57c3844slive avoid accidentally revealing their source code if the
aa997d6b651a6ac262d708b7f807a080d57c3844slive configuration is ever changed. The
aa997d6b651a6ac262d708b7f807a080d57c3844slive <directive>ScriptAlias</directive> makes this easy by mapping a
aa997d6b651a6ac262d708b7f807a080d57c3844slive URL and designating CGI scripts at the same time. If you do
aa997d6b651a6ac262d708b7f807a080d57c3844slive choose to place your CGI scripts in a directory already
aa997d6b651a6ac262d708b7f807a080d57c3844slive accessible from the web, do not use
aa997d6b651a6ac262d708b7f807a080d57c3844slive <directive>ScriptAlias</directive>. Instead, use <directive
aa997d6b651a6ac262d708b7f807a080d57c3844slive module="core" type="section">Directory</directive>, <directive
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh SetHandler cgi-script
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh Options ExecCGI
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh</Directory>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
48981ff8ae4c9f2d7ac18c320727de9c36480d0fslive This is necessary since multiple <var>URL-paths</var> can map
48981ff8ae4c9f2d7ac18c320727de9c36480d0fslive to the same filesystem location, potentially bypassing the
48981ff8ae4c9f2d7ac18c320727de9c36480d0fslive <directive>ScriptAlias</directive> and revealing the source code
0222f4c188bbd414e293e0b78a8e350e3054322anilgun of the CGI scripts if they are not restricted by a
48981ff8ae4c9f2d7ac18c320727de9c36480d0fslive <directive module="core">Directory</directive> section.</note>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin <p>If the <directive>ScriptAlias</directive> directive is used within
291eb44b3adaf8247425286615b4f4b69fbea274minfrin a <directive type="section" module="core">Location</directive>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin or <directive type="section" module="core">LocationMatch</directive>
291eb44b3adaf8247425286615b4f4b69fbea274minfrin section with the URL-path omitted, then the URL parameter will be
291eb44b3adaf8247425286615b4f4b69fbea274minfrin interpreted using <a href="/expr.html">expression syntax</a>.</p>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<Location "/cgi-bin">
291eb44b3adaf8247425286615b4f4b69fbea274minfrin</Location>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<LocationMatch "/cgi-bin/errors/(?<NUMBER>[0-9]+)">
b475917ddf898282aa51ce31b3275c2c4783ce98coar ScriptAlias "/web/cgi-bin/errors/%{env:MATCH_NUMBER}.cgi"
291eb44b3adaf8247425286615b4f4b69fbea274minfrin</LocationMatch><br />
291eb44b3adaf8247425286615b4f4b69fbea274minfrin </highlight>
aa997d6b651a6ac262d708b7f807a080d57c3844slive<seealso><a href="/howto/cgi.html">CGI Tutorial</a></seealso>
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"
0222f4c188bbd414e293e0b78a8e350e3054322anilgun >ScriptAlias</directive>, but makes use of
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <glossary ref="regex">regular expressions</glossary>,
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>
b475917ddf898282aa51ce31b3275c2c4783ce98coarScriptAliasMatch "^/cgi-bin(.*)" "/usr/local/apache/cgi-bin$1"
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <p>As for AliasMatch, the full range of <glossary ref="rexex">regular
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier expression</glossary> power is available.
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier For example, it is possible to construct an alias with case-insensitive
bb5f801a009c899d5678dad7177aaac3a02349a5humbedooh matching of the URL-path:</p>
b475917ddf898282aa51ce31b3275c2c4783ce98coarScriptAliasMatch "(?i)^/cgi-bin(.*)" "/usr/local/apache/cgi-bin$1"
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh </highlight>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <p>The considerations related to the difference between
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <directive module="mod_alias">AliasMatch</directive>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier also apply to the difference between
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <directive module="mod_alias">ScriptAlias</directive> and
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <directive module="mod_alias">ScriptAliasMatch</directive>.
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier See <directive module="mod_alias">AliasMatch</directive> for
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier details.</p>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive</modulesynopsis>