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.xsl"?>
   4 <modulesynopsis>
   5
   6 <name>mod_alias</name>
   7 <description>Provides for mapping different parts of the host
   8     filesystem in the document tree and for URL redirection</description>
   9 <status>Base</status>
  10 <sourcefile>mod_alias.c</sourcefile>
  11 <identifier>alias_module</identifier>
  12
  13 <summary>
  14     <p>The directives contained in this module allow for manipulation
  15     and control of URLs as requests arrive at the server. The
  16     <directive module="mod_alias">Alias</directive> and <directive
  17     module="mod_alias">ScriptAlias</directive> directives are used to
  18     map between URLs and filesystem paths.  This allows for content
  19     which is not directly under the <directive
  20     module="core">DocumentRoot</directive> served as part of the web
  21     document tree. The <directive
  22     module="mod_alias">ScriptAlias</directive> directive has the
  23     additional effect of marking the target directory as containing
  24     only CGI scripts.</p>
  25
  26     <p>The <directive module="mod_alias">Redirect</directive>
  27     directives are used to instruct clients to make a new request with
  28     a different URL. They are often used when a resource has moved to
  29     a new location.</p>
  30 </summary>
  31
  32 <seealso><module>mod_rewrite</module></seealso> <seealso><a
  33 href="../urlmapping.html">Mapping URLs to the filesystem</a></seealso>
  34
  35 <directivesynopsis>
  36 <name>Alias</name>
  37 <description>Maps URLs to filesystem locations</description>
  38 <syntax> Alias <em>URL-path
  39     file-path</em>|<em>directory-path</em></syntax>
  40 <contextlist><context>server config</context><context>virtual host</context>
  41 </contextlist>
  42
  43 <usage>
  44
  45     <p>The <directive>Alias</directive> directive allows documents to
  46     be stored in the local filesystem other than under the
  47     <directive module="core">DocumentRoot</directive>. URLs with a
  48     (%-decoded) path beginning with <em>url-path</em> will be mapped
  49     to local files beginning with <em>directory-filename</em>.</p>
  50
  51     <p>Example:</p>
  52
  53 <example>Alias /image /ftp/pub/image</example>
  54
  55     <p>A request for http://myserver/image/foo.gif would cause the
  56     server to return the file /ftp/pub/image/foo.gif.</p>
  57
  58     <p>Note that if you include a trailing / on the
  59     <em>url-path</em> then the server will require a trailing / in
  60     order to expand the alias. That is, if you use <code>Alias
  61     /icons/ /usr/local/apache/icons/</code> then the url
  62     <code>/icons</code> will not be aliased.</p>
  63
  64     <p>Note that you may need to specify additional <directive
  65     module="core">&lt;Directory&gt;</directive> sections which cover
  66     the <em>destination</em> of aliases.  Aliasing occurs before
  67     <directive module="core">&lt;Directory&gt;</directive> sections
  68     are checked, so only the destination of aliases are affected.
  69     (Note however <directive module="core">&lt;Location&gt;</directive>
  70     sections are run through once before aliases are performed, so
  71     they will apply.)</p>
  72
  73 </usage>
  74 </directivesynopsis>
  75
  76 <directivesynopsis>
  77 <name>AliasMatch</name>
  78 <description>Maps URLs to filesystem locations using regular
  79 expressions</description>
  80 <syntax>AliasMatch <em>regex
  81     file-path</em>|<em>directory-path</em></syntax>
  82 <contextlist><context>server config</context><context>virtual host</context>
  83 </contextlist>
  84
  85 <usage>
  86     <p>This directive is equivalent to <directive
  87     module="mod_alias">Alias</directive>, but makes use of standard
  88     regular expressions, instead of simple prefix matching. The
  89     supplied regular expression is matched against the URL-path, and
  90     if it matches, the server will substitute any parenthesized
  91     matches into the given string and use it as a filename. For
  92     example, to activate the <code>/icons</code> directory, one might
  93     use:</p>
  94 <example>
  95     AliasMatch ^/icons(.*) /usr/local/apache/icons$1
  96 </example>
  97 </usage>
  98 </directivesynopsis>
  99
 100 <directivesynopsis>
 101 <name>Redirect</name>
 102 <description>Sends an external redirect asking the client to fetch
 103 a different URL</description>
 104 <syntax>Redirect [<em>status</em>] <em>URL-path URL</em></syntax>
 105 <contextlist><context>server config</context><context>virtual host</context>
 106 <context>directory</context><context>.htaccess</context></contextlist>
 107 <override>FileInfo</override>
 108
 109 <usage>
 110     <p>The Redirect directive maps an old URL into a new one. The
 111     new URL is returned to the client which attempts to fetch it
 112     again with the new address. <em>URL-path</em> a (%-decoded)
 113     path; any requests for documents beginning with this path will
 114     be returned a redirect error to a new (%-encoded) URL beginning
 115     with <em>URL</em>.</p>
 116
 117     <p>Example:</p>
 118
 119 <example>Redirect /service http://foo2.bar.com/service</example>
 120
 121     <p>If the client requests http://myserver/service/foo.txt, it
 122     will be told to access http://foo2.bar.com/service/foo.txt
 123     instead.</p>
 124
 125 <note><title>Note</title> <p>Redirect directives take precedence over
 126 Alias and ScriptAlias directives, irrespective of their ordering in
 127 the configuration file. Also, <em>URL-path</em> must be an absolute
 128 path, not a relative path, even when used with .htaccess files or
 129 inside of <directive module="core">&lt;Directory&gt;</directive>
 130 sections.</p></note>
 131
 132     <p>If no <em>status</em> argument is given, the redirect will
 133     be "temporary" (HTTP status 302). This indicates to the client
 134     that the resource has moved temporarily. The <em>status</em>
 135     argument can be used to return other HTTP status codes:</p>
 136
 137     <dl>
 138       <dt>permanent</dt>
 139
 140       <dd>Returns a permanent redirect status (301) indicating that
 141       the resource has moved permanently.</dd>
 142
 143       <dt>temp</dt>
 144
 145       <dd>Returns a temporary redirect status (302). This is the
 146       default.</dd>
 147
 148       <dt>seeother</dt>
 149
 150       <dd>Returns a "See Other" status (303) indicating that the
 151       resource has been replaced.</dd>
 152
 153       <dt>gone</dt>
 154
 155       <dd>Returns a "Gone" status (410) indicating that the
 156       resource has been permanently removed. When this status is
 157       used the <em>url</em> argument should be omitted.</dd>
 158     </dl>
 159
 160     <p>Other status codes can be returned by giving the numeric
 161     status code as the value of <em>status</em>. If the status is
 162     between 300 and 399, the <em>url</em> argument must be present,
 163     otherwise it must be omitted. Note that the status must be
 164     known to the Apache code (see the function
 165     <code>send_error_response</code> in http_protocol.c).</p>
 166
 167     <p>Example:</p>
 168
 169     <example>
 170         Redirect permanent /one http://example.com/two<br />
 171         Redirect 303 /three http://example.com/other
 172     </example>
 173
 174 </usage>
 175 </directivesynopsis>
 176
 177 <directivesynopsis>
 178 <name>RedirectMatch</name>
 179 <description>Sends an external redirect asking the client to fetch
 180 a different URL based on a regular expression match of the
 181 current URL</description>
 182 <syntax>RedirectMatch [<em>status</em>] <em>regex URL</em></syntax>
 183 <contextlist><context>server config</context><context>virtual host</context>
 184 <context>directory</context><context>.htaccess</context></contextlist>
 185 <override>FileInfo</override>
 186
 187 <usage>
 188     <p>This directive is equivalent to <directive
 189     module="mod_alias">Redirect</directive>, but makes use of standard
 190     regular expressions, instead of simple prefix matching. The
 191     supplied regular expression is matched against the URL-path, and
 192     if it matches, the server will substitute any parenthesized
 193     matches into the given string and use it as a filename. For
 194     example, to redirect all GIF files to like-named JPEG files on
 195     another server, one might use:</p>
 196 <example>
 197     RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg
 198 </example>
 199 </usage>
 200 </directivesynopsis>
 201
 202 <directivesynopsis>
 203 <name>RedirectTemp</name>
 204 <description>Sends an external temporary redirect asking the client to fetch
 205 a different URL</description>
 206 <syntax>RedirectTemp <em>URL-path URL</em></syntax>
 207 <contextlist><context>server config</context><context>virtual host</context>
 208 <context>directory</context><context>.htaccess</context></contextlist>
 209 <override>FileInfo</override>
 210
 211 <usage>
 212     <p>This directive makes the client know that the Redirect is
 213     only temporary (status 302). Exactly equivalent to
 214     <code>Redirect temp</code>.</p>
 215 </usage>
 216 </directivesynopsis>
 217
 218 <directivesynopsis>
 219 <name>RedirectPermanent</name>
 220 <description>Sends an external permanent redirect asking the client to fetch
 221 a different URL</description>
 222 <syntax>RedirectPermanent <em>URL-path URL</em></syntax>
 223 <contextlist><context>server config</context><context>virtual host</context>
 224 <context>directory</context><context>.htaccess</context></contextlist>
 225 <override>FileInfo</override>
 226
 227 <usage>
 228     <p>This directive makes the client know that the Redirect is
 229     permanent (status 301). Exactly equivalent to <code>Redirect
 230     permanent</code>.</p>
 231 </usage>
 232 </directivesynopsis>
 233
 234 <directivesynopsis>
 235 <name>ScriptAlias</name>
 236 <description>Maps a URL to a filesystem location and designates the
 237 target as a CGI script</description>
 238 <syntax>ScriptAlias
 239 <em>URL-path file-path</em>|<em>directory-path</em></syntax>
 240 <contextlist><context>server config</context><context>virtual host</context>
 241 </contextlist>
 242
 243 <usage>
 244     <p>The <directive>ScriptAlias</directive> directive has the same
 245     behavior as the <directive module="mod_alias">Alias</directive>
 246     directive, except that in addition it marks the target directory
 247     as containing CGI scripts that will be processed by <module
 248     >mod_cgi</module>'s cgi-script handler. URLs with a
 249     (%-decoded) path beginning with <em>URL-path</em> will be mapped
 250     to scripts beginning with the second argument which is a full
 251     pathname in the local filesystem.</p>
 252
 253     <p>Example:</p>
 254
 255 <example>ScriptAlias /cgi-bin/ /web/cgi-bin/</example>
 256
 257     <p>A request for <code>http://myserver/cgi-bin/foo</code> would cause the
 258     server to run the script <code>/web/cgi-bin/foo</code>.</p>
 259 </usage>
 260 </directivesynopsis>
 261
 262 <directivesynopsis>
 263 <name>ScriptAliasMatch</name>
 264 <description>Maps a URL to a filesystem location using a regular expression
 265 and designates the target as a CGI script</description>
 266 <syntax>ScriptAliasMatch
 267 <em>regex file-path</em>|<em>directory-path</em></syntax>
 268 <contextlist><context>server config</context><context>virtual host</context>
 269 </contextlist>
 270
 271 <usage>
 272     <p>This directive is equivalent to <directive module="mod_alias"
 273     >ScriptAlias</directive>, but makes use of standard
 274     regular expressions, instead of simple prefix matching. The
 275     supplied regular expression is matched against the URL-path,
 276     and if it matches, the server will substitute any parenthesized
 277     matches into the given string and use it as a filename. For
 278     example, to activate the standard <code>/cgi-bin</code>, one
 279     might use:</p>
 280 <example>
 281     ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
 282 </example>
 283 </usage>
 284 </directivesynopsis>
 285
 286 </modulesynopsis>
 287