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">
143 Alias "/docs" "/var/web"
146 <p>the URL <code>http://www.example.com/docs/dir/file.html</code>
147 will be served from <code>/var/web/dir/file.html</code>. The
148 <directive module="mod_alias">ScriptAlias</directive> directive
149 works the same way, with the additional effect that all content
150 located at the target path is treated as <glossary ref="cgi"
151 >CGI</glossary> scripts.</p>
153 <p>For situations where you require additional flexibility, you
154 can use the <directive module="mod_alias">AliasMatch</directive>
155 and <directive module="mod_alias">ScriptAliasMatch</directive>
156 directives to do powerful <glossary ref="regex">regular
157 expression</glossary> based matching and substitution. For
160 <highlight language="config">
161 ScriptAliasMatch "^/~([a-zA-Z0-9]+)/cgi-bin/(.+)" "/home/$1/cgi-bin/$2"
164 <p>will map a request to
165 <code>http://example.com/~user/cgi-bin/script.cgi</code> to the
166 path <code>/home/user/cgi-bin/script.cgi</code> and will treat
167 the resulting file as a CGI script.</p>
170 <section id="user"><title>User Directories</title>
172 <p>Traditionally on Unix systems, the home directory of a
173 particular <em>user</em> can be referred to as
174 <code>~user/</code>. The module <module>mod_userdir</module>
175 extends this idea to the web by allowing files under each user's
176 home directory to be accessed using URLs such as the
179 <example>http://www.example.com/~user/file.html</example>
181 <p>For security reasons, it is inappropriate to give direct
182 access to a user's home directory from the web. Therefore, the
183 <directive module="mod_userdir">UserDir</directive> directive
184 specifies a directory underneath the user's home directory
185 where web files are located. Using the default setting of
186 <code>Userdir public_html</code>, the above URL maps to a file
188 <code>/home/user/public_html/file.html</code> where
189 <code>/home/user/</code> is the user's home directory as
190 specified in <code>/etc/passwd</code>.</p>
192 <p>There are also several other forms of the
193 <code>Userdir</code> directive which you can use on systems
194 where <code>/etc/passwd</code> does not contain the location of
195 the home directory.</p>
197 <p>Some people find the "~" symbol (which is often encoded on the
198 web as <code>%7e</code>) to be awkward and prefer to use an
199 alternate string to represent user directories. This functionality
200 is not supported by mod_userdir. However, if users' home
201 directories are structured in a regular way, then it is possible
202 to use the <directive module="mod_alias">AliasMatch</directive>
203 directive to achieve the desired effect. For example, to make
204 <code>http://www.example.com/upages/user/file.html</code> map to
205 <code>/home/user/public_html/file.html</code>, use the following
206 <code>AliasMatch</code> directive:</p>
208 <highlight language="config">
209 AliasMatch "^/upages/([a-zA-Z0-9]+)(/(.*))?$" "/home/$1/public_html/$3"
213 <section id="redirect"><title>URL Redirection</title>
215 <p>The configuration directives discussed in the above sections
216 tell httpd to get content from a specific place in the filesystem
217 and return it to the client. Sometimes, it is desirable instead to
218 inform the client that the requested content is located at a
219 different URL, and instruct the client to make a new request with
220 the new URL. This is called <em>redirection</em> and is
221 implemented by the <directive
222 module="mod_alias">Redirect</directive> directive. For example, if
223 the contents of the directory <code>/foo/</code> under the
224 <directive module="core">DocumentRoot</directive> are moved
225 to the new directory <code>/bar/</code>, you can instruct clients
226 to request the content at the new location as follows:</p>
228 <highlight language="config">
229 Redirect permanent "/foo/" "http://www.example.com/bar/"
232 <p>This will redirect any URL-Path starting in
233 <code>/foo/</code> to the same URL path on the
234 <code>www.example.com</code> server with <code>/bar/</code>
235 substituted for <code>/foo/</code>. You can redirect clients to
236 any server, not only the origin server.</p>
238 <p>httpd also provides a <directive
239 module="mod_alias">RedirectMatch</directive> directive for more
240 complicated rewriting problems. For example, to redirect requests
241 for the site home page to a different site, but leave all other
242 requests alone, use the following configuration:</p>
244 <highlight language="config">
245 RedirectMatch permanent "^/$" "http://www.example.com/startpage.html"
248 <p>Alternatively, to temporarily redirect all pages on one site
249 to a particular page on another site, use the following:</p>
251 <highlight language="config">
252 RedirectMatch temp ".*" "http://othersite.example.com/startpage.html"
256 <section id="proxy"><title>Reverse Proxy</title>
258 <p>httpd also allows you to bring remote documents into the URL space
259 of the local server. This technique is called <em>reverse
260 proxying</em> because the web server acts like a proxy server by
261 fetching the documents from a remote server and returning them to the
262 client. It is different from normal (forward) proxying because, to the client,
263 it appears the documents originate at the reverse proxy server.</p>
265 <p>In the following example, when clients request documents under the
266 <code>/foo/</code> directory, the server fetches those documents from
267 the <code>/bar/</code> directory on <code>internal.example.com</code>
268 and returns them to the client as if they were from the local
271 <highlight language="config">
272 ProxyPass "/foo/" "http://internal.example.com/bar/"<br />
273 ProxyPassReverse "/foo/" "http://internal.example.com/bar/"<br />
274 ProxyPassReverseCookieDomain internal.example.com public.example.com<br />
275 ProxyPassReverseCookiePath "/foo/" "/bar/"
278 <p>The <directive module="mod_proxy">ProxyPass</directive> configures
279 the server to fetch the appropriate documents, while the
280 <directive module="mod_proxy">ProxyPassReverse</directive>
281 directive rewrites redirects originating at
282 <code>internal.example.com</code> so that they target the appropriate
283 directory on the local server. Similarly, the
284 <directive module="mod_proxy">ProxyPassReverseCookieDomain</directive>
285 and <directive module="mod_proxy">ProxyPassReverseCookiePath</directive>
286 rewrite cookies set by the backend server.</p>
287 <p>It is important to note, however, that
288 links inside the documents will not be rewritten. So any absolute
289 links on <code>internal.example.com</code> will result in the client
290 breaking out of the proxy server and requesting directly from
291 <code>internal.example.com</code>. You can modify these links (and other
292 content) in a page as it is being served to the client using
293 <module>mod_substitute</module>.</p>
295 <highlight language="config">
296 Substitute s/internal\.example\.com/www.example.com/i
299 <p>For more sophisticated rewriting of links in HTML and XHTML, the
300 <module>mod_proxy_html</module> module is also available. It allows you
301 to create maps of URLs that need to be rewritten, so that complex
302 proxying scenarios can be handled.</p>
305 <section id="rewrite"><title>Rewriting Engine</title>
307 <p>When even more powerful substitution is required, the rewriting
308 engine provided by <module>mod_rewrite</module>
309 can be useful. The directives provided by this module can use
310 characteristics of the request such as browser type or source IP
311 address in deciding from where to serve content. In addition,
312 mod_rewrite can use external database files or programs to
313 determine how to handle a request. The rewriting engine is capable
314 of performing all three types of mappings discussed above:
315 internal redirects (aliases), external redirects, and proxying.
316 Many practical examples employing mod_rewrite are discussed in the
317 <a href="rewrite/">detailed mod_rewrite documentation</a>.</p>
320 <section id="notfound"><title>File Not Found</title>
322 <p>Inevitably, URLs will be requested for which no matching
323 file can be found in the filesystem. This can happen for
324 several reasons. In some cases, it can be a result of moving
325 documents from one location to another. In this case, it is
326 best to use <a href="#redirect">URL redirection</a> to inform
327 clients of the new location of the resource. In this way, you
328 can assure that old bookmarks and links will continue to work,
329 even though the resource is at a new location.</p>
331 <p>Another common cause of "File Not Found" errors is
332 accidental mistyping of URLs, either directly in the browser,
333 or in HTML links. httpd provides the module
334 <module>mod_speling</module> (sic) to help with
335 this problem. When this module is activated, it will intercept
336 "File Not Found" errors and look for a resource with a similar
337 filename. If one such file is found, mod_speling will send an
338 HTTP redirect to the client informing it of the correct
339 location. If several "close" files are found, a list of
340 available alternatives will be presented to the client.</p>
342 <p>An especially useful feature of mod_speling, is that it will
343 compare filenames without respect to case. This can help
344 systems where users are unaware of the case-sensitive nature of
345 URLs and the unix filesystem. But using mod_speling for
346 anything more than the occasional URL correction can place
347 additional load on the server, since each "incorrect" request
348 is followed by a URL redirection and a new request from the
351 <p><module>mod_dir</module> provides <directive module="mod_dir"
352 >FallbackResource</directive>, which can be used to map virtual
353 URIs to a real resource, which then serves them. This is a very
354 useful replacement to <module>mod_rewrite</module> when implementing
355 a 'front controller'</p>
357 <p>If all attempts to locate the content fail, httpd returns
358 an error page with HTTP status code 404 (file not found). The
359 appearance of this page is controlled with the
360 <directive module="core">ErrorDocument</directive> directive
361 and can be customized in a flexible manner as discussed in the
362 <a href="custom-error.html">Custom error responses</a>
366 <section id="other"><title>Other URL Mapping Modules</title>
368 <!-- TODO Flesh out each of the items in the list below. -->
370 <p>Other modules available for URL mapping include:</p>
373 <li><module>mod_actions</module> - Maps a request to a CGI script
374 based on the request method, or resource MIME type.</li>
375 <li><module>mod_dir</module> - Provides basic mapping of a trailing
376 slash into an index file such as <code>index.html</code>.</li>
377 <li><module>mod_imagemap</module> - Maps a request to a URL based
378 on where a user clicks on an image embedded in a HTML document.</li>
379 <li><module>mod_negotiation</module> - Selects an appropriate
380 document based on client preferences such as language or content