1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
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
14 http://www.apache.org/licenses/LICENSE-2.0
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.
23 <manualpage metafile="urlmapping.xml.meta">
25 <title>Mapping URLs to Filesystem Locations</title>
28 <p>This document explains how the Apache HTTP Server uses the URL of a request
29 to determine the filesystem location from which to serve a
33 <section id="related"><title>Related Modules and Directives</title>
37 <module>mod_actions</module>
38 <module>mod_alias</module>
39 <module>mod_autoindex</module>
40 <module>mod_dir</module>
41 <module>mod_imagemap</module>
42 <module>mod_negotiation</module>
43 <module>mod_proxy</module>
44 <module>mod_rewrite</module>
45 <module>mod_speling</module>
46 <module>mod_userdir</module>
47 <module>mod_vhost_alias</module>
50 <directive module="mod_alias">Alias</directive>
51 <directive module="mod_alias">AliasMatch</directive>
52 <directive module="mod_speling">CheckSpelling</directive>
53 <directive module="mod_dir">DirectoryIndex</directive>
54 <directive module="core">DocumentRoot</directive>
55 <directive module="core">ErrorDocument</directive>
56 <directive module="core">Options</directive>
57 <directive module="mod_proxy">ProxyPass</directive>
58 <directive module="mod_proxy">ProxyPassReverse</directive>
59 <directive module="mod_proxy">ProxyPassReverseCookieDomain</directive>
60 <directive module="mod_proxy">ProxyPassReverseCookiePath</directive>
61 <directive module="mod_alias">Redirect</directive>
62 <directive module="mod_alias">RedirectMatch</directive>
63 <directive module="mod_rewrite">RewriteCond</directive>
64 <directive module="mod_rewrite">RewriteRule</directive>
65 <directive module="mod_alias">ScriptAlias</directive>
66 <directive module="mod_alias">ScriptAliasMatch</directive>
67 <directive module="mod_userdir">UserDir</directive>
72 <section id="documentroot"><title>DocumentRoot</title>
74 <p>In deciding what file to serve for a given request, httpd's
75 default behavior is to take the URL-Path for the request (the part
76 of the URL following the hostname and port) and add it to the end
77 of the <directive module="core">DocumentRoot</directive> specified
78 in your configuration files. Therefore, the files and directories
79 underneath the <directive module="core">DocumentRoot</directive>
80 make up the basic document tree which will be visible from the
83 <p>For example, if <directive module="core">DocumentRoot</directive>
84 were set to <code>/var/www/html</code> then a request for
85 <code>http://www.example.com/fish/guppies.html</code> would result
86 in the file <code>/var/www/html/fish/guppies.html</code> being
87 served to the requesting client.</p>
89 <p>If a directory is requested (i.e. a path ending with
90 <code>/</code>), the file served from that directory is defined by
91 the <directive module="mod_dir">DirectoryIndex</directive> directive.
92 For example, if <code>DocumentRoot</code> were set as above, and
95 <example>DirectoryIndex index.html index.php</example>
97 <p>Then a request for <code>http://www.example.com/fish/</code> will
98 cause httpd to attempt to serve the file
99 <code>/var/www/html/fish/index.html</code>. In the event that
100 that file does not exist, it will next attempt to serve the file
101 <code>/var/www/html/fish/index.php</code>.</p>
103 <p>If neither of these files existed, the next step is to
104 attempt to provide a directory index, if
105 <module>mod_autoindex</module> is loaded and configured to permit
108 <p>httpd is also capable of <a href="vhosts/">Virtual
109 Hosting</a>, where the server receives requests for more than one
110 host. In this case, a different <directive
111 module="core">DocumentRoot</directive> can be specified for each
112 virtual host, or alternatively, the directives provided by the
113 module <module>mod_vhost_alias</module> can
114 be used to dynamically determine the appropriate place from which
115 to serve content based on the requested IP address or
118 <p>The <directive module="core">DocumentRoot</directive> directive
119 is set in your main server configuration file
120 (<code>httpd.conf</code>) and, possibly, once per additional <a
121 href="vhosts/">Virtual Host</a> you create.</p>
124 <section id="outside"><title>Files Outside the DocumentRoot</title>
126 <p>There are frequently circumstances where it is necessary to
127 allow web access to parts of the filesystem that are not strictly
128 underneath the <directive
129 module="core">DocumentRoot</directive>. httpd offers several
130 different ways to accomplish this. On Unix systems, symbolic links
131 can bring other parts of the filesystem under the <directive
132 module="core">DocumentRoot</directive>. For security reasons,
133 httpd will follow symbolic links only if the <directive
134 module="core">Options</directive> setting for the relevant
135 directory includes <code>FollowSymLinks</code> or
136 <code>SymLinksIfOwnerMatch</code>.</p>
138 <p>Alternatively, the <directive
139 module="mod_alias">Alias</directive> directive will map any part
140 of the filesystem into the web space. For example, with</p>
142 <highlight language="config">Alias /docs /var/web</highlight>
144 <p>the URL <code>http://www.example.com/docs/dir/file.html</code>
145 will be served from <code>/var/web/dir/file.html</code>. The
146 <directive module="mod_alias">ScriptAlias</directive> directive
147 works the same way, with the additional effect that all content
148 located at the target path is treated as <glossary ref="cgi"
149 >CGI</glossary> scripts.</p>
151 <p>For situations where you require additional flexibility, you
152 can use the <directive module="mod_alias">AliasMatch</directive>
153 and <directive module="mod_alias">ScriptAliasMatch</directive>
154 directives to do powerful <glossary ref="regex">regular
155 expression</glossary> based matching and substitution. For
158 <highlight language="config">
159 ScriptAliasMatch ^/~([a-zA-Z0-9]+)/cgi-bin/(.+) /home/$1/cgi-bin/$2
162 <p>will map a request to
163 <code>http://example.com/~user/cgi-bin/script.cgi</code> to the
164 path <code>/home/user/cgi-bin/script.cgi</code> and will treat
165 the resulting file as a CGI script.</p>
168 <section id="user"><title>User Directories</title>
170 <p>Traditionally on Unix systems, the home directory of a
171 particular <em>user</em> can be referred to as
172 <code>~user/</code>. The module <module>mod_userdir</module>
173 extends this idea to the web by allowing files under each user's
174 home directory to be accessed using URLs such as the
177 <example>http://www.example.com/~user/file.html</example>
179 <p>For security reasons, it is inappropriate to give direct
180 access to a user's home directory from the web. Therefore, the
181 <directive module="mod_userdir">UserDir</directive> directive
182 specifies a directory underneath the user's home directory
183 where web files are located. Using the default setting of
184 <code>Userdir public_html</code>, the above URL maps to a file
186 <code>/home/user/public_html/file.html</code> where
187 <code>/home/user/</code> is the user's home directory as
188 specified in <code>/etc/passwd</code>.</p>
190 <p>There are also several other forms of the
191 <code>Userdir</code> directive which you can use on systems
192 where <code>/etc/passwd</code> does not contain the location of
193 the home directory.</p>
195 <p>Some people find the "~" symbol (which is often encoded on the
196 web as <code>%7e</code>) to be awkward and prefer to use an
197 alternate string to represent user directories. This functionality
198 is not supported by mod_userdir. However, if users' home
199 directories are structured in a regular way, then it is possible
200 to use the <directive module="mod_alias">AliasMatch</directive>
201 directive to achieve the desired effect. For example, to make
202 <code>http://www.example.com/upages/user/file.html</code> map to
203 <code>/home/user/public_html/file.html</code>, use the following
204 <code>AliasMatch</code> directive:</p>
206 <highlight language="config">
207 AliasMatch ^/upages/([a-zA-Z0-9]+)(/(.*))?$ /home/$1/public_html/$3
211 <section id="redirect"><title>URL Redirection</title>
213 <p>The configuration directives discussed in the above sections
214 tell httpd to get content from a specific place in the filesystem
215 and return it to the client. Sometimes, it is desirable instead to
216 inform the client that the requested content is located at a
217 different URL, and instruct the client to make a new request with
218 the new URL. This is called <em>redirection</em> and is
219 implemented by the <directive
220 module="mod_alias">Redirect</directive> directive. For example, if
221 the contents of the directory <code>/foo/</code> under the
222 <directive module="core">DocumentRoot</directive> are moved
223 to the new directory <code>/bar/</code>, you can instruct clients
224 to request the content at the new location as follows:</p>
226 <highlight language="config">
227 Redirect permanent /foo/ http://www.example.com/bar/
230 <p>This will redirect any URL-Path starting in
231 <code>/foo/</code> to the same URL path on the
232 <code>www.example.com</code> server with <code>/bar/</code>
233 substituted for <code>/foo/</code>. You can redirect clients to
234 any server, not only the origin server.</p>
236 <p>httpd also provides a <directive
237 module="mod_alias">RedirectMatch</directive> directive for more
238 complicated rewriting problems. For example, to redirect requests
239 for the site home page to a different site, but leave all other
240 requests alone, use the following configuration:</p>
242 <highlight language="config">
243 RedirectMatch permanent ^/$ http://www.example.com/startpage.html
246 <p>Alternatively, to temporarily redirect all pages on one site
247 to a particular page on another site, use the following:</p>
249 <highlight language="config">
250 RedirectMatch temp .* http://othersite.example.com/startpage.html
254 <section id="proxy"><title>Reverse Proxy</title>
256 <p>httpd also allows you to bring remote documents into the URL space
257 of the local server. This technique is called <em>reverse
258 proxying</em> because the web server acts like a proxy server by
259 fetching the documents from a remote server and returning them to the
260 client. It is different from normal (forward) proxying because, to the client,
261 it appears the documents originate at the reverse proxy server.</p>
263 <p>In the following example, when clients request documents under the
264 <code>/foo/</code> directory, the server fetches those documents from
265 the <code>/bar/</code> directory on <code>internal.example.com</code>
266 and returns them to the client as if they were from the local
269 <highlight language="config">
270 ProxyPass /foo/ http://internal.example.com/bar/<br />
271 ProxyPassReverse /foo/ http://internal.example.com/bar/<br />
272 ProxyPassReverseCookieDomain internal.example.com public.example.com<br />
273 ProxyPassReverseCookiePath /foo/ /bar/
276 <p>The <directive module="mod_proxy">ProxyPass</directive> configures
277 the server to fetch the appropriate documents, while the
278 <directive module="mod_proxy">ProxyPassReverse</directive>
279 directive rewrites redirects originating at
280 <code>internal.example.com</code> so that they target the appropriate
281 directory on the local server. Similarly, the
282 <directive module="mod_proxy">ProxyPassReverseCookieDomain</directive>
283 and <directive module="mod_proxy">ProxyPassReverseCookiePath</directive>
284 rewrite cookies set by the backend server.</p>
285 <p>It is important to note, however, that
286 links inside the documents will not be rewritten. So any absolute
287 links on <code>internal.example.com</code> will result in the client
288 breaking out of the proxy server and requesting directly from
289 <code>internal.example.com</code>. You can modify these links (and other
290 content) in a page as it is being served to the client using
291 <module>mod_substitute</module>.</p>
293 <highlight language="config">
294 Substitute s/internal\.example\.com/www.example.com/i
297 <p>For more sophisticated rewriting of links in HTML and XHTML, the
298 <module>mod_proxy_html</module> module is also available. It allows you
299 to create maps of URLs that need to be rewritten, so that complex
300 proxying scenarios can be handled.</p>
303 <section id="rewrite"><title>Rewriting Engine</title>
305 <p>When even more powerful substitution is required, the rewriting
306 engine provided by <module>mod_rewrite</module>
307 can be useful. The directives provided by this module can use
308 characteristics of the request such as browser type or source IP
309 address in deciding from where to serve content. In addition,
310 mod_rewrite can use external database files or programs to
311 determine how to handle a request. The rewriting engine is capable
312 of performing all three types of mappings discussed above:
313 internal redirects (aliases), external redirects, and proxying.
314 Many practical examples employing mod_rewrite are discussed in the
315 <a href="rewrite/">detailed mod_rewrite documentation</a>.</p>
318 <section id="notfound"><title>File Not Found</title>
320 <p>Inevitably, URLs will be requested for which no matching
321 file can be found in the filesystem. This can happen for
322 several reasons. In some cases, it can be a result of moving
323 documents from one location to another. In this case, it is
324 best to use <a href="#redirect">URL redirection</a> to inform
325 clients of the new location of the resource. In this way, you
326 can assure that old bookmarks and links will continue to work,
327 even though the resource is at a new location.</p>
329 <p>Another common cause of "File Not Found" errors is
330 accidental mistyping of URLs, either directly in the browser,
331 or in HTML links. httpd provides the module
332 <module>mod_speling</module> (sic) to help with
333 this problem. When this module is activated, it will intercept
334 "File Not Found" errors and look for a resource with a similar
335 filename. If one such file is found, mod_speling will send an
336 HTTP redirect to the client informing it of the correct
337 location. If several "close" files are found, a list of
338 available alternatives will be presented to the client.</p>
340 <p>An especially useful feature of mod_speling, is that it will
341 compare filenames without respect to case. This can help
342 systems where users are unaware of the case-sensitive nature of
343 URLs and the unix filesystem. But using mod_speling for
344 anything more than the occasional URL correction can place
345 additional load on the server, since each "incorrect" request
346 is followed by a URL redirection and a new request from the
349 <p><module>mod_dir</module> provides <directive module="mod_dir"
350 >FallbackResource</directive>, which can be used to map virtual
351 URIs to a real resource, which then serves them. This is a very
352 useful replacement to <module>mod_rewrite</module> when implementing
353 a 'front controller'</p>
355 <p>If all attempts to locate the content fail, httpd returns
356 an error page with HTTP status code 404 (file not found). The
357 appearance of this page is controlled with the
358 <directive module="core">ErrorDocument</directive> directive
359 and can be customized in a flexible manner as discussed in the
360 <a href="custom-error.html">Custom error responses</a>
364 <section id="other"><title>Other URL Mapping Modules</title>
366 <!-- TODO Flesh out each of the items in the list below. -->
368 <p>Other modules available for URL mapping include:</p>
371 <li><module>mod_actions</module> - Maps a request to a CGI script
372 based on the request method, or resource MIME type.</li>
373 <li><module>mod_dir</module> - Provides basic mapping of a trailing
374 slash into an index file such as <code>index.html</code>.</li>
375 <li><module>mod_imagemap</module> - Maps a request to a URL based
376 on where a user clicks on an image embedded in a HTML document.</li>
377 <li><module>mod_negotiation</module> - Selects an appropriate
378 document based on client preferences such as language or content