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 [-c ] ...where is your test message and 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 ") 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: 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 SourceForge "tracker" facilities at http://sourceforge.net/projects/opendmarc.