</td></tr><tr><td>
<a href="server-wide.html">Server-Wide Configuration</A>
</td></tr><tr><td>
+<A HREF="urlmapping.html">>Mapping URLs to the Filesystem</A>
+</td></tr><tr><td>
<A HREF="vhosts/">Virtual Hosts</A>
</td></tr><tr><td>
<A HREF="handler.html">Handlers</A>
</td></tr><tr><td>
<a href="server-wide.html">Server-Wide Configuration</A>
</td></tr><tr><td>
+<A HREF="urlmapping.html">>Mapping URLs to the Filesystem</A>
+</td></tr><tr><td>
<A HREF="vhosts/">Virtual Hosts</A>
</td></tr><tr><td>
<A HREF="handler.html">Handlers</A>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<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 the method in which Apache determines
+what filesystem location to serve a file from based on the
+URL of a request.</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="#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_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_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 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 first single slash) 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 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 which 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 be used to bring other parts of the
+filesystem under the <code>DocumentRoot</code>. For security reasons,
+symbolic links will only be followed 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 can be used to map any part of the filesystem into the web
+space. For example, with</p>
+
+<blockquote><code>Alias /docs /var/web/
+</blockquote></code>
+
+<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 additional flexibility is required, the <a
+href="mod/mod_alias.html#aliasmatch">AliasMatch</a> and <a
+href="mod/mod_alias.html#scriptaliasmatch">ScriptAliasMatch</a>
+directives can do powerful <a
+href="misc/FAQ.html#regex">regular-expression</a> based matching and
+substitution. For example,</p>
+
+<blockquote><code> ScriptAliasMatch ^/~([^/]*)/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 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 would be 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 is used to
+specify a directory underneath the user's home directory where web
+files will be located. Using the default setting of <code>Userdir
+public_html</code>, the above URL would look for a file at a directory
+like <code>/home/user/public_html/file.html</code> where the
+</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 can be used on systems where <code>/etc/passwd</code>
+cannot be used to find 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>, the following
+<code>AliasMatch</code> directive can be used.</p>
+
+<blockquote><code>
+AliasMatch ^/upages/([^/]*)/?(.*) /home/$1/public_html/$2
+</code></blockquote>
+
+<h2><a name="redirect">URL Redirection</a></h2>
+
+<p>The configuration directives discussed in the above sections are
+used to 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 content being requested is
+located at an different URL, and instruct the client to make a new
+request with the new URL. This is referred to as <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> have been moved to the new directory
+<code>/bar/</code>, clients can instructed 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>. Note that
+clients can be redirected to any server, not only the origin
+server.</p>
+
+<p>Apache also provides a <a
+href="mod/mod_alias.html#redirectmatch">RedirectMatch</a> directive
+which can be used 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, the following configuration
+can be used.</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, the following configuration is useful.</p>
+
+<blockquote><code>
+RedirectMatch temp .* http://www.example.com/startpage.html
+</code></blockquote>
+
+<h2><a 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 can 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>
+
+<h2><a 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">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 be useful for
+systems where users are unaware of the case-sensitive nature of URLs
+and the unix filesystem. However, using mod_speling for anything more
+than the occasional URL correction can lead to 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>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<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 the method in which Apache determines
+what filesystem location to serve a file from based on the
+URL of a request.</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="#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_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_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 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 first single slash) 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 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 which 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 be used to bring other parts of the
+filesystem under the <code>DocumentRoot</code>. For security reasons,
+symbolic links will only be followed 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 can be used to map any part of the filesystem into the web
+space. For example, with</p>
+
+<blockquote><code>Alias /docs /var/web/
+</blockquote></code>
+
+<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 additional flexibility is required, the <a
+href="mod/mod_alias.html#aliasmatch">AliasMatch</a> and <a
+href="mod/mod_alias.html#scriptaliasmatch">ScriptAliasMatch</a>
+directives can do powerful <a
+href="misc/FAQ.html#regex">regular-expression</a> based matching and
+substitution. For example,</p>
+
+<blockquote><code> ScriptAliasMatch ^/~([^/]*)/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 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 would be 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 is used to
+specify a directory underneath the user's home directory where web
+files will be located. Using the default setting of <code>Userdir
+public_html</code>, the above URL would look for a file at a directory
+like <code>/home/user/public_html/file.html</code> where the
+</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 can be used on systems where <code>/etc/passwd</code>
+cannot be used to find 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>, the following
+<code>AliasMatch</code> directive can be used.</p>
+
+<blockquote><code>
+AliasMatch ^/upages/([^/]*)/?(.*) /home/$1/public_html/$2
+</code></blockquote>
+
+<h2><a name="redirect">URL Redirection</a></h2>
+
+<p>The configuration directives discussed in the above sections are
+used to 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 content being requested is
+located at an different URL, and instruct the client to make a new
+request with the new URL. This is referred to as <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> have been moved to the new directory
+<code>/bar/</code>, clients can instructed 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>. Note that
+clients can be redirected to any server, not only the origin
+server.</p>
+
+<p>Apache also provides a <a
+href="mod/mod_alias.html#redirectmatch">RedirectMatch</a> directive
+which can be used 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, the following configuration
+can be used.</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, the following configuration is useful.</p>
+
+<blockquote><code>
+RedirectMatch temp .* http://www.example.com/startpage.html
+</code></blockquote>
+
+<h2><a 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 can 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>
+
+<h2><a 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">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 be useful for
+systems where users are unaware of the case-sensitive nature of URLs
+and the unix filesystem. However, using mod_speling for anything more
+than the occasional URL correction can lead to 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>
projects / apache / commitdiff