Debian Codegraph @

README

raw
1 DESCRIPTION:
2 ------------
3
4 This is version 1.12 of Apache::AuthDBI and Apache::DBI.
5
6 These modules are supposed to be used with the Apache server together with
7 an embedded perl interpreter like mod_perl. They provide support for basic
8 authentication and authorization as well as support for persistent database
9 connections via Perl's Database Independent Interface (DBI).
10
11 o 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
16 o 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
20 Apache::DBI has been in widespread deployment on many platforms for
21 years. Apache::DBI is one of the most widely used mod_perl related
22 modules. It can be considered stable.
23
24
25
26 RECENT CHANGES:
27 ---------------
28
29 See the Changes file for more detail
30
31
32 DEVELOPMENT:
33 ------------
34
35 Apache::DBI is in svn at perl.org; see
36 http://svn.perl.org/modules/Apache-DBI
37
38
39 EXAMPLES:
40 ---------
41
42 Here we explain only some simple examples. For further information and
43 limitations please read the module documentation.
44
45
46 1. user authentication
47
48 Suppose you want to restrict access to a certain URL to a specific user and
49 the necessary information for restricting user access is stored in your
50 database. A typical setup would be the following:
51
52 conf/httpd.conf:
53
54 PerlModule Apache::AuthDBI
55
56 URL/.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
75 In 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
77 accessing the URL for the first time a requester pops up, asking for username
78 and password. For authentication the module retrieves for the given username
79 the password from the database. This is compared with the crypted password
80 given by the user. If the check succeeds, the user is given access to the
81 specified URL.
82
83 Please do not confuse this user authentication with the username/password
84 needed for the database connect. These two authentications are completely
85 independent !
86
87 Windows users should turn off the case-sensitive option.
88
89
90 2. group authorization
91
92 Suppose you want to restrict access to a certain URL to a specific user group
93 and the necessary information for restricting user access is stored in your
94 database. A typical setup would be the following:
95
96 conf/httpd.conf:
97
98 PerlModule Apache::AuthDBI
99
100 URL/.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
121 In 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,
124 asking for username and password. The first check (authentication) retrieves
125 for the given username the password from the database. This is compared with
126 the crypted password given by the user. In a second check (authorization)
127 the groups of the given username are looked up in the database and compared
128 with the groups required in the .htaccess file. If both checks succeed, the
129 user is given access to the specified URL.
130
131 Please do not confuse the user authentication with the username/password
132 needed for the database connect. These two authentications are completely
133 independent !
134
135 Although authorization handles all types of basic authentication it is
136 perfectly sufficient to configure only authentication, as long, as the
137 require token restricts access to 'valid-user' or to one or more single user
138 names. You need to configure authorization only if you have more than one
139 require token or if the require token contains one or more group names.
140
141
142 3. persistent database connection
143
144 The following information is intended to motivate the use of persistent
145 database connections and to explain the necessary configuration.
146
147 In the above example for user authorization the requester asking for username
148 and password pops up only once. The browser stores the user input and provides
149 it to subsequent requests. But the sequence of two database accesses is done
150 for every request, e.g. if your restricted URL contains a HTML page with some
151 images, this sequence is executed once for the HTML page and once for every
152 image ! 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
154 for the authorization procedure. This drawback can be overcome with the use of
155 persistent database connections as provided by the Apache::DBI module.
156
157 The benefit of a persistent database connection is not limited to the use
158 of authorization. Every application, which does a lot of database queries,
159 should gain a significant performance boost, when using persistent database
160 connections.
161
162 If you plan to use persistent database connections, there is only one thing
163 to do: add the following configuration directive to conf/httpd.conf or to
164 your startup.pl:
165
166 PerlModule Apache::DBI # this comes first !!
167 .... # other modules using DBI
168
169 Do not change your perl scripts ! In particular do not add any
170 'use Apache::DBI;' statements. Also there is no need to remove
171 the $dbh->disconnect statements from your perl scripts.
172
173 The DBI module checks when it is loaded if the Apache::DBI module has been
174 loaded before (that's the reason the Apache::DBI module has to come first).
175 In this case, during the database connect, control flow goes through the
176 Apache::DBI module which stores the new database handle in a global hash and
177 which overloads the disconnect method with a do-nothing.
178
179 With the above configuration every server initiates a database connection upon
180 the first connect request. Sometimes it is more convenient to initiate all
181 needed 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
185 This method is supposed to be called in a startup file, in which also all
186 needed modules can be loaded. As an example the file startup.pl is provided.
187 Add all other modules you need to this file and just add one line to your
188 httpd.conf:
189
190 PerlRequire /usr/local/apache/perl/startup.pl
191
192 This way all modules are pulled into the main httpd process. When the main
193 process forks his children, the code of all modules is already in place and
194 the database handle will also be initiated.
195
196 WARNING: Do not attempt to open a persistent database connection in the parent
197 process (via PerlRequire or PerlModule). If you do, children will get a copy
198 of this handle, causing clashes when the handle is used by two processes at
199 the same time. Each child must have it's own unique connection handle. For
200 the same reason it is not possible, to share one database handle between all
201 servers using some IPC mechanism.
202
203 If you want to make sure that the module works correctly, turn on debugging
204 as described below and search for 'Apache::DBI' in the output. You should
205 get one 'new connect' message for every server process. Any subsequent request
206 should result in a 'already connected' message. Please keep in mind, that
207 server processes may be killed as well as newly created depending upon your
208 configuration and depending upon your load. Every new server process needs to
209 do its own initial database connect.
210
211 Another useful method for enhancing the performance is to enable the caching in
212 AuthDBI 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
214 considerably.
215
216
217 COPYRIGHT:
218 ----------
219
220 You may distribute under the terms of either the GNU General Public
221 License or the Artistic License, as specified in the Perl README file.
222
223
224 PREREQUISITES:
225 --------------
226
227 Configure 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
232 If there are no security reasons to limit the API, just use EVERYTHING=1.
233
234 mod_perl2 RC5 and higher should work with Apache::DBI 0.96 and higher.
235 No specific switches must be passed to mod_perl2's Makefile.PL.
236
237 INSTALLATION:
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
247 IF YOU HAVE PROBLEMS:
248 ---------------------
249
250 Please read the README and the the module documentation: 'perldoc Apache::AuthDBI',
251 'perldoc Apache::DBI'.
252 Please verify your setup: turn on debug output and compare it to traces.txt.
253
254 If you have problems with persistent database connections, verify that everything
255 works correct without using Apache::DBI.
256
257 Before sending a bug report it might be useful to look at the debug output.
258 To enable full debug output set the following variables in startup.pl or in your
259 perl script:
260
261 $Apache::DBI::DEBUG = 2;
262 $Apache::AuthDBI::DEBUG = 2;
263
264 and watch the error_log. Compare the output to the traces in traces.txt.
265
266 If this doesn't help, please send an email to <[email protected]> and include
267 the 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
276 A common problem is an error-message that $dbh will not stay shared. A
277 complete explanation for this behavior is given in the modperl-FAQ. In
278 short, instead of this:
279
280 my $dbh = ...;
281 subroutine();
282 sub subroutine {
283 $dbh->....
284 }
285
286 do this:
287
288 my $dbh = ...;
289 subroutine($dbh);
290 sub subroutine {
291 my $dbh = shift;
292 $dbh->....
293 }
294
295
296
297 FURTHER INFORMATION:
298 --------------------
299
300 mod_perl by Doug MacEachern [email protected]
301 http://perl.apache.org/
302
303 DBI by Tim Bunce [email protected]
304 http://dbi.perl.org/
305
306 Apache by Apache Group news:comp.infosystems.www.servers.unix
307 [email protected]
308 http://httpd.apache.org/
309
310
311 ---------------------------------------------------------------------------
312
313 Edmund Mergl <[email protected]>
314 Ask Bjoern Hansen <[email protected]>
315 Philip M. Gollucci <[email protected]>
316
317 ---------------------------------------------------------------------------