INTRODUCTION
============

This document will walk you through the process of configuring and activating
the OpenDMARC filter once it has been compiled and installed.  In doing so you
will:

o Choose a local socket interface between the filter and your MTA
o Configure your filter
o Activate your filter
o Test your filter


COMPILING AND INSTALLING
========================

The INSTALL document in the root of the build directory covers the compilation
and software installation of opendmarc and its prerequisites.  You should
complete that process before continuing with the next section.


CONFIGURING OPENDMARC
=====================

(1) Take a look at the opendmarc.conf.sample as an example configuration file 
    for your domain.  If you wish to run with anything other than default
    settings, copy that file to /etc/mail/opendmarc.conf and make your changes
    there.

(6) Start opendmarc.  You will need at least the "-p" option, unless you
    specified it in opendmarc.conf above.  If you did set up a configuration
    file, you'll also need to tell opendmarc where to find it (if not
    /etc/mail/opendmarc.conf) via the "-c" option.  For example:

	opendmarc -c CONFPATH

    ...where CONFPATH is the path to the configuration file you wish to
    use.  One or more configuration example files are provided.

(7) Configure your MTA:

    For Sendmail:

    (a) Choose a socket at which the MTA and the filter will rendezvous
        (see the documentation in libmilter for details)

    (b) Add a line like this example to your sendmail.mc using your desired
        socket specification:

	    INPUT_MAIL_FILTER(`opendmarc', `S=inet:8893@localhost')

        Note that this must come after filters that do DKIM and SPF evaluation,
        as this filter relies on the addition of authentication results data
        to the header by upstream filters.

    (c) Rebuild your sendmail.cf in the usual way

    For Postfix:

    (a) Choose a socket at which the MTA and the filter will rendezvous.
        Be careful with UNIX domain sockets as on some distributions and setups
	the smtpd process is running in a chroot environment.  A UNIX socket 
	will need to be visible to the chrooted smtpd process.

    (b) Add the following lines like this example to your postfix main.cf using
        your desired socket specification:

	    smtpd_milters = inet:localhost:8893
	    non_smtpd_milters = inet:localhost:8893
	
        Note that this must come after filters that do DKIM and SPF evaluation,
        as this filter relies on the addition of authentication results data
        to the header by upstream filters.

    (c) If you have a content filter in master.cf that feeds it back into a
        different smtpd process, you should alter the second smtpd process in
	master.cf to contain '-o receive_override_options=no_milters' to
	prevent messages being signed or verified twice.  For tips on avoiding
	DKIM signature breakage, see:
	http://www.postfix.org/MILTER_README.html#workarounds

(8) Restart/reload your MTA.

    For Sendmail:
	kill -1 `head -1 /var/run/sendmail.pid`

    For Postfix:
	postfix reload

	...or the following if master.cf was changed:

	/etc/init.d/postfix restart


TESTING AND DEBUGGING
=====================

This package is used for processing incoming mail.  As such, evaluating
the efficacy and impact of the DMARC policy you publish in your DNS is
not covered here.  These instructions are for checking your site's processing
of arriving mail using opendmarc.

The simplest thing to do to exercise your installation is to construct a test
message that claims to come from some domain (yours or another) and feed
it to opendmarc in test mode.  The command to run the test is as follows:

	opendmarc -t <msgfile> [-c <conffile>]

...where <msgfile> is your test message and <conffile> is your configuration
file (if not the default).  Make sure to set a HistoryFile in your test
configuration so that you can see the raw data the filter records about
messages it receives.  You can add "-v" one or more times to this to get
verbose output, though understanding the output requires some understanding
of how the "milter" protocol works.

Test mode will not start the service; it will process your single input
message and exit.  It will not affect the service if it is already running.
Test mode operates by simulating the arrival of the message via an MTA
talking to the filter.  With enough "-v" options, you will see simulation
of each of the milter calls generated by your message.  Some parameters
to the session have defaults you can override by setting environment variables,
as follows:

	OPENDMARC_TEST_CLIENTHOST	hostname of the SMTP client
					sending the message (default
					is "localhost")

	OPENDMARC_TEST_CLIENTIP		IP addressof the SMTP client
					sending the message, as a string
					(default is "127.0.0.1")

	OPENDMARC_TEST_HELONAME		parameter passed by the SMTP client
					with the HELO/EHLO command
					(default is "localhost")

	OPENDMARC_TEST_ENVFROM		envelope sender, passed by the
					SMTP client with the MAIL FROM
					command (default is
					"<[email protected]">)

In essence, you want to see the result of the mlfi_eom() call, which will
be in the verbose output, and ensure that it matches the action your filter
should be taking in response to the message you've built.

You can also look at the history file produced by your message to ensure
that all the DKIM signatures and SPF results are recorded, and the DMARC
policy matching the From domain (if any) was properly extracted.
Understanding the contents of this file requires some knowledge of
their encodings, but there are only a few of them:

	adkim, aspf	published policy's alignment rule for DKIM and SPF
			(114 = relaxed, 115 = strict)

	align_dkim, align_spf
			whether identifier alignment was established
			for DKIM and SPF (4 = yes, 5 = no)

	spf		SPF evaluation (0 = pass, 2 = fail, 6 = none,
			-1 = not evaluated)

	dkim		DKIM evaluation (same as SPF, followed by the signing
			domain name)

	pdomain		policy domain (the "organizational" domain,
			the one asserting policy)

	from		domain found in the From field

	mfrom		domain found in the MAIL FROM parameter

	policy		policy to enforce, as follows:
			14 = unknown (no record found)
			15 = pass
			16 = reject
			17 = quarantine
			18 = none

SUPPORT
=======

There are two public mailing lists available for news and questions about
OpenDMARC.  To keep up to date on the latest developments, please
subscribe to one or both of the following:

	[email protected] (release announcements)
	[email protected] (general discussion)

These can be accessed via http://www.trusteddomain.org/mailman/listinfo.

To report bugs and feature requests, you can access the SourceForge "tracker"
facilities at http://sourceforge.net/projects/opendmarc.