1DESCRIPTION: 2------------ 3 4This is version 1.08 of Apache::AuthDBI and Apache::DBI. 5 6These modules are supposed to be used with the Apache server together with 7an embedded perl interpreter like mod_perl. They provide support for basic 8authentication and authorization as well as support for persistent database 9connections via Perl's Database Independent Interface (DBI). 10 11o DBI.pm provides persistent database connections: 12 - connections can be established during server-startup 13 - configurable rollback to ensure data integrity 14 - configurable verification of the connections to avoid time-outs. 15 16o AuthDBI.pm provides authentication and authorization: 17 - optional shared cache for passwords to minimize database load 18 - configurable cleanup-handler deletes outdated entries from the cache 19 20Apache::DBI has been in widespread deployment on many platforms for 21years. Apache::DBI is one of the most widely used mod_perl related 22modules. It can be considered stable. 23 24 25 26RECENT CHANGES: 27--------------- 28 29 See the Changes file for more detail 30 31 32DEVELOPMENT: 33------------ 34 35Apache::DBI is in svn at perl.org; see 36http://svn.perl.org/modules/Apache-DBI 37 38 39EXAMPLES: 40--------- 41 42Here we explain only some simple examples. For further information and 43limitations please read the module documentation. 44 45 461. user authentication 47 48Suppose you want to restrict access to a certain URL to a specific user and 49the necessary information for restricting user access is stored in your 50database. A typical setup would be the following: 51 52conf/httpd.conf: 53 54 PerlModule Apache::AuthDBI 55 56URL/.htaccess: 57 58 AuthName DBI 59 AuthType Basic 60 61 PerlAuthenHandler Apache::AuthDBI::authen 62 63 PerlSetVar Auth_DBI_data_source dbi:driver:dsn 64 PerlSetVar Auth_DBI_username db_username 65 PerlSetVar Auth_DBI_password db_password 66 # DBI->connect($data_source, $username, $password) 67 68 PerlSetVar Auth_DBI_pwd_table users 69 PerlSetVar Auth_DBI_uid_field username 70 PerlSetVar Auth_DBI_pwd_field password 71 #SELECT pwd_field FROM pwd_table WHERE uid_field=$user 72 73 require user myuser 74 75In this example it is assumed, that your database contains a table named 76'users' which has at least the two columns 'username' and 'password'. When 77accessing the URL for the first time a requester pops up, asking for username 78and password. For authentication the module retrieves for the given username 79the password from the database. This is compared with the crypted password 80given by the user. If the check succeeds, the user is given access to the 81specified URL. 82 83Please do not confuse this user authentication with the username/password 84needed for the database connect. These two authentications are completely 85independent ! 86 87Windows users should turn off the case-sensitive option. 88 89 902. group authorization 91 92Suppose you want to restrict access to a certain URL to a specific user group 93and the necessary information for restricting user access is stored in your 94database. A typical setup would be the following: 95 96conf/httpd.conf: 97 98 PerlModule Apache::AuthDBI 99 100URL/.htaccess: 101 102 AuthName DBI 103 AuthType Basic 104 105 PerlAuthenHandler Apache::AuthDBI::authen 106 PerlAuthzHandler Apache::AuthDBI::authz 107 108 PerlSetVar Auth_DBI_data_source dbi:mydriver:mydsn 109 PerlSetVar Auth_DBI_username db_username 110 PerlSetVar Auth_DBI_password db_password 111 # DBI->connect($data_source, $username, $password) 112 113 PerlSetVar Auth_DBI_pwd_table users 114 PerlSetVar Auth_DBI_uid_field username 115 PerlSetVar Auth_DBI_pwd_field password 116 PerlSetVar Auth_DBI_grp_field groupname 117 #SELECT grp_field FROM pwd_table WHERE uid_field=$user 118 119 require group mygroup 120 121In this example it is assumed, that your database contains a table named 122'users' which has at least the three columns 'username', 'password' and 123'groupname'. When accessing the URL for the first time a requester pops up, 124asking for username and password. The first check (authentication) retrieves 125for the given username the password from the database. This is compared with 126the crypted password given by the user. In a second check (authorization) 127the groups of the given username are looked up in the database and compared 128with the groups required in the .htaccess file. If both checks succeed, the 129user is given access to the specified URL. 130 131Please do not confuse the user authentication with the username/password 132needed for the database connect. These two authentications are completely 133independent ! 134 135Although authorization handles all types of basic authentication it is 136perfectly sufficient to configure only authentication, as long, as the 137require token restricts access to 'valid-user' or to one or more single user 138names. You need to configure authorization only if you have more than one 139require token or if the require token contains one or more group names. 140 141 1423. persistent database connection 143 144The following information is intended to motivate the use of persistent 145database connections and to explain the necessary configuration. 146 147In the above example for user authorization the requester asking for username 148and password pops up only once. The browser stores the user input and provides 149it to subsequent requests. But the sequence of two database accesses is done 150for every request, e.g. if your restricted URL contains a HTML page with some 151images, this sequence is executed once for the HTML page and once for every 152image ! For databases which needs a significant amount of time for the connect 153(e.g. start of a backend process) this might become an unacceptable overhead 154for the authorization procedure. This drawback can be overcome with the use of 155persistent database connections as provided by the Apache::DBI module. 156 157The benefit of a persistent database connection is not limited to the use 158of authorization. Every application, which does a lot of database queries, 159should gain a significant performance boost, when using persistent database 160connections. 161 162If you plan to use persistent database connections, there is only one thing 163to do: add the following configuration directive to conf/httpd.conf or to 164your startup.pl: 165 166 PerlModule Apache::DBI # this comes first !! 167 .... # other modules using DBI 168 169Do not change your perl scripts ! In particular do not add any 170'use Apache::DBI;' statements. Also there is no need to remove 171the $dbh->disconnect statements from your perl scripts. 172 173The DBI module checks when it is loaded if the Apache::DBI module has been 174loaded before (that's the reason the Apache::DBI module has to come first). 175In this case, during the database connect, control flow goes through the 176Apache::DBI module which stores the new database handle in a global hash and 177which overloads the disconnect method with a do-nothing. 178 179With the above configuration every server initiates a database connection upon 180the first connect request. Sometimes it is more convenient to initiate all 181needed database handles upon process startup. This can be done with the method: 182 183 Apache::DBI->connect_on_init($data_source, $username, $auth, \%attr) 184 185This method is supposed to be called in a startup file, in which also all 186needed modules can be loaded. As an example the file startup.pl is provided. 187Add all other modules you need to this file and just add one line to your 188httpd.conf: 189 190 PerlRequire /usr/local/apache/perl/startup.pl 191 192This way all modules are pulled into the main httpd process. When the main 193process forks his children, the code of all modules is already in place and 194the database handle will also be initiated. 195 196WARNING: Do not attempt to open a persistent database connection in the parent 197process (via PerlRequire or PerlModule). If you do, children will get a copy 198of this handle, causing clashes when the handle is used by two processes at 199the same time. Each child must have it's own unique connection handle. For 200the same reason it is not possible, to share one database handle between all 201servers using some IPC mechanism. 202 203If you want to make sure that the module works correctly, turn on debugging 204as described below and search for 'Apache::DBI' in the output. You should 205get one 'new connect' message for every server process. Any subsequent request 206should result in a 'already connected' message. Please keep in mind, that 207server processes may be killed as well as newly created depending upon your 208configuration and depending upon your load. Every new server process needs to 209do its own initial database connect. 210 211Another useful method for enhancing the performance is to enable the caching in 212AuthDBI setting Auth_DBI_cache_time > 0 and to use shared memory for the cache 213(see the module documentation for details). This will reduce the database load 214considerably. 215 216 217COPYRIGHT: 218---------- 219 220You may distribute under the terms of either the GNU General Public 221License or the Artistic License, as specified in the Perl README file. 222 223 224PREREQUISITES: 225-------------- 226 227Configure mod_perl1 with: 228 229 perl Makefile.PL PERL_CHILD_INIT=1 PERL_AUTHEN=1 PERL_AUTHZ=1 230 PERL_CLEANUP=1 PERL_STACKED_HANDLERS=1 231 232If there are no security reasons to limit the API, just use EVERYTHING=1. 233 234mod_perl2 RC5 and higher should work with Apache::DBI 0.96 and higher. 235No specific switches must be passed to mod_perl2's Makefile.PL. 236 237INSTALLATION: 238------------- 239 240 perl Makefile.PL 241 make 242 make test # only works with MySQL so far; patches welcome 243 make install 244 245 246 247IF YOU HAVE PROBLEMS: 248--------------------- 249 250Please read the README and the the module documentation: 'perldoc Apache::AuthDBI', 251'perldoc Apache::DBI'. 252Please verify your setup: turn on debug output and compare it to traces.txt. 253 254If you have problems with persistent database connections, verify that everything 255works correct without using Apache::DBI. 256 257Before sending a bug report it might be useful to look at the debug output. 258To enable full debug output set the following variables in startup.pl or in your 259perl script: 260 261 $Apache::DBI::DEBUG = 2; 262 $Apache::AuthDBI::DEBUG = 2; 263 264and watch the error_log. Compare the output to the traces in traces.txt. 265 266If this doesn't help, please send an email to <modperl@apache.org> and include 267the following information in your bug-report: 268 269 - debug output, 270 - output of perl -V, 271 - version of ApacheDBI, 272 - version of DBI, 273 - used database 274 275 276A common problem is an error-message that $dbh will not stay shared. A 277complete explanation for this behavior is given in the modperl-FAQ. In 278short, instead of this: 279 280 my $dbh = ...; 281 subroutine(); 282 sub subroutine { 283 $dbh->.... 284 } 285 286do this: 287 288 my $dbh = ...; 289 subroutine($dbh); 290 sub subroutine { 291 my $dbh = shift; 292 $dbh->.... 293 } 294 295 296 297FURTHER INFORMATION: 298-------------------- 299 300mod_perl by Doug MacEachern modperl-subscribe@perl.apache.org 301 http://perl.apache.org/ 302 303DBI by Tim Bunce dbi-users-subscribe@perl.org 304 http://dbi.perl.org/ 305 306Apache by Apache Group news:comp.infosystems.www.servers.unix 307 users-subscribe@httpd.apache.org 308 http://httpd.apache.org/ 309 310 311--------------------------------------------------------------------------- 312 313 Edmund Mergl <E.Mergl@bawue.de> 314 Ask Bjoern Hansen <ask@develooper.com> 315 Philip M. Gollucci <pgollucci@p6m7g8.com> 316 317--------------------------------------------------------------------------- 318