home *** CD-ROM | disk | FTP | other *** search
/ PC World 2003 May / PCWorld_2003-05_cd.bin / Komunik / apache / apache_2.0.45-win32-x86-no_ssl.msi / Data.Cab / F232710_urlmapping.xml < prev    next >
Extensible Markup Language  |  2003-01-26  |  13KB  |  281 lines
  1. <?xml version="1.0" encoding="UTF-8" ?>
  2. <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
  3. <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
  4.  
  5. <manualpage>
  6.   <relativepath href="."/>
  7.  
  8.   <title>Mapping URLs to Filesystem Locations</title>
  9.  
  10.   <summary>
  11.     <p>This document explains how Apache uses the URL of a request
  12.     to determine the filesystem location from which to serve a
  13.     file.</p>
  14.   </summary>
  15.  
  16. <section id="related"><title>Related Modules and Directives</title>
  17.  
  18. <related>
  19. <modulelist>
  20. <module>mod_alias</module>
  21. <module>mod_proxy</module>
  22. <module>mod_rewrite</module>
  23. <module>mod_userdir</module>
  24. <module>mod_speling</module>
  25. <module>mod_vhost_alias</module>
  26. </modulelist>
  27. <directivelist>
  28. <directive module="mod_alias">Alias</directive>
  29. <directive module="mod_alias">AliasMatch</directive>
  30. <directive module="mod_speling">CheckSpelling</directive>
  31. <directive module="core">DocumentRoot</directive>
  32. <directive module="core">ErrorDocument</directive>
  33. <directive module="core">Options</directive>
  34. <directive module="mod_proxy">ProxyPass</directive>
  35. <directive module="mod_proxy">ProxyPassReverse</directive>
  36. <directive module="mod_alias">Redirect</directive>
  37. <directive module="mod_alias">RedirectMatch</directive>
  38. <directive module="mod_rewrite">RewriteCond</directive>
  39. <directive module="mod_rewrite">RewriteMatch</directive>
  40. <directive module="mod_alias">ScriptAlias</directive>
  41. <directive module="mod_alias">ScriptAliasMatch</directive>
  42. <directive module="mod_userdir">UserDir</directive>
  43. </directivelist>
  44. </related>
  45. </section>
  46.  
  47. <section id="documentroot"><title>DocumentRoot</title>
  48.  
  49.     <p>In deciding what file to serve for a given request, Apache's
  50.     default behavior is to take the URL-Path for the request (the part
  51.     of the URL following the hostname and port) and add it to the end
  52.     of the <directive module="core">DocumentRoot</directive> specified
  53.     in your configuration files. Therefore, the files and directories
  54.     underneath the <directive module="core">DocumentRoot</directive>
  55.     make up the basic document tree which will be visible from the
  56.     web.</p>
  57.  
  58.     <p>Apache is also capable of <a href="vhosts/">Virtual
  59.     Hosting</a>, where the server receives requests for more than one
  60.     host. In this case, a different <directive
  61.     module="core">DocumentRoot</directive> can be specified for each
  62.     virtual host, or alternatively, the directives provided by the
  63.     module <module>mod_vhost_alias</module> can
  64.     be used to dynamically determine the appropriate place from which
  65.     to serve content based on the requested IP address or
  66.     hostname.</p>
  67. </section>
  68.  
  69. <section id="outside"><title>Files Outside the DocumentRoot</title>
  70.  
  71.     <p>There are frequently circumstances where it is necessary to
  72.     allow web access to parts of the filesystem that are not strictly
  73.     underneath the <directive
  74.     module="core">DocumentRoot</directive>. Apache offers several
  75.     different ways to accomplish this. On Unix systems, symbolic links
  76.     can bring other parts of the filesystem under the <directive
  77.     module="core">DocumentRoot</directive>. For security reasons,
  78.     Apache will follow symbolic links only if the <directive
  79.     module="core">Options</directive> setting for the relevant
  80.     directory includes <code>FollowSymLinks</code> or
  81.     <code>SymLinksIfOwnerMatch</code>.</p>
  82.  
  83.     <p>Alternatively, the <directive
  84.     module="mod_alias">Alias</directive> directive will map any part
  85.     of the filesystem into the web space. For example, with</p>
  86.  
  87. <example>Alias /docs /var/web</example>
  88.  
  89.     <p>the URL <code>http://www.example.com/docs/dir/file.html</code>
  90.     will be served from <code>/var/web/dir/file.html</code>. The
  91.     <directive module="mod_alias">ScriptAlias</directive> directive
  92.     works the same way, with the additional effect that all content
  93.     located at the target path is treated as CGI scripts.</p>
  94.  
  95.     <p>For situations where you require additional flexibility, you
  96.     can use the <directive module="mod_alias">AliasMatch</directive> and 
  97.     <directive module="mod_alias">ScriptAliasMatch</directive>
  98.     directives to do powerful regular-expression based matching and
  99.     substitution. For example,</p>
  100.  
  101. <example>ScriptAliasMatch ^/~([a-zA-Z0-9]*)/cgi-bin/(.*)
  102.       /home/$1/cgi-bin/$2</example>
  103.  
  104.     <p>will map a request to
  105.     <code>http://example.com/~user/cgi-bin/script.cgi</code> to the
  106.     path <code>/home/user/cgi-bin/script.cgi</code> and will treat
  107.     the resulting file as a CGI script.</p>
  108. </section>
  109.  
  110. <section id="user"><title>User Directories</title>
  111.  
  112.     <p>Traditionally on Unix systems, the home directory of a
  113.     particular <em>user</em> can be referred to as
  114.     <code>~user/</code>. The module <module>mod_userdir</module>
  115.     extends this idea to the web by allowing files under each user's
  116.     home directory to be accessed using URLs such as the
  117.     following.</p>
  118.  
  119. <example>http://www.example.com/~user/file.html</example>
  120.  
  121.     <p>For security reasons, it is inappropriate to give direct
  122.     access to a user's home directory from the web. Therefore, the
  123.     <directive module="mod_userdir">UserDir</directive> directive
  124.     specifies a directory underneath the user's home directory
  125.     where web files are located. Using the default setting of
  126.     <code>Userdir public_html</code>, the above URL maps to a file
  127.     at a directory like
  128.     <code>/home/user/public_html/file.html</code> where
  129.     <code>/home/user/</code> is the user's home directory as
  130.     specified in <code>/etc/passwd</code>.</p>
  131.  
  132.     <p>There are also several other forms of the
  133.     <code>Userdir</code> directive which you can use on systems
  134.     where <code>/etc/passwd</code> does not contain the location of
  135.     the home directory.</p>
  136.  
  137.     <p>Some people find the "~" symbol (which is often encoded on the
  138.     web as <code>%7e</code>) to be awkward and prefer to use an
  139.     alternate string to represent user directories. This functionality
  140.     is not supported by mod_userdir. However, if users' home
  141.     directories are structured in a regular way, then it is possible
  142.     to use the <directive module="mod_alias">AliasMatch</directive>
  143.     directive to achieve the desired effect. For example, to make
  144.     <code>http://www.example.com/upages/user/file.html</code> map to
  145.     <code>/home/user/public_html/file.html</code>, use the following
  146.     <code>AliasMatch</code> directive:</p>
  147.  
  148. <example>AliasMatch ^/upages/([a-zA-Z0-9]*)/?(.*)
  149.       /home/$1/public_html/$2</example>
  150. </section>
  151.  
  152. <section id="redirect"><title>URL Redirection</title>
  153.  
  154.     <p>The configuration directives discussed in the above sections
  155.     tell Apache to get content from a specific place in the filesystem
  156.     and return it to the client. Sometimes, it is desirable instead to
  157.     inform the client that the requested content is located at a
  158.     different URL, and instruct the client to make a new request with
  159.     the new URL. This is called <em>redirection</em> and is
  160.     implemented by the <directive
  161.     module="mod_alias">Redirect</directive> directive. For example, if
  162.     the contents of the directory <code>/foo/</code> under the
  163.     <directive module="core">DocumentRoot</directive> are moved
  164.     to the new directory <code>/bar/</code>, you can instruct clients
  165.     to request the content at the new location as follows:</p>
  166.  
  167. <example>Redirect permanent /foo/
  168.       http://www.example.com/bar/</example>
  169.  
  170.     <p>This will redirect any URL-Path starting in
  171.     <code>/foo/</code> to the same URL path on the
  172.     <code>www.example.com</code> server with <code>/bar/</code>
  173.     substituted for <code>/foo/</code>. You can redirect clients to
  174.     any server, not only the origin server.</p>
  175.  
  176.     <p>Apache also provides a <directive
  177.     module="mod_alias">RedirectMatch</directive> directive for more
  178.     complicated rewriting problems. For example, to redirect requests
  179.     for the site home page to a different site, but leave all other
  180.     requests alone, use the following configuration:</p>
  181.  
  182. <example>RedirectMatch permanent ^/$
  183.       http://www.example.com/startpage.html</example>
  184.  
  185.     <p>Alternatively, to temporarily redirect all pages on one site
  186.     to a particular page on another site, use the following:</p>
  187.  
  188. <example>RedirectMatch temp .*
  189.       http://othersite.example.com/startpage.html</example>
  190. </section>
  191.  
  192. <section id="proxy"><title>Reverse Proxy</title>
  193.  
  194. <p>Apache also allows you to bring remote documents into the URL space
  195. of the local server.  This technique is called <em>reverse
  196. proxying</em> because the web server acts like a proxy server by
  197. fetching the documents from a remote server and returning them to the
  198. client.  It is different from normal proxying because, to the client,
  199. it appears the documents originate at the reverse proxy server.</p>
  200.  
  201. <p>In the following example, when clients request documents under the
  202. <code>/foo/</code> directory, the server fetches those documents from
  203. the <code>/bar/</code> directory on <code>internal.example.com</code>
  204. and returns them to the client as if they were from the local
  205. server.</p>
  206.  
  207. <example>
  208. ProxyPass /foo/ http://internal.example.com/bar/<br />
  209. ProxyPassReverse /foo/ http://internal.example.com/bar/
  210. </example>
  211.  
  212. <p>The <directive module="mod_proxy">ProxyPass</directive> configures
  213. the server to fetch the appropriate documents, while the
  214. <directive module="mod_proxy">ProxyPassReverse</directive>
  215. directive rewrites redirects originating at
  216. <code>internal.examle.com</code> so that they target the appropriate
  217. directory on the local server.  It is important to note, however, that
  218. links inside the documents will not be rewritten.  So any absolute
  219. links on <code>internal.example.com</code> will result in the client
  220. breaking out of the proxy server and requesting directly from
  221. <code>internal.example.com</code>.</p>
  222. </section>
  223.  
  224. <section id="rewrite"><title>Rewriting Engine</title>
  225.  
  226.     <p>When even more powerful substitution is required, the rewriting
  227.     engine provided by <module>mod_rewrite</module>
  228.     can be useful. The directives provided by this module use
  229.     characteristics of the request such as browser type or source IP
  230.     address in deciding from where to serve content. In addition,
  231.     mod_rewrite can use external database files or programs to
  232.     determine how to handle a request. The rewriting engine is capable
  233.     of performing all three types of mappings discussed above:
  234.     internal redirects (aliases), external redirects, and proxying.
  235.     Many practical examples employing mod_rewrite are discussed in the
  236.     <a href="misc/rewriteguide.html">URL Rewriting Guide</a>.</p>
  237. </section>
  238.  
  239. <section id="notfound"><title>File Not Found</title>
  240.  
  241.     <p>Inevitably, URLs will be requested for which no matching
  242.     file can be found in the filesystem. This can happen for
  243.     several reasons. In some cases, it can be a result of moving
  244.     documents from one location to another. In this case, it is
  245.     best to use <a href="#redirect">URL redirection</a> to inform
  246.     clients of the new location of the resource. In this way, you
  247.     can assure that old bookmarks and links will continue to work,
  248.     even though the resource is at a new location.</p>
  249.  
  250.     <p>Another common cause of "File Not Found" errors is
  251.     accidental mistyping of URLs, either directly in the browser,
  252.     or in HTML links. Apache provides the module
  253.     <module>mod_speling</module> (sic) to help with
  254.     this problem. When this module is activated, it will intercept
  255.     "File Not Found" errors and look for a resource with a similar
  256.     filename. If one such file is found, mod_speling will send an
  257.     HTTP redirect to the client informing it of the correct
  258.     location. If several "close" files are found, a list of
  259.     available alternatives will be presented to the client.</p>
  260.  
  261.     <p>An especially useful feature of mod_speling, is that it will
  262.     compare filenames without respect to case. This can help
  263.     systems where users are unaware of the case-sensitive nature of
  264.     URLs and the unix filesystem. But using mod_speling for
  265.     anything more than the occasional URL correction can place
  266.     additional load on the server, since each "incorrect" request
  267.     is followed by a URL redirection and a new request from the
  268.     client.</p>
  269.  
  270.     <p>If all attempts to locate the content fail, Apache returns
  271.     an error page with HTTP status code 404 (file not found). The
  272.     appearance of this page is controlled with the
  273.     <directive module="core">ErrorDocument</directive> directive
  274.     and can be customized in a flexible manner as discussed in the
  275.     <a href="custom-error.html">Custom error responses</a> and <a
  276.     href="misc/custom_errordocs.html">International Server Error
  277.     Responses</a> documents.</p>
  278. </section>
  279.  
  280. </manualpage>
  281.