OPENDMARC REPORTS
=================

This directory contains tools necessary to generate DMARC reports at regular
intervals.  It includes the following:

	opendmarc-expire	perl script to expire old DMARC records from
				the database; meant to be run from cron

	opendmarc-expire.8	man page for the above

	opendmarc-import	perl script to import opendmarc history files
				into the database; meant to be run from cron

	opendmarc-import.8	man page for the above

	opendmarc-params	perl script to adjust domain-specific opendmarc
				data in the database

	opendmarc-params.8	man page for the above

	opendmarc-reports	perl script to generate DMARC reports
				whenever it is run; meant to be run from cron

	opendmarc-reports.8	man page for the above

The adjacent "db" directory contains an SQL schema to be used with this
package.  The opendmarc filter populates the tables in that schema as messages
are received and DMARC policies evaluated.  The scripts in here use the
accumulated information to generate reports, and age out old data.

To use schema.mysql, enter the MySQL command line tool, connect to the
database in which you want to create the required tables, and type
"source schema.mysql".

DEPENDENCIES
============

The OpenDMARC reports package requires a recent installation of Perl (>= 5) and
also the JSON module. The latter can be installed, in most cases, with the
following command:

	sudo perl -MCPAN -e 'install JSON'

On debian:

	sudo apt-get install libjson-perl

SETUP
=====

1) From within the MySQL command line environment, "source schema.mysql" to
   create the required database and tables.  You may also wish to set up
   users and access grants for users that will access this data.

2) Add a HistoryFile entry to opendmarc.conf referring to the location where
   per-message DMARC details should be recorded.  This location should be
   readable and writable by the user running the filter, but nobody else.

3) Add a cron job that will use opendmarc-import to import the history file's
   contents at regular and fairly frequent intervals (each minute or at least
   every five minutes).  The included opendmarc-importstats script might be
   useful here.  Ensure the appropriate database access parameters (names,
   users, passwords) are set in the script.

4) Add a cron job that will run opendmarc-reports to generate and send the
   XML reports based on recent database entries.

--
Copyright (c) 2012-2014, 2016-2018, The Trusted Domain Project.
All rights reserved.
