From: Chris Darroch Date: Wed, 26 Mar 2008 20:05:20 +0000 (+0000) Subject: PR 43211: Revise mod_authn_dbd documenation to reflect current APR DBD X-Git-Tag: 2.2.9~271 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ad44509e3d3a6e91843c87b193d9908569b1adef;p=thirdparty%2Fapache%2Fhttpd.git 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 32adc56d0ff..03fac247ec7 100644 --- a/docs/manual/mod/mod_authn_dbd.xml +++ b/docs/manual/mod/mod_authn_dbd.xml @@ -62,45 +62,39 @@

This simple example shows use of this module in the context of the Authentication and DBD frameworks.

-#Database Management
-
-#Use the PostgreSQL driver
-DBDriver pgsql
-
-#Connection string: database name and login credentials
-DBDParams "dbname=htpasswd user=apache password=xxxxxx"
-
-#Parameters for Connection Pool Management
-DBDMin  1
-DBDKeep 2
-DBDMax  10
-DBDExptime 60
-
-#Authentication Section
-<Directory /usr/www/myhost/private>
-
-    #mod_auth configuration for authn_dbd
-    AuthType Basic
-    AuthName "My Server"
-    AuthBasicProvider dbd
-
-    #authz configuration
-    Require valid-user
-
-    #SQL query to verify a user
-    #(note: DBD drivers recognise both stdio-like %s and native syntax)
-    AuthDBDUserPWQuery "select password from authn where username = %s"
-</Directory>
-
- +# mod_dbd configuration +DBDriver pgsql +DBDParams "dbname=apacheauth user=apache password=xxxxxx" + +DBDMin 4 +DBDKeep 8 +DBDMax 20 +DBDExptime 300 + +<Directory /usr/www/myhost/private> + # 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" +</Directory> +
Exposing Login Information

-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 APR 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_".

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.

The AuthDBDUserPWQuery 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). -

- - AuthDBDUserPWQuery "SELECT password FROM authn WHERE username = %s" - -

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 AUTHENTICATE_<COLUMN>. + 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 %s format specifier.

+ Example
+AuthDBDUserPWQuery \
+  "SELECT password FROM authn WHERE user = %s"
+
 +

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 mod_authn_dbd.

+

If httpd was built against APR 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 AUTHENTICATE_COLUMN.

@@ -145,18 +145,22 @@ configuration required in some web applications.

The AuthDBDUserRealmQuery 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 %s format specifiers.

+ Example
+AuthDBDUserRealmQuery \
+  "SELECT password FROM authn WHERE user = %s AND realm = %s"
+
 +

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 mod_authn_dbd.

+

If httpd was built against APR 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 AUTHENTICATE_COLUMN.

- - AuthDBDUserRealmQuery "SELECT password FROM authn - WHERE username = %s AND realm = %s" - -

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 AUTHENTICATE_<COLUMN>. -

- diff --git a/docs/manual/mod/mod_dbd.xml b/docs/manual/mod/mod_dbd.xml index 30969242223..cc77ceea2ad 100644 --- a/docs/manual/mod/mod_dbd.xml +++ b/docs/manual/mod/mod_dbd.xml @@ -31,11 +31,14 @@

mod_dbd manages SQL database connections using - apr_dbd. - It provides database connections on request to modules - requiring SQL database functions, and takes care of + APR. 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.

+ for both threaded and non-threaded MPMs. For details, see the + APR website and this overview of the + Apache DBD Framework + by its original developer. +

 Password Formats @@ -47,9 +50,9 @@ classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python). On threaded platform, it provides an altogether more scalable and efficient connection pool, as - described in this article at ApacheTutor. mod_dbd supersedes - the modules presented in that article.

+ described in this + article at ApacheTutor. Note that mod_dbd + supersedes the modules presented in that article.

Apache DBD API