Split the Access Control stuff off into it's own howto, because I wanted

to do some stuff that really isn't auth related.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@355768 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 99 insertions, 154 deletions

diff --git a/docs/manual/howto/auth.html.en b/docs/manual/howto/auth.html.en
index 1bb97e2698..1fcbc4e578 100644
--- a/docs/manual/howto/auth.html.en
+++ b/docs/manual/howto/auth.html.en
@@ -35,8 +35,6 @@
 <li><img alt="" src="../images/down.gif" /> <a href="#lettingmorethanonepersonin">Letting more than one
 person in</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#possibleproblems">Possible problems</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#whatotherneatstuffcanido">What other neat stuff can I
-do?</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#moreinformation">More information</a></li>
 </ul></div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
@@ -90,6 +88,9 @@ module from each group.</p>
   of the request, but is not part of the authentication provider
   system.</p>
 
+  <p>You probably also want to take a look at the <a href="access.html">Access Control</a> howto, which discusses the
+  various ways to control access to your server.</p>
+
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="introduction" id="introduction">Introduction</a></h2>
@@ -100,6 +101,11 @@ module from each group.</p>
 
     <p>This article covers the "standard" way of protecting parts
     of your web site that most of you are going to use.</p>
+
+    <div class="note"><h3>Note:</h3>
+    <p>If your data really needs to be secure, consider using
+    <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> in addition to any authentication.</p>
+    </div>
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="theprerequisites" id="theprerequisites">The Prerequisites</a></h2>
@@ -137,7 +143,12 @@ module from each group.</p>
     <p>Here's the basics of password protecting a directory on your
     server.</p>
 
-    <p>You'll need to create a password file. This file should be
+    <p>First, you need to create a password file. Exactly how you do
+    this will vary depending on what authentication provider you have
+    chosen. More on that later. To start with, we'll use a text password
+    file.</p>
+
+    <p>This file should be
     placed somewhere not accessible from the web. This is so that
     folks cannot download the password file. For example, if your
     documents are served out of <code>/usr/local/apache/htdocs</code> you
@@ -146,7 +157,10 @@ module from each group.</p>
 
     <p>To create the file, use the <code class="program"><a href="../programs/htpasswd.html">htpasswd</a></code> utility that
     came with Apache. This will be located in the <code>bin</code> directory
-    of wherever you installed Apache. To create the file, type:</p>
+    of wherever you installed Apache. If you have installed Apache from
+    a third-party package, it may be in your execution path.</p>
+    
+    <p>To create the file, type:</p>
 
     <div class="example"><p><code>
       htpasswd -c /usr/local/apache/passwd/passwords rbowen
@@ -164,8 +178,8 @@ module from each group.</p>
 
     <p>If <code class="program"><a href="../programs/htpasswd.html">htpasswd</a></code> is not in your path, of course
     you'll have to type the full path to the file to get it to run.
-    On my server, it's located at
-    <code>/usr/local/apache/bin/htpasswd</code></p>
+    With a default installation, it's located at
+    <code>/usr/local/apache2/bin/htpasswd</code></p>
 
     <p>Next, you'll need to configure the server to request a
     password and tell the server which users are allowed access.
@@ -181,6 +195,8 @@ module from each group.</p>
     <div class="example"><p><code>
       AuthType Basic<br />
       AuthName "Restricted Files"<br />
+      # (Following line optional)<br />
+      AuthBasicProvider file<br />
       AuthUserFile /usr/local/apache/passwd/passwords<br />
       Require user rbowen
     </code></p></div>
@@ -191,9 +207,10 @@ module from each group.</p>
     implemented by <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code>. It is important to be aware,
     however, that Basic authentication sends the password from the client to
     the server unencrypted. This method should therefore not be used for
-    highly sensitive data. Apache supports one other authentication method:
-    <code>AuthType Digest</code>. This method is implemented by <code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code> and is much more secure. Only the most recent
-    versions of clients are known to support Digest authentication.</p>
+    highly sensitive data, unless accompanied by <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>.
+    Apache supports one other authentication method:
+    <code>AuthType Digest</code>. This method is implemented by <code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code> and is much more secure. Most recent
+    browsers support Digest authentication.</p>
 
     <p>The <code class="directive"><a href="../mod/core.html#authname">AuthName</a></code> directive sets
     the <dfn>Realm</dfn> to be used in the authentication. The realm serves
@@ -212,6 +229,12 @@ module from each group.</p>
     will always need to ask again for the password whenever the
     hostname of the server changes.</p>
 
