SQLAuthenticate {on | off}
or
SQLAuthenticate [ users ] [ groups ] [ userset [fast] ] [ groupset [fast] ]
Default
SQLAuthenticate on
Context
server config, <Global>, <VirtualHost>
Module
mod_sql
Compatibility
1.2.5rc1 and later
The SQLAuthenticate directive configures mod_sql's authentication behavior, controlling whether to provide user and/or group information during authentication, and how that provisioning is performed. The parameters may appear in any order.
The available parameter values are:
on
Shorthand for SQLAuthenticate users groups userset groupset.
off
Disables all mod_sql authentication functions.
users
If present, mod_sql will do user lookups. If not present, mod_sql will do no user lookups at all, including the {set|get|end}pwent() calls (see below).
groups
If present, mod_sql will do group lookups. If not present, mod_sql will do no group lookups at all, including the {set|get|end}grent() calls (see below).
userset[fast]
If present, mod_sql will process the potentially expensive {set|get|end}pwent() calls. If not present, mod_sql will not process these calls. Adding the suffix "fast" tells mod_sql to process the users as a single large query, rather than making a query per user. This may significantly reduce the number of queries against the database at the expense of increased memory use. This parameter will have no effect if "users" is not specified.
groupset[fast]
If present, mod_sql will process the potentially expensive {set|get|end}grent() calls. If not present, mod_sql will not process these calls. Adding the suffix "fast" tells mod_sql to process the groups as a single large query, rather than making a query per group. This may significantly reduce the number of queries against the database at the expense of increased memory use. This parameter will have no effect if "groups" is not specified.
The SQLLog and SQLShowInfo directives will always be processed by mod_sql. The SQLAuthenticate directive only affects the user and group lookup/authentication portions of the module.
Turning off (i.e. by not including) the userset or groupset parameters affects the functionality of mod_sql. Not allowing these lookups may remove the ability to control access or control functionality by group membership, depending on your other authentication handlers and the data available to them. At the same time, choosing not to do these lookups may dramatically speed login for many large sites.
The "fast" suffix is not appropriate for every site. Normally, mod_sql will retrieve a list of users and groups, and get information from the database on a per-user or per-group basis. This is query intensive: it requires (nn + 1) queries, where n is the number of users or groups to lookup. By choosing "fast" lookups, mod_sql will make a single SELECT query to get information from the database.
In exchange for the radical reduction in the number of queries, the single query will increase the memory consumption of the process; all group or user information will be read at once rather than in discrete chunks.
Normally mod_sql allows multiple group members per row, and multiple rows per group. If you use the "fast" option for groupset, you must use only one row per group. For example, normally mod_sql treats the following three tables in exactly the same way:
|--------------------------------------------------|
| GROUPNAME | GID | MEMBERS |
|--------------------------------------------------|
| group1 | 1000 | naomi |
| group1 | 1000 | priscilla |
| group1 | 1000 | gertrude |
|--------------------------------------------------|
|--------------------------------------------------|
| GROUPNAME | GID | MEMBERS |
|--------------------------------------------------|
| group1 | 1000 | naomi, priscilla |
| group1 | 1000 | gertrude |
|--------------------------------------------------|
|--------------------------------------------------|
| GROUPNAME | GID | MEMBERS |
|--------------------------------------------------|
| group1 | 1000 | naomi, priscilla, gertrude |
|--------------------------------------------------|
If you use the "fast" option, mod_sql assumes that all entries are structured like the last example.