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