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 Copyright 2002-2005 The Apache Software Foundation or its licensors,
10 Licensed under the Apache License, Version 2.0 (the "License");
11 you may not use this file except in compliance with the License.
12 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 Apache 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_alias</module>
38 <module>mod_proxy</module>
39 <module>mod_rewrite</module>
40 <module>mod_userdir</module>
41 <module>mod_speling</module>
42 <module>mod_vhost_alias</module>
45 <directive module="mod_alias">Alias</directive>
46 <directive module="mod_alias">AliasMatch</directive>
47 <directive module="mod_speling">CheckSpelling</directive>
48 <directive module="core">DocumentRoot</directive>
49 <directive module="core">ErrorDocument</directive>
50 <directive module="core">Options</directive>
51 <directive module="mod_proxy">ProxyPass</directive>
52 <directive module="mod_proxy">ProxyPassReverse</directive>
53 <directive module="mod_proxy">ProxyPassReverseCookieDomain</directive>
54 <directive module="mod_proxy">ProxyPassReverseCookiePath</directive>
55 <directive module="mod_alias">Redirect</directive>
56 <directive module="mod_alias">RedirectMatch</directive>
57 <directive module="mod_rewrite">RewriteCond</directive>
58 <directive module="mod_rewrite">RewriteMatch</directive>
59 <directive module="mod_alias">ScriptAlias</directive>
60 <directive module="mod_alias">ScriptAliasMatch</directive>
61 <directive module="mod_userdir">UserDir</directive>
66 <section id="documentroot"><title>DocumentRoot</title>
68 <p>In deciding what file to serve for a given request, Apache's
69 default behavior is to take the URL-Path for the request (the part
70 of the URL following the hostname and port) and add it to the end
71 of the <directive module="core">DocumentRoot</directive> specified
72 in your configuration files. Therefore, the files and directories
73 underneath the <directive module="core">DocumentRoot</directive>
74 make up the basic document tree which will be visible from the
77 <p>Apache is also capable of <a href="vhosts/">Virtual
78 Hosting</a>, where the server receives requests for more than one
79 host. In this case, a different <directive
80 module="core">DocumentRoot</directive> can be specified for each
81 virtual host, or alternatively, the directives provided by the
82 module <module>mod_vhost_alias</module> can
83 be used to dynamically determine the appropriate place from which
84 to serve content based on the requested IP address or
88 <section id="outside"><title>Files Outside the DocumentRoot</title>
90 <p>There are frequently circumstances where it is necessary to
91 allow web access to parts of the filesystem that are not strictly
92 underneath the <directive
93 module="core">DocumentRoot</directive>. Apache offers several
94 different ways to accomplish this. On Unix systems, symbolic links
95 can bring other parts of the filesystem under the <directive
96 module="core">DocumentRoot</directive>. For security reasons,
97 Apache will follow symbolic links only if the <directive
98 module="core">Options</directive> setting for the relevant
99 directory includes <code>FollowSymLinks</code> or
100 <code>SymLinksIfOwnerMatch</code>.</p>
102 <p>Alternatively, the <directive
103 module="mod_alias">Alias</directive> directive will map any part
104 of the filesystem into the web space. For example, with</p>
106 <example>Alias /docs /var/web</example>
108 <p>the URL <code>http://www.example.com/docs/dir/file.html</code>
109 will be served from <code>/var/web/dir/file.html</code>. The
110 <directive module="mod_alias">ScriptAlias</directive> directive
111 works the same way, with the additional effect that all content
112 located at the target path is treated as CGI scripts.</p>
114 <p>For situations where you require additional flexibility, you
115 can use the <directive module="mod_alias">AliasMatch</directive> and
116 <directive module="mod_alias">ScriptAliasMatch</directive>
117 directives to do powerful regular-expression based matching and
118 substitution. For example,</p>
120 <example>ScriptAliasMatch ^/~([a-zA-Z0-9]+)/cgi-bin/(.+)
121 /home/$1/cgi-bin/$2</example>
123 <p>will map a request to
124 <code>http://example.com/~user/cgi-bin/script.cgi</code> to the
125 path <code>/home/user/cgi-bin/script.cgi</code> and will treat
126 the resulting file as a CGI script.</p>
129 <section id="user"><title>User Directories</title>
131 <p>Traditionally on Unix systems, the home directory of a
132 particular <em>user</em> can be referred to as
133 <code>~user/</code>. The module <module>mod_userdir</module>
134 extends this idea to the web by allowing files under each user's
135 home directory to be accessed using URLs such as the
138 <example>http://www.example.com/~user/file.html</example>
140 <p>For security reasons, it is inappropriate to give direct
141 access to a user's home directory from the web. Therefore, the
142 <directive module="mod_userdir">UserDir</directive> directive
143 specifies a directory underneath the user's home directory
144 where web files are located. Using the default setting of
145 <code>Userdir public_html</code>, the above URL maps to a file
147 <code>/home/user/public_html/file.html</code> where
148 <code>/home/user/</code> is the user's home directory as
149 specified in <code>/etc/passwd</code>.</p>
151 <p>There are also several other forms of the
152 <code>Userdir</code> directive which you can use on systems
153 where <code>/etc/passwd</code> does not contain the location of
154 the home directory.</p>
156 <p>Some people find the "~" symbol (which is often encoded on the
157 web as <code>%7e</code>) to be awkward and prefer to use an
158 alternate string to represent user directories. This functionality
159 is not supported by mod_userdir. However, if users' home
160 directories are structured in a regular way, then it is possible
161 to use the <directive module="mod_alias">AliasMatch</directive>
162 directive to achieve the desired effect. For example, to make
163 <code>http://www.example.com/upages/user/file.html</code> map to
164 <code>/home/user/public_html/file.html</code>, use the following
165 <code>AliasMatch</code> directive:</p>
167 <example>AliasMatch ^/upages/([a-zA-Z0-9]+)/?(.*)
168 /home/$1/public_html/$2</example>
171 <section id="redirect"><title>URL Redirection</title>
173 <p>The configuration directives discussed in the above sections
174 tell Apache to get content from a specific place in the filesystem
175 and return it to the client. Sometimes, it is desirable instead to
176 inform the client that the requested content is located at a
177 different URL, and instruct the client to make a new request with
178 the new URL. This is called <em>redirection</em> and is
179 implemented by the <directive
180 module="mod_alias">Redirect</directive> directive. For example, if
181 the contents of the directory <code>/foo/</code> under the
182 <directive module="core">DocumentRoot</directive> are moved
183 to the new directory <code>/bar/</code>, you can instruct clients
184 to request the content at the new location as follows:</p>
186 <example>Redirect permanent /foo/
187 http://www.example.com/bar/</example>
189 <p>This will redirect any URL-Path starting in
190 <code>/foo/</code> to the same URL path on the
191 <code>www.example.com</code> server with <code>/bar/</code>
192 substituted for <code>/foo/</code>. You can redirect clients to
193 any server, not only the origin server.</p>
195 <p>Apache also provides a <directive
196 module="mod_alias">RedirectMatch</directive> directive for more
197 complicated rewriting problems. For example, to redirect requests
198 for the site home page to a different site, but leave all other
199 requests alone, use the following configuration:</p>
201 <example>RedirectMatch permanent ^/$
202 http://www.example.com/startpage.html</example>
204 <p>Alternatively, to temporarily redirect all pages on one site
205 to a particular page on another site, use the following:</p>
207 <example>RedirectMatch temp .*
208 http://othersite.example.com/startpage.html</example>
211 <section id="proxy"><title>Reverse Proxy</title>
213 <p>Apache also allows you to bring remote documents into the URL space
214 of the local server. This technique is called <em>reverse
215 proxying</em> because the web server acts like a proxy server by
216 fetching the documents from a remote server and returning them to the
217 client. It is different from normal proxying because, to the client,
218 it appears the documents originate at the reverse proxy server.</p>
220 <p>In the following example, when clients request documents under the
221 <code>/foo/</code> directory, the server fetches those documents from
222 the <code>/bar/</code> directory on <code>internal.example.com</code>
223 and returns them to the client as if they were from the local
227 ProxyPass /foo/ http://internal.example.com/bar/<br />
228 ProxyPassReverse /foo/ http://internal.example.com/bar/
229 ProxyPassReverseCookieDomain internal.example.com public.example.com
230 ProxyPassReverseCookiePath /foo/ /bar/
233 <p>The <directive module="mod_proxy">ProxyPass</directive> configures
234 the server to fetch the appropriate documents, while the
235 <directive module="mod_proxy">ProxyPassReverse</directive>
236 directive rewrites redirects originating at
237 <code>internal.example.com</code> so that they target the appropriate
238 directory on the local server. Similarly, the
239 <directive module="mod_proxy">ProxyPassReverseCookieDomain</directive>
240 and <directive module="mod_proxy">ProxyPassReverseCookieDomain</directive>
241 rewrite cookies set by the backend server.</p>
242 <p>It is important to note, however, that
243 links inside the documents will not be rewritten. So any absolute
244 links on <code>internal.example.com</code> will result in the client
245 breaking out of the proxy server and requesting directly from
246 <code>internal.example.com</code>. A third-party module
247 <a href="http://apache.webthing.com/mod_proxy_html/">mod_proxy_html</a>
248 is available to rewrite links in HTML and XHTML.</p>
251 <section id="rewrite"><title>Rewriting Engine</title>
253 <p>When even more powerful substitution is required, the rewriting
254 engine provided by <module>mod_rewrite</module>
255 can be useful. The directives provided by this module use
256 characteristics of the request such as browser type or source IP
257 address in deciding from where to serve content. In addition,
258 mod_rewrite can use external database files or programs to
259 determine how to handle a request. The rewriting engine is capable
260 of performing all three types of mappings discussed above:
261 internal redirects (aliases), external redirects, and proxying.
262 Many practical examples employing mod_rewrite are discussed in the
263 <a href="misc/rewriteguide.html">URL Rewriting Guide</a>.</p>
266 <section id="notfound"><title>File Not Found</title>
268 <p>Inevitably, URLs will be requested for which no matching
269 file can be found in the filesystem. This can happen for
270 several reasons. In some cases, it can be a result of moving
271 documents from one location to another. In this case, it is
272 best to use <a href="#redirect">URL redirection</a> to inform
273 clients of the new location of the resource. In this way, you
274 can assure that old bookmarks and links will continue to work,
275 even though the resource is at a new location.</p>
277 <p>Another common cause of "File Not Found" errors is
278 accidental mistyping of URLs, either directly in the browser,
279 or in HTML links. Apache provides the module
280 <module>mod_speling</module> (sic) to help with
281 this problem. When this module is activated, it will intercept
282 "File Not Found" errors and look for a resource with a similar
283 filename. If one such file is found, mod_speling will send an
284 HTTP redirect to the client informing it of the correct
285 location. If several "close" files are found, a list of
286 available alternatives will be presented to the client.</p>
288 <p>An especially useful feature of mod_speling, is that it will
289 compare filenames without respect to case. This can help
290 systems where users are unaware of the case-sensitive nature of
291 URLs and the unix filesystem. But using mod_speling for
292 anything more than the occasional URL correction can place
293 additional load on the server, since each "incorrect" request
294 is followed by a URL redirection and a new request from the
297 <p>If all attempts to locate the content fail, Apache returns
298 an error page with HTTP status code 404 (file not found). The
299 appearance of this page is controlled with the
300 <directive module="core">ErrorDocument</directive> directive
301 and can be customized in a flexible manner as discussed in the
302 <a href="custom-error.html">Custom error responses</a>