1INTRODUCTION 2============ 3 4This document will walk you through the process of configuring and activating 5the OpenDMARC filter once it has been compiled and installed. In doing so you 6will: 7 8o Choose a local socket interface between the filter and your MTA 9o Configure your filter 10o Activate your filter 11o Test your filter 12 13 14COMPILING AND INSTALLING 15======================== 16 17The INSTALL document in the root of the build directory covers the compilation 18and software installation of opendmarc and its prerequisites. You should 19complete that process before continuing with the next section. 20 21 22CONFIGURING OPENDMARC 23===================== 24 25(1) Take a look at the opendmarc.conf.sample as an example configuration file 26 for your domain. If you wish to run with anything other than default 27 settings, copy that file to /etc/mail/opendmarc.conf and make your changes 28 there. 29 30(6) Start opendmarc. You will need at least the "-p" option, unless you 31 specified it in opendmarc.conf above. If you did set up a configuration 32 file, you'll also need to tell opendmarc where to find it (if not 33 /etc/mail/opendmarc.conf) via the "-c" option. For example: 34 35 opendmarc -c CONFPATH 36 37 ...where CONFPATH is the path to the configuration file you wish to 38 use. One or more configuration example files are provided. 39 40(7) Configure your MTA: 41 42 For Sendmail: 43 44 (a) Choose a socket at which the MTA and the filter will rendezvous 45 (see the documentation in libmilter for details) 46 47 (b) Add a line like this example to your sendmail.mc using your desired 48 socket specification: 49 50 INPUT_MAIL_FILTER(`opendmarc', `S=inet:8893@localhost') 51 52 Note that this must come after filters that do DKIM, SPF, and ARC 53 evaluation, as this filter relies on the addition of authentication 54 results data to the header by upstream filters. 55 56 (c) Rebuild your sendmail.cf in the usual way 57 58 For Postfix: 59 60 (a) Choose a socket at which the MTA and the filter will rendezvous. 61 Be careful with UNIX domain sockets as on some distributions and setups 62 the smtpd process is running in a chroot environment. A UNIX socket 63 will need to be visible to the chrooted smtpd process. 64 65 (b) Add the following lines like this example to your postfix main.cf using 66 your desired socket specification: 67 68 smtpd_milters = inet:localhost:8893 69 non_smtpd_milters = inet:localhost:8893 70 71 Note that this must come after filters that do DKIM and SPF evaluation, 72 as this filter relies on the addition of authentication results data 73 to the header by upstream filters. 74 75 (c) If you have a content filter in master.cf that feeds it back into a 76 different smtpd process, you should alter the second smtpd process in 77 master.cf to contain '-o receive_override_options=no_milters' to 78 prevent messages being signed or verified twice. For tips on avoiding 79 DKIM signature breakage, see: 80 http://www.postfix.org/MILTER_README.html#workarounds 81 82(8) Restart/reload your MTA. 83 84 For Sendmail: 85 kill -1 `head -1 /var/run/sendmail.pid` 86 87 For Postfix: 88 postfix reload 89 90 ...or the following if master.cf was changed: 91 92 /etc/init.d/postfix restart 93 94(9) Depending on your settings, mail sent with a policy of p=quarantine 95 may wind up in your MTA's "Hold" or "Quarantine" queue. 96 97 The setting "HoldQuarantinedMessages" (defaults to false) can be used 98 to control this feature. 99 100 101TESTING AND DEBUGGING 102===================== 103 104This package is used for processing incoming mail. As such, evaluating 105the efficacy and impact of the DMARC policy you publish in your DNS is 106not covered here. These instructions are for checking your site's processing 107of arriving mail using opendmarc. 108 109The simplest thing to do to exercise your installation is to construct a test 110message that claims to come from some domain (yours or another) and feed 111it to opendmarc in test mode. The command to run the test is as follows: 112 113 opendmarc -t <msgfile> [-c <conffile>] 114 115...where <msgfile> is your test message and <conffile> is your configuration 116file (if not the default). Make sure to set a HistoryFile in your test 117configuration so that you can see the raw data the filter records about 118messages it receives. You can add "-v" one or more times to this to get 119verbose output, though understanding the output requires some understanding 120of how the "milter" protocol works. 121 122Test mode will not start the service; it will process your single input 123message and exit. It will not affect the service if it is already running. 124Test mode operates by simulating the arrival of the message via an MTA 125talking to the filter. With enough "-v" options, you will see simulation 126of each of the milter calls generated by your message. Some parameters 127to the session have defaults you can override by setting environment variables, 128as follows: 129 130 OPENDMARC_TEST_CLIENTHOST hostname of the SMTP client 131 sending the message (default 132 is "localhost") 133 134 OPENDMARC_TEST_CLIENTIP IP addressof the SMTP client 135 sending the message, as a string 136 (default is "127.0.0.1") 137 138 OPENDMARC_TEST_HELOHOST parameter passed by the SMTP client 139 with the HELO/EHLO command 140 (default is "localhost") 141 142 OPENDMARC_TEST_ENVFROM envelope sender, passed by the 143 SMTP client with the MAIL FROM 144 command (default is 145 "<sender@example.org">) 146 147In essence, you want to see the result of the mlfi_eom() call, which will 148be in the verbose output, and ensure that it matches the action your filter 149should be taking in response to the message you've built. 150 151You can also look at the history file produced by your message to ensure 152that all the DKIM signatures and SPF results are recorded, and the DMARC 153policy matching the From domain (if any) was properly extracted. 154Understanding the contents of this file requires some knowledge of 155their encodings, but there are only a few of them: 156 157 adkim, aspf published policy's alignment rule for DKIM and SPF 158 (114 = relaxed, 115 = strict) 159 160 align_dkim, align_spf 161 whether identifier alignment was established 162 for DKIM and SPF (4 = yes, 5 = no) 163 164 spf SPF evaluation (0 = pass, 2 = fail, 6 = none, 165 -1 = not evaluated) 166 167 dkim DKIM evaluation (signing domain, selector, evaluation - same as SPF) 168 169 pdomain policy domain (the "organizational" domain, 170 the one asserting policy) 171 172 from domain found in the From field 173 174 mfrom domain found in the MAIL FROM parameter 175 176 policy policy to enforce, as follows: 177 14 = unknown (no record found) 178 15 = pass 179 16 = reject 180 17 = quarantine 181 18 = none 182 183 arc ARC evaluation (0 = pass, 2 = fail) 184 185 arc_policy ARC local policy evaluation (evaluation -- same as ARC, ARC seal 186 data - JSON-encoded array of governing arc seal fields: instance, 187 domain, selector) 188 189ARC Evaluation by OpenDMARC 190=========================== 191 192Mailing lists and some forwarders can break authentication of valid 193messages, resulting in false positive DMARC failures. ARC allows such 194intermediaries to encapsulate the authentication information they saw, so that 195a downstream MTA can more properly evaluate the message and deliver around an 196otherwise false positive result. 197 198OpenDMARC uses ARC information to deliver a message around a failure in a very 199specific and limited fashion. OpenDMARC does not evaluate the ARC status of a 200message; it relies on other ARC-aware software (such as OpenARC) to make a 201determination about the validity of any ARC information on the message, and 202attach those results in the Authentication-Results for the local 203TrustedAuthservID. At a high level (explained further below), OpenDMARC then 204reviews those trusted results, makes a determination as to whether it trusts 205the domains that sealed the chain, and decides whether to override the 206original message disposition. The results of this evaluation are then recorded 207and returned in the "local_policy" comment to the sending domain owner. 208 209OpenDMARC makes its limited determination about delivering around a DMARC 210failure in the following way: When DMARC fails, and there is one and only one 211ARC status in the Authentication-Results for the local TrustedAuthservID, and 212that ARC status is "pass", and all sealers are on the DomainWhitelist, then 213the message will be delivered instead of being subject to the DMARC policy of 214the sending domain. 215 216 217SUPPORT 218======= 219 220There are two public mailing lists available for news and questions about 221OpenDMARC. To keep up to date on the latest developments, please 222subscribe to one or both of the following: 223 224 opendmarc-announce@trusteddomain.org (release announcements) 225 opendmarc-users@trusteddomain.org (general discussion) 226 227These can be accessed via http://www.trusteddomain.org/mailman/listinfo. 228 229To report bugs and feature requests, you can access the GitHub "tracker" 230facilities at https://github.com/trusteddomainproject/OpenDMARC/issues. 231