2003-04-17
Shibboleth MySQL Credential Cache
Version 0.9

BUILDING THE C++ CODE

First make sure you have OpenSAML and Shibboleth installed.  This code
depends on a successful installation of both OpenSAML and Shibboleth
(and all their respective dependencies).

Next you'll need to make sure you've got a MySQL Embedded Server
installation on your system (see www.mysql.com).  This requires MySQL
versions >= 4.0.x, and in particular a configuration configured
"--with-embedded-server."  Even more importantly MySQL must be built
with the same C++ compiler you use to compile Shib and SAML.  This
also means the binary packages distributed from mysql.com are probably
not usable directly.

Once you've got MySQL, Shibboleth, OpenSAML, Xerces, and log4cpp
installed you can configure and build the shib-mysql-ccache code.
Running "./configure --help" will describe all the various configure
options available, but the options of note are:

	   --with-xerces=
	   --with-log4cpp=
	   --with-saml=
	   --with-shibboleth=
	   --with-mysql=

If you have xerces, log4cpp, saml, and shibboleth installed in the
same directory (e.g. /opt/shibboleth) then you only need to supply
--with-xerces=/opt/shibboleth and all the paths will get set properly.

The MySQL configuration looks for "mysql_config" in your path or uses
the provided --with-mysql=<path> and looks in the "bin" directory for
<path>/bin/mysql_config.  Note that this will always look in your PATH
first, so you cannot use --with-mysql= to override a mysql_config in
your path.  (This may get fixed in a future release).

An example configure and build would look like:

   ./configure --prefix=/opt/shibboleth --with-xerces=/opt/shibboleth
   [configure output snipped]
   make all
   make install

This will install libshib-mysql-ccache.so into <prefix>/lib, and you
can configure shibboleth to use it.


RUNNING WITH THE MYSQL CCACHE

The following process explains how to modify your shibboleth.ini
configuration to run with the MySQL CCache:

1) load the ccache module by adding it to the [extensions:saml]
   section in the ini file:

        mysql = /opt/shibboleth/lib/libshib-mysql-ccache.so

2) You can use the new cache by setting the cacheType to "mysql", like:

        cacheType = mysql

3) You can configure two timeout periods; the cacheTimeout configures
   how long a session is cached in RAM, and there is a new
   "mysql-cache-timeout" that defines how long a session is cached in
   the database.  This allows you to set something like:

        cacheTimeout = 3600
        mysql-cache-timeout = 14400

   This means that sessions remain in the database for 4 hours, but
   they will be removed from RAM cache after one hour.  This lets you
   tune your memory usage by flushing your sessions from the database
   and from RAM over different periods of time.

   If you choose not to set the mysql-cache-timeout, it will use the
   cacheTimeout value.  The default timeout is 8 hours.  The recheck
   time is shared with the memory cache, and is still set using the
   cacheClean option.  The default recheck period is 5 minutes.

4) You can add additional MySQL configuration options by putting them
   into the [mysql] section of the ini file.  For example, if you want
   to set the location where mysql will store the shar datafiles, you
   can set a value like:

        arg0 = --datadir=/home/shibboleth/data

   The 'arg0' part is ignored (but each one much be unique); the rest
   of the line is supplied to MySQL.  Other potential arguments are
   available; see the MySQL documentation for more information.