$Id: README,v 1.4 2010/05/29 03:57:07 cm-msk Exp $

INTRODUCTION

This is the development area for OpenDKIM's statistics collection system.

The OpenDKIM filter has an option to collect and record anonymous statistics
about DKIM's operation including information like number of signatures,
percent of signature failures, first-party vs. third-party signatures,
ADSP statistics, etc. and store them into a database.  An additional tool
called opendkim-stats (in the "opendkim" directory) can be used to retrieve
this information and display it or mail it someplace for data aggregation.

This is especially useful for the industry to collect usage statistics
about how DKIM is being used, the proliferation of third-party signing,
etc.  You are encouraged, but certainly not required, to provide usage
information to The OpenDKIM Project.  The code that does the reporting is
open source and included in this package, so you can easily verify that
nothing private is being revealed in the data thus submitted.

This directory contains information and software for generating, receiving
and processing such reports, including commands for creating a MySQL database
to store the reports for later query, and a program that can receive reports
generated by opendkim-stats to put such data directly into that database.


INSTALLATION

This system can be made to work with any SQL-based system, but the provided
scripts and documentation presume MySQL.

1.	Compile OpenDKIM using the "--enable-stats" option:

	% ./configure --enable-stats
	% make

	Note that this requires that libdb, part of the SleepyCat
	open source database package, be installed on your system.
	Most of the time your software vendor will have this available
	for you as an optional package (RPM for most Linux systems,
	a port for most BSD systems) or you can get it over the web as
	open source and build it yourself from this URL:

	http://www.oracle.com/database/berkeley-db/index.html

	When the compilation is complete, follow the instructions in the
	INSTALL file to complete installation and configuration.  In your
	configuration file, add a "Statistics" line indicating where you
	want your filter to accumulate data about your mail.

2.	Install MySQL.  Create credentials for an "opendkim" user, optionally
	with some password.  Create a database called "opendkim".  Note that
	this does NOT refer to a "real" UNIX user and password.  The user you
	create must be granted INSERT access to that table and must also
	have the global FILE privilege.

3. 	From inside the MySQL client, source the "mkdb.mysql" script.
	This will create the table required to store the statistics reports.

4.	Install the "opendkim-importstats.sh" scripts someplace.  Edit it as
	needed to reflect the credentials of your "opendkim" MySQL user.

5.	Configure OpenDKIM to have statistics enabled, and begin reporting
	them to a file someplace.  See the opendkim(8) and opendkim.conf(5)
	man pages for details.

6.	Initialize the statistics database:

	opendkim-stats -i /path/to/stats.db
		
7.	Restart opendkim.

8a.	If you are interested in accumulating only your own statistics,
	add a crontab entry that executes the following at some reasonable
	frequency:

	/path/to/opendkim-importstats.sh 

	Also, edit that script so that the "statsdb" variable is set to the
	location of your statistics database in the SETUP section near
	the top, e.g.:

		statsdb="/var/db/opendkim/stats.db"

	The path to the database is as set in your opendkim.conf(5)
	configuration file.

8b.	If you are interested in accepting reports from someplace else,
	create a mailing alias that is a pipe to the "opendkim-importstats.sh"
	script.  Edit that script so that the "statsdb" variable is set to the
	empty string in the SETUP section near the top, e.g.:

		statsdb=""

8c.	If you are interested in exporting your reports, add a crontab
	entry that executes the following at some reasonable frequency:

	opendkim-stats -c -m <address> -r <path-to-stats-db>

	...where <address> is the address to which you would like to send
	your reports.  The path to the database is as set in your
	opendkim.conf(5) configuration file.
