PR 43211: Revise mod_authn_dbd documenation to reflect current APR DBD

query statement parameter requirements.  Tidy up examples and links to
glossary and external sites.

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

diff --git a/docs/manual/mod/mod_authn_dbd.xml b/docs/manual/mod/mod_authn_dbd.xml
index 32adc56d0ff16b46901b2fe2a99e477f2a5f95d6..03fac247ec7db97f905fb225821b587570a4ec80 100644 (file)
--- a/docs/manual/mod/mod_authn_dbd.xml
+++ b/docs/manual/mod/mod_authn_dbd.xml
@@ -62,45 +62,39 @@
 <p>This simple example shows use of this module in the context of
 the Authentication and DBD frameworks.</p>
 <example><pre>
-#Database Management
-
-#Use the PostgreSQL driver
-<code>DBDriver pgsql</code>
-
-#Connection string: database name and login credentials
-<code>DBDParams "dbname=htpasswd user=apache password=xxxxxx"</code>
-
-#Parameters for Connection Pool Management
-<code>DBDMin  1
-DBDKeep 2
-DBDMax  10
-DBDExptime 60</code>
-
-#Authentication Section
-<code>&lt;Directory /usr/www/myhost/private&gt;</code>
-
-    #mod_auth configuration for authn_dbd
-    <code>AuthType Basic
-    AuthName "My Server"
-    AuthBasicProvider dbd</code>
-
-    #authz configuration
-    <code>Require valid-user</code>
-
-    #SQL query to verify a user
-    #(note: DBD drivers recognise both stdio-like %s and native syntax)
-    <code>AuthDBDUserPWQuery "select password from authn where username = %s"
-&lt;/Directory&gt;</code>
-</pre>
-</example>
+# mod_dbd configuration
+DBDriver pgsql
+DBDParams "dbname=apacheauth user=apache password=xxxxxx"
+
+DBDMin  4
+DBDKeep 8
+DBDMax  20
+DBDExptime 300
+
+&lt;Directory /usr/www/myhost/private&gt;
+  # core authentication and mod_auth_basic configuration
+  # for mod_authn_dbd
+  AuthType Basic
+  AuthName "My Server"
+  AuthBasicProvider dbd
+
+  # core authorization configuration
+  Require valid-user
+
+  # mod_authn_dbd SQL query to authenticate a user
+  AuthDBDUserPWQuery \
+    "SELECT password FROM authn WHERE user = %s"
+&lt;/Directory&gt;
+</pre></example>
 </section>
 
 <section id="exposed">
 <title>Exposing Login Information</title>
 <p>
-Whenever a query is made to the database server, all columns returned by
-the query are placed in the environment, using environment variables with
-the prefix "AUTHENTICATE_".
+If httpd was built against <glossary>APR</glossary> version 1.3.0
+or higher, then whenever a query is made to the database server, all
+column values in the first row returned by the query are placed in the
+environment, using environment variables with the prefix "AUTHENTICATE_".
 </p>
 <p>If a database query for example returned the username, full name
 and telephone number of a user, a CGI program will have access to
@@ -120,16 +114,22 @@ configuration required in some web applications.
 
 <usage>
     <p>The <directive>AuthDBDUserPWQuery</directive> specifies an
-    SQL query to look up a password for a specified user.
-    The query must take a single string (typically SQL varchar)
-    argument (username), and return a single value (encrypted password).
-    </p>
-    <example>
-    AuthDBDUserPWQuery "SELECT password FROM authn WHERE username = %s"
-    </example>
-    <p>If httpd was built against apr v1.3.0 or higher, any additional
-    columns specified in the select statement will be inserted into
-    the environment with the name <code>AUTHENTICATE_&lt;COLUMN&gt;</code>.
+    SQL query to look up a password for a specified user.  The user's ID
+    will be passed as a single string parameter when the SQL query is
+    executed.  It may be referenced within the query statement using
+    a <code>%s</code> format specifier.</p>
+    <example><title>Example</title><pre>
+AuthDBDUserPWQuery \
+  "SELECT password FROM authn WHERE user = %s"
+</pre></example>
+    <p>The first column value of the first row returned by the query
+    statement should be a string containing the encrypted password.
+    Subsequent rows will be ignored.  If no rows are returned, the user
+    will not be authenticated through <module>mod_authn_dbd</module>.</p>
+    <p>If httpd was built against <glossary>APR</glossary> version 1.3.0
+    or higher, any additional column values in the first row returned by
+    the query statement will be stored as environment variables with
+    names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
     </p>
 </usage>
 </directivesynopsis>
@@ -145,18 +145,22 @@ configuration required in some web applications.
 <usage>
     <p>The <directive>AuthDBDUserRealmQuery</directive> specifies an
     SQL query to look up a password for a specified user and realm.
-    The query must take two string (typically SQL varchar) arguments
-    (username and realm), and return a single value (encrypted password).
+    The user's ID and the realm, in that order, will be passed as string
+    parameters when the SQL query is executed.  They may be referenced
+    within the query statement using <code>%s</code> format specifiers.</p>
+    <example><title>Example</title><pre>
+AuthDBDUserRealmQuery \
+  "SELECT password FROM authn WHERE user = %s AND realm = %s"
+</pre></example>
+    <p>The first column value of the first row returned by the query
+    statement should be a string containing the encrypted password.
+    Subsequent rows will be ignored.  If no rows are returned, the user
+    will not be authenticated through <module>mod_authn_dbd</module>.</p>
+    <p>If httpd was built against <glossary>APR</glossary> version 1.3.0
+    or higher, any additional column values in the first row returned by
+    the query statement will be stored as environment variables with
+    names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
     </p>
-    <example>
-    AuthDBDUserRealmQuery "SELECT password FROM authn
-                              WHERE username = %s AND realm = %s"
-    </example>
-    <p>If httpd was built against apr v1.3.0 or higher, any additional
-    columns specified in the select statement will be inserted into
-    the environment with the name <code>AUTHENTICATE_&lt;COLUMN&gt;</code>.
-    </p>
-
 </usage>
 </directivesynopsis>
 

diff --git a/docs/manual/mod/mod_dbd.xml b/docs/manual/mod/mod_dbd.xml
index 30969242223695da852561c5e148fc779183c329..cc77ceea2add64451e7d216af284fff610718e8b 100644 (file)
--- a/docs/manual/mod/mod_dbd.xml
+++ b/docs/manual/mod/mod_dbd.xml
@@ -31,11 +31,14 @@
 
 <summary>
     <p><module>mod_dbd</module> manages SQL database connections using
-    <a href="http://people.apache.org/~niq/dbd.html">apr_dbd</a>.
-    It provides database connections on request to modules
-    requiring SQL database functions, and takes care of
+    <glossary>APR</glossary>.  It provides database connections on request
+    to modules requiring SQL database functions, and takes care of
     managing databases with optimal efficiency and scalability
-    for both threaded and non-threaded MPMs.</p>
+    for both threaded and non-threaded MPMs.  For details, see the
+    <a href="http://apr.apache.org/">APR</a> website and this overview of the
+    <a href="http://people.apache.org/~niq/dbd.html">Apache DBD Framework</a>
+    by its original developer.
+</p>
 </summary>
 
 <seealso><a href="../misc/password_encryptions.html">Password Formats</a></seealso>
@@ -47,9 +50,9 @@
     classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python).
     On threaded platform, it provides an altogether more
     scalable and efficient <em>connection pool</em>, as
-    described in <a href="http://www.apachetutor.org/dev/reslist"
-    >this article at ApacheTutor</a>. <module>mod_dbd</module> supersedes
-    the modules presented in that article.</p>
+    described in <a href="http://www.apachetutor.org/dev/reslist">this
+    article at ApacheTutor</a>.  Note that <module>mod_dbd</module>
+    supersedes the modules presented in that article.</p>
 </section>
 
 <section id="API"><title>Apache DBD API</title>