From: Daniel Gruno <humbedooh@apache.org>
Date: Fri, 20 Jul 2012 12:52:22 +0000 (+0000)
Subject: Some more backports of information from trunk that applies to 2.2 as well.
X-Git-Tag: 2.2.23~109
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0d3aaaae817c539eeb9ab36e1479b4c525eac3d1;p=thirdparty%2Fapache%2Fhttpd.git

Some more backports of information from trunk that applies to 2.2 as well.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.2.x@1363757 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/howto/auth.xml b/docs/manual/howto/auth.xml
index 39054ec1a94..511e6bf5459 100644
--- a/docs/manual/howto/auth.xml
+++ b/docs/manual/howto/auth.xml
@@ -23,13 +23,16 @@
 <manualpage metafile="auth.xml.meta">
 <parentdocument href="./">How-To / Tutorials</parentdocument>
 
-<title>Authentication, Authorization and Access Control</title>
+<title>Authentication and Authorization</title>
 
 <summary>
     <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>For general access control, see the <a href="access.html">Access
+    Control How-To</a>.</p>
 </summary>
 
 <section id="related"><title>Related Modules and Directives</title>
@@ -40,30 +43,33 @@ module from each group.</p>
 
 <ul>
   <li>Authentication type (see the
-      <directive module="core">AuthType</directive> directive)
+      <directive module="mod_authn_core">AuthType</directive> directive)
     <ul>
       <li><module>mod_auth_basic</module></li>
       <li><module>mod_auth_digest</module></li>
     </ul>
   </li>
-  <li>Authentication provider
+  <li>Authentication provider (see the
+  <directive module="mod_auth_basic">AuthBasicProvider</directive> and
+  <directive module="mod_auth_digest">AuthDigestProvider</directive> directives)
+
     <ul>
-      <li><module>mod_authn_alias</module></li>
       <li><module>mod_authn_anon</module></li>
       <li><module>mod_authn_dbd</module></li>
       <li><module>mod_authn_dbm</module></li>
-      <li><module>mod_authn_default</module></li>
       <li><module>mod_authn_file</module></li>
       <li><module>mod_authnz_ldap</module></li>
+      <li><module>mod_authn_socache</module></li>
     </ul>
   </li>
   <li>Authorization (see the
-      <directive module="core">Require</directive> directive)
+      <directive module="mod_authz_core">Require</directive> directive)
     <ul>
       <li><module>mod_authnz_ldap</module></li>
+      <li><module>mod_authz_dbd</module></li>
       <li><module>mod_authz_dbm</module></li>
-      <li><module>mod_authz_default</module></li>
       <li><module>mod_authz_groupfile</module></li>
+      <li><module>mod_authz_host</module></li>
       <li><module>mod_authz_owner</module></li>
       <li><module>mod_authz_user</module></li>
     </ul>
@@ -131,6 +137,13 @@ module from each group.</p>
     structure of your server, in order to know where some files are
     kept. This should not be terribly difficult, and I'll try to
     make this clear when we come to that point.</p>
+
+    <p>You will also need to make sure that the modules
+    <module>mod_authn_core</module> and <module>mod_authz_core</module>
+    have either been built into the httpd binary or loaded by the
+    httpd.conf configuration file. Both of these modules provide core
+    directives and functionality that are critical to the configuration
+    and use of authentication and authorization in the web server.</p>
 </section>
 
 <section id="gettingitworking"><title>Getting it working</title>
@@ -192,7 +205,7 @@ module from each group.</p>
       # (Following line optional)<br />
       AuthBasicProvider file<br />
       AuthUserFile /usr/local/apache/passwd/passwords<br />
-      Require user rbowen
+Require user rbowen
     </example>
 
     <p>Let's examine each of those directives individually. The <directive
@@ -208,7 +221,7 @@ module from each group.</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
+    <p>The <directive module="mod_authn_core">AuthName</directive> directive sets
     the <dfn>Realm</dfn> to be used in the authentication. The realm serves
     two major functions. First, the client often presents this information to
     the user as part of the password dialog box. Second, it is used by the
@@ -247,7 +260,7 @@ module from each group.</p>
     href="http://modules.apache.org/">Apache Modules
     Database</a>.</p>
 
-    <p>Finally, the <directive module="core">Require</directive>
+    <p>Finally, the <directive module="mod_authz_core">Require</directive>
     directive provides the authorization part of the process by
     setting the user that is allowed to access this region of the
     server. In the next section, we discuss various ways to use the