+    <p>The <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> is,
+    in this case, optional, since <code>file</code> is the default value
+    for this directive. You'll need to use this directive if you are
+    choosing a different source for authentication, such as
+    <code class="module"><a href="../mod/mod_authn_dbm.html">mod_authn_dbm</a></code> or <code class="module"><a href="../mod/mod_auth_dbd.html">mod_auth_dbd</a></code>.</p>
+
     <p>The <code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code>
     directive sets the path to the password file that we just
     created with <code class="program"><a href="../programs/htpasswd.html">htpasswd</a></code>. If you have a large number
@@ -317,79 +340,16 @@ person in</a></h2>
     different authentication method at that time.</p>
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
-<h2><a name="whatotherneatstuffcanido" id="whatotherneatstuffcanido">What other neat stuff can I
-do?</a></h2>
-    <p>Authentication by username and password is only part of the
-    story. Frequently you want to let people in based on something
-    other than who they are. Something such as where they are
-    coming from.</p>
-
-    <p>The <code class="directive"><a href="../mod/mod_authz_host.html#allow">Allow</a></code> and
-    <code class="directive"><a href="../mod/mod_authz_host.html#deny">Deny</a></code> directives let
-    you allow and deny access based on the host name, or host
-    address, of the machine requesting a document. The
-    <code class="directive"><a href="../mod/mod_authz_host.html#order">Order</a></code> directive goes
-    hand-in-hand with these two, and tells Apache in which order to
-    apply the filters.</p>
-
-    <p>The usage of these directives is:</p>
-
-    <div class="example"><p><code>
-      Allow from <var>address</var>
-    </code></p></div>
-
-    <p>where <var>address</var> is an IP address (or a partial IP
-    address) or a fully qualified domain name (or a partial domain
-    name); you may provide multiple addresses or domain names, if
-    desired.</p>
-
-    <p>For example, if you have someone spamming your message
-    board, and you want to keep them out, you could do the
-    following:</p>
-
-    <div class="example"><p><code>
-      Deny from 205.252.46.165
-    </code></p></div>
-
-    <p>Visitors coming from that address will not be able to see
-    the content covered by this directive. If, instead, you have a
-    machine name, rather than an IP address, you can use that.</p>
-
-    <div class="example"><p><code>
-      Deny from <var>host.example.com</var>
-    </code></p></div>
-
-    <p>And, if you'd like to block access from an entire domain,
-    you can specify just part of an address or domain name:</p>
-
-    <div class="example"><p><code>
-      Deny from <var>192.101.205</var><br />
-      Deny from <var>cyberthugs.com</var> <var>moreidiots.com</var><br />
-      Deny from ke
-    </code></p></div>
-
-    <p>Using <code class="directive"><a href="../mod/mod_authz_host.html#order">Order</a></code> will let you
-    be sure that you are actually restricting things to the group that you want
-    to let in, by combining a <code class="directive"><a href="../mod/mod_authz_host.html#deny">Deny</a></code> and an <code class="directive"><a href="../mod/mod_authz_host.html#allow">Allow</a></code> directive:</p>
-
-    <div class="example"><p><code>
-      Order deny,allow<br />
-      Deny from all<br />
-      Allow from <var>dev.example.com</var>
-    </code></p></div>
-
-    <p>Listing just the <code class="directive"><a href="../mod/mod_authz_host.html#allow">Allow</a></code>
-    directive would not do what you want, because it will let folks from that
-    host in, in addition to letting everyone in. What you want is to let
-    <em>only</em> those folks in.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
 <h2><a name="moreinformation" id="moreinformation">More information</a></h2>
     <p>You should also read the documentation for
     <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code> and <code class="module"><a href="../mod/mod_authz_host.html">mod_authz_host</a></code> which
     contain some more information about how this all works.
     <code class="module"><a href="../mod/mod_authn_alias.html">mod_authn_alias</a></code> can also help in simplifying certain
     authentication configurations.</p>
+
+    <p>And you may want to look at the <a href="access.html">Access
+    Control</a> howto, which discusses a number of related topics.</p>
+
 </div></div>
 <div class="bottomlang">
 <p><span>Available Languages: </span><a href="../en/howto/auth.html" title="English">&nbsp;en&nbsp;</a> |
diff --git a/docs/manual/howto/auth.xml b/docs/manual/howto/auth.xml
index ea6531886d..cb6d060832 100644
--- a/docs/manual/howto/auth.xml
+++ b/docs/manual/howto/auth.xml
@@ -81,6 +81,10 @@ module from each group.</p>
   of the request, but is not part of the authentication provider
   system.</p>
 
