Commit | Line | Data |
---|---|---|
420a0d19 CE |
1 | From time to time, experimental features may be added to Exim. |
2 | While a feature is experimental, there will be a build-time | |
3 | option whose name starts "EXPERIMENTAL_" that must be set in | |
4 | order to include the feature. This file contains information | |
5 | about experimental features, all of which are unstable and | |
6 | liable to incompatible change. | |
7 | ||
8 | ||
2ea97746 | 9 | Brightmail AntiSpam (BMI) support |
420a0d19 CE |
10 | -------------------------------------------------------------- |
11 | ||
12 | Brightmail AntiSpam is a commercial package. Please see | |
13 | http://www.brightmail.com for more information on | |
14 | the product. For the sake of clarity, we'll refer to it as | |
15 | "BMI" from now on. | |
16 | ||
17 | ||
18 | 0) BMI concept and implementation overview | |
19 | ||
20 | In contrast to how spam-scanning with SpamAssassin is | |
21 | implemented in exiscan-acl, BMI is more suited for per | |
22 | -recipient scanning of messages. However, each messages is | |
23 | scanned only once, but multiple "verdicts" for multiple | |
24 | recipients can be returned from the BMI server. The exiscan | |
25 | implementation passes the message to the BMI server just | |
26 | before accepting it. It then adds the retrieved verdicts to | |
27 | the messages header file in the spool. These verdicts can then | |
28 | be queried in routers, where operation is per-recipient | |
29 | instead of per-message. To use BMI, you need to take the | |
30 | following steps: | |
31 | ||
32 | 1) Compile Exim with BMI support | |
33 | 2) Set up main BMI options (top section of Exim config file) | |
34 | 3) Set up ACL control statement (ACL section of the config | |
35 | file) | |
36 | 4) Set up your routers to use BMI verdicts (routers section | |
37 | of the config file). | |
38 | 5) (Optional) Set up per-recipient opt-in information. | |
39 | ||
40 | These four steps are explained in more details below. | |
41 | ||
42 | 1) Adding support for BMI at compile time | |
43 | ||
44 | To compile with BMI support, you need to link Exim against | |
2ea97746 | 45 | the Brightmail client SDK, consisting of a library |
420a0d19 CE |
46 | (libbmiclient_single.so) and a header file (bmi_api.h). |
47 | You'll also need to explicitly set a flag in the Makefile to | |
48 | include BMI support in the Exim binary. Both can be achieved | |
49 | with these lines in Local/Makefile: | |
50 | ||
51 | EXPERIMENTAL_BRIGHTMAIL=yes | |
52 | CFLAGS=-I/path/to/the/dir/with/the/includefile | |
53 | EXTRALIBS_EXIM=-L/path/to/the/dir/with/the/library -lbmiclient_single | |
54 | ||
55 | If you use other CFLAGS or EXTRALIBS_EXIM settings then | |
56 | merge the content of these lines with them. | |
57 | ||
58 | Note for BMI6.x users: You'll also have to add -lxml2_single | |
59 | to the EXTRALIBS_EXIM line. Users of 5.5x do not need to do | |
60 | this. | |
61 | ||
62 | You should also include the location of | |
63 | libbmiclient_single.so in your dynamic linker configuration | |
64 | file (usually /etc/ld.so.conf) and run "ldconfig" | |
65 | afterwards, or else the produced Exim binary will not be | |
66 | able to find the library file. | |
67 | ||
68 | ||
69 | 2) Setting up BMI support in the Exim main configuration | |
70 | ||
71 | To enable BMI support in the main Exim configuration, you | |
72 | should set the path to the main BMI configuration file with | |
73 | the "bmi_config_file" option, like this: | |
74 | ||
75 | bmi_config_file = /opt/brightmail/etc/brightmail.cfg | |
76 | ||
77 | This must go into section 1 of Exim's configuration file (You | |
78 | can put it right on top). If you omit this option, it | |
79 | defaults to /opt/brightmail/etc/brightmail.cfg. | |
80 | ||
81 | Note for BMI6.x users: This file is in XML format in V6.xx | |
82 | and its name is /opt/brightmail/etc/bmiconfig.xml. So BMI | |
83 | 6.x users MUST set the bmi_config_file option. | |
84 | ||
85 | ||
86 | 3) Set up ACL control statement | |
87 | ||
88 | To optimize performance, it makes sense only to process | |
89 | messages coming from remote, untrusted sources with the BMI | |
90 | server. To set up a messages for processing by the BMI | |
91 | server, you MUST set the "bmi_run" control statement in any | |
92 | ACL for an incoming message. You will typically do this in | |
93 | an "accept" block in the "acl_check_rcpt" ACL. You should | |
94 | use the "accept" block(s) that accept messages from remote | |
95 | servers for your own domain(s). Here is an example that uses | |
96 | the "accept" blocks from Exim's default configuration file: | |
97 | ||
98 | ||
99 | accept domains = +local_domains | |
100 | endpass | |
101 | verify = recipient | |
102 | control = bmi_run | |
103 | ||
104 | accept domains = +relay_to_domains | |
105 | endpass | |
106 | verify = recipient | |
107 | control = bmi_run | |
108 | ||
109 | If bmi_run is not set in any ACL during reception of the | |
110 | message, it will NOT be passed to the BMI server. | |
111 | ||
112 | ||
113 | 4) Setting up routers to use BMI verdicts | |
114 | ||
115 | When a message has been run through the BMI server, one or | |
116 | more "verdicts" are present. Different recipients can have | |
117 | different verdicts. Each recipient is treated individually | |
118 | during routing, so you can query the verdicts by recipient | |
119 | at that stage. From Exim's view, a verdict can have the | |
120 | following outcomes: | |
121 | ||
122 | o deliver the message normally | |
123 | o deliver the message to an alternate location | |
124 | o do not deliver the message | |
125 | ||
126 | To query the verdict for a recipient, the implementation | |
127 | offers the following tools: | |
128 | ||
129 | ||
130 | - Boolean router preconditions. These can be used in any | |
131 | router. For a simple implementation of BMI, these may be | |
132 | all that you need. The following preconditions are | |
133 | available: | |
134 | ||
135 | o bmi_deliver_default | |
136 | ||
137 | This precondition is TRUE if the verdict for the | |
138 | recipient is to deliver the message normally. If the | |
139 | message has not been processed by the BMI server, this | |
140 | variable defaults to TRUE. | |
141 | ||
142 | o bmi_deliver_alternate | |
143 | ||
144 | This precondition is TRUE if the verdict for the | |
145 | recipient is to deliver the message to an alternate | |
146 | location. You can get the location string from the | |
147 | $bmi_alt_location expansion variable if you need it. See | |
148 | further below. If the message has not been processed by | |
149 | the BMI server, this variable defaults to FALSE. | |
150 | ||
151 | o bmi_dont_deliver | |
152 | ||
153 | This precondition is TRUE if the verdict for the | |
154 | recipient is NOT to deliver the message to the | |
155 | recipient. You will typically use this precondition in a | |
156 | top-level blackhole router, like this: | |
157 | ||
158 | # don't deliver messages handled by the BMI server | |
159 | bmi_blackhole: | |
160 | driver = redirect | |
161 | bmi_dont_deliver | |
162 | data = :blackhole: | |
163 | ||
164 | This router should be on top of all others, so messages | |
165 | that should not be delivered do not reach other routers | |
166 | at all. If the message has not been processed by | |
167 | the BMI server, this variable defaults to FALSE. | |
168 | ||
169 | ||
170 | - A list router precondition to query if rules "fired" on | |
171 | the message for the recipient. Its name is "bmi_rule". You | |
172 | use it by passing it a colon-separated list of rule | |
173 | numbers. You can use this condition to route messages that | |
174 | matched specific rules. Here is an example: | |
175 | ||
176 | # special router for BMI rule #5, #8 and #11 | |
177 | bmi_rule_redirect: | |
178 | driver = redirect | |
179 | bmi_rule = 5:8:11 | |
180 | data = postmaster@mydomain.com | |
181 | ||
182 | ||
183 | - Expansion variables. Several expansion variables are set | |
184 | during routing. You can use them in custom router | |
185 | conditions, for example. The following variables are | |
186 | available: | |
187 | ||
188 | o $bmi_base64_verdict | |
189 | ||
190 | This variable will contain the BASE64 encoded verdict | |
191 | for the recipient being routed. You can use it to add a | |
192 | header to messages for tracking purposes, for example: | |
193 | ||
194 | localuser: | |
195 | driver = accept | |
196 | check_local_user | |
197 | headers_add = X-Brightmail-Verdict: $bmi_base64_verdict | |
198 | transport = local_delivery | |
199 | ||
200 | If there is no verdict available for the recipient being | |
201 | routed, this variable contains the empty string. | |
202 | ||
203 | o $bmi_base64_tracker_verdict | |
204 | ||
205 | This variable will contain a BASE64 encoded subset of | |
206 | the verdict information concerning the "rules" that | |
207 | fired on the message. You can add this string to a | |
208 | header, commonly named "X-Brightmail-Tracker". Example: | |
209 | ||
210 | localuser: | |
211 | driver = accept | |
212 | check_local_user | |
213 | headers_add = X-Brightmail-Tracker: $bmi_base64_tracker_verdict | |
214 | transport = local_delivery | |
215 | ||
216 | If there is no verdict available for the recipient being | |
217 | routed, this variable contains the empty string. | |
218 | ||
219 | o $bmi_alt_location | |
220 | ||
221 | If the verdict is to redirect the message to an | |
222 | alternate location, this variable will contain the | |
223 | alternate location string returned by the BMI server. In | |
224 | its default configuration, this is a header-like string | |
225 | that can be added to the message with "headers_add". If | |
226 | there is no verdict available for the recipient being | |
227 | routed, or if the message is to be delivered normally, | |
228 | this variable contains the empty string. | |
229 | ||
230 | o $bmi_deliver | |
231 | ||
232 | This is an additional integer variable that can be used | |
233 | to query if the message should be delivered at all. You | |
234 | should use router preconditions instead if possible. | |
235 | ||
236 | $bmi_deliver is '0': the message should NOT be delivered. | |
237 | $bmi_deliver is '1': the message should be delivered. | |
238 | ||
239 | ||
240 | IMPORTANT NOTE: Verdict inheritance. | |
241 | The message is passed to the BMI server during message | |
242 | reception, using the target addresses from the RCPT TO: | |
243 | commands in the SMTP transaction. If recipients get expanded | |
244 | or re-written (for example by aliasing), the new address(es) | |
245 | inherit the verdict from the original address. This means | |
246 | that verdicts also apply to all "child" addresses generated | |
247 | from top-level addresses that were sent to the BMI server. | |
248 | ||
249 | ||
250 | 5) Using per-recipient opt-in information (Optional) | |
251 | ||
252 | The BMI server features multiple scanning "profiles" for | |
253 | individual recipients. These are usually stored in a LDAP | |
254 | server and are queried by the BMI server itself. However, | |
255 | you can also pass opt-in data for each recipient from the | |
256 | MTA to the BMI server. This is particularly useful if you | |
257 | already look up recipient data in Exim anyway (which can | |
258 | also be stored in a SQL database or other source). This | |
259 | implementation enables you to pass opt-in data to the BMI | |
260 | server in the RCPT ACL. This works by setting the | |
261 | 'bmi_optin' modifier in a block of that ACL. If should be | |
262 | set to a list of comma-separated strings that identify the | |
263 | features which the BMI server should use for that particular | |
264 | recipient. Ideally, you would use the 'bmi_optin' modifier | |
265 | in the same ACL block where you set the 'bmi_run' control | |
266 | flag. Here is an example that will pull opt-in data for each | |
267 | recipient from a flat file called | |
268 | '/etc/exim/bmi_optin_data'. | |
269 | ||
270 | The file format: | |
271 | ||
272 | user1@mydomain.com: <OPTIN STRING1>:<OPTIN STRING2> | |
273 | user2@thatdomain.com: <OPTIN STRING3> | |
274 | ||
275 | ||
276 | The example: | |
277 | ||
278 | accept domains = +relay_to_domains | |
279 | endpass | |
280 | verify = recipient | |
281 | bmi_optin = ${lookup{$local_part@$domain}lsearch{/etc/exim/bmi_optin_data}} | |
282 | control = bmi_run | |
283 | ||
284 | Of course, you can also use any other lookup method that | |
285 | Exim supports, including LDAP, Postgres, MySQL, Oracle etc., | |
286 | as long as the result is a list of colon-separated opt-in | |
287 | strings. | |
288 | ||
289 | For a list of available opt-in strings, please contact your | |
290 | Brightmail representative. | |
291 | ||
292 | ||
293 | ||
294 | ||
420a0d19 CE |
295 | SRS (Sender Rewriting Scheme) Support |
296 | -------------------------------------------------------------- | |
297 | ||
298 | Exiscan currently includes SRS support via Miles Wilton's | |
299 | libsrs_alt library. The current version of the supported | |
2ea97746 | 300 | library is 0.5, there are reports of 1.0 working. |
420a0d19 CE |
301 | |
302 | In order to use SRS, you must get a copy of libsrs_alt from | |
303 | ||
2ea97746 CE |
304 | https://opsec.eu/src/srs/ |
305 | ||
306 | (not the original source, which has disappeared.) | |
420a0d19 CE |
307 | |
308 | Unpack the tarball, then refer to MTAs/README.EXIM | |
309 | to proceed. You need to set | |
310 | ||
311 | EXPERIMENTAL_SRS=yes | |
312 | ||
313 | in your Local/Makefile. | |
314 | ||
315 | ||
2ea97746 | 316 | |
420a0d19 CE |
317 | DCC Support |
318 | -------------------------------------------------------------- | |
2ea97746 | 319 | Distributed Checksum Clearinghouse; http://www.rhyolite.com/dcc/ |
420a0d19 CE |
320 | |
321 | *) Building exim | |
322 | ||
323 | In order to build exim with DCC support add | |
324 | ||
325 | EXPERIMENTAL_DCC=yes | |
326 | ||
327 | to your Makefile. (Re-)build/install exim. exim -d should show | |
328 | EXPERIMENTAL_DCC under "Support for". | |
329 | ||
330 | ||
331 | *) Configuration | |
332 | ||
333 | In the main section of exim.cf add at least | |
334 | dccifd_address = /usr/local/dcc/var/dccifd | |
335 | or | |
336 | dccifd_address = <ip> <port> | |
337 | ||
338 | In the DATA ACL you can use the new condition | |
339 | dcc = * | |
340 | ||
341 | After that "$dcc_header" contains the X-DCC-Header. | |
342 | ||
343 | Return values are: | |
344 | fail for overall "R", "G" from dccifd | |
345 | defer for overall "T" from dccifd | |
346 | accept for overall "A", "S" from dccifd | |
347 | ||
348 | dcc = */defer_ok works as for spamd. | |
349 | ||
350 | The "$dcc_result" variable contains the overall result from DCC | |
351 | answer. There will an X-DCC: header added to the mail. | |
352 | ||
353 | Usually you'll use | |
354 | defer !dcc = * | |
355 | to greylist with DCC. | |
356 | ||
357 | If you set, in the main section, | |
358 | dcc_direct_add_header = true | |
359 | then the dcc header will be added "in deep" and if the spool | |
360 | file was already written it gets removed. This forces Exim to | |
361 | write it again if needed. This helps to get the DCC Header | |
362 | through to eg. SpamAssassin. | |
363 | ||
364 | If you want to pass even more headers in the middle of the | |
365 | DATA stage you can set | |
366 | $acl_m_dcc_add_header | |
367 | to tell the DCC routines to add more information; eg, you might set | |
368 | this to some results from ClamAV. Be careful. Header syntax is | |
369 | not checked and is added "as is". | |
370 | ||
371 | In case you've troubles with sites sending the same queue items from several | |
372 | hosts and fail to get through greylisting you can use | |
373 | $acl_m_dcc_override_client_ip | |
374 | ||
375 | Setting $acl_m_dcc_override_client_ip to an IP address overrides the default | |
376 | of $sender_host_address. eg. use the following ACL in DATA stage: | |
377 | ||
378 | warn set acl_m_dcc_override_client_ip = \ | |
379 | ${lookup{$sender_helo_name}nwildlsearch{/etc/mail/multipleip_sites}{$value}{}} | |
380 | condition = ${if def:acl_m_dcc_override_client_ip} | |
381 | log_message = dbg: acl_m_dcc_override_client_ip set to \ | |
382 | $acl_m_dcc_override_client_ip | |
383 | ||
384 | Then set something like | |
385 | # cat /etc/mail/multipleip_sites | |
386 | mout-xforward.gmx.net 82.165.159.12 | |
387 | mout.gmx.net 212.227.15.16 | |
388 | ||
2ea97746 CE |
389 | Use a reasonable IP. eg. one the sending cluster actually uses. |
390 | ||
391 | ||
420a0d19 CE |
392 | |
393 | DMARC Support | |
394 | -------------------------------------------------------------- | |
395 | ||
396 | DMARC combines feedback from SPF, DKIM, and header From: in order | |
397 | to attempt to provide better indicators of the authenticity of an | |
398 | email. This document does not explain the fundamentals, you | |
399 | should read and understand how it works by visiting the website at | |
400 | http://www.dmarc.org/. | |
401 | ||
402 | DMARC support is added via the libopendmarc library. Visit: | |
403 | ||
404 | http://sourceforge.net/projects/opendmarc/ | |
405 | ||
406 | to obtain a copy, or find it in your favorite rpm package | |
407 | repository. If building from source, this description assumes | |
408 | that headers will be in /usr/local/include, and that the libraries | |
409 | are in /usr/local/lib. | |
410 | ||
411 | 1. To compile Exim with DMARC support, you must first enable SPF. | |
2ea97746 | 412 | Please read the Local/Makefile comments on enabling the SUPPORT_SPF |
420a0d19 CE |
413 | feature. You must also have DKIM support, so you cannot set the |
414 | DISABLE_DKIM feature. Once both of those conditions have been met | |
415 | you can enable DMARC in Local/Makefile: | |
416 | ||
417 | EXPERIMENTAL_DMARC=yes | |
418 | LDFLAGS += -lopendmarc | |
419 | # CFLAGS += -I/usr/local/include | |
420 | # LDFLAGS += -L/usr/local/lib | |
421 | ||
422 | The first line sets the feature to include the correct code, and | |
423 | the second line says to link the libopendmarc libraries into the | |
424 | exim binary. The commented out lines should be uncommented if you | |
425 | built opendmarc from source and installed in the default location. | |
426 | Adjust the paths if you installed them elsewhere, but you do not | |
427 | need to uncomment them if an rpm (or you) installed them in the | |
428 | package controlled locations (/usr/include and /usr/lib). | |
429 | ||
430 | ||
431 | 2. Use the following global settings to configure DMARC: | |
432 | ||
433 | Required: | |
434 | dmarc_tld_file Defines the location of a text file of valid | |
435 | top level domains the opendmarc library uses | |
436 | during domain parsing. Maintained by Mozilla, | |
437 | the most current version can be downloaded | |
438 | from a link at http://publicsuffix.org/list/. | |
2ea97746 | 439 | See also util/renew-opendmarc-tlds.sh script. |
420a0d19 CE |
440 | |
441 | Optional: | |
442 | dmarc_history_file Defines the location of a file to log results | |
443 | of dmarc verification on inbound emails. The | |
444 | contents are importable by the opendmarc tools | |
445 | which will manage the data, send out DMARC | |
446 | reports, and expire the data. Make sure the | |
447 | directory of this file is writable by the user | |
448 | exim runs as. | |
449 | ||
2ea97746 | 450 | dmarc_forensic_sender Alternate email address to use when sending a |
420a0d19 CE |
451 | forensic report detailing alignment failures |
452 | if a sender domain's dmarc record specifies it | |
453 | and you have configured Exim to send them. | |
2ea97746 CE |
454 | |
455 | If set, this is expanded and used for the | |
456 | From: header line; the address is extracted | |
457 | from it and used for the envelope from. | |
458 | If not set, the From: header is expanded from | |
459 | the dsn_from option, and <> is used for the | |
460 | envelope from. | |
461 | ||
462 | Default: unset. | |
420a0d19 CE |
463 | |
464 | ||
465 | 3. By default, the DMARC processing will run for any remote, | |
466 | non-authenticated user. It makes sense to only verify DMARC | |
467 | status of messages coming from remote, untrusted sources. You can | |
468 | use standard conditions such as hosts, senders, etc, to decide that | |
469 | DMARC verification should *not* be performed for them and disable | |
470 | DMARC with a control setting: | |
471 | ||
472 | control = dmarc_disable_verify | |
473 | ||
474 | A DMARC record can also specify a "forensic address", which gives | |
475 | exim an email address to submit reports about failed alignment. | |
476 | Exim does not do this by default because in certain conditions it | |
477 | results in unintended information leakage (what lists a user might | |
478 | be subscribed to, etc). You must configure exim to submit forensic | |
479 | reports to the owner of the domain. If the DMARC record contains a | |
480 | forensic address and you specify the control statement below, then | |
481 | exim will send these forensic emails. It's also advised that you | |
482 | configure a dmarc_forensic_sender because the default sender address | |
483 | construction might be inadequate. | |
484 | ||
2ea97746 | 485 | control = dmarc_enable_forensic |
420a0d19 CE |
486 | |
487 | (AGAIN: You can choose not to send these forensic reports by simply | |
2ea97746 | 488 | not putting the dmarc_enable_forensic control line at any point in |
420a0d19 CE |
489 | your exim config. If you don't tell it to send them, it will not |
490 | send them.) | |
491 | ||
492 | There are no options to either control. Both must appear before | |
493 | the DATA acl. | |
494 | ||
495 | ||
496 | 4. You can now run DMARC checks in incoming SMTP by using the | |
497 | "dmarc_status" ACL condition in the DATA ACL. You are required to | |
498 | call the spf condition first in the ACLs, then the "dmarc_status" | |
499 | condition. Putting this condition in the ACLs is required in order | |
500 | for a DMARC check to actually occur. All of the variables are set | |
501 | up before the DATA ACL, but there is no actual DMARC check that | |
502 | occurs until a "dmarc_status" condition is encountered in the ACLs. | |
503 | ||
504 | The dmarc_status condition takes a list of strings on its | |
505 | right-hand side. These strings describe recommended action based | |
506 | on the DMARC check. To understand what the policy recommendations | |
507 | mean, refer to the DMARC website above. Valid strings are: | |
508 | ||
509 | o accept The DMARC check passed and the library recommends | |
510 | accepting the email. | |
511 | o reject The DMARC check failed and the library recommends | |
512 | rejecting the email. | |
513 | o quarantine The DMARC check failed and the library recommends | |
514 | keeping it for further inspection. | |
515 | o none The DMARC check passed and the library recommends | |
516 | no specific action, neutral. | |
517 | o norecord No policy section in the DMARC record for this | |
518 | sender domain. | |
519 | o nofrom Unable to determine the domain of the sender. | |
520 | o temperror Library error or dns error. | |
521 | o off The DMARC check was disabled for this email. | |
522 | ||
523 | You can prefix each string with an exclamation mark to invert its | |
524 | meaning, for example "!accept" will match all results but | |
525 | "accept". The string list is evaluated left-to-right in a | |
526 | short-circuit fashion. When a string matches the outcome of the | |
527 | DMARC check, the condition succeeds. If none of the listed | |
528 | strings matches the outcome of the DMARC check, the condition | |
529 | fails. | |
530 | ||
531 | Of course, you can also use any other lookup method that Exim | |
532 | supports, including LDAP, Postgres, MySQL, etc, as long as the | |
533 | result is a list of colon-separated strings. | |
534 | ||
2ea97746 CE |
535 | Performing the check sets up information used by the |
536 | ${authresults } expansion item. | |
537 | ||
420a0d19 CE |
538 | Several expansion variables are set before the DATA ACL is |
539 | processed, and you can use them in this ACL. The following | |
540 | expansion variables are available: | |
541 | ||
542 | o $dmarc_status | |
543 | This is a one word status indicating what the DMARC library | |
544 | thinks of the email. It is a combination of the results of | |
545 | DMARC record lookup and the SPF/DKIM/DMARC processing results | |
546 | (if a DMARC record was found). The actual policy declared | |
547 | in the DMARC record is in a separate expansion variable. | |
548 | ||
549 | o $dmarc_status_text | |
550 | This is a slightly longer, human readable status. | |
551 | ||
552 | o $dmarc_used_domain | |
553 | This is the domain which DMARC used to look up the DMARC | |
554 | policy record. | |
555 | ||
556 | o $dmarc_domain_policy | |
557 | This is the policy declared in the DMARC record. Valid values | |
558 | are "none", "reject" and "quarantine". It is blank when there | |
559 | is any error, including no DMARC record. | |
560 | ||
2ea97746 CE |
561 | A now-redundant variable $dmarc_ar_header has now been withdrawn. |
562 | Use the ${authresults } expansion instead. | |
420a0d19 CE |
563 | |
564 | ||
565 | 5. How to enable DMARC advanced operation: | |
566 | By default, Exim's DMARC configuration is intended to be | |
567 | non-intrusive and conservative. To facilitate this, Exim will not | |
568 | create any type of logging files without explicit configuration by | |
569 | you, the admin. Nor will Exim send out any emails/reports about | |
570 | DMARC issues without explicit configuration by you, the admin (other | |
571 | than typical bounce messages that may come about due to ACL | |
572 | processing or failure delivery issues). | |
573 | ||
574 | In order to log statistics suitable to be imported by the opendmarc | |
575 | tools, you need to: | |
576 | a. Configure the global setting dmarc_history_file. | |
577 | b. Configure cron jobs to call the appropriate opendmarc history | |
578 | import scripts and truncating the dmarc_history_file. | |
579 | ||
580 | In order to send forensic reports, you need to: | |
581 | a. Configure the global setting dmarc_forensic_sender. | |
582 | b. Configure, somewhere before the DATA ACL, the control option to | |
583 | enable sending DMARC forensic reports. | |
584 | ||
585 | ||
586 | 6. Example usage: | |
587 | (RCPT ACL) | |
588 | warn domains = +local_domains | |
589 | hosts = +local_hosts | |
590 | control = dmarc_disable_verify | |
591 | ||
592 | warn !domains = +screwed_up_dmarc_records | |
593 | control = dmarc_enable_forensic | |
594 | ||
595 | warn condition = (lookup if destined to mailing list) | |
596 | set acl_m_mailing_list = 1 | |
597 | ||
598 | (DATA ACL) | |
599 | warn dmarc_status = accept : none : off | |
600 | !authenticated = * | |
601 | log_message = DMARC DEBUG: $dmarc_status $dmarc_used_domain | |
420a0d19 CE |
602 | |
603 | warn dmarc_status = !accept | |
604 | !authenticated = * | |
605 | log_message = DMARC DEBUG: '$dmarc_status' for $dmarc_used_domain | |
606 | ||
607 | warn dmarc_status = quarantine | |
608 | !authenticated = * | |
609 | set $acl_m_quarantine = 1 | |
610 | # Do something in a transport with this flag variable | |
611 | ||
612 | deny condition = ${if eq{$dmarc_domain_policy}{reject}} | |
613 | condition = ${if eq{$acl_m_mailing_list}{1}} | |
614 | message = Messages from $dmarc_used_domain break mailing lists | |
615 | ||
616 | deny dmarc_status = reject | |
617 | !authenticated = * | |
2ea97746 | 618 | message = Message from $dmarc_used_domain failed sender's DMARC policy, REJECT |
420a0d19 | 619 | |
2ea97746 | 620 | warn add_header = :at_start:${authresults {$primary_hostname}} |
420a0d19 | 621 | |
420a0d19 | 622 | |
420a0d19 | 623 | |
2ea97746 CE |
624 | DSN extra information |
625 | --------------------- | |
626 | If compiled with EXPERIMENTAL_DSN_INFO extra information will be added | |
627 | to DSN fail messages ("bounces"), when available. The intent is to aid | |
628 | tracing of specific failing messages, when presented with a "bounce" | |
629 | complaint and needing to search logs. | |
420a0d19 CE |
630 | |
631 | ||
2ea97746 CE |
632 | The remote MTA IP address, with port number if nonstandard. |
633 | Example: | |
634 | Remote-MTA: X-ip; [127.0.0.1]:587 | |
635 | Rationale: | |
636 | Several addresses may correspond to the (already available) | |
637 | dns name for the remote MTA. | |
420a0d19 | 638 | |
2ea97746 CE |
639 | The remote MTA connect-time greeting. |
640 | Example: | |
641 | X-Remote-MTA-smtp-greeting: X-str; 220 the.local.host.name ESMTP Exim x.yz Tue, 2 Mar 1999 09:44:33 +0000 | |
642 | Rationale: | |
643 | This string sometimes presents the remote MTA's idea of its | |
644 | own name, and sometimes identifies the MTA software. | |
420a0d19 | 645 | |
2ea97746 CE |
646 | The remote MTA response to HELO or EHLO. |
647 | Example: | |
648 | X-Remote-MTA-helo-response: X-str; 250-the.local.host.name Hello localhost [127.0.0.1] | |
649 | Limitations: | |
650 | Only the first line of a multiline response is recorded. | |
651 | Rationale: | |
652 | This string sometimes presents the remote MTA's view of | |
653 | the peer IP connecting to it. | |
654 | ||
655 | The reporting MTA detailed diagnostic. | |
656 | Example: | |
657 | X-Exim-Diagnostic: X-str; SMTP error from remote mail server after RCPT TO:<d3@myhost.test.ex>: 550 hard error | |
658 | Rationale: | |
659 | This string sometimes give extra information over the | |
660 | existing (already available) Diagnostic-Code field. | |
420a0d19 | 661 | |
420a0d19 | 662 | |
2ea97746 | 663 | Note that non-RFC-documented field names and data types are used. |
420a0d19 | 664 | |
420a0d19 | 665 | |
2ea97746 CE |
666 | LMDB Lookup support |
667 | ------------------- | |
668 | LMDB is an ultra-fast, ultra-compact, crash-proof key-value embedded data store. | |
669 | It is modeled loosely on the BerkeleyDB API. You should read about the feature | |
670 | set as well as operation modes at https://symas.com/products/lightning-memory-mapped-database/ | |
420a0d19 | 671 | |
2ea97746 CE |
672 | LMDB single key lookup support is provided by linking to the LMDB C library. |
673 | The current implementation does not support writing to the LMDB database. | |
420a0d19 | 674 | |
2ea97746 CE |
675 | Visit https://github.com/LMDB/lmdb to download the library or find it in your |
676 | operating systems package repository. | |
420a0d19 | 677 | |
420a0d19 CE |
678 | If building from source, this description assumes that headers will be in |
679 | /usr/local/include, and that the libraries are in /usr/local/lib. | |
680 | ||
2ea97746 | 681 | 1. In order to build exim with LMDB lookup support add or uncomment |
420a0d19 | 682 | |
2ea97746 | 683 | EXPERIMENTAL_LMDB=yes |
420a0d19 CE |
684 | |
685 | to your Local/Makefile. (Re-)build/install exim. exim -d should show | |
2ea97746 | 686 | Experimental_LMDB in the line "Support for:". |
420a0d19 | 687 | |
2ea97746 CE |
688 | EXPERIMENTAL_LMDB=yes |
689 | LDFLAGS += -llmdb | |
420a0d19 CE |
690 | # CFLAGS += -I/usr/local/include |
691 | # LDFLAGS += -L/usr/local/lib | |
692 | ||
693 | The first line sets the feature to include the correct code, and | |
2ea97746 | 694 | the second line says to link the LMDB libraries into the |
420a0d19 | 695 | exim binary. The commented out lines should be uncommented if you |
2ea97746 | 696 | built LMDB from source and installed in the default location. |
420a0d19 CE |
697 | Adjust the paths if you installed them elsewhere, but you do not |
698 | need to uncomment them if an rpm (or you) installed them in the | |
699 | package controlled locations (/usr/include and /usr/lib). | |
700 | ||
2ea97746 CE |
701 | 2. Create your LMDB files, you can use the mdb_load utility which is |
702 | part of the LMDB distribution our your favourite language bindings. | |
420a0d19 | 703 | |
2ea97746 CE |
704 | 3. Add the single key lookups to your exim.conf file, example lookups |
705 | are below. | |
420a0d19 | 706 | |
2ea97746 CE |
707 | ${lookup{$sender_address_domain}lmdb{/var/lib/baruwa/data/db/relaydomains.mdb}{$value}} |
708 | ${lookup{$sender_address_domain}lmdb{/var/lib/baruwa/data/db/relaydomains.mdb}{$value}fail} | |
709 | ${lookup{$sender_address_domain}lmdb{/var/lib/baruwa/data/db/relaydomains.mdb}} | |
420a0d19 | 710 | |
420a0d19 | 711 | |
2ea97746 CE |
712 | Queuefile transport |
713 | ------------------- | |
714 | Queuefile is a pseudo transport which does not perform final delivery. | |
715 | It simply copies the exim spool files out of the spool directory into | |
716 | an external directory retaining the exim spool format. | |
420a0d19 | 717 | |
2ea97746 CE |
718 | The spool files can then be processed by external processes and then |
719 | requeued into exim spool directories for final delivery. | |
720 | However, note carefully the warnings in the main documentation on | |
721 | qpool file formats. | |
420a0d19 | 722 | |
2ea97746 CE |
723 | The motivation/inspiration for the transport is to allow external |
724 | processes to access email queued by exim and have access to all the | |
725 | information which would not be available if the messages were delivered | |
726 | to the process in the standard email formats. | |
420a0d19 | 727 | |
2ea97746 CE |
728 | The mailscanner package is one of the processes that can take advantage |
729 | of this transport to filter email. | |
420a0d19 | 730 | |
2ea97746 CE |
731 | The transport can be used in the same way as the other existing transports, |
732 | i.e by configuring a router to route mail to a transport configured with | |
733 | the queuefile driver. | |
420a0d19 | 734 | |
2ea97746 | 735 | The transport only takes one option: |
420a0d19 | 736 | |
2ea97746 CE |
737 | * directory - This is used to specify the directory messages should be |
738 | copied to. Expanded. | |
420a0d19 | 739 | |
2ea97746 CE |
740 | The generic transport options (body_only, current_directory, disable_logging, |
741 | debug_print, delivery_date_add, envelope_to_add, event_action, group, | |
742 | headers_add, headers_only, headers_remove, headers_rewrite, home_directory, | |
743 | initgroups, max_parallel, message_size_limit, rcpt_include_affixes, | |
744 | retry_use_local_part, return_path, return_path_add, shadow_condition, | |
745 | shadow_transport, transport_filter, transport_filter_timeout, user) are | |
746 | ignored. | |
420a0d19 | 747 | |
2ea97746 | 748 | Sample configuration: |
420a0d19 | 749 | |
2ea97746 | 750 | (Router) |
420a0d19 | 751 | |
2ea97746 CE |
752 | scan: |
753 | driver = accept | |
754 | transport = scan | |
420a0d19 | 755 | |
2ea97746 | 756 | (Transport) |
420a0d19 | 757 | |
2ea97746 CE |
758 | scan: |
759 | driver = queuefile | |
760 | directory = /var/spool/baruwa-scanner/input | |
420a0d19 | 761 | |
420a0d19 | 762 | |
2ea97746 | 763 | In order to build exim with Queuefile transport support add or uncomment |
420a0d19 | 764 | |
2ea97746 | 765 | EXPERIMENTAL_QUEUEFILE=yes |
420a0d19 | 766 | |
2ea97746 CE |
767 | to your Local/Makefile. (Re-)build/install exim. exim -d should show |
768 | Experimental_QUEUEFILE in the line "Support for:". | |
420a0d19 | 769 | |
420a0d19 | 770 | |
2ea97746 CE |
771 | ARC support |
772 | ----------- | |
773 | Specification: https://tools.ietf.org/html/draft-ietf-dmarc-arc-protocol-11 | |
774 | Note that this is not an RFC yet, so may change. | |
420a0d19 | 775 | |
2ea97746 CE |
776 | ARC is intended to support the utility of SPF and DKIM in the presence of |
777 | intermediaries in the transmission path - forwarders and mailinglists - | |
778 | by establishing a cryptographically-signed chain in headers. | |
420a0d19 | 779 | |
2ea97746 CE |
780 | Normally one would only bother doing ARC-signing when functioning as |
781 | an intermediary. One might do verify for local destinations. | |
420a0d19 | 782 | |
2ea97746 CE |
783 | ARC uses the notion of a "ADministrative Management Domain" (ADMD). |
784 | Described in RFC 5598 (section 2.3), this is essentially the set of | |
785 | mail-handling systems that the mail transits. A label should be chosen to | |
786 | identify the ADMD. Messages should be ARC-verified on entry to the ADMD, | |
787 | and ARC-signed on exit from it. | |
420a0d19 | 788 | |
420a0d19 | 789 | |
2ea97746 CE |
790 | Verification |
791 | -- | |
792 | An ACL condition is provided to perform the "verifier actions" detailed | |
793 | in section 6 of the above specification. It may be called from the DATA ACL | |
794 | and succeeds if the result matches any of a given list. | |
795 | It also records the highest ARC instance number (the chain size) | |
796 | and verification result for later use in creating an Authentication-Results: | |
797 | standard header. | |
420a0d19 | 798 | |
2ea97746 | 799 | verify = arc/<acceptable_list> none:fail:pass |
420a0d19 | 800 | |
2ea97746 | 801 | add_header = :at_start:${authresults {<admd-identifier>}} |
420a0d19 | 802 | |
2ea97746 CE |
803 | Note that it would be wise to strip incoming messages of A-R headers |
804 | that claim to be from our own <admd-identifier>. | |
420a0d19 | 805 | |
2ea97746 | 806 | There are four new variables: |
420a0d19 | 807 | |
2ea97746 CE |
808 | $arc_state One of pass, fail, none |
809 | $arc_state_reason (if fail, why) | |
810 | $arc_domains colon-sep list of ARC chain domains, in chain order. | |
811 | problematic elements may have empty list elements | |
812 | $arc_oldest_pass lowest passing instance number of chain | |
420a0d19 | 813 | |
2ea97746 CE |
814 | Example: |
815 | logwrite = oldest-p-ams: <${reduce {$lh_ARC-Authentication-Results:} \ | |
816 | {} \ | |
817 | {${if = {$arc_oldest_pass} \ | |
818 | {${extract {i}{${extract {1}{;}{$item}}}}} \ | |
819 | {$item} {$value}}} \ | |
820 | }> | |
821 | ||
822 | Receive log lines for an ARC pass will be tagged "ARC". | |
823 | ||
824 | ||
825 | Signing | |
826 | -- | |
827 | arc_sign = <admd-identifier> : <selector> : <privkey> [ : <options> ] | |
828 | An option on the smtp transport, which constructs and prepends to the message | |
829 | an ARC set of headers. The textually-first Authentication-Results: header | |
830 | is used as a basis (you must have added one on entry to the ADMD). | |
831 | Expanded as a whole; if unset, empty or forced-failure then no signing is done. | |
832 | If it is set, all of the first three elements must be non-empty. | |
833 | ||
834 | The fourth element is optional, and if present consists of a comma-separated list | |
835 | of options. The options implemented are | |
836 | ||
837 | timestamps Add a t= tag to the generated AMS and AS headers, with the | |
838 | current time. | |
839 | expire[=<val>] Add an x= tag to the generated AMS header, with an expiry time. | |
840 | If the value <val> is an plain number it is used unchanged. | |
841 | If it starts with a '+' then the following number is added | |
842 | to the current time, as an offset in seconds. | |
843 | If a value is not given it defaults to a one month offset. | |
844 | ||
845 | [As of writing, gmail insist that a t= tag on the AS is mandatory] | |
846 | ||
847 | Caveats: | |
848 | * There must be an Authentication-Results header, presumably added by an ACL | |
849 | while receiving the message, for the same ADMD, for arc_sign to succeed. | |
850 | This requires careful coordination between inbound and outbound logic. | |
851 | ||
852 | Only one A-R header is taken account of. This is a limitation versus | |
853 | the ARC spec (which says that all A-R headers from within the ADMD must | |
854 | be used). | |
855 | ||
856 | * If passing a message to another system, such as a mailing-list manager | |
857 | (MLM), between receipt and sending, be wary of manipulations to headers made | |
858 | by the MLM. | |
859 | + For instance, Mailman with REMOVE_DKIM_HEADERS==3 might improve | |
860 | deliverability in a pre-ARC world, but that option also renames the | |
861 | Authentication-Results header, which breaks signing. | |
862 | ||
863 | * Even if you use multiple DKIM keys for different domains, the ARC concept | |
864 | should try to stick to one ADMD, so pick a primary domain and use that for | |
865 | AR headers and outbound signing. | |
866 | ||
867 | Signing is not compatible with cutthrough delivery; any (before expansion) | |
868 | value set for the option will result in cutthrough delivery not being | |
869 | used via the transport in question. | |
870 | ||
871 | ||
872 | ||
873 | ||
874 | REQUIRETLS support | |
875 | ------------------ | |
876 | Ref: https://tools.ietf.org/html/draft-ietf-uta-smtp-require-tls-03 | |
877 | ||
878 | If compiled with EXPERIMENTAL_REQUIRETLS support is included for this | |
879 | feature, where a REQUIRETLS option is added to the MAIL command. | |
880 | The client may not retry in clear if the MAIL+REQUIRETLS fails (or was never | |
881 | offered), and the server accepts an obligation that any onward transmission | |
882 | by SMTP of the messages accepted will also use REQUIRETLS - or generate a | |
883 | fail DSN. | |
884 | ||
885 | The Exim implementation includes | |
886 | - a main-part option tls_advertise_requiretls; host list, default "*" | |
887 | - an observability variable $requiretls returning yes/no | |
888 | - an ACL "control = requiretls" modifier for setting the requirement | |
889 | - Log lines and Received: headers capitalise the S in the protocol | |
890 | element: "P=esmtpS" | |
891 | ||
892 | Differences from spec: | |
893 | - we support upgrading the requirement for REQUIRETLS, including adding | |
894 | it from cold, within an MTA. The spec only define the sourcing MUA | |
895 | as being able to source the requirement, and makes no mention of upgrade. | |
896 | - No support is coded for the RequireTLS header (which can be used | |
897 | to annul DANE and/or STS policiy). [this can _almost_ be done in | |
898 | transport option expansions, but not quite: it requires tha DANE-present | |
899 | but STARTTLS-failing targets fallback to cleartext, which current DANE | |
900 | coding specifically blocks] | |
901 | ||
902 | Note that REQUIRETLS is only advertised once a TLS connection is achieved | |
903 | (in contrast to STARTTLS). If you want to check the advertising, do something | |
904 | like "swaks -s 127.0.0.1 -tls -q HELO". | |
905 | ||
906 | ||
907 | ||
908 | ||
909 | Early pipelining support | |
910 | ------------------------ | |
911 | Ref: https://datatracker.ietf.org/doc/draft-harris-early-pipe/ | |
912 | ||
913 | If compiled with EXPERIMENTAL_PIPE_CONNECT support is included for this feature. | |
914 | The server advertises the feature in its EHLO response, currently using the name | |
915 | "X_PIPE_CONNECT" (this will change, some time in the future). | |
916 | A client may cache this information, along with the rest of the EHLO response, | |
917 | and use it for later connections. Those later ones can send esmtp commands before | |
918 | a banner is received. | |
919 | ||
920 | Up to 1.5 roundtrip times can be taken out of cleartext connections, 2.5 on | |
921 | STARTTLS connections. | |
922 | ||
923 | In combination with the traditional PIPELINING feature the following example | |
924 | sequences are possible (among others): | |
925 | ||
926 | (client) (server) | |
927 | ||
928 | EHLO,MAIL,RCPT,DATA -> | |
929 | <- banner,EHLO-resp,MAIL-ack,RCPT-ack,DATA-goahead | |
930 | message-data -> | |
931 | ------ | |
932 | ||
933 | EHLO,MAIL,RCPT,BDAT -> | |
934 | <- banner,EHLO-resp,MAIL-ack,RCPT-ack | |
935 | message-data -> | |
936 | ------ | |
937 | ||
938 | EHLO,STARTTLS -> | |
939 | <- banner,EHLO-resp,TLS-goahead | |
940 | TLS1.2-client-hello -> | |
941 | <- TLS-server-hello,cert,hello-done | |
942 | client-Kex,change-cipher,finished -> | |
943 | <- change-cipher,finished | |
944 | EHLO,MAIL,RCPT,DATA -> | |
945 | <- EHLO-resp,MAIL-ack,RCPT-ack,DATA-goahead | |
946 | ||
947 | ------ | |
948 | (tls-on-connect) | |
949 | TLS1.2-client-hello -> | |
950 | <- TLS-server-hello,cert,hello-done | |
951 | client-Kex,change-cipher,finished -> | |
952 | <- change-cipher,finshed | |
953 | <- banner | |
954 | EHLO,MAIL,RCPT,DATA -> | |
955 | <- EHLO-resp,MAIL-ack,RCPT-ack,DATA-goahead | |
956 | ||
957 | Where the initial client packet is SMTP, it can combine with the TCP Fast Open | |
958 | feature and be sent in the TCP SYN. | |
959 | ||
960 | ||
961 | A main-section option "pipelining_connect_advertise_hosts" (default: *) | |
962 | and an smtp transport option "hosts_pipe_connect" (default: unset) | |
963 | control the feature. | |
964 | ||
965 | If the "pipelining" log_selector is enabled, the "L" field in server <= | |
966 | log lines has a period appended if the feature was advertised but not used; | |
967 | or has an asterisk appended if the feature was used. In client => lines | |
968 | the "L" field has an asterisk appended if the feature was used. | |
969 | ||
970 | The "retry_data_expire" option controls cache invalidation. | |
971 | Entries are also rewritten (or cleared) if the adverised features | |
972 | change. | |
973 | ||
974 | ||
975 | NOTE: since the EHLO command must be constructed before the connection is | |
976 | made it cannot depend on the interface IP address that will be used. | |
977 | Transport configurations should be checked for this. An example avoidance: | |
978 | ||
979 | helo_data = ${if def:sending_ip_address \ | |
980 | {${lookup dnsdb{>! ptr=$sending_ip_address} \ | |
981 | {${sg{$value} {^([^!]*).*\$} {\$1}}} fail}} \ | |
982 | {$primary_hostname}} | |
420a0d19 | 983 | |
420a0d19 CE |
984 | |
985 | ||
986 | ||
987 | -------------------------------------------------------------- | |
988 | End of file | |
989 | -------------------------------------------------------------- |