1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- 4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5 This file is generated from xml source: DO NOT EDIT 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 --> 8<title>Mapping URLs to Filesystem Locations - Apache HTTP Server</title> 9<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 10<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 11<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body id="manual-page"><div id="page-header"> 17<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 18<p class="apache">Apache HTTP Server Version 2.2</p> 19<img alt="" src="/images/feather.gif" /></div> 20<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 21<div id="path"> 22<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="./">Version 2.2</a></div><div id="page-content"><div id="preamble"><h1>Mapping URLs to Filesystem Locations</h1> 23<div class="toplang"> 24<p><span>Available Languages: </span><a href="/en/urlmapping.html" title="English"> en </a> | 25<a href="/ja/urlmapping.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 26<a href="/ko/urlmapping.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> | 27<a href="/tr/urlmapping.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 28</div> 29 30 <p>This document explains how Apache uses the URL of a request 31 to determine the filesystem location from which to serve a 32 file.</p> 33 </div> 34<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#related">Related Modules and Directives</a></li> 35<li><img alt="" src="/images/down.gif" /> <a href="#documentroot">DocumentRoot</a></li> 36<li><img alt="" src="/images/down.gif" /> <a href="#outside">Files Outside the DocumentRoot</a></li> 37<li><img alt="" src="/images/down.gif" /> <a href="#user">User Directories</a></li> 38<li><img alt="" src="/images/down.gif" /> <a href="#redirect">URL Redirection</a></li> 39<li><img alt="" src="/images/down.gif" /> <a href="#proxy">Reverse Proxy</a></li> 40<li><img alt="" src="/images/down.gif" /> <a href="#rewrite">Rewriting Engine</a></li> 41<li><img alt="" src="/images/down.gif" /> <a href="#notfound">File Not Found</a></li> 42</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 43<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 44<div class="section"> 45<h2><a name="related" id="related">Related Modules and Directives</a></h2> 46 47<table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="/mod/mod_alias.html">mod_alias</a></code></li><li><code class="module"><a href="/mod/mod_proxy.html">mod_proxy</a></code></li><li><code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code></li><li><code class="module"><a href="/mod/mod_userdir.html">mod_userdir</a></code></li><li><code class="module"><a href="/mod/mod_speling.html">mod_speling</a></code></li><li><code class="module"><a href="/mod/mod_vhost_alias.html">mod_vhost_alias</a></code></li></ul></td><td><ul><li><code class="directive"><a href="/mod/mod_alias.html#alias">Alias</a></code></li><li><code class="directive"><a href="/mod/mod_alias.html#aliasmatch">AliasMatch</a></code></li><li><code class="directive"><a href="/mod/mod_speling.html#checkspelling">CheckSpelling</a></code></li><li><code class="directive"><a href="/mod/core.html#documentroot">DocumentRoot</a></code></li><li><code class="directive"><a href="/mod/core.html#errordocument">ErrorDocument</a></code></li><li><code class="directive"><a href="/mod/core.html#options">Options</a></code></li><li><code class="directive"><a href="/mod/mod_proxy.html#proxypass">ProxyPass</a></code></li><li><code class="directive"><a href="/mod/mod_proxy.html#proxypassreverse">ProxyPassReverse</a></code></li><li><code class="directive"><a href="/mod/mod_proxy.html#proxypassreversecookiedomain">ProxyPassReverseCookieDomain</a></code></li><li><code class="directive"><a href="/mod/mod_proxy.html#proxypassreversecookiepath">ProxyPassReverseCookiePath</a></code></li><li><code class="directive"><a href="/mod/mod_alias.html#redirect">Redirect</a></code></li><li><code class="directive"><a href="/mod/mod_alias.html#redirectmatch">RedirectMatch</a></code></li><li><code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code></li><li><code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code></li><li><code class="directive"><a href="/mod/mod_alias.html#scriptalias">ScriptAlias</a></code></li><li><code class="directive"><a href="/mod/mod_alias.html#scriptaliasmatch">ScriptAliasMatch</a></code></li><li><code class="directive"><a href="/mod/mod_userdir.html#userdir">UserDir</a></code></li></ul></td></tr></table> 48</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 49<div class="section"> 50<h2><a name="documentroot" id="documentroot">DocumentRoot</a></h2> 51 52 <p>In deciding what file to serve for a given request, Apache's 53 default behavior is to take the URL-Path for the request (the part 54 of the URL following the hostname and port) and add it to the end 55 of the <code class="directive"><a href="/mod/core.html#documentroot">DocumentRoot</a></code> specified 56 in your configuration files. Therefore, the files and directories 57 underneath the <code class="directive"><a href="/mod/core.html#documentroot">DocumentRoot</a></code> 58 make up the basic document tree which will be visible from the 59 web.</p> 60 61 <p>For example, if <code class="directive"><a href="/mod/core.html#documentroot">DocumentRoot</a></code> 62 were set to <code>/var/www/html</code> then a request for 63 <code>http://www.example.com/fish/guppies.html</code> would result 64 in the file <code>/var/www/html/fish/guppies.html</code> being 65 served to the requesting client.</p> 66 67 <p>Apache is also capable of <a href="vhosts/">Virtual 68 Hosting</a>, where the server receives requests for more than one 69 host. In this case, a different <code class="directive"><a href="/mod/core.html#documentroot">DocumentRoot</a></code> can be specified for each 70 virtual host, or alternatively, the directives provided by the 71 module <code class="module"><a href="/mod/mod_vhost_alias.html">mod_vhost_alias</a></code> can 72 be used to dynamically determine the appropriate place from which 73 to serve content based on the requested IP address or 74 hostname.</p> 75 76 <p>The <code class="directive"><a href="/mod/core.html#documentroot">DocumentRoot</a></code> directive 77 is set in your main server configuration file 78 (<code>httpd.conf</code>) and, possibly, once per additional <a href="vhosts/">Virtual Host</a> you create.</p> 79</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 80<div class="section"> 81<h2><a name="outside" id="outside">Files Outside the DocumentRoot</a></h2> 82 83 <p>There are frequently circumstances where it is necessary to 84 allow web access to parts of the filesystem that are not strictly 85 underneath the <code class="directive"><a href="/mod/core.html#documentroot">DocumentRoot</a></code>. Apache offers several 86 different ways to accomplish this. On Unix systems, symbolic links 87 can bring other parts of the filesystem under the <code class="directive"><a href="/mod/core.html#documentroot">DocumentRoot</a></code>. For security reasons, 88 Apache will follow symbolic links only if the <code class="directive"><a href="/mod/core.html#options">Options</a></code> setting for the relevant 89 directory includes <code>FollowSymLinks</code> or 90 <code>SymLinksIfOwnerMatch</code>.</p> 91 92 <p>Alternatively, the <code class="directive"><a href="/mod/mod_alias.html#alias">Alias</a></code> directive will map any part 93 of the filesystem into the web space. For example, with</p> 94 95<div class="example"><p><code>Alias /docs /var/web</code></p></div> 96 97 <p>the URL <code>http://www.example.com/docs/dir/file.html</code> 98 will be served from <code>/var/web/dir/file.html</code>. The 99 <code class="directive"><a href="/mod/mod_alias.html#scriptalias">ScriptAlias</a></code> directive 100 works the same way, with the additional effect that all content 101 located at the target path is treated as <a class="glossarylink" href="/glossary.html#cgi" title="see glossary">CGI</a> scripts.</p> 102 103 <p>For situations where you require additional flexibility, you 104 can use the <code class="directive"><a href="/mod/mod_alias.html#aliasmatch">AliasMatch</a></code> 105 and <code class="directive"><a href="/mod/mod_alias.html#scriptaliasmatch">ScriptAliasMatch</a></code> 106 directives to do powerful <a class="glossarylink" href="/glossary.html#regex" title="see glossary">regular 107 expression</a> based matching and substitution. For 108 example,</p> 109 110<div class="example"><p><code>ScriptAliasMatch ^/~([a-zA-Z0-9]+)/cgi-bin/(.+) 111 /home/$1/cgi-bin/$2</code></p></div> 112 113 <p>will map a request to 114 <code>http://example.com/~user/cgi-bin/script.cgi</code> to the 115 path <code>/home/user/cgi-bin/script.cgi</code> and will treat 116 the resulting file as a CGI script.</p> 117</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 118<div class="section"> 119<h2><a name="user" id="user">User Directories</a></h2> 120 121 <p>Traditionally on Unix systems, the home directory of a 122 particular <em>user</em> can be referred to as 123 <code>~user/</code>. The module <code class="module"><a href="/mod/mod_userdir.html">mod_userdir</a></code> 124 extends this idea to the web by allowing files under each user's 125 home directory to be accessed using URLs such as the 126 following.</p> 127 128<div class="example"><p><code>http://www.example.com/~user/file.html</code></p></div> 129 130 <p>For security reasons, it is inappropriate to give direct 131 access to a user's home directory from the web. Therefore, the 132 <code class="directive"><a href="/mod/mod_userdir.html#userdir">UserDir</a></code> directive 133 specifies a directory underneath the user's home directory 134 where web files are located. Using the default setting of 135 <code>Userdir public_html</code>, the above URL maps to a file 136 at a directory like 137 <code>/home/user/public_html/file.html</code> where 138 <code>/home/user/</code> is the user's home directory as 139 specified in <code>/etc/passwd</code>.</p> 140 141 <p>There are also several other forms of the 142 <code>Userdir</code> directive which you can use on systems 143 where <code>/etc/passwd</code> does not contain the location of 144 the home directory.</p> 145 146 <p>Some people find the "~" symbol (which is often encoded on the 147 web as <code>%7e</code>) to be awkward and prefer to use an 148 alternate string to represent user directories. This functionality 149 is not supported by mod_userdir. However, if users' home 150 directories are structured in a regular way, then it is possible 151 to use the <code class="directive"><a href="/mod/mod_alias.html#aliasmatch">AliasMatch</a></code> 152 directive to achieve the desired effect. For example, to make 153 <code>http://www.example.com/upages/user/file.html</code> map to 154 <code>/home/user/public_html/file.html</code>, use the following 155 <code>AliasMatch</code> directive:</p> 156 157<div class="example"><p><code>AliasMatch ^/upages/([a-zA-Z0-9]+)/?(.*) 158 /home/$1/public_html/$2</code></p></div> 159</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 160<div class="section"> 161<h2><a name="redirect" id="redirect">URL Redirection</a></h2> 162 163 <p>The configuration directives discussed in the above sections 164 tell Apache to get content from a specific place in the filesystem 165 and return it to the client. Sometimes, it is desirable instead to 166 inform the client that the requested content is located at a 167 different URL, and instruct the client to make a new request with 168 the new URL. This is called <em>redirection</em> and is 169 implemented by the <code class="directive"><a href="/mod/mod_alias.html#redirect">Redirect</a></code> directive. For example, if 170 the contents of the directory <code>/foo/</code> under the 171 <code class="directive"><a href="/mod/core.html#documentroot">DocumentRoot</a></code> are moved 172 to the new directory <code>/bar/</code>, you can instruct clients 173 to request the content at the new location as follows:</p> 174 175<div class="example"><p><code>Redirect permanent /foo/ 176 http://www.example.com/bar/</code></p></div> 177 178 <p>This will redirect any URL-Path starting in 179 <code>/foo/</code> to the same URL path on the 180 <code>www.example.com</code> server with <code>/bar/</code> 181 substituted for <code>/foo/</code>. You can redirect clients to 182 any server, not only the origin server.</p> 183 184 <p>Apache also provides a <code class="directive"><a href="/mod/mod_alias.html#redirectmatch">RedirectMatch</a></code> directive for more 185 complicated rewriting problems. For example, to redirect requests 186 for the site home page to a different site, but leave all other 187 requests alone, use the following configuration:</p> 188 189<div class="example"><p><code>RedirectMatch permanent ^/$ 190 http://www.example.com/startpage.html</code></p></div> 191 192 <p>Alternatively, to temporarily redirect all pages on one site 193 to a particular page on another site, use the following:</p> 194 195<div class="example"><p><code>RedirectMatch temp .* 196 http://othersite.example.com/startpage.html</code></p></div> 197</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 198<div class="section"> 199<h2><a name="proxy" id="proxy">Reverse Proxy</a></h2> 200 201<p>Apache also allows you to bring remote documents into the URL space 202of the local server. This technique is called <em>reverse 203proxying</em> because the web server acts like a proxy server by 204fetching the documents from a remote server and returning them to the 205client. It is different from normal proxying because, to the client, 206it appears the documents originate at the reverse proxy server.</p> 207 208<p>In the following example, when clients request documents under the 209<code>/foo/</code> directory, the server fetches those documents from 210the <code>/bar/</code> directory on <code>internal.example.com</code> 211and returns them to the client as if they were from the local 212server.</p> 213 214<div class="example"><p><code> 215ProxyPass /foo/ http://internal.example.com/bar/<br /> 216ProxyPassReverse /foo/ http://internal.example.com/bar/<br /> 217ProxyPassReverseCookieDomain internal.example.com public.example.com<br /> 218ProxyPassReverseCookiePath /foo/ /bar/ 219</code></p></div> 220 221<p>The <code class="directive"><a href="/mod/mod_proxy.html#proxypass">ProxyPass</a></code> configures 222the server to fetch the appropriate documents, while the 223<code class="directive"><a href="/mod/mod_proxy.html#proxypassreverse">ProxyPassReverse</a></code> 224directive rewrites redirects originating at 225<code>internal.example.com</code> so that they target the appropriate 226directory on the local server. Similarly, the 227<code class="directive"><a href="/mod/mod_proxy.html#proxypassreversecookiedomain">ProxyPassReverseCookieDomain</a></code> 228and <code class="directive"><a href="/mod/mod_proxy.html#proxypassreversecookiepath">ProxyPassReverseCookiePath</a></code> 229rewrite cookies set by the backend server.</p> 230<p>It is important to note, however, that 231links inside the documents will not be rewritten. So any absolute 232links on <code>internal.example.com</code> will result in the client 233breaking out of the proxy server and requesting directly from 234<code>internal.example.com</code>. A third-party module 235<a href="http://apache.webthing.com/mod_proxy_html/">mod_proxy_html</a> 236is available to rewrite links in HTML and XHTML.</p> 237</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 238<div class="section"> 239<h2><a name="rewrite" id="rewrite">Rewriting Engine</a></h2> 240 241 <p>When even more powerful substitution is required, the rewriting 242 engine provided by <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> 243 can be useful. The directives provided by this module use 244 characteristics of the request such as browser type or source IP 245 address in deciding from where to serve content. In addition, 246 mod_rewrite can use external database files or programs to 247 determine how to handle a request. The rewriting engine is capable 248 of performing all three types of mappings discussed above: 249 internal redirects (aliases), external redirects, and proxying. 250 Many practical examples employing mod_rewrite are discussed in the 251 <a href="rewrite/">detailed mod_rewrite documentation</a>.</p> 252</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 253<div class="section"> 254<h2><a name="notfound" id="notfound">File Not Found</a></h2> 255 256 <p>Inevitably, URLs will be requested for which no matching 257 file can be found in the filesystem. This can happen for 258 several reasons. In some cases, it can be a result of moving 259 documents from one location to another. In this case, it is 260 best to use <a href="#redirect">URL redirection</a> to inform 261 clients of the new location of the resource. In this way, you 262 can assure that old bookmarks and links will continue to work, 263 even though the resource is at a new location.</p> 264 265 <p>Another common cause of "File Not Found" errors is 266 accidental mistyping of URLs, either directly in the browser, 267 or in HTML links. Apache provides the module 268 <code class="module"><a href="/mod/mod_speling.html">mod_speling</a></code> (sic) to help with 269 this problem. When this module is activated, it will intercept 270 "File Not Found" errors and look for a resource with a similar 271 filename. If one such file is found, mod_speling will send an 272 HTTP redirect to the client informing it of the correct 273 location. If several "close" files are found, a list of 274 available alternatives will be presented to the client.</p> 275 276 <p>An especially useful feature of mod_speling, is that it will 277 compare filenames without respect to case. This can help 278 systems where users are unaware of the case-sensitive nature of 279 URLs and the unix filesystem. But using mod_speling for 280 anything more than the occasional URL correction can place 281 additional load on the server, since each "incorrect" request 282 is followed by a URL redirection and a new request from the 283 client.</p> 284 285 <p>If all attempts to locate the content fail, Apache returns 286 an error page with HTTP status code 404 (file not found). The 287 appearance of this page is controlled with the 288 <code class="directive"><a href="/mod/core.html#errordocument">ErrorDocument</a></code> directive 289 and can be customized in a flexible manner as discussed in the 290 <a href="custom-error.html">Custom error responses</a> 291 document.</p> 292</div></div> 293<div class="bottomlang"> 294<p><span>Available Languages: </span><a href="/en/urlmapping.html" title="English"> en </a> | 295<a href="/ja/urlmapping.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 296<a href="/ko/urlmapping.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> | 297<a href="/tr/urlmapping.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 298</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 299<script type="text/javascript"><!--//--><![CDATA[//><!-- 300var comments_shortname = 'httpd'; 301var comments_identifier = 'http://httpd.apache.org/docs/2.2/urlmapping.html'; 302(function(w, d) { 303 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 304 d.write('<div id="comments_thread"><\/div>'); 305 var s = d.createElement('script'); 306 s.type = 'text/javascript'; 307 s.async = true; 308 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 309 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 310 } 311 else { 312 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 313 } 314})(window, document); 315//--><!]]></script></div><div id="footer"> 316<p class="apache">Copyright 2013 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> 317<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 318if (typeof(prettyPrint) !== 'undefined') { 319 prettyPrint(); 320} 321//--><!]]></script> 322</body></html>
