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, SPF, and ARC
        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

(9) Depending on your settings, mail sent with a policy of p=quarantine
    may wind up in your MTA's "Hold" or "Quarantine" queue.

	The setting "HoldQuarantinedMessages" (defaults to false) can be used
	to control this feature.


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_HELOHOST		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
					"<sender@example.org">)

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 (signing domain, selector, evaluation - same as SPF)

	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

	arc		ARC evaluation (0 = pass, 2 = fail)

	arc_policy	ARC local policy evaluation (evaluation -- same as ARC, ARC seal
			data - JSON-encoded array of governing arc seal fields: instance,
			domain, selector)

ARC Evaluation by OpenDMARC
===========================

Mailing lists and some forwarders can break authentication of valid
messages, resulting in false positive DMARC failures.  ARC allows such
intermediaries to encapsulate the authentication information they saw, so that
a downstream MTA can more properly evaluate the message and deliver around an
otherwise false positive result.

OpenDMARC uses ARC information to deliver a message around a failure in a very
specific and limited fashion.  OpenDMARC does not evaluate the ARC status of a
message; it relies on other ARC-aware software (such as OpenARC) to make a
determination about the validity of any ARC information on the message, and
attach those results in the Authentication-Results for the local
TrustedAuthservID.  At a high level (explained further below), OpenDMARC then
reviews those trusted results, makes a determination as to whether it trusts
the domains that sealed the chain, and decides whether to override the
original message disposition. The results of this evaluation are then recorded
and returned in the "local_policy" comment to the sending domain owner.

OpenDMARC makes its limited determination about delivering around a DMARC
failure in the following way: When DMARC fails, and there is one and only one
ARC status in the Authentication-Results for the local TrustedAuthservID, and
that ARC status is "pass", and all sealers are on the DomainWhitelist, then
the message will be delivered instead of being subject to the DMARC policy of
the sending domain.


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:

	opendmarc-announce@trusteddomain.org (release announcements)
	opendmarc-users@trusteddomain.org (general discussion)

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

To report bugs and feature requests, you can access the GitHub "tracker"
facilities at https://github.com/trusteddomainproject/OpenDMARC/issues.