+  <p>You probably also want to take a look at the <a
+  href="access.html">Access Control</a> howto, which discusses the
+  various ways to control access to your server.</p>
+
 </section>
 
 <section id="introduction"><title>Introduction</title>
@@ -91,6 +95,11 @@ module from each group.</p>
 
     <p>This article covers the "standard" way of protecting parts
     of your web site that most of you are going to use.</p>
+
+    <note><title>Note:</title>
+    <p>If your data really needs to be secure, consider using
+    <module>mod_ssl</module> in addition to any authentication.</p>
+    </note>
 </section>
 
 <section id="theprerequisites"><title>The Prerequisites</title>
@@ -128,7 +137,12 @@ module from each group.</p>
     <p>Here's the basics of password protecting a directory on your
     server.</p>
 
-    <p>You'll need to create a password file. This file should be
+    <p>First, you need to create a password file. Exactly how you do
+    this will vary depending on what authentication provider you have
+    chosen. More on that later. To start with, we'll use a text password
+    file.</p>
+
+    <p>This file should be
     placed somewhere not accessible from the web. This is so that
     folks cannot download the password file. For example, if your
     documents are served out of <code>/usr/local/apache/htdocs</code> you
@@ -137,7 +151,10 @@ module from each group.</p>
 
     <p>To create the file, use the <program>htpasswd</program> utility that
     came with Apache. This will be located in the <code>bin</code> directory
-    of wherever you installed Apache. To create the file, type:</p>
+    of wherever you installed Apache. If you have installed Apache from
+    a third-party package, it may be in your execution path.</p>
+    
+    <p>To create the file, type:</p>
 
     <example>
       htpasswd -c /usr/local/apache/passwd/passwords rbowen
@@ -155,8 +172,8 @@ module from each group.</p>
 
     <p>If <program>htpasswd</program> is not in your path, of course
     you'll have to type the full path to the file to get it to run.
-    On my server, it's located at
-    <code>/usr/local/apache/bin/htpasswd</code></p>
+    With a default installation, it's located at
+    <code>/usr/local/apache2/bin/htpasswd</code></p>
 
     <p>Next, you'll need to configure the server to request a
     password and tell the server which users are allowed access.
@@ -172,6 +189,8 @@ module from each group.</p>
     <example>
       AuthType Basic<br />
       AuthName "Restricted Files"<br />
+      # (Following line optional)<br />
+      AuthBasicProvider file<br />
       AuthUserFile /usr/local/apache/passwd/passwords<br />
       Require user rbowen
     </example>
@@ -183,10 +202,11 @@ module from each group.</p>
     implemented by <module>mod_auth_basic</module>. It is important to be aware,
     however, that Basic authentication sends the password from the client to
     the server unencrypted. This method should therefore not be used for
-    highly sensitive data. Apache supports one other authentication method:
+    highly sensitive data, unless accompanied by <module>mod_ssl</module>.
+    Apache supports one other authentication method:
     <code>AuthType Digest</code>. This method is implemented by <module
-    >mod_auth_digest</module> and is much more secure. Only the most recent
-    versions of clients are known to support Digest authentication.</p>
+    >mod_auth_digest</module> and is much more secure. Most recent
+    browsers support Digest authentication.</p>
 
     <p>The <directive module="core">AuthName</directive> directive sets
     the <dfn>Realm</dfn> to be used in the authentication. The realm serves
@@ -205,6 +225,13 @@ module from each group.</p>
     will always need to ask again for the password whenever the
     hostname of the server changes.</p>
 
+    <p>The <directive
+    module="mod_auth_basic">AuthBasicProvider</directive> is,
+    in this case, optional, since <code>file</code> is the default value
+    for this directive. You'll need to use this directive if you are
+    choosing a different source for authentication, such as
+    <module>mod_authn_dbm</module> or <module>mod_auth_dbd</module>.</p>
+
     <p>The <directive module="mod_authn_file">AuthUserFile</directive>
     directive sets the path to the password file that we just
     created with <program>htpasswd</program>. If you have a large number
@@ -314,81 +341,16 @@ person in</title>
     different authentication method at that time.</p>
 </section>
 
