mirror of
https://github.com/apache/httpd.git
synced 2025-07-16 04:41:55 +03:00
3efa37f511
Submitted by: Andr� Malo <nd@perlig.de> git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@96213 13f79535-47bb-0310-9956-ffa450edef68
334 lines
14 KiB
Plaintext
Executable File
334 lines
14 KiB
Plaintext
Executable File
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>Mapping URLs to Filesystem Locations - Apache HTTP
|
|
Server</title>
|
|
</head>
|
|
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
|
|
|
|
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
|
|
vlink="#000080" alink="#FF0000">
|
|
<!--#include virtual="header.html" -->
|
|
|
|
<h1 align="center">Mapping URLs to Filesystem Locations</h1>
|
|
|
|
<p>This document explains how Apache uses the URL of a request
|
|
to determine the filesystem location from which to serve a
|
|
file.</p>
|
|
|
|
<ul>
|
|
<li><a href="#documentroot">DocumentRoot</a></li>
|
|
|
|
<li><a href="#outside">Files Outside the
|
|
DocumentRoot</a></li>
|
|
|
|
<li><a href="#user">User Directories</a></li>
|
|
|
|
<li><a href="#redirect">URL Redirection</a></li>
|
|
|
|
<li><a href="#proxy">Reverse Proxy</a></li>
|
|
|
|
<li><a href="#rewrite">Rewrite Engine</a></li>
|
|
|
|
<li><a href="#notfound">File Not Found</a></li>
|
|
</ul>
|
|
<hr />
|
|
|
|
<table border="1">
|
|
<tr>
|
|
<td valign="top"><strong>Related Modules</strong><br />
|
|
<br />
|
|
<a href="mod/mod_alias.html">mod_alias</a><br />
|
|
<a href="mod/mod_proxy.html">mod_proxy</a><br />
|
|
<a href="mod/mod_rewrite.html">mod_rewrite</a><br />
|
|
<a href="mod/mod_userdir.html">mod_userdir</a><br />
|
|
<a href="mod/mod_speling.html">mod_speling</a><br />
|
|
<a
|
|
href="mod/mod_vhost_alias.html">mod_vhost_alias</a><br />
|
|
</td>
|
|
|
|
<td valign="top"><strong>Related Directives</strong><br />
|
|
<br />
|
|
<a href="mod/mod_alias.html#alias">Alias</a><br />
|
|
<a
|
|
href="mod/mod_alias.html#aliasmatch">AliasMatch</a><br />
|
|
<a
|
|
href="mod/mod_speling.html#checkspelling">CheckSpelling</a><br />
|
|
<a
|
|
href="mod/core.html#documentroot">DocumentRoot</a><br />
|
|
<a
|
|
href="mod/core.html#errordocument">ErrorDocument</a><br />
|
|
<a href="mod/core.html#options">Options</a><br />
|
|
<a href="mod/mod_proxy.html#proxypass">ProxyPass</a><br />
|
|
<a href="mod/mod_proxy.html#proxypassreverse">ProxyPassReverse</a><br />
|
|
<a href="mod/mod_alias.html#redirect">Redirect</a><br />
|
|
<a
|
|
href="mod/mod_alias.html#redirectmatch">RedirectMatch</a><br />
|
|
<a
|
|
href="mod/mod_rewrite.html#RewriteCond">RewriteCond</a><br />
|
|
<a
|
|
href="mod/mod_rewrite.html#RewriteRule">RewriteRule</a><br />
|
|
<a
|
|
href="mod/mod_alias.html#scriptalias">ScriptAlias</a><br />
|
|
<a
|
|
href="mod/mod_alias.html#scriptaliasmatch">ScriptAliasMatch</a><br />
|
|
<a href="mod/mod_userdir.html#userdir">UserDir</a><br />
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2><a id="documentroot"
|
|
name="documentroot">DocumentRoot</a></h2>
|
|
|
|
<p>In deciding what file to serve for a given request, Apache's
|
|
default behavior is to take the URL-Path for the request (the
|
|
part of the URL following the hostname and port) and add it to
|
|
the end of the <a
|
|
href="mod/core.html#documentroot">DocumentRoot</a> specified in
|
|
your configuration files. Therefore, the files and directories
|
|
underneath the <code>DocumentRoot</code> make up the basic
|
|
document tree which will be visible from the web.</p>
|
|
|
|
<p>Apache is also capable of <a href="vhosts/">Virtual
|
|
Hosting</a>, where the server receives requests for more than
|
|
one host. In this case, a different <code>DocumentRoot</code>
|
|
can be specified for each virtual host, or alternatively, the
|
|
directives provided by the module <a
|
|
href="mod/mod_vhost_alias.html">mod_vhost_alias</a> can be used
|
|
to dynamically determine the appropriate place from which to
|
|
serve content based on the requested IP address or
|
|
hostname.</p>
|
|
|
|
<h2><a id="outside" name="outside">Files Outside the
|
|
DocumentRoot</a></h2>
|
|
|
|
<p>There are frequently circumstances where it is necessary to
|
|
allow web access to parts of the filesystem that are not
|
|
strictly underneath the <a
|
|
href="mod/core.html#documentroot">DocumentRoot</a>. Apache
|
|
offers several different ways to accomplish this. On Unix
|
|
systems, symbolic links can bring other parts of the filesystem
|
|
under the <code>DocumentRoot</code>. For security reasons,
|
|
Apache will follow symbolic links only if the <a
|
|
href="mod/core.html#options">Options</a> setting for the
|
|
relevant directory includes <code>FollowSymLinks</code> or
|
|
<code>SymLinksIfOwnerMatch</code>.</p>
|
|
|
|
<p>Alternatively, the <a
|
|
href="mod/mod_alias.html#alias">Alias</a> directive will map
|
|
any part of the filesystem into the web space. For example,
|
|
with</p>
|
|
|
|
<blockquote>
|
|
<code>Alias /docs /var/web</code>
|
|
</blockquote>
|
|
|
|
<p>the URL
|
|
<code>http://www.example.com/docs/dir/file.html</code> will be
|
|
served from <code>/var/web/dir/file.html</code>. The <a
|
|
href="mod/mod_alias.html#scriptalias">ScriptAlias</a> directive
|
|
works the same way, with the additional effect that all content
|
|
located at the target path is treated as CGI scripts.</p>
|
|
|
|
<p>For situations where you require additional flexibility, you
|
|
can use the <a
|
|
href="mod/mod_alias.html#aliasmatch">AliasMatch</a> and <a
|
|
href="mod/mod_alias.html#scriptaliasmatch">ScriptAliasMatch</a>
|
|
directives to do powerful regular-expression based matching and
|
|
substitution. For example,</p>
|
|
|
|
<blockquote>
|
|
<code>ScriptAliasMatch ^/~([a-zA-Z0-9]*)/cgi-bin/(.*)
|
|
/home/$1/cgi-bin/$2</code>
|
|
</blockquote>
|
|
|
|
<p>will map a request to
|
|
<code>http://example.com/~user/cgi-bin/script.cgi</code> to the
|
|
path <code>/home/user/cgi-bin/script.cgi</code> and will treat
|
|
the resulting file as a CGI script.</p>
|
|
|
|
<h2><a id="user" name="user">User Directories</a></h2>
|
|
|
|
<p>Traditionally on Unix systems, the home directory of a
|
|
particular <em>user</em> can be referred to as
|
|
<code>~user/</code>. The module <a
|
|
href="mod/mod_userdir.html">mod_userdir</a> extends this idea
|
|
to the web by allowing files under each user's home directory
|
|
to be accessed using URLs such as the following.</p>
|
|
|
|
<blockquote>
|
|
<code>http://www.example.com/~user/file.html</code>
|
|
</blockquote>
|
|
|
|
<p>For security reasons, it is inappropriate to give direct
|
|
access to a user's home directory from the web. Therefore, the
|
|
<a href="mod/mod_userdir.html#userdir">UserDir</a> directive
|
|
specifies a directory underneath the user's home directory
|
|
where web files are located. Using the default setting of
|
|
<code>Userdir public_html</code>, the above URL maps to a file
|
|
at a directory like
|
|
<code>/home/user/public_html/file.html</code> where
|
|
<code>/home/user/</code> is the user's home directory as
|
|
specified in <code>/etc/passwd</code>.</p>
|
|
|
|
<p>There are also several other forms of the
|
|
<code>Userdir</code> directive which you can use on systems
|
|
where <code>/etc/passwd</code> does not contain the location of
|
|
the home directory.</p>
|
|
|
|
<p>Some people find the "~" symbol (which is often encoded on
|
|
the web as <code>%7e</code>) to be awkward and prefer to use an
|
|
alternate string to represent user directories. This
|
|
functionality is not supported by mod_userdir. However, if
|
|
users' home directories are structured in a regular way, then
|
|
it is possible to use the <a
|
|
href="mod/mod_alias.html#aliasmatch">AliasMatch</a> directive
|
|
to achieve the desired effect. For example, to make
|
|
<code>http://www.example.com/upages/user/file.html</code> map
|
|
to <code>/home/user/public_html/file.html</code>, use the
|
|
following <code>AliasMatch</code> directive:</p>
|
|
|
|
<blockquote>
|
|
<code>AliasMatch ^/upages/([a-zA-Z0-9]*)/?(.*)
|
|
/home/$1/public_html/$2</code>
|
|
</blockquote>
|
|
|
|
<h2><a id="redirect" name="redirect">URL Redirection</a></h2>
|
|
|
|
<p>The configuration directives discussed in the above sections
|
|
tell Apache to get content from a specific place in the
|
|
filesystem and return it to the client. Sometimes, it is
|
|
desirable instead to inform the client that the requested
|
|
content is located at a different URL, and instruct the client
|
|
to make a new request with the new URL. This is called
|
|
<em>redirection</em> and is implemented by the <a
|
|
href="mod/mod_alias.html#redirect">Redirect</a> directive. For
|
|
example, if the contents of the directory <code>/foo/</code>
|
|
under the <code>DocumentRoot</code> are moved to the new
|
|
directory <code>/bar/</code>, you can instruct clients to
|
|
request the content at the new location as follows:</p>
|
|
|
|
<blockquote>
|
|
<code>Redirect permanent /foo/
|
|
http://www.example.com/bar/</code>
|
|
</blockquote>
|
|
|
|
<p>This will redirect any URL-Path starting in
|
|
<code>/foo/</code> to the same URL path on the
|
|
<code>www.example.com</code> server with <code>/bar/</code>
|
|
substituted for <code>/foo/</code>. You can redirect clients to
|
|
any server, not only the origin server.</p>
|
|
|
|
<p>Apache also provides a <a
|
|
href="mod/mod_alias.html#redirectmatch">RedirectMatch</a>
|
|
directive for more complicated rewriting problems. For example,
|
|
to redirect requests for the site home page to a different
|
|
site, but leave all other requests alone, use the following
|
|
configuration:</p>
|
|
|
|
<blockquote>
|
|
<code>RedirectMatch permanent ^/$
|
|
http://www.example.com/startpage.html</code>
|
|
</blockquote>
|
|
|
|
<p>Alternatively, to temporarily redirect all pages on a site
|
|
to one particular page, use the following:</p>
|
|
|
|
<blockquote>
|
|
<code>RedirectMatch temp .*
|
|
http://www.example.com/startpage.html</code>
|
|
</blockquote>
|
|
|
|
|
|
<h2><a id="proxy" name="proxy">Reverse Proxy</a></h2>
|
|
|
|
<p>Apache also allows you to bring remote documents into the URL space
|
|
of the local server. This technique is called <em>reverse
|
|
proxying</em> because the web server acts like a proxy server by
|
|
fetching the documents from a remote server and returning them to the
|
|
client. It is different from normal proxying because, to the client,
|
|
it appears the documents originate at the reverse proxy server.</p>
|
|
|
|
<p>In the following example, when clients request documents under the
|
|
<code>/foo/</code> directory, the server fetches those documents from
|
|
the <code>/bar/</code> directory on <code>internal.example.com</code>
|
|
and returns them to the client as if they were from the local
|
|
server.</p>
|
|
|
|
<blockquote>
|
|
ProxyPass /foo/ http://internal.example.com/bar/<br />
|
|
ProxyPassReverse /foo/ http://internal.example.com/bar/
|
|
</blockquote>
|
|
|
|
<p>The <a href="mod/mod_proxy.html#proxypass">ProxyPass</a> configures
|
|
the server to fetch the appropriate documents, while the <a
|
|
href="mod/mod_proxy.html#proxypassreverse">ProxyPassReverse</a>
|
|
directive rewrites redirects originating at
|
|
<code>internal.examle.com</code> so that they target the appropriate
|
|
directory on the local server. It is important to note, however, that
|
|
links inside the documents will not be rewritten. So any absolute
|
|
links on <code>internal.example.com</code> will result in the client
|
|
breaking out of the proxy server and requesting directly from
|
|
<code>internal.example.com</code>.</p>
|
|
|
|
|
|
<h2><a id="rewrite" name="rewrite">Rewriting Engine</a></h2>
|
|
|
|
<p>When even more powerful substitution is required, the rewriting
|
|
engine provided by <a href="mod/mod_rewrite.html">mod_rewrite</a>
|
|
can be useful. The directives provided by this module use
|
|
characteristics of the request such as browser type or source IP
|
|
address in deciding from where to serve content. In addition,
|
|
mod_rewrite can use external database files or programs to
|
|
determine how to handle a request. The rewriting engine is capable
|
|
of performing all three types of mappings discussed above:
|
|
internal redirects (aliases), external redirects, and proxying.
|
|
Many practical examples employing mod_rewrite are discussed in the
|
|
<a href="misc/rewriteguide.html">URL Rewriting Guide</a>.</p>
|
|
|
|
<h2><a id="notfound" name="notfound">File Not Found</a></h2>
|
|
|
|
<p>Inevitably, URLs will be requested for which no matching
|
|
file can be found in the filesystem. This can happen for
|
|
several reasons. In some cases, it can be a result of moving
|
|
documents from one location to another. In this case, it is
|
|
best to use <a href="#redirect">URL redirection</a> to inform
|
|
clients of the new location of the resource. In this way, you
|
|
can assure that old bookmarks and links will continue to work,
|
|
even though the resource is at a new location.</p>
|
|
|
|
<p>Another common cause of "File Not Found" errors is
|
|
accidental mistyping of URLs, either directly in the browser,
|
|
or in HTML links. Apache provides the module <a
|
|
href="mod/mod_speling.html">mod_speling</a> (sic) to help with
|
|
this problem. When this module is activated, it will intercept
|
|
"File Not Found" errors and look for a resource with a similar
|
|
filename. If one such file is found, mod_speling will send an
|
|
HTTP redirect to the client informing it of the correct
|
|
location. If several "close" files are found, a list of
|
|
available alternatives will be presented to the client.</p>
|
|
|
|
<p>An especially useful feature of mod_speling, is that it will
|
|
compare filenames without respect to case. This can help
|
|
systems where users are unaware of the case-sensitive nature of
|
|
URLs and the unix filesystem. But using mod_speling for
|
|
anything more than the occasional URL correction can place
|
|
additional load on the server, since each "incorrect" request
|
|
is followed by a URL redirection and a new request from the
|
|
client.</p>
|
|
|
|
<p>If all attempts to locate the content fail, Apache returns
|
|
an error page with HTTP status code 404 (file not found). The
|
|
appearance of this page is controlled with the <a
|
|
href="mod/core.html#errordocument">ErrorDocument</a> directive
|
|
and can be customized in a flexible manner as discussed in the
|
|
<a href="custom-error.html">Custom error responses</a> and <a
|
|
href="misc/custom_errordocs.html">International Server Error
|
|
Responses</a> documents.</p>
|
|
<!--#include virtual="footer.html" -->
|
|
</body>
|
|
</html>
|
|
|