=item C<CookieSecret>
-The secret cookie which should be set along with whatever response is
-sent to the client. The value in the hash is the actual secret value
+The login cookie which should be set along with whatever response is
+sent to the client. The value in the hash is the actual value
of the cookie as a string. C<undef> means no cookie setting header
should be sent; C<''> means the cookie should be cleared.
Must be an absolute filename.
-=item C<assocdb_dbh>
+=item C<db_dbh>
CGI::Auth::Flexible needs a database for recording users' login
session. This database needs to be shared across all instances of the
changes made by CAF and your own application.)
By default, CAF uses a sqlite3 database stored on local disk in the
-file named by C<assocdb_path>. This will be suitable for all
+file named by C<db_path>. This will be suitable for all
applications which run on a single host.
This value, if supplied, should be a DBI handle for the database.
-=item C<assocdb_dsn>
+=item C<db_dsn>
This is the DSN to pass to C<< DBI->connect >>. Used only if
-C<assocdb_dbh> is not supplied.
+C<db_dbh> is not supplied.
-=item C<assocdb_path>
+=item C<db_path>
Path to the sqlite3 database used for CAF's session storage. The
-default is currently C<caf-assocs.db> but will change in the future.
+default is C<caf.db>.
-Used only if neither C<assocdb_dbh> or C<assocdb_dsn> are supplied.
+Used only if neither C<db_dbh> or C<db_dsn> are supplied.
If this is a relative path, it is in C<dir>.
-=item C<assocdb_table>
+=item C<db_prefix>
Prefix for the SQL tables and indices to use (and to create, if
necessary).
database, you may need to create for yourself the tables and indices
used by CGI::Auth::Flexible.
+By default, every time CAF starts up, it attempts to execute certain
+fixed database statements to create the tables and indices it needs.
+These are run with C<$dbh->{PrintError}> set to 0. The effect with
+sqlite (the default database) is that the tables and indices are
+created iff they do not already exist, and that no spurious errors are
+reported anywhere.
+
+If you use a different database, or just prefer to do things
+differently, you can set up the tables yourself and/or disable or
+modify the default setup statements, via the C<db_setup_stmts>
+setting.
+
+The tables needed are:
+
+
xxx document _db_setup_do
xxx make _db_setup_do explicitly overrideable
xxx remaining settings
- assocdb_password
+ db_password
username_password_error
login_ok
get_cookie_domain
xxx document cookie usage
xxx document construct_cookie fn
+xxx document @default_db_setup_statements
+
xxx bugs wrong default random on Linux
xxx bugs wrong default random on *BSD
xxx bugs keys not shared should be in db
-xxx rename caf-assocs.db
xxx rename caf_assocsecret default cookie name
xxx mention relationship between login_timeout and cookies