-<section id="whatotherneatstuffcanido"><title>What other neat stuff can I
-do?</title>
-    <p>Authentication by username and password is only part of the
-    story. Frequently you want to let people in based on something
-    other than who they are. Something such as where they are
-    coming from.</p>
-
-    <p>The <directive module="mod_authz_host">Allow</directive> and
-    <directive module="mod_authz_host">Deny</directive> directives let
-    you allow and deny access based on the host name, or host
-    address, of the machine requesting a document. The
-    <directive module="mod_authz_host">Order</directive> directive goes
-    hand-in-hand with these two, and tells Apache in which order to
-    apply the filters.</p>
-
-    <p>The usage of these directives is:</p>
-
-    <example>
-      Allow from <var>address</var>
-    </example>
-
-    <p>where <var>address</var> is an IP address (or a partial IP
-    address) or a fully qualified domain name (or a partial domain
-    name); you may provide multiple addresses or domain names, if
-    desired.</p>
-
-    <p>For example, if you have someone spamming your message
-    board, and you want to keep them out, you could do the
-    following:</p>
-
-    <example>
-      Deny from 205.252.46.165
-    </example>
-
-    <p>Visitors coming from that address will not be able to see
-    the content covered by this directive. If, instead, you have a
-    machine name, rather than an IP address, you can use that.</p>
-
-    <example>
-      Deny from <var>host.example.com</var>
-    </example>
-
-    <p>And, if you'd like to block access from an entire domain,
-    you can specify just part of an address or domain name:</p>
-
-    <example>
-      Deny from <var>192.101.205</var><br />
-      Deny from <var>cyberthugs.com</var> <var>moreidiots.com</var><br />
-      Deny from ke
-    </example>
-
-    <p>Using <directive module="mod_authz_host">Order</directive> will let you
-    be sure that you are actually restricting things to the group that you want
-    to let in, by combining a <directive
-    module="mod_authz_host">Deny</directive> and an <directive
-    module="mod_authz_host">Allow</directive> directive:</p>
-
-    <example>
-      Order deny,allow<br />
-      Deny from all<br />
-      Allow from <var>dev.example.com</var>
-    </example>
-
-    <p>Listing just the <directive module="mod_authz_host">Allow</directive>
-    directive would not do what you want, because it will let folks from that
-    host in, in addition to letting everyone in. What you want is to let
-    <em>only</em> those folks in.</p>
-</section>
-
 <section id="moreinformation"><title>More information</title>
     <p>You should also read the documentation for
     <module>mod_auth_basic</module> and <module>mod_authz_host</module> which
     contain some more information about how this all works.
     <module>mod_authn_alias</module> can also help in simplifying certain
     authentication configurations.</p>
+
+    <p>And you may want to look at the <a href="access.html">Access
+    Control</a> howto, which discusses a number of related topics.</p>
+
 </section>
 
 </manualpage>
diff --git a/docs/manual/howto/index.xml b/docs/manual/howto/index.xml
index c81e72a1e6..378dbcbe1d 100644
--- a/docs/manual/howto/index.xml
+++ b/docs/manual/howto/index.xml
@@ -1,4 +1,15 @@
 <?xml version="1.0" encoding="UTF-8" ?>
+
+<metafile>
+  <basename>access</basename>
+  <path>/howto/</path>
+  <relpath>..</relpath>
+
+  <variants>
+    <variant>en</variant>
+  </variants>
+</metafile>
+<?xml version="1.0" encoding="UTF-8" ?>
 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
 <!-- $LastChangedRevision$ -->
@@ -30,18 +41,30 @@
     <title>How-To / Tutorials</title>
 
     <dl>
-      <dt>Authentication</dt>
+      <dt>Authentication and Authorization</dt>
       <dd>
         <p>Authentication is any process by which you verify that
         someone is who they claim they are. Authorization is any
         process by which someone is allowed to be where they want to
         go, or to have information that they want to have.</p>
 
-        <p>See: <a href="auth.html">Authentication, Authorization, and Access Control</a></p>
+        <p>See: <a href="auth.html">Authentication, Authorization</a></p>
       </dd>
     </dl>
 
     <dl>
+      <dt>Access Control</dt>
+      <dd>
+        <p>Access control refers to the process of restricting, or
+        granting access to a resource based on arbitrary criteria. There
+        are a variety of different ways that this can be
+        accomplished.</p>
+
+        <p>See: <a href="access.html">Access Control</a></p>
+      </dd>
+    </dl>
+
+   <dl>
       <dt>Dynamic Content with CGI</dt>
       <dd>
         <p>The CGI (Common Gateway Interface) defines a way for a web