| 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 | |
| 9 | Brightmail AntiSpam (BMI) support |
| 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 |
| 45 | the Brightmail client SDK, consisting of a library |
| 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 | |
| 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 |
| 300 | library is 0.5, there are reports of 1.0 working. |
| 301 | |
| 302 | In order to use SRS, you must get a copy of libsrs_alt from |
| 303 | |
| 304 | https://opsec.eu/src/srs/ |
| 305 | |
| 306 | (not the original source, which has disappeared.) |
| 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 | |
| 316 | |
| 317 | DCC Support |
| 318 | -------------------------------------------------------------- |
| 319 | Distributed Checksum Clearinghouse; http://www.rhyolite.com/dcc/ |
| 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 | |
| 389 | Use a reasonable IP. eg. one the sending cluster actually uses. |
| 390 | |
| 391 | |
| 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. |
| 412 | Please read the Local/Makefile comments on enabling the SUPPORT_SPF |
| 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/. |
| 439 | See also util/renew-opendmarc-tlds.sh script. |
| 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 | |
| 450 | dmarc_forensic_sender The email address to use when sending a |
| 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. |
| 454 | Default: do-not-reply@$default_hostname |
| 455 | |
| 456 | |
| 457 | 3. By default, the DMARC processing will run for any remote, |
| 458 | non-authenticated user. It makes sense to only verify DMARC |
| 459 | status of messages coming from remote, untrusted sources. You can |
| 460 | use standard conditions such as hosts, senders, etc, to decide that |
| 461 | DMARC verification should *not* be performed for them and disable |
| 462 | DMARC with a control setting: |
| 463 | |
| 464 | control = dmarc_disable_verify |
| 465 | |
| 466 | A DMARC record can also specify a "forensic address", which gives |
| 467 | exim an email address to submit reports about failed alignment. |
| 468 | Exim does not do this by default because in certain conditions it |
| 469 | results in unintended information leakage (what lists a user might |
| 470 | be subscribed to, etc). You must configure exim to submit forensic |
| 471 | reports to the owner of the domain. If the DMARC record contains a |
| 472 | forensic address and you specify the control statement below, then |
| 473 | exim will send these forensic emails. It's also advised that you |
| 474 | configure a dmarc_forensic_sender because the default sender address |
| 475 | construction might be inadequate. |
| 476 | |
| 477 | control = dmarc_enable_forensic |
| 478 | |
| 479 | (AGAIN: You can choose not to send these forensic reports by simply |
| 480 | not putting the dmarc_enable_forensic control line at any point in |
| 481 | your exim config. If you don't tell it to send them, it will not |
| 482 | send them.) |
| 483 | |
| 484 | There are no options to either control. Both must appear before |
| 485 | the DATA acl. |
| 486 | |
| 487 | |
| 488 | 4. You can now run DMARC checks in incoming SMTP by using the |
| 489 | "dmarc_status" ACL condition in the DATA ACL. You are required to |
| 490 | call the spf condition first in the ACLs, then the "dmarc_status" |
| 491 | condition. Putting this condition in the ACLs is required in order |
| 492 | for a DMARC check to actually occur. All of the variables are set |
| 493 | up before the DATA ACL, but there is no actual DMARC check that |
| 494 | occurs until a "dmarc_status" condition is encountered in the ACLs. |
| 495 | |
| 496 | The dmarc_status condition takes a list of strings on its |
| 497 | right-hand side. These strings describe recommended action based |
| 498 | on the DMARC check. To understand what the policy recommendations |
| 499 | mean, refer to the DMARC website above. Valid strings are: |
| 500 | |
| 501 | o accept The DMARC check passed and the library recommends |
| 502 | accepting the email. |
| 503 | o reject The DMARC check failed and the library recommends |
| 504 | rejecting the email. |
| 505 | o quarantine The DMARC check failed and the library recommends |
| 506 | keeping it for further inspection. |
| 507 | o none The DMARC check passed and the library recommends |
| 508 | no specific action, neutral. |
| 509 | o norecord No policy section in the DMARC record for this |
| 510 | sender domain. |
| 511 | o nofrom Unable to determine the domain of the sender. |
| 512 | o temperror Library error or dns error. |
| 513 | o off The DMARC check was disabled for this email. |
| 514 | |
| 515 | You can prefix each string with an exclamation mark to invert its |
| 516 | meaning, for example "!accept" will match all results but |
| 517 | "accept". The string list is evaluated left-to-right in a |
| 518 | short-circuit fashion. When a string matches the outcome of the |
| 519 | DMARC check, the condition succeeds. If none of the listed |
| 520 | strings matches the outcome of the DMARC check, the condition |
| 521 | fails. |
| 522 | |
| 523 | Of course, you can also use any other lookup method that Exim |
| 524 | supports, including LDAP, Postgres, MySQL, etc, as long as the |
| 525 | result is a list of colon-separated strings. |
| 526 | |
| 527 | Performing the check sets up information used by the |
| 528 | ${authresults } expansion item. |
| 529 | |
| 530 | Several expansion variables are set before the DATA ACL is |
| 531 | processed, and you can use them in this ACL. The following |
| 532 | expansion variables are available: |
| 533 | |
| 534 | o $dmarc_status |
| 535 | This is a one word status indicating what the DMARC library |
| 536 | thinks of the email. It is a combination of the results of |
| 537 | DMARC record lookup and the SPF/DKIM/DMARC processing results |
| 538 | (if a DMARC record was found). The actual policy declared |
| 539 | in the DMARC record is in a separate expansion variable. |
| 540 | |
| 541 | o $dmarc_status_text |
| 542 | This is a slightly longer, human readable status. |
| 543 | |
| 544 | o $dmarc_used_domain |
| 545 | This is the domain which DMARC used to look up the DMARC |
| 546 | policy record. |
| 547 | |
| 548 | o $dmarc_domain_policy |
| 549 | This is the policy declared in the DMARC record. Valid values |
| 550 | are "none", "reject" and "quarantine". It is blank when there |
| 551 | is any error, including no DMARC record. |
| 552 | |
| 553 | A now-redundant variable $dmarc_ar_header has now been withdrawn. |
| 554 | Use the ${authresults } expansion instead. |
| 555 | |
| 556 | |
| 557 | 5. How to enable DMARC advanced operation: |
| 558 | By default, Exim's DMARC configuration is intended to be |
| 559 | non-intrusive and conservative. To facilitate this, Exim will not |
| 560 | create any type of logging files without explicit configuration by |
| 561 | you, the admin. Nor will Exim send out any emails/reports about |
| 562 | DMARC issues without explicit configuration by you, the admin (other |
| 563 | than typical bounce messages that may come about due to ACL |
| 564 | processing or failure delivery issues). |
| 565 | |
| 566 | In order to log statistics suitable to be imported by the opendmarc |
| 567 | tools, you need to: |
| 568 | a. Configure the global setting dmarc_history_file. |
| 569 | b. Configure cron jobs to call the appropriate opendmarc history |
| 570 | import scripts and truncating the dmarc_history_file. |
| 571 | |
| 572 | In order to send forensic reports, you need to: |
| 573 | a. Configure the global setting dmarc_forensic_sender. |
| 574 | b. Configure, somewhere before the DATA ACL, the control option to |
| 575 | enable sending DMARC forensic reports. |
| 576 | |
| 577 | |
| 578 | 6. Example usage: |
| 579 | (RCPT ACL) |
| 580 | warn domains = +local_domains |
| 581 | hosts = +local_hosts |
| 582 | control = dmarc_disable_verify |
| 583 | |
| 584 | warn !domains = +screwed_up_dmarc_records |
| 585 | control = dmarc_enable_forensic |
| 586 | |
| 587 | warn condition = (lookup if destined to mailing list) |
| 588 | set acl_m_mailing_list = 1 |
| 589 | |
| 590 | (DATA ACL) |
| 591 | warn dmarc_status = accept : none : off |
| 592 | !authenticated = * |
| 593 | log_message = DMARC DEBUG: $dmarc_status $dmarc_used_domain |
| 594 | |
| 595 | warn dmarc_status = !accept |
| 596 | !authenticated = * |
| 597 | log_message = DMARC DEBUG: '$dmarc_status' for $dmarc_used_domain |
| 598 | |
| 599 | warn dmarc_status = quarantine |
| 600 | !authenticated = * |
| 601 | set $acl_m_quarantine = 1 |
| 602 | # Do something in a transport with this flag variable |
| 603 | |
| 604 | deny condition = ${if eq{$dmarc_domain_policy}{reject}} |
| 605 | condition = ${if eq{$acl_m_mailing_list}{1}} |
| 606 | message = Messages from $dmarc_used_domain break mailing lists |
| 607 | |
| 608 | deny dmarc_status = reject |
| 609 | !authenticated = * |
| 610 | message = Message from $dmarc_used_domain failed sender's DMARC policy, REJECT |
| 611 | |
| 612 | warn add_header = :at_start:${authresults {$primary_hostname}} |
| 613 | |
| 614 | |
| 615 | |
| 616 | DSN extra information |
| 617 | --------------------- |
| 618 | If compiled with EXPERIMENTAL_DSN_INFO extra information will be added |
| 619 | to DSN fail messages ("bounces"), when available. The intent is to aid |
| 620 | tracing of specific failing messages, when presented with a "bounce" |
| 621 | complaint and needing to search logs. |
| 622 | |
| 623 | |
| 624 | The remote MTA IP address, with port number if nonstandard. |
| 625 | Example: |
| 626 | Remote-MTA: X-ip; [127.0.0.1]:587 |
| 627 | Rationale: |
| 628 | Several addresses may correspond to the (already available) |
| 629 | dns name for the remote MTA. |
| 630 | |
| 631 | The remote MTA connect-time greeting. |
| 632 | Example: |
| 633 | X-Remote-MTA-smtp-greeting: X-str; 220 the.local.host.name ESMTP Exim x.yz Tue, 2 Mar 1999 09:44:33 +0000 |
| 634 | Rationale: |
| 635 | This string sometimes presents the remote MTA's idea of its |
| 636 | own name, and sometimes identifies the MTA software. |
| 637 | |
| 638 | The remote MTA response to HELO or EHLO. |
| 639 | Example: |
| 640 | X-Remote-MTA-helo-response: X-str; 250-the.local.host.name Hello localhost [127.0.0.1] |
| 641 | Limitations: |
| 642 | Only the first line of a multiline response is recorded. |
| 643 | Rationale: |
| 644 | This string sometimes presents the remote MTA's view of |
| 645 | the peer IP connecting to it. |
| 646 | |
| 647 | The reporting MTA detailed diagnostic. |
| 648 | Example: |
| 649 | X-Exim-Diagnostic: X-str; SMTP error from remote mail server after RCPT TO:<d3@myhost.test.ex>: 550 hard error |
| 650 | Rationale: |
| 651 | This string sometimes give extra information over the |
| 652 | existing (already available) Diagnostic-Code field. |
| 653 | |
| 654 | |
| 655 | Note that non-RFC-documented field names and data types are used. |
| 656 | |
| 657 | |
| 658 | LMDB Lookup support |
| 659 | ------------------- |
| 660 | LMDB is an ultra-fast, ultra-compact, crash-proof key-value embedded data store. |
| 661 | It is modeled loosely on the BerkeleyDB API. You should read about the feature |
| 662 | set as well as operation modes at https://symas.com/products/lightning-memory-mapped-database/ |
| 663 | |
| 664 | LMDB single key lookup support is provided by linking to the LMDB C library. |
| 665 | The current implementation does not support writing to the LMDB database. |
| 666 | |
| 667 | Visit https://github.com/LMDB/lmdb to download the library or find it in your |
| 668 | operating systems package repository. |
| 669 | |
| 670 | If building from source, this description assumes that headers will be in |
| 671 | /usr/local/include, and that the libraries are in /usr/local/lib. |
| 672 | |
| 673 | 1. In order to build exim with LMDB lookup support add or uncomment |
| 674 | |
| 675 | EXPERIMENTAL_LMDB=yes |
| 676 | |
| 677 | to your Local/Makefile. (Re-)build/install exim. exim -d should show |
| 678 | Experimental_LMDB in the line "Support for:". |
| 679 | |
| 680 | EXPERIMENTAL_LMDB=yes |
| 681 | LDFLAGS += -llmdb |
| 682 | # CFLAGS += -I/usr/local/include |
| 683 | # LDFLAGS += -L/usr/local/lib |
| 684 | |
| 685 | The first line sets the feature to include the correct code, and |
| 686 | the second line says to link the LMDB libraries into the |
| 687 | exim binary. The commented out lines should be uncommented if you |
| 688 | built LMDB from source and installed in the default location. |
| 689 | Adjust the paths if you installed them elsewhere, but you do not |
| 690 | need to uncomment them if an rpm (or you) installed them in the |
| 691 | package controlled locations (/usr/include and /usr/lib). |
| 692 | |
| 693 | 2. Create your LMDB files, you can use the mdb_load utility which is |
| 694 | part of the LMDB distribution our your favourite language bindings. |
| 695 | |
| 696 | 3. Add the single key lookups to your exim.conf file, example lookups |
| 697 | are below. |
| 698 | |
| 699 | ${lookup{$sender_address_domain}lmdb{/var/lib/baruwa/data/db/relaydomains.mdb}{$value}} |
| 700 | ${lookup{$sender_address_domain}lmdb{/var/lib/baruwa/data/db/relaydomains.mdb}{$value}fail} |
| 701 | ${lookup{$sender_address_domain}lmdb{/var/lib/baruwa/data/db/relaydomains.mdb}} |
| 702 | |
| 703 | |
| 704 | Queuefile transport |
| 705 | ------------------- |
| 706 | Queuefile is a pseudo transport which does not perform final delivery. |
| 707 | It simply copies the exim spool files out of the spool directory into |
| 708 | an external directory retaining the exim spool format. |
| 709 | |
| 710 | The spool files can then be processed by external processes and then |
| 711 | requeued into exim spool directories for final delivery. |
| 712 | |
| 713 | The motivation/inspiration for the transport is to allow external |
| 714 | processes to access email queued by exim and have access to all the |
| 715 | information which would not be available if the messages were delivered |
| 716 | to the process in the standard email formats. |
| 717 | |
| 718 | The mailscanner package is one of the processes that can take advantage |
| 719 | of this transport to filter email. |
| 720 | |
| 721 | The transport can be used in the same way as the other existing transports, |
| 722 | i.e by configuring a router to route mail to a transport configured with |
| 723 | the queuefile driver. |
| 724 | |
| 725 | The transport only takes one option: |
| 726 | |
| 727 | * directory - This is used to specify the directory messages should be |
| 728 | copied to. Expanded. |
| 729 | |
| 730 | The generic transport options (body_only, current_directory, disable_logging, |
| 731 | debug_print, delivery_date_add, envelope_to_add, event_action, group, |
| 732 | headers_add, headers_only, headers_remove, headers_rewrite, home_directory, |
| 733 | initgroups, max_parallel, message_size_limit, rcpt_include_affixes, |
| 734 | retry_use_local_part, return_path, return_path_add, shadow_condition, |
| 735 | shadow_transport, transport_filter, transport_filter_timeout, user) are |
| 736 | ignored. |
| 737 | |
| 738 | Sample configuration: |
| 739 | |
| 740 | (Router) |
| 741 | |
| 742 | scan: |
| 743 | driver = accept |
| 744 | transport = scan |
| 745 | |
| 746 | (Transport) |
| 747 | |
| 748 | scan: |
| 749 | driver = queuefile |
| 750 | directory = /var/spool/baruwa-scanner/input |
| 751 | |
| 752 | |
| 753 | In order to build exim with Queuefile transport support add or uncomment |
| 754 | |
| 755 | EXPERIMENTAL_QUEUEFILE=yes |
| 756 | |
| 757 | to your Local/Makefile. (Re-)build/install exim. exim -d should show |
| 758 | Experimental_QUEUEFILE in the line "Support for:". |
| 759 | |
| 760 | |
| 761 | ARC support |
| 762 | ----------- |
| 763 | Specification: https://tools.ietf.org/html/draft-ietf-dmarc-arc-protocol-11 |
| 764 | Note that this is not an RFC yet, so may change. |
| 765 | |
| 766 | ARC is intended to support the utility of SPF and DKIM in the presence of |
| 767 | intermediaries in the transmission path - forwarders and mailinglists - |
| 768 | by establishing a cryptographically-signed chain in headers. |
| 769 | |
| 770 | Normally one would only bother doing ARC-signing when functioning as |
| 771 | an intermediary. One might do verify for local destinations. |
| 772 | |
| 773 | ARC uses the notion of a "ADministrative Management Domain" (ADMD). |
| 774 | Described in RFC 5598 (section 2.3), this is essentially the set of |
| 775 | mail-handling systems that the mail transits. A label should be chosen to |
| 776 | identify the ADMD. Messages should be ARC-verified on entry to the ADMD, |
| 777 | and ARC-signed on exit from it. |
| 778 | |
| 779 | |
| 780 | Verification |
| 781 | -- |
| 782 | An ACL condition is provided to perform the "verifier actions" detailed |
| 783 | in section 6 of the above specification. It may be called from the DATA ACL |
| 784 | and succeeds if the result matches any of a given list. |
| 785 | It also records the highest ARC instance number (the chain size) |
| 786 | and verification result for later use in creating an Authentication-Results: |
| 787 | standard header. |
| 788 | |
| 789 | verify = arc/<acceptable_list> none:fail:pass |
| 790 | |
| 791 | add_header = :at_start:${authresults {<admd-identifier>}} |
| 792 | |
| 793 | Note that it would be wise to strip incoming messages of A-R headers |
| 794 | that claim to be from our own <admd-identifier>. |
| 795 | |
| 796 | There are three new variables: $arc_state, $arc_state_reason, $arc_domains: |
| 797 | |
| 798 | $arc_state One of pass, fail, none |
| 799 | $arc_state_reason (if fail, why) |
| 800 | $arc_domains colon-sep list of ARC chain domains, in chain order. |
| 801 | problematic elements may have empty list elements |
| 802 | $arc_oldest_pass lowest passing instance number of chain |
| 803 | |
| 804 | Receive log lines for an ARC pass will be tagged "ARC". |
| 805 | |
| 806 | |
| 807 | Signing |
| 808 | -- |
| 809 | arc_sign = <admd-identifier> : <selector> : <privkey> [ : <options> ] |
| 810 | An option on the smtp transport, which constructs and prepends to the message |
| 811 | an ARC set of headers. The textually-first Authentication-Results: header |
| 812 | is used as a basis (you must have added one on entry to the ADMD). |
| 813 | Expanded as a whole; if unset, empty or forced-failure then no signing is done. |
| 814 | If it is set, all three elements must be non-empty. |
| 815 | |
| 816 | The fourth element is optional, and if present consists of a comma-separated list |
| 817 | of options. The options implemented are |
| 818 | |
| 819 | timestamps Add a t= tag to the generated AMS and AS headers, with the |
| 820 | current time. |
| 821 | expire[=<val>] Add an x= tag to the generated AMS header, with an expiry time. |
| 822 | If the value <val> is an plain number it is used unchanged. |
| 823 | If it starts with a '+' then the following number is added |
| 824 | to the current time, as an offset in seconds. |
| 825 | If a value is not given it defaults to a one month offset. |
| 826 | |
| 827 | [As of writing, gmail insist that a t= tag on the AS is mandatory] |
| 828 | |
| 829 | Caveats: |
| 830 | * There must be an Authentication-Results header, presumably added by an ACL |
| 831 | while receiving the message, for the same ADMD, for arc_sign to succeed. |
| 832 | This requires careful coordination between inbound and outbound logic. |
| 833 | * If passing a message to another system, such as a mailing-list manager |
| 834 | (MLM), between receipt and sending, be wary of manipulations to headers made |
| 835 | by the MLM. |
| 836 | + For instance, Mailman with REMOVE_DKIM_HEADERS==3 might improve |
| 837 | deliverability in a pre-ARC world, but that option also renames the |
| 838 | Authentication-Results header, which breaks signing. |
| 839 | * Even if you use multiple DKIM keys for different domains, the ARC concept |
| 840 | should try to stick to one ADMD, so pick a primary domain and use that for |
| 841 | AR headers and outbound signing. |
| 842 | |
| 843 | Signing is not compatible with cutthrough delivery; any (before expansion) |
| 844 | value set for the option will result in cutthrough delivery not being |
| 845 | used via the transport in question. |
| 846 | |
| 847 | |
| 848 | |
| 849 | -------------------------------------------------------------- |
| 850 | End of file |
| 851 | -------------------------------------------------------------- |