@@ -327,7 +340,7 @@ person in</title>
       AuthBasicProvider file<br />
       AuthUserFile /usr/local/apache/passwd/passwords<br />
       AuthGroupFile /usr/local/apache/passwd/groups<br />
-      Require group GroupName
+Require group GroupName
     </example>
 
     <p>Now, anyone that is listed in the group <code>GroupName</code>,
@@ -394,7 +407,7 @@ person in</title>
     AuthBasicProvider dbm<br />
     AuthDBMUserFile /www/passwords/passwd.dbm<br />
     Require valid-user<br />
-    &lt;/Directory&gt;
+&lt;/Directory&gt;
     </example>
 
     <p>Other options are available. Consult the
diff --git a/docs/manual/howto/cgi.xml b/docs/manual/howto/cgi.xml
index 32140322cba..60b58c3cbcb 100644
--- a/docs/manual/howto/cgi.xml
+++ b/docs/manual/howto/cgi.xml
@@ -57,10 +57,21 @@
     need to have Apache configured to permit CGI execution. There
     are several ways to do this.</p>
 
+    <note type="warning">Note: If Apache has been built with shared module
+    support you need to ensure that the module is loaded; in your
+    <code>httpd.conf</code> you need to make sure the
+    <directive module="mod_so">LoadModule</directive>
+    directive has not been commented out.  A correctly configured directive
+    may look like this:
+
+    <highlight language="config">
+      LoadModule cgi_module modules/mod_cgi.so
+    </highlight></note>
+
     <section id="scriptalias">
       <title>ScriptAlias</title>
 
-      <p>The 
+      <p>The
       <directive module="mod_alias">ScriptAlias</directive>
 
       directive tells Apache that a particular directory is set
@@ -95,7 +106,7 @@
 
       <p>For example, if the URL
       <code>http://www.example.com/cgi-bin/test.pl</code>
-      is requested, Apache will attempt to execute the file 
+      is requested, Apache will attempt to execute the file
       <code>/usr/local/apache2/cgi-bin/test.pl</code>
       and return the output. Of course, the file will have to
       exist, and be executable, and return output in a particular
@@ -111,7 +122,7 @@
       use CGI programs. However, if the proper security precautions are
       taken, there is no reason why CGI programs cannot be run from
       arbitrary directories. For example, you may wish to let users
-      have web content in their home directories with the 
+      have web content in their home directories with the
       <directive module="mod_userdir">UserDir</directive> directive.
       If they want to have their own CGI programs, but don't have access to
       the main <code>cgi-bin</code> directory, they will need to be able to
@@ -123,7 +134,7 @@
       module="mod_mime">AddHandler</directive> or <directive
       module="core">SetHandler</directive> directive.  Second,
       <code>ExecCGI</code> must be specified in the <directive
-      module="core">Options</directive> directive.</p> 
+      module="core">Options</directive> directive.</p>
     </section>
 
     <section id="options">
@@ -139,7 +150,7 @@
         <indent>
           Options +ExecCGI<br />
         </indent>
-        &lt;/Directory&gt;
+&lt;/Directory&gt;
       </example>
 
       <p>The above directive tells Apache to permit the execution
@@ -175,7 +186,7 @@
         Options +ExecCGI<br/>
         AddHandler cgi-script .cgi<br/>
       </indent>
-      &lt;/Directory&gt;
+&lt;/Directory&gt;
       </example>
 
       <p>If you wish designate a <code>cgi-bin</code> subdirectory of
@@ -188,7 +199,7 @@
         Options ExecCGI<br/>
         SetHandler cgi-script<br/>
       </indent>
-      &lt;/Directory&gt;
+&lt;/Directory&gt;
       </example>
 
     </section>
@@ -224,13 +235,13 @@
 
       <p>The following is an example CGI program that prints one
       line to your browser. Type in the following, save it to a
-      file called <code>first.pl</code>, and put it in your 
+      file called <code>first.pl</code>, and put it in your
       <code>cgi-bin</code> directory.</p>
 
       <example>
         #!/usr/bin/perl<br />
         print "Content-type: text/html\n\n";<br />
-        print "Hello, World.";
+print "Hello, World.";
       </example>
 
       <p>Even if you are not familiar with Perl, you should be able
@@ -252,7 +263,7 @@
         http://www.example.com/cgi-bin/first.pl
       </example>
 
-      <p>or wherever you put your file, you will see the one line 
+      <p>or wherever you put your file, you will see the one line
       <code>Hello, World.</code> appear in your browser window.
       It's not very exciting, but once you get that working, you'll
       have a good chance of getting just about anything working.</p>
@@ -274,7 +285,7 @@
       <dt>The source code of your CGI program or a "POST Method Not
       Allowed" message</dt>
       <dd>That means that you have not properly configured Apache
-      to process your CGI program. Reread the section on 
+      to process your CGI program. Reread the section on
       <a href="#configuring">configuring
       Apache</a> and try to find what you missed.</dd>
 
@@ -284,7 +295,7 @@
       <a href="#permissions">file permissions</a>.</dd>
 
       <dt>A message saying "Internal Server Error"</dt>
-      <dd>If you check the 
+      <dd>If you check the
       <a href="#errorlogs">Apache error log</a>, you will probably
       find that it says "Premature end of
       script headers", possibly along with an error message
@@ -341,11 +352,6 @@
 
       <p>Make sure that this is in fact the path to the
       interpreter.</p>
-
-      <p>In addition, if your CGI program depends on other <a
-      href="#env">environment variables</a>, you will need to
-      assure that those variables are passed by Apache.</p>
-
       <note type="warning">
       When editing CGI scripts on Windows, end-of-line characters may be
       appended to the interpreter path. Ensure that files are then
@@ -354,6 +360,21 @@
       unrecognized end-of-line character being interpreted as a part of
       the interpreter filename.
       </note>
+    </section>
+
+    <section id="missingenv">
+      <title>Missing environment variables</title>
+
+      <p>If your CGI program depends on non-standard <a
+      href="#env">environment variables</a>, you will need to
+      assure that those variables are passed by Apache.</p>
+
+      <p>When you miss HTTP headers from the environment, make
+      sure they are formatted according to
+      <a href="http://tools.ietf.org/html/rfc2616">RFC 2616</a>,
+      section 4.2: Header names must start with a letter,
+      followed only by letters, numbers or hyphen. Any header
+      violating this rule will be dropped silently.</p>
 
     </section>
 
@@ -441,7 +462,7 @@
       (where the computer searches for the actual file
       implementing a command when you type it), your username, your
       terminal type, and so on. For a full list of your normal,
-      every day environment variables, type 
+      every day environment variables, type
       <code>env</code> at a command prompt.</p>
 
       <p>During the CGI transaction, the server and the browser
@@ -458,13 +479,13 @@
 
       <p>This simple Perl CGI program will display all of the
       environment variables that are being passed around. Two
-      similar programs are included in the 
+      similar programs are included in the
       <code>cgi-bin</code>
 
       directory of the Apache distribution. Note that some
       variables are required, while others are optional, so you may
       see some variables listed that were not in the official list.
-      In addition, Apache provides many different ways for you to 
+      In addition, Apache provides many different ways for you to
       <a href="../env.html">add your own environment variables</a>
       to the basic ones provided by default.</p>
 
@@ -475,7 +496,7 @@
         <indent>
           print "$key --&gt; $ENV{$key}&lt;br&gt;";<br />
         </indent>
-        }
+}
       </example>
     </section>
 
@@ -484,10 +505,10 @@
 
       <p>Other communication between the server and the client
       happens over standard input (<code>STDIN</code>) and standard
-      output (<code>STDOUT</code>). In normal everyday context, 
-      <code>STDIN</code> means the keyboard, or a file that a 
+      output (<code>STDOUT</code>). In normal everyday context,
+      <code>STDIN</code> means the keyboard, or a file that a
       program is given to act on, and <code>STDOUT</code>
-      usually means the console or screen.</p> 
+      usually means the console or screen.</p>
 
       <p>When you <code>POST</code> a web form to a CGI program,
       the data in that form is bundled up into a special format
@@ -509,10 +530,10 @@
 
       <p>You'll sometimes also see this type of string appended to
       a URL. When that is done, the server puts that string
-      into the environment variable called 
+      into the environment variable called
       <code>QUERY_STRING</code>. That's called a <code>GET</code>
       request. Your HTML form specifies whether a <code>GET</code>
-      or a <code>POST</code> is used to deliver the data, by setting the 
+      or a <code>POST</code> is used to deliver the data, by setting the
       <code>METHOD</code> attribute in the <code>FORM</code> tag.</p>
 
       <p>Your program is then responsible for splitting that string
@@ -536,7 +557,7 @@
     set of functionality, which is all you need in most programs.</p>
 
     <p>If you're writing CGI programs in C, there are a variety of
-    options. One of these is the <code>CGIC</code> library, from 
+    options. One of these is the <code>CGIC</code> library, from
     <a href="http://www.boutell.com/cgic/"
     >http://www.boutell.com/cgic/</a>.</p>
   </section>