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 occuring 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     <example>
  83     Alias /foo/bar /baz<br />
  84     Alias /foo /gaq
  85     </example>
  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
  93 </section>
  94
  95 <directivesynopsis>
  96 <name>Alias</name>
  97 <description>Maps URLs to filesystem locations</description>
  98 <syntax>Alias <var>URL-path</var>
  99 <var>file-path</var>|<var>directory-path</var></syntax>
 100 <contextlist><context>server config</context><context>virtual host</context>
 101 </contextlist>
 102
 103 <usage>
 104
 105     <p>The <directive>Alias</directive> directive allows documents to
 106     be stored in the local filesystem other than under the
 107     <directive module="core">DocumentRoot</directive>. URLs with a
 108     (%-decoded) path beginning with <var>url-path</var> will be mapped
 109     to local files beginning with <var>directory-path</var>.  The
 110     <var>url-path</var> is case-sensitive, even on case-insensitive
 111     file systems.</p>
 112
 113     <example><title>Example:</title>
 114       Alias /image /ftp/pub/image
 115     </example>
 116
 117     <p>A request for <code>http://myserver/image/foo.gif</code> would cause
 118     the server to return the file <code>/ftp/pub/image/foo.gif</code>.  Only
 119     complete path segments are matched, so the above alias would not match a
 120     request for <code>http://myserver/imagefoo.gif</code>.  For more complex
 121     matching using regular expressions, see the <directive module="mod_alias"
 122     >AliasMatch</directive> directive.</p>
 123
 124     <p>Note that if you include a trailing / on the
 125     <var>url-path</var> then the server will require a trailing / in
 126     order to expand the alias. That is, if you use</p>
 127
 128     <dl><dd><code>Alias /icons/ /usr/local/apache/icons/</code></dd></dl>
 129
 130     <p>then the url <code>/icons</code> will not be aliased.</p>
 131
 132     <p>Note that you may need to specify additional <directive
 133     type="section" module="core">Directory</directive> sections which
 134     cover the <em>destination</em> of aliases.  Aliasing occurs before
 135     <directive type="section" module="core">Directory</directive> sections
 136     are checked, so only the destination of aliases are affected.
 137     (Note however <directive type="section" module="core">Location</directive>
 138     sections are run through once before aliases are performed, so
 139     they will apply.)</p>
 140
 141     <p>In particular, if you are creating an <code>Alias</code> to a
 142     directory outside of your <directive
 143     module="core">DocumentRoot</directive>, you may need to explicitly
 144     permit access to the target directory.</p>
 145
 146     <example><title>Example:</title>
 147         Alias /image /ftp/pub/image<br />
 148         &lt;Directory /ftp/pub/image&gt;<br />
 149         <indent>
 150             Order allow,deny<br />
 151             Allow from all<br />
 152         </indent>
 153         &lt;/Directory&gt;
 154     </example>
 155
 156 </usage>
 157 </directivesynopsis>
 158
 159 <directivesynopsis>
 160 <name>AliasMatch</name>
 161 <description>Maps URLs to filesystem locations using regular
 162 expressions</description>
 163 <syntax>AliasMatch <var>regex</var>
 164 <var>file-path</var>|<var>directory-path</var></syntax>
 165 <contextlist><context>server config</context><context>virtual host</context>
 166 </contextlist>
 167
 168 <usage>
 169     <p>This directive is equivalent to <directive
 170     module="mod_alias">Alias</directive>, but makes use of
 171     <glossary ref="regex">regular expressions</glossary>,
 172     instead of simple prefix matching. The
 173     supplied regular expression is matched against the URL-path, and
 174     if it matches, the server will substitute any parenthesized
 175     matches into the given string and use it as a filename. For
 176     example, to activate the <code>/icons</code> directory, one might
 177     use:</p>
 178
 179     <example>
 180       AliasMatch ^/icons(.*) /usr/local/apache/icons$1
 181     </example>
 182
 183     <p>The full range of <glossary ref="regex">regular expression</glossary>
 184     power is available.  For example,
 185     it is possible to construct an alias with case-insensitive
 186     matching of the url-path:</p>
 187
 188     <example>
 189       AliasMatch (?i)^/image(.*) /ftp/pub/image$1
 190     </example>
 191
 192     <p>One subtle difference
 193     between <directive module="mod_alias">Alias</directive>
 194     and <directive module="mod_alias">AliasMatch</directive> is
 195     that <directive module="mod_alias">Alias</directive> will
 196     automatically copy any additional part of the URI, past the part
 197     that matched, onto the end of the file path on the right side,
 198     while <directive module="mod_alias">AliasMatch</directive> will
 199     not.  This means that in almost all cases, you will want the
 200     regular expression to match the entire request URI from beginning
 201     to end, and to use substitution on the right side.</p>
 202
 203     <p>In other words, just changing
 204     <directive module="mod_alias">Alias</directive> to
 205     <directive module="mod_alias">AliasMatch</directive> will not
 206     have the same effect.  At a minimum, you need to
 207     add <code>^</code> to the beginning of the regular expression
 208     and add <code>(.*)$</code> to the end, and add <code>$1</code> to
 209     the end of the replacement.</p>
 210
 211     <p>For example, suppose you want to replace this with AliasMatch:</p>
 212
 213     <example>
 214       Alias /image/ /ftp/pub/image/
 215     </example>
 216
 217     <p>This is NOT equivalent - don't do this!  This will send all
 218     requests that have /image/ anywhere in them to /ftp/pub/image/:</p>
 219
 220     <example>
 221       AliasMatch /image/ /ftp/pub/image/
 222     </example>
 223
 224     <p>This is what you need to get the same effect:</p>
 225
 226     <example>
 227       AliasMatch ^/image/(.*)$ /ftp/pub/image/$1
 228     </example>
 229
 230     <p>Of course, there's no point in
 231     using <directive module="mod_alias">AliasMatch</directive>
 232     where <directive module="mod_alias">Alias</directive> would
 233     work.  <directive module="mod_alias">AliasMatch</directive> lets
 234     you do more complicated things.  For example, you could
 235     serve different kinds of files from different directories:</p>
 236
 237     <example>
 238       AliasMatch ^/image/(.*)\.jpg$ /files/jpg.images/$1.jpg<br/>
 239       AliasMatch ^/image/(.*)\.gif$ /files/gif.images/$1.gif
 240     </example>
 241
 242 </usage>
 243 </directivesynopsis>
 244
 245 <directivesynopsis>
 246 <name>Redirect</name>
 247 <description>Sends an external redirect asking the client to fetch
 248 a different URL</description>
 249 <syntax>Redirect [<var>status</var>] <var>URL-path</var>
 250 <var>URL</var></syntax>
 251 <contextlist><context>server config</context><context>virtual host</context>
 252 <context>directory</context><context>.htaccess</context></contextlist>
 253 <override>FileInfo</override>
 254
 255 <usage>
 256     <p>The Redirect directive maps an old URL into a new one by asking
 257     the client to refetch the resource at the new location.</p>
 258
 259     <p>The old <em>URL-path</em> is a case-sensitive (%-decoded) path
 260     beginning with a slash.  A relative path is not allowed.</p>
 261
 262     <p>The new <em>URL</em> may be either an absolute URL beginning
 263     with a scheme and hostname, or a URL-path beginning with a slash.
 264     In this latter case the scheme and hostname of the current server will
 265     be added.</p>
 266
 267     <p>Then any request beginning with <em>URL-Path</em> will return a
 268     redirect request to the client at the location of the target
 269     <em>URL</em>.  Additional path information beyond the matched
 270     <em>URL-Path</em> will be appended to the target URL.</p>
 271
 272     <example><title>Example:</title>
 273       # Redirect to a URL on a different host<br />
 274       Redirect /service http://foo2.example.com/service<br />
 275       <br />
 276       # Redirect to a URL on the same host<br />
 277       Redirect /one /two
 278     </example>
 279
 280     <p>If the client requests <code>http://example.com/service/foo.txt</code>,
 281     it will be told to access
 282     <code>http://foo2.example.com/service/foo.txt</code>
 283         instead. This includes requests with <code>GET</code> parameters, such as
 284     <code>http://example.com/service/foo.pl?q=23&amp;a=42</code>,
 285     it will be redirected to
 286     <code>http://foo2.example.com/service/foo.pl?q=23&amp;a=42</code>.
 287         Note that <code>POST</code>s will be discarded.<br />
 288         Only complete path segments are matched, so the above
 289     example would not match a request for
 290     <code>http://example.com/servicefoo.txt</code>.  For more complex matching
 291     using regular expressions, see the <directive
 292     module="mod_alias">RedirectMatch</directive> directive.</p>
 293
 294
 295     <note><title>Note</title>
 296     <p>Redirect directives take precedence over Alias and ScriptAlias
 297     directives, irrespective of their ordering in the configuration
 298     file.</p></note>
 299
 300     <p>If no <var>status</var> argument is given, the redirect will
 301     be "temporary" (HTTP status 302). This indicates to the client
 302     that the resource has moved temporarily. The <var>status</var>
 303     argument can be used to return other HTTP status codes:</p>
 304
 305     <dl>
 306       <dt>permanent</dt>
 307
 308       <dd>Returns a permanent redirect status (301) indicating that
 309       the resource has moved permanently.</dd>
 310
 311       <dt>temp</dt>
 312
 313       <dd>Returns a temporary redirect status (302). This is the
 314       default.</dd>
 315
 316       <dt>seeother</dt>
 317
 318       <dd>Returns a "See Other" status (303) indicating that the
 319       resource has been replaced.</dd>
 320
 321       <dt>gone</dt>
 322
 323       <dd>Returns a "Gone" status (410) indicating that the
 324       resource has been permanently removed. When this status is
 325       used the <var>URL</var> argument should be omitted.</dd>
 326     </dl>
 327
 328     <p>Other status codes can be returned by giving the numeric
 329     status code as the value of <var>status</var>. If the status is
 330     between 300 and 399, the <var>URL</var> argument must be present,
 331     otherwise it must be omitted. Note that the status must be
 332     known to the Apache code (see the function
 333     <code>send_error_response</code> in http_protocol.c).</p>
 334
 335     <example><title>Example:</title>
 336       Redirect permanent /one http://example.com/two<br />
 337       Redirect 303 /three http://example.com/other
 338     </example>
 339
 340 </usage>
 341 </directivesynopsis>
 342
 343 <directivesynopsis>
 344 <name>RedirectMatch</name>
 345 <description>Sends an external redirect based on a regular expression match
 346 of the current URL</description>
 347 <syntax>RedirectMatch [<var>status</var>] <var>regex</var>
 348 <var>URL</var></syntax>
 349 <contextlist><context>server config</context><context>virtual host</context>
 350 <context>directory</context><context>.htaccess</context></contextlist>
 351 <override>FileInfo</override>
 352
 353 <usage>
 354     <p>This directive is equivalent to <directive
 355     module="mod_alias">Redirect</directive>, but makes use of
 356     <glossary ref="regex">regular expressions</glossary>,
 357     instead of simple prefix matching. The
 358     supplied regular expression is matched against the URL-path, and
 359     if it matches, the server will substitute any parenthesized
 360     matches into the given string and use it as a filename. For
 361     example, to redirect all GIF files to like-named JPEG files on
 362     another server, one might use:</p>
 363
 364     <example>
 365       RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg
 366     </example>
 367
 368     <p>The considerations related to the difference between
 369     <directive module="mod_alias">Alias</directive> and
 370     <directive module="mod_alias">AliasMatch</directive>
 371     also apply to the difference between
 372     <directive module="mod_alias">Redirect</directive> and
 373     <directive module="mod_alias">RedirectMatch</directive>.
 374     See <directive module="mod_alias">AliasMatch</directive> for
 375     details.</p>
 376
 377
 378 </usage>
 379 </directivesynopsis>
 380
 381 <directivesynopsis>
 382 <name>RedirectTemp</name>
 383 <description>Sends an external temporary redirect asking the client to fetch
 384 a different URL</description>
 385 <syntax>RedirectTemp <var>URL-path</var> <var>URL</var></syntax>
 386 <contextlist><context>server config</context><context>virtual host</context>
 387 <context>directory</context><context>.htaccess</context></contextlist>
 388 <override>FileInfo</override>
 389
 390 <usage>
 391     <p>This directive makes the client know that the Redirect is
 392     only temporary (status 302). Exactly equivalent to
 393     <code>Redirect temp</code>.</p>
 394 </usage>
 395 </directivesynopsis>
 396
 397 <directivesynopsis>
 398 <name>RedirectPermanent</name>
 399 <description>Sends an external permanent redirect asking the client to fetch
 400 a different URL</description>
 401 <syntax>RedirectPermanent <var>URL-path</var> <var>URL</var></syntax>
 402 <contextlist><context>server config</context><context>virtual host</context>
 403 <context>directory</context><context>.htaccess</context></contextlist>
 404 <override>FileInfo</override>
 405
 406 <usage>
 407     <p>This directive makes the client know that the Redirect is
 408     permanent (status 301). Exactly equivalent to <code>Redirect
 409     permanent</code>.</p>
 410 </usage>
 411 </directivesynopsis>
 412
 413 <directivesynopsis>
 414 <name>ScriptAlias</name>
 415 <description>Maps a URL to a filesystem location and designates the
 416 target as a CGI script</description>
 417 <syntax>ScriptAlias <var>URL-path</var>
 418 <var>file-path</var>|<var>directory-path</var></syntax>
 419 <contextlist><context>server config</context><context>virtual host</context>
 420 </contextlist>
 421
 422 <usage>
 423     <p>The <directive>ScriptAlias</directive> directive has the same
 424     behavior as the <directive module="mod_alias">Alias</directive>
 425     directive, except that in addition it marks the target directory
 426     as containing CGI scripts that will be processed by <module
 427     >mod_cgi</module>'s cgi-script handler. URLs with a case-sensitive
 428     (%-decoded) path beginning with <var>URL-path</var> will be mapped
 429     to scripts beginning with the second argument, which is a full
 430     pathname in the local filesystem.</p>
 431
 432     <example><title>Example:</title>
 433       ScriptAlias /cgi-bin/ /web/cgi-bin/
 434     </example>
 435
 436     <p>A request for <code>http://myserver/cgi-bin/foo</code> would cause the
 437     server to run the script <code>/web/cgi-bin/foo</code>.  This configuration
 438     is essentially equivalent to:</p>
 439     <example>
 440       Alias /cgi-bin/ /web/cgi-bin/<br />
 441       &lt;Location /cgi-bin &gt;<br />
 442       <indent>
 443       SetHandler cgi-script<br />
 444       Options +ExecCGI<br />
 445       </indent>
 446       &lt;/Location&gt;
 447     </example>
 448
 449         <p><directive>ScriptAlias</directive> can also be used in conjunction with
 450         a script or handler you have. For example:</p>
 451
 452         <example>
 453           ScriptAlias /cgi-bin/ /web/cgi-handler.pl
 454     </example>
 455
 456     <p>In this scenario all files requested in <code>/cgi-bin/</code> will be
 457     handled by the file you have configured, this allows you to use your own custom
 458     handler.  You may want to use this as a wrapper for CGI so that you can add
 459     content, or some other bespoke action.</p>
 460
 461     <note type="warning">It is safer to avoid placing CGI scripts under the
 462     <directive module="core">DocumentRoot</directive> in order to
 463     avoid accidentally revealing their source code if the
 464     configuration is ever changed.  The
 465     <directive>ScriptAlias</directive> makes this easy by mapping a
 466     URL and designating CGI scripts at the same time.  If you do
 467     choose to place your CGI scripts in a directory already
 468     accessible from the web, do not use
 469     <directive>ScriptAlias</directive>.  Instead, use <directive
 470     module="core" type="section">Directory</directive>, <directive
 471     module="core">SetHandler</directive>, and <directive
 472     module="core">Options</directive> as in:
 473     <example>
 474       &lt;Directory /usr/local/apache2/htdocs/cgi-bin &gt;<br />
 475       <indent>
 476       SetHandler cgi-script<br />
 477       Options ExecCGI<br />
 478       </indent>
 479       &lt;/Directory&gt;
 480     </example>
 481     This is necessary since multiple <var>URL-paths</var> can map
 482     to the same filesystem location, potentially bypassing the
 483     <directive>ScriptAlias</directive> and revealing the source code
 484     of the CGI scripts if they are not restricted by a
 485     <directive module="core">Directory</directive> section.</note>
 486
 487 </usage>
 488 <seealso><a href="../howto/cgi.html">CGI Tutorial</a></seealso>
 489 </directivesynopsis>
 490
 491 <directivesynopsis>
 492 <name>ScriptAliasMatch</name>
 493 <description>Maps a URL to a filesystem location using a regular expression
 494 and designates the target as a CGI script</description>
 495 <syntax>ScriptAliasMatch <var>regex</var>
 496 <var>file-path</var>|<var>directory-path</var></syntax>
 497 <contextlist><context>server config</context><context>virtual host</context>
 498 </contextlist>
 499
 500 <usage>
 501     <p>This directive is equivalent to <directive module="mod_alias"
 502     >ScriptAlias</directive>, but makes use of
 503     <glossary ref="regex">regular expressions</glossary>,
 504     instead of simple prefix matching. The
 505     supplied regular expression is matched against the URL-path,
 506     and if it matches, the server will substitute any parenthesized
 507     matches into the given string and use it as a filename. For
 508     example, to activate the standard <code>/cgi-bin</code>, one
 509     might use:</p>
 510
 511     <example>
 512       ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
 513     </example>
 514
 515     <p>As for AliasMatch, the full range of <glossary ref="rexex">regular
 516     expression</glossary> power is available.
 517     For example, it is possible to construct an alias with case-insensitive
 518     matching of the url-path:</p>
 519
 520     <example>
 521       ScriptAliasMatch (?i)^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
 522     </example>
 523
 524     <p>The considerations related to the difference between
 525     <directive module="mod_alias">Alias</directive> and
 526     <directive module="mod_alias">AliasMatch</directive>
 527     also apply to the difference between
 528     <directive module="mod_alias">ScriptAlias</directive> and
 529     <directive module="mod_alias">ScriptAliasMatch</directive>.
 530     See <directive module="mod_alias">AliasMatch</directive> for
 531     details.</p>
 532
 533 </usage>
 534 </directivesynopsis>
 535
 536 </modulesynopsis>
 537