granicus.if.org Git - apache/blob - docs/manual/mod/mod_alias.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_alias.xml.meta">
  24
  25 <name>mod_alias</name>
  26 <description>Provides for mapping different parts of the host
  27     filesystem in the document tree and for URL redirection</description>
  28 <status>Base</status>
  29 <sourcefile>mod_alias.c</sourcefile>
  30 <identifier>alias_module</identifier>
  31
  32 <summary>
  33     <p>The directives contained in this module allow for manipulation
  34     and control of URLs as requests arrive at the server. The
  35     <directive module="mod_alias">Alias</directive> and <directive
  36     module="mod_alias">ScriptAlias</directive> directives are used to
  37     map between URLs and filesystem paths.  This allows for content
  38     which is not directly under the <directive
  39     module="core">DocumentRoot</directive> served as part of the web
  40     document tree. The <directive
  41     module="mod_alias">ScriptAlias</directive> directive has the
  42     additional effect of marking the target directory as containing
  43     only CGI scripts.</p>
  44
  45     <p>The <directive module="mod_alias">Redirect</directive>
  46     directives are used to instruct clients to make a new request with
  47     a different URL. They are often used when a resource has moved to
  48     a new location.</p>
  49
  50     <p><module>mod_alias</module> is designed to handle simple URL
  51     manipulation tasks.  For more complicated tasks such as
  52     manipulating the query string, use the tools provided by
  53     <module>mod_rewrite</module>.</p>
  54
  55 </summary>
  56
  57 <seealso><module>mod_rewrite</module></seealso> <seealso><a
  58 href="../urlmapping.html">Mapping URLs to the filesystem</a></seealso>
  59
  60 <section id="order"><title>Order of Processing</title>
  61
  62     <p>Aliases and Redirects occurring in different contexts are processed
  63     like other directives according to standard <a
  64     href="../sections.html#mergin">merging rules</a>.  But when multiple
  65     Aliases or Redirects occur in the same context (for example, in the
  66     same <directive type="section" module="core">VirtualHost</directive>
  67     section) they are processed in a particular order.</p>
  68
  69     <p>First, all Redirects are processed before Aliases are processed,
  70     and therefore a request that matches a <directive
  71     module="mod_alias">Redirect</directive> or <directive
  72     module="mod_alias">RedirectMatch</directive> will never have Aliases
  73     applied.  Second, the Aliases and Redirects are processed in the order
  74     they appear in the configuration files, with the first match taking
  75     precedence.</p>
  76
  77     <p>For this reason, when two or more of these directives apply to the
  78     same sub-path, you must list the most specific path first in order for
  79     all the directives to have an effect.  For example, the following
  80     configuration will work as expected:</p>
  81
  82     <highlight language="config">
  83 Alias "/foo/bar" "/baz"
  84 Alias "/foo" "/gaq"
  85     </highlight>
  86
  87     <p>But if the above two directives were reversed in order, the
  88     <code>/foo</code> <directive module="mod_alias">Alias</directive>
  89     would always match before the <code>/foo/bar</code> <directive
  90     module="mod_alias">Alias</directive>, so the latter directive would be
  91     ignored.</p>
  92 </section>
  93
  94 <directivesynopsis>
  95 <name>Alias</name>
  96 <description>Maps URLs to filesystem locations</description>
  97 <syntax>Alias <var>URL-path</var>
  98 <var>file-path</var>|<var>directory-path</var></syntax>
  99 <contextlist><context>server config</context><context>virtual host</context>
 100 </contextlist>
 101
 102 <usage>
 103
 104     <p>The <directive>Alias</directive> directive allows documents to
 105     be stored in the local filesystem other than under the
 106     <directive module="core">DocumentRoot</directive>. URLs with a
 107     (%-decoded) path beginning with <var>URL-path</var> will be mapped
 108     to local files beginning with <var>directory-path</var>.  The
 109     <var>URL-path</var> is case-sensitive, even on case-insensitive
 110     file systems.</p>
 111
 112     <highlight language="config">
 113       Alias "/image" "/ftp/pub/image"
 114     </highlight>
 115
 116     <p>A request for <code>http://example.com/image/foo.gif</code> would cause
 117     the server to return the file <code>/ftp/pub/image/foo.gif</code>.  Only
 118     complete path segments are matched, so the above alias would not match a
 119     request for <code>http://example.com/imagefoo.gif</code>.  For more complex
 120     matching using regular expressions, see the <directive module="mod_alias"
 121     >AliasMatch</directive> directive.</p>
 122
 123     <p>Note that if you include a trailing / on the
 124     <var>URL-path</var> then the server will require a trailing / in
 125     order to expand the alias. That is, if you use</p>
 126
 127     <highlight language="config">
 128       Alias "/icons/" "/usr/local/apache/icons/"
 129     </highlight>
 130
 131     <p>then the URL <code>/icons</code> will not be aliased, as it lacks
 132     that trailing /. Likewise, if you omit the slash on the
 133     <var>URL-path</var> then you must also omit it from the
 134     <var>file-path</var>.</p>
 135
 136     <p>Note that you may need to specify additional <directive
 137     type="section" module="core">Directory</directive> sections which
 138     cover the <em>destination</em> of aliases.  Aliasing occurs before
 139     <directive type="section" module="core">Directory</directive> sections
 140     are checked, so only the destination of aliases are affected.
 141     (Note however <directive type="section" module="core">Location</directive>
 142     sections are run through once before aliases are performed, so
 143     they will apply.)</p>
 144
 145     <p>In particular, if you are creating an <code>Alias</code> to a
 146     directory outside of your <directive
 147     module="core">DocumentRoot</directive>, you may need to explicitly
 148     permit access to the target directory.</p>
 149
 150     <highlight language="config">
 151 Alias "/image" "/ftp/pub/image"
 152 &lt;Directory "/ftp/pub/image"&gt;
 153     Require all granted
 154 &lt;/Directory&gt;
 155     </highlight>
 156
 157     <p>Any number slashes in the <var>URL-path</var> parameter
 158     matches any number of slashes in the requested URL-path.</p>
 159 </usage>
 160 </directivesynopsis>
 161
 162 <directivesynopsis>
 163 <name>AliasMatch</name>
 164 <description>Maps URLs to filesystem locations using regular
 165 expressions</description>
 166 <syntax>AliasMatch <var>regex</var>
 167 <var>file-path</var>|<var>directory-path</var></syntax>
 168 <contextlist><context>server config</context><context>virtual host</context>
 169 </contextlist>
 170
 171 <usage>
 172     <p>This directive is equivalent to <directive
 173     module="mod_alias">Alias</directive>, but makes use of
 174     <glossary ref="regex">regular expressions</glossary>,
 175     instead of simple prefix matching. The
 176     supplied regular expression is matched against the URL-path, and
 177     if it matches, the server will substitute any parenthesized
 178     matches into the given string and use it as a filename. For
 179     example, to activate the <code>/icons</code> directory, one might
 180     use:</p>
 181
 182     <highlight language="config">
 183       AliasMatch "^/icons(/|$)(.*)" "/usr/local/apache/icons$1$2"
 184     </highlight>
 185
 186     <p>The full range of <glossary ref="regex">regular expression</glossary>
 187     power is available.  For example,
 188     it is possible to construct an alias with case-insensitive
 189     matching of the URL-path:</p>
 190
 191     <highlight language="config">
 192       AliasMatch "(?i)^/image(.*)" "/ftp/pub/image$1"
 193     </highlight>
 194
 195     <p>One subtle difference
 196     between <directive module="mod_alias">Alias</directive>
 197     and <directive module="mod_alias">AliasMatch</directive> is
 198     that <directive module="mod_alias">Alias</directive> will
 199     automatically copy any additional part of the URI, past the part
 200     that matched, onto the end of the file path on the right side,
 201     while <directive module="mod_alias">AliasMatch</directive> will
 202     not.  This means that in almost all cases, you will want the
 203     regular expression to match the entire request URI from beginning
 204     to end, and to use substitution on the right side.</p>
 205
 206     <p>In other words, just changing
 207     <directive module="mod_alias">Alias</directive> to
 208     <directive module="mod_alias">AliasMatch</directive> will not
 209     have the same effect.  At a minimum, you need to
 210     add <code>^</code> to the beginning of the regular expression
 211     and add <code>(.*)$</code> to the end, and add <code>$1</code> to
 212     the end of the replacement.</p>
 213
 214     <p>For example, suppose you want to replace this with AliasMatch:</p>
 215
 216     <highlight language="config">
 217       Alias "/image/" "/ftp/pub/image/"
 218     </highlight>
 219
 220     <p>This is NOT equivalent - don't do this!  This will send all
 221     requests that have /image/ anywhere in them to /ftp/pub/image/:</p>
 222
 223     <highlight language="config">
 224       AliasMatch "/image/" "/ftp/pub/image/"
 225     </highlight>
 226
 227     <p>This is what you need to get the same effect:</p>
 228
 229     <highlight language="config">
 230       AliasMatch "^/image/(.*)$" "/ftp/pub/image/$1"
 231     </highlight>
 232
 233     <p>Of course, there's no point in
 234     using <directive module="mod_alias">AliasMatch</directive>
 235     where <directive module="mod_alias">Alias</directive> would
 236     work.  <directive module="mod_alias">AliasMatch</directive> lets
 237     you do more complicated things.  For example, you could
 238     serve different kinds of files from different directories:</p>
 239
 240     <highlight language="config">
 241 AliasMatch "^/image/(.*)\.jpg$" "/files/jpg.images/$1.jpg"
 242 AliasMatch "^/image/(.*)\.gif$" "/files/gif.images/$1.gif"
 243     </highlight>
 244
 245     <p>Multiple leading slashes in the requested URL are discarded
 246        by the server before directives from this module compares
 247        against the requested URL-path.
 248     </p>
 249
 250 </usage>
 251 </directivesynopsis>
 252
 253 <directivesynopsis>
 254 <name>Redirect</name>
 255 <description>Sends an external redirect asking the client to fetch
 256 a different URL</description>
 257 <syntax>Redirect [<var>status</var>] <var>URL-path</var>
 258 <var>URL</var></syntax>
 259 <contextlist><context>server config</context><context>virtual host</context>
 260 <context>directory</context><context>.htaccess</context></contextlist>
 261 <override>FileInfo</override>
 262
 263 <usage>
 264     <p>The Redirect directive maps an old URL into a new one by asking
 265     the client to refetch the resource at the new location.</p>
 266
 267     <p>The old <em>URL-path</em> is a case-sensitive (%-decoded) path
 268     beginning with a slash.  A relative path is not allowed.</p>
 269
 270     <p>The new <em>URL</em> may be either an absolute URL beginning
 271     with a scheme and hostname, or a URL-path beginning with a slash.
 272     In this latter case the scheme and hostname of the current server will
 273     be added.</p>
 274
 275     <p>Then any request beginning with <em>URL-Path</em> will return a
 276     redirect request to the client at the location of the target
 277     <em>URL</em>.  Additional path information beyond the matched
 278     <em>URL-Path</em> will be appended to the target URL.</p>
 279
 280     <highlight language="config">
 281 # Redirect to a URL on a different host
 282 Redirect "/service" "http://foo2.example.com/service"
 283
 284 # Redirect to a URL on the same host
 285 Redirect "/one" "/two"
 286     </highlight>
 287
 288     <p>If the client requests <code>http://example.com/service/foo.txt</code>,
 289     it will be told to access
 290     <code>http://foo2.example.com/service/foo.txt</code>
 291     instead. This includes requests with <code>GET</code> parameters, such as
 292     <code>http://example.com/service/foo.pl?q=23&amp;a=42</code>,
 293     it will be redirected to
 294     <code>http://foo2.example.com/service/foo.pl?q=23&amp;a=42</code>.
 295     Note that <code>POST</code>s will be discarded.<br />
 296     Only complete path segments are matched, so the above
 297     example would not match a request for
 298     <code>http://example.com/servicefoo.txt</code>.  For more complex matching
 299     using regular expressions, see the <directive
 300     module="mod_alias">RedirectMatch</directive> directive.</p>
 301
 302
 303     <note><title>Note</title>
 304     <p>Redirect directives take precedence over Alias and ScriptAlias
 305     directives, irrespective of their ordering in the configuration
 306     file.</p></note>
 307
 308     <p>If no <var>status</var> argument is given, the redirect will
 309     be "temporary" (HTTP status 302). This indicates to the client
 310     that the resource has moved temporarily. The <var>status</var>
 311     argument can be used to return other HTTP status codes:</p>
 312
 313     <dl>
 314       <dt>permanent</dt>
 315
 316       <dd>Returns a permanent redirect status (301) indicating that
 317       the resource has moved permanently.</dd>
 318
 319       <dt>temp</dt>
 320
 321       <dd>Returns a temporary redirect status (302). This is the
 322       default.</dd>
 323
 324       <dt>seeother</dt>
 325
 326       <dd>Returns a "See Other" status (303) indicating that the
 327       resource has been replaced.</dd>
 328
 329       <dt>gone</dt>
 330
 331       <dd>Returns a "Gone" status (410) indicating that the
 332       resource has been permanently removed. When this status is
 333       used the <var>URL</var> argument should be omitted.</dd>
 334     </dl>
 335
 336     <p>Other status codes can be returned by giving the numeric
 337     status code as the value of <var>status</var>. If the status is
 338     between 300 and 399, the <var>URL</var> argument must be present.
 339     If the status is <em>not</em> between 300 and 399, the
 340     <var>URL</var> argument must be omitted. The status must be a valid
 341     HTTP status code, known to the Apache HTTP Server (see the function
 342     <code>send_error_response</code> in http_protocol.c).</p>
 343
 344     <highlight language="config">
 345 Redirect permanent "/one" "http://example.com/two"
 346 Redirect 303 "/three" "http://example.com/other"
 347     </highlight>
 348 </usage>
 349 </directivesynopsis>
 350
 351 <directivesynopsis>
 352 <name>RedirectMatch</name>
 353 <description>Sends an external redirect based on a regular expression match
 354 of the current URL</description>
 355 <syntax>RedirectMatch [<var>status</var>] <var>regex</var>
 356 <var>URL</var></syntax>
 357 <contextlist><context>server config</context><context>virtual host</context>
 358 <context>directory</context><context>.htaccess</context></contextlist>
 359 <override>FileInfo</override>
 360
 361 <usage>
 362     <p>This directive is equivalent to <directive
 363     module="mod_alias">Redirect</directive>, but makes use of
 364     <glossary ref="regex">regular expressions</glossary>,
 365     instead of simple prefix matching. The
 366     supplied regular expression is matched against the URL-path, and
 367     if it matches, the server will substitute any parenthesized
 368     matches into the given string and use it as a filename. For
 369     example, to redirect all GIF files to like-named JPEG files on
 370     another server, one might use:</p>
 371
 372     <highlight language="config">
 373       RedirectMatch "(.*)\.gif$" "http://other.example.com$1.jpg"
 374     </highlight>
 375
 376     <p>The considerations related to the difference between
 377     <directive module="mod_alias">Alias</directive> and
 378     <directive module="mod_alias">AliasMatch</directive>
 379     also apply to the difference between
 380     <directive module="mod_alias">Redirect</directive> and
 381     <directive module="mod_alias">RedirectMatch</directive>.
 382     See <directive module="mod_alias">AliasMatch</directive> for
 383     details.</p>
 384
 385
 386 </usage>
 387 </directivesynopsis>
 388
 389 <directivesynopsis>
 390 <name>RedirectTemp</name>
 391 <description>Sends an external temporary redirect asking the client to fetch
 392 a different URL</description>
 393 <syntax>RedirectTemp <var>URL-path</var> <var>URL</var></syntax>
 394 <contextlist><context>server config</context><context>virtual host</context>
 395 <context>directory</context><context>.htaccess</context></contextlist>
 396 <override>FileInfo</override>
 397
 398 <usage>
 399     <p>This directive makes the client know that the Redirect is
 400     only temporary (status 302). Exactly equivalent to
 401     <code>Redirect temp</code>.</p>
 402 </usage>
 403 </directivesynopsis>
 404
 405 <directivesynopsis>
 406 <name>RedirectPermanent</name>
 407 <description>Sends an external permanent redirect asking the client to fetch
 408 a different URL</description>
 409 <syntax>RedirectPermanent <var>URL-path</var> <var>URL</var></syntax>
 410 <contextlist><context>server config</context><context>virtual host</context>
 411 <context>directory</context><context>.htaccess</context></contextlist>
 412 <override>FileInfo</override>
 413
 414 <usage>
 415     <p>This directive makes the client know that the Redirect is
 416     permanent (status 301). Exactly equivalent to <code>Redirect
 417     permanent</code>.</p>
 418 </usage>
 419 </directivesynopsis>
 420
 421 <directivesynopsis>
 422 <name>ScriptAlias</name>
 423 <description>Maps a URL to a filesystem location and designates the
 424 target as a CGI script</description>
 425 <syntax>ScriptAlias <var>URL-path</var>
 426 <var>file-path</var>|<var>directory-path</var></syntax>
 427 <contextlist><context>server config</context><context>virtual host</context>
 428 </contextlist>
 429
 430 <usage>
 431     <p>The <directive>ScriptAlias</directive> directive has the same
 432     behavior as the <directive module="mod_alias">Alias</directive>
 433     directive, except that in addition it marks the target directory
 434     as containing CGI scripts that will be processed by <module
 435     >mod_cgi</module>'s cgi-script handler. URLs with a case-sensitive
 436     (%-decoded) path beginning with <var>URL-path</var> will be mapped
 437     to scripts beginning with the second argument, which is a full
 438     pathname in the local filesystem.</p>
 439
 440     <highlight language="config">
 441       ScriptAlias "/cgi-bin/" "/web/cgi-bin/"
 442     </highlight>
 443
 444     <p>A request for <code>http://example.com/cgi-bin/foo</code> would cause the
 445     server to run the script <code>/web/cgi-bin/foo</code>.  This configuration
 446     is essentially equivalent to:</p>
 447     <highlight language="config">
 448 Alias "/cgi-bin/" "/web/cgi-bin/"
 449 &lt;Location "/cgi-bin" &gt;
 450     SetHandler cgi-script
 451     Options +ExecCGI
 452 &lt;/Location&gt;
 453     </highlight>
 454
 455     <p><directive>ScriptAlias</directive> can also be used in conjunction with
 456     a script or handler you have. For example:</p>
 457
 458     <highlight language="config">
 459 ScriptAlias "/cgi-bin/" "/web/cgi-handler.pl"
 460     </highlight>
 461
 462     <p>In this scenario all files requested in <code>/cgi-bin/</code> will be
 463     handled by the file you have configured, this allows you to use your own custom
 464     handler.  You may want to use this as a wrapper for CGI so that you can add
 465     content, or some other bespoke action.</p>
 466
 467     <note type="warning">It is safer to avoid placing CGI scripts under the
 468     <directive module="core">DocumentRoot</directive> in order to
 469     avoid accidentally revealing their source code if the
 470     configuration is ever changed.  The
 471     <directive>ScriptAlias</directive> makes this easy by mapping a
 472     URL and designating CGI scripts at the same time.  If you do
 473     choose to place your CGI scripts in a directory already
 474     accessible from the web, do not use
 475     <directive>ScriptAlias</directive>.  Instead, use <directive
 476     module="core" type="section">Directory</directive>, <directive
 477     module="core">SetHandler</directive>, and <directive
 478     module="core">Options</directive> as in:
 479     <highlight language="config">
 480 &lt;Directory "/usr/local/apache2/htdocs/cgi-bin"&gt;
 481     SetHandler cgi-script
 482     Options ExecCGI
 483 &lt;/Directory&gt;
 484     </highlight>
 485     This is necessary since multiple <var>URL-paths</var> can map
 486     to the same filesystem location, potentially bypassing the
 487     <directive>ScriptAlias</directive> and revealing the source code
 488     of the CGI scripts if they are not restricted by a
 489     <directive module="core">Directory</directive> section.</note>
 490 </usage>
 491 <seealso><a href="../howto/cgi.html">CGI Tutorial</a></seealso>
 492 </directivesynopsis>
 493
 494 <directivesynopsis>
 495 <name>ScriptAliasMatch</name>
 496 <description>Maps a URL to a filesystem location using a regular expression
 497 and designates the target as a CGI script</description>
 498 <syntax>ScriptAliasMatch <var>regex</var>
 499 <var>file-path</var>|<var>directory-path</var></syntax>
 500 <contextlist><context>server config</context><context>virtual host</context>
 501 </contextlist>
 502
 503 <usage>
 504     <p>This directive is equivalent to <directive module="mod_alias"
 505     >ScriptAlias</directive>, but makes use of
 506     <glossary ref="regex">regular expressions</glossary>,
 507     instead of simple prefix matching. The
 508     supplied regular expression is matched against the URL-path,
 509     and if it matches, the server will substitute any parenthesized
 510     matches into the given string and use it as a filename. For
 511     example, to activate the standard <code>/cgi-bin</code>, one
 512     might use:</p>
 513
 514     <highlight language="config">
 515       ScriptAliasMatch "^/cgi-bin(.*)" "/usr/local/apache/cgi-bin$1"
 516     </highlight>
 517
 518     <p>As for AliasMatch, the full range of <glossary ref="rexex">regular
 519     expression</glossary> power is available.
 520     For example, it is possible to construct an alias with case-insensitive
 521     matching of the URL-path:</p>
 522
 523     <highlight language="config">
 524       ScriptAliasMatch "(?i)^/cgi-bin(.*)" "/usr/local/apache/cgi-bin$1"
 525     </highlight>
 526
 527     <p>The considerations related to the difference between
 528     <directive module="mod_alias">Alias</directive> and
 529     <directive module="mod_alias">AliasMatch</directive>
 530     also apply to the difference between
 531     <directive module="mod_alias">ScriptAlias</directive> and
 532     <directive module="mod_alias">ScriptAliasMatch</directive>.
 533     See <directive module="mod_alias">AliasMatch</directive> for
 534     details.</p>
 535
 536 </usage>
 537 </directivesynopsis>
 538
 539 </modulesynopsis>