VladPolskiy/apache-http-server
1
0
Fork 0
mirror of https://github.com/apache/httpd.git synced 2025-08-15 23:27:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

Ran w3c tidy on these as 'tidy -mi -asxml' to get xhtml. Please verify,

Browse Source 
in particular, the non-english files, to make sure I did not screw
anything up. They look fine to me.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91112 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Rich Bowen
2001-09-22 18:53:20 +00:00
parent 64670c57ff
commit 1bf05b9838
47 changed files with 10378 additions and 9352 deletions
Download Patch File Download Diff File Expand all files Collapse all files

457
docs/manual/urlmapping.html.en
View File

@ -1,247 +1,296 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE>Mapping URLs to Filesystem Locations - Apache HTTP Server</TITLE>
</HEAD>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- 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>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org" />
<p>This document explains how Apache uses the URL of a request to
determine the filesystem location from which to serve a file.</p>
<title>Mapping URLs to Filesystem Locations - Apache HTTP
Server</title>
</head>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<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="#rewrite">Rewrite Engine</a></li>
<li><a href="#notfound">File Not Found</a></li>
</ul>
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
vlink="#000080" alink="#FF0000">
<!--#include virtual="header.html" -->
<hr>
<h1 align="center">Mapping URLs to Filesystem Locations</h1>
<table border="1">
<tr><td valign="top">
<strong>Related Modules</strong><br><br>
<p>This document explains how Apache uses the URL of a request
to determine the filesystem location from which to serve a
file.</p>
<a href="mod/mod_alias.html">mod_alias</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>
<ul>
<li><a href="#documentroot">DocumentRoot</a></li>
</td><td valign="top">
<strong>Related Directives</strong><br><br>
<li><a href="#outside">Files Outside the
DocumentRoot</a></li>
<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_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>
<li><a href="#user">User Directories</a></li>
</td></tr></table>
<li><a href="#redirect">URL Redirection</a></li>
<h2><a name="documentroot">DocumentRoot</a></h2>
<li><a href="#rewrite">Rewrite Engine</a></li>
<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>
<li><a href="#notfound">File Not Found</a></li>
</ul>
<hr />
<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>
<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_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>
<h2><a name="outside">Files Outside the DocumentRoot</a></h2>
<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_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>
<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>
<h2><a id="documentroot"
name="documentroot">DocumentRoot</a></h2>
<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>
<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>
<blockquote><code>Alias /docs /var/web/
</code></blockquote>
<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>
<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>
<h2><a id="outside" name="outside">Files Outside the
DocumentRoot</a></h2>
<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>
<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>
<blockquote><code> ScriptAliasMatch ^/~([^/]*)/cgi-bin/(.*)
/home/$1/cgi-bin/$2 </code></blockquote>
<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>
<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>
<blockquote>
<code>Alias /docs /var/web/</code>
</blockquote>
<h2><a name="user">User Directories</a></h2>
<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>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>
<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>http://www.example.com/~user/file.html</code></blockquote>
<blockquote>
<code>ScriptAliasMatch ^/~([^/]*)/cgi-bin/(.*)
/home/$1/cgi-bin/$2</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>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>
<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>
<h2><a id="user" name="user">User Directories</a></h2>
<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>
<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>
AliasMatch ^/upages/([^/]*)/?(.*) /home/$1/public_html/$2
</code></blockquote>
<blockquote>
<code>http://www.example.com/~user/file.html</code>
</blockquote>
<h2><a name="redirect">URL Redirection</a></h2>
<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>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>
<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>
<blockquote><code>Redirect permanent
/foo/ http://www.example.com/bar/</code></blockquote>
<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>
<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>
<blockquote>
<code>AliasMatch ^/upages/([^/]*)/?(.*)
/home/$1/public_html/$2</code>
</blockquote>
<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>
<h2><a id="redirect" name="redirect">URL Redirection</a></h2>
<blockquote><code>
RedirectMatch permanent ^/$ http://www.example.com/startpage.html
</code></blockquote>
<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>
<p>Alternatively, to temporarily redirect all pages on a site to one
particular page, use the following:</p>
<blockquote>
<code>Redirect permanent /foo/
http://www.example.com/bar/</code>
</blockquote>
<blockquote><code>
RedirectMatch temp .* http://www.example.com/startpage.html
</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>
<h2><a name="rewrite">Rewriting Engine</a></h2>
<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>
<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. Many practical examples employing
mod_rewrite are discussed in the <a href="misc/rewriteguide.html">URL
Rewriting Guide</a>.</p>
<blockquote>
<code>RedirectMatch permanent ^/$
http://www.example.com/startpage.html</code>
</blockquote>
<h2><a name="notfound">File Not Found</a></h2>
<p>Alternatively, to temporarily redirect all pages on a site
to one particular page, use the following:</p>
<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>
<blockquote>
<code>RedirectMatch temp .*
http://www.example.com/startpage.html</code>
</blockquote>
<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>
<h2><a id="rewrite" name="rewrite">Rewriting Engine</a></h2>
<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>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. Many practical examples employing mod_rewrite are
discussed in the <a href="misc/rewriteguide.html">URL Rewriting
Guide</a>.</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>
<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>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>