Commit | Line | Data |
---|---|---|
7bafa7d9 TK |
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 | |
d36a0501 PP |
5 | about experimental features, all of which are unstable and |
6 | liable to incompatible change. | |
ee161e8f PH |
7 | |
8 | ||
0b23848a | 9 | Brightmail AntiSpam (BMI) suppport |
ee161e8f PH |
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 | |
3ec3e3bb | 33 | 2) Set up main BMI options (top section of Exim config file) |
ee161e8f PH |
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 | ||
8ff3788c | 40 | These four steps are explained in more details below. |
ee161e8f PH |
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 Brighmail 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 | |
47bbda99 | 52 | CFLAGS=-I/path/to/the/dir/with/the/includefile |
ee161e8f | 53 | EXTRALIBS_EXIM=-L/path/to/the/dir/with/the/library -lbmiclient_single |
8ff3788c | 54 | |
ee161e8f PH |
55 | If you use other CFLAGS or EXTRALIBS_EXIM settings then |
56 | merge the content of these lines with them. | |
57 | ||
7c0c8547 | 58 | Note for BMI6.x users: You'll also have to add -lxml2_single |
ee161e8f PH |
59 | to the EXTRALIBS_EXIM line. Users of 5.5x do not need to do |
60 | this. | |
8ff3788c | 61 | |
ee161e8f PH |
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 | ||
3ec3e3bb | 69 | 2) Setting up BMI support in the Exim main configuration |
ee161e8f | 70 | |
3ec3e3bb | 71 | To enable BMI support in the main Exim configuration, you |
ee161e8f PH |
72 | should set the path to the main BMI configuration file with |
73 | the "bmi_config_file" option, like this: | |
8ff3788c | 74 | |
ee161e8f | 75 | bmi_config_file = /opt/brightmail/etc/brightmail.cfg |
8ff3788c | 76 | |
3ec3e3bb | 77 | This must go into section 1 of Exim's configuration file (You |
ee161e8f PH |
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. | |
8ff3788c | 84 | |
ee161e8f PH |
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 | |
3ec3e3bb | 96 | the "accept" blocks from Exim's default configuration file: |
8ff3788c | 97 | |
ee161e8f PH |
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 | |
8ff3788c | 108 | |
ee161e8f PH |
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 | |
3ec3e3bb | 119 | at that stage. From Exim's view, a verdict can have the |
ee161e8f | 120 | following outcomes: |
8ff3788c | 121 | |
ee161e8f PH |
122 | o deliver the message normally |
123 | o deliver the message to an alternate location | |
124 | o do not deliver the message | |
8ff3788c | 125 | |
ee161e8f PH |
126 | To query the verdict for a recipient, the implementation |
127 | offers the following tools: | |
8ff3788c TK |
128 | |
129 | ||
ee161e8f PH |
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: | |
8ff3788c | 134 | |
ee161e8f | 135 | o bmi_deliver_default |
8ff3788c | 136 | |
ee161e8f PH |
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. | |
8ff3788c | 141 | |
ee161e8f | 142 | o bmi_deliver_alternate |
8ff3788c | 143 | |
ee161e8f PH |
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. | |
8ff3788c | 150 | |
ee161e8f | 151 | o bmi_dont_deliver |
8ff3788c | 152 | |
ee161e8f PH |
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: | |
8ff3788c | 157 | |
ee161e8f PH |
158 | # don't deliver messages handled by the BMI server |
159 | bmi_blackhole: | |
160 | driver = redirect | |
161 | bmi_dont_deliver | |
162 | data = :blackhole: | |
8ff3788c | 163 | |
ee161e8f PH |
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. | |
8ff3788c TK |
168 | |
169 | ||
ee161e8f PH |
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: | |
8ff3788c | 175 | |
ee161e8f PH |
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 | |
8ff3788c TK |
181 | |
182 | ||
ee161e8f PH |
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: | |
8ff3788c | 187 | |
ee161e8f | 188 | o $bmi_base64_verdict |
8ff3788c | 189 | |
ee161e8f PH |
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: | |
8ff3788c | 193 | |
ee161e8f PH |
194 | localuser: |
195 | driver = accept | |
196 | check_local_user | |
197 | headers_add = X-Brightmail-Verdict: $bmi_base64_verdict | |
198 | transport = local_delivery | |
8ff3788c | 199 | |
ee161e8f PH |
200 | If there is no verdict available for the recipient being |
201 | routed, this variable contains the empty string. | |
8ff3788c | 202 | |
ee161e8f | 203 | o $bmi_base64_tracker_verdict |
8ff3788c | 204 | |
ee161e8f PH |
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: | |
8ff3788c | 209 | |
ee161e8f PH |
210 | localuser: |
211 | driver = accept | |
212 | check_local_user | |
213 | headers_add = X-Brightmail-Tracker: $bmi_base64_tracker_verdict | |
214 | transport = local_delivery | |
8ff3788c | 215 | |
ee161e8f PH |
216 | If there is no verdict available for the recipient being |
217 | routed, this variable contains the empty string. | |
8ff3788c | 218 | |
ee161e8f | 219 | o $bmi_alt_location |
8ff3788c | 220 | |
ee161e8f PH |
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. | |
8ff3788c | 229 | |
ee161e8f | 230 | o $bmi_deliver |
8ff3788c | 231 | |
ee161e8f PH |
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. | |
8ff3788c | 235 | |
ee161e8f PH |
236 | $bmi_deliver is '0': the message should NOT be delivered. |
237 | $bmi_deliver is '1': the message should be delivered. | |
8ff3788c TK |
238 | |
239 | ||
ee161e8f PH |
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. | |
8ff3788c TK |
248 | |
249 | ||
ee161e8f PH |
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 | |
3ec3e3bb | 257 | already look up recipient data in Exim anyway (which can |
ee161e8f PH |
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'. | |
8ff3788c | 269 | |
ee161e8f | 270 | The file format: |
8ff3788c | 271 | |
ee161e8f PH |
272 | user1@mydomain.com: <OPTIN STRING1>:<OPTIN STRING2> |
273 | user2@thatdomain.com: <OPTIN STRING3> | |
8ff3788c TK |
274 | |
275 | ||
ee161e8f | 276 | The example: |
8ff3788c | 277 | |
ee161e8f PH |
278 | accept domains = +relay_to_domains |
279 | endpass | |
280 | verify = recipient | |
281 | bmi_optin = ${lookup{$local_part@$domain}lsearch{/etc/exim/bmi_optin_data}} | |
8ff3788c TK |
282 | control = bmi_run |
283 | ||
ee161e8f | 284 | Of course, you can also use any other lookup method that |
3ec3e3bb | 285 | Exim supports, including LDAP, Postgres, MySQL, Oracle etc., |
ee161e8f PH |
286 | as long as the result is a list of colon-separated opt-in |
287 | strings. | |
8ff3788c | 288 | |
ee161e8f PH |
289 | For a list of available opt-in strings, please contact your |
290 | Brightmail representative. | |
ee161e8f | 291 | |
8ff3788c TK |
292 | |
293 | ||
294 | ||
0b23848a | 295 | Sender Policy Framework (SPF) support |
ee161e8f PH |
296 | -------------------------------------------------------------- |
297 | ||
f413481d | 298 | To learn more about SPF, visit http://www.openspf.org. This |
ee161e8f PH |
299 | document does not explain the SPF fundamentals, you should |
300 | read and understand the implications of deploying SPF on your | |
301 | system before doing so. | |
302 | ||
8ff3788c | 303 | SPF support is added via the libspf2 library. Visit |
ee161e8f PH |
304 | |
305 | http://www.libspf2.org/ | |
8ff3788c | 306 | |
ee161e8f PH |
307 | to obtain a copy, then compile and install it. By default, |
308 | this will put headers in /usr/local/include and the static | |
309 | library in /usr/local/lib. | |
310 | ||
3ec3e3bb | 311 | To compile Exim with SPF support, set these additional flags in |
ee161e8f PH |
312 | Local/Makefile: |
313 | ||
314 | EXPERIMENTAL_SPF=yes | |
315 | CFLAGS=-DSPF -I/usr/local/include | |
316 | EXTRALIBS_EXIM=-L/usr/local/lib -lspf2 | |
317 | ||
318 | This assumes that the libspf2 files are installed in | |
319 | their default locations. | |
320 | ||
321 | You can now run SPF checks in incoming SMTP by using the "spf" | |
322 | ACL condition in either the MAIL, RCPT or DATA ACLs. When | |
d36a0501 | 323 | using it in the RCPT ACL, you can make the checks dependent on |
ee161e8f PH |
324 | the RCPT address (or domain), so you can check SPF records |
325 | only for certain target domains. This gives you the | |
326 | possibility to opt-out certain customers that do not want | |
327 | their mail to be subject to SPF checking. | |
328 | ||
329 | The spf condition takes a list of strings on its right-hand | |
330 | side. These strings describe the outcome of the SPF check for | |
331 | which the spf condition should succeed. Valid strings are: | |
332 | ||
333 | o pass The SPF check passed, the sending host | |
334 | is positively verified by SPF. | |
335 | o fail The SPF check failed, the sending host | |
336 | is NOT allowed to send mail for the domain | |
337 | in the envelope-from address. | |
338 | o softfail The SPF check failed, but the queried | |
339 | domain can't absolutely confirm that this | |
340 | is a forgery. | |
341 | o none The queried domain does not publish SPF | |
342 | records. | |
343 | o neutral The SPF check returned a "neutral" state. | |
344 | This means the queried domain has published | |
345 | a SPF record, but wants to allow outside | |
346 | servers to send mail under its domain as well. | |
8ddef691 TL |
347 | This should be treated like "none". |
348 | o permerror This indicates a syntax error in the SPF | |
349 | record of the queried domain. You may deny | |
350 | messages when this occurs. (Changed in 4.83) | |
351 | o temperror This indicates a temporary error during all | |
3ec3e3bb | 352 | processing, including Exim's SPF processing. |
ee161e8f | 353 | You may defer messages when this occurs. |
8ddef691 | 354 | (Changed in 4.83) |
982650ec TL |
355 | o err_temp Same as permerror, deprecated in 4.83, will be |
356 | removed in a future release. | |
357 | o err_perm Same as temperror, deprecated in 4.83, will be | |
358 | removed in a future release. | |
8ff3788c | 359 | |
ee161e8f | 360 | You can prefix each string with an exclamation mark to invert |
982650ec | 361 | its meaning, for example "!fail" will match all results but |
ee161e8f PH |
362 | "fail". The string list is evaluated left-to-right, in a |
363 | short-circuit fashion. When a string matches the outcome of | |
364 | the SPF check, the condition succeeds. If none of the listed | |
365 | strings matches the outcome of the SPF check, the condition | |
366 | fails. | |
367 | ||
f413481d TK |
368 | Here is an example to fail forgery attempts from domains that |
369 | publish SPF records: | |
ee161e8f PH |
370 | |
371 | /* ----------------- | |
f413481d TK |
372 | deny message = $sender_host_address is not allowed to send mail from ${if def:sender_address_domain {$sender_address_domain}{$sender_helo_name}}. \ |
373 | Please see http://www.openspf.org/Why?scope=${if def:sender_address_domain {mfrom}{helo}};identity=${if def:sender_address_domain {$sender_address}{$sender_helo_name}};ip=$sender_host_address | |
ee161e8f PH |
374 | spf = fail |
375 | --------------------- */ | |
376 | ||
377 | You can also give special treatment to specific domains: | |
378 | ||
379 | /* ----------------- | |
380 | deny message = AOL sender, but not from AOL-approved relay. | |
381 | sender_domains = aol.com | |
382 | spf = fail:neutral | |
383 | --------------------- */ | |
384 | ||
385 | Explanation: AOL publishes SPF records, but is liberal and | |
386 | still allows non-approved relays to send mail from aol.com. | |
387 | This will result in a "neutral" state, while mail from genuine | |
388 | AOL servers will result in "pass". The example above takes | |
389 | this into account and treats "neutral" like "fail", but only | |
390 | for aol.com. Please note that this violates the SPF draft. | |
391 | ||
392 | When the spf condition has run, it sets up several expansion | |
393 | variables. | |
394 | ||
395 | $spf_header_comment | |
396 | This contains a human-readable string describing the outcome | |
397 | of the SPF check. You can add it to a custom header or use | |
398 | it for logging purposes. | |
8ff3788c | 399 | |
ee161e8f | 400 | $spf_received |
8fe685ad | 401 | This contains a complete Received-SPF: header that can be |
ee161e8f PH |
402 | added to the message. Please note that according to the SPF |
403 | draft, this header must be added at the top of the header | |
404 | list. Please see section 10 on how you can do this. | |
8ff3788c | 405 | |
65a7d8c3 NM |
406 | Note: in case of "Best-guess" (see below), the convention is |
407 | to put this string in a header called X-SPF-Guess: instead. | |
408 | ||
ee161e8f PH |
409 | $spf_result |
410 | This contains the outcome of the SPF check in string form, | |
8ddef691 TL |
411 | one of pass, fail, softfail, none, neutral, permerror or |
412 | temperror. | |
8ff3788c | 413 | |
ee161e8f PH |
414 | $spf_smtp_comment |
415 | This contains a string that can be used in a SMTP response | |
416 | to the calling party. Useful for "fail". | |
8ff3788c | 417 | |
65a7d8c3 NM |
418 | In addition to SPF, you can also perform checks for so-called |
419 | "Best-guess". Strictly speaking, "Best-guess" is not standard | |
420 | SPF, but it is supported by the same framework that enables SPF | |
421 | capability. Refer to http://www.openspf.org/FAQ/Best_guess_record | |
422 | for a description of what it means. | |
423 | ||
424 | To access this feature, simply use the spf_guess condition in place | |
425 | of the spf one. For example: | |
426 | ||
427 | /* ----------------- | |
428 | deny message = $sender_host_address doesn't look trustworthy to me | |
429 | spf_guess = fail | |
430 | --------------------- */ | |
431 | ||
432 | In case you decide to reject messages based on this check, you | |
433 | should note that although it uses the same framework, "Best-guess" | |
434 | is NOT SPF, and therefore you should not mention SPF at all in your | |
435 | reject message. | |
436 | ||
437 | When the spf_guess condition has run, it sets up the same expansion | |
438 | variables as when spf condition is run, described above. | |
439 | ||
d36a0501 | 440 | Additionally, since Best-guess is not standardized, you may redefine |
65a7d8c3 NM |
441 | what "Best-guess" means to you by redefining spf_guess variable in |
442 | global config. For example, the following: | |
443 | ||
444 | /* ----------------- | |
445 | spf_guess = v=spf1 a/16 mx/16 ptr ?all | |
446 | --------------------- */ | |
447 | ||
448 | would relax host matching rules to a broader network range. | |
8ff3788c | 449 | |
ee161e8f | 450 | |
950aa3fb JH |
451 | A lookup expansion is also available. It takes an email |
452 | address as the key and an IP address as the database: | |
453 | ||
454 | $lookup (username@domain} spf {ip.ip.ip.ip}} | |
455 | ||
456 | The lookup will return the same result strings as they can appear in | |
457 | $spf_result (pass,fail,softfail,neutral,none,err_perm,err_temp). | |
458 | Currently, only IPv4 addresses are supported. | |
459 | ||
460 | ||
461 | ||
0b23848a | 462 | SRS (Sender Rewriting Scheme) Support |
ee161e8f PH |
463 | -------------------------------------------------------------- |
464 | ||
465 | Exiscan currently includes SRS support via Miles Wilton's | |
8ff3788c | 466 | libsrs_alt library. The current version of the supported |
ee161e8f PH |
467 | library is 0.5. |
468 | ||
469 | In order to use SRS, you must get a copy of libsrs_alt from | |
470 | ||
471 | http://srs.mirtol.com/ | |
472 | ||
473 | Unpack the tarball, then refer to MTAs/README.EXIM | |
474 | to proceed. You need to set | |
475 | ||
476 | EXPERIMENTAL_SRS=yes | |
477 | ||
478 | in your Local/Makefile. | |
479 | ||
480 | ||
0e1ccf44 PP |
481 | DCC Support |
482 | -------------------------------------------------------------- | |
d36254f2 | 483 | Distributed Checksum Clearinghouse; http://www.rhyolite.com/dcc/ |
0e1ccf44 PP |
484 | |
485 | *) Building exim | |
486 | ||
487 | In order to build exim with DCC support add | |
488 | ||
489 | EXPERIMENTAL_DCC=yes | |
490 | ||
491 | to your Makefile. (Re-)build/install exim. exim -d should show | |
492 | EXPERIMENTAL_DCC under "Support for". | |
493 | ||
494 | ||
495 | *) Configuration | |
496 | ||
497 | In the main section of exim.cf add at least | |
498 | dccifd_address = /usr/local/dcc/var/dccifd | |
499 | or | |
500 | dccifd_address = <ip> <port> | |
501 | ||
502 | In the DATA ACL you can use the new condition | |
503 | dcc = * | |
504 | ||
505 | After that "$dcc_header" contains the X-DCC-Header. | |
506 | ||
d36a0501 | 507 | Return values are: |
0e1ccf44 PP |
508 | fail for overall "R", "G" from dccifd |
509 | defer for overall "T" from dccifd | |
510 | accept for overall "A", "S" from dccifd | |
511 | ||
512 | dcc = */defer_ok works as for spamd. | |
513 | ||
514 | The "$dcc_result" variable contains the overall result from DCC | |
515 | answer. There will an X-DCC: header added to the mail. | |
516 | ||
517 | Usually you'll use | |
518 | defer !dcc = * | |
519 | to greylist with DCC. | |
520 | ||
521 | If you set, in the main section, | |
522 | dcc_direct_add_header = true | |
523 | then the dcc header will be added "in deep" and if the spool | |
524 | file was already written it gets removed. This forces Exim to | |
525 | write it again if needed. This helps to get the DCC Header | |
526 | through to eg. SpamAssassin. | |
527 | ||
528 | If you want to pass even more headers in the middle of the | |
529 | DATA stage you can set | |
530 | $acl_m_dcc_add_header | |
05c39afa | 531 | to tell the DCC routines to add more information; eg, you might set |
0e1ccf44 PP |
532 | this to some results from ClamAV. Be careful. Header syntax is |
533 | not checked and is added "as is". | |
534 | ||
05c39afa JH |
535 | In case you've troubles with sites sending the same queue items from several |
536 | hosts and fail to get through greylisting you can use | |
537 | $acl_m_dcc_override_client_ip | |
538 | ||
539 | Setting $acl_m_dcc_override_client_ip to an IP address overrides the default | |
540 | of $sender_host_address. eg. use the following ACL in DATA stage: | |
541 | ||
542 | warn set acl_m_dcc_override_client_ip = \ | |
543 | ${lookup{$sender_helo_name}nwildlsearch{/etc/mail/multipleip_sites}{$value}{}} | |
544 | condition = ${if def:acl_m_dcc_override_client_ip} | |
545 | log_message = dbg: acl_m_dcc_override_client_ip set to \ | |
546 | $acl_m_dcc_override_client_ip | |
547 | ||
548 | Then set something like | |
549 | # cat /etc/mail/multipleip_sites | |
550 | mout-xforward.gmx.net 82.165.159.12 | |
551 | mout.gmx.net 212.227.15.16 | |
552 | ||
553 | Use a reasonable IP. eg. one the sending cluster acutally uses. | |
0e1ccf44 | 554 | |
1899bab2 TL |
555 | DMARC Support |
556 | -------------------------------------------------------------- | |
557 | ||
558 | DMARC combines feedback from SPF, DKIM, and header From: in order | |
559 | to attempt to provide better indicators of the authenticity of an | |
560 | email. This document does not explain the fundamentals, you | |
561 | should read and understand how it works by visiting the website at | |
562 | http://www.dmarc.org/. | |
563 | ||
564 | DMARC support is added via the libopendmarc library. Visit: | |
565 | ||
566 | http://sourceforge.net/projects/opendmarc/ | |
567 | ||
568 | to obtain a copy, or find it in your favorite rpm package | |
569 | repository. If building from source, this description assumes | |
570 | that headers will be in /usr/local/include, and that the libraries | |
571 | are in /usr/local/lib. | |
572 | ||
573 | 1. To compile Exim with DMARC support, you must first enable SPF. | |
574 | Please read the above section on enabling the EXPERIMENTAL_SPF | |
575 | feature. You must also have DKIM support, so you cannot set the | |
576 | DISABLE_DKIM feature. Once both of those conditions have been met | |
577 | you can enable DMARC in Local/Makefile: | |
578 | ||
579 | EXPERIMENTAL_DMARC=yes | |
580 | LDFLAGS += -lopendmarc | |
581 | # CFLAGS += -I/usr/local/include | |
582 | # LDFLAGS += -L/usr/local/lib | |
583 | ||
584 | The first line sets the feature to include the correct code, and | |
585 | the second line says to link the libopendmarc libraries into the | |
586 | exim binary. The commented out lines should be uncommented if you | |
587 | built opendmarc from source and installed in the default location. | |
588 | Adjust the paths if you installed them elsewhere, but you do not | |
589 | need to uncomment them if an rpm (or you) installed them in the | |
590 | package controlled locations (/usr/include and /usr/lib). | |
591 | ||
592 | ||
593 | 2. Use the following global settings to configure DMARC: | |
594 | ||
595 | Required: | |
596 | dmarc_tld_file Defines the location of a text file of valid | |
597 | top level domains the opendmarc library uses | |
598 | during domain parsing. Maintained by Mozilla, | |
599 | the most current version can be downloaded | |
600 | from a link at http://publicsuffix.org/list/. | |
601 | ||
602 | Optional: | |
603 | dmarc_history_file Defines the location of a file to log results | |
604 | of dmarc verification on inbound emails. The | |
605 | contents are importable by the opendmarc tools | |
606 | which will manage the data, send out DMARC | |
607 | reports, and expire the data. Make sure the | |
608 | directory of this file is writable by the user | |
609 | exim runs as. | |
610 | ||
611 | dmarc_forensic_sender The email address to use when sending a | |
612 | forensic report detailing alignment failures | |
613 | if a sender domain's dmarc record specifies it | |
614 | and you have configured Exim to send them. | |
615 | Default: do-not-reply@$default_hostname | |
616 | ||
617 | ||
618 | 3. By default, the DMARC processing will run for any remote, | |
619 | non-authenticated user. It makes sense to only verify DMARC | |
620 | status of messages coming from remote, untrusted sources. You can | |
621 | use standard conditions such as hosts, senders, etc, to decide that | |
622 | DMARC verification should *not* be performed for them and disable | |
623 | DMARC with a control setting: | |
624 | ||
12d0043d | 625 | control = dmarc_disable_verify |
1899bab2 TL |
626 | |
627 | A DMARC record can also specify a "forensic address", which gives | |
628 | exim an email address to submit reports about failed alignment. | |
629 | Exim does not do this by default because in certain conditions it | |
630 | results in unintended information leakage (what lists a user might | |
631 | be subscribed to, etc). You must configure exim to submit forensic | |
632 | reports to the owner of the domain. If the DMARC record contains a | |
633 | forensic address and you specify the control statement below, then | |
634 | exim will send these forensic emails. It's also advised that you | |
635 | configure a dmarc_forensic_sender because the default sender address | |
636 | construction might be inadequate. | |
637 | ||
7b2f71c1 | 638 | control = dmarc_enable_forensic |
1899bab2 TL |
639 | |
640 | (AGAIN: You can choose not to send these forensic reports by simply | |
7b2f71c1 | 641 | not putting the dmarc_enable_forensic control line at any point in |
1899bab2 TL |
642 | your exim config. If you don't tell it to send them, it will not |
643 | send them.) | |
644 | ||
645 | There are no options to either control. Both must appear before | |
646 | the DATA acl. | |
647 | ||
648 | ||
649 | 4. You can now run DMARC checks in incoming SMTP by using the | |
650 | "dmarc_status" ACL condition in the DATA ACL. You are required to | |
651 | call the spf condition first in the ACLs, then the "dmarc_status" | |
652 | condition. Putting this condition in the ACLs is required in order | |
653 | for a DMARC check to actually occur. All of the variables are set | |
654 | up before the DATA ACL, but there is no actual DMARC check that | |
655 | occurs until a "dmarc_status" condition is encountered in the ACLs. | |
656 | ||
657 | The dmarc_status condition takes a list of strings on its | |
658 | right-hand side. These strings describe recommended action based | |
659 | on the DMARC check. To understand what the policy recommendations | |
660 | mean, refer to the DMARC website above. Valid strings are: | |
661 | ||
662 | o accept The DMARC check passed and the library recommends | |
663 | accepting the email. | |
664 | o reject The DMARC check failed and the library recommends | |
665 | rejecting the email. | |
666 | o quarantine The DMARC check failed and the library recommends | |
667 | keeping it for further inspection. | |
7a8678e6 | 668 | o none The DMARC check passed and the library recommends |
669 | no specific action, neutral. | |
1899bab2 TL |
670 | o norecord No policy section in the DMARC record for this |
671 | sender domain. | |
672 | o nofrom Unable to determine the domain of the sender. | |
7a8678e6 | 673 | o temperror Library error or dns error. |
05070e30 | 674 | o off The DMARC check was disabled for this email. |
1899bab2 TL |
675 | |
676 | You can prefix each string with an exclamation mark to invert its | |
677 | meaning, for example "!accept" will match all results but | |
678 | "accept". The string list is evaluated left-to-right in a | |
679 | short-circuit fashion. When a string matches the outcome of the | |
680 | DMARC check, the condition succeeds. If none of the listed | |
681 | strings matches the outcome of the DMARC check, the condition | |
682 | fails. | |
683 | ||
684 | Of course, you can also use any other lookup method that Exim | |
685 | supports, including LDAP, Postgres, MySQL, etc, as long as the | |
8c8b8274 | 686 | result is a list of colon-separated strings. |
1899bab2 TL |
687 | |
688 | Several expansion variables are set before the DATA ACL is | |
689 | processed, and you can use them in this ACL. The following | |
690 | expansion variables are available: | |
691 | ||
692 | o $dmarc_status | |
693 | This is a one word status indicating what the DMARC library | |
8c8b8274 TL |
694 | thinks of the email. It is a combination of the results of |
695 | DMARC record lookup and the SPF/DKIM/DMARC processing results | |
696 | (if a DMARC record was found). The actual policy declared | |
697 | in the DMARC record is in a separate expansion variable. | |
1899bab2 TL |
698 | |
699 | o $dmarc_status_text | |
700 | This is a slightly longer, human readable status. | |
701 | ||
702 | o $dmarc_used_domain | |
703 | This is the domain which DMARC used to look up the DMARC | |
704 | policy record. | |
705 | ||
8c8b8274 TL |
706 | o $dmarc_domain_policy |
707 | This is the policy declared in the DMARC record. Valid values | |
708 | are "none", "reject" and "quarantine". It is blank when there | |
709 | is any error, including no DMARC record. | |
710 | ||
1899bab2 TL |
711 | o $dmarc_ar_header |
712 | This is the entire Authentication-Results header which you can | |
713 | add using an add_header modifier. | |
714 | ||
715 | ||
716 | 5. How to enable DMARC advanced operation: | |
717 | By default, Exim's DMARC configuration is intended to be | |
718 | non-intrusive and conservative. To facilitate this, Exim will not | |
719 | create any type of logging files without explicit configuration by | |
720 | you, the admin. Nor will Exim send out any emails/reports about | |
721 | DMARC issues without explicit configuration by you, the admin (other | |
722 | than typical bounce messages that may come about due to ACL | |
723 | processing or failure delivery issues). | |
724 | ||
725 | In order to log statistics suitable to be imported by the opendmarc | |
726 | tools, you need to: | |
727 | a. Configure the global setting dmarc_history_file. | |
728 | b. Configure cron jobs to call the appropriate opendmarc history | |
729 | import scripts and truncating the dmarc_history_file. | |
730 | ||
731 | In order to send forensic reports, you need to: | |
732 | a. Configure the global setting dmarc_forensic_sender. | |
733 | b. Configure, somewhere before the DATA ACL, the control option to | |
734 | enable sending DMARC forensic reports. | |
735 | ||
736 | ||
737 | 6. Example usage: | |
738 | (RCPT ACL) | |
739 | warn domains = +local_domains | |
740 | hosts = +local_hosts | |
12d0043d | 741 | control = dmarc_disable_verify |
1899bab2 TL |
742 | |
743 | warn !domains = +screwed_up_dmarc_records | |
744 | control = dmarc_enable_forensic | |
745 | ||
8c8b8274 TL |
746 | warn condition = (lookup if destined to mailing list) |
747 | set acl_m_mailing_list = 1 | |
748 | ||
1899bab2 TL |
749 | (DATA ACL) |
750 | warn dmarc_status = accept : none : off | |
751 | !authenticated = * | |
752 | log_message = DMARC DEBUG: $dmarc_status $dmarc_used_domain | |
753 | add_header = $dmarc_ar_header | |
754 | ||
755 | warn dmarc_status = !accept | |
756 | !authenticated = * | |
757 | log_message = DMARC DEBUG: '$dmarc_status' for $dmarc_used_domain | |
758 | ||
759 | warn dmarc_status = quarantine | |
760 | !authenticated = * | |
761 | set $acl_m_quarantine = 1 | |
762 | # Do something in a transport with this flag variable | |
763 | ||
8c8b8274 TL |
764 | deny condition = ${if eq{$dmarc_domain_policy}{reject}} |
765 | condition = ${if eq{$acl_m_mailing_list}{1}} | |
766 | message = Messages from $dmarc_used_domain break mailing lists | |
767 | ||
1899bab2 TL |
768 | deny dmarc_status = reject |
769 | !authenticated = * | |
7b2f71c1 | 770 | message = Message from $dmarc_used_domain failed sender's DMARC policy, REJECT |
1899bab2 TL |
771 | |
772 | ||
773 | ||
774ef2d7 | 774 | Event Actions |
d68218c7 JH |
775 | -------------------------------------------------------------- |
776 | ||
774ef2d7 JH |
777 | (Renamed from TPDA, Transport post-delivery actions) |
778 | ||
779 | An arbitrary per-transport string can be expanded upon various transport events. | |
14a465c3 JH |
780 | Additionally a main-section configuration option can be expanded on some |
781 | per-message events. | |
d68218c7 JH |
782 | This feature may be used, for example, to write exim internal log information |
783 | (not available otherwise) into a database. | |
784 | ||
a7538db1 | 785 | In order to use the feature, you must compile with |
d68218c7 | 786 | |
774ef2d7 | 787 | EXPERIMENTAL_EVENT=yes |
d68218c7 JH |
788 | |
789 | in your Local/Makefile | |
790 | ||
14a465c3 | 791 | and define one or both of |
774ef2d7 JH |
792 | - the event_action option in the transport |
793 | - the event_action main option | |
14a465c3 | 794 | to be expanded when the event fires. |
d68218c7 | 795 | |
774ef2d7 | 796 | A new variable, $event_name, is set to the event type when the |
a7538db1 | 797 | expansion is done. The current list of events is: |
d68218c7 | 798 | |
774ef2d7 JH |
799 | msg:complete after main per message |
800 | msg:delivery after transport per recipient | |
5ef5dd52 JB |
801 | msg:rcpt:host:defer after transport per recipient per host |
802 | msg:rcpt:defer after transport per recipient | |
774ef2d7 JH |
803 | msg:host:defer after transport per attempt |
804 | msg:fail:delivery after main per recipient | |
805 | msg:fail:internal after main per recipient | |
806 | tcp:connect before transport per connection | |
807 | tcp:close after transport per connection | |
723fe533 | 808 | tls:cert before both per certificate in verification chain |
774ef2d7 JH |
809 | smtp:connect after transport per connection |
810 | ||
811 | The expansion is called for all event types, and should use the $event_name | |
186c98a1 JH |
812 | variable to decide when to act. The value of the variable is a colon-separated |
813 | list, defining a position in the tree of possible events; it may be used as | |
814 | a list or just matched on as a whole. There will be no whitespace. | |
815 | ||
5ef5dd52 JB |
816 | New event types may be added in the future. |
817 | ||
d68218c7 | 818 | |
774ef2d7 | 819 | There is an auxilary variable, $event_data, for which the |
a7538db1 | 820 | content is event_dependent: |
d68218c7 | 821 | |
a7538db1 | 822 | msg:delivery smtp confirmation mssage |
5ef5dd52 JB |
823 | msg:rcpt:host:defer error string |
824 | msg:rcpt:defer error string | |
a7538db1 JH |
825 | msg:host:defer error string |
826 | tls:cert verification chain depth | |
827 | smtp:connect smtp banner | |
d68218c7 | 828 | |
5ef5dd52 | 829 | The :defer events populate one extra variable, $event_defer_errno. |
a7538db1 | 830 | |
14a465c3 | 831 | The following variables are likely to be useful depending on the event type: |
a7538db1 JH |
832 | |
833 | router_name, transport_name | |
834 | local_part, domain | |
835 | host, host_address, host_port | |
836 | tls_out_peercert | |
837 | lookup_dnssec_authenticated, tls_out_dane | |
838 | sending_ip_address, sending_port | |
aec45841 | 839 | message_exim_id, verify_mode |
d68218c7 | 840 | |
d68218c7 JH |
841 | |
842 | An example might look like: | |
843 | ||
3c71915d | 844 | event_action = ${if eq {msg:delivery}{$event_name} \ |
a7538db1 | 845 | {${lookup pgsql {SELECT * FROM record_Delivery( \ |
d68218c7 JH |
846 | '${quote_pgsql:$sender_address_domain}',\ |
847 | '${quote_pgsql:${lc:$sender_address_local_part}}', \ | |
a7538db1 JH |
848 | '${quote_pgsql:$domain}', \ |
849 | '${quote_pgsql:${lc:$local_part}}', \ | |
850 | '${quote_pgsql:$host_address}', \ | |
851 | '${quote_pgsql:${lc:$host}}', \ | |
852 | '${quote_pgsql:$message_exim_id}')}} \ | |
853 | } {}} | |
d68218c7 | 854 | |
774ef2d7 JH |
855 | The string is expanded when each of the supported events occur |
856 | and any side-effects of the expansion will happen. | |
5ef5dd52 JB |
857 | |
858 | Note that for complex operations an ACL expansion can be used, | |
859 | however due to the multiple contexts the Exim operates in | |
860 | a) variables set in events raised from transports will not | |
861 | be visible outside that transport call. | |
862 | b) acl_m variables in a server context are lost on a new connection, | |
863 | and after helo/ehlo/mail/starttls/rset commands | |
864 | ||
d68218c7 | 865 | |
a7538db1 | 866 | |
774ef2d7 | 867 | The expansion of the event_action option should normally |
a7538db1 JH |
868 | return an empty string. Should it return anything else the |
869 | following will be forced: | |
870 | ||
871 | msg:delivery (ignored) | |
872 | msg:host:defer (ignored) | |
14a465c3 | 873 | msg:fail:delivery (ignored) |
a7538db1 JH |
874 | tcp:connect do not connect |
875 | tcp:close (ignored) | |
876 | tls:cert refuse verification | |
877 | smtp:connect close connection | |
878 | ||
774ef2d7 | 879 | No other use is made of the result string. |
a7538db1 | 880 | |
d68218c7 | 881 | |
723fe533 JH |
882 | Known issues: |
883 | - the tls:cert event is only called for the cert chain elements | |
884 | received over the wire, with GnuTLS. OpenSSL gives the entire | |
186c98a1 | 885 | chain including those loaded locally. |
1899bab2 | 886 | |
9bdd29ad TL |
887 | |
888 | Redis Lookup | |
889 | -------------------------------------------------------------- | |
890 | ||
891 | Redis is open source advanced key-value data store. This document | |
892 | does not explain the fundamentals, you should read and understand how | |
893 | it works by visiting the website at http://www.redis.io/. | |
894 | ||
895 | Redis lookup support is added via the hiredis library. Visit: | |
896 | ||
897 | https://github.com/redis/hiredis | |
898 | ||
899 | to obtain a copy, or find it in your operating systems package repository. | |
900 | If building from source, this description assumes that headers will be in | |
901 | /usr/local/include, and that the libraries are in /usr/local/lib. | |
902 | ||
903 | 1. In order to build exim with Redis lookup support add | |
904 | ||
905 | EXPERIMENTAL_REDIS=yes | |
906 | ||
907 | to your Local/Makefile. (Re-)build/install exim. exim -d should show | |
908 | Experimental_Redis in the line "Support for:". | |
909 | ||
910 | EXPERIMENTAL_REDIS=yes | |
911 | LDFLAGS += -lhiredis | |
912 | # CFLAGS += -I/usr/local/include | |
913 | # LDFLAGS += -L/usr/local/lib | |
914 | ||
915 | The first line sets the feature to include the correct code, and | |
916 | the second line says to link the hiredis libraries into the | |
917 | exim binary. The commented out lines should be uncommented if you | |
918 | built hiredis from source and installed in the default location. | |
919 | Adjust the paths if you installed them elsewhere, but you do not | |
920 | need to uncomment them if an rpm (or you) installed them in the | |
921 | package controlled locations (/usr/include and /usr/lib). | |
922 | ||
923 | ||
924 | 2. Use the following global settings to configure Redis lookup support: | |
925 | ||
926 | Required: | |
927 | redis_servers This option provides a list of Redis servers | |
928 | and associated connection data, to be used in | |
929 | conjunction with redis lookups. The option is | |
930 | only available if Exim is configured with Redis | |
931 | support. | |
932 | ||
933 | For example: | |
934 | ||
935 | redis_servers = 127.0.0.1/10/ - using database 10 with no password | |
936 | redis_servers = 127.0.0.1//password - to make use of the default database of 0 with a password | |
937 | redis_servers = 127.0.0.1// - for default database of 0 with no password | |
938 | ||
939 | 3. Once you have the Redis servers defined you can then make use of the | |
940 | experimental Redis lookup by specifying ${lookup redis{}} in a lookup query. | |
941 | ||
942 | 4. Example usage: | |
943 | ||
944 | (Host List) | |
945 | hostlist relay_from_ips = <\n ${lookup redis{SMEMBERS relay_from_ips}} | |
946 | ||
947 | Where relay_from_ips is a Redis set which contains entries such as "192.168.0.0/24" "10.0.0.0/8" and so on. | |
948 | The result set is returned as | |
949 | 192.168.0.0/24 | |
950 | 10.0.0.0/8 | |
951 | .. | |
952 | . | |
953 | ||
954 | (Domain list) | |
955 | domainlist virtual_domains = ${lookup redis {HGET $domain domain}} | |
956 | ||
957 | Where $domain is a hash which includes the key 'domain' and the value '$domain'. | |
958 | ||
959 | (Adding or updating an existing key) | |
960 | set acl_c_spammer = ${if eq{${lookup redis{SPAMMER_SET}}}{OK}} | |
961 | ||
962 | Where SPAMMER_SET is a macro and it is defined as | |
963 | ||
964 | "SET SPAMMER <some_value>" | |
965 | ||
966 | (Getting a value from Redis) | |
967 | ||
968 | set acl_c_spam_host = ${lookup redis{GET...}} | |
969 | ||
970 | ||
a3c86431 TL |
971 | Proxy Protocol Support |
972 | -------------------------------------------------------------- | |
973 | ||
974 | Exim now has Experimental "Proxy Protocol" support. It was built on | |
975 | specifications from: | |
976 | http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt | |
36719342 TL |
977 | Above URL revised May 2014 to change version 2 spec: |
978 | http://git.1wt.eu/web?p=haproxy.git;a=commitdiff;h=afb768340c9d7e50d8e | |
a3c86431 TL |
979 | |
980 | The purpose of this function is so that an application load balancer, | |
981 | such as HAProxy, can sit in front of several Exim servers and Exim | |
982 | will log the IP that is connecting to the proxy server instead of | |
983 | the IP of the proxy server when it connects to Exim. It resets the | |
984 | $sender_address_host and $sender_address_port to the IP:port of the | |
985 | connection to the proxy. It also re-queries the DNS information for | |
986 | this new IP address so that the original sender's hostname and IP | |
987 | get logged in the Exim logfile. There is no logging if a host passes or | |
988 | fails Proxy Protocol negotiation, but it can easily be determined and | |
989 | recorded in an ACL (example is below). | |
990 | ||
991 | 1. To compile Exim with Proxy Protocol support, put this in | |
992 | Local/Makefile: | |
993 | ||
994 | EXPERIMENTAL_PROXY=yes | |
995 | ||
996 | 2. Global configuration settings: | |
997 | ||
998 | proxy_required_hosts = HOSTLIST | |
999 | ||
1000 | The proxy_required_hosts option will require any IP in that hostlist | |
1001 | to use Proxy Protocol. The specification of Proxy Protocol is very | |
1002 | strict, and if proxy negotiation fails, Exim will not allow any SMTP | |
1003 | command other than QUIT. (See end of this section for an example.) | |
1004 | The option is expanded when used, so it can be a hostlist as well as | |
1005 | string of IP addresses. Since it is expanded, specifying an alternate | |
1006 | separator is supported for ease of use with IPv6 addresses. | |
1007 | ||
1008 | To log the IP of the proxy in the incoming logline, add: | |
1009 | log_selector = +proxy | |
1010 | ||
1011 | A default incoming logline (wrapped for appearance) will look like this: | |
1012 | ||
1013 | 2013-11-04 09:25:06 1VdNti-0001OY-1V <= me@example.net | |
1014 | H=mail.example.net [1.2.3.4] P=esmtp S=433 | |
1015 | ||
1016 | With the log selector enabled, an email that was proxied through a | |
1017 | Proxy Protocol server at 192.168.1.2 will look like this: | |
1018 | ||
1019 | 2013-11-04 09:25:06 1VdNti-0001OY-1V <= me@example.net | |
1020 | H=mail.example.net [1.2.3.4] P=esmtp PRX=192.168.1.2 S=433 | |
1021 | ||
1022 | 3. In the ACL's the following expansion variables are available. | |
1023 | ||
eb57651e TL |
1024 | proxy_host_address The (internal) src IP of the proxy server |
1025 | making the connection to the Exim server. | |
1026 | proxy_host_port The (internal) src port the proxy server is | |
1027 | using to connect to the Exim server. | |
1028 | proxy_target_address The dest (public) IP of the remote host to | |
1029 | the proxy server. | |
1030 | proxy_target_port The dest port the remote host is using to | |
1031 | connect to the proxy server. | |
1032 | proxy_session Boolean, yes/no, the connected host is required | |
1033 | to use Proxy Protocol. | |
a3c86431 TL |
1034 | |
1035 | There is no expansion for a failed proxy session, however you can detect | |
1036 | it by checking if $proxy_session is true but $proxy_host is empty. As | |
1037 | an example, in my connect ACL, I have: | |
1038 | ||
1039 | warn condition = ${if and{ {bool{$proxy_session}} \ | |
a3bddaa8 | 1040 | {eq{$proxy_host_address}{}} } } |
a3c86431 TL |
1041 | log_message = Failed required proxy protocol negotiation \ |
1042 | from $sender_host_name [$sender_host_address] | |
1043 | ||
1044 | warn condition = ${if and{ {bool{$proxy_session}} \ | |
a3bddaa8 | 1045 | {!eq{$proxy_host_address}{}} } } |
a3c86431 | 1046 | # But don't log health probes from the proxy itself |
a3bddaa8 | 1047 | condition = ${if eq{$proxy_host_address}{$sender_host_address} \ |
a3c86431 TL |
1048 | {false}{true}} |
1049 | log_message = Successfully proxied from $sender_host_name \ | |
1050 | [$sender_host_address] through proxy protocol \ | |
a3bddaa8 | 1051 | host $proxy_host_address |
a3c86431 | 1052 | |
eb57651e TL |
1053 | # Possibly more clear |
1054 | warn logwrite = Remote Source Address: $sender_host_address:$sender_host_port | |
1055 | logwrite = Proxy Target Address: $proxy_target_address:$proxy_target_port | |
1056 | logwrite = Proxy Internal Address: $proxy_host_address:$proxy_host_port | |
1057 | logwrite = Internal Server Address: $received_ip_address:$received_port | |
1058 | ||
1059 | ||
2365d793 | 1060 | 4. Recommended ACL additions: |
a3c86431 TL |
1061 | - Since the real connections are all coming from your proxy, and the |
1062 | per host connection tracking is done before Proxy Protocol is | |
1063 | evaluated, smtp_accept_max_per_host must be set high enough to | |
1064 | handle all of the parallel volume you expect per inbound proxy. | |
2365d793 TL |
1065 | - With the smtp_accept_max_per_host set so high, you lose the ability |
1066 | to protect your server from massive numbers of inbound connections | |
1067 | from one IP. In order to prevent your server from being DOS'd, you | |
1068 | need to add a per connection ratelimit to your connect ACL. I | |
1069 | suggest something like this: | |
1070 | ||
1071 | # Set max number of connections per host | |
1072 | LIMIT = 5 | |
1073 | # Or do some kind of IP lookup in a flat file or database | |
1074 | # LIMIT = ${lookup{$sender_host_address}iplsearch{/etc/exim/proxy_limits}} | |
1075 | ||
1076 | defer message = Too many connections from this IP right now | |
1077 | ratelimit = LIMIT / 5s / per_conn / strict | |
1078 | ||
1079 | ||
1080 | 5. Runtime issues to be aware of: | |
a3c86431 TL |
1081 | - The proxy has 3 seconds (hard-coded in the source code) to send the |
1082 | required Proxy Protocol header after it connects. If it does not, | |
1083 | the response to any commands will be: | |
1084 | "503 Command refused, required Proxy negotiation failed" | |
1085 | - If the incoming connection is configured in Exim to be a Proxy | |
1086 | Protocol host, but the proxy is not sending the header, the banner | |
1087 | does not get sent until the timeout occurs. If the sending host | |
1088 | sent any input (before the banner), this causes a standard Exim | |
1089 | synchronization error (i.e. trying to pipeline before PIPELINING | |
1090 | was advertised). | |
1091 | - This is not advised, but is mentioned for completeness if you have | |
1092 | a specific internal configuration that you want this: If the Exim | |
1093 | server only has an internal IP address and no other machines in your | |
1094 | organization will connect to it to try to send email, you may | |
1095 | simply set the hostlist to "*", however, this will prevent local | |
1096 | mail programs from working because that would require mail from | |
1097 | localhost to use Proxy Protocol. Again, not advised! | |
1098 | ||
2365d793 | 1099 | 6. Example of a refused connection because the Proxy Protocol header was |
a3c86431 TL |
1100 | not sent from a host configured to use Proxy Protocol. In the example, |
1101 | the 3 second timeout occurred (when a Proxy Protocol banner should have | |
1102 | been sent), the banner was displayed to the user, but all commands are | |
1103 | rejected except for QUIT: | |
1104 | ||
1105 | # nc mail.example.net 25 | |
1106 | 220-mail.example.net, ESMTP Exim 4.82+proxy, Mon, 04 Nov 2013 10:45:59 | |
1107 | 220 -0800 RFC's enforced | |
1108 | EHLO localhost | |
1109 | 503 Command refused, required Proxy negotiation failed | |
1110 | QUIT | |
1111 | 221 mail.example.net closing connection | |
1112 | ||
1113 | ||
8d692470 JH |
1114 | |
1115 | ||
7eb6c37c JH |
1116 | SOCKS |
1117 | ------------------------------------------------------------ | |
1118 | Support for proxying outbound SMTP via a Socks 5 proxy | |
1119 | (RFC 1928) is included if Exim is compiled with | |
1120 | EXPERIMENTAL_SOCKS defined. | |
1121 | ||
1122 | If an smtp transport has a nonempty socks_proxy option | |
1123 | defined, this is active. The option is expanded and | |
1124 | should be a list (colon-separated by default) of | |
1125 | proxy specifiers. Each proxy specifier is a list | |
1126 | (space-separated by default) where the initial element | |
1127 | is an IP address and any subsequent elements are options. | |
1128 | ||
1129 | Options are a string <name>=<value>. | |
1130 | These options are currently defined: | |
1131 | - "auth", with possible values "none" and "name". | |
1132 | Using "name" selects username/password authentication | |
1133 | per RFC 1929. Default is "none". | |
1134 | - "name" sets the authentication username. Default is empty. | |
1135 | - "pass" sets the authentication password. Default is empty. | |
1136 | - "port" sets the tcp port number for the proxy. Default is 1080. | |
1137 | - "tmo" sets a connection timeout in seconds for this proxy. Default is 5. | |
7f06582c JH |
1138 | - "pri" specifies a priority for the server within the list, higher |
1139 | values being tried first. The default priority is 1. | |
1140 | - "weight" specifies a selection bias. Within a priority set servers | |
1141 | are queried in a random fashion, weighted by this value. The default | |
1142 | value for selection bias is 1. | |
1143 | ||
1144 | Proxies from the list are tried according to their priority | |
1145 | and weight settings until one responds. The timeout for the | |
1146 | overall connection applies to the set of proxied attempts. | |
7eb6c37c JH |
1147 | |
1148 | If events are used, the remote IP/port during a | |
1149 | tcp:connect event will be that of the proxy. | |
1150 | ||
1151 | ||
1152 | ||
1153 | ||
043b1248 JH |
1154 | DANE |
1155 | ------------------------------------------------------------ | |
7cac846b JH |
1156 | DNS-based Authentication of Named Entities, as applied |
1157 | to SMTP over TLS, provides assurance to a client that | |
1158 | it is actually talking to the server it wants to rather | |
1159 | than some attacker operating a Man In The Middle (MITM) | |
1160 | operation. The latter can terminate the TLS connection | |
1161 | you make, and make another one to the server (so both | |
1162 | you and the server still think you have an encrypted | |
1163 | connection) and, if one of the "well known" set of | |
1164 | Certificate Authorities has been suborned - something | |
1165 | which *has* been seen already (2014), a verifiable | |
1166 | certificate (if you're using normal root CAs, eg. the | |
1167 | Mozilla set, as your trust anchors). | |
1168 | ||
1169 | What DANE does is replace the CAs with the DNS as the | |
1170 | trust anchor. The assurance is limited to a) the possibility | |
1171 | that the DNS has been suborned, b) mistakes made by the | |
1172 | admins of the target server. The attack surface presented | |
1173 | by (a) is thought to be smaller than that of the set | |
1174 | of root CAs. | |
1175 | ||
0e66b3b6 JH |
1176 | It also allows the server to declare (implicitly) that |
1177 | connections to it should use TLS. An MITM could simply | |
1178 | fail to pass on a server's STARTTLS. | |
1179 | ||
7cac846b JH |
1180 | DANE scales better than having to maintain (and |
1181 | side-channel communicate) copies of server certificates | |
1182 | for every possible target server. It also scales | |
1183 | (slightly) better than having to maintain on an SMTP | |
1184 | client a copy of the standard CAs bundle. It also | |
1185 | means not having to pay a CA for certificates. | |
1186 | ||
1187 | DANE requires a server operator to do three things: | |
1188 | 1) run DNSSEC. This provides assurance to clients | |
1189 | that DNS lookups they do for the server have not | |
401a8935 JH |
1190 | been tampered with. The domain MX record applying |
1191 | to this server, its A record, its TLSA record and | |
1192 | any associated CNAME records must all be covered by | |
1193 | DNSSEC. | |
7cac846b JH |
1194 | 2) add TLSA DNS records. These say what the server |
1195 | certificate for a TLS connection should be. | |
1196 | 3) offer a server certificate, or certificate chain, | |
1197 | in TLS connections which is traceable to the one | |
1198 | defined by (one of?) the TSLA records | |
1199 | ||
1200 | There are no changes to Exim specific to server-side | |
1201 | operation of DANE. | |
1202 | ||
1203 | The TLSA record for the server may have "certificate | |
0e66b3b6 | 1204 | usage" of DANE-TA(2) or DANE-EE(3). The latter specifies |
7cac846b JH |
1205 | the End Entity directly, i.e. the certificate involved |
1206 | is that of the server (and should be the sole one transmitted | |
1207 | during the TLS handshake); this is appropriate for a | |
1208 | single system, using a self-signed certificate. | |
0e66b3b6 | 1209 | DANE-TA usage is effectively declaring a specific CA |
7cac846b JH |
1210 | to be used; this might be a private CA or a public, |
1211 | well-known one. A private CA at simplest is just | |
1212 | a self-signed certificate which is used to sign | |
1213 | cerver certificates, but running one securely does | |
1214 | require careful arrangement. If a private CA is used | |
1215 | then either all clients must be primed with it, or | |
1216 | (probably simpler) the server TLS handshake must transmit | |
1217 | the entire certificate chain from CA to server-certificate. | |
1218 | If a public CA is used then all clients must be primed with it | |
1219 | (losing one advantage of DANE) - but the attack surface is | |
1220 | reduced from all public CAs to that single CA. | |
0e66b3b6 | 1221 | DANE-TA is commonly used for several services and/or |
7cac846b JH |
1222 | servers, each having a TLSA query-domain CNAME record, |
1223 | all of which point to a single TLSA record. | |
1224 | ||
1225 | The TLSA record should have a Selector field of SPKI(1) | |
401a8935 JH |
1226 | and a Matching Type field of SHA2-512(2). |
1227 | ||
1228 | At the time of writing, https://www.huque.com/bin/gen_tlsa | |
1229 | is useful for quickly generating TLSA records; and commands like | |
1230 | ||
1231 | openssl x509 -in -pubkey -noout <certificate.pem \ | |
1232 | | openssl rsa -outform der -pubin 2>/dev/null \ | |
1233 | | openssl sha512 \ | |
1234 | | awk '{print $2}' | |
1235 | ||
1236 | are workable for 4th-field hashes. | |
7cac846b | 1237 | |
0e66b3b6 | 1238 | For use with the DANE-TA model, server certificates |
7cac846b JH |
1239 | must have a correct name (SubjectName or SubjectAltName). |
1240 | ||
1241 | The use of OCSP-stapling should be considered, allowing | |
1242 | for fast revocation of certificates (which would otherwise | |
eeb9276b | 1243 | be limited by the DNS TTL on the TLSA records). However, |
0e66b3b6 | 1244 | this is likely to only be usable with DANE-TA. NOTE: the |
fca41d5a JH |
1245 | default of requesting OCSP for all hosts is modified iff |
1246 | DANE is in use, to: | |
1247 | ||
1248 | hosts_request_ocsp = ${if or { {= {0}{$tls_out_tlsa_usage}} \ | |
1249 | {= {4}{$tls_out_tlsa_usage}} } \ | |
594706ea | 1250 | {*}{}} |
fca41d5a JH |
1251 | |
1252 | The (new) variable $tls_out_tlsa_usage is a bitfield with | |
1253 | numbered bits set for TLSA record usage codes. | |
1254 | The zero above means DANE was not in use, | |
0e66b3b6 JH |
1255 | the four means that only DANE-TA usage TLSA records were |
1256 | found. If the definition of hosts_request_ocsp includes the | |
1257 | string "tls_out_tlsa_usage", they are re-expanded in time to | |
1258 | control the OCSP request. | |
594706ea | 1259 | |
fca41d5a | 1260 | This modification of hosts_request_ocsp is only done if |
036ed0db JH |
1261 | it has the default value of "*". Admins who change it, and |
1262 | those who use hosts_require_ocsp, should consider the interaction | |
1263 | with DANE in their OCSP settings. | |
7cac846b JH |
1264 | |
1265 | ||
7a31d643 JH |
1266 | For client-side DANE there are two new smtp transport options, |
1267 | hosts_try_dane and hosts_require_dane. They do the obvious thing. | |
1268 | [ should they be domain-based rather than host-based? ] | |
7cac846b JH |
1269 | |
1270 | DANE will only be usable if the target host has DNSSEC-secured | |
1271 | MX, A and TLSA records. | |
1272 | ||
0e66b3b6 JH |
1273 | A TLSA lookup will be done if either of the above options match |
1274 | and the host-lookup succeded using dnssec. | |
3750d68d JH |
1275 | If a TLSA lookup is done and succeeds, a DANE-verified TLS connection |
1276 | will be required for the host. | |
0e66b3b6 | 1277 | |
7cac846b JH |
1278 | (TODO: specify when fallback happens vs. when the host is not used) |
1279 | ||
3750d68d JH |
1280 | If DANE is requested and useable (see above) the following transport |
1281 | options are ignored: | |
0e66b3b6 | 1282 | hosts_require_tls |
043b1248 JH |
1283 | tls_verify_hosts |
1284 | tls_try_verify_hosts | |
1285 | tls_verify_certificates | |
1286 | tls_crl | |
1287 | tls_verify_cert_hostnames | |
043b1248 | 1288 | |
3750d68d JH |
1289 | If DANE is not usable, whether requested or not, and CA-anchored |
1290 | verification evaluation is wanted, the above variables should be set | |
1291 | appropriately. | |
1292 | ||
7cac846b JH |
1293 | Currently dnssec_request_domains must be active (need to think about that) |
1294 | and dnssec_require_domains is ignored. | |
043b1248 | 1295 | |
eeb9276b JH |
1296 | If verification was successful using DANE then the "CV" item |
1297 | in the delivery log line will show as "CV=dane". | |
1298 | ||
594706ea JH |
1299 | There is a new variable $tls_out_dane which will have "yes" if |
1300 | verification succeeded using DANE and "no" otherwise (only useful | |
8d692470 | 1301 | in combination with EXPERIMENTAL_EVENT), and a new variable |
594706ea JH |
1302 | $tls_out_tlsa_usage (detailed above). |
1303 | ||
e51c7be2 | 1304 | |
c65be124 | 1305 | |
ed0512a1 | 1306 | INTERNATIONAL |
c65be124 | 1307 | ------------------------------------------------------------ |
ed0512a1 | 1308 | SMTPUTF8 |
c65be124 JH |
1309 | Internationalised mail name handling. |
1310 | RFCs 6530, 6533, 5890 | |
1311 | ||
4e08fd50 JH |
1312 | Compile with EXPERIMENTAL_INTERNATIONAL and libidn. |
1313 | ||
810d16ad | 1314 | New main config option smtputf8_advertise_hosts, default '*', |
9d4319df JH |
1315 | a host list. If this matches the sending host and |
1316 | accept_8bitmime is true (the default) then the ESMTP option | |
1317 | SMTPUTF8 will be advertised. | |
1318 | ||
1319 | If the sender specifies the SMTPUTF8 option on a MAIL command | |
1320 | international handling for the message is enabled and | |
1321 | the expansion variable $message_smtputf8 will have value TRUE. | |
1322 | ||
1323 | The option allow_utf8_domains is set to true for this | |
7019e10b JH |
1324 | message. All DNS lookups are converted to a-label form |
1325 | whatever the setting of allow_utf8_domains. | |
9d4319df | 1326 | |
810d16ad JH |
1327 | Both localparts and domain are maintained as the original |
1328 | utf8 form internally; any matching or regex use will | |
1329 | require appropriate care. Filenames created, eg. by | |
1330 | the appendfile transport, will have utf8 name. | |
1331 | ||
1332 | Helo names sent by the smtp transport will have any utf8 | |
1333 | components expanded to a-label form. | |
1334 | ||
4af0d74a JH |
1335 | Any certificate name checks will be done using the a-label |
1336 | form of the name. | |
1337 | ||
9d4319df | 1338 | Log lines and Received-by: header lines will aquire a "utf8" |
5a886ce7 | 1339 | prefix on the protocol element, eg. utf8esmtp. |
9d4319df | 1340 | |
810d16ad | 1341 | New expansion operators: |
4e08fd50 JH |
1342 | ${utf8_domain_to_alabel:str} |
1343 | ${utf8_domain_from_alabel:str} | |
1344 | ${utf8_localpart_to_alabel:str} | |
1345 | ${utf8_localpart_from_alabel:str} | |
c65be124 | 1346 | |
3c8b3577 JH |
1347 | New "control = utf8_downconvert" ACL modifier, |
1348 | sets a flag requiring that addresses are converted to | |
1349 | a-label form before smtp delivery, for use in a | |
1350 | Message Submission Agent context. Can also be | |
1351 | phrased as "control = utf8_downconvert/1" and is | |
1352 | mandatory. The flag defaults to zero and can be cleared | |
1353 | by "control = utf8_downconvert/0". The value "-1" | |
1354 | may also be used, to use a-label for only if the | |
1355 | destination host does not support SMTPUTF8. | |
1356 | ||
9479146e JH |
1357 | If mua_wrapper is set, the utf8_downconvert control |
1358 | defaults to -1 (convert if needed). | |
1359 | ||
1360 | ||
1361 | There is no explicit support for VRFY and EXPN. | |
1362 | Configurations supporting these should inspect | |
1363 | $smtp_command_argument for an SMTPUTF8 argument. | |
1364 | ||
1365 | There is no support for LMTP on Unix sockets. | |
1366 | Using the "lmtp" protocol option on an smtp transport, | |
1367 | for LMTP over TCP, should work as expected. | |
1368 | ||
810d16ad | 1369 | Known issues: |
810d16ad | 1370 | - DSN unitext handling is not present |
9479146e | 1371 | - no provision for converting logging from or to UTF-8 |
c65be124 | 1372 | |
ed0512a1 JH |
1373 | ---- |
1374 | IMAP folder names | |
1375 | ||
1376 | New expansion operator: | |
1377 | ||
1378 | ${imapfolder {<string>} {<sep>} {<specials>}} | |
1379 | ||
1380 | The string is converted from the charset specified by the headers charset | |
1381 | command (in a filter file) or headers_charset global option, to the | |
1382 | modified UTF-7 encoding specified by RFC 2060, with the following | |
1383 | exception: All occurences of <sep> (which has to be a single character) | |
1384 | are replaced with periods ("."), and all periods and slashes that aren't | |
1385 | <sep> and are not in the <specials> string are BASE64 encoded. | |
1386 | ||
1387 | The third argument can be omitted, defaulting to an empty string. | |
1388 | The second argument can be omitted, defaulting to "/". | |
1389 | ||
1390 | This is the encoding used by Courier for Maildir names on disk, and followed | |
1391 | by many other IMAP servers. | |
1392 | ||
1393 | Example 1: ${imapfolder {Foo/Bar}} yields "Foo.Bar". | |
1394 | Example 2: ${imapfolder {Foo/Bar}{.}{/}} yields "Foo&AC8-Bar". | |
1395 | Example 3: ${imapfolder {Räksmörgås}} yields "R&AOQ-ksm&APY-rg&AOU-s". | |
1396 | ||
1397 | Note that the source charset setting is vital, and also that characters | |
1398 | must be representable in UTF-16. | |
1399 | ||
1400 | ||
1401 | ||
895fbaf2 JH |
1402 | DSN extra information |
1403 | --------------------- | |
1404 | If compiled with EXPERIMENTAL_DSN_INFO extra information will be added | |
1405 | to DSN fail messages ("bounces"), when available. The intent is to aid | |
1406 | tracing of specific failing messages, when presented with a "bounce" | |
1407 | complaint and needing to search logs. | |
1408 | ||
1409 | ||
1410 | The remote MTA IP address, with port number if nonstandard. | |
1411 | Example: | |
1412 | Remote-MTA: X-ip; [127.0.0.1]:587 | |
1413 | Rationale: | |
1414 | Several addresses may correspond to the (already available) | |
1415 | dns name for the remote MTA. | |
1416 | ||
1417 | The remote MTA connect-time greeting. | |
1418 | Example: | |
1419 | X-Remote-MTA-smtp-greeting: X-str; 220 the.local.host.name ESMTP Exim x.yz Tue, 2 Mar 1999 09:44:33 +0000 | |
1420 | Rationale: | |
1421 | This string sometimes presents the remote MTA's idea of its | |
1422 | own name, and sometimes identifies the MTA software. | |
1423 | ||
1424 | The remote MTA response to HELO or EHLO. | |
1425 | Example: | |
1426 | X-Remote-MTA-helo-response: X-str; 250-the.local.host.name Hello localhost [127.0.0.1] | |
1427 | Limitations: | |
1428 | Only the first line of a multiline response is recorded. | |
1429 | Rationale: | |
1430 | This string sometimes presents the remote MTA's view of | |
1431 | the peer IP connecting to it. | |
1432 | ||
1433 | The reporting MTA detailed diagnostic. | |
1434 | Example: | |
1435 | X-Exim-Diagnostic: X-str; SMTP error from remote mail server after RCPT TO:<d3@myhost.test.ex>: 550 hard error | |
1436 | Rationale: | |
1437 | This string somtimes give extra information over the | |
1438 | existing (already available) Diagnostic-Code field. | |
1439 | ||
1440 | ||
1441 | Note that non-RFC-documented field names and data types are used. | |
1442 | ||
1443 | ||
1444 | ||
ed0512a1 | 1445 | |
ee161e8f PH |
1446 | -------------------------------------------------------------- |
1447 | End of file | |
1448 | -------------------------------------------------------------- |