httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chr...@apache.org
Subject svn commit: r641535 - in /httpd/httpd/branches/2.2.x/docs/manual/mod: mod_authn_dbd.xml mod_dbd.xml
Date Wed, 26 Mar 2008 20:05:23 GMT
Author: chrisd
Date: Wed Mar 26 13:05:20 2008
New Revision: 641535

URL: http://svn.apache.org/viewvc?rev=641535&view=rev
Log:
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.

Modified:
    httpd/httpd/branches/2.2.x/docs/manual/mod/mod_authn_dbd.xml
    httpd/httpd/branches/2.2.x/docs/manual/mod/mod_dbd.xml

Modified: httpd/httpd/branches/2.2.x/docs/manual/mod/mod_authn_dbd.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/mod/mod_authn_dbd.xml?rev=641535&r1=641534&r2=641535&view=diff
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/mod/mod_authn_dbd.xml (original)
+++ httpd/httpd/branches/2.2.x/docs/manual/mod/mod_authn_dbd.xml Wed Mar 26 13:05:20 2008
@@ -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 @@
 
 <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 @@
 <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).
-    </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>.
+    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>
-
 </usage>
 </directivesynopsis>
 

Modified: httpd/httpd/branches/2.2.x/docs/manual/mod/mod_dbd.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/mod/mod_dbd.xml?rev=641535&r1=641534&r2=641535&view=diff
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/mod/mod_dbd.xml (original)
+++ httpd/httpd/branches/2.2.x/docs/manual/mod/mod_dbd.xml Wed Mar 26 13:05:20 2008
@@ -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>



Mime
View raw message