Commit | Line | Data |
---|---|---|
420a0d19 CE |
1 | Specification of the Exim Mail Transfer Agent |
2 | ||
3 | Exim Maintainers | |
4 | ||
2813c06e CE |
5 | Copyright (c) 2017 University of Cambridge |
6 | ||
7 | Revision 4.89 07 Mar 2017 EM | |
420a0d19 | 8 | |
420a0d19 CE |
9 | ------------------------------------------------------------------------------- |
10 | ||
11 | TABLE OF CONTENTS | |
12 | ||
13 | 1. Introduction | |
14 | ||
15 | 1.1. Exim documentation | |
16 | 1.2. FTP and web sites | |
17 | 1.3. Mailing lists | |
18 | 1.4. Exim training | |
19 | 1.5. Bug reports | |
20 | 1.6. Where to find the Exim distribution | |
21 | 1.7. Limitations | |
22 | 1.8. Run time configuration | |
23 | 1.9. Calling interface | |
24 | 1.10. Terminology | |
25 | ||
26 | 2. Incorporated code | |
27 | 3. How Exim receives and delivers mail | |
28 | ||
29 | 3.1. Overall philosophy | |
30 | 3.2. Policy control | |
31 | 3.3. User filters | |
32 | 3.4. Message identification | |
33 | 3.5. Receiving mail | |
34 | 3.6. Handling an incoming message | |
35 | 3.7. Life of a message | |
36 | 3.8. Processing an address for delivery | |
37 | 3.9. Processing an address for verification | |
38 | 3.10. Running an individual router | |
39 | 3.11. Duplicate addresses | |
40 | 3.12. Router preconditions | |
41 | 3.13. Delivery in detail | |
42 | 3.14. Retry mechanism | |
43 | 3.15. Temporary delivery failure | |
44 | 3.16. Permanent delivery failure | |
45 | 3.17. Failures to deliver bounce messages | |
46 | ||
47 | 4. Building and installing Exim | |
48 | ||
49 | 4.1. Unpacking | |
50 | 4.2. Multiple machine architectures and operating systems | |
51 | 4.3. PCRE library | |
52 | 4.4. DBM libraries | |
53 | 4.5. Pre-building configuration | |
54 | 4.6. Support for iconv() | |
55 | 4.7. Including TLS/SSL encryption support | |
56 | 4.8. Use of tcpwrappers | |
57 | 4.9. Including support for IPv6 | |
58 | 4.10. Dynamically loaded lookup module support | |
59 | 4.11. The building process | |
60 | 4.12. Output from "make" | |
61 | 4.13. Overriding build-time options for Exim | |
62 | 4.14. OS-specific header files | |
63 | 4.15. Overriding build-time options for the monitor | |
64 | 4.16. Installing Exim binaries and scripts | |
65 | 4.17. Installing info documentation | |
66 | 4.18. Setting up the spool directory | |
67 | 4.19. Testing | |
68 | 4.20. Replacing another MTA with Exim | |
69 | 4.21. Upgrading Exim | |
70 | 4.22. Stopping the Exim daemon on Solaris | |
71 | ||
72 | 5. The Exim command line | |
73 | ||
74 | 5.1. Setting options by program name | |
75 | 5.2. Trusted and admin users | |
76 | 5.3. Command line options | |
77 | ||
78 | 6. The Exim run time configuration file | |
79 | ||
80 | 6.1. Using a different configuration file | |
81 | 6.2. Configuration file format | |
82 | 6.3. File inclusions in the configuration file | |
83 | 6.4. Macros in the configuration file | |
84 | 6.5. Macro substitution | |
85 | 6.6. Redefining macros | |
86 | 6.7. Overriding macro values | |
87 | 6.8. Example of macro usage | |
2813c06e CE |
88 | 6.9. Builtin macros |
89 | 6.10. Conditional skips in the configuration file | |
90 | 6.11. Common option syntax | |
91 | 6.12. Boolean options | |
92 | 6.13. Integer values | |
93 | 6.14. Octal integer values | |
94 | 6.15. Fixed point numbers | |
95 | 6.16. Time intervals | |
96 | 6.17. String values | |
97 | 6.18. Expanded strings | |
98 | 6.19. User and group names | |
99 | 6.20. List construction | |
100 | 6.21. Changing list separators | |
101 | 6.22. Empty items in lists | |
102 | 6.23. Format of driver configurations | |
420a0d19 CE |
103 | |
104 | 7. The default configuration file | |
105 | ||
106 | 7.1. Main configuration settings | |
107 | 7.2. ACL configuration | |
108 | 7.3. Router configuration | |
109 | 7.4. Transport configuration | |
110 | 7.5. Default retry rule | |
111 | 7.6. Rewriting configuration | |
112 | 7.7. Authenticators configuration | |
113 | ||
114 | 8. Regular expressions | |
115 | 9. File and database lookups | |
116 | ||
117 | 9.1. Examples of different lookup syntax | |
118 | 9.2. Lookup types | |
119 | 9.3. Single-key lookup types | |
120 | 9.4. Query-style lookup types | |
121 | 9.5. Temporary errors in lookups | |
122 | 9.6. Default values in single-key lookups | |
123 | 9.7. Partial matching in single-key lookups | |
124 | 9.8. Lookup caching | |
125 | 9.9. Quoting lookup data | |
126 | 9.10. More about dnsdb | |
2813c06e CE |
127 | 9.11. Dnsdb lookup modifiers |
128 | 9.12. Pseudo dnsdb record types | |
129 | 9.13. Multiple dnsdb lookups | |
130 | 9.14. More about LDAP | |
131 | 9.15. Format of LDAP queries | |
132 | 9.16. LDAP quoting | |
133 | 9.17. LDAP connections | |
134 | 9.18. LDAP authentication and control information | |
135 | 9.19. Format of data returned by LDAP | |
136 | 9.20. More about NIS+ | |
137 | 9.21. SQL lookups | |
138 | 9.22. More about MySQL, PostgreSQL, Oracle, InterBase, and Redis | |
139 | 9.23. Specifying the server in the query | |
140 | 9.24. Special MySQL features | |
141 | 9.25. Special PostgreSQL features | |
142 | 9.26. More about SQLite | |
143 | 9.27. More about Redis | |
420a0d19 CE |
144 | |
145 | 10. Domain, host, address, and local part lists | |
146 | ||
147 | 10.1. Expansion of lists | |
148 | 10.2. Negated items in lists | |
149 | 10.3. File names in lists | |
150 | 10.4. An lsearch file is not an out-of-line list | |
151 | 10.5. Named lists | |
152 | 10.6. Named lists compared with macros | |
153 | 10.7. Named list caching | |
154 | 10.8. Domain lists | |
155 | 10.9. Host lists | |
156 | 10.10. Special host list patterns | |
157 | 10.11. Host list patterns that match by IP address | |
158 | 10.12. Host list patterns for single-key lookups by host address | |
159 | 10.13. Host list patterns that match by host name | |
160 | 10.14. Behaviour when an IP address or name cannot be found | |
161 | 10.15. Mixing wildcarded host names and addresses in host lists | |
162 | 10.16. Temporary DNS errors when looking up host information | |
163 | 10.17. Host list patterns for single-key lookups by host name | |
164 | 10.18. Host list patterns for query-style lookups | |
165 | 10.19. Address lists | |
166 | 10.20. Case of letters in address lists | |
167 | 10.21. Local part lists | |
168 | ||
169 | 11. String expansions | |
170 | ||
171 | 11.1. Literal text in expanded strings | |
172 | 11.2. Character escape sequences in expanded strings | |
173 | 11.3. Testing string expansions | |
174 | 11.4. Forced expansion failure | |
175 | 11.5. Expansion items | |
176 | 11.6. Expansion operators | |
177 | 11.7. Expansion conditions | |
178 | 11.8. Combining expansion conditions | |
179 | 11.9. Expansion variables | |
180 | ||
181 | 12. Embedded Perl | |
182 | ||
183 | 12.1. Setting up so Perl can be used | |
184 | 12.2. Calling Perl subroutines | |
185 | 12.3. Calling Exim functions from Perl | |
186 | 12.4. Use of standard output and error by Perl | |
187 | ||
188 | 13. Starting the daemon and the use of network interfaces | |
189 | ||
190 | 13.1. Starting a listening daemon | |
191 | 13.2. Special IP listening addresses | |
192 | 13.3. Overriding local_interfaces and daemon_smtp_ports | |
193 | 13.4. Support for the obsolete SSMTP (or SMTPS) protocol | |
194 | 13.5. IPv6 address scopes | |
195 | 13.6. Disabling IPv6 | |
196 | 13.7. Examples of starting a listening daemon | |
197 | 13.8. Recognizing the local host | |
198 | 13.9. Delivering to a remote host | |
199 | ||
200 | 14. Main configuration | |
201 | ||
202 | 14.1. Miscellaneous | |
203 | 14.2. Exim parameters | |
204 | 14.3. Privilege controls | |
205 | 14.4. Logging | |
206 | 14.5. Frozen messages | |
207 | 14.6. Data lookups | |
208 | 14.7. Message ids | |
209 | 14.8. Embedded Perl Startup | |
210 | 14.9. Daemon | |
211 | 14.10. Resource control | |
212 | 14.11. Policy controls | |
213 | 14.12. Callout cache | |
214 | 14.13. TLS | |
215 | 14.14. Local user handling | |
216 | 14.15. All incoming messages (SMTP and non-SMTP) | |
217 | 14.16. Non-SMTP incoming messages | |
218 | 14.17. Incoming SMTP messages | |
219 | 14.18. SMTP extensions | |
220 | 14.19. Processing messages | |
221 | 14.20. System filter | |
222 | 14.21. Routing and delivery | |
223 | 14.22. Bounce and warning messages | |
224 | 14.23. Alphabetical list of main options | |
225 | ||
226 | 15. Generic options for routers | |
227 | 16. The accept router | |
228 | 17. The dnslookup router | |
229 | ||
230 | 17.1. Problems with DNS lookups | |
231 | 17.2. Declining addresses by dnslookup | |
232 | 17.3. Private options for dnslookup | |
233 | 17.4. Effect of qualify_single and search_parents | |
234 | ||
235 | 18. The ipliteral router | |
236 | 19. The iplookup router | |
237 | 20. The manualroute router | |
238 | ||
239 | 20.1. Private options for manualroute | |
240 | 20.2. Routing rules in route_list | |
241 | 20.3. Routing rules in route_data | |
242 | 20.4. Format of the list of hosts | |
243 | 20.5. Format of one host item | |
244 | 20.6. How the list of hosts is used | |
245 | 20.7. How the options are used | |
246 | 20.8. Manualroute examples | |
247 | ||
248 | 21. The queryprogram router | |
249 | 22. The redirect router | |
250 | ||
251 | 22.1. Redirection data | |
252 | 22.2. Forward files and address verification | |
253 | 22.3. Interpreting redirection data | |
254 | 22.4. Items in a non-filter redirection list | |
255 | 22.5. Redirecting to a local mailbox | |
256 | 22.6. Special items in redirection lists | |
257 | 22.7. Duplicate addresses | |
258 | 22.8. Repeated redirection expansion | |
259 | 22.9. Errors in redirection lists | |
260 | 22.10. Private options for the redirect router | |
261 | ||
262 | 23. Environment for running local transports | |
263 | ||
264 | 23.1. Concurrent deliveries | |
265 | 23.2. Uids and gids | |
266 | 23.3. Current and home directories | |
267 | 23.4. Expansion variables derived from the address | |
268 | ||
269 | 24. Generic options for transports | |
270 | 25. Address batching in local transports | |
271 | 26. The appendfile transport | |
272 | ||
273 | 26.1. The file and directory options | |
274 | 26.2. Private options for appendfile | |
275 | 26.3. Operational details for appending | |
276 | 26.4. Operational details for delivery to a new file | |
277 | 26.5. Maildir delivery | |
278 | 26.6. Using tags to record message sizes | |
279 | 26.7. Using a maildirsize file | |
280 | 26.8. Mailstore delivery | |
281 | 26.9. Non-special new file delivery | |
282 | ||
283 | 27. The autoreply transport | |
284 | ||
285 | 27.1. Private options for autoreply | |
286 | ||
287 | 28. The lmtp transport | |
288 | 29. The pipe transport | |
289 | ||
290 | 29.1. Concurrent delivery | |
291 | 29.2. Returned status and data | |
292 | 29.3. How the command is run | |
293 | 29.4. Environment variables | |
294 | 29.5. Private options for pipe | |
295 | 29.6. Using an external local delivery agent | |
296 | ||
297 | 30. The smtp transport | |
298 | ||
299 | 30.1. Multiple messages on a single connection | |
300 | 30.2. Use of the $host and $host_address variables | |
301 | 30.3. Use of $tls_cipher and $tls_peerdn | |
302 | 30.4. Private options for smtp | |
303 | 30.5. How the limits for the number of hosts to try are used | |
304 | ||
305 | 31. Address rewriting | |
306 | ||
307 | 31.1. Explicitly configured address rewriting | |
308 | 31.2. When does rewriting happen? | |
309 | 31.3. Testing the rewriting rules that apply on input | |
310 | 31.4. Rewriting rules | |
311 | 31.5. Rewriting patterns | |
312 | 31.6. Rewriting replacements | |
313 | 31.7. Rewriting flags | |
314 | 31.8. Flags specifying which headers and envelope addresses to rewrite | |
315 | 31.9. The SMTP-time rewriting flag | |
316 | 31.10. Flags controlling the rewriting process | |
317 | 31.11. Rewriting examples | |
318 | ||
319 | 32. Retry configuration | |
320 | ||
321 | 32.1. Changing retry rules | |
322 | 32.2. Format of retry rules | |
323 | 32.3. Choosing which retry rule to use for address errors | |
324 | 32.4. Choosing which retry rule to use for host and message errors | |
325 | 32.5. Retry rules for specific errors | |
326 | 32.6. Retry rules for specified senders | |
327 | 32.7. Retry parameters | |
328 | 32.8. Retry rule examples | |
329 | 32.9. Timeout of retry data | |
330 | 32.10. Long-term failures | |
331 | 32.11. Deliveries that work intermittently | |
332 | ||
333 | 33. SMTP authentication | |
334 | ||
335 | 33.1. Generic options for authenticators | |
336 | 33.2. The AUTH parameter on MAIL commands | |
337 | 33.3. Authentication on an Exim server | |
338 | 33.4. Testing server authentication | |
339 | 33.5. Authentication by an Exim client | |
340 | ||
341 | 34. The plaintext authenticator | |
342 | ||
343 | 34.1. Plaintext options | |
344 | 34.2. Using plaintext in a server | |
345 | 34.3. The PLAIN authentication mechanism | |
346 | 34.4. The LOGIN authentication mechanism | |
347 | 34.5. Support for different kinds of authentication | |
348 | 34.6. Using plaintext in a client | |
349 | ||
350 | 35. The cram_md5 authenticator | |
351 | ||
352 | 35.1. Using cram_md5 as a server | |
353 | 35.2. Using cram_md5 as a client | |
354 | ||
355 | 36. The cyrus_sasl authenticator | |
356 | ||
357 | 36.1. Using cyrus_sasl as a server | |
358 | ||
359 | 37. The dovecot authenticator | |
360 | 38. The gsasl authenticator | |
361 | ||
362 | 38.1. gsasl auth variables | |
363 | ||
364 | 39. The heimdal_gssapi authenticator | |
365 | ||
366 | 39.1. heimdal_gssapi auth variables | |
367 | ||
368 | 40. The spa authenticator | |
369 | ||
370 | 40.1. Using spa as a server | |
371 | 40.2. Using spa as a client | |
372 | ||
2813c06e CE |
373 | 41. The tls authenticator |
374 | 42. Encrypted SMTP connections using TLS/SSL | |
375 | ||
376 | 42.1. Support for the legacy "ssmtp" (aka "smtps") protocol | |
377 | 42.2. OpenSSL vs GnuTLS | |
378 | 42.3. GnuTLS parameter computation | |
379 | 42.4. Requiring specific ciphers in OpenSSL | |
380 | 42.5. Requiring specific ciphers or other parameters in GnuTLS | |
381 | 42.6. Configuring an Exim server to use TLS | |
382 | 42.7. Requesting and verifying client certificates | |
383 | 42.8. Revoked certificates | |
384 | 42.9. Configuring an Exim client to use TLS | |
385 | 42.10. Use of TLS Server Name Indication | |
386 | 42.11. Multiple messages on the same encrypted TCP/IP connection | |
387 | 42.12. Certificates and all that | |
388 | 42.13. Certificate chains | |
389 | 42.14. Self-signed certificates | |
390 | ||
391 | 43. Access control lists | |
392 | ||
393 | 43.1. Testing ACLs | |
394 | 43.2. Specifying when ACLs are used | |
395 | 43.3. The non-SMTP ACLs | |
396 | 43.4. The SMTP connect ACL | |
397 | 43.5. The EHLO/HELO ACL | |
398 | 43.6. The DATA ACLs | |
399 | 43.7. The SMTP DKIM ACL | |
400 | 43.8. The SMTP MIME ACL | |
401 | 43.9. The SMTP PRDR ACL | |
402 | 43.10. The QUIT ACL | |
403 | 43.11. The not-QUIT ACL | |
404 | 43.12. Finding an ACL to use | |
405 | 43.13. ACL return codes | |
406 | 43.14. Unset ACL options | |
407 | 43.15. Data for message ACLs | |
408 | 43.16. Data for non-message ACLs | |
409 | 43.17. Format of an ACL | |
410 | 43.18. ACL verbs | |
411 | 43.19. ACL variables | |
412 | 43.20. Condition and modifier processing | |
413 | 43.21. ACL modifiers | |
414 | 43.22. Use of the control modifier | |
415 | 43.23. Summary of message fixup control | |
416 | 43.24. Adding header lines in ACLs | |
417 | 43.25. Removing header lines in ACLs | |
418 | 43.26. ACL conditions | |
419 | 43.27. Using DNS lists | |
420 | 43.28. Specifying the IP address for a DNS list lookup | |
421 | 43.29. DNS lists keyed on domain names | |
422 | 43.30. Multiple explicit keys for a DNS list | |
423 | 43.31. Data returned by DNS lists | |
424 | 43.32. Variables set from DNS lists | |
425 | 43.33. Additional matching conditions for DNS lists | |
426 | 43.34. Negated DNS matching conditions | |
427 | 43.35. Handling multiple DNS records from a DNS list | |
428 | 43.36. Detailed information from merged DNS lists | |
429 | 43.37. DNS lists and IPv6 | |
430 | 43.38. Rate limiting incoming messages | |
431 | 43.39. Ratelimit options for what is being measured | |
432 | 43.40. Ratelimit update modes | |
433 | 43.41. Ratelimit options for handling fast clients | |
434 | 43.42. Limiting the rate of different events | |
435 | 43.43. Using rate limiting | |
436 | 43.44. Address verification | |
437 | 43.45. Callout verification | |
438 | 43.46. Additional parameters for callouts | |
439 | 43.47. Callout caching | |
440 | 43.48. Sender address verification reporting | |
441 | 43.49. Redirection while verifying | |
442 | 43.50. Client SMTP authorization (CSA) | |
443 | 43.51. Bounce address tag validation | |
444 | 43.52. Using an ACL to control relaying | |
445 | 43.53. Checking a relay configuration | |
446 | ||
447 | 44. Content scanning at ACL time | |
448 | ||
449 | 44.1. Scanning for viruses | |
450 | 44.2. Scanning with SpamAssassin and Rspamd | |
451 | 44.3. Calling SpamAssassin from an Exim ACL | |
452 | 44.4. Scanning MIME parts | |
453 | 44.5. Scanning with regular expressions | |
454 | ||
455 | 45. Adding a local scan function to Exim | |
456 | ||
457 | 45.1. Building Exim to use a local scan function | |
458 | 45.2. API for local_scan() | |
459 | 45.3. Configuration options for local_scan() | |
460 | 45.4. Available Exim variables | |
461 | 45.5. Structure of header lines | |
462 | 45.6. Structure of recipient items | |
463 | 45.7. Available Exim functions | |
464 | 45.8. More about Exim's memory handling | |
465 | ||
466 | 46. System-wide message filtering | |
467 | ||
468 | 46.1. Specifying a system filter | |
469 | 46.2. Testing a system filter | |
470 | 46.3. Contents of a system filter | |
471 | 46.4. Additional variable for system filters | |
472 | 46.5. Defer, freeze, and fail commands for system filters | |
473 | 46.6. Adding and removing headers in a system filter | |
474 | 46.7. Setting an errors address in a system filter | |
475 | 46.8. Per-address filtering | |
476 | ||
477 | 47. Message processing | |
478 | ||
479 | 47.1. Submission mode for non-local messages | |
480 | 47.2. Line endings | |
481 | 47.3. Unqualified addresses | |
482 | 47.4. The UUCP From line | |
483 | 47.5. Resent- header lines | |
484 | 47.6. The Auto-Submitted: header line | |
485 | 47.7. The Bcc: header line | |
486 | 47.8. The Date: header line | |
487 | 47.9. The Delivery-date: header line | |
488 | 47.10. The Envelope-to: header line | |
489 | 47.11. The From: header line | |
490 | 47.12. The Message-ID: header line | |
491 | 47.13. The Received: header line | |
492 | 47.14. The References: header line | |
493 | 47.15. The Return-path: header line | |
494 | 47.16. The Sender: header line | |
495 | 47.17. Adding and removing header lines in routers and transports | |
496 | 47.18. Constructed addresses | |
497 | 47.19. Case of local parts | |
498 | 47.20. Dots in local parts | |
499 | 47.21. Rewriting addresses | |
500 | ||
501 | 48. SMTP processing | |
502 | ||
503 | 48.1. Outgoing SMTP and LMTP over TCP/IP | |
504 | 48.2. Errors in outgoing SMTP | |
505 | 48.3. Incoming SMTP messages over TCP/IP | |
506 | 48.4. Unrecognized SMTP commands | |
507 | 48.5. Syntax and protocol errors in SMTP commands | |
508 | 48.6. Use of non-mail SMTP commands | |
509 | 48.7. The VRFY and EXPN commands | |
510 | 48.8. The ETRN command | |
511 | 48.9. Incoming local SMTP | |
512 | 48.10. Outgoing batched SMTP | |
513 | 48.11. Incoming batched SMTP | |
514 | ||
515 | 49. Customizing bounce and warning messages | |
516 | ||
517 | 49.1. Customizing bounce messages | |
518 | 49.2. Customizing warning messages | |
519 | ||
520 | 50. Some common configuration settings | |
521 | ||
522 | 50.1. Sending mail to a smart host | |
523 | 50.2. Using Exim to handle mailing lists | |
524 | 50.3. Syntax errors in mailing lists | |
525 | 50.4. Re-expansion of mailing lists | |
526 | 50.5. Closed mailing lists | |
527 | 50.6. Variable Envelope Return Paths (VERP) | |
528 | 50.7. Virtual domains | |
529 | 50.8. Multiple user mailboxes | |
530 | 50.9. Simplified vacation processing | |
531 | 50.10. Taking copies of mail | |
532 | 50.11. Intermittently connected hosts | |
533 | 50.12. Exim on the upstream server host | |
534 | 50.13. Exim on the intermittently connected client host | |
535 | ||
536 | 51. Using Exim as a non-queueing client | |
537 | 52. Log files | |
538 | ||
539 | 52.1. Where the logs are written | |
540 | 52.2. Logging to local files that are periodically "cycled" | |
541 | 52.3. Datestamped log files | |
542 | 52.4. Logging to syslog | |
543 | 52.5. Log line flags | |
544 | 52.6. Logging message reception | |
545 | 52.7. Logging deliveries | |
546 | 52.8. Discarded deliveries | |
547 | 52.9. Deferred deliveries | |
548 | 52.10. Delivery failures | |
549 | 52.11. Fake deliveries | |
550 | 52.12. Completion | |
551 | 52.13. Summary of Fields in Log Lines | |
552 | 52.14. Other log entries | |
553 | 52.15. Reducing or increasing what is logged | |
554 | 52.16. Message log | |
555 | ||
556 | 53. Exim utilities | |
557 | ||
558 | 53.1. Finding out what Exim processes are doing (exiwhat) | |
559 | 53.2. Selective queue listing (exiqgrep) | |
560 | 53.3. Summarizing the queue (exiqsumm) | |
561 | 53.4. Extracting specific information from the log (exigrep) | |
562 | 53.5. Selecting messages by various criteria (exipick) | |
563 | 53.6. Cycling log files (exicyclog) | |
564 | 53.7. Mail statistics (eximstats) | |
565 | 53.8. Checking access policy (exim_checkaccess) | |
566 | 53.9. Making DBM files (exim_dbmbuild) | |
567 | 53.10. Finding individual retry times (exinext) | |
568 | 53.11. Hints database maintenance | |
569 | 53.12. exim_dumpdb | |
570 | 53.13. exim_tidydb | |
571 | 53.14. exim_fixdb | |
572 | 53.15. Mailbox maintenance (exim_lock) | |
573 | ||
574 | 54. The Exim monitor | |
575 | ||
576 | 54.1. Running the monitor | |
577 | 54.2. The stripcharts | |
578 | 54.3. Main action buttons | |
579 | 54.4. The log display | |
580 | 54.5. The queue display | |
581 | 54.6. The queue menu | |
582 | ||
583 | 55. Security considerations | |
584 | ||
585 | 55.1. Building a more "hardened" Exim | |
586 | 55.2. Root privilege | |
587 | 55.3. Running Exim without privilege | |
588 | 55.4. Delivering to local files | |
589 | 55.5. Running local commands | |
590 | 55.6. Trust in configuration data | |
591 | 55.7. IPv4 source routing | |
592 | 55.8. The VRFY, EXPN, and ETRN commands in SMTP | |
593 | 55.9. Privileged users | |
594 | 55.10. Spool files | |
595 | 55.11. Use of argv[0] | |
596 | 55.12. Use of %f formatting | |
597 | 55.13. Embedded Exim path | |
598 | 55.14. Dynamic module directory | |
599 | 55.15. Use of sprintf() | |
600 | 55.16. Use of debug_printf() and log_write() | |
601 | 55.17. Use of strcat() and strcpy() | |
602 | ||
603 | 56. Format of spool files | |
604 | ||
605 | 56.1. Format of the -H file | |
606 | ||
607 | 57. Support for DKIM (DomainKeys Identified Mail) | |
608 | ||
609 | 57.1. Signing outgoing messages | |
610 | 57.2. Verifying DKIM signatures in incoming mail | |
611 | ||
612 | 58. Proxies | |
613 | ||
614 | 58.1. Inbound proxies | |
615 | 58.2. Outbound proxies | |
616 | 58.3. Logging | |
617 | ||
618 | 59. Internationalisation | |
619 | ||
620 | 59.1. MTA operations | |
621 | 59.2. MDA operations | |
622 | ||
623 | 60. Events | |
624 | 61. Adding new drivers or lookup types | |
420a0d19 CE |
625 | |
626 | ||
627 | ||
628 | =============================================================================== | |
629 | 1. INTRODUCTION | |
630 | ||
631 | Exim is a mail transfer agent (MTA) for hosts that are running Unix or | |
632 | Unix-like operating systems. It was designed on the assumption that it would be | |
633 | run on hosts that are permanently connected to the Internet. However, it can be | |
634 | used on intermittently connected hosts with suitable configuration adjustments. | |
635 | ||
636 | Configuration files currently exist for the following operating systems: AIX, | |
637 | BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, GNU/ | |
638 | Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, | |
639 | OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, | |
640 | Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. | |
641 | Some of these operating systems are no longer current and cannot easily be | |
642 | tested, so the configuration files may no longer work in practice. | |
643 | ||
644 | There are also configuration files for compiling Exim in the Cygwin environment | |
645 | that can be installed on systems running Windows. However, this document does | |
646 | not contain any information about running Exim in the Cygwin environment. | |
647 | ||
648 | The terms and conditions for the use and distribution of Exim are contained in | |
649 | the file NOTICE. Exim is distributed under the terms of the GNU General Public | |
650 | Licence, a copy of which may be found in the file LICENCE. | |
651 | ||
652 | The use, supply or promotion of Exim for the purpose of sending bulk, | |
653 | unsolicited electronic mail is incompatible with the basic aims of the program, | |
654 | which revolve around the free provision of a service that enhances the quality | |
655 | of personal communications. The author of Exim regards indiscriminate | |
656 | mass-mailing as an antisocial, irresponsible abuse of the Internet. | |
657 | ||
658 | Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the | |
659 | experience of running and working on the Smail 3 code, I could never have | |
660 | contemplated starting to write a new MTA. Many of the ideas and user interfaces | |
661 | were originally taken from Smail 3, though the actual code of Exim is entirely | |
662 | new, and has developed far beyond the initial concept. | |
663 | ||
664 | Many people, both in Cambridge and around the world, have contributed to the | |
665 | development and the testing of Exim, and to porting it to various operating | |
666 | systems. I am grateful to them all. The distribution now contains a file called | |
667 | ACKNOWLEDGMENTS, in which I have started recording the names of contributors. | |
668 | ||
669 | ||
670 | 1.1 Exim documentation | |
671 | ---------------------- | |
672 | ||
2813c06e CE |
673 | This edition of the Exim specification applies to version 4.89 of Exim. |
674 | Substantive changes from the 4.88 edition are marked in some renditions of the | |
420a0d19 CE |
675 | document; this paragraph is so marked if the rendition is capable of showing a |
676 | change indicator. | |
677 | ||
678 | This document is very much a reference manual; it is not a tutorial. The reader | |
679 | is expected to have some familiarity with the SMTP mail transfer protocol and | |
680 | with general Unix system administration. Although there are some discussions | |
681 | and examples in places, the information is mostly organized in a way that makes | |
682 | it easy to look up, rather than in a natural order for sequential reading. | |
683 | Furthermore, the manual aims to cover every aspect of Exim in detail, including | |
684 | a number of rarely-used, special-purpose features that are unlikely to be of | |
685 | very wide interest. | |
686 | ||
687 | An "easier" discussion of Exim which provides more in-depth explanatory, | |
688 | introductory, and tutorial material can be found in a book entitled The Exim | |
689 | SMTP Mail Server (second edition, 2007), published by UIT Cambridge (http:// | |
690 | www.uit.co.uk/exim-book/). | |
691 | ||
692 | This book also contains a chapter that gives a general introduction to SMTP and | |
693 | Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date | |
694 | with the latest release of Exim. (Note that the earlier book about Exim, | |
695 | published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) | |
696 | ||
697 | If you are using a Debian distribution of Exim, you will find information about | |
698 | Debian-specific features in the file /usr/share/doc/exim4-base/README.Debian. | |
699 | The command man update-exim.conf is another source of Debian-specific | |
700 | information. | |
701 | ||
702 | As the program develops, there may be features in newer versions that have not | |
703 | yet made it into this document, which is updated only when the most significant | |
704 | digit of the fractional part of the version number changes. Specifications of | |
705 | new features that are not yet in this manual are placed in the file doc/ | |
706 | NewStuff in the Exim distribution. | |
707 | ||
708 | Some features may be classified as "experimental". These may change | |
709 | incompatibly while they are developing, or even be withdrawn. For this reason, | |
710 | they are not documented in this manual. Information about experimental features | |
711 | can be found in the file doc/experimental.txt. | |
712 | ||
713 | All changes to the program (whether new features, bug fixes, or other kinds of | |
714 | change) are noted briefly in the file called doc/ChangeLog. | |
715 | ||
716 | This specification itself is available as an ASCII file in doc/spec.txt so that | |
717 | it can easily be searched with a text editor. Other files in the doc directory | |
718 | are: | |
719 | ||
720 | OptionLists.txt list of all options in alphabetical order | |
721 | dbm.discuss.txt discussion about DBM libraries | |
722 | exim.8 a man page of Exim's command line options | |
723 | experimental.txt documentation of experimental features | |
724 | filter.txt specification of the filter language | |
725 | Exim3.upgrade upgrade notes from release 2 to release 3 | |
726 | Exim4.upgrade upgrade notes from release 3 to release 4 | |
2813c06e | 727 | openssl.txt installing a current OpenSSL release |
420a0d19 CE |
728 | |
729 | The main specification and the specification of the filtering language are also | |
730 | available in other formats (HTML, PostScript, PDF, and Texinfo). Section 1.6 | |
731 | below tells you how to get hold of these. | |
732 | ||
733 | ||
734 | 1.2 FTP and web sites | |
735 | --------------------- | |
736 | ||
737 | The primary site for Exim source distributions is currently the University of | |
738 | Cambridge's FTP site, whose contents are described in Where to find the Exim | |
739 | distribution below. In addition, there is a web site and an FTP site at | |
740 | exim.org. These are now also hosted at the University of Cambridge. The | |
741 | exim.org site was previously hosted for a number of years by Energis Squared, | |
742 | formerly Planet Online Ltd, whose support I gratefully acknowledge. | |
743 | ||
744 | As well as Exim distribution tar files, the Exim web site contains a number of | |
745 | differently formatted versions of the documentation. A recent addition to the | |
746 | online information is the Exim wiki (http://wiki.exim.org), which contains what | |
747 | used to be a separate FAQ, as well as various other examples, tips, and | |
748 | know-how that have been contributed by Exim users. | |
749 | ||
750 | An Exim Bugzilla exists at http://bugs.exim.org. You can use this to report | |
751 | bugs, and also to add items to the wish list. Please search first to check that | |
752 | you are not duplicating a previous entry. | |
753 | ||
754 | ||
755 | 1.3 Mailing lists | |
756 | ----------------- | |
757 | ||
758 | The following Exim mailing lists exist: | |
759 | ||
760 | exim-announce@exim.org Moderated, low volume announcements list | |
761 | exim-users@exim.org General discussion list | |
762 | exim-dev@exim.org Discussion of bugs, enhancements, etc. | |
763 | exim-cvs@exim.org Automated commit messages from the VCS | |
764 | ||
765 | You can subscribe to these lists, change your existing subscriptions, and view | |
766 | or search the archives via the mailing lists link on the Exim home page. If you | |
767 | are using a Debian distribution of Exim, you may wish to subscribe to the | |
768 | Debian-specific mailing list pkg-exim4-users@lists.alioth.debian.org via this | |
769 | web page: | |
770 | ||
771 | http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users | |
772 | ||
773 | Please ask Debian-specific questions on this list and not on the general Exim | |
774 | lists. | |
775 | ||
776 | ||
777 | 1.4 Exim training | |
778 | ----------------- | |
779 | ||
780 | Training courses in Cambridge (UK) used to be run annually by the author of | |
781 | Exim, before he retired. At the time of writing, there are no plans to run | |
782 | further Exim courses in Cambridge. However, if that changes, relevant | |
783 | information will be posted at http://www-tus.csx.cam.ac.uk/courses/exim/. | |
784 | ||
785 | ||
786 | 1.5 Bug reports | |
787 | --------------- | |
788 | ||
789 | Reports of obvious bugs can be emailed to bugs@exim.org or reported via the | |
790 | Bugzilla (http://bugs.exim.org). However, if you are unsure whether some | |
791 | behaviour is a bug or not, the best thing to do is to post a message to the | |
792 | exim-dev mailing list and have it discussed. | |
793 | ||
794 | ||
795 | 1.6 Where to find the Exim distribution | |
796 | --------------------------------------- | |
797 | ||
798 | The master ftp site for the Exim distribution is | |
799 | ||
800 | ftp://ftp.csx.cam.ac.uk/pub/software/email/exim | |
801 | ||
802 | This is mirrored by | |
803 | ||
804 | ftp://ftp.exim.org/pub/exim | |
805 | ||
806 | The file references that follow are relative to the exim directories at these | |
807 | sites. There are now quite a number of independent mirror sites around the | |
808 | world. Those that I know about are listed in the file called Mirrors. | |
809 | ||
810 | Within the exim directory there are subdirectories called exim3 (for previous | |
811 | Exim 3 distributions), exim4 (for the latest Exim 4 distributions), and Testing | |
812 | for testing versions. In the exim4 subdirectory, the current release can always | |
813 | be found in files called | |
814 | ||
815 | exim-n.nn.tar.gz | |
816 | exim-n.nn.tar.bz2 | |
817 | ||
818 | where n.nn is the highest such version number in the directory. The two files | |
819 | contain identical data; the only difference is the type of compression. The | |
820 | .bz2 file is usually a lot smaller than the .gz file. | |
821 | ||
822 | The distributions will be PGP signed by an individual key of the Release | |
823 | Coordinator. This key will have a uid containing an email address in the | |
824 | exim.org domain and will have signatures from other people, including other | |
825 | Exim maintainers. We expect that the key will be in the "strong set" of PGP | |
826 | keys. There should be a trust path to that key from Nigel Metheringham's PGP | |
827 | key, a version of which can be found in the release directory in the file | |
828 | nigel-pubkey.asc. All keys used will be available in public keyserver pools, | |
829 | such as pool.sks-keyservers.net. | |
830 | ||
831 | At time of last update, releases were being made by Phil Pennock and signed | |
832 | with key 0x403043153903637F, although that key is expected to be replaced in | |
833 | 2013. A trust path from Nigel's key to Phil's can be observed at https:// | |
834 | www.security.spodhuis.org/exim-trustpath. | |
835 | ||
836 | Releases have also been authorized to be performed by Todd Lyons who signs with | |
837 | key 0xC4F4F94804D29EBA. A direct trust path exists between previous RE Phil | |
838 | Pennock and Todd Lyons through a common associate. | |
839 | ||
840 | The signatures for the tar bundles are in: | |
841 | ||
842 | exim-n.nn.tar.gz.asc | |
843 | exim-n.nn.tar.bz2.asc | |
844 | ||
845 | For each released version, the log of changes is made separately available in a | |
846 | separate file in the directory ChangeLogs so that it is possible to find out | |
847 | what has changed without having to download the entire distribution. | |
848 | ||
849 | The main distribution contains ASCII versions of this specification and other | |
850 | documentation; other formats of the documents are available in separate files | |
851 | inside the exim4 directory of the FTP site: | |
852 | ||
853 | exim-html-n.nn.tar.gz | |
854 | exim-pdf-n.nn.tar.gz | |
855 | exim-postscript-n.nn.tar.gz | |
856 | exim-texinfo-n.nn.tar.gz | |
857 | ||
858 | These tar files contain only the doc directory, not the complete distribution, | |
859 | and are also available in .bz2 as well as .gz forms. | |
860 | ||
861 | ||
862 | 1.7 Limitations | |
863 | --------------- | |
864 | ||
865 | * Exim is designed for use as an Internet MTA, and therefore handles | |
866 | addresses in RFC 2822 domain format only. It cannot handle UUCP "bang | |
867 | paths", though simple two-component bang paths can be converted by a | |
868 | straightforward rewriting configuration. This restriction does not prevent | |
869 | Exim from being interfaced to UUCP as a transport mechanism, provided that | |
870 | domain addresses are used. | |
871 | ||
872 | * Exim insists that every address it handles has a domain attached. For | |
873 | incoming local messages, domainless addresses are automatically qualified | |
874 | with a configured domain value. Configuration options specify from which | |
875 | remote systems unqualified addresses are acceptable. These are then | |
876 | qualified on arrival. | |
877 | ||
878 | * The only external transport mechanisms that are currently implemented are | |
879 | SMTP and LMTP over a TCP/IP network (including support for IPv6). However, | |
880 | a pipe transport is available, and there are facilities for writing | |
881 | messages to files and pipes, optionally in batched SMTP format; these | |
882 | facilities can be used to send messages to other transport mechanisms such | |
883 | as UUCP, provided they can handle domain-style addresses. Batched SMTP | |
884 | input is also catered for. | |
885 | ||
886 | * Exim is not designed for storing mail for dial-in hosts. When the volumes | |
887 | of such mail are large, it is better to get the messages "delivered" into | |
888 | files (that is, off Exim's queue) and subsequently passed on to the dial-in | |
889 | hosts by other means. | |
890 | ||
891 | * Although Exim does have basic facilities for scanning incoming messages, | |
892 | these are not comprehensive enough to do full virus or spam scanning. Such | |
893 | operations are best carried out using additional specialized software | |
894 | packages. If you compile Exim with the content-scanning extension, | |
895 | straightforward interfaces to a number of common scanners are provided. | |
896 | ||
897 | ||
898 | 1.8 Run time configuration | |
899 | -------------------------- | |
900 | ||
901 | Exim's run time configuration is held in a single text file that is divided | |
902 | into a number of sections. The entries in this file consist of keywords and | |
903 | values, in the style of Smail 3 configuration files. A default configuration | |
904 | file which is suitable for simple online installations is provided in the | |
905 | distribution, and is described in chapter 7 below. | |
906 | ||
907 | ||
908 | 1.9 Calling interface | |
909 | --------------------- | |
910 | ||
911 | Like many MTAs, Exim has adopted the Sendmail command line interface so that it | |
912 | can be a straight replacement for /usr/lib/sendmail or /usr/sbin/sendmail when | |
913 | sending mail, but you do not need to know anything about Sendmail in order to | |
914 | run Exim. For actions other than sending messages, Sendmail-compatible options | |
915 | also exist, but those that produce output (for example, -bp, which lists the | |
916 | messages on the queue) do so in Exim's own format. There are also some | |
917 | additional options that are compatible with Smail 3, and some further options | |
918 | that are new to Exim. Chapter 5 documents all Exim's command line options. This | |
919 | information is automatically made into the man page that forms part of the Exim | |
920 | distribution. | |
921 | ||
922 | Control of messages on the queue can be done via certain privileged command | |
923 | line options. There is also an optional monitor program called eximon, which | |
924 | displays current information in an X window, and which contains a menu | |
925 | interface to Exim's command line administration options. | |
926 | ||
927 | ||
928 | 1.10 Terminology | |
929 | ---------------- | |
930 | ||
931 | The body of a message is the actual data that the sender wants to transmit. It | |
932 | is the last part of a message, and is separated from the header (see below) by | |
933 | a blank line. | |
934 | ||
935 | When a message cannot be delivered, it is normally returned to the sender in a | |
936 | delivery failure message or a "non-delivery report" (NDR). The term bounce is | |
937 | commonly used for this action, and the error reports are often called bounce | |
938 | messages. This is a convenient shorthand for "delivery failure error report". | |
939 | Such messages have an empty sender address in the message's envelope (see | |
940 | below) to ensure that they cannot themselves give rise to further bounce | |
941 | messages. | |
942 | ||
943 | The term default appears frequently in this manual. It is used to qualify a | |
944 | value which is used in the absence of any setting in the configuration. It may | |
945 | also qualify an action which is taken unless a configuration setting specifies | |
946 | otherwise. | |
947 | ||
948 | The term defer is used when the delivery of a message to a specific destination | |
949 | cannot immediately take place for some reason (a remote host may be down, or a | |
950 | user's local mailbox may be full). Such deliveries are deferred until a later | |
951 | time. | |
952 | ||
953 | The word domain is sometimes used to mean all but the first component of a | |
954 | host's name. It is not used in that sense here, where it normally refers to the | |
955 | part of an email address following the @ sign. | |
956 | ||
957 | A message in transit has an associated envelope, as well as a header and a | |
958 | body. The envelope contains a sender address (to which bounce messages should | |
959 | be delivered), and any number of recipient addresses. References to the sender | |
960 | or the recipients of a message usually mean the addresses in the envelope. An | |
961 | MTA uses these addresses for delivery, and for returning bounce messages, not | |
962 | the addresses that appear in the header lines. | |
963 | ||
964 | The header of a message is the first part of a message's text, consisting of a | |
965 | number of lines, each of which has a name such as From:, To:, Subject:, etc. | |
966 | Long header lines can be split over several text lines by indenting the | |
967 | continuations. The header is separated from the body by a blank line. | |
968 | ||
969 | The term local part, which is taken from RFC 2822, is used to refer to that | |
970 | part of an email address that precedes the @ sign. The part that follows the @ | |
971 | sign is called the domain or mail domain. | |
972 | ||
973 | The terms local delivery and remote delivery are used to distinguish delivery | |
974 | to a file or a pipe on the local host from delivery by SMTP over TCP/IP to | |
975 | another host. As far as Exim is concerned, all hosts other than the host it is | |
976 | running on are remote. | |
977 | ||
978 | Return path is another name that is used for the sender address in a message's | |
979 | envelope. | |
980 | ||
981 | The term queue is used to refer to the set of messages awaiting delivery, | |
982 | because this term is in widespread use in the context of MTAs. However, in | |
983 | Exim's case the reality is more like a pool than a queue, because there is | |
984 | normally no ordering of waiting messages. | |
985 | ||
986 | The term queue runner is used to describe a process that scans the queue and | |
987 | attempts to deliver those messages whose retry times have come. This term is | |
988 | used by other MTAs, and also relates to the command runq, but in Exim the | |
989 | waiting messages are normally processed in an unpredictable order. | |
990 | ||
991 | The term spool directory is used for a directory in which Exim keeps the | |
992 | messages on its queue - that is, those that it is in the process of delivering. | |
993 | This should not be confused with the directory in which local mailboxes are | |
994 | stored, which is called a "spool directory" by some people. In the Exim | |
995 | documentation, "spool" is always used in the first sense. | |
996 | ||
997 | ||
998 | ||
999 | =============================================================================== | |
1000 | 2. INCORPORATED CODE | |
1001 | ||
1002 | A number of pieces of external code are included in the Exim distribution. | |
1003 | ||
1004 | * Regular expressions are supported in the main Exim program and in the Exim | |
1005 | monitor using the freely-distributable PCRE library, copyright (c) | |
1006 | University of Cambridge. The source to PCRE is no longer shipped with Exim, | |
1007 | so you will need to use the version of PCRE shipped with your system, or | |
1008 | obtain and install the full version of the library from ftp:// | |
1009 | ftp.csx.cam.ac.uk/pub/software/programming/pcre. | |
1010 | ||
1011 | * Support for the cdb (Constant DataBase) lookup method is provided by code | |
1012 | contributed by Nigel Metheringham of (at the time he contributed it) Planet | |
1013 | Online Ltd. The implementation is completely contained within the code of | |
1014 | Exim. It does not link against an external cdb library. The code contains | |
1015 | the following statements: | |
1016 | ||
1017 | Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd | |
1018 | ||
1019 | This program is free software; you can redistribute it and/or modify it | |
1020 | under the terms of the GNU General Public License as published by the | |
1021 | Free Software Foundation; either version 2 of the License, or (at your | |
1022 | option) any later version. This code implements Dan Bernstein's | |
1023 | Constant DataBase (cdb) spec. Information, the spec and sample code for | |
1024 | cdb can be obtained from http://www.pobox.com/~djb/cdb.html. This | |
1025 | implementation borrows some code from Dan Bernstein's implementation | |
1026 | (which has no license restrictions applied to it). | |
1027 | ||
1028 | * Client support for Microsoft's Secure Password Authentication is provided | |
1029 | by code contributed by Marc Prud'hommeaux. Server support was contributed | |
1030 | by Tom Kistner. This includes code taken from the Samba project, which is | |
1031 | released under the Gnu GPL. | |
1032 | ||
1033 | * Support for calling the Cyrus pwcheck and saslauthd daemons is provided by | |
1034 | code taken from the Cyrus-SASL library and adapted by Alexander S. | |
1035 | Sabourenkov. The permission notice appears below, in accordance with the | |
1036 | conditions expressed therein. | |
1037 | ||
1038 | Copyright (c) 2001 Carnegie Mellon University. All rights reserved. | |
1039 | ||
1040 | Redistribution and use in source and binary forms, with or without | |
1041 | modification, are permitted provided that the following conditions are | |
1042 | met: | |
1043 | ||
1044 | 1. Redistributions of source code must retain the above copyright | |
1045 | notice, this list of conditions and the following disclaimer. | |
1046 | ||
1047 | 2. Redistributions in binary form must reproduce the above copyright | |
1048 | notice, this list of conditions and the following disclaimer in the | |
1049 | documentation and/or other materials provided with the | |
1050 | distribution. | |
1051 | ||
1052 | 3. The name "Carnegie Mellon University" must not be used to endorse | |
1053 | or promote products derived from this software without prior | |
1054 | written permission. For permission or any other legal details, | |
1055 | please contact | |
1056 | ||
1057 | Office of Technology Transfer | |
1058 | Carnegie Mellon University | |
1059 | 5000 Forbes Avenue | |
1060 | Pittsburgh, PA 15213-3890 | |
1061 | (412) 268-4387, fax: (412) 268-7395 | |
1062 | tech-transfer@andrew.cmu.edu | |
1063 | ||
1064 | 4. Redistributions of any form whatsoever must retain the following | |
1065 | acknowledgment: | |
1066 | ||
1067 | "This product includes software developed by Computing Services at | |
1068 | Carnegie Mellon University (http://www.cmu.edu/computing/." | |
1069 | ||
1070 | CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO | |
1071 | THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY | |
1072 | AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE | |
1073 | FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
1074 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN | |
1075 | AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING | |
1076 | OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS | |
1077 | SOFTWARE. | |
1078 | ||
1079 | * The Exim Monitor program, which is an X-Window application, includes | |
1080 | modified versions of the Athena StripChart and TextPop widgets. This code | |
1081 | is copyright by DEC and MIT, and their permission notice appears below, in | |
1082 | accordance with the conditions expressed therein. | |
1083 | ||
1084 | Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, | |
1085 | Massachusetts, and the Massachusetts Institute of Technology, | |
1086 | Cambridge, Massachusetts. | |
1087 | ||
1088 | All Rights Reserved | |
1089 | ||
1090 | Permission to use, copy, modify, and distribute this software and its | |
1091 | documentation for any purpose and without fee is hereby granted, | |
1092 | provided that the above copyright notice appear in all copies and that | |
1093 | both that copyright notice and this permission notice appear in | |
1094 | supporting documentation, and that the names of Digital or MIT not be | |
1095 | used in advertising or publicity pertaining to distribution of the | |
1096 | software without specific, written prior permission. | |
1097 | ||
1098 | DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, | |
1099 | INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO | |
1100 | EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR | |
1101 | CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF | |
1102 | USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR | |
1103 | OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR | |
1104 | PERFORMANCE OF THIS SOFTWARE. | |
1105 | ||
1106 | * The DMARC implementation uses the OpenDMARC library which is Copyrighted by | |
1107 | The Trusted Domain Project. Portions of Exim source which use OpenDMARC | |
1108 | derived code are indicated in the respective source files. The full | |
1109 | OpenDMARC license is provided in the LICENSE.opendmarc file contained in | |
1110 | the distributed source code. | |
1111 | ||
1112 | * Many people have contributed code fragments, some large, some small, that | |
1113 | were not covered by any specific licence requirements. It is assumed that | |
1114 | the contributors are happy to see their code incorporated into Exim under | |
1115 | the GPL. | |
1116 | ||
1117 | ||
1118 | ||
1119 | =============================================================================== | |
1120 | 3. HOW EXIM RECEIVES AND DELIVERS MAIL | |
1121 | ||
1122 | ||
1123 | 3.1 Overall philosophy | |
1124 | ---------------------- | |
1125 | ||
1126 | Exim is designed to work efficiently on systems that are permanently connected | |
1127 | to the Internet and are handling a general mix of mail. In such circumstances, | |
1128 | most messages can be delivered immediately. Consequently, Exim does not | |
1129 | maintain independent queues of messages for specific domains or hosts, though | |
1130 | it does try to send several messages in a single SMTP connection after a host | |
1131 | has been down, and it also maintains per-host retry information. | |
1132 | ||
1133 | ||
1134 | 3.2 Policy control | |
1135 | ------------------ | |
1136 | ||
1137 | Policy controls are now an important feature of MTAs that are connected to the | |
1138 | Internet. Perhaps their most important job is to stop MTAs being abused as | |
1139 | "open relays" by misguided individuals who send out vast amounts of unsolicited | |
1140 | junk, and want to disguise its source. Exim provides flexible facilities for | |
1141 | specifying policy controls on incoming mail: | |
1142 | ||
1143 | * Exim 4 (unlike previous versions of Exim) implements policy controls on | |
1144 | incoming mail by means of Access Control Lists (ACLs). Each list is a | |
1145 | series of statements that may either grant or deny access. ACLs can be used | |
1146 | at several places in the SMTP dialogue while receiving a message from a | |
1147 | remote host. However, the most common places are after each RCPT command, | |
1148 | and at the very end of the message. The sysadmin can specify conditions for | |
1149 | accepting or rejecting individual recipients or the entire message, | |
2813c06e | 1150 | respectively, at these two points (see chapter 43). Denial of access |
420a0d19 CE |
1151 | results in an SMTP error code. |
1152 | ||
1153 | * An ACL is also available for locally generated, non-SMTP messages. In this | |
1154 | case, the only available actions are to accept or deny the entire message. | |
1155 | ||
1156 | * When Exim is compiled with the content-scanning extension, facilities are | |
1157 | provided in the ACL mechanism for passing the message to external virus and | |
1158 | /or spam scanning software. The result of such a scan is passed back to the | |
1159 | ACL, which can then use it to decide what to do with the message. | |
1160 | ||
1161 | * When a message has been received, either from a remote host or from the | |
1162 | local host, but before the final acknowledgment has been sent, a locally | |
1163 | supplied C function called local_scan() can be run to inspect the message | |
2813c06e | 1164 | and decide whether to accept it or not (see chapter 45). If the message is |
420a0d19 CE |
1165 | accepted, the list of recipients can be modified by the function. |
1166 | ||
1167 | * Using the local_scan() mechanism is another way of calling external scanner | |
1168 | software. The SA-Exim add-on package works this way. It does not require | |
1169 | Exim to be compiled with the content-scanning extension. | |
1170 | ||
1171 | * After a message has been accepted, a further checking mechanism is | |
2813c06e | 1172 | available in the form of the system filter (see chapter 46). This runs at |
420a0d19 CE |
1173 | the start of every delivery process. |
1174 | ||
1175 | ||
1176 | 3.3 User filters | |
1177 | ---------------- | |
1178 | ||
1179 | In a conventional Exim configuration, users are able to run private filters by | |
1180 | setting up appropriate .forward files in their home directories. See chapter 22 | |
1181 | (about the redirect router) for the configuration needed to support this, and | |
1182 | the separate document entitled Exim's interfaces to mail filtering for user | |
1183 | details. Two different kinds of filtering are available: | |
1184 | ||
1185 | * Sieve filters are written in the standard filtering language that is | |
1186 | defined by RFC 3028. | |
1187 | ||
1188 | * Exim filters are written in a syntax that is unique to Exim, but which is | |
1189 | more powerful than Sieve, which it pre-dates. | |
1190 | ||
1191 | User filters are run as part of the routing process, described below. | |
1192 | ||
1193 | ||
1194 | 3.4 Message identification | |
1195 | -------------------------- | |
1196 | ||
1197 | Every message handled by Exim is given a message id which is sixteen characters | |
1198 | long. It is divided into three parts, separated by hyphens, for example | |
1199 | "16VDhn-0001bo-D3". Each part is a sequence of letters and digits, normally | |
1200 | encoding numbers in base 62. However, in the Darwin operating system (Mac OS X) | |
1201 | and when Exim is compiled to run under Cygwin, base 36 (avoiding the use of | |
1202 | lower case letters) is used instead, because the message id is used to | |
1203 | construct file names, and the names of files in those systems are not always | |
1204 | case-sensitive. | |
1205 | ||
1206 | The detail of the contents of the message id have changed as Exim has evolved. | |
1207 | Earlier versions relied on the operating system not re-using a process id (pid) | |
1208 | within one second. On modern operating systems, this assumption can no longer | |
1209 | be made, so the algorithm had to be changed. To retain backward compatibility, | |
1210 | the format of the message id was retained, which is why the following rules are | |
1211 | somewhat eccentric: | |
1212 | ||
1213 | * The first six characters of the message id are the time at which the | |
1214 | message started to be received, to a granularity of one second. That is, | |
1215 | this field contains the number of seconds since the start of the epoch (the | |
1216 | normal Unix way of representing the date and time of day). | |
1217 | ||
1218 | * After the first hyphen, the next six characters are the id of the process | |
1219 | that received the message. | |
1220 | ||
1221 | * There are two different possibilities for the final two characters: | |
1222 | ||
1223 | 1. If localhost_number is not set, this value is the fractional part of | |
1224 | the time of reception, normally in units of 1/2000 of a second, but for | |
1225 | systems that must use base 36 instead of base 62 (because of | |
1226 | case-insensitive file systems), the units are 1/1000 of a second. | |
1227 | ||
1228 | 2. If localhost_number is set, it is multiplied by 200 (100) and added to | |
1229 | the fractional part of the time, which in this case is in units of 1/ | |
1230 | 200 (1/100) of a second. | |
1231 | ||
1232 | After a message has been received, Exim waits for the clock to tick at the | |
1233 | appropriate resolution before proceeding, so that if another message is | |
1234 | received by the same process, or by another process with the same (re-used) | |
1235 | pid, it is guaranteed that the time will be different. In most cases, the clock | |
1236 | will already have ticked while the message was being received. | |
1237 | ||
1238 | ||
1239 | 3.5 Receiving mail | |
1240 | ------------------ | |
1241 | ||
1242 | The only way Exim can receive mail from another host is using SMTP over TCP/IP, | |
1243 | in which case the sender and recipient addresses are transferred using SMTP | |
1244 | commands. However, from a locally running process (such as a user's MUA), there | |
1245 | are several possibilities: | |
1246 | ||
1247 | * If the process runs Exim with the -bm option, the message is read | |
1248 | non-interactively (usually via a pipe), with the recipients taken from the | |
1249 | command line, or from the body of the message if -t is also used. | |
1250 | ||
1251 | * If the process runs Exim with the -bS option, the message is also read | |
1252 | non-interactively, but in this case the recipients are listed at the start | |
1253 | of the message in a series of SMTP RCPT commands, terminated by a DATA | |
1254 | command. This is so-called "batch SMTP" format, but it isn't really SMTP. | |
1255 | The SMTP commands are just another way of passing envelope addresses in a | |
1256 | non-interactive submission. | |
1257 | ||
1258 | * If the process runs Exim with the -bs option, the message is read | |
1259 | interactively, using the SMTP protocol. A two-way pipe is normally used for | |
1260 | passing data between the local process and the Exim process. This is "real" | |
1261 | SMTP and is handled in the same way as SMTP over TCP/IP. For example, the | |
1262 | ACLs for SMTP commands are used for this form of submission. | |
1263 | ||
1264 | * A local process may also make a TCP/IP call to the host's loopback address | |
1265 | (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim | |
1266 | does not treat the loopback address specially. It treats all such | |
1267 | connections in the same way as connections from other hosts. | |
1268 | ||
1269 | In the three cases that do not involve TCP/IP, the sender address is | |
1270 | constructed from the login name of the user that called Exim and a default | |
1271 | qualification domain (which can be set by the qualify_domain configuration | |
1272 | option). For local or batch SMTP, a sender address that is passed using the | |
1273 | SMTP MAIL command is ignored. However, the system administrator may allow | |
1274 | certain users ("trusted users") to specify a different sender address | |
1275 | unconditionally, or all users to specify certain forms of different sender | |
1276 | address. The -f option or the SMTP MAIL command is used to specify these | |
1277 | different addresses. See section 5.2 for details of trusted users, and the | |
1278 | untrusted_set_sender option for a way of allowing untrusted users to change | |
1279 | sender addresses. | |
1280 | ||
1281 | Messages received by either of the non-interactive mechanisms are subject to | |
1282 | checking by the non-SMTP ACL, if one is defined. Messages received using SMTP | |
1283 | (either over TCP/IP, or interacting with a local process) can be checked by a | |
1284 | number of ACLs that operate at different times during the SMTP session. Either | |
1285 | individual recipients, or the entire message, can be rejected if local policy | |
2813c06e | 1286 | requirements are not met. The local_scan() function (see chapter 45) is run for |
420a0d19 CE |
1287 | all incoming messages. |
1288 | ||
1289 | Exim can be configured not to start a delivery process when a message is | |
1290 | received; this can be unconditional, or depend on the number of incoming SMTP | |
1291 | connections or the system load. In these situations, new messages wait on the | |
1292 | queue until a queue runner process picks them up. However, in standard | |
1293 | configurations under normal conditions, delivery is started as soon as a | |
1294 | message is received. | |
1295 | ||
1296 | ||
1297 | 3.6 Handling an incoming message | |
1298 | -------------------------------- | |
1299 | ||
1300 | When Exim accepts a message, it writes two files in its spool directory. The | |
1301 | first contains the envelope information, the current status of the message, and | |
1302 | the header lines, and the second contains the body of the message. The names of | |
1303 | the two spool files consist of the message id, followed by "-H" for the file | |
1304 | containing the envelope and header, and "-D" for the data file. | |
1305 | ||
1306 | By default all these message files are held in a single directory called input | |
1307 | inside the general Exim spool directory. Some operating systems do not perform | |
1308 | very well if the number of files in a directory gets large; to improve | |
1309 | performance in such cases, the split_spool_directory option can be used. This | |
1310 | causes Exim to split up the input files into 62 sub-directories whose names are | |
1311 | single letters or digits. When this is done, the queue is processed one | |
1312 | sub-directory at a time instead of all at once, which can improve overall | |
1313 | performance even when there are not enough files in each directory to affect | |
1314 | file system performance. | |
1315 | ||
1316 | The envelope information consists of the address of the message's sender and | |
1317 | the addresses of the recipients. This information is entirely separate from any | |
1318 | addresses contained in the header lines. The status of the message includes a | |
1319 | list of recipients who have already received the message. The format of the | |
2813c06e | 1320 | first spool file is described in chapter 56. |
420a0d19 CE |
1321 | |
1322 | Address rewriting that is specified in the rewrite section of the configuration | |
1323 | (see chapter 31) is done once and for all on incoming addresses, both in the | |
1324 | header lines and the envelope, at the time the message is accepted. If during | |
1325 | the course of delivery additional addresses are generated (for example, via | |
1326 | aliasing), these new addresses are rewritten as soon as they are generated. At | |
1327 | the time a message is actually delivered (transported) further rewriting can | |
1328 | take place; because this is a transport option, it can be different for | |
1329 | different forms of delivery. It is also possible to specify the addition or | |
1330 | removal of certain header lines at the time the message is delivered (see | |
1331 | chapters 15 and 24). | |
1332 | ||
1333 | ||
1334 | 3.7 Life of a message | |
1335 | --------------------- | |
1336 | ||
1337 | A message remains in the spool directory until it is completely delivered to | |
1338 | its recipients or to an error address, or until it is deleted by an | |
1339 | administrator or by the user who originally created it. In cases when delivery | |
1340 | cannot proceed - for example, when a message can neither be delivered to its | |
1341 | recipients nor returned to its sender, the message is marked "frozen" on the | |
1342 | spool, and no more deliveries are attempted. | |
1343 | ||
1344 | An administrator can "thaw" such messages when the problem has been corrected, | |
1345 | and can also freeze individual messages by hand if necessary. In addition, an | |
1346 | administrator can force a delivery error, causing a bounce message to be sent. | |
1347 | ||
1348 | There are options called ignore_bounce_errors_after and timeout_frozen_after, | |
1349 | which discard frozen messages after a certain time. The first applies only to | |
1350 | frozen bounces, the second to any frozen messages. | |
1351 | ||
1352 | While Exim is working on a message, it writes information about each delivery | |
1353 | attempt to its main log file. This includes successful, unsuccessful, and | |
2813c06e | 1354 | delayed deliveries for each recipient (see chapter 52). The log lines are also |
420a0d19 CE |
1355 | written to a separate message log file for each message. These logs are solely |
1356 | for the benefit of the administrator, and are normally deleted along with the | |
1357 | spool files when processing of a message is complete. The use of individual | |
1358 | message logs can be disabled by setting no_message_logs; this might give an | |
1359 | improvement in performance on very busy systems. | |
1360 | ||
1361 | All the information Exim itself needs to set up a delivery is kept in the first | |
1362 | spool file, along with the header lines. When a successful delivery occurs, the | |
1363 | address is immediately written at the end of a journal file, whose name is the | |
1364 | message id followed by "-J". At the end of a delivery run, if there are some | |
1365 | addresses left to be tried again later, the first spool file (the "-H" file) is | |
1366 | updated to indicate which these are, and the journal file is then deleted. | |
1367 | Updating the spool file is done by writing a new file and renaming it, to | |
1368 | minimize the possibility of data loss. | |
1369 | ||
1370 | Should the system or the program crash after a successful delivery but before | |
1371 | the spool file has been updated, the journal is left lying around. The next | |
1372 | time Exim attempts to deliver the message, it reads the journal file and | |
1373 | updates the spool file before proceeding. This minimizes the chances of double | |
1374 | deliveries caused by crashes. | |
1375 | ||
1376 | ||
1377 | 3.8 Processing an address for delivery | |
1378 | -------------------------------------- | |
1379 | ||
1380 | The main delivery processing elements of Exim are called routers and transports | |
1381 | , and collectively these are known as drivers. Code for a number of them is | |
1382 | provided in the source distribution, and compile-time options specify which | |
1383 | ones are included in the binary. Run time options specify which ones are | |
1384 | actually used for delivering messages. | |
1385 | ||
1386 | Each driver that is specified in the run time configuration is an instance of | |
1387 | that particular driver type. Multiple instances are allowed; for example, you | |
1388 | can set up several different smtp transports, each with different option values | |
1389 | that might specify different ports or different timeouts. Each instance has its | |
1390 | own identifying name. In what follows we will normally use the instance name | |
1391 | when discussing one particular instance (that is, one specific configuration of | |
1392 | the driver), and the generic driver name when discussing the driver's features | |
1393 | in general. | |
1394 | ||
1395 | A router is a driver that operates on an address, either determining how its | |
1396 | delivery should happen, by assigning it to a specific transport, or converting | |
1397 | the address into one or more new addresses (for example, via an alias file). A | |
1398 | router may also explicitly choose to fail an address, causing it to be bounced. | |
1399 | ||
1400 | A transport is a driver that transmits a copy of the message from Exim's spool | |
1401 | to some destination. There are two kinds of transport: for a local transport, | |
1402 | the destination is a file or a pipe on the local host, whereas for a remote | |
1403 | transport the destination is some other host. A message is passed to a specific | |
1404 | transport as a result of successful routing. If a message has several | |
1405 | recipients, it may be passed to a number of different transports. | |
1406 | ||
1407 | An address is processed by passing it to each configured router instance in | |
1408 | turn, subject to certain preconditions, until a router accepts the address or | |
1409 | specifies that it should be bounced. We will describe this process in more | |
1410 | detail shortly. First, as a simple example, we consider how each recipient | |
1411 | address in a message is processed in a small configuration of three routers. | |
1412 | ||
1413 | To make this a more concrete example, it is described in terms of some actual | |
1414 | routers, but remember, this is only an example. You can configure Exim's | |
1415 | routers in many different ways, and there may be any number of routers in a | |
1416 | configuration. | |
1417 | ||
1418 | The first router that is specified in a configuration is often one that handles | |
1419 | addresses in domains that are not recognized specially by the local host. These | |
1420 | are typically addresses for arbitrary domains on the Internet. A precondition | |
1421 | is set up which looks for the special domains known to the host (for example, | |
1422 | its own domain name), and the router is run for addresses that do not match. | |
1423 | Typically, this is a router that looks up domains in the DNS in order to find | |
1424 | the hosts to which this address routes. If it succeeds, the address is assigned | |
1425 | to a suitable SMTP transport; if it does not succeed, the router is configured | |
1426 | to fail the address. | |
1427 | ||
1428 | The second router is reached only when the domain is recognized as one that | |
1429 | "belongs" to the local host. This router does redirection - also known as | |
1430 | aliasing and forwarding. When it generates one or more new addresses from the | |
1431 | original, each of them is routed independently from the start. Otherwise, the | |
1432 | router may cause an address to fail, or it may simply decline to handle the | |
1433 | address, in which case the address is passed to the next router. | |
1434 | ||
1435 | The final router in many configurations is one that checks to see if the | |
1436 | address belongs to a local mailbox. The precondition may involve a check to see | |
1437 | if the local part is the name of a login account, or it may look up the local | |
1438 | part in a file or a database. If its preconditions are not met, or if the | |
1439 | router declines, we have reached the end of the routers. When this happens, the | |
1440 | address is bounced. | |
1441 | ||
1442 | ||
1443 | 3.9 Processing an address for verification | |
1444 | ------------------------------------------ | |
1445 | ||
1446 | As well as being used to decide how to deliver to an address, Exim's routers | |
1447 | are also used for address verification. Verification can be requested as one of | |
1448 | the checks to be performed in an ACL for incoming messages, on both sender and | |
1449 | recipient addresses, and it can be tested using the -bv and -bvs command line | |
1450 | options. | |
1451 | ||
1452 | When an address is being verified, the routers are run in "verify mode". This | |
1453 | does not affect the way the routers work, but it is a state that can be | |
1454 | detected. By this means, a router can be skipped or made to behave differently | |
1455 | when verifying. A common example is a configuration in which the first router | |
1456 | sends all messages to a message-scanning program, unless they have been | |
1457 | previously scanned. Thus, the first router accepts all addresses without any | |
1458 | checking, making it useless for verifying. Normally, the no_verify option would | |
1459 | be set for such a router, causing it to be skipped in verify mode. | |
1460 | ||
1461 | ||
1462 | 3.10 Running an individual router | |
1463 | --------------------------------- | |
1464 | ||
1465 | As explained in the example above, a number of preconditions are checked before | |
1466 | running a router. If any are not met, the router is skipped, and the address is | |
1467 | passed to the next router. When all the preconditions on a router are met, the | |
1468 | router is run. What happens next depends on the outcome, which is one of the | |
1469 | following: | |
1470 | ||
1471 | * accept: The router accepts the address, and either assigns it to a | |
1472 | transport, or generates one or more "child" addresses. Processing the | |
1473 | original address ceases, unless the unseen option is set on the router. | |
1474 | This option can be used to set up multiple deliveries with different | |
1475 | routing (for example, for keeping archive copies of messages). When unseen | |
1476 | is set, the address is passed to the next router. Normally, however, an | |
1477 | accept return marks the end of routing. | |
1478 | ||
1479 | Any child addresses generated by the router are processed independently, | |
1480 | starting with the first router by default. It is possible to change this by | |
1481 | setting the redirect_router option to specify which router to start at for | |
1482 | child addresses. Unlike pass_router (see below) the router specified by | |
1483 | redirect_router may be anywhere in the router configuration. | |
1484 | ||
1485 | * pass: The router recognizes the address, but cannot handle it itself. It | |
1486 | requests that the address be passed to another router. By default the | |
1487 | address is passed to the next router, but this can be changed by setting | |
1488 | the pass_router option. However, (unlike redirect_router) the named router | |
1489 | must be below the current router (to avoid loops). | |
1490 | ||
1491 | * decline: The router declines to accept the address because it does not | |
1492 | recognize it at all. By default, the address is passed to the next router, | |
1493 | but this can be prevented by setting the no_more option. When no_more is | |
1494 | set, all the remaining routers are skipped. In effect, no_more converts | |
1495 | decline into fail. | |
1496 | ||
1497 | * fail: The router determines that the address should fail, and queues it for | |
1498 | the generation of a bounce message. There is no further processing of the | |
1499 | original address unless unseen is set on the router. | |
1500 | ||
1501 | * defer: The router cannot handle the address at the present time. (A | |
1502 | database may be offline, or a DNS lookup may have timed out.) No further | |
1503 | processing of the address happens in this delivery attempt. It is tried | |
1504 | again next time the message is considered for delivery. | |
1505 | ||
1506 | * error: There is some error in the router (for example, a syntax error in | |
1507 | its configuration). The action is as for defer. | |
1508 | ||
1509 | If an address reaches the end of the routers without having been accepted by | |
1510 | any of them, it is bounced as unrouteable. The default error message in this | |
1511 | situation is "unrouteable address", but you can set your own message by making | |
1512 | use of the cannot_route_message option. This can be set for any router; the | |
1513 | value from the last router that "saw" the address is used. | |
1514 | ||
1515 | Sometimes while routing you want to fail a delivery when some conditions are | |
1516 | met but others are not, instead of passing the address on for further routing. | |
1517 | You can do this by having a second router that explicitly fails the delivery | |
1518 | when the relevant conditions are met. The redirect router has a "fail" facility | |
1519 | for this purpose. | |
1520 | ||
1521 | ||
1522 | 3.11 Duplicate addresses | |
1523 | ------------------------ | |
1524 | ||
1525 | Once routing is complete, Exim scans the addresses that are assigned to local | |
1526 | and remote transports, and discards any duplicates that it finds. During this | |
1527 | check, local parts are treated as case-sensitive. This happens only when | |
1528 | actually delivering a message; when testing routers with -bt, all the routed | |
1529 | addresses are shown. | |
1530 | ||
1531 | ||
1532 | 3.12 Router preconditions | |
1533 | ------------------------- | |
1534 | ||
1535 | The preconditions that are tested for each router are listed below, in the | |
1536 | order in which they are tested. The individual configuration options are | |
1537 | described in more detail in chapter 15. | |
1538 | ||
1539 | * The local_part_prefix and local_part_suffix options can specify that the | |
1540 | local parts handled by the router may or must have certain prefixes and/or | |
1541 | suffixes. If a mandatory affix (prefix or suffix) is not present, the | |
1542 | router is skipped. These conditions are tested first. When an affix is | |
1543 | present, it is removed from the local part before further processing, | |
1544 | including the evaluation of any other conditions. | |
1545 | ||
1546 | * Routers can be designated for use only when not verifying an address, that | |
1547 | is, only when routing it for delivery (or testing its delivery routing). If | |
1548 | the verify option is set false, the router is skipped when Exim is | |
1549 | verifying an address. Setting the verify option actually sets two options, | |
1550 | verify_sender and verify_recipient, which independently control the use of | |
1551 | the router for sender and recipient verification. You can set these options | |
1552 | directly if you want a router to be used for only one type of verification. | |
1553 | Note that cutthrough delivery is classed as a recipient verification for | |
1554 | this purpose. | |
1555 | ||
1556 | * If the address_test option is set false, the router is skipped when Exim is | |
1557 | run with the -bt option to test an address routing. This can be helpful | |
1558 | when the first router sends all new messages to a scanner of some sort; it | |
1559 | makes it possible to use -bt to test subsequent delivery routing without | |
1560 | having to simulate the effect of the scanner. | |
1561 | ||
1562 | * Routers can be designated for use only when verifying an address, as | |
1563 | opposed to routing it for delivery. The verify_only option controls this. | |
1564 | Again, cutthrough delivery counts as a verification. | |
1565 | ||
1566 | * Individual routers can be explicitly skipped when running the routers to | |
1567 | check an address given in the SMTP EXPN command (see the expn option). | |
1568 | ||
1569 | * If the domains option is set, the domain of the address must be in the set | |
1570 | of domains that it defines. | |
1571 | ||
1572 | * If the local_parts option is set, the local part of the address must be in | |
1573 | the set of local parts that it defines. If local_part_prefix or | |
1574 | local_part_suffix is in use, the prefix or suffix is removed from the local | |
1575 | part before this check. If you want to do precondition tests on local parts | |
1576 | that include affixes, you can do so by using a condition option (see below) | |
1577 | that uses the variables $local_part, $local_part_prefix, and | |
1578 | $local_part_suffix as necessary. | |
1579 | ||
1580 | * If the check_local_user option is set, the local part must be the name of | |
1581 | an account on the local host. If this check succeeds, the uid and gid of | |
1582 | the local user are placed in $local_user_uid and $local_user_gid and the | |
1583 | user's home directory is placed in $home; these values can be used in the | |
1584 | remaining preconditions. | |
1585 | ||
1586 | * If the router_home_directory option is set, it is expanded at this point, | |
1587 | because it overrides the value of $home. If this expansion were left till | |
1588 | later, the value of $home as set by check_local_user would be used in | |
1589 | subsequent tests. Having two different values of $home in the same router | |
1590 | could lead to confusion. | |
1591 | ||
1592 | * If the senders option is set, the envelope sender address must be in the | |
1593 | set of addresses that it defines. | |
1594 | ||
1595 | * If the require_files option is set, the existence or non-existence of | |
1596 | specified files is tested. | |
1597 | ||
1598 | * If the condition option is set, it is evaluated and tested. This option | |
1599 | uses an expanded string to allow you to set up your own custom | |
1600 | preconditions. Expanded strings are described in chapter 11. | |
1601 | ||
1602 | Note that require_files comes near the end of the list, so you cannot use it to | |
1603 | check for the existence of a file in which to lookup up a domain, local part, | |
1604 | or sender. However, as these options are all expanded, you can use the exists | |
1605 | expansion condition to make such tests within each condition. The require_files | |
1606 | option is intended for checking files that the router may be going to use | |
1607 | internally, or which are needed by a specific transport (for example, | |
1608 | .procmailrc). | |
1609 | ||
1610 | ||
1611 | 3.13 Delivery in detail | |
1612 | ----------------------- | |
1613 | ||
1614 | When a message is to be delivered, the sequence of events is as follows: | |
1615 | ||
1616 | * If a system-wide filter file is specified, the message is passed to it. The | |
1617 | filter may add recipients to the message, replace the recipients, discard | |
1618 | the message, cause a new message to be generated, or cause the message | |
1619 | delivery to fail. The format of the system filter file is the same as for | |
1620 | Exim user filter files, described in the separate document entitled Exim's | |
1621 | interfaces to mail filtering. (Note: Sieve cannot be used for system filter | |
1622 | files.) | |
1623 | ||
2813c06e | 1624 | Some additional features are available in system filters - see chapter 46 |
420a0d19 CE |
1625 | for details. Note that a message is passed to the system filter only once |
1626 | per delivery attempt, however many recipients it has. However, if there are | |
1627 | several delivery attempts because one or more addresses could not be | |
1628 | immediately delivered, the system filter is run each time. The filter | |
1629 | condition first_delivery can be used to detect the first run of the system | |
1630 | filter. | |
1631 | ||
1632 | * Each recipient address is offered to each configured router in turn, | |
1633 | subject to its preconditions, until one is able to handle it. If no router | |
1634 | can handle the address, that is, if they all decline, the address is | |
1635 | failed. Because routers can be targeted at particular domains, several | |
1636 | locally handled domains can be processed entirely independently of each | |
1637 | other. | |
1638 | ||
1639 | * A router that accepts an address may assign it to a local or a remote | |
1640 | transport. However, the transport is not run at this time. Instead, the | |
1641 | address is placed on a list for the particular transport, which will be run | |
1642 | later. Alternatively, the router may generate one or more new addresses | |
1643 | (typically from alias, forward, or filter files). New addresses are fed | |
1644 | back into this process from the top, but in order to avoid loops, a router | |
1645 | ignores any address which has an identically-named ancestor that was | |
1646 | processed by itself. | |
1647 | ||
1648 | * When all the routing has been done, addresses that have been successfully | |
1649 | handled are passed to their assigned transports. When local transports are | |
1650 | doing real local deliveries, they handle only one address at a time, but if | |
1651 | a local transport is being used as a pseudo-remote transport (for example, | |
1652 | to collect batched SMTP messages for transmission by some other means) | |
1653 | multiple addresses can be handled. Remote transports can always handle more | |
1654 | than one address at a time, but can be configured not to do so, or to | |
1655 | restrict multiple addresses to the same domain. | |
1656 | ||
1657 | * Each local delivery to a file or a pipe runs in a separate process under a | |
1658 | non-privileged uid, and these deliveries are run one at a time. Remote | |
1659 | deliveries also run in separate processes, normally under a uid that is | |
1660 | private to Exim ("the Exim user"), but in this case, several remote | |
1661 | deliveries can be run in parallel. The maximum number of simultaneous | |
1662 | remote deliveries for any one message is set by the remote_max_parallel | |
1663 | option. The order in which deliveries are done is not defined, except that | |
1664 | all local deliveries happen before any remote deliveries. | |
1665 | ||
1666 | * When it encounters a local delivery during a queue run, Exim checks its | |
1667 | retry database to see if there has been a previous temporary delivery | |
1668 | failure for the address before running the local transport. If there was a | |
1669 | previous failure, Exim does not attempt a new delivery until the retry time | |
1670 | for the address is reached. However, this happens only for delivery | |
1671 | attempts that are part of a queue run. Local deliveries are always | |
1672 | attempted when delivery immediately follows message reception, even if | |
1673 | retry times are set for them. This makes for better behaviour if one | |
1674 | particular message is causing problems (for example, causing quota | |
1675 | overflow, or provoking an error in a filter file). | |
1676 | ||
1677 | * Remote transports do their own retry handling, since an address may be | |
1678 | deliverable to one of a number of hosts, each of which may have a different | |
1679 | retry time. If there have been previous temporary failures and no host has | |
1680 | reached its retry time, no delivery is attempted, whether in a queue run or | |
1681 | not. See chapter 32 for details of retry strategies. | |
1682 | ||
1683 | * If there were any permanent errors, a bounce message is returned to an | |
1684 | appropriate address (the sender in the common case), with details of the | |
1685 | error for each failing address. Exim can be configured to send copies of | |
1686 | bounce messages to other addresses. | |
1687 | ||
1688 | * If one or more addresses suffered a temporary failure, the message is left | |
1689 | on the queue, to be tried again later. Delivery of these addresses is said | |
1690 | to be deferred. | |
1691 | ||
1692 | * When all the recipient addresses have either been delivered or bounced, | |
1693 | handling of the message is complete. The spool files and message log are | |
1694 | deleted, though the message log can optionally be preserved if required. | |
1695 | ||
1696 | ||
1697 | 3.14 Retry mechanism | |
1698 | -------------------- | |
1699 | ||
1700 | Exim's mechanism for retrying messages that fail to get delivered at the first | |
1701 | attempt is the queue runner process. You must either run an Exim daemon that | |
1702 | uses the -q option with a time interval to start queue runners at regular | |
1703 | intervals, or use some other means (such as cron) to start them. If you do not | |
1704 | arrange for queue runners to be run, messages that fail temporarily at the | |
1705 | first attempt will remain on your queue for ever. A queue runner process works | |
1706 | its way through the queue, one message at a time, trying each delivery that has | |
1707 | passed its retry time. You can run several queue runners at once. | |
1708 | ||
1709 | Exim uses a set of configured rules to determine when next to retry the failing | |
1710 | address (see chapter 32). These rules also specify when Exim should give up | |
1711 | trying to deliver to the address, at which point it generates a bounce message. | |
1712 | If no retry rules are set for a particular host, address, and error | |
1713 | combination, no retries are attempted, and temporary errors are treated as | |
1714 | permanent. | |
1715 | ||
1716 | ||
1717 | 3.15 Temporary delivery failure | |
1718 | ------------------------------- | |
1719 | ||
1720 | There are many reasons why a message may not be immediately deliverable to a | |
1721 | particular address. Failure to connect to a remote machine (because it, or the | |
1722 | connection to it, is down) is one of the most common. Temporary failures may be | |
1723 | detected during routing as well as during the transport stage of delivery. | |
1724 | Local deliveries may be delayed if NFS files are unavailable, or if a mailbox | |
1725 | is on a file system where the user is over quota. Exim can be configured to | |
1726 | impose its own quotas on local mailboxes; where system quotas are set they will | |
1727 | also apply. | |
1728 | ||
1729 | If a host is unreachable for a period of time, a number of messages may be | |
1730 | waiting for it by the time it recovers, and sending them in a single SMTP | |
1731 | connection is clearly beneficial. Whenever a delivery to a remote host is | |
1732 | deferred, Exim makes a note in its hints database, and whenever a successful | |
1733 | SMTP delivery has happened, it looks to see if any other messages are waiting | |
1734 | for the same host. If any are found, they are sent over the same SMTP | |
1735 | connection, subject to a configuration limit as to the maximum number in any | |
1736 | one connection. | |
1737 | ||
1738 | ||
1739 | 3.16 Permanent delivery failure | |
1740 | ------------------------------- | |
1741 | ||
1742 | When a message cannot be delivered to some or all of its intended recipients, a | |
1743 | bounce message is generated. Temporary delivery failures turn into permanent | |
1744 | errors when their timeout expires. All the addresses that fail in a given | |
1745 | delivery attempt are listed in a single message. If the original message has | |
1746 | many recipients, it is possible for some addresses to fail in one delivery | |
1747 | attempt and others to fail subsequently, giving rise to more than one bounce | |
1748 | message. The wording of bounce messages can be customized by the administrator. | |
2813c06e | 1749 | See chapter 49 for details. |
420a0d19 CE |
1750 | |
1751 | Bounce messages contain an X-Failed-Recipients: header line that lists the | |
1752 | failed addresses, for the benefit of programs that try to analyse such messages | |
1753 | automatically. | |
1754 | ||
1755 | A bounce message is normally sent to the sender of the original message, as | |
1756 | obtained from the message's envelope. For incoming SMTP messages, this is the | |
1757 | address given in the MAIL command. However, when an address is expanded via a | |
1758 | forward or alias file, an alternative address can be specified for delivery | |
1759 | failures of the generated addresses. For a mailing list expansion (see section | |
2813c06e | 1760 | 50.2) it is common to direct bounce messages to the manager of the list. |
420a0d19 CE |
1761 | |
1762 | ||
1763 | 3.17 Failures to deliver bounce messages | |
1764 | ---------------------------------------- | |
1765 | ||
1766 | If a bounce message (either locally generated or received from a remote host) | |
1767 | itself suffers a permanent delivery failure, the message is left on the queue, | |
1768 | but it is frozen, awaiting the attention of an administrator. There are options | |
1769 | that can be used to make Exim discard such failed messages, or to keep them for | |
1770 | only a short time (see timeout_frozen_after and ignore_bounce_errors_after). | |
1771 | ||
1772 | ||
1773 | ||
1774 | =============================================================================== | |
1775 | 4. BUILDING AND INSTALLING EXIM | |
1776 | ||
1777 | ||
1778 | 4.1 Unpacking | |
1779 | ------------- | |
1780 | ||
1781 | Exim is distributed as a gzipped or bzipped tar file which, when unpacked, | |
1782 | creates a directory with the name of the current release (for example, | |
2813c06e | 1783 | exim-4.89) into which the following files are placed: |
420a0d19 CE |
1784 | |
1785 | ACKNOWLEDGMENTS contains some acknowledgments | |
1786 | CHANGES contains a reference to where changes are documented | |
1787 | LICENCE the GNU General Public Licence | |
1788 | Makefile top-level make file | |
1789 | NOTICE conditions for the use of Exim | |
1790 | README list of files, directories and simple build instructions | |
1791 | ||
1792 | Other files whose names begin with README may also be present. The following | |
1793 | subdirectories are created: | |
1794 | ||
1795 | Local an empty directory for local configuration files | |
1796 | OS OS-specific files | |
1797 | doc documentation files | |
1798 | exim_monitor source files for the Exim monitor | |
1799 | scripts scripts used in the build process | |
1800 | src remaining source files | |
1801 | util independent utilities | |
1802 | ||
1803 | The main utility programs are contained in the src directory, and are built | |
1804 | with the Exim binary. The util directory contains a few optional scripts that | |
1805 | may be useful to some sites. | |
1806 | ||
1807 | ||
1808 | 4.2 Multiple machine architectures and operating systems | |
1809 | -------------------------------------------------------- | |
1810 | ||
1811 | The building process for Exim is arranged to make it easy to build binaries for | |
1812 | a number of different architectures and operating systems from the same set of | |
1813 | source files. Compilation does not take place in the src directory. Instead, a | |
1814 | build directory is created for each architecture and operating system. Symbolic | |
1815 | links to the sources are installed in this directory, which is where the actual | |
1816 | building takes place. In most cases, Exim can discover the machine architecture | |
1817 | and operating system for itself, but the defaults can be overridden if | |
1818 | necessary. | |
1819 | ||
1820 | ||
1821 | 4.3 PCRE library | |
1822 | ---------------- | |
1823 | ||
1824 | Exim no longer has an embedded PCRE library as the vast majority of modern | |
1825 | systems include PCRE as a system library, although you may need to install the | |
1826 | PCRE or PCRE development package for your operating system. If your system has | |
1827 | a normal PCRE installation the Exim build process will need no further | |
1828 | configuration. If the library or the headers are in an unusual location you | |
1829 | will need to either set the PCRE_LIBS and INCLUDE directives appropriately, or | |
1830 | set PCRE_CONFIG=yes to use the installed pcre-config command. If your operating | |
1831 | system has no PCRE support then you will need to obtain and build the current | |
1832 | PCRE from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/. More | |
1833 | information on PCRE is available at http://www.pcre.org/. | |
1834 | ||
1835 | ||
1836 | 4.4 DBM libraries | |
1837 | ----------------- | |
1838 | ||
1839 | Even if you do not use any DBM files in your configuration, Exim still needs a | |
1840 | DBM library in order to operate, because it uses indexed files for its hints | |
1841 | databases. Unfortunately, there are a number of DBM libraries in existence, and | |
1842 | different operating systems often have different ones installed. | |
1843 | ||
1844 | If you are using Solaris, IRIX, one of the modern BSD systems, or a modern | |
1845 | Linux distribution, the DBM configuration should happen automatically, and you | |
1846 | may be able to ignore this section. Otherwise, you may have to learn more than | |
1847 | you would like about DBM libraries from what follows. | |
1848 | ||
1849 | Licensed versions of Unix normally contain a library of DBM functions operating | |
1850 | via the ndbm interface, and this is what Exim expects by default. Free versions | |
1851 | of Unix seem to vary in what they contain as standard. In particular, some | |
1852 | early versions of Linux have no default DBM library, and different distributors | |
1853 | have chosen to bundle different libraries with their packaged versions. | |
1854 | However, the more recent releases seem to have standardized on the Berkeley DB | |
1855 | library. | |
1856 | ||
1857 | Different DBM libraries have different conventions for naming the files they | |
1858 | use. When a program opens a file called dbmfile, there are several | |
1859 | possibilities: | |
1860 | ||
1861 | 1. A traditional ndbm implementation, such as that supplied as part of | |
1862 | Solaris, operates on two files called dbmfile.dir and dbmfile.pag. | |
1863 | ||
1864 | 2. The GNU library, gdbm, operates on a single file. If used via its ndbm | |
1865 | compatibility interface it makes two different hard links to it with names | |
1866 | dbmfile.dir and dbmfile.pag, but if used via its native interface, the file | |
1867 | name is used unmodified. | |
1868 | ||
1869 | 3. The Berkeley DB package, if called via its ndbm compatibility interface, | |
1870 | operates on a single file called dbmfile.db, but otherwise looks to the | |
1871 | programmer exactly the same as the traditional ndbm implementation. | |
1872 | ||
1873 | 4. If the Berkeley package is used in its native mode, it operates on a single | |
1874 | file called dbmfile; the programmer's interface is somewhat different to | |
1875 | the traditional ndbm interface. | |
1876 | ||
1877 | 5. To complicate things further, there are several very different versions of | |
1878 | the Berkeley DB package. Version 1.85 was stable for a very long time, | |
1879 | releases 2.x and 3.x were current for a while, but the latest versions are | |
1880 | now numbered 4.x. Maintenance of some of the earlier releases has ceased. | |
1881 | All versions of Berkeley DB can be obtained from http://www.sleepycat.com/. | |
1882 | ||
1883 | 6. Yet another DBM library, called tdb, is available from http:// | |
1884 | download.sourceforge.net/tdb. It has its own interface, and also operates | |
1885 | on a single file. | |
1886 | ||
1887 | Exim and its utilities can be compiled to use any of these interfaces. In order | |
1888 | to use any version of the Berkeley DB package in native mode, you must set | |
1889 | USE_DB in an appropriate configuration file (typically Local/Makefile). For | |
1890 | example: | |
1891 | ||
1892 | USE_DB=yes | |
1893 | ||
1894 | Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An error is | |
1895 | diagnosed if you set more than one of these. | |
1896 | ||
1897 | At the lowest level, the build-time configuration sets none of these options, | |
1898 | thereby assuming an interface of type (1). However, some operating system | |
1899 | configuration files (for example, those for the BSD operating systems and | |
1900 | Linux) assume type (4) by setting USE_DB as their default, and the | |
1901 | configuration files for Cygwin set USE_GDBM. Anything you set in Local/Makefile | |
1902 | , however, overrides these system defaults. | |
1903 | ||
1904 | As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be necessary to | |
1905 | set DBMLIB, to cause inclusion of the appropriate library, as in one of these | |
1906 | lines: | |
1907 | ||
1908 | DBMLIB = -ldb | |
1909 | DBMLIB = -ltdb | |
1910 | ||
1911 | Settings like that will work if the DBM library is installed in the standard | |
1912 | place. Sometimes it is not, and the library's header file may also not be in | |
1913 | the default path. You may need to set INCLUDE to specify where the header file | |
1914 | is, and to specify the path to the library more fully in DBMLIB, as in this | |
1915 | example: | |
1916 | ||
1917 | INCLUDE=-I/usr/local/include/db-4.1 | |
1918 | DBMLIB=/usr/local/lib/db-4.1/libdb.a | |
1919 | ||
1920 | There is further detailed discussion about the various DBM libraries in the | |
1921 | file doc/dbm.discuss.txt in the Exim distribution. | |
1922 | ||
1923 | ||
1924 | 4.5 Pre-building configuration | |
1925 | ------------------------------ | |
1926 | ||
1927 | Before building Exim, a local configuration file that specifies options | |
1928 | independent of any operating system has to be created with the name Local/ | |
1929 | Makefile. A template for this file is supplied as the file src/EDITME, and it | |
1930 | contains full descriptions of all the option settings therein. These | |
1931 | descriptions are therefore not repeated here. If you are building Exim for the | |
1932 | first time, the simplest thing to do is to copy src/EDITME to Local/Makefile, | |
1933 | then read it and edit it appropriately. | |
1934 | ||
1935 | There are three settings that you must supply, because Exim will not build | |
1936 | without them. They are the location of the run time configuration file | |
1937 | (CONFIGURE_FILE), the directory in which Exim binaries will be installed | |
1938 | (BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and maybe | |
1939 | EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be a | |
1940 | colon-separated list of file names; Exim uses the first of them that exists. | |
1941 | ||
1942 | There are a few other parameters that can be specified either at build time or | |
1943 | at run time, to enable the same binary to be used on a number of different | |
1944 | machines. However, if the locations of Exim's spool directory and log file | |
1945 | directory (if not within the spool directory) are fixed, it is recommended that | |
1946 | you specify them in Local/Makefile instead of at run time, so that errors | |
1947 | detected early in Exim's execution (such as a malformed configuration file) can | |
1948 | be logged. | |
1949 | ||
1950 | Exim's interfaces for calling virus and spam scanning software directly from | |
1951 | access control lists are not compiled by default. If you want to include these | |
1952 | facilities, you need to set | |
1953 | ||
1954 | WITH_CONTENT_SCAN=yes | |
1955 | ||
1956 | in your Local/Makefile. For details of the facilities themselves, see chapter | |
2813c06e | 1957 | 44. |
420a0d19 CE |
1958 | |
1959 | If you are going to build the Exim monitor, a similar configuration process is | |
1960 | required. The file exim_monitor/EDITME must be edited appropriately for your | |
1961 | installation and saved under the name Local/eximon.conf. If you are happy with | |
1962 | the default settings described in exim_monitor/EDITME, Local/eximon.conf can be | |
1963 | empty, but it must exist. | |
1964 | ||
1965 | This is all the configuration that is needed in straightforward cases for known | |
1966 | operating systems. However, the building process is set up so that it is easy | |
1967 | to override options that are set by default or by operating-system-specific | |
1968 | configuration files, for example to change the name of the C compiler, which | |
1969 | defaults to gcc. See section 4.13 below for details of how to do this. | |
1970 | ||
1971 | ||
1972 | 4.6 Support for iconv() | |
1973 | ----------------------- | |
1974 | ||
1975 | The contents of header lines in messages may be encoded according to the rules | |
1976 | described RFC 2047. This makes it possible to transmit characters that are not | |
1977 | in the ASCII character set, and to label them as being in a particular | |
1978 | character set. When Exim is inspecting header lines by means of the $h_ | |
1979 | mechanism, it decodes them, and translates them into a specified character set | |
2813c06e CE |
1980 | (default is set at build time). The translation is possible only if the |
1981 | operating system supports the iconv() function. | |
420a0d19 CE |
1982 | |
1983 | However, some of the operating systems that supply iconv() do not support very | |
1984 | many conversions. The GNU libiconv library (available from http://www.gnu.org/ | |
1985 | software/libiconv/) can be installed on such systems to remedy this deficiency, | |
1986 | as well as on systems that do not supply iconv() at all. After installing | |
1987 | libiconv, you should add | |
1988 | ||
1989 | HAVE_ICONV=yes | |
1990 | ||
1991 | to your Local/Makefile and rebuild Exim. | |
1992 | ||
1993 | ||
1994 | 4.7 Including TLS/SSL encryption support | |
1995 | ---------------------------------------- | |
1996 | ||
1997 | Exim can be built to support encrypted SMTP connections, using the STARTTLS | |
1998 | command as per RFC 2487. It can also support legacy clients that expect to | |
1999 | start a TLS session immediately on connection to a non-standard port (see the | |
2000 | tls_on_connect_ports runtime option and the -tls-on-connect command line | |
2001 | option). | |
2002 | ||
2003 | If you want to build Exim with TLS support, you must first install either the | |
2004 | OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for | |
2005 | implementing SSL. | |
2006 | ||
2007 | If OpenSSL is installed, you should set | |
2008 | ||
2009 | SUPPORT_TLS=yes | |
2010 | TLS_LIBS=-lssl -lcrypto | |
2011 | ||
2012 | in Local/Makefile. You may also need to specify the locations of the OpenSSL | |
2013 | library and include files. For example: | |
2014 | ||
2015 | SUPPORT_TLS=yes | |
2016 | TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto | |
2017 | TLS_INCLUDE=-I/usr/local/openssl/include/ | |
2018 | ||
2019 | If you have pkg-config available, then instead you can just use: | |
2020 | ||
2021 | SUPPORT_TLS=yes | |
2022 | USE_OPENSSL_PC=openssl | |
2023 | ||
2024 | If GnuTLS is installed, you should set | |
2025 | ||
2026 | SUPPORT_TLS=yes | |
2027 | USE_GNUTLS=yes | |
2028 | TLS_LIBS=-lgnutls -ltasn1 -lgcrypt | |
2029 | ||
2030 | in Local/Makefile, and again you may need to specify the locations of the | |
2031 | library and include files. For example: | |
2032 | ||
2033 | SUPPORT_TLS=yes | |
2034 | USE_GNUTLS=yes | |
2035 | TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt | |
2036 | TLS_INCLUDE=-I/usr/gnu/include | |
2037 | ||
2038 | If you have pkg-config available, then instead you can just use: | |
2039 | ||
2040 | SUPPORT_TLS=yes | |
2041 | USE_GNUTLS=yes | |
2042 | USE_GNUTLS_PC=gnutls | |
2043 | ||
2044 | You do not need to set TLS_INCLUDE if the relevant directory is already | |
2045 | specified in INCLUDE. Details of how to configure Exim to make use of TLS are | |
2813c06e | 2046 | given in chapter 42. |
420a0d19 CE |
2047 | |
2048 | ||
2049 | 4.8 Use of tcpwrappers | |
2050 | ---------------------- | |
2051 | ||
2052 | Exim can be linked with the tcpwrappers library in order to check incoming SMTP | |
2053 | calls using the tcpwrappers control files. This may be a convenient alternative | |
2054 | to Exim's own checking facilities for installations that are already making use | |
2055 | of tcpwrappers for other purposes. To do this, you should set USE_TCP_WRAPPERS | |
2056 | in Local/Makefile, arrange for the file tcpd.h to be available at compile time, | |
2057 | and also ensure that the library libwrap.a is available at link time, typically | |
2058 | by including -lwrap in EXTRALIBS_EXIM. For example, if tcpwrappers is installed | |
2059 | in /usr/local, you might have | |
2060 | ||
2061 | USE_TCP_WRAPPERS=yes | |
2062 | CFLAGS=-O -I/usr/local/include | |
2063 | EXTRALIBS_EXIM=-L/usr/local/lib -lwrap | |
2064 | ||
2065 | in Local/Makefile. The daemon name to use in the tcpwrappers control files is | |
2066 | "exim". For example, the line | |
2067 | ||
2068 | exim : LOCAL 192.168.1. .friendly.domain.example | |
2069 | ||
2070 | in your /etc/hosts.allow file allows connections from the local host, from the | |
2071 | subnet 192.168.1.0/24, and from all hosts in friendly.domain.example. All other | |
2072 | connections are denied. The daemon name used by tcpwrappers can be changed at | |
2073 | build time by setting TCP_WRAPPERS_DAEMON_NAME in Local/Makefile, or by setting | |
2074 | tcp_wrappers_daemon_name in the configure file. Consult the tcpwrappers | |
2075 | documentation for further details. | |
2076 | ||
2077 | ||
2078 | 4.9 Including support for IPv6 | |
2079 | ------------------------------ | |
2080 | ||
2081 | Exim contains code for use on systems that have IPv6 support. Setting | |
2082 | "HAVE_IPV6=YES" in Local/Makefile causes the IPv6 code to be included; it may | |
2083 | also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems where the IPv6 | |
2084 | support is not fully integrated into the normal include and library files. | |
2085 | ||
2086 | Two different types of DNS record for handling IPv6 addresses have been | |
2087 | defined. AAAA records (analogous to A records for IPv4) are in use, and are | |
2088 | currently seen as the mainstream. Another record type called A6 was proposed as | |
2089 | better than AAAA because it had more flexibility. However, it was felt to be | |
2813c06e CE |
2090 | over-complex, and its status was reduced to "experimental". Exim used to have a |
2091 | compile option for including A6 record support but this has now been withdrawn. | |
420a0d19 CE |
2092 | |
2093 | ||
2094 | 4.10 Dynamically loaded lookup module support | |
2095 | --------------------------------------------- | |
2096 | ||
2097 | On some platforms, Exim supports not compiling all lookup types directly into | |
2098 | the main binary, instead putting some into external modules which can be loaded | |
2099 | on demand. This permits packagers to build Exim with support for lookups with | |
2100 | extensive library dependencies without requiring all users to install all of | |
2101 | those dependencies. Most, but not all, lookup types can be built this way. | |
2102 | ||
2103 | Set "LOOKUP_MODULE_DIR" to the directory into which the modules will be | |
2104 | installed; Exim will only load modules from that directory, as a security | |
2105 | measure. You will need to set "CFLAGS_DYNAMIC" if not already defined for your | |
2106 | OS; see OS/Makefile-Linux for an example. Some other requirements for adjusting | |
2107 | "EXTRALIBS" may also be necessary, see src/EDITME for details. | |
2108 | ||
2109 | Then, for each module to be loaded dynamically, define the relevant "LOOKUP_"< | |
2110 | lookup_type> flags to have the value "2" instead of "yes". For example, this | |
2111 | will build in lsearch but load sqlite and mysql support on demand: | |
2112 | ||
2113 | LOOKUP_LSEARCH=yes | |
2114 | LOOKUP_SQLITE=2 | |
2115 | LOOKUP_MYSQL=2 | |
2116 | ||
2117 | ||
2118 | 4.11 The building process | |
2119 | ------------------------- | |
2120 | ||
2121 | Once Local/Makefile (and Local/eximon.conf, if required) have been created, run | |
2122 | make at the top level. It determines the architecture and operating system | |
2123 | types, and creates a build directory if one does not exist. For example, on a | |
2124 | Sun system running Solaris 8, the directory build-SunOS5-5.8-sparc is created. | |
2125 | Symbolic links to relevant source files are installed in the build directory. | |
2126 | ||
420a0d19 CE |
2127 | If this is the first time make has been run, it calls a script that builds a |
2128 | make file inside the build directory, using the configuration files from the | |
2129 | Local directory. The new make file is then passed to another instance of make. | |
2130 | This does the real work, building a number of utility scripts, and then | |
2131 | compiling and linking the binaries for the Exim monitor (if configured), a | |
2132 | number of utility programs, and finally Exim itself. The command "make | |
2133 | makefile" can be used to force a rebuild of the make file in the build | |
2134 | directory, should this ever be necessary. | |
2135 | ||
2136 | If you have problems building Exim, check for any comments there may be in the | |
2137 | README file concerning your operating system, and also take a look at the FAQ, | |
2138 | where some common problems are covered. | |
2139 | ||
2140 | ||
2141 | 4.12 Output from "make" | |
2142 | ----------------------- | |
2143 | ||
2144 | The output produced by the make process for compile lines is often very | |
2145 | unreadable, because these lines can be very long. For this reason, the normal | |
2146 | output is suppressed by default, and instead output similar to that which | |
2147 | appears when compiling the 2.6 Linux kernel is generated: just a short line for | |
2148 | each module that is being compiled or linked. However, it is still possible to | |
2149 | get the full output, by calling make like this: | |
2150 | ||
2151 | FULLECHO='' make -e | |
2152 | ||
2153 | The value of FULLECHO defaults to "@", the flag character that suppresses | |
2154 | command reflection in make. When you ask for the full output, it is given in | |
2155 | addition to the short output. | |
2156 | ||
2157 | ||
2158 | 4.13 Overriding build-time options for Exim | |
2159 | ------------------------------------------- | |
2160 | ||
2161 | The main make file that is created at the beginning of the building process | |
2162 | consists of the concatenation of a number of files which set configuration | |
2163 | values, followed by a fixed set of make instructions. If a value is set more | |
2164 | than once, the last setting overrides any previous ones. This provides a | |
2165 | convenient way of overriding defaults. The files that are concatenated are, in | |
2166 | order: | |
2167 | ||
2168 | OS/Makefile-Default | |
2169 | OS/Makefile-<ostype> | |
2170 | Local/Makefile | |
2171 | Local/Makefile-<ostype> | |
2172 | Local/Makefile-<archtype> | |
2173 | Local/Makefile-<ostype>-<archtype> | |
2174 | OS/Makefile-Base | |
2175 | ||
2176 | where <ostype> is the operating system type and <archtype> is the architecture | |
2177 | type. Local/Makefile is required to exist, and the building process fails if it | |
2178 | is absent. The other three Local files are optional, and are often not needed. | |
2179 | ||
2180 | The values used for <ostype> and <archtype> are obtained from scripts called | |
2181 | scripts/os-type and scripts/arch-type respectively. If either of the | |
2182 | environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their values are | |
2183 | used, thereby providing a means of forcing particular settings. Otherwise, the | |
2184 | scripts try to get values from the uname command. If this fails, the shell | |
2185 | variables OSTYPE and ARCHTYPE are inspected. A number of ad hoc transformations | |
2186 | are then applied, to produce the standard names that Exim expects. You can run | |
2187 | these scripts directly from the shell in order to find out what values are | |
2188 | being used on your system. | |
2189 | ||
2190 | OS/Makefile-Default contains comments about the variables that are set therein. | |
2191 | Some (but not all) are mentioned below. If there is something that needs | |
2192 | changing, review the contents of this file and the contents of the make file | |
2193 | for your operating system (OS/Makefile-<ostype>) to see what the default values | |
2194 | are. | |
2195 | ||
2196 | If you need to change any of the values that are set in OS/Makefile-Default or | |
2197 | in OS/Makefile-<ostype>, or to add any new definitions, you do not need to | |
2198 | change the original files. Instead, you should make the changes by putting the | |
2199 | new values in an appropriate Local file. For example, when building Exim in | |
2200 | many releases of the Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1) | |
2201 | operating system, it is necessary to specify that the C compiler is called cc | |
2202 | rather than gcc. Also, the compiler must be called with the option -std1, to | |
2203 | make it recognize some of the features of Standard C that Exim uses. (Most | |
2204 | other compilers recognize Standard C by default.) To do this, you should create | |
2205 | a file called Local/Makefile-OSF1 containing the lines | |
2206 | ||
2207 | CC=cc | |
2208 | CFLAGS=-std1 | |
2209 | ||
2210 | If you are compiling for just one operating system, it may be easier to put | |
2211 | these lines directly into Local/Makefile. | |
2212 | ||
2213 | Keeping all your local configuration settings separate from the distributed | |
2214 | files makes it easy to transfer them to new versions of Exim simply by copying | |
2215 | the contents of the Local directory. | |
2216 | ||
2217 | Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file | |
2218 | lookup, but not all systems have these components installed, so the default is | |
2219 | not to include the relevant code in the binary. All the different kinds of file | |
2220 | and database lookup that Exim supports are implemented as separate code modules | |
2221 | which are included only if the relevant compile-time options are set. In the | |
2222 | case of LDAP, NIS, and NIS+, the settings for Local/Makefile are: | |
2223 | ||
2224 | LOOKUP_LDAP=yes | |
2225 | LOOKUP_NIS=yes | |
2226 | LOOKUP_NISPLUS=yes | |
2227 | ||
2228 | and similar settings apply to the other lookup types. They are all listed in | |
2229 | src/EDITME. In many cases the relevant include files and interface libraries | |
2230 | need to be installed before compiling Exim. However, there are some optional | |
2231 | lookup types (such as cdb) for which the code is entirely contained within | |
2232 | Exim, and no external include files or libraries are required. When a lookup | |
2233 | type is not included in the binary, attempts to configure Exim to use it cause | |
2234 | run time configuration errors. | |
2235 | ||
2236 | Many systems now use a tool called pkg-config to encapsulate information about | |
2237 | how to compile against a library; Exim has some initial support for being able | |
2238 | to use pkg-config for lookups and authenticators. For any given makefile | |
2239 | variable which starts "LOOKUP_" or "AUTH_", you can add a new variable with the | |
2240 | "_PC" suffix in the name and assign as the value the name of the package to be | |
2241 | queried. The results of querying via the pkg-config command will be added to | |
2242 | the appropriate Makefile variables with "+=" directives, so your version of | |
2243 | make will need to support that syntax. For instance: | |
2244 | ||
2245 | LOOKUP_SQLITE=yes | |
2246 | LOOKUP_SQLITE_PC=sqlite3 | |
2247 | AUTH_GSASL=yes | |
2248 | AUTH_GSASL_PC=libgsasl | |
2249 | AUTH_HEIMDAL_GSSAPI=yes | |
2250 | AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi | |
2251 | ||
2252 | Exim can be linked with an embedded Perl interpreter, allowing Perl subroutines | |
2253 | to be called during string expansion. To enable this facility, | |
2254 | ||
2255 | EXIM_PERL=perl.o | |
2256 | ||
2257 | must be defined in Local/Makefile. Details of this facility are given in | |
2258 | chapter 12. | |
2259 | ||
2260 | The location of the X11 libraries is something that varies a lot between | |
2261 | operating systems, and there may be different versions of X11 to cope with. | |
2262 | Exim itself makes no use of X11, but if you are compiling the Exim monitor, the | |
2263 | X11 libraries must be available. The following three variables are set in OS/ | |
2264 | Makefile-Default: | |
2265 | ||
2266 | X11=/usr/X11R6 | |
2267 | XINCLUDE=-I$(X11)/include | |
2268 | XLFLAGS=-L$(X11)/lib | |
2269 | ||
2270 | These are overridden in some of the operating-system configuration files. For | |
2271 | example, in OS/Makefile-SunOS5 there is | |
2272 | ||
2273 | X11=/usr/openwin | |
2274 | XINCLUDE=-I$(X11)/include | |
2275 | XLFLAGS=-L$(X11)/lib -R$(X11)/lib | |
2276 | ||
2277 | If you need to override the default setting for your operating system, place a | |
2278 | definition of all three of these variables into your Local/Makefile-<ostype> | |
2279 | file. | |
2280 | ||
2281 | If you need to add any extra libraries to the link steps, these can be put in a | |
2282 | variable called EXTRALIBS, which appears in all the link commands, but by | |
2283 | default is not defined. In contrast, EXTRALIBS_EXIM is used only on the command | |
2284 | for linking the main Exim binary, and not for any associated utilities. | |
2285 | ||
2286 | There is also DBMLIB, which appears in the link commands for binaries that use | |
2287 | DBM functions (see also section 4.4). Finally, there is EXTRALIBS_EXIMON, which | |
2288 | appears only in the link step for the Exim monitor binary, and which can be | |
2289 | used, for example, to include additional X11 libraries. | |
2290 | ||
2291 | The make file copes with rebuilding Exim correctly if any of the configuration | |
2292 | files are edited. However, if an optional configuration file is deleted, it is | |
2293 | necessary to touch the associated non-optional file (that is, Local/Makefile or | |
2294 | Local/eximon.conf) before rebuilding. | |
2295 | ||
2296 | ||
2297 | 4.14 OS-specific header files | |
2298 | ----------------------------- | |
2299 | ||
2300 | The OS directory contains a number of files with names of the form os.h- | |
2301 | <ostype>. These are system-specific C header files that should not normally | |
2302 | need to be changed. There is a list of macro settings that are recognized in | |
2303 | the file OS/os.configuring, which should be consulted if you are porting Exim | |
2304 | to a new operating system. | |
2305 | ||
2306 | ||
2307 | 4.15 Overriding build-time options for the monitor | |
2308 | -------------------------------------------------- | |
2309 | ||
2310 | A similar process is used for overriding things when building the Exim monitor, | |
2311 | where the files that are involved are | |
2312 | ||
2313 | OS/eximon.conf-Default | |
2314 | OS/eximon.conf-<ostype> | |
2315 | Local/eximon.conf | |
2316 | Local/eximon.conf-<ostype> | |
2317 | Local/eximon.conf-<archtype> | |
2318 | Local/eximon.conf-<ostype>-<archtype> | |
2319 | ||
2320 | As with Exim itself, the final three files need not exist, and in this case the | |
2321 | OS/eximon.conf-<ostype> file is also optional. The default values in OS/ | |
2322 | eximon.conf-Default can be overridden dynamically by setting environment | |
2323 | variables of the same name, preceded by EXIMON_. For example, setting | |
2324 | EXIMON_LOG_DEPTH in the environment overrides the value of LOG_DEPTH at run | |
2325 | time. | |
2326 | ||
2327 | ||
2328 | 4.16 Installing Exim binaries and scripts | |
2329 | ----------------------------------------- | |
2330 | ||
2331 | The command "make install" runs the exim_install script with no arguments. The | |
2332 | script copies binaries and utility scripts into the directory whose name is | |
2333 | specified by the BIN_DIRECTORY setting in Local/Makefile. The install script | |
2334 | copies files only if they are newer than the files they are going to replace. | |
2335 | The Exim binary is required to be owned by root and have the setuid bit set, | |
2336 | for normal configurations. Therefore, you must run "make install" as root so | |
2337 | that it can set up the Exim binary in this way. However, in some special | |
2338 | situations (for example, if a host is doing no local deliveries) it may be | |
2813c06e | 2339 | possible to run Exim without making the binary setuid root (see chapter 55 for |
420a0d19 CE |
2340 | details). |
2341 | ||
2342 | Exim's run time configuration file is named by the CONFIGURE_FILE setting in | |
2343 | Local/Makefile. If this names a single file, and the file does not exist, the | |
2344 | default configuration file src/configure.default is copied there by the | |
2345 | installation script. If a run time configuration file already exists, it is | |
2346 | left alone. If CONFIGURE_FILE is a colon-separated list, naming several | |
2347 | alternative files, no default is installed. | |
2348 | ||
2349 | One change is made to the default configuration file when it is installed: the | |
2350 | default configuration contains a router that references a system aliases file. | |
2351 | The path to this file is set to the value specified by SYSTEM_ALIASES_FILE in | |
2352 | Local/Makefile (/etc/aliases by default). If the system aliases file does not | |
2353 | exist, the installation script creates it, and outputs a comment to the user. | |
2354 | ||
2355 | The created file contains no aliases, but it does contain comments about the | |
2356 | aliases a site should normally have. Mail aliases have traditionally been kept | |
2357 | in /etc/aliases. However, some operating systems are now using /etc/mail/ | |
2358 | aliases. You should check if yours is one of these, and change Exim's | |
2359 | configuration if necessary. | |
2360 | ||
2361 | The default configuration uses the local host's name as the only local domain, | |
2362 | and is set up to do local deliveries into the shared directory /var/mail, | |
2363 | running as the local user. System aliases and .forward files in users' home | |
2364 | directories are supported, but no NIS or NIS+ support is configured. Domains | |
2365 | other than the name of the local host are routed using the DNS, with delivery | |
2366 | over SMTP. | |
2367 | ||
2368 | It is possible to install Exim for special purposes (such as building a binary | |
2369 | distribution) in a private part of the file system. You can do this by a | |
2370 | command such as | |
2371 | ||
2372 | make DESTDIR=/some/directory/ install | |
2373 | ||
2374 | This has the effect of pre-pending the specified directory to all the file | |
2375 | paths, except the name of the system aliases file that appears in the default | |
2376 | configuration. (If a default alias file is created, its name is modified.) For | |
2377 | backwards compatibility, ROOT is used if DESTDIR is not set, but this usage is | |
2378 | deprecated. | |
2379 | ||
2380 | Running make install does not copy the Exim 4 conversion script convert4r4. You | |
2381 | will probably run this only once if you are upgrading from Exim 3. None of the | |
2382 | documentation files in the doc directory are copied, except for the info files | |
2383 | when you have set INFO_DIRECTORY, as described in section 4.17 below. | |
2384 | ||
2385 | For the utility programs, old versions are renamed by adding the suffix .O to | |
2386 | their names. The Exim binary itself, however, is handled differently. It is | |
2387 | installed under a name that includes the version number and the compile number, | |
2813c06e | 2388 | for example exim-4.89-1. The script then arranges for a symbolic link called |
420a0d19 CE |
2389 | exim to point to the binary. If you are updating a previous version of Exim, |
2390 | the script takes care to ensure that the name exim is never absent from the | |
2391 | directory (as seen by other processes). | |
2392 | ||
2393 | If you want to see what the make install will do before running it for real, | |
2394 | you can pass the -n option to the installation script by this command: | |
2395 | ||
2396 | make INSTALL_ARG=-n install | |
2397 | ||
2398 | The contents of the variable INSTALL_ARG are passed to the installation script. | |
2399 | You do not need to be root to run this test. Alternatively, you can run the | |
2400 | installation script directly, but this must be from within the build directory. | |
2401 | For example, from the top-level Exim directory you could use this command: | |
2402 | ||
2403 | (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n) | |
2404 | ||
2405 | There are two other options that can be supplied to the installation script. | |
2406 | ||
2407 | * -no_chown bypasses the call to change the owner of the installed binary to | |
2408 | root, and the call to make it a setuid binary. | |
2409 | ||
2410 | * -no_symlink bypasses the setting up of the symbolic link exim to the | |
2411 | installed binary. | |
2412 | ||
2413 | INSTALL_ARG can be used to pass these options to the script. For example: | |
2414 | ||
2415 | make INSTALL_ARG=-no_symlink install | |
2416 | ||
2417 | The installation script can also be given arguments specifying which files are | |
2418 | to be copied. For example, to install just the Exim binary, and nothing else, | |
2419 | without creating the symbolic link, you could use: | |
2420 | ||
2421 | make INSTALL_ARG='-no_symlink exim' install | |
2422 | ||
2423 | ||
2424 | 4.17 Installing info documentation | |
2425 | ---------------------------------- | |
2426 | ||
2427 | Not all systems use the GNU info system for documentation, and for this reason, | |
2428 | the Texinfo source of Exim's documentation is not included in the main | |
2429 | distribution. Instead it is available separately from the ftp site (see section | |
2430 | 1.6). | |
2431 | ||
2432 | If you have defined INFO_DIRECTORY in Local/Makefile and the Texinfo source of | |
2433 | the documentation is found in the source tree, running "make install" | |
2434 | automatically builds the info files and installs them. | |
2435 | ||
2436 | ||
2437 | 4.18 Setting up the spool directory | |
2438 | ----------------------------------- | |
2439 | ||
2440 | When it starts up, Exim tries to create its spool directory if it does not | |
2441 | exist. The Exim uid and gid are used for the owner and group of the spool | |
2442 | directory. Sub-directories are automatically created in the spool directory as | |
2443 | necessary. | |
2444 | ||
2445 | ||
2446 | 4.19 Testing | |
2447 | ------------ | |
2448 | ||
2449 | Having installed Exim, you can check that the run time configuration file is | |
2450 | syntactically valid by running the following command, which assumes that the | |
2451 | Exim binary directory is within your PATH environment variable: | |
2452 | ||
2453 | exim -bV | |
2454 | ||
2455 | If there are any errors in the configuration file, Exim outputs error messages. | |
2456 | Otherwise it outputs the version number and build date, the DBM library that is | |
2457 | being used, and information about which drivers and other optional code modules | |
2458 | are included in the binary. Some simple routing tests can be done by using the | |
2459 | address testing option. For example, | |
2460 | ||
2461 | exim -bt <local username> | |
2462 | ||
2463 | should verify that it recognizes a local mailbox, and | |
2464 | ||
2465 | exim -bt <remote address> | |
2466 | ||
2467 | a remote one. Then try getting it to deliver mail, both locally and remotely. | |
2468 | This can be done by passing messages directly to Exim, without going through a | |
2469 | user agent. For example: | |
2470 | ||
2471 | exim -v postmaster@your.domain.example | |
2472 | From: user@your.domain.example | |
2473 | To: postmaster@your.domain.example | |
2474 | Subject: Testing Exim | |
2475 | ||
2476 | This is a test message. | |
2477 | ^D | |
2478 | ||
2479 | The -v option causes Exim to output some verification of what it is doing. In | |
2480 | this case you should see copies of three log lines, one for the message's | |
2481 | arrival, one for its delivery, and one containing "Completed". | |
2482 | ||
2483 | If you encounter problems, look at Exim's log files (mainlog and paniclog) to | |
2484 | see if there is any relevant information there. Another source of information | |
2485 | is running Exim with debugging turned on, by specifying the -d option. If a | |
2486 | message is stuck on Exim's spool, you can force a delivery with debugging | |
2487 | turned on by a command of the form | |
2488 | ||
2489 | exim -d -M <exim-message-id> | |
2490 | ||
2491 | You must be root or an "admin user" in order to do this. The -d option produces | |
2492 | rather a lot of output, but you can cut this down to specific areas. For | |
2493 | example, if you use -d-all+route only the debugging information relevant to | |
2494 | routing is included. (See the -d option in chapter 5 for more details.) | |
2495 | ||
2496 | One specific problem that has shown up on some sites is the inability to do | |
2497 | local deliveries into a shared mailbox directory, because it does not have the | |
2498 | "sticky bit" set on it. By default, Exim tries to create a lock file before | |
2499 | writing to a mailbox file, and if it cannot create the lock file, the delivery | |
2500 | is deferred. You can get round this either by setting the "sticky bit" on the | |
2501 | directory, or by setting a specific group for local deliveries and allowing | |
2502 | that group to create files in the directory (see the comments above the | |
2503 | local_delivery transport in the default configuration file). Another approach | |
2504 | is to configure Exim not to use lock files, but just to rely on fcntl() locking | |
2505 | instead. However, you should do this only if all user agents also use fcntl() | |
2506 | locking. For further discussion of locking issues, see chapter 26. | |
2507 | ||
2508 | One thing that cannot be tested on a system that is already running an MTA is | |
2509 | the receipt of incoming SMTP mail on the standard SMTP port. However, the -oX | |
2510 | option can be used to run an Exim daemon that listens on some other port, or | |
2511 | inetd can be used to do this. The -bh option and the exim_checkaccess utility | |
2512 | can be used to check out policy controls on incoming SMTP mail. | |
2513 | ||
2514 | Testing a new version on a system that is already running Exim can most easily | |
2515 | be done by building a binary with a different CONFIGURE_FILE setting. From | |
2516 | within the run time configuration, all other file and directory names that Exim | |
2517 | uses can be altered, in order to keep it entirely clear of the production | |
2518 | version. | |
2519 | ||
2520 | ||
2521 | 4.20 Replacing another MTA with Exim | |
2522 | ------------------------------------ | |
2523 | ||
2524 | Building and installing Exim for the first time does not of itself put it in | |
2525 | general use. The name by which the system's MTA is called by mail user agents | |
2526 | is either /usr/sbin/sendmail, or /usr/lib/sendmail (depending on the operating | |
2527 | system), and it is necessary to make this name point to the exim binary in | |
2528 | order to get the user agents to pass messages to Exim. This is normally done by | |
2529 | renaming any existing file and making /usr/sbin/sendmail or /usr/lib/sendmail a | |
2530 | symbolic link to the exim binary. It is a good idea to remove any setuid | |
2531 | privilege and executable status from the old MTA. It is then necessary to stop | |
2532 | and restart the mailer daemon, if one is running. | |
2533 | ||
2534 | Some operating systems have introduced alternative ways of switching MTAs. For | |
2535 | example, if you are running FreeBSD, you need to edit the file /etc/mail/ | |
2536 | mailer.conf instead of setting up a symbolic link as just described. A typical | |
2537 | example of the contents of this file for running Exim is as follows: | |
2538 | ||
2539 | sendmail /usr/exim/bin/exim | |
2540 | send-mail /usr/exim/bin/exim | |
2541 | mailq /usr/exim/bin/exim -bp | |
2542 | newaliases /usr/bin/true | |
2543 | ||
2544 | Once you have set up the symbolic link, or edited /etc/mail/mailer.conf, your | |
2545 | Exim installation is "live". Check it by sending a message from your favourite | |
2546 | user agent. | |
2547 | ||
2548 | You should consider what to tell your users about the change of MTA. Exim may | |
2549 | have different capabilities to what was previously running, and there are | |
2550 | various operational differences such as the text of messages produced by | |
2551 | command line options and in bounce messages. If you allow your users to make | |
2552 | use of Exim's filtering capabilities, you should make the document entitled | |
2553 | Exim's interface to mail filtering available to them. | |
2554 | ||
2555 | ||
2556 | 4.21 Upgrading Exim | |
2557 | ------------------- | |
2558 | ||
2559 | If you are already running Exim on your host, building and installing a new | |
2560 | version automatically makes it available to MUAs, or any other programs that | |
2561 | call the MTA directly. However, if you are running an Exim daemon, you do need | |
2562 | to send it a HUP signal, to make it re-execute itself, and thereby pick up the | |
2563 | new binary. You do not need to stop processing mail in order to install a new | |
2564 | version of Exim. The install script does not modify an existing runtime | |
2565 | configuration file. | |
2566 | ||
2567 | ||
2568 | 4.22 Stopping the Exim daemon on Solaris | |
2569 | ---------------------------------------- | |
2570 | ||
2571 | The standard command for stopping the mailer daemon on Solaris is | |
2572 | ||
2573 | /etc/init.d/sendmail stop | |
2574 | ||
2575 | If /usr/lib/sendmail has been turned into a symbolic link, this script fails to | |
2576 | stop Exim because it uses the command ps -e and greps the output for the text | |
2577 | "sendmail"; this is not present because the actual program name (that is, | |
2578 | "exim") is given by the ps command with these options. A solution is to replace | |
2579 | the line that finds the process id with something like | |
2580 | ||
2581 | pid=`cat /var/spool/exim/exim-daemon.pid` | |
2582 | ||
2583 | to obtain the daemon's pid directly from the file that Exim saves it in. | |
2584 | ||
2585 | Note, however, that stopping the daemon does not "stop Exim". Messages can | |
2586 | still be received from local processes, and if automatic delivery is configured | |
2587 | (the normal case), deliveries will still occur. | |
2588 | ||
2589 | ||
2590 | ||
2591 | =============================================================================== | |
2592 | 5. THE EXIM COMMAND LINE | |
2593 | ||
2594 | Exim's command line takes the standard Unix form of a sequence of options, each | |
2595 | starting with a hyphen character, followed by a number of arguments. The | |
2596 | options are compatible with the main options of Sendmail, and there are also | |
2597 | some additional options, some of which are compatible with Smail 3. Certain | |
2598 | combinations of options do not make sense, and provoke an error if used. The | |
2599 | form of the arguments depends on which options are set. | |
2600 | ||
2601 | ||
2602 | 5.1 Setting options by program name | |
2603 | ----------------------------------- | |
2604 | ||
2605 | If Exim is called under the name mailq, it behaves as if the option -bp were | |
2606 | present before any other options. The -bp option requests a listing of the | |
2607 | contents of the mail queue on the standard output. This feature is for | |
2608 | compatibility with some systems that contain a command of that name in one of | |
2609 | the standard libraries, symbolically linked to /usr/sbin/sendmail or /usr/lib/ | |
2610 | sendmail. | |
2611 | ||
2612 | If Exim is called under the name rsmtp it behaves as if the option -bS were | |
2613 | present before any other options, for compatibility with Smail. The -bS option | |
2614 | is used for reading in a number of messages in batched SMTP format. | |
2615 | ||
2616 | If Exim is called under the name rmail it behaves as if the -i and -oee options | |
2617 | were present before any other options, for compatibility with Smail. The name | |
2618 | rmail is used as an interface by some UUCP systems. | |
2619 | ||
2620 | If Exim is called under the name runq it behaves as if the option -q were | |
2621 | present before any other options, for compatibility with Smail. The -q option | |
2622 | causes a single queue runner process to be started. | |
2623 | ||
2624 | If Exim is called under the name newaliases it behaves as if the option -bi | |
2625 | were present before any other options, for compatibility with Sendmail. This | |
2626 | option is used for rebuilding Sendmail's alias file. Exim does not have the | |
2627 | concept of a single alias file, but can be configured to run a given command if | |
2628 | called with the -bi option. | |
2629 | ||
2630 | ||
2631 | 5.2 Trusted and admin users | |
2632 | --------------------------- | |
2633 | ||
2634 | Some Exim options are available only to trusted users and others are available | |
2635 | only to admin users. In the description below, the phrases "Exim user" and | |
2636 | "Exim group" mean the user and group defined by EXIM_USER and EXIM_GROUP in | |
2637 | Local/Makefile or set by the exim_user and exim_group options. These do not | |
2638 | necessarily have to use the name "exim". | |
2639 | ||
2640 | * The trusted users are root, the Exim user, any user listed in the | |
2641 | trusted_users configuration option, and any user whose current group or any | |
2642 | supplementary group is one of those listed in the trusted_groups | |
2643 | configuration option. Note that the Exim group is not automatically | |
2644 | trusted. | |
2645 | ||
2646 | Trusted users are always permitted to use the -f option or a leading | |
2647 | "From " line to specify the envelope sender of a message that is passed to | |
2648 | Exim through the local interface (see the -bm and -f options below). See | |
2649 | the untrusted_set_sender option for a way of permitting non-trusted users | |
2650 | to set envelope senders. | |
2651 | ||
2652 | For a trusted user, there is never any check on the contents of the From: | |
2653 | header line, and a Sender: line is never added. Furthermore, any existing | |
2654 | Sender: line in incoming local (non-TCP/IP) messages is not removed. | |
2655 | ||
2656 | Trusted users may also specify a host name, host address, interface | |
2657 | address, protocol name, ident value, and authentication data when | |
2658 | submitting a message locally. Thus, they are able to insert messages into | |
2659 | Exim's queue locally that have the characteristics of messages received | |
2660 | from a remote host. Untrusted users may in some circumstances use -f, but | |
2661 | can never set the other values that are available to trusted users. | |
2662 | ||
2663 | * The admin users are root, the Exim user, and any user that is a member of | |
2664 | the Exim group or of any group listed in the admin_groups configuration | |
2665 | option. The current group does not have to be one of these groups. | |
2666 | ||
2667 | Admin users are permitted to list the queue, and to carry out certain | |
2668 | operations on messages, for example, to force delivery failures. It is also | |
2669 | necessary to be an admin user in order to see the full information provided | |
2670 | by the Exim monitor, and full debugging output. | |
2671 | ||
2672 | By default, the use of the -M, -q, -R, and -S options to cause Exim to | |
2673 | attempt delivery of messages on its queue is restricted to admin users. | |
2674 | However, this restriction can be relaxed by setting the prod_requires_admin | |
2675 | option false (that is, specifying no_prod_requires_admin). | |
2676 | ||
2677 | Similarly, the use of the -bp option to list all the messages in the queue | |
2678 | is restricted to admin users unless queue_list_requires_admin is set false. | |
2679 | ||
2680 | Warning: If you configure your system so that admin users are able to edit | |
2681 | Exim's configuration file, you are giving those users an easy way of getting | |
2682 | root. There is further discussion of this issue at the start of chapter 6. | |
2683 | ||
2684 | ||
2685 | 5.3 Command line options | |
2686 | ------------------------ | |
2687 | ||
2688 | Exim's command line options are described in alphabetical order below. If none | |
2689 | of the options that specifies a specific action (such as starting the daemon or | |
2690 | a queue runner, or testing an address, or receiving a message in a specific | |
2691 | format, or listing the queue) are present, and there is at least one argument | |
2692 | on the command line, -bm (accept a local message on the standard input, with | |
2693 | the arguments specifying the recipients) is assumed. Otherwise, Exim outputs a | |
2694 | brief message about itself and exits. | |
2695 | ||
2696 | -- | |
2697 | ||
2698 | This is a pseudo-option whose only purpose is to terminate the options and | |
2699 | therefore to cause subsequent command line items to be treated as arguments | |
2700 | rather than options, even if they begin with hyphens. | |
2701 | ||
2702 | --help | |
2703 | ||
2704 | This option causes Exim to output a few sentences stating what it is. The | |
2705 | same output is generated if the Exim binary is called with no options and | |
2706 | no arguments. | |
2707 | ||
2708 | --version | |
2709 | ||
2710 | This option is an alias for -bV and causes version information to be | |
2711 | displayed. | |
2712 | ||
2713 | -Ac, -Am | |
2714 | ||
2715 | These options are used by Sendmail for selecting configuration files and | |
2716 | are ignored by Exim. | |
2717 | ||
2718 | -B<type> | |
2719 | ||
2720 | This is a Sendmail option for selecting 7 or 8 bit processing. Exim is | |
2721 | 8-bit clean; it ignores this option. | |
2722 | ||
2723 | -bd | |
2724 | ||
2725 | This option runs Exim as a daemon, awaiting incoming SMTP connections. | |
2726 | Usually the -bd option is combined with the -q<time> option, to specify | |
2727 | that the daemon should also initiate periodic queue runs. | |
2728 | ||
2729 | The -bd option can be used only by an admin user. If either of the -d | |
2730 | (debugging) or -v (verifying) options are set, the daemon does not | |
2731 | disconnect from the controlling terminal. When running this way, it can be | |
2732 | stopped by pressing ctrl-C. | |
2733 | ||
2734 | By default, Exim listens for incoming connections to the standard SMTP port | |
2735 | on all the host's running interfaces. However, it is possible to listen on | |
2736 | other ports, on multiple ports, and only on specific interfaces. Chapter 13 | |
2737 | contains a description of the options that control this. | |
2738 | ||
2739 | When a listening daemon is started without the use of -oX (that is, without | |
2740 | overriding the normal configuration), it writes its process id to a file | |
2741 | called exim-daemon.pid in Exim's spool directory. This location can be | |
2742 | overridden by setting PID_FILE_PATH in Local/Makefile. The file is written | |
2743 | while Exim is still running as root. | |
2744 | ||
2745 | When -oX is used on the command line to start a listening daemon, the | |
2746 | process id is not written to the normal pid file path. However, -oP can be | |
2747 | used to specify a path on the command line if a pid file is required. | |
2748 | ||
2749 | The SIGHUP signal can be used to cause the daemon to re-execute itself. | |
2750 | This should be done whenever Exim's configuration file, or any file that is | |
2751 | incorporated into it by means of the .include facility, is changed, and | |
2752 | also whenever a new version of Exim is installed. It is not necessary to do | |
2753 | this when other files that are referenced from the configuration (for | |
2754 | example, alias files) are changed, because these are reread each time they | |
2755 | are used. | |
2756 | ||
2757 | -bdf | |
2758 | ||
2759 | This option has the same effect as -bd except that it never disconnects | |
2760 | from the controlling terminal, even when no debugging is specified. | |
2761 | ||
2762 | -be | |
2763 | ||
2764 | Run Exim in expansion testing mode. Exim discards its root privilege, to | |
2765 | prevent ordinary users from using this mode to read otherwise inaccessible | |
2766 | files. If no arguments are given, Exim runs interactively, prompting for | |
2767 | lines of data. Otherwise, it processes each argument in turn. | |
2768 | ||
2769 | If Exim was built with USE_READLINE=yes in Local/Makefile, it tries to load | |
2770 | the libreadline library dynamically whenever the -be option is used without | |
2771 | command line arguments. If successful, it uses the readline() function, | |
2772 | which provides extensive line-editing facilities, for reading the test | |
2773 | data. A line history is supported. | |
2774 | ||
2775 | Long expansion expressions can be split over several lines by using | |
2776 | backslash continuations. As in Exim's run time configuration, white space | |
2777 | at the start of continuation lines is ignored. Each argument or data line | |
2778 | is passed through the string expansion mechanism, and the result is output. | |
2779 | Variable values from the configuration file (for example, $qualify_domain) | |
2813c06e CE |
2780 | are available, but no message-specific values (such as $message_exim_id) |
2781 | are set, because no message is being processed (but see -bem and -Mset). | |
420a0d19 CE |
2782 | |
2783 | Note: If you use this mechanism to test lookups, and you change the data | |
2784 | files or databases you are using, you must exit and restart Exim before | |
2785 | trying the same lookup again. Otherwise, because each Exim process caches | |
2786 | the results of lookups, you will just get the same result as before. | |
2787 | ||
2788 | -bem <filename> | |
2789 | ||
2790 | This option operates like -be except that it must be followed by the name | |
2791 | of a file. For example: | |
2792 | ||
2793 | exim -bem /tmp/testmessage | |
2794 | ||
2795 | The file is read as a message (as if receiving a locally-submitted non-SMTP | |
2796 | message) before any of the test expansions are done. Thus, message-specific | |
2797 | variables such as $message_size and $header_from: are available. However, | |
2798 | no Received: header is added to the message. If the -t option is set, | |
2799 | recipients are read from the headers in the normal way, and are shown in | |
2800 | the $recipients variable. Note that recipients cannot be given on the | |
2801 | command line, because further arguments are taken as strings to expand | |
2802 | (just like -be). | |
2803 | ||
2804 | -bF <filename> | |
2805 | ||
2806 | This option is the same as -bf except that it assumes that the filter being | |
2807 | tested is a system filter. The additional commands that are available only | |
2808 | in system filters are recognized. | |
2809 | ||
2810 | -bf <filename> | |
2811 | ||
2812 | This option runs Exim in user filter testing mode; the file is the filter | |
2813 | file to be tested, and a test message must be supplied on the standard | |
2814 | input. If there are no message-dependent tests in the filter, an empty file | |
2815 | can be supplied. | |
2816 | ||
2817 | If you want to test a system filter file, use -bF instead of -bf. You can | |
2818 | use both -bF and -bf on the same command, in order to test a system filter | |
2819 | and a user filter in the same run. For example: | |
2820 | ||
2821 | exim -bF /system/filter -bf /user/filter </test/message | |
2822 | ||
2823 | This is helpful when the system filter adds header lines or sets filter | |
2824 | variables that are used by the user filter. | |
2825 | ||
2826 | If the test filter file does not begin with one of the special lines | |
2827 | ||
2828 | # Exim filter | |
2829 | # Sieve filter | |
2830 | ||
2831 | it is taken to be a normal .forward file, and is tested for validity under | |
2832 | that interpretation. See sections 22.4 to 22.6 for a description of the | |
2833 | possible contents of non-filter redirection lists. | |
2834 | ||
2835 | The result of an Exim command that uses -bf, provided no errors are | |
2836 | detected, is a list of the actions that Exim would try to take if presented | |
2837 | with the message for real. More details of filter testing are given in the | |
2838 | separate document entitled Exim's interfaces to mail filtering. | |
2839 | ||
2840 | When testing a filter file, the envelope sender can be set by the -f | |
2841 | option, or by a "From " line at the start of the test message. Various | |
2842 | parameters that would normally be taken from the envelope recipient address | |
2843 | of the message can be set by means of additional command line options (see | |
2844 | the next four options). | |
2845 | ||
2846 | -bfd <domain> | |
2847 | ||
2848 | This sets the domain of the recipient address when a filter file is being | |
2849 | tested by means of the -bf option. The default is the value of | |
2850 | $qualify_domain. | |
2851 | ||
2852 | -bfl <local part> | |
2853 | ||
2854 | This sets the local part of the recipient address when a filter file is | |
2855 | being tested by means of the -bf option. The default is the username of the | |
2856 | process that calls Exim. A local part should be specified with any prefix | |
2857 | or suffix stripped, because that is how it appears to the filter when a | |
2858 | message is actually being delivered. | |
2859 | ||
2860 | -bfp <prefix> | |
2861 | ||
2862 | This sets the prefix of the local part of the recipient address when a | |
2863 | filter file is being tested by means of the -bf option. The default is an | |
2864 | empty prefix. | |
2865 | ||
2866 | -bfs <suffix> | |
2867 | ||
2868 | This sets the suffix of the local part of the recipient address when a | |
2869 | filter file is being tested by means of the -bf option. The default is an | |
2870 | empty suffix. | |
2871 | ||
2872 | -bh <IP address> | |
2873 | ||
2874 | This option runs a fake SMTP session as if from the given IP address, using | |
2875 | the standard input and output. The IP address may include a port number at | |
2876 | the end, after a full stop. For example: | |
2877 | ||
2878 | exim -bh 10.9.8.7.1234 | |
2879 | exim -bh fe80::a00:20ff:fe86:a061.5678 | |
2880 | ||
2881 | When an IPv6 address is given, it is converted into canonical form. In the | |
2882 | case of the second example above, the value of $sender_host_address after | |
2883 | conversion to the canonical form is | |
2884 | "fe80:0000:0000:0a00:20ff:fe86:a061.5678". | |
2885 | ||
2886 | Comments as to what is going on are written to the standard error file. | |
2887 | These include lines beginning with "LOG" for anything that would have been | |
2888 | logged. This facility is provided for testing configuration options for | |
2889 | incoming messages, to make sure they implement the required policy. For | |
2890 | example, you can test your relay controls using -bh. | |
2891 | ||
2892 | Warning 1: You can test features of the configuration that rely on ident | |
2893 | (RFC 1413) information by using the -oMt option. However, Exim cannot | |
2894 | actually perform an ident callout when testing using -bh because there is | |
2895 | no incoming SMTP connection. | |
2896 | ||
2813c06e | 2897 | Warning 2: Address verification callouts (see section 43.45) are also |
420a0d19 CE |
2898 | skipped when testing using -bh. If you want these callouts to occur, use |
2899 | -bhc instead. | |
2900 | ||
2901 | Messages supplied during the testing session are discarded, and nothing is | |
2902 | written to any of the real log files. There may be pauses when DNS (and | |
2903 | other) lookups are taking place, and of course these may time out. The -oMi | |
2904 | option can be used to specify a specific IP interface and port if this is | |
2905 | important, and -oMaa and -oMai can be used to set parameters as if the SMTP | |
2906 | session were authenticated. | |
2907 | ||
2908 | The exim_checkaccess utility is a "packaged" version of -bh whose output | |
2909 | just states whether a given recipient address from a given host is | |
2813c06e | 2910 | acceptable or not. See section 53.8. |
420a0d19 CE |
2911 | |
2912 | Features such as authentication and encryption, where the client input is | |
2913 | not plain text, cannot easily be tested with -bh. Instead, you should use a | |
2914 | specialized SMTP test program such as swaks. | |
2915 | ||
2916 | -bhc <IP address> | |
2917 | ||
2918 | This option operates in the same way as -bh, except that address | |
2919 | verification callouts are performed if required. This includes consulting | |
2920 | and updating the callout cache database. | |
2921 | ||
2922 | -bi | |
2923 | ||
2924 | Sendmail interprets the -bi option as a request to rebuild its alias file. | |
2925 | Exim does not have the concept of a single alias file, and so it cannot | |
2926 | mimic this behaviour. However, calls to /usr/lib/sendmail with the -bi | |
2927 | option tend to appear in various scripts such as NIS make files, so the | |
2928 | option must be recognized. | |
2929 | ||
2930 | If -bi is encountered, the command specified by the bi_command | |
2931 | configuration option is run, under the uid and gid of the caller of Exim. | |
2932 | If the -oA option is used, its value is passed to the command as an | |
2933 | argument. The command set by bi_command may not contain arguments. The | |
2934 | command can use the exim_dbmbuild utility, or some other means, to rebuild | |
2935 | alias files if this is required. If the bi_command option is not set, | |
2936 | calling Exim with -bi is a no-op. | |
2937 | ||
2938 | -bI:help | |
2939 | ||
2940 | We shall provide various options starting "-bI:" for querying Exim for | |
2941 | information. The output of many of these will be intended for machine | |
2942 | consumption. This one is not. The -bI:help option asks Exim for a synopsis | |
2943 | of supported options beginning "-bI:". Use of any of these options shall | |
2944 | cause Exim to exit after producing the requested output. | |
2945 | ||
2946 | -bI:dscp | |
2947 | ||
2948 | This option causes Exim to emit an alphabetically sorted list of all | |
2949 | recognised DSCP names. | |
2950 | ||
2951 | -bI:sieve | |
2952 | ||
2953 | This option causes Exim to emit an alphabetically sorted list of all | |
2954 | supported Sieve protocol extensions on stdout, one per line. This is | |
2955 | anticipated to be useful for ManageSieve (RFC 5804) implementations, in | |
2956 | providing that protocol's "SIEVE" capability response line. As the precise | |
2957 | list may depend upon compile-time build options, which this option will | |
2958 | adapt to, this is the only way to guarantee a correct response. | |
2959 | ||
2960 | -bm | |
2961 | ||
2962 | This option runs an Exim receiving process that accepts an incoming, | |
2963 | locally-generated message on the standard input. The recipients are given | |
2964 | as the command arguments (except when -t is also present - see below). Each | |
2965 | argument can be a comma-separated list of RFC 2822 addresses. This is the | |
2966 | default option for selecting the overall action of an Exim call; it is | |
2967 | assumed if no other conflicting option is present. | |
2968 | ||
2969 | If any addresses in the message are unqualified (have no domain), they are | |
2970 | qualified by the values of the qualify_domain or qualify_recipient options, | |
2971 | as appropriate. The -bnq option (see below) provides a way of suppressing | |
2972 | this for special cases. | |
2973 | ||
2974 | Policy checks on the contents of local messages can be enforced by means of | |
2813c06e | 2975 | the non-SMTP ACL. See chapter 43 for details. |
420a0d19 CE |
2976 | |
2977 | The return code is zero if the message is successfully accepted. Otherwise, | |
2978 | the action is controlled by the -oex option setting - see below. | |
2979 | ||
2980 | The format of the message must be as defined in RFC 2822, except that, for | |
2981 | compatibility with Sendmail and Smail, a line in one of the forms | |
2982 | ||
2983 | From sender Fri Jan 5 12:55 GMT 1997 | |
2984 | From sender Fri, 5 Jan 97 12:55:01 | |
2985 | ||
2986 | (with the weekday optional, and possibly with additional text after the | |
2987 | date) is permitted to appear at the start of the message. There appears to | |
2988 | be no authoritative specification of the format of this line. Exim | |
2989 | recognizes it by matching against the regular expression defined by the | |
2990 | uucp_from_pattern option, which can be changed if necessary. | |
2991 | ||
2992 | The specified sender is treated as if it were given as the argument to the | |
2993 | -f option, but if a -f option is also present, its argument is used in | |
2994 | preference to the address taken from the message. The caller of Exim must | |
2995 | be a trusted user for the sender of a message to be set in this way. | |
2996 | ||
2997 | -bmalware <filename> | |
2998 | ||
2813c06e CE |
2999 | This debugging option causes Exim to scan the given file or directory |
3000 | (depending on the used scanner interface), using the malware scanning | |
3001 | framework. The option of av_scanner influences this option, so if | |
420a0d19 CE |
3002 | av_scanner's value is dependent upon an expansion then the expansion should |
3003 | have defaults which apply to this invocation. ACLs are not invoked, so if | |
3004 | av_scanner references an ACL variable then that variable will never be | |
3005 | populated and -bmalware will fail. | |
3006 | ||
3007 | Exim will have changed working directory before resolving the filename, so | |
3008 | using fully qualified pathnames is advisable. Exim will be running as the | |
3009 | Exim user when it tries to open the file, rather than as the invoking user. | |
3010 | This option requires admin privileges. | |
3011 | ||
3012 | The -bmalware option will not be extended to be more generally useful, | |
3013 | there are better tools for file-scanning. This option exists to help | |
3014 | administrators verify their Exim and AV scanner configuration. | |
3015 | ||
3016 | -bnq | |
3017 | ||
3018 | By default, Exim automatically qualifies unqualified addresses (those | |
3019 | without domains) that appear in messages that are submitted locally (that | |
3020 | is, not over TCP/IP). This qualification applies both to addresses in | |
3021 | envelopes, and addresses in header lines. Sender addresses are qualified | |
3022 | using qualify_domain, and recipient addresses using qualify_recipient | |
3023 | (which defaults to the value of qualify_domain). | |
3024 | ||
3025 | Sometimes, qualification is not wanted. For example, if -bS (batch SMTP) is | |
3026 | being used to re-submit messages that originally came from remote hosts | |
3027 | after content scanning, you probably do not want to qualify unqualified | |
3028 | addresses in header lines. (Such lines will be present only if you have not | |
3029 | enabled a header syntax check in the appropriate ACL.) | |
3030 | ||
3031 | The -bnq option suppresses all qualification of unqualified addresses in | |
3032 | messages that originate on the local host. When this is used, unqualified | |
3033 | addresses in the envelope provoke errors (causing message rejection) and | |
3034 | unqualified addresses in header lines are left alone. | |
3035 | ||
3036 | -bP | |
3037 | ||
3038 | If this option is given with no arguments, it causes the values of all | |
3039 | Exim's main configuration options to be written to the standard output. The | |
3040 | values of one or more specific options can be requested by giving their | |
3041 | names as arguments, for example: | |
3042 | ||
3043 | exim -bP qualify_domain hold_domains | |
3044 | ||
3045 | However, any option setting that is preceded by the word "hide" in the | |
3046 | configuration file is not shown in full, except to an admin user. For other | |
3047 | users, the output is as in this example: | |
3048 | ||
3049 | mysql_servers = <value not displayable> | |
3050 | ||
2813c06e CE |
3051 | If config is given as an argument, the config is output, as it was parsed, |
3052 | any include file resolved, any comment removed. | |
3053 | ||
3054 | If config_file is given as an argument, the name of the run time | |
3055 | configuration file is output. (configure_file works too, for backward | |
3056 | compatibility.) If a list of configuration files was supplied, the value | |
3057 | that is output here is the name of the file that was actually used. | |
420a0d19 CE |
3058 | |
3059 | If the -n flag is given, then for most modes of -bP operation the name will | |
3060 | not be output. | |
3061 | ||
3062 | If log_file_path or pid_file_path are given, the names of the directories | |
3063 | where log files and daemon pid files are written are output, respectively. | |
3064 | If these values are unset, log files are written in a sub-directory of the | |
3065 | spool directory called log, and the pid file is written directly into the | |
3066 | spool directory. | |
3067 | ||
3068 | If -bP is followed by a name preceded by "+", for example, | |
3069 | ||
3070 | exim -bP +local_domains | |
3071 | ||
3072 | it searches for a matching named list of any type (domain, host, address, | |
3073 | or local part) and outputs what it finds. | |
3074 | ||
3075 | If one of the words router, transport, or authenticator is given, followed | |
3076 | by the name of an appropriate driver instance, the option settings for that | |
3077 | driver are output. For example: | |
3078 | ||
3079 | exim -bP transport local_delivery | |
3080 | ||
3081 | The generic driver options are output first, followed by the driver's | |
3082 | private options. A list of the names of drivers of a particular type can be | |
3083 | obtained by using one of the words router_list, transport_list, or | |
3084 | authenticator_list, and a complete list of all drivers with their option | |
3085 | settings can be obtained by using routers, transports, or authenticators. | |
3086 | ||
2813c06e CE |
3087 | If environment is given as an argument, the set of environment variables is |
3088 | output, line by line. Using the -n flag suppresses the value of the | |
3089 | variables. | |
3090 | ||
420a0d19 CE |
3091 | If invoked by an admin user, then macro, macro_list and macros are |
3092 | available, similarly to the drivers. Because macros are sometimes used for | |
3093 | storing passwords, this option is restricted. The output format is one item | |
3094 | per line. | |
3095 | ||
3096 | -bp | |
3097 | ||
3098 | This option requests a listing of the contents of the mail queue on the | |
3099 | standard output. If the -bp option is followed by a list of message ids, | |
3100 | just those messages are listed. By default, this option can be used only by | |
3101 | an admin user. However, the queue_list_requires_admin option can be set | |
3102 | false to allow any user to see the queue. | |
3103 | ||
3104 | Each message on the queue is displayed as in the following example: | |
3105 | ||
3106 | 25m 2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example> | |
3107 | red.king@looking-glass.fict.example | |
3108 | <other addresses> | |
3109 | ||
3110 | The first line contains the length of time the message has been on the | |
3111 | queue (in this case 25 minutes), the size of the message (2.9K), the unique | |
3112 | local identifier for the message, and the message sender, as contained in | |
3113 | the envelope. For bounce messages, the sender address is empty, and appears | |
3114 | as "<>". If the message was submitted locally by an untrusted user who | |
3115 | overrode the default sender address, the user's login name is shown in | |
3116 | parentheses before the sender address. | |
3117 | ||
3118 | If the message is frozen (attempts to deliver it are suspended) then the | |
3119 | text "*** frozen ***" is displayed at the end of this line. | |
3120 | ||
3121 | The recipients of the message (taken from the envelope, not the headers) | |
3122 | are displayed on subsequent lines. Those addresses to which the message has | |
3123 | already been delivered are marked with the letter D. If an original address | |
3124 | gets expanded into several addresses via an alias or forward file, the | |
3125 | original is displayed with a D only when deliveries for all of its child | |
3126 | addresses are complete. | |
3127 | ||
3128 | -bpa | |
3129 | ||
3130 | This option operates like -bp, but in addition it shows delivered addresses | |
3131 | that were generated from the original top level address(es) in each message | |
3132 | by alias or forwarding operations. These addresses are flagged with "+D" | |
3133 | instead of just "D". | |
3134 | ||
3135 | -bpc | |
3136 | ||
3137 | This option counts the number of messages on the queue, and writes the | |
3138 | total to the standard output. It is restricted to admin users, unless | |
3139 | queue_list_requires_admin is set false. | |
3140 | ||
3141 | -bpr | |
3142 | ||
3143 | This option operates like -bp, but the output is not sorted into | |
3144 | chronological order of message arrival. This can speed it up when there are | |
3145 | lots of messages on the queue, and is particularly useful if the output is | |
3146 | going to be post-processed in a way that doesn't need the sorting. | |
3147 | ||
3148 | -bpra | |
3149 | ||
3150 | This option is a combination of -bpr and -bpa. | |
3151 | ||
3152 | -bpru | |
3153 | ||
3154 | This option is a combination of -bpr and -bpu. | |
3155 | ||
3156 | -bpu | |
3157 | ||
3158 | This option operates like -bp but shows only undelivered top-level | |
3159 | addresses for each message displayed. Addresses generated by aliasing or | |
3160 | forwarding are not shown, unless the message was deferred after processing | |
3161 | by a router with the one_time option set. | |
3162 | ||
3163 | -brt | |
3164 | ||
3165 | This option is for testing retry rules, and it must be followed by up to | |
3166 | three arguments. It causes Exim to look for a retry rule that matches the | |
3167 | values and to write it to the standard output. For example: | |
3168 | ||
3169 | exim -brt bach.comp.mus.example | |
3170 | Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m; | |
3171 | ||
3172 | See chapter 32 for a description of Exim's retry rules. The first argument, | |
3173 | which is required, can be a complete address in the form local_part@domain, | |
3174 | or it can be just a domain name. If the second argument contains a dot, it | |
3175 | is interpreted as an optional second domain name; if no retry rule is found | |
3176 | for the first argument, the second is tried. This ties in with Exim's | |
3177 | behaviour when looking for retry rules for remote hosts - if no rule is | |
3178 | found that matches the host, one that matches the mail domain is sought. | |
3179 | Finally, an argument that is the name of a specific delivery error, as used | |
3180 | in setting up retry rules, can be given. For example: | |
3181 | ||
3182 | exim -brt haydn.comp.mus.example quota_3d | |
3183 | Retry rule: *@haydn.comp.mus.example quota_3d F,1h,15m | |
3184 | ||
3185 | -brw | |
3186 | ||
3187 | This option is for testing address rewriting rules, and it must be followed | |
3188 | by a single argument, consisting of either a local part without a domain, | |
3189 | or a complete address with a fully qualified domain. Exim outputs how this | |
3190 | address would be rewritten for each possible place it might appear. See | |
3191 | chapter 31 for further details. | |
3192 | ||
3193 | -bS | |
3194 | ||
3195 | This option is used for batched SMTP input, which is an alternative | |
3196 | interface for non-interactive local message submission. A number of | |
3197 | messages can be submitted in a single run. However, despite its name, this | |
3198 | is not really SMTP input. Exim reads each message's envelope from SMTP | |
3199 | commands on the standard input, but generates no responses. If the caller | |
3200 | is trusted, or untrusted_set_sender is set, the senders in the SMTP MAIL | |
3201 | commands are believed; otherwise the sender is always the caller of Exim. | |
3202 | ||
3203 | The message itself is read from the standard input, in SMTP format (leading | |
3204 | dots doubled), terminated by a line containing just a single dot. An error | |
3205 | is provoked if the terminating dot is missing. A further message may then | |
3206 | follow. | |
3207 | ||
3208 | As for other local message submissions, the contents of incoming batch SMTP | |
2813c06e | 3209 | messages can be checked using the non-SMTP ACL (see chapter 43). |
420a0d19 CE |
3210 | Unqualified addresses are automatically qualified using qualify_domain and |
3211 | qualify_recipient, as appropriate, unless the -bnq option is used. | |
3212 | ||
3213 | Some other SMTP commands are recognized in the input. HELO and EHLO act as | |
3214 | RSET; VRFY, EXPN, ETRN, and HELP act as NOOP; QUIT quits, ignoring the rest | |
3215 | of the standard input. | |
3216 | ||
3217 | If any error is encountered, reports are written to the standard output and | |
3218 | error streams, and Exim gives up immediately. The return code is 0 if no | |
3219 | error was detected; it is 1 if one or more messages were accepted before | |
3220 | the error was detected; otherwise it is 2. | |
3221 | ||
2813c06e | 3222 | More details of input using batched SMTP are given in section 48.11. |
420a0d19 CE |
3223 | |
3224 | -bs | |
3225 | ||
3226 | This option causes Exim to accept one or more messages by reading SMTP | |
3227 | commands on the standard input, and producing SMTP replies on the standard | |
2813c06e | 3228 | output. SMTP policy controls, as defined in ACLs (see chapter 43) are |
420a0d19 CE |
3229 | applied. Some user agents use this interface as a way of passing |
3230 | locally-generated messages to the MTA. | |
3231 | ||
3232 | In this usage, if the caller of Exim is trusted, or untrusted_set_sender is | |
3233 | set, the senders of messages are taken from the SMTP MAIL commands. | |
3234 | Otherwise the content of these commands is ignored and the sender is set up | |
3235 | as the calling user. Unqualified addresses are automatically qualified | |
3236 | using qualify_domain and qualify_recipient, as appropriate, unless the -bnq | |
3237 | option is used. | |
3238 | ||
3239 | The -bs option is also used to run Exim from inetd, as an alternative to | |
3240 | using a listening daemon. Exim can distinguish the two cases by checking | |
3241 | whether the standard input is a TCP/IP socket. When Exim is called from | |
3242 | inetd, the source of the mail is assumed to be remote, and the comments | |
3243 | above concerning senders and qualification do not apply. In this situation, | |
3244 | Exim behaves in exactly the same way as it does when receiving a message | |
3245 | via the listening daemon. | |
3246 | ||
3247 | -bt | |
3248 | ||
3249 | This option runs Exim in address testing mode, in which each argument is | |
3250 | taken as a recipient address to be tested for deliverability. The results | |
3251 | are written to the standard output. If a test fails, and the caller is not | |
3252 | an admin user, no details of the failure are output, because these might | |
3253 | contain sensitive information such as usernames and passwords for database | |
3254 | lookups. | |
3255 | ||
3256 | If no arguments are given, Exim runs in an interactive manner, prompting | |
3257 | with a right angle bracket for addresses to be tested. | |
3258 | ||
3259 | Unlike the -be test option, you cannot arrange for Exim to use the readline | |
3260 | () function, because it is running as root and there are security issues. | |
3261 | ||
3262 | Each address is handled as if it were the recipient address of a message | |
3263 | (compare the -bv option). It is passed to the routers and the result is | |
3264 | written to the standard output. However, any router that has | |
3265 | no_address_test set is bypassed. This can make -bt easier to use for | |
3266 | genuine routing tests if your first router passes everything to a scanner | |
3267 | program. | |
3268 | ||
3269 | The return code is 2 if any address failed outright; it is 1 if no address | |
3270 | failed outright but at least one could not be resolved for some reason. | |
3271 | Return code 0 is given only when all addresses succeed. | |
3272 | ||
3273 | Note: When actually delivering a message, Exim removes duplicate recipient | |
3274 | addresses after routing is complete, so that only one delivery takes place. | |
3275 | This does not happen when testing with -bt; the full results of routing are | |
3276 | always shown. | |
3277 | ||
3278 | Warning: -bt can only do relatively simple testing. If any of the routers | |
3279 | in the configuration makes any tests on the sender address of a message, | |
3280 | you can use the -f option to set an appropriate sender when running -bt | |
3281 | tests. Without it, the sender is assumed to be the calling user at the | |
3282 | default qualifying domain. However, if you have set up (for example) | |
3283 | routers whose behaviour depends on the contents of an incoming message, you | |
3284 | cannot test those conditions using -bt. The -N option provides a possible | |
3285 | way of doing such tests. | |
3286 | ||
3287 | -bV | |
3288 | ||
3289 | This option causes Exim to write the current version number, compilation | |
3290 | number, and compilation date of the exim binary to the standard output. It | |
3291 | also lists the DBM library that is being used, the optional modules (such | |
3292 | as specific lookup types), the drivers that are included in the binary, and | |
3293 | the name of the run time configuration file that is in use. | |
3294 | ||
3295 | As part of its operation, -bV causes Exim to read and syntax check its | |
3296 | configuration file. However, this is a static check only. It cannot check | |
3297 | values that are to be expanded. For example, although a misspelt ACL verb | |
3298 | is detected, an error in the verb's arguments is not. You cannot rely on | |
3299 | -bV alone to discover (for example) all the typos in the configuration; | |
3300 | some realistic testing is needed. The -bh and -N options provide more | |
3301 | dynamic testing facilities. | |
3302 | ||
3303 | -bv | |
3304 | ||
3305 | This option runs Exim in address verification mode, in which each argument | |
3306 | is taken as a recipient address to be verified by the routers. (This does | |
3307 | not involve any verification callouts). During normal operation, | |
3308 | verification happens mostly as a consequence processing a verify condition | |
2813c06e | 3309 | in an ACL (see chapter 43). If you want to test an entire ACL, possibly |
420a0d19 CE |
3310 | including callouts, see the -bh and -bhc options. |
3311 | ||
3312 | If verification fails, and the caller is not an admin user, no details of | |
3313 | the failure are output, because these might contain sensitive information | |
3314 | such as usernames and passwords for database lookups. | |
3315 | ||
3316 | If no arguments are given, Exim runs in an interactive manner, prompting | |
3317 | with a right angle bracket for addresses to be verified. | |
3318 | ||
3319 | Unlike the -be test option, you cannot arrange for Exim to use the readline | |
3320 | () function, because it is running as exim and there are security issues. | |
3321 | ||
3322 | Verification differs from address testing (the -bt option) in that routers | |
3323 | that have no_verify set are skipped, and if the address is accepted by a | |
3324 | router that has fail_verify set, verification fails. The address is | |
3325 | verified as a recipient if -bv is used; to test verification for a sender | |
3326 | address, -bvs should be used. | |
3327 | ||
3328 | If the -v option is not set, the output consists of a single line for each | |
3329 | address, stating whether it was verified or not, and giving a reason in the | |
3330 | latter case. Without -v, generating more than one address by redirection | |
3331 | causes verification to end successfully, without considering the generated | |
3332 | addresses. However, if just one address is generated, processing continues, | |
3333 | and the generated address must verify successfully for the overall | |
3334 | verification to succeed. | |
3335 | ||
3336 | When -v is set, more details are given of how the address has been handled, | |
3337 | and in the case of address redirection, all the generated addresses are | |
3338 | also considered. Verification may succeed for some and fail for others. | |
3339 | ||
3340 | The return code is 2 if any address failed outright; it is 1 if no address | |
3341 | failed outright but at least one could not be resolved for some reason. | |
3342 | Return code 0 is given only when all addresses succeed. | |
3343 | ||
3344 | If any of the routers in the configuration makes any tests on the sender | |
3345 | address of a message, you should use the -f option to set an appropriate | |
3346 | sender when running -bv tests. Without it, the sender is assumed to be the | |
3347 | calling user at the default qualifying domain. | |
3348 | ||
3349 | -bvs | |
3350 | ||
3351 | This option acts like -bv, but verifies the address as a sender rather than | |
3352 | a recipient address. This affects any rewriting and qualification that | |
3353 | might happen. | |
3354 | ||
3355 | -bw | |
3356 | ||
3357 | This option runs Exim as a daemon, awaiting incoming SMTP connections, | |
3358 | similarly to the -bd option. All port specifications on the command-line | |
3359 | and in the configuration file are ignored. Queue-running may not be | |
3360 | specified. | |
3361 | ||
3362 | In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is | |
3363 | listening for connections. This permits the system to start up and have | |
3364 | inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for | |
3365 | each port only when the first connection is received. | |
3366 | ||
3367 | If the option is given as -bw<time> then the time is a timeout, after which | |
3368 | the daemon will exit, which should cause inetd to listen once more. | |
3369 | ||
3370 | -C <filelist> | |
3371 | ||
3372 | This option causes Exim to find the run time configuration file from the | |
3373 | given list instead of from the list specified by the CONFIGURE_FILE | |
3374 | compile-time setting. Usually, the list will consist of just a single file | |
3375 | name, but it can be a colon-separated list of names. In this case, the | |
3376 | first file that exists is used. Failure to open an existing file stops Exim | |
3377 | from proceeding any further along the list, and an error is generated. | |
3378 | ||
3379 | When this option is used by a caller other than root, and the list is | |
3380 | different from the compiled-in list, Exim gives up its root privilege | |
3381 | immediately, and runs with the real and effective uid and gid set to those | |
3382 | of the caller. However, if a TRUSTED_CONFIG_LIST file is defined in Local/ | |
3383 | Makefile, that file contains a list of full pathnames, one per line, for | |
3384 | configuration files which are trusted. Root privilege is retained for any | |
3385 | configuration file so listed, as long as the caller is the Exim user (or | |
3386 | the user specified in the CONFIGURE_OWNER option, if any), and as long as | |
3387 | the configuration file is not writeable by inappropriate users or groups. | |
3388 | ||
3389 | Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a | |
3390 | configuration using -C right through message reception and delivery, even | |
3391 | if the caller is root. The reception works, but by that time, Exim is | |
3392 | running as the Exim user, so when it re-executes to regain privilege for | |
3393 | the delivery, the use of -C causes privilege to be lost. However, root can | |
3394 | test reception and delivery using two separate commands (one to put a | |
3395 | message on the queue, using -odq, and another to do the delivery, using -M | |
3396 | ). | |
3397 | ||
3398 | If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix | |
3399 | string with which any file named in a -C command line option must start. In | |
3400 | addition, the file name must not contain the sequence "/../". However, if | |
3401 | the value of the -C option is identical to the value of CONFIGURE_FILE in | |
3402 | Local/Makefile, Exim ignores -C and proceeds as usual. There is no default | |
3403 | setting for ALT_CONFIG_PREFIX; when it is unset, any file name can be used | |
3404 | with -C. | |
3405 | ||
3406 | ALT_CONFIG_PREFIX can be used to confine alternative configuration files to | |
3407 | a directory to which only root has access. This prevents someone who has | |
3408 | broken into the Exim account from running a privileged Exim with an | |
3409 | arbitrary configuration file. | |
3410 | ||
3411 | The -C facility is useful for ensuring that configuration files are | |
3412 | syntactically correct, but cannot be used for test deliveries, unless the | |
3413 | caller is privileged, or unless it is an exotic configuration that does not | |
3414 | require privilege. No check is made on the owner or group of the files | |
3415 | specified by this option. | |
3416 | ||
3417 | -D<macro>=<value> | |
3418 | ||
3419 | This option can be used to override macro definitions in the configuration | |
3420 | file (see section 6.4). However, like -C, if it is used by an unprivileged | |
3421 | caller, it causes Exim to give up its root privilege. If DISABLE_D_OPTION | |
3422 | is defined in Local/Makefile, the use of -D is completely disabled, and its | |
3423 | use causes an immediate error exit. | |
3424 | ||
3425 | If WHITELIST_D_MACROS is defined in Local/Makefile then it should be a | |
3426 | colon-separated list of macros which are considered safe and, if -D only | |
3427 | supplies macros from this list, and the values are acceptable, then Exim | |
3428 | will not give up root privilege if the caller is root, the Exim run-time | |
3429 | user, or the CONFIGURE_OWNER, if set. This is a transition mechanism and is | |
3430 | expected to be removed in the future. Acceptable values for the macros | |
3431 | satisfy the regexp: "^[A-Za-z0-9_/.-]*$" | |
3432 | ||
3433 | The entire option (including equals sign if present) must all be within one | |
3434 | command line item. -D can be used to set the value of a macro to the empty | |
3435 | string, in which case the equals sign is optional. These two commands are | |
3436 | synonymous: | |
3437 | ||
3438 | exim -DABC ... | |
3439 | exim -DABC= ... | |
3440 | ||
3441 | To include spaces in a macro definition item, quotes must be used. If you | |
3442 | use quotes, spaces are permitted around the macro name and the equals sign. | |
3443 | For example: | |
3444 | ||
3445 | exim '-D ABC = something' ... | |
3446 | ||
2813c06e CE |
3447 | -D may be repeated up to 10 times on a command line. Only macro names up to |
3448 | 22 letters long can be set. | |
420a0d19 CE |
3449 | |
3450 | -d<debug options> | |
3451 | ||
3452 | This option causes debugging information to be written to the standard | |
3453 | error stream. It is restricted to admin users because debugging output may | |
3454 | show database queries that contain password information. Also, the details | |
3455 | of users' filter files should be protected. If a non-admin user uses -d, | |
3456 | Exim writes an error message to the standard error stream and exits with a | |
3457 | non-zero return code. | |
3458 | ||
3459 | When -d is used, -v is assumed. If -d is given on its own, a lot of | |
3460 | standard debugging data is output. This can be reduced, or increased to | |
3461 | include some more rarely needed information, by directly following -d with | |
3462 | a string made up of names preceded by plus or minus characters. These add | |
3463 | or remove sets of debugging data, respectively. For example, -d+filter adds | |
3464 | filter debugging, whereas -d-all+filter selects only filter debugging. Note | |
3465 | that no spaces are allowed in the debug setting. The available debugging | |
3466 | categories are: | |
3467 | ||
3468 | acl ACL interpretation | |
3469 | auth authenticators | |
3470 | deliver general delivery logic | |
3471 | dns DNS lookups (see also resolver) | |
3472 | dnsbl DNS black list (aka RBL) code | |
3473 | exec arguments for execv() calls | |
3474 | expand detailed debugging for string expansions | |
3475 | filter filter handling | |
3476 | hints_lookup hints data lookups | |
3477 | host_lookup all types of name-to-IP address handling | |
3478 | ident ident lookup | |
3479 | interface lists of local interfaces | |
3480 | lists matching things in lists | |
3481 | load system load checks | |
2813c06e | 3482 | local_scan can be used by local_scan() (see chapter 45) |
420a0d19 CE |
3483 | lookup general lookup code and all lookups |
3484 | memory memory handling | |
3485 | pid add pid to debug output lines | |
3486 | process_info setting info for the process log | |
3487 | queue_run queue runs | |
3488 | receive general message reception logic | |
3489 | resolver turn on the DNS resolver's debugging output | |
3490 | retry retry handling | |
3491 | rewrite address rewriting | |
3492 | route address routing | |
3493 | timestamp add timestamp to debug output lines | |
3494 | tls TLS logic | |
3495 | transport transports | |
3496 | uid changes of uid/gid and looking up uid/gid | |
3497 | verify address verification logic | |
3498 | all almost all of the above (see below), and also -v | |
3499 | ||
3500 | The "all" option excludes "memory" when used as "+all", but includes it for | |
3501 | "-all". The reason for this is that "+all" is something that people tend to | |
3502 | use when generating debug output for Exim maintainers. If "+memory" is | |
3503 | included, an awful lot of output that is very rarely of interest is | |
3504 | generated, so it now has to be explicitly requested. However, "-all" does | |
3505 | turn everything off. | |
3506 | ||
3507 | The "resolver" option produces output only if the DNS resolver was compiled | |
3508 | with DEBUG enabled. This is not the case in some operating systems. Also, | |
3509 | unfortunately, debugging output from the DNS resolver is written to stdout | |
3510 | rather than stderr. | |
3511 | ||
3512 | The default (-d with no argument) omits "expand", "filter", "interface", | |
3513 | "load", "memory", "pid", "resolver", and "timestamp". However, the "pid" | |
3514 | selector is forced when debugging is turned on for a daemon, which then | |
3515 | passes it on to any re-executed Exims. Exim also automatically adds the pid | |
3516 | to debug lines when several remote deliveries are run in parallel. | |
3517 | ||
3518 | The "timestamp" selector causes the current time to be inserted at the | |
3519 | start of all debug output lines. This can be useful when trying to track | |
3520 | down delays in processing. | |
3521 | ||
3522 | If the debug_print option is set in any driver, it produces output whenever | |
3523 | any debugging is selected, or if -v is used. | |
3524 | ||
3525 | -dd<debug options> | |
3526 | ||
3527 | This option behaves exactly like -d except when used on a command that | |
3528 | starts a daemon process. In that case, debugging is turned off for the | |
3529 | subprocesses that the daemon creates. Thus, it is useful for monitoring the | |
3530 | behaviour of the daemon without creating as much output as full debugging | |
3531 | does. | |
3532 | ||
3533 | -dropcr | |
3534 | ||
3535 | This is an obsolete option that is now a no-op. It used to affect the way | |
3536 | Exim handled CR and LF characters in incoming messages. What happens now is | |
2813c06e | 3537 | described in section 47.2. |
420a0d19 CE |
3538 | |
3539 | -E | |
3540 | ||
3541 | This option specifies that an incoming message is a locally-generated | |
3542 | delivery failure report. It is used internally by Exim when handling | |
3543 | delivery failures and is not intended for external use. Its only effect is | |
3544 | to stop Exim generating certain messages to the postmaster, as otherwise | |
3545 | message cascades could occur in some situations. As part of the same | |
3546 | option, a message id may follow the characters -E. If it does, the log | |
3547 | entry for the receipt of the new message contains the id, following "R=", | |
3548 | as a cross-reference. | |
3549 | ||
3550 | -ex | |
3551 | ||
3552 | There are a number of Sendmail options starting with -oe which seem to be | |
3553 | called by various programs without the leading o in the option. For | |
3554 | example, the vacation program uses -eq. Exim treats all options of the form | |
3555 | -ex as synonymous with the corresponding -oex options. | |
3556 | ||
3557 | -F <string> | |
3558 | ||
3559 | This option sets the sender's full name for use when a locally-generated | |
3560 | message is being accepted. In the absence of this option, the user's gecos | |
3561 | entry from the password data is used. As users are generally permitted to | |
3562 | alter their gecos entries, no security considerations are involved. White | |
3563 | space between -F and the <string> is optional. | |
3564 | ||
3565 | -f <address> | |
3566 | ||
3567 | This option sets the address of the envelope sender of a locally-generated | |
3568 | message (also known as the return path). The option can normally be used | |
3569 | only by a trusted user, but untrusted_set_sender can be set to allow | |
3570 | untrusted users to use it. | |
3571 | ||
3572 | Processes running as root or the Exim user are always trusted. Other | |
3573 | trusted users are defined by the trusted_users or trusted_groups options. | |
3574 | In the absence of -f, or if the caller is not trusted, the sender of a | |
3575 | local message is set to the caller's login name at the default qualify | |
3576 | domain. | |
3577 | ||
3578 | There is one exception to the restriction on the use of -f: an empty sender | |
3579 | can be specified by any user, trusted or not, to create a message that can | |
3580 | never provoke a bounce. An empty sender can be specified either as an empty | |
3581 | string, or as a pair of angle brackets with nothing between them, as in | |
3582 | these examples of shell commands: | |
3583 | ||
3584 | exim -f '<>' user@domain | |
3585 | exim -f "" user@domain | |
3586 | ||
3587 | In addition, the use of -f is not restricted when testing a filter file | |
3588 | with -bf or when testing or verifying addresses using the -bt or -bv | |
3589 | options. | |
3590 | ||
3591 | Allowing untrusted users to change the sender address does not of itself | |
3592 | make it possible to send anonymous mail. Exim still checks that the From: | |
3593 | header refers to the local user, and if it does not, it adds a Sender: | |
3594 | header, though this can be overridden by setting no_local_from_check. | |
3595 | ||
3596 | White space between -f and the <address> is optional (that is, they can be | |
3597 | given as two arguments or one combined argument). The sender of a | |
3598 | locally-generated message can also be set (when permitted) by an initial | |
3599 | "From " line in the message - see the description of -bm above - but if -f | |
3600 | is also present, it overrides "From ". | |
3601 | ||
3602 | -G | |
3603 | ||
3604 | This option is equivalent to an ACL applying: | |
3605 | ||
3606 | control = suppress_local_fixups | |
3607 | ||
3608 | for every message received. Note that Sendmail will complain about such bad | |
3609 | formatting, where Exim silently just does not fix it up. This may change in | |
3610 | future. | |
3611 | ||
3612 | As this affects audit information, the caller must be a trusted user to use | |
3613 | this option. | |
3614 | ||
3615 | -h <number> | |
3616 | ||
3617 | This option is accepted for compatibility with Sendmail, but has no effect. | |
3618 | (In Sendmail it overrides the "hop count" obtained by counting Received: | |
3619 | headers.) | |
3620 | ||
3621 | -i | |
3622 | ||
3623 | This option, which has the same effect as -oi, specifies that a dot on a | |
3624 | line by itself should not terminate an incoming, non-SMTP message. I can | |
3625 | find no documentation for this option in Solaris 2.4 Sendmail, but the | |
3626 | mailx command in Solaris 2.4 uses it. See also -ti. | |
3627 | ||
3628 | -L <tag> | |
3629 | ||
3630 | This option is equivalent to setting syslog_processname in the config file | |
3631 | and setting log_file_path to "syslog". Its use is restricted to | |
3632 | administrators. The configuration file has to be read and parsed, to | |
3633 | determine access rights, before this is set and takes effect, so early | |
3634 | configuration file errors will not honour this flag. | |
3635 | ||
3636 | The tag should not be longer than 32 characters. | |
3637 | ||
3638 | -M <message id> <message id> ... | |
3639 | ||
3640 | This option requests Exim to run a delivery attempt on each message in | |
3641 | turn. If any of the messages are frozen, they are automatically thawed | |
3642 | before the delivery attempt. The settings of queue_domains, | |
3643 | queue_smtp_domains, and hold_domains are ignored. | |
3644 | ||
3645 | Retry hints for any of the addresses are overridden - Exim tries to deliver | |
3646 | even if the normal retry time has not yet been reached. This option | |
3647 | requires the caller to be an admin user. However, there is an option called | |
3648 | prod_requires_admin which can be set false to relax this restriction (and | |
3649 | also the same requirement for the -q, -R, and -S options). | |
3650 | ||
3651 | The deliveries happen synchronously, that is, the original Exim process | |
3652 | does not terminate until all the delivery attempts have finished. No output | |
3653 | is produced unless there is a serious error. If you want to see what is | |
3654 | happening, use the -v option as well, or inspect Exim's main log. | |
3655 | ||
3656 | -Mar <message id> <address> <address> ... | |
3657 | ||
3658 | This option requests Exim to add the addresses to the list of recipients of | |
3659 | the message ("ar" for "add recipients"). The first argument must be a | |
3660 | message id, and the remaining ones must be email addresses. However, if the | |
3661 | message is active (in the middle of a delivery attempt), it is not altered. | |
3662 | This option can be used only by an admin user. | |
3663 | ||
3664 | -MC <transport> <hostname> <sequence number> <message id> | |
3665 | ||
3666 | This option is not intended for use by external callers. It is used | |
3667 | internally by Exim to invoke another instance of itself to deliver a | |
3668 | waiting message using an existing SMTP connection, which is passed as the | |
2813c06e | 3669 | standard input. Details are given in chapter 48. This must be the final |
420a0d19 CE |
3670 | option, and the caller must be root or the Exim user in order to use it. |
3671 | ||
3672 | -MCA | |
3673 | ||
3674 | This option is not intended for use by external callers. It is used | |
3675 | internally by Exim in conjunction with the -MC option. It signifies that | |
3676 | the connection to the remote host has been authenticated. | |
3677 | ||
2813c06e CE |
3678 | -MCD |
3679 | ||
3680 | This option is not intended for use by external callers. It is used | |
3681 | internally by Exim in conjunction with the -MC option. It signifies that | |
3682 | the remote host supports the ESMTP DSN extension. | |
3683 | ||
3684 | -MCG | |
3685 | ||
3686 | This option is not intended for use by external callers. It is used | |
3687 | internally by Exim in conjunction with the -MC option. It signifies that an | |
3688 | alternate queue is used, named by the following option. | |
3689 | ||
420a0d19 CE |
3690 | -MCP |
3691 | ||
3692 | This option is not intended for use by external callers. It is used | |
3693 | internally by Exim in conjunction with the -MC option. It signifies that | |
3694 | the server to which Exim is connected supports pipelining. | |
3695 | ||
3696 | -MCQ <process id> <pipe fd> | |
3697 | ||
3698 | This option is not intended for use by external callers. It is used | |
3699 | internally by Exim in conjunction with the -MC option when the original | |
3700 | delivery was started by a queue runner. It passes on the process id of the | |
3701 | queue runner, together with the file descriptor number of an open pipe. | |
3702 | Closure of the pipe signals the final completion of the sequence of | |
3703 | processes that are passing messages through the same SMTP connection. | |
3704 | ||
3705 | -MCS | |
3706 | ||
3707 | This option is not intended for use by external callers. It is used | |
3708 | internally by Exim in conjunction with the -MC option, and passes on the | |
3709 | fact that the SMTP SIZE option should be used on messages delivered down | |
3710 | the existing connection. | |
3711 | ||
3712 | -MCT | |
3713 | ||
3714 | This option is not intended for use by external callers. It is used | |
3715 | internally by Exim in conjunction with the -MC option, and passes on the | |
3716 | fact that the host to which Exim is connected supports TLS encryption. | |
3717 | ||
3718 | -Mc <message id> <message id> ... | |
3719 | ||
3720 | This option requests Exim to run a delivery attempt on each message in | |
3721 | turn, but unlike the -M option, it does check for retry hints, and respects | |
3722 | any that are found. This option is not very useful to external callers. It | |
3723 | is provided mainly for internal use by Exim when it needs to re-invoke | |
2813c06e | 3724 | itself in order to regain root privilege for a delivery (see chapter 55). |
420a0d19 CE |
3725 | However, -Mc can be useful when testing, in order to run a delivery that |
3726 | respects retry times and other options such as hold_domains that are | |
3727 | overridden when -M is used. Such a delivery does not count as a queue run. | |
3728 | If you want to run a specific delivery as if in a queue run, you should use | |
3729 | -q with a message id argument. A distinction between queue run deliveries | |
3730 | and other deliveries is made in one or two places. | |
3731 | ||
3732 | -Mes <message id> <address> | |
3733 | ||
3734 | This option requests Exim to change the sender address in the message to | |
3735 | the given address, which must be a fully qualified address or "<>" ("es" | |
3736 | for "edit sender"). There must be exactly two arguments. The first argument | |
3737 | must be a message id, and the second one an email address. However, if the | |
3738 | message is active (in the middle of a delivery attempt), its status is not | |
3739 | altered. This option can be used only by an admin user. | |
3740 | ||
3741 | -Mf <message id> <message id> ... | |
3742 | ||
3743 | This option requests Exim to mark each listed message as "frozen". This | |
3744 | prevents any delivery attempts taking place until the message is "thawed", | |
3745 | either manually or as a result of the auto_thaw configuration option. | |
3746 | However, if any of the messages are active (in the middle of a delivery | |
3747 | attempt), their status is not altered. This option can be used only by an | |
3748 | admin user. | |
3749 | ||
3750 | -Mg <message id> <message id> ... | |
3751 | ||
3752 | This option requests Exim to give up trying to deliver the listed messages, | |
3753 | including any that are frozen. However, if any of the messages are active, | |
3754 | their status is not altered. For non-bounce messages, a delivery error | |
3755 | message is sent to the sender, containing the text "cancelled by | |
3756 | administrator". Bounce messages are just discarded. This option can be used | |
3757 | only by an admin user. | |
3758 | ||
3759 | -Mmad <message id> <message id> ... | |
3760 | ||
3761 | This option requests Exim to mark all the recipient addresses in the | |
3762 | messages as already delivered ("mad" for "mark all delivered"). However, if | |
3763 | any message is active (in the middle of a delivery attempt), its status is | |
3764 | not altered. This option can be used only by an admin user. | |
3765 | ||
3766 | -Mmd <message id> <address> <address> ... | |
3767 | ||
3768 | This option requests Exim to mark the given addresses as already delivered | |
3769 | ("md" for "mark delivered"). The first argument must be a message id, and | |
3770 | the remaining ones must be email addresses. These are matched to recipient | |
3771 | addresses in the message in a case-sensitive manner. If the message is | |
3772 | active (in the middle of a delivery attempt), its status is not altered. | |
3773 | This option can be used only by an admin user. | |
3774 | ||
3775 | -Mrm <message id> <message id> ... | |
3776 | ||
3777 | This option requests Exim to remove the given messages from the queue. No | |
3778 | bounce messages are sent; each message is simply forgotten. However, if any | |
3779 | of the messages are active, their status is not altered. This option can be | |
3780 | used only by an admin user or by the user who originally caused the message | |
3781 | to be placed on the queue. | |
3782 | ||
3783 | -Mset <message id> | |
3784 | ||
3785 | This option is useful only in conjunction with -be (that is, when testing | |
3786 | string expansions). Exim loads the given message from its spool before | |
3787 | doing the test expansions, thus setting message-specific variables such as | |
3788 | $message_size and the header variables. The $recipients variable is made | |
3789 | available. This feature is provided to make it easier to test expansions | |
3790 | that make use of these variables. However, this option can be used only by | |
3791 | an admin user. See also -bem. | |
3792 | ||
3793 | -Mt <message id> <message id> ... | |
3794 | ||
3795 | This option requests Exim to "thaw" any of the listed messages that are | |
3796 | "frozen", so that delivery attempts can resume. However, if any of the | |
3797 | messages are active, their status is not altered. This option can be used | |
3798 | only by an admin user. | |
3799 | ||
3800 | -Mvb <message id> | |
3801 | ||
3802 | This option causes the contents of the message body (-D) spool file to be | |
3803 | written to the standard output. This option can be used only by an admin | |
3804 | user. | |
3805 | ||
3806 | -Mvc <message id> | |
3807 | ||
3808 | This option causes a copy of the complete message (header lines plus body) | |
3809 | to be written to the standard output in RFC 2822 format. This option can be | |
3810 | used only by an admin user. | |
3811 | ||
3812 | -Mvh <message id> | |
3813 | ||
3814 | This option causes the contents of the message headers (-H) spool file to | |
3815 | be written to the standard output. This option can be used only by an admin | |
3816 | user. | |
3817 | ||
3818 | -Mvl <message id> | |
3819 | ||
3820 | This option causes the contents of the message log spool file to be written | |
3821 | to the standard output. This option can be used only by an admin user. | |
3822 | ||
3823 | -m | |
3824 | ||
3825 | This is apparently a synonym for -om that is accepted by Sendmail, so Exim | |
3826 | treats it that way too. | |
3827 | ||
3828 | -N | |
3829 | ||
3830 | This is a debugging option that inhibits delivery of a message at the | |
3831 | transport level. It implies -v. Exim goes through many of the motions of | |
3832 | delivery - it just doesn't actually transport the message, but instead | |
3833 | behaves as if it had successfully done so. However, it does not make any | |
3834 | updates to the retry database, and the log entries for deliveries are | |
3835 | flagged with "*>" rather than "=>". | |
3836 | ||
3837 | Because -N discards any message to which it applies, only root or the Exim | |
3838 | user are allowed to use it with -bd, -q, -R or -M. In other words, an | |
3839 | ordinary user can use it only when supplying an incoming message to which | |
3840 | it will apply. Although transportation never fails when -N is set, an | |
3841 | address may be deferred because of a configuration problem on a transport, | |
3842 | or a routing problem. Once -N has been used for a delivery attempt, it | |
3843 | sticks to the message, and applies to any subsequent delivery attempts that | |
3844 | may happen for that message. | |
3845 | ||
3846 | -n | |
3847 | ||
3848 | This option is interpreted by Sendmail to mean "no aliasing". For normal | |
2813c06e CE |
3849 | modes of operation, it is ignored by Exim. When combined with -bP it makes |
3850 | the output more terse (suppresses option names, environment values and | |
3851 | config pretty printing). | |
420a0d19 CE |
3852 | |
3853 | -O <data> | |
3854 | ||
3855 | This option is interpreted by Sendmail to mean "set option". It is ignored | |
3856 | by Exim. | |
3857 | ||
3858 | -oA <file name> | |
3859 | ||
3860 | This option is used by Sendmail in conjunction with -bi to specify an | |
3861 | alternative alias file name. Exim handles -bi differently; see the | |
3862 | description above. | |
3863 | ||
3864 | -oB <n> | |
3865 | ||
3866 | This is a debugging option which limits the maximum number of messages that | |
3867 | can be delivered down one SMTP connection, overriding the value set in any | |
3868 | smtp transport. If <n> is omitted, the limit is set to 1. | |
3869 | ||
3870 | -odb | |
3871 | ||
3872 | This option applies to all modes in which Exim accepts incoming messages, | |
3873 | including the listening daemon. It requests "background" delivery of such | |
3874 | messages, which means that the accepting process automatically starts a | |
3875 | delivery process for each message received, but does not wait for the | |
3876 | delivery processes to finish. | |
3877 | ||
3878 | When all the messages have been received, the reception process exits, | |
3879 | leaving the delivery processes to finish in their own time. The standard | |
3880 | output and error streams are closed at the start of each delivery process. | |
3881 | This is the default action if none of the -od options are present. | |
3882 | ||
3883 | If one of the queueing options in the configuration file (queue_only or | |
3884 | queue_only_file, for example) is in effect, -odb overrides it if | |
3885 | queue_only_override is set true, which is the default setting. If | |
3886 | queue_only_override is set false, -odb has no effect. | |
3887 | ||
3888 | -odf | |
3889 | ||
3890 | This option requests "foreground" (synchronous) delivery when Exim has | |
3891 | accepted a locally-generated message. (For the daemon it is exactly the | |
3892 | same as -odb.) A delivery process is automatically started to deliver the | |
3893 | message, and Exim waits for it to complete before proceeding. | |
3894 | ||
3895 | The original Exim reception process does not finish until the delivery | |
3896 | process for the final message has ended. The standard error stream is left | |
3897 | open during deliveries. | |
3898 | ||
3899 | However, like -odb, this option has no effect if queue_only_override is | |
3900 | false and one of the queueing options in the configuration file is in | |
3901 | effect. | |
3902 | ||
3903 | If there is a temporary delivery error during foreground delivery, the | |
3904 | message is left on the queue for later delivery, and the original reception | |
2813c06e | 3905 | process exits. See chapter 51 for a way of setting up a restricted |
420a0d19 CE |
3906 | configuration that never queues messages. |
3907 | ||
3908 | -odi | |
3909 | ||
3910 | This option is synonymous with -odf. It is provided for compatibility with | |
3911 | Sendmail. | |
3912 | ||
3913 | -odq | |
3914 | ||
3915 | This option applies to all modes in which Exim accepts incoming messages, | |
3916 | including the listening daemon. It specifies that the accepting process | |
3917 | should not automatically start a delivery process for each message | |
3918 | received. Messages are placed on the queue, and remain there until a | |
3919 | subsequent queue runner process encounters them. There are several | |
3920 | configuration options (such as queue_only) that can be used to queue | |
3921 | incoming messages under certain conditions. This option overrides all of | |
3922 | them and also -odqs. It always forces queueing. | |
3923 | ||
3924 | -odqs | |
3925 | ||
3926 | This option is a hybrid between -odb/-odi and -odq. However, like -odb and | |
3927 | -odi, this option has no effect if queue_only_override is false and one of | |
3928 | the queueing options in the configuration file is in effect. | |
3929 | ||
3930 | When -odqs does operate, a delivery process is started for each incoming | |
3931 | message, in the background by default, but in the foreground if -odi is | |
3932 | also present. The recipient addresses are routed, and local deliveries are | |
3933 | done in the normal way. However, if any SMTP deliveries are required, they | |
3934 | are not done at this time, so the message remains on the queue until a | |
3935 | subsequent queue runner process encounters it. Because routing was done, | |
3936 | Exim knows which messages are waiting for which hosts, and so a number of | |
3937 | messages for the same host can be sent in a single SMTP connection. The | |
3938 | queue_smtp_domains configuration option has the same effect for specific | |
3939 | domains. See also the -qq option. | |
3940 | ||
3941 | -oee | |
3942 | ||
3943 | If an error is detected while a non-SMTP message is being received (for | |
3944 | example, a malformed address), the error is reported to the sender in a | |
3945 | mail message. | |
3946 | ||
3947 | Provided this error message is successfully sent, the Exim receiving | |
3948 | process exits with a return code of zero. If not, the return code is 2 if | |
3949 | the problem is that the original message has no recipients, or 1 for any | |
3950 | other error. This is the default -oex option if Exim is called as rmail. | |
3951 | ||
3952 | -oem | |
3953 | ||
3954 | This is the same as -oee, except that Exim always exits with a non-zero | |
3955 | return code, whether or not the error message was successfully sent. This | |
3956 | is the default -oex option, unless Exim is called as rmail. | |
3957 | ||
3958 | -oep | |
3959 | ||
3960 | If an error is detected while a non-SMTP message is being received, the | |
3961 | error is reported by writing a message to the standard error file (stderr). | |
3962 | The return code is 1 for all errors. | |
3963 | ||
3964 | -oeq | |
3965 | ||
3966 | This option is supported for compatibility with Sendmail, but has the same | |
3967 | effect as -oep. | |
3968 | ||
3969 | -oew | |
3970 | ||
3971 | This option is supported for compatibility with Sendmail, but has the same | |
3972 | effect as -oem. | |
3973 | ||
3974 | -oi | |
3975 | ||
3976 | This option, which has the same effect as -i, specifies that a dot on a | |
3977 | line by itself should not terminate an incoming, non-SMTP message. | |
3978 | Otherwise, a single dot does terminate, though Exim does no special | |
3979 | processing for other lines that start with a dot. This option is set by | |
3980 | default if Exim is called as rmail. See also -ti. | |
3981 | ||
3982 | -oitrue | |
3983 | ||
3984 | This option is treated as synonymous with -oi. | |
3985 | ||
3986 | -oMa <host address> | |
3987 | ||
3988 | A number of options starting with -oM can be used to set values associated | |
3989 | with remote hosts on locally-submitted messages (that is, messages not | |
3990 | received over TCP/IP). These options can be used by any caller in | |
3991 | conjunction with the -bh, -be, -bf, -bF, -bt, or -bv testing options. In | |
3992 | other circumstances, they are ignored unless the caller is trusted. | |
3993 | ||
3994 | The -oMa option sets the sender host address. This may include a port | |
3995 | number at the end, after a full stop (period). For example: | |
3996 | ||
3997 | exim -bs -oMa 10.9.8.7.1234 | |
3998 | ||
3999 | An alternative syntax is to enclose the IP address in square brackets, | |
4000 | followed by a colon and the port number: | |
4001 | ||
4002 | exim -bs -oMa [10.9.8.7]:1234 | |
4003 | ||
4004 | The IP address is placed in the $sender_host_address variable, and the | |
4005 | port, if present, in $sender_host_port. If both -oMa and -bh are present on | |
4006 | the command line, the sender host IP address is taken from whichever one is | |
4007 | last. | |
4008 | ||
4009 | -oMaa <name> | |
4010 | ||
4011 | See -oMa above for general remarks about the -oM options. The -oMaa option | |
4012 | sets the value of $sender_host_authenticated (the authenticator name). See | |
4013 | chapter 33 for a discussion of SMTP authentication. This option can be used | |
4014 | with -bh and -bs to set up an authenticated SMTP session without actually | |
4015 | using the SMTP AUTH command. | |
4016 | ||
4017 | -oMai <string> | |
4018 | ||
4019 | See -oMa above for general remarks about the -oM options. The -oMai option | |
4020 | sets the value of $authenticated_id (the id that was authenticated). This | |
4021 | overrides the default value (the caller's login id, except with -bh, where | |
4022 | there is no default) for messages from local sources. See chapter 33 for a | |
4023 | discussion of authenticated ids. | |
4024 | ||
4025 | -oMas <address> | |
4026 | ||
4027 | See -oMa above for general remarks about the -oM options. The -oMas option | |
4028 | sets the authenticated sender value in $authenticated_sender. It overrides | |
4029 | the sender address that is created from the caller's login id for messages | |
4030 | from local sources, except when -bh is used, when there is no default. For | |
4031 | both -bh and -bs, an authenticated sender that is specified on a MAIL | |
4032 | command overrides this value. See chapter 33 for a discussion of | |
4033 | authenticated senders. | |
4034 | ||
4035 | -oMi <interface address> | |
4036 | ||
4037 | See -oMa above for general remarks about the -oM options. The -oMi option | |
4038 | sets the IP interface address value. A port number may be included, using | |
4039 | the same syntax as for -oMa. The interface address is placed in | |
4040 | $received_ip_address and the port number, if present, in $received_port. | |
4041 | ||
4042 | -oMm <message reference> | |
4043 | ||
4044 | See -oMa above for general remarks about the -oM options. The -oMm option | |
4045 | sets the message reference, e.g. message-id, and is logged during delivery. | |
4046 | This is useful when some kind of audit trail is required to tie messages | |
4047 | together. The format of the message reference is checked and will abort if | |
4048 | the format is invalid. The option will only be accepted if exim is running | |
4049 | in trusted mode, not as any regular user. | |
4050 | ||
4051 | The best example of a message reference is when Exim sends a bounce | |
4052 | message. The message reference is the message-id of the original message | |
4053 | for which Exim is sending the bounce. | |
4054 | ||
4055 | -oMr <protocol name> | |
4056 | ||
4057 | See -oMa above for general remarks about the -oM options. The -oMr option | |
4058 | sets the received protocol value that is stored in $received_protocol. | |
4059 | However, it does not apply (and is ignored) when -bh or -bs is used. For | |
4060 | -bh, the protocol is forced to one of the standard SMTP protocol names (see | |
4061 | the description of $received_protocol in section 11.9). For -bs, the | |
4062 | protocol is always "local-" followed by one of those same names. For -bS | |
4063 | (batched SMTP) however, the protocol can be set by -oMr. | |
4064 | ||
4065 | -oMs <host name> | |
4066 | ||
4067 | See -oMa above for general remarks about the -oM options. The -oMs option | |
4068 | sets the sender host name in $sender_host_name. When this option is | |
4069 | present, Exim does not attempt to look up a host name from an IP address; | |
4070 | it uses the name it is given. | |
4071 | ||
4072 | -oMt <ident string> | |
4073 | ||
4074 | See -oMa above for general remarks about the -oM options. The -oMt option | |
4075 | sets the sender ident value in $sender_ident. The default setting for local | |
4076 | callers is the login id of the calling process, except when -bh is used, | |
4077 | when there is no default. | |
4078 | ||
4079 | -om | |
4080 | ||
4081 | In Sendmail, this option means "me too", indicating that the sender of a | |
4082 | message should receive a copy of the message if the sender appears in an | |
4083 | alias expansion. Exim always does this, so the option does nothing. | |
4084 | ||
4085 | -oo | |
4086 | ||
4087 | This option is ignored. In Sendmail it specifies "old style headers", | |
4088 | whatever that means. | |
4089 | ||
4090 | -oP <path> | |
4091 | ||
4092 | This option is useful only in conjunction with -bd or -q with a time value. | |
4093 | The option specifies the file to which the process id of the daemon is | |
4094 | written. When -oX is used with -bd, or when -q with a time is used without | |
4095 | -bd, this is the only way of causing Exim to write a pid file, because in | |
4096 | those cases, the normal pid file is not used. | |
4097 | ||
4098 | -or <time> | |
4099 | ||
4100 | This option sets a timeout value for incoming non-SMTP messages. If it is | |
4101 | not set, Exim will wait forever for the standard input. The value can also | |
4102 | be set by the receive_timeout option. The format used for specifying times | |
2813c06e | 4103 | is described in section 6.16. |
420a0d19 CE |
4104 | |
4105 | -os <time> | |
4106 | ||
4107 | This option sets a timeout value for incoming SMTP messages. The timeout | |
4108 | applies to each SMTP command and block of data. The value can also be set | |
4109 | by the smtp_receive_timeout option; it defaults to 5 minutes. The format | |
2813c06e | 4110 | used for specifying times is described in section 6.16. |
420a0d19 CE |
4111 | |
4112 | -ov | |
4113 | ||
4114 | This option has exactly the same effect as -v. | |
4115 | ||
4116 | -oX <number or string> | |
4117 | ||
4118 | This option is relevant only when the -bd (start listening daemon) option | |
4119 | is also given. It controls which ports and interfaces the daemon uses. | |
4120 | Details of the syntax, and how it interacts with configuration file | |
4121 | options, are given in chapter 13. When -oX is used to start a daemon, no | |
4122 | pid file is written unless -oP is also present to specify a pid file name. | |
4123 | ||
4124 | -pd | |
4125 | ||
4126 | This option applies when an embedded Perl interpreter is linked with Exim | |
4127 | (see chapter 12). It overrides the setting of the perl_at_start option, | |
4128 | forcing the starting of the interpreter to be delayed until it is needed. | |
4129 | ||
4130 | -ps | |
4131 | ||
4132 | This option applies when an embedded Perl interpreter is linked with Exim | |
4133 | (see chapter 12). It overrides the setting of the perl_at_start option, | |
4134 | forcing the starting of the interpreter to occur as soon as Exim is | |
4135 | started. | |
4136 | ||
4137 | -p<rval>:<sval> | |
4138 | ||
4139 | For compatibility with Sendmail, this option is equivalent to | |
4140 | ||
4141 | -oMr <rval> -oMs <sval> | |
4142 | ||
4143 | It sets the incoming protocol and host name (for trusted callers). The host | |
4144 | name and its colon can be omitted when only the protocol is to be set. Note | |
4145 | the Exim already has two private options, -pd and -ps, that refer to | |
4146 | embedded Perl. It is therefore impossible to set a protocol value of "d" or | |
4147 | "s" using this option (but that does not seem a real limitation). | |
4148 | ||
4149 | -q | |
4150 | ||
4151 | This option is normally restricted to admin users. However, there is a | |
4152 | configuration option called prod_requires_admin which can be set false to | |
4153 | relax this restriction (and also the same requirement for the -M, -R, and | |
4154 | -S options). | |
4155 | ||
2813c06e CE |
4156 | If other commandline options do not specify an action, the -q option starts |
4157 | one queue runner process. This scans the queue of waiting messages, and | |
4158 | runs a delivery process for each one in turn. It waits for each delivery | |
4159 | process to finish before starting the next one. A delivery process may not | |
4160 | actually do any deliveries if the retry times for the addresses have not | |
4161 | been reached. Use -qf (see below) if you want to override this. | |
420a0d19 CE |
4162 | |
4163 | If the delivery process spawns other processes to deliver other messages | |
4164 | down passed SMTP connections, the queue runner waits for these to finish | |
4165 | before proceeding. | |
4166 | ||
4167 | When all the queued messages have been considered, the original queue | |
4168 | runner process terminates. In other words, a single pass is made over the | |
4169 | waiting mail, one message at a time. Use -q with a time (see below) if you | |
4170 | want this to be repeated periodically. | |
4171 | ||
4172 | Exim processes the waiting messages in an unpredictable order. It isn't | |
4173 | very random, but it is likely to be different each time, which is all that | |
4174 | matters. If one particular message screws up a remote MTA, other messages | |
4175 | to the same MTA have a chance of getting through if they get tried first. | |
4176 | ||
4177 | It is possible to cause the messages to be processed in lexical message id | |
4178 | order, which is essentially the order in which they arrived, by setting the | |
4179 | queue_run_in_order option, but this is not recommended for normal use. | |
4180 | ||
4181 | -q<qflags> | |
4182 | ||
4183 | The -q option may be followed by one or more flag letters that change its | |
4184 | behaviour. They are all optional, but if more than one is present, they | |
4185 | must appear in the correct order. Each flag is described in a separate item | |
4186 | below. | |
4187 | ||
4188 | -qq... | |
4189 | ||
4190 | An option starting with -qq requests a two-stage queue run. In the first | |
4191 | stage, the queue is scanned as if the queue_smtp_domains option matched | |
4192 | every domain. Addresses are routed, local deliveries happen, but no remote | |
4193 | transports are run. | |
4194 | ||
4195 | The hints database that remembers which messages are waiting for specific | |
4196 | hosts is updated, as if delivery to those hosts had been deferred. After | |
4197 | this is complete, a second, normal queue scan happens, with routing and | |
4198 | delivery taking place as normal. Messages that are routed to the same host | |
4199 | should mostly be delivered down a single SMTP connection because of the | |
4200 | hints that were set up during the first queue scan. This option may be | |
4201 | useful for hosts that are connected to the Internet intermittently. | |
4202 | ||
4203 | -q[q]i... | |
4204 | ||
4205 | If the i flag is present, the queue runner runs delivery processes only for | |
4206 | those messages that haven't previously been tried. (i stands for "initial | |
4207 | delivery".) This can be helpful if you are putting messages on the queue | |
4208 | using -odq and want a queue runner just to process the new messages. | |
4209 | ||
4210 | -q[q][i]f... | |
4211 | ||
4212 | If one f flag is present, a delivery attempt is forced for each non-frozen | |
4213 | message, whereas without f only those non-frozen addresses that have passed | |
4214 | their retry times are tried. | |
4215 | ||
4216 | -q[q][i]ff... | |
4217 | ||
4218 | If ff is present, a delivery attempt is forced for every message, whether | |
4219 | frozen or not. | |
4220 | ||
4221 | -q[q][i][f[f]]l | |
4222 | ||
4223 | The l (the letter "ell") flag specifies that only local deliveries are to | |
4224 | be done. If a message requires any remote deliveries, it remains on the | |
4225 | queue for later delivery. | |
4226 | ||
2813c06e CE |
4227 | -q[q][i][f[f]][l][G<name>[/<time>]]] |
4228 | ||
4229 | If the G flag and a name is present, the queue runner operates on the queue | |
4230 | with the given name rather than the default queue. The name should not | |
4231 | contain a / character. For a periodic queue run (see below) append to the | |
4232 | name a slash and a time value. | |
4233 | ||
4234 | If other commandline options specify an action, a -qG<name> option will | |
4235 | specify a queue to operate on. For example: | |
4236 | ||
4237 | exim -bp -qGquarantine | |
4238 | mailq -qGquarantine | |
4239 | exim -qGoffpeak -Rf @special.domain.example | |
4240 | ||
420a0d19 CE |
4241 | -q<qflags> <start id> <end id> |
4242 | ||
4243 | When scanning the queue, Exim can be made to skip over messages whose ids | |
4244 | are lexically less than a given value by following the -q option with a | |
4245 | starting message id. For example: | |
4246 | ||
4247 | exim -q 0t5C6f-0000c8-00 | |
4248 | ||
4249 | Messages that arrived earlier than "0t5C6f-0000c8-00" are not inspected. If | |
4250 | a second message id is given, messages whose ids are lexically greater than | |
4251 | it are also skipped. If the same id is given twice, for example, | |
4252 | ||
4253 | exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00 | |
4254 | ||
4255 | just one delivery process is started, for that message. This differs from | |
4256 | -M in that retry data is respected, and it also differs from -Mc in that it | |
4257 | counts as a delivery from a queue run. Note that the selection mechanism | |
4258 | does not affect the order in which the messages are scanned. There are also | |
4259 | other ways of selecting specific sets of messages for delivery in a queue | |
4260 | run - see -R and -S. | |
4261 | ||
4262 | -q<qflags><time> | |
4263 | ||
4264 | When a time value is present, the -q option causes Exim to run as a daemon, | |
4265 | starting a queue runner process at intervals specified by the given time | |
2813c06e | 4266 | value (whose format is described in section 6.16). This form of the -q |
420a0d19 CE |
4267 | option is commonly combined with the -bd option, in which case a single |
4268 | daemon process handles both functions. A common way of starting up a | |
4269 | combined daemon at system boot time is to use a command such as | |
4270 | ||
4271 | /usr/exim/bin/exim -bd -q30m | |
4272 | ||
4273 | Such a daemon listens for incoming SMTP calls, and also starts a queue | |
4274 | runner process every 30 minutes. | |
4275 | ||
4276 | When a daemon is started by -q with a time value, but without -bd, no pid | |
4277 | file is written unless one is explicitly requested by the -oP option. | |
4278 | ||
4279 | -qR<rsflags> <string> | |
4280 | ||
4281 | This option is synonymous with -R. It is provided for Sendmail | |
4282 | compatibility. | |
4283 | ||
4284 | -qS<rsflags> <string> | |
4285 | ||
4286 | This option is synonymous with -S. | |
4287 | ||
4288 | -R<rsflags> <string> | |
4289 | ||
4290 | The <rsflags> may be empty, in which case the white space before the string | |
4291 | is optional, unless the string is f, ff, r, rf, or rff, which are the | |
4292 | possible values for <rsflags>. White space is required if <rsflags> is not | |
4293 | empty. | |
4294 | ||
4295 | This option is similar to -q with no time value, that is, it causes Exim to | |
4296 | perform a single queue run, except that, when scanning the messages on the | |
4297 | queue, Exim processes only those that have at least one undelivered | |
4298 | recipient address containing the given string, which is checked in a | |
4299 | case-independent way. If the <rsflags> start with r, <string> is | |
4300 | interpreted as a regular expression; otherwise it is a literal string. | |
4301 | ||
4302 | If you want to do periodic queue runs for messages with specific | |
4303 | recipients, you can combine -R with -q and a time value. For example: | |
4304 | ||
4305 | exim -q25m -R @special.domain.example | |
4306 | ||
4307 | This example does a queue run for messages with recipients in the given | |
4308 | domain every 25 minutes. Any additional flags that are specified with -q | |
4309 | are applied to each queue run. | |
4310 | ||
4311 | Once a message is selected for delivery by this mechanism, all its | |
4312 | addresses are processed. For the first selected message, Exim overrides any | |
4313 | retry information and forces a delivery attempt for each undelivered | |
4314 | address. This means that if delivery of any address in the first message is | |
4315 | successful, any existing retry information is deleted, and so delivery | |
4316 | attempts for that address in subsequently selected messages (which are | |
4317 | processed without forcing) will run. However, if delivery of any address | |
4318 | does not succeed, the retry information is updated, and in subsequently | |
4319 | selected messages, the failing address will be skipped. | |
4320 | ||
4321 | If the <rsflags> contain f or ff, the delivery forcing applies to all | |
4322 | selected messages, not just the first; frozen messages are included when ff | |
4323 | is present. | |
4324 | ||
4325 | The -R option makes it straightforward to initiate delivery of all messages | |
4326 | to a given domain after a host has been down for some time. When the SMTP | |
2813c06e | 4327 | command ETRN is accepted by its ACL (see chapter 43), its default effect is |
420a0d19 CE |
4328 | to run Exim with the -R option, but it can be configured to run an |
4329 | arbitrary command instead. | |
4330 | ||
4331 | -r | |
4332 | ||
4333 | This is a documented (for Sendmail) obsolete alternative name for -f. | |
4334 | ||
4335 | -S<rsflags> <string> | |
4336 | ||
4337 | This option acts like -R except that it checks the string against each | |
4338 | message's sender instead of against the recipients. If -R is also set, both | |
4339 | conditions must be met for a message to be selected. If either of the | |
4340 | options has f or ff in its flags, the associated action is taken. | |
4341 | ||
4342 | -Tqt <times> | |
4343 | ||
4344 | This is an option that is exclusively for use by the Exim testing suite. It | |
4345 | is not recognized when Exim is run normally. It allows for the setting up | |
4346 | of explicit "queue times" so that various warning/retry features can be | |
4347 | tested. | |
4348 | ||
4349 | -t | |
4350 | ||
4351 | When Exim is receiving a locally-generated, non-SMTP message on its | |
4352 | standard input, the -t option causes the recipients of the message to be | |
4353 | obtained from the To:, Cc:, and Bcc: header lines in the message instead of | |
4354 | from the command arguments. The addresses are extracted before any | |
4355 | rewriting takes place and the Bcc: header line, if present, is then | |
4356 | removed. | |
4357 | ||
4358 | If the command has any arguments, they specify addresses to which the | |
4359 | message is not to be delivered. That is, the argument addresses are removed | |
4360 | from the recipients list obtained from the headers. This is compatible with | |
4361 | Smail 3 and in accordance with the documented behaviour of several versions | |
4362 | of Sendmail, as described in man pages on a number of operating systems | |
4363 | (e.g. Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail | |
4364 | add argument addresses to those obtained from the headers, and the O'Reilly | |
4365 | Sendmail book documents it that way. Exim can be made to add argument | |
4366 | addresses instead of subtracting them by setting the option | |
4367 | extract_addresses_remove_arguments false. | |
4368 | ||
4369 | If there are any Resent- header lines in the message, Exim extracts | |
4370 | recipients from all Resent-To:, Resent-Cc:, and Resent-Bcc: header lines | |
4371 | instead of from To:, Cc:, and Bcc:. This is for compatibility with Sendmail | |
4372 | and other MTAs. (Prior to release 4.20, Exim gave an error if -t was used | |
4373 | in conjunction with Resent- header lines.) | |
4374 | ||
4375 | RFC 2822 talks about different sets of Resent- header lines (for when a | |
4376 | message is resent several times). The RFC also specifies that they should | |
4377 | be added at the front of the message, and separated by Received: lines. It | |
4378 | is not at all clear how -t should operate in the present of multiple sets, | |
4379 | nor indeed exactly what constitutes a "set". In practice, it seems that | |
4380 | MUAs do not follow the RFC. The Resent- lines are often added at the end of | |
4381 | the header, and if a message is resent more than once, it is common for the | |
4382 | original set of Resent- headers to be renamed as X-Resent- when a new set | |
4383 | is added. This removes any possible ambiguity. | |
4384 | ||
4385 | -ti | |
4386 | ||
4387 | This option is exactly equivalent to -t -i. It is provided for | |
4388 | compatibility with Sendmail. | |
4389 | ||
4390 | -tls-on-connect | |
4391 | ||
4392 | This option is available when Exim is compiled with TLS support. It forces | |
4393 | all incoming SMTP connections to behave as if the incoming port is listed | |
2813c06e | 4394 | in the tls_on_connect_ports option. See section 13.4 and chapter 42 for |
420a0d19 CE |
4395 | further details. |
4396 | ||
4397 | -U | |
4398 | ||
4399 | Sendmail uses this option for "initial message submission", and its | |
4400 | documentation states that in future releases, it may complain about | |
4401 | syntactically invalid messages rather than fixing them when this flag is | |
4402 | not set. Exim ignores this option. | |
4403 | ||
4404 | -v | |
4405 | ||
4406 | This option causes Exim to write information to the standard error stream, | |
4407 | describing what it is doing. In particular, it shows the log lines for | |
4408 | receiving and delivering a message, and if an SMTP connection is made, the | |
4409 | SMTP dialogue is shown. Some of the log lines shown may not actually be | |
4410 | written to the log if the setting of log_selector discards them. Any | |
4411 | relevant selectors are shown with each log line. If none are shown, the | |
4412 | logging is unconditional. | |
4413 | ||
4414 | -x | |
4415 | ||
4416 | AIX uses -x for a private purpose ("mail from a local mail program has | |
4417 | National Language Support extended characters in the body of the mail | |
4418 | item"). It sets -x when calling the MTA from its mail command. Exim ignores | |
4419 | this option. | |
4420 | ||
4421 | -X <logfile> | |
4422 | ||
4423 | This option is interpreted by Sendmail to cause debug information to be | |
4424 | sent to the named file. It is ignored by Exim. | |
4425 | ||
2813c06e CE |
4426 | -z <log-line> |
4427 | ||
4428 | This option writes its argument to Exim's logfile. Use is restricted to | |
4429 | administrators; the intent is for operational notes. Quotes should be used | |
4430 | to maintain a multi-word item as a single argument, under most shells. | |
4431 | ||
420a0d19 CE |
4432 | |
4433 | ||
4434 | =============================================================================== | |
4435 | 6. THE EXIM RUN TIME CONFIGURATION FILE | |
4436 | ||
4437 | Exim uses a single run time configuration file that is read whenever an Exim | |
4438 | binary is executed. Note that in normal operation, this happens frequently, | |
4439 | because Exim is designed to operate in a distributed manner, without central | |
4440 | control. | |
4441 | ||
4442 | If a syntax error is detected while reading the configuration file, Exim writes | |
4443 | a message on the standard error, and exits with a non-zero return code. The | |
4444 | message is also written to the panic log. Note: Only simple syntax errors can | |
4445 | be detected at this time. The values of any expanded options are not checked | |
4446 | until the expansion happens, even when the expansion does not actually alter | |
4447 | the string. | |
4448 | ||
4449 | The name of the configuration file is compiled into the binary for security | |
4450 | reasons, and is specified by the CONFIGURE_FILE compilation option. In most | |
4451 | configurations, this specifies a single file. However, it is permitted to give | |
4452 | a colon-separated list of file names, in which case Exim uses the first | |
4453 | existing file in the list. | |
4454 | ||
4455 | The run time configuration file must be owned by root or by the user that is | |
4456 | specified at compile time by the CONFIGURE_OWNER option (if set). The | |
4457 | configuration file must not be world-writeable, or group-writeable unless its | |
4458 | group is the root group or the one specified at compile time by the | |
4459 | CONFIGURE_GROUP option. | |
4460 | ||
4461 | Warning: In a conventional configuration, where the Exim binary is setuid to | |
4462 | root, anybody who is able to edit the run time configuration file has an easy | |
4463 | way to run commands as root. If you specify a user or group in the | |
4464 | CONFIGURE_OWNER or CONFIGURE_GROUP options, then that user and/or any users who | |
4465 | are members of that group will trivially be able to obtain root privileges. | |
4466 | ||
4467 | Up to Exim version 4.72, the run time configuration file was also permitted to | |
4468 | be writeable by the Exim user and/or group. That has been changed in Exim 4.73 | |
4469 | since it offered a simple privilege escalation for any attacker who managed to | |
4470 | compromise the Exim user account. | |
4471 | ||
4472 | A default configuration file, which will work correctly in simple situations, | |
4473 | is provided in the file src/configure.default. If CONFIGURE_FILE defines just | |
4474 | one file name, the installation process copies the default configuration to a | |
4475 | new file of that name if it did not previously exist. If CONFIGURE_FILE is a | |
4476 | list, no default is automatically installed. Chapter 7 is a "walk-through" | |
4477 | discussion of the default configuration. | |
4478 | ||
4479 | ||
4480 | 6.1 Using a different configuration file | |
4481 | ---------------------------------------- | |
4482 | ||
4483 | A one-off alternate configuration can be specified by the -C command line | |
4484 | option, which may specify a single file or a list of files. However, when -C is | |
4485 | used, Exim gives up its root privilege, unless called by root (or unless the | |
4486 | argument for -C is identical to the built-in value from CONFIGURE_FILE), or is | |
4487 | listed in the TRUSTED_CONFIG_LIST file and the caller is the Exim user or the | |
4488 | user specified in the CONFIGURE_OWNER setting. -C is useful mainly for checking | |
4489 | the syntax of configuration files before installing them. No owner or group | |
4490 | checks are done on a configuration file specified by -C, if root privilege has | |
4491 | been dropped. | |
4492 | ||
4493 | Even the Exim user is not trusted to specify an arbitrary configuration file | |
4494 | with the -C option to be used with root privileges, unless that file is listed | |
4495 | in the TRUSTED_CONFIG_LIST file. This locks out the possibility of testing a | |
4496 | configuration using -C right through message reception and delivery, even if | |
4497 | the caller is root. The reception works, but by that time, Exim is running as | |
4498 | the Exim user, so when it re-execs to regain privilege for the delivery, the | |
4499 | use of -C causes privilege to be lost. However, root can test reception and | |
4500 | delivery using two separate commands (one to put a message on the queue, using | |
4501 | -odq, and another to do the delivery, using -M). | |
4502 | ||
4503 | If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix string | |
4504 | with which any file named in a -C command line option must start. In addition, | |
4505 | the file name must not contain the sequence "/../". There is no default setting | |
4506 | for ALT_CONFIG_PREFIX; when it is unset, any file name can be used with -C. | |
4507 | ||
4508 | One-off changes to a configuration can be specified by the -D command line | |
4509 | option, which defines and overrides values for macros used inside the | |
4510 | configuration file. However, like -C, the use of this option by a | |
4511 | non-privileged user causes Exim to discard its root privilege. If | |
4512 | DISABLE_D_OPTION is defined in Local/Makefile, the use of -D is completely | |
4513 | disabled, and its use causes an immediate error exit. | |
4514 | ||
4515 | The WHITELIST_D_MACROS option in Local/Makefile permits the binary builder to | |
4516 | declare certain macro names trusted, such that root privilege will not | |
4517 | necessarily be discarded. WHITELIST_D_MACROS defines a colon-separated list of | |
4518 | macros which are considered safe and, if -D only supplies macros from this | |
4519 | list, and the values are acceptable, then Exim will not give up root privilege | |
4520 | if the caller is root, the Exim run-time user, or the CONFIGURE_OWNER, if set. | |
4521 | This is a transition mechanism and is expected to be removed in the future. | |
4522 | Acceptable values for the macros satisfy the regexp: "^[A-Za-z0-9_/.-]*$" | |
4523 | ||
4524 | Some sites may wish to use the same Exim binary on different machines that | |
4525 | share a file system, but to use different configuration files on each machine. | |
4526 | If CONFIGURE_FILE_USE_NODE is defined in Local/Makefile, Exim first looks for a | |
4527 | file whose name is the configuration file name followed by a dot and the | |
4528 | machine's node name, as obtained from the uname() function. If this file does | |
4529 | not exist, the standard name is tried. This processing occurs for each file | |
4530 | name in the list given by CONFIGURE_FILE or -C. | |
4531 | ||
4532 | In some esoteric situations different versions of Exim may be run under | |
4533 | different effective uids and the CONFIGURE_FILE_USE_EUID is defined to help | |
4534 | with this. See the comments in src/EDITME for details. | |
4535 | ||
4536 | ||
4537 | 6.2 Configuration file format | |
4538 | ----------------------------- | |
4539 | ||
4540 | Exim's configuration file is divided into a number of different parts. General | |
4541 | option settings must always appear at the start of the file. The other parts | |
4542 | are all optional, and may appear in any order. Each part other than the first | |
2813c06e CE |
4543 | is introduced by the word "begin" followed by at least one literal space, and |
4544 | the name of the part. The optional parts are: | |
420a0d19 CE |
4545 | |
4546 | * ACL: Access control lists for controlling incoming SMTP mail (see chapter | |
2813c06e | 4547 | 43). |
420a0d19 CE |
4548 | |
4549 | * authenticators: Configuration settings for the authenticator drivers. These | |
4550 | are concerned with the SMTP AUTH command (see chapter 33). | |
4551 | ||
4552 | * routers: Configuration settings for the router drivers. Routers process | |
4553 | addresses and determine how the message is to be delivered (see chapters 15 | |
4554 | -22). | |
4555 | ||
4556 | * transports: Configuration settings for the transport drivers. Transports | |
4557 | define mechanisms for copying messages to destinations (see chapters 24-30 | |
4558 | ). | |
4559 | ||
4560 | * retry: Retry rules, for use when a message cannot be delivered immediately. | |
4561 | If there is no retry section, or if it is empty (that is, no retry rules | |
4562 | are defined), Exim will not retry deliveries. In this situation, temporary | |
4563 | errors are treated the same as permanent errors. Retry rules are discussed | |
4564 | in chapter 32. | |
4565 | ||
4566 | * rewrite: Global address rewriting rules, for use when a message arrives and | |
4567 | when new addresses are generated during delivery. Rewriting is discussed in | |
4568 | chapter 31. | |
4569 | ||
4570 | * local_scan: Private options for the local_scan() function. If you want to | |
4571 | use this feature, you must set | |
4572 | ||
4573 | LOCAL_SCAN_HAS_OPTIONS=yes | |
4574 | ||
4575 | in Local/Makefile before building Exim. Details of the local_scan() | |
2813c06e | 4576 | facility are given in chapter 45. |
420a0d19 CE |
4577 | |
4578 | Leading and trailing white space in configuration lines is always ignored. | |
4579 | ||
4580 | Blank lines in the file, and lines starting with a # character (ignoring | |
4581 | leading white space) are treated as comments and are ignored. Note: A # | |
4582 | character other than at the beginning of a line is not treated specially, and | |
4583 | does not introduce a comment. | |
4584 | ||
4585 | Any non-comment line can be continued by ending it with a backslash. Note that | |
4586 | the general rule for white space means that trailing white space after the | |
4587 | backslash and leading white space at the start of continuation lines is | |
4588 | ignored. Comment lines beginning with # (but not empty lines) may appear in the | |
4589 | middle of a sequence of continuation lines. | |
4590 | ||
4591 | A convenient way to create a configuration file is to start from the default, | |
4592 | which is supplied in src/configure.default, and add, delete, or change settings | |
4593 | as required. | |
4594 | ||
4595 | The ACLs, retry rules, and rewriting rules have their own syntax which is | |
2813c06e | 4596 | described in chapters 43, 32, and 31, respectively. The other parts of the |
420a0d19 | 4597 | configuration file have some syntactic items in common, and these are described |
2813c06e | 4598 | below, from section 6.11 onwards. Before that, the inclusion, macro, and |
420a0d19 CE |
4599 | conditional facilities are described. |
4600 | ||
4601 | ||
4602 | 6.3 File inclusions in the configuration file | |
4603 | --------------------------------------------- | |
4604 | ||
4605 | You can include other files inside Exim's run time configuration file by using | |
4606 | this syntax: | |
4607 | ||
4608 | .include <file name> | |
4609 | .include_if_exists <file name> | |
4610 | ||
4611 | on a line by itself. Double quotes round the file name are optional. If you use | |
4612 | the first form, a configuration error occurs if the file does not exist; the | |
2813c06e CE |
4613 | second form does nothing for non-existent files. |
4614 | ||
4615 | The first form allows a relative name. It is resolved relative to the directory | |
4616 | of the including file. For the second form an absolute file name is required. | |
420a0d19 CE |
4617 | |
4618 | Includes may be nested to any depth, but remember that Exim reads its | |
4619 | configuration file often, so it is a good idea to keep them to a minimum. If | |
4620 | you change the contents of an included file, you must HUP the daemon, because | |
4621 | an included file is read only when the configuration itself is read. | |
4622 | ||
4623 | The processing of inclusions happens early, at a physical line level, so, like | |
4624 | comment lines, an inclusion can be used in the middle of an option setting, for | |
4625 | example: | |
4626 | ||
4627 | hosts_lookup = a.b.c \ | |
4628 | .include /some/file | |
4629 | ||
4630 | Include processing happens after macro processing (see below). Its effect is to | |
4631 | process the lines of the included file as if they occurred inline where the | |
4632 | inclusion appears. | |
4633 | ||
4634 | ||
4635 | 6.4 Macros in the configuration file | |
4636 | ------------------------------------ | |
4637 | ||
4638 | If a line in the main part of the configuration (that is, before the first | |
4639 | "begin" line) begins with an upper case letter, it is taken as a macro | |
4640 | definition, and must be of the form | |
4641 | ||
4642 | <name> = <rest of line> | |
4643 | ||
4644 | The name must consist of letters, digits, and underscores, and need not all be | |
4645 | in upper case, though that is recommended. The rest of the line, including any | |
4646 | continuations, is the replacement text, and has leading and trailing white | |
4647 | space removed. Quotes are not removed. The replacement text can never end with | |
4648 | a backslash character, but this doesn't seem to be a serious limitation. | |
4649 | ||
4650 | Macros may also be defined between router, transport, authenticator, or ACL | |
4651 | definitions. They may not, however, be defined within an individual driver or | |
4652 | ACL, or in the local_scan, retry, or rewrite sections of the configuration. | |
4653 | ||
4654 | ||
4655 | 6.5 Macro substitution | |
4656 | ---------------------- | |
4657 | ||
4658 | Once a macro is defined, all subsequent lines in the file (and any included | |
4659 | files) are scanned for the macro name; if there are several macros, the line is | |
4660 | scanned for each in turn, in the order in which the macros are defined. The | |
4661 | replacement text is not re-scanned for the current macro, though it is scanned | |
4662 | for subsequently defined macros. For this reason, a macro name may not contain | |
4663 | the name of a previously defined macro as a substring. You could, for example, | |
4664 | define | |
4665 | ||
4666 | ABCD_XYZ = <something> | |
4667 | ABCD = <something else> | |
4668 | ||
4669 | but putting the definitions in the opposite order would provoke a configuration | |
4670 | error. Macro expansion is applied to individual physical lines from the file, | |
4671 | before checking for line continuation or file inclusion (see above). If a line | |
4672 | consists solely of a macro name, and the expansion of the macro is empty, the | |
4673 | line is ignored. A macro at the start of a line may turn the line into a | |
4674 | comment line or a ".include" line. | |
4675 | ||
4676 | ||
4677 | 6.6 Redefining macros | |
4678 | --------------------- | |
4679 | ||
4680 | Once defined, the value of a macro can be redefined later in the configuration | |
4681 | (or in an included file). Redefinition is specified by using == instead of =. | |
4682 | For example: | |
4683 | ||
4684 | MAC = initial value | |
4685 | ... | |
4686 | MAC == updated value | |
4687 | ||
4688 | Redefinition does not alter the order in which the macros are applied to the | |
4689 | subsequent lines of the configuration file. It is still the same order in which | |
4690 | the macros were originally defined. All that changes is the macro's value. | |
4691 | Redefinition makes it possible to accumulate values. For example: | |
4692 | ||
4693 | MAC = initial value | |
4694 | ... | |
4695 | MAC == MAC and something added | |
4696 | ||
4697 | This can be helpful in situations where the configuration file is built from a | |
4698 | number of other files. | |
4699 | ||
4700 | ||
4701 | 6.7 Overriding macro values | |
4702 | --------------------------- | |
4703 | ||
4704 | The values set for macros in the configuration file can be overridden by the -D | |
4705 | command line option, but Exim gives up its root privilege when -D is used, | |
4706 | unless called by root or the Exim user. A definition on the command line using | |
4707 | the -D option causes all definitions and redefinitions within the file to be | |
4708 | ignored. | |
4709 | ||
4710 | ||
4711 | 6.8 Example of macro usage | |
4712 | -------------------------- | |
4713 | ||
4714 | As an example of macro usage, consider a configuration where aliases are looked | |
4715 | up in a MySQL database. It helps to keep the file less cluttered if long | |
4716 | strings such as SQL statements are defined separately as macros, for example: | |
4717 | ||
4718 | ALIAS_QUERY = select mailbox from user where \ | |
4719 | login='${quote_mysql:$local_part}'; | |
4720 | ||
4721 | This can then be used in a redirect router setting like this: | |
4722 | ||
4723 | data = ${lookup mysql{ALIAS_QUERY}} | |
4724 | ||
4725 | In earlier versions of Exim macros were sometimes used for domain, host, or | |
4726 | address lists. In Exim 4 these are handled better by named lists - see section | |
4727 | 10.5. | |
4728 | ||
4729 | ||
2813c06e CE |
4730 | 6.9 Builtin macros |
4731 | ------------------ | |
4732 | ||
4733 | Exim defines some macros depending on facilities available, which may differ | |
4734 | due to build-time definitions and from one release to another. All of these | |
4735 | macros start with an underscore. They can be used to conditionally include | |
4736 | parts of a configuration (see below). | |
4737 | ||
4738 | The following classes of macros are defined: | |
4739 | ||
4740 | _HAVE_* build-time defines | |
4741 | _DRIVER_ROUTER_* router drivers | |
4742 | _DRIVER_TRANSPORT_* transport drivers | |
4743 | _DRIVER_AUTHENTICATOR_* authenticator drivers | |
4744 | _OPT_MAIN_* main config options | |
4745 | _OPT_ROUTERS_* generic router options | |
4746 | _OPT_TRANSPORTS_* generic transport options | |
4747 | _OPT_AUTHENTICATORS_* generic authenticator options | |
4748 | _OPT_ROUTER_*_* private router options | |
4749 | _OPT_TRANSPORT_*_* private transport options | |
4750 | _OPT_AUTHENTICATOR_*_* private authenticator options | |
4751 | ||
4752 | Use an "exim -bP macros" command to get the list of macros. | |
4753 | ||
4754 | ||
4755 | 6.10 Conditional skips in the configuration file | |
4756 | ------------------------------------------------ | |
420a0d19 CE |
4757 | |
4758 | You can use the directives ".ifdef", ".ifndef", ".elifdef", ".elifndef", | |
4759 | ".else", and ".endif" to dynamically include or exclude portions of the | |
4760 | configuration file. The processing happens whenever the file is read (that is, | |
4761 | when an Exim binary starts to run). | |
4762 | ||
4763 | The implementation is very simple. Instances of the first four directives must | |
4764 | be followed by text that includes the names of one or macros. The condition | |
4765 | that is tested is whether or not any macro substitution has taken place in the | |
4766 | line. Thus: | |
4767 | ||
4768 | .ifdef AAA | |
4769 | message_size_limit = 50M | |
4770 | .else | |
4771 | message_size_limit = 100M | |
4772 | .endif | |
4773 | ||
2813c06e CE |
4774 | sets a message size limit of 50M if the macro "AAA" is defined (or "A" or |
4775 | "AA"), and 100M otherwise. If there is more than one macro named on the line, | |
4776 | the condition is true if any of them are defined. That is, it is an "or" | |
4777 | condition. To obtain an "and" condition, you need to use nested ".ifdef"s. | |
420a0d19 CE |
4778 | |
4779 | Although you can use a macro expansion to generate one of these directives, it | |
4780 | is not very useful, because the condition "there was a macro substitution in | |
4781 | this line" will always be true. | |
4782 | ||
4783 | Text following ".else" and ".endif" is ignored, and can be used as comment to | |
4784 | clarify complicated nestings. | |
4785 | ||
4786 | ||
2813c06e | 4787 | 6.11 Common option syntax |
420a0d19 CE |
4788 | ------------------------- |
4789 | ||
4790 | For the main set of options, driver options, and local_scan() options, each | |
4791 | setting is on a line by itself, and starts with a name consisting of lower-case | |
4792 | letters and underscores. Many options require a data value, and in these cases | |
4793 | the name must be followed by an equals sign (with optional white space) and | |
4794 | then the value. For example: | |
4795 | ||
4796 | qualify_domain = mydomain.example.com | |
4797 | ||
4798 | Some option settings may contain sensitive data, for example, passwords for | |
4799 | accessing databases. To stop non-admin users from using the -bP command line | |
4800 | option to read these values, you can precede the option settings with the word | |
4801 | "hide". For example: | |
4802 | ||
4803 | hide mysql_servers = localhost/users/admin/secret-password | |
4804 | ||
4805 | For non-admin users, such options are displayed like this: | |
4806 | ||
4807 | mysql_servers = <value not displayable> | |
4808 | ||
4809 | If "hide" is used on a driver option, it hides the value of that option on all | |
4810 | instances of the same driver. | |
4811 | ||
4812 | The following sections describe the syntax used for the different data types | |
4813 | that are found in option settings. | |
4814 | ||
4815 | ||
2813c06e | 4816 | 6.12 Boolean options |
420a0d19 CE |
4817 | -------------------- |
4818 | ||
4819 | Options whose type is given as boolean are on/off switches. There are two | |
4820 | different ways of specifying such options: with and without a data value. If | |
4821 | the option name is specified on its own without data, the switch is turned on; | |
4822 | if it is preceded by "no_" or "not_" the switch is turned off. However, boolean | |
4823 | options may be followed by an equals sign and one of the words "true", "false", | |
4824 | "yes", or "no", as an alternative syntax. For example, the following two | |
4825 | settings have exactly the same effect: | |
4826 | ||
4827 | queue_only | |
4828 | queue_only = true | |
4829 | ||
4830 | The following two lines also have the same (opposite) effect: | |
4831 | ||
4832 | no_queue_only | |
4833 | queue_only = false | |
4834 | ||
4835 | You can use whichever syntax you prefer. | |
4836 | ||
4837 | ||
2813c06e | 4838 | 6.13 Integer values |
420a0d19 CE |
4839 | ------------------- |
4840 | ||
4841 | If an option's type is given as "integer", the value can be given in decimal, | |
4842 | hexadecimal, or octal. If it starts with a digit greater than zero, a decimal | |
4843 | number is assumed. Otherwise, it is treated as an octal number unless it starts | |
4844 | with the characters "0x", in which case the remainder is interpreted as a | |
4845 | hexadecimal number. | |
4846 | ||
4847 | If an integer value is followed by the letter K, it is multiplied by 1024; if | |
2813c06e CE |
4848 | it is followed by the letter M, it is multiplied by 1024x1024; if by the letter |
4849 | G, 1024x1024x1024. When the values of integer option settings are output, | |
4850 | values which are an exact multiple of 1024 or 1024x1024 are sometimes, but not | |
4851 | always, printed using the letters K and M. The printing style is independent of | |
4852 | the actual input format that was used. | |
420a0d19 CE |
4853 | |
4854 | ||
2813c06e | 4855 | 6.14 Octal integer values |
420a0d19 CE |
4856 | ------------------------- |
4857 | ||
4858 | If an option's type is given as "octal integer", its value is always | |
4859 | interpreted as an octal number, whether or not it starts with the digit zero. | |
4860 | Such options are always output in octal. | |
4861 | ||
4862 | ||
2813c06e | 4863 | 6.15 Fixed point numbers |
420a0d19 CE |
4864 | ------------------------ |
4865 | ||
4866 | If an option's type is given as "fixed-point", its value must be a decimal | |
4867 | integer, optionally followed by a decimal point and up to three further digits. | |
4868 | ||
4869 | ||
2813c06e | 4870 | 6.16 Time intervals |
420a0d19 CE |
4871 | ------------------- |
4872 | ||
4873 | A time interval is specified as a sequence of numbers, each followed by one of | |
4874 | the following letters, with no intervening white space: | |
4875 | ||
4876 | s seconds | |
4877 | m minutes | |
4878 | h hours | |
4879 | d days | |
4880 | w weeks | |
4881 | ||
4882 | For example, "3h50m" specifies 3 hours and 50 minutes. The values of time | |
4883 | intervals are output in the same format. Exim does not restrict the values; it | |
4884 | is perfectly acceptable, for example, to specify "90m" instead of "1h30m". | |
4885 | ||
4886 | ||
2813c06e | 4887 | 6.17 String values |
420a0d19 CE |
4888 | ------------------ |
4889 | ||
4890 | If an option's type is specified as "string", the value can be specified with | |
4891 | or without double-quotes. If it does not start with a double-quote, the value | |
4892 | consists of the remainder of the line plus any continuation lines, starting at | |
4893 | the first character after any leading white space, with trailing white space | |
4894 | removed, and with no interpretation of the characters in the string. Because | |
4895 | Exim removes comment lines (those beginning with #) at an early stage, they can | |
4896 | appear in the middle of a multi-line string. The following two settings are | |
4897 | therefore equivalent: | |
4898 | ||
4899 | trusted_users = uucp:mail | |
4900 | trusted_users = uucp:\ | |
4901 | # This comment line is ignored | |
4902 | ||
4903 | ||
4904 | If a string does start with a double-quote, it must end with a closing | |
4905 | double-quote, and any backslash characters other than those used for line | |
4906 | continuation are interpreted as escape characters, as follows: | |
4907 | ||
4908 | "\\" single backslash | |
4909 | "\n" newline | |
4910 | "\r" carriage return | |
4911 | "\t" tab | |
4912 | "\"<octal digits> up to 3 octal digits specify one character | |
4913 | "\x"<hex digits> up to 2 hexadecimal digits specify one character | |
4914 | ||
4915 | If a backslash is followed by some other character, including a double-quote | |
4916 | character, that character replaces the pair. | |
4917 | ||
4918 | Quoting is necessary only if you want to make use of the backslash escapes to | |
4919 | insert special characters, or if you need to specify a value with leading or | |
4920 | trailing spaces. These cases are rare, so quoting is almost never needed in | |
4921 | current versions of Exim. In versions of Exim before 3.14, quoting was required | |
4922 | in order to continue lines, so you may come across older configuration files | |
4923 | and examples that apparently quote unnecessarily. | |
4924 | ||
4925 | ||
2813c06e | 4926 | 6.18 Expanded strings |
420a0d19 CE |
4927 | --------------------- |
4928 | ||
4929 | Some strings in the configuration file are subjected to string expansion, by | |
4930 | which means various parts of the string may be changed according to the | |
4931 | circumstances (see chapter 11). The input syntax for such strings is as just | |
4932 | described; in particular, the handling of backslashes in quoted strings is done | |
4933 | as part of the input process, before expansion takes place. However, backslash | |
4934 | is also an escape character for the expander, so any backslashes that are | |
4935 | required for that reason must be doubled if they are within a quoted | |
4936 | configuration string. | |
4937 | ||
4938 | ||
2813c06e | 4939 | 6.19 User and group names |
420a0d19 CE |
4940 | ------------------------- |
4941 | ||
4942 | User and group names are specified as strings, using the syntax described | |
4943 | above, but the strings are interpreted specially. A user or group name must | |
4944 | either consist entirely of digits, or be a name that can be looked up using the | |
4945 | getpwnam() or getgrnam() function, as appropriate. | |
4946 | ||
4947 | ||
2813c06e | 4948 | 6.20 List construction |
420a0d19 CE |
4949 | ---------------------- |
4950 | ||
4951 | The data for some configuration options is a list of items, with colon as the | |
4952 | default separator. Many of these options are shown with type "string list" in | |
4953 | the descriptions later in this document. Others are listed as "domain list", | |
4954 | "host list", "address list", or "local part list". Syntactically, they are all | |
4955 | the same; however, those other than "string list" are subject to particular | |
4956 | kinds of interpretation, as described in chapter 10. | |
4957 | ||
4958 | In all these cases, the entire list is treated as a single string as far as the | |
2813c06e | 4959 | input syntax is concerned. The trusted_users setting in section 6.17 above is |
420a0d19 CE |
4960 | an example. If a colon is actually needed in an item in a list, it must be |
4961 | entered as two colons. Leading and trailing white space on each item in a list | |
4962 | is ignored. This makes it possible to include items that start with a colon, | |
4963 | and in particular, certain forms of IPv6 address. For example, the list | |
4964 | ||
4965 | local_interfaces = 127.0.0.1 : ::::1 | |
4966 | ||
4967 | contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1. | |
4968 | ||
4969 | Note: Although leading and trailing white space is ignored in individual list | |
4970 | items, it is not ignored when parsing the list. The space after the first colon | |
4971 | in the example above is necessary. If it were not there, the list would be | |
4972 | interpreted as the two items 127.0.0.1:: and 1. | |
4973 | ||
4974 | ||
2813c06e | 4975 | 6.21 Changing list separators |
420a0d19 CE |
4976 | ----------------------------- |
4977 | ||
4978 | Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was | |
4979 | introduced to allow the separator character to be changed. If a list begins | |
4980 | with a left angle bracket, followed by any punctuation character, that | |
4981 | character is used instead of colon as the list separator. For example, the list | |
4982 | above can be rewritten to use a semicolon separator like this: | |
4983 | ||
4984 | local_interfaces = <; 127.0.0.1 ; ::1 | |
4985 | ||
4986 | This facility applies to all lists, with the exception of the list in | |
4987 | log_file_path. It is recommended that the use of non-colon separators be | |
4988 | confined to circumstances where they really are needed. | |
4989 | ||
4990 | It is also possible to use newline and other control characters (those with | |
4991 | code values less than 32, plus DEL) as separators in lists. Such separators | |
4992 | must be provided literally at the time the list is processed. For options that | |
4993 | are string-expanded, you can write the separator using a normal escape | |
4994 | sequence. This will be processed by the expander before the string is | |
4995 | interpreted as a list. For example, if a newline-separated list of domains is | |
4996 | generated by a lookup, you can process it directly by a line such as this: | |
4997 | ||
4998 | domains = <\n ${lookup mysql{.....}} | |
4999 | ||
5000 | This avoids having to change the list separator in such data. You are unlikely | |
5001 | to want to use a control character as a separator in an option that is not | |
5002 | expanded, because the value is literal text. However, it can be done by giving | |
5003 | the value in quotes. For example: | |
5004 | ||
5005 | local_interfaces = "<\n 127.0.0.1 \n ::1" | |
5006 | ||
5007 | Unlike printing character separators, which can be included in list items by | |
5008 | doubling, it is not possible to include a control character as data when it is | |
5009 | set as the separator. Two such characters in succession are interpreted as | |
5010 | enclosing an empty list item. | |
5011 | ||
5012 | ||
2813c06e | 5013 | 6.22 Empty items in lists |
420a0d19 CE |
5014 | ------------------------- |
5015 | ||
5016 | An empty item at the end of a list is always ignored. In other words, trailing | |
5017 | separator characters are ignored. Thus, the list in | |
5018 | ||
5019 | senders = user@domain : | |
5020 | ||
5021 | contains only a single item. If you want to include an empty string as one item | |
5022 | in a list, it must not be the last item. For example, this list contains three | |
5023 | items, the second of which is empty: | |
5024 | ||
5025 | senders = user1@domain : : user2@domain | |
5026 | ||
5027 | Note: There must be white space between the two colons, as otherwise they are | |
5028 | interpreted as representing a single colon data character (and the list would | |
5029 | then contain just one item). If you want to specify a list that contains just | |
5030 | one, empty item, you can do it as in this example: | |
5031 | ||
5032 | senders = : | |
5033 | ||
5034 | In this case, the first item is empty, and the second is discarded because it | |
5035 | is at the end of the list. | |
5036 | ||
5037 | ||
2813c06e | 5038 | 6.23 Format of driver configurations |
420a0d19 CE |
5039 | ------------------------------------ |
5040 | ||
5041 | There are separate parts in the configuration for defining routers, transports, | |
5042 | and authenticators. In each part, you are defining a number of driver | |
5043 | instances, each with its own set of options. Each driver instance is defined by | |
5044 | a sequence of lines like this: | |
5045 | ||
5046 | <instance name>: | |
5047 | <option> | |
5048 | ... | |
5049 | <option> | |
5050 | ||
5051 | In the following example, the instance name is localuser, and it is followed by | |
5052 | three options settings: | |
5053 | ||
5054 | localuser: | |
5055 | driver = accept | |
5056 | check_local_user | |
5057 | transport = local_delivery | |
5058 | ||
5059 | For each driver instance, you specify which Exim code module it uses - by the | |
5060 | setting of the driver option - and (optionally) some configuration settings. | |
5061 | For example, in the case of transports, if you want a transport to deliver with | |
5062 | SMTP you would use the smtp driver; if you want to deliver to a local file you | |
5063 | would use the appendfile driver. Each of the drivers is described in detail in | |
5064 | its own separate chapter later in this manual. | |
5065 | ||
5066 | You can have several routers, transports, or authenticators that are based on | |
5067 | the same underlying driver (each must have a different instance name). | |
5068 | ||
5069 | The order in which routers are defined is important, because addresses are | |
5070 | passed to individual routers one by one, in order. The order in which | |
5071 | transports are defined does not matter at all. The order in which | |
5072 | authenticators are defined is used only when Exim, as a client, is searching | |
5073 | them to find one that matches an authentication mechanism offered by the | |
5074 | server. | |
5075 | ||
5076 | Within a driver instance definition, there are two kinds of option: generic and | |
5077 | private. The generic options are those that apply to all drivers of the same | |
5078 | type (that is, all routers, all transports or all authenticators). The driver | |
5079 | option is a generic option that must appear in every definition. The private | |
5080 | options are special for each driver, and none need appear, because they all | |
5081 | have default values. | |
5082 | ||
5083 | The options may appear in any order, except that the driver option must precede | |
5084 | any private options, since these depend on the particular driver. For this | |
5085 | reason, it is recommended that driver always be the first option. | |
5086 | ||
5087 | Driver instance names, which are used for reference in log entries and | |
5088 | elsewhere, can be any sequence of letters, digits, and underscores (starting | |
5089 | with a letter) and must be unique among drivers of the same type. A router and | |
5090 | a transport (for example) can each have the same name, but no two router | |
5091 | instances can have the same name. The name of a driver instance should not be | |
5092 | confused with the name of the underlying driver module. For example, the | |
5093 | configuration lines: | |
5094 | ||
5095 | remote_smtp: | |
5096 | driver = smtp | |
5097 | ||
5098 | create an instance of the smtp transport driver whose name is remote_smtp. The | |
5099 | same driver code can be used more than once, with different instance names and | |
5100 | different option settings each time. A second instance of the smtp transport, | |
5101 | with different options, might be defined thus: | |
5102 | ||
5103 | special_smtp: | |
5104 | driver = smtp | |
5105 | port = 1234 | |
5106 | command_timeout = 10s | |
5107 | ||
5108 | The names remote_smtp and special_smtp would be used to reference these | |
5109 | transport instances from routers, and these names would appear in log lines. | |
5110 | ||
5111 | Comment lines may be present in the middle of driver specifications. The full | |
5112 | list of option settings for any particular driver instance, including all the | |
5113 | defaulted values, can be extracted by making use of the -bP command line | |
5114 | option. | |
5115 | ||
5116 | ||
5117 | ||
5118 | =============================================================================== | |
5119 | 7. THE DEFAULT CONFIGURATION FILE | |
5120 | ||
5121 | The default configuration file supplied with Exim as src/configure.default is | |
5122 | sufficient for a host with simple mail requirements. As an introduction to the | |
5123 | way Exim is configured, this chapter "walks through" the default configuration, | |
5124 | giving brief explanations of the settings. Detailed descriptions of the options | |
5125 | are given in subsequent chapters. The default configuration file itself | |
5126 | contains extensive comments about ways you might want to modify the initial | |
5127 | settings. However, note that there are many options that are not mentioned at | |
5128 | all in the default configuration. | |
5129 | ||
5130 | ||
5131 | 7.1 Main configuration settings | |
5132 | ------------------------------- | |
5133 | ||
5134 | The main (global) configuration option settings must always come first in the | |
5135 | file. The first thing you'll see in the file, after some initial comments, is | |
5136 | the line | |
5137 | ||
5138 | # primary_hostname = | |
5139 | ||
5140 | This is a commented-out setting of the primary_hostname option. Exim needs to | |
5141 | know the official, fully qualified name of your host, and this is where you can | |
5142 | specify it. However, in most cases you do not need to set this option. When it | |
5143 | is unset, Exim uses the uname() system function to obtain the host name. | |
5144 | ||
5145 | The first three non-comment configuration lines are as follows: | |
5146 | ||
5147 | domainlist local_domains = @ | |
5148 | domainlist relay_to_domains = | |
5149 | hostlist relay_from_hosts = 127.0.0.1 | |
5150 | ||
5151 | These are not, in fact, option settings. They are definitions of two named | |
5152 | domain lists and one named host list. Exim allows you to give names to lists of | |
5153 | domains, hosts, and email addresses, in order to make it easier to manage the | |
5154 | configuration file (see section 10.5). | |
5155 | ||
5156 | The first line defines a domain list called local_domains; this is used later | |
5157 | in the configuration to identify domains that are to be delivered on the local | |
5158 | host. | |
5159 | ||
5160 | There is just one item in this list, the string "@". This is a special form of | |
5161 | entry which means "the name of the local host". Thus, if the local host is | |
5162 | called a.host.example, mail to any.user@a.host.example is expected to be | |
5163 | delivered locally. Because the local host's name is referenced indirectly, the | |
5164 | same configuration file can be used on different hosts. | |
5165 | ||
5166 | The second line defines a domain list called relay_to_domains, but the list | |
5167 | itself is empty. Later in the configuration we will come to the part that | |
5168 | controls mail relaying through the local host; it allows relaying to any | |
5169 | domains in this list. By default, therefore, no relaying on the basis of a mail | |
5170 | domain is permitted. | |
5171 | ||
5172 | The third line defines a host list called relay_from_hosts. This list is used | |
5173 | later in the configuration to permit relaying from any host or IP address that | |
5174 | matches the list. The default contains just the IP address of the IPv4 loopback | |
5175 | interface, which means that processes on the local host are able to submit mail | |
5176 | for relaying by sending it over TCP/IP to that interface. No other hosts are | |
5177 | permitted to submit messages for relaying. | |
5178 | ||
5179 | Just to be sure there's no misunderstanding: at this point in the configuration | |
5180 | we aren't actually setting up any controls. We are just defining some domains | |
5181 | and hosts that will be used in the controls that are specified later. | |
5182 | ||
5183 | The next two configuration lines are genuine option settings: | |
5184 | ||
5185 | acl_smtp_rcpt = acl_check_rcpt | |
5186 | acl_smtp_data = acl_check_data | |
5187 | ||
5188 | These options specify Access Control Lists (ACLs) that are to be used during an | |
5189 | incoming SMTP session for every recipient of a message (every RCPT command), | |
5190 | and after the contents of the message have been received, respectively. The | |
5191 | names of the lists are acl_check_rcpt and acl_check_data, and we will come to | |
5192 | their definitions below, in the ACL section of the configuration. The RCPT ACL | |
5193 | controls which recipients are accepted for an incoming message - if a | |
5194 | configuration does not provide an ACL to check recipients, no SMTP mail can be | |
5195 | accepted. The DATA ACL allows the contents of a message to be checked. | |
5196 | ||
5197 | Two commented-out option settings are next: | |
5198 | ||
5199 | # av_scanner = clamd:/tmp/clamd | |
5200 | # spamd_address = 127.0.0.1 783 | |
5201 | ||
5202 | These are example settings that can be used when Exim is compiled with the | |
5203 | content-scanning extension. The first specifies the interface to the virus | |
5204 | scanner, and the second specifies the interface to SpamAssassin. Further | |
2813c06e | 5205 | details are given in chapter 44. |
420a0d19 CE |
5206 | |
5207 | Three more commented-out option settings follow: | |
5208 | ||
5209 | # tls_advertise_hosts = * | |
5210 | # tls_certificate = /etc/ssl/exim.crt | |
5211 | # tls_privatekey = /etc/ssl/exim.pem | |
5212 | ||
5213 | These are example settings that can be used when Exim is compiled with support | |
5214 | for TLS (aka SSL) as described in section 4.7. The first one specifies the list | |
5215 | of clients that are allowed to use TLS when connecting to this server; in this | |
5216 | case the wildcard means all clients. The other options specify where Exim | |
5217 | should find its TLS certificate and private key, which together prove the | |
5218 | server's identity to any clients that connect. More details are given in | |
2813c06e | 5219 | chapter 42. |
420a0d19 CE |
5220 | |
5221 | Another two commented-out option settings follow: | |
5222 | ||
5223 | # daemon_smtp_ports = 25 : 465 : 587 | |
5224 | # tls_on_connect_ports = 465 | |
5225 | ||
5226 | These options provide better support for roaming users who wish to use this | |
5227 | server for message submission. They are not much use unless you have turned on | |
5228 | TLS (as described in the previous paragraph) and authentication (about which | |
5229 | more in section 7.7). The usual SMTP port 25 is often blocked on end-user | |
5230 | networks, so RFC 4409 specifies that message submission should use port 587 | |
5231 | instead. However some software (notably Microsoft Outlook) cannot be configured | |
5232 | to use port 587 correctly, so these settings also enable the non-standard | |
5233 | "smtps" (aka "ssmtp") port 465 (see section 13.4). | |
5234 | ||
5235 | Two more commented-out options settings follow: | |
5236 | ||
5237 | # qualify_domain = | |
5238 | # qualify_recipient = | |
5239 | ||
5240 | The first of these specifies a domain that Exim uses when it constructs a | |
5241 | complete email address from a local login name. This is often needed when Exim | |
5242 | receives a message from a local process. If you do not set qualify_domain, the | |
5243 | value of primary_hostname is used. If you set both of these options, you can | |
5244 | have different qualification domains for sender and recipient addresses. If you | |
5245 | set only the first one, its value is used in both cases. | |
5246 | ||
5247 | The following line must be uncommented if you want Exim to recognize addresses | |
5248 | of the form user@[10.11.12.13] that is, with a "domain literal" (an IP address | |
5249 | within square brackets) instead of a named domain. | |
5250 | ||
5251 | # allow_domain_literals | |
5252 | ||
5253 | The RFCs still require this form, but many people think that in the modern | |
5254 | Internet it makes little sense to permit mail to be sent to specific hosts by | |
5255 | quoting their IP addresses. This ancient format has been used by people who try | |
5256 | to abuse hosts by using them for unwanted relaying. However, some people | |
5257 | believe there are circumstances (for example, messages addressed to postmaster) | |
5258 | where domain literals are still useful. | |
5259 | ||
5260 | The next configuration line is a kind of trigger guard: | |
5261 | ||
5262 | never_users = root | |
5263 | ||
5264 | It specifies that no delivery must ever be run as the root user. The normal | |
5265 | convention is to set up root as an alias for the system administrator. This | |
5266 | setting is a guard against slips in the configuration. The list of users | |
5267 | specified by never_users is not, however, the complete list; the build-time | |
5268 | configuration in Local/Makefile has an option called FIXED_NEVER_USERS | |
5269 | specifying a list that cannot be overridden. The contents of never_users are | |
5270 | added to this list. By default FIXED_NEVER_USERS also specifies root. | |
5271 | ||
5272 | When a remote host connects to Exim in order to send mail, the only information | |
5273 | Exim has about the host's identity is its IP address. The next configuration | |
5274 | line, | |
5275 | ||
5276 | host_lookup = * | |
5277 | ||
5278 | specifies that Exim should do a reverse DNS lookup on all incoming connections, | |
5279 | in order to get a host name. This improves the quality of the logging | |
5280 | information, but if you feel it is too expensive, you can remove it entirely, | |
5281 | or restrict the lookup to hosts on "nearby" networks. Note that it is not | |
5282 | always possible to find a host name from an IP address, because not all DNS | |
5283 | reverse zones are maintained, and sometimes DNS servers are unreachable. | |
5284 | ||
5285 | The next two lines are concerned with ident callbacks, as defined by RFC 1413 | |
5286 | (hence their names): | |
5287 | ||
5288 | rfc1413_hosts = * | |
5289 | rfc1413_query_timeout = 0s | |
5290 | ||
5291 | These settings cause Exim to avoid ident callbacks for all incoming SMTP calls. | |
5292 | Few hosts offer RFC1413 service these days; calls have to be terminated by a | |
5293 | timeout and this needlessly delays the startup of an incoming SMTP connection. | |
5294 | If you have hosts for which you trust RFC1413 and need this information, you | |
5295 | can change this. | |
5296 | ||
2813c06e | 5297 | This line enables an efficiency SMTP option. It is negotiated by clients and |
420a0d19 CE |
5298 | not expected to cause problems but can be disabled if needed. |
5299 | ||
5300 | prdr_enable = true | |
5301 | ||
5302 | When Exim receives messages over SMTP connections, it expects all addresses to | |
5303 | be fully qualified with a domain, as required by the SMTP definition. However, | |
5304 | if you are running a server to which simple clients submit messages, you may | |
5305 | find that they send unqualified addresses. The two commented-out options: | |
5306 | ||
5307 | # sender_unqualified_hosts = | |
5308 | # recipient_unqualified_hosts = | |
5309 | ||
5310 | show how you can specify hosts that are permitted to send unqualified sender | |
5311 | and recipient addresses, respectively. | |
5312 | ||
2813c06e CE |
5313 | The log_selector option is used to increase the detail of logging over the |
5314 | default: | |
5315 | ||
5316 | log_selector = +smtp_protocol_error +smtp_syntax_error \ | |
5317 | +tls_certificate_verified | |
5318 | ||
420a0d19 CE |
5319 | The percent_hack_domains option is also commented out: |
5320 | ||
5321 | # percent_hack_domains = | |
5322 | ||
5323 | It provides a list of domains for which the "percent hack" is to operate. This | |
5324 | is an almost obsolete form of explicit email routing. If you do not know | |
5325 | anything about it, you can safely ignore this topic. | |
5326 | ||
2813c06e | 5327 | The next two settings in the main part of the default configuration are |
420a0d19 CE |
5328 | concerned with messages that have been "frozen" on Exim's queue. When a message |
5329 | is frozen, Exim no longer continues to try to deliver it. Freezing occurs when | |
5330 | a bounce message encounters a permanent failure because the sender address of | |
5331 | the original message that caused the bounce is invalid, so the bounce cannot be | |
5332 | delivered. This is probably the most common case, but there are also other | |
5333 | conditions that cause freezing, and frozen messages are not always bounce | |
5334 | messages. | |
5335 | ||
5336 | ignore_bounce_errors_after = 2d | |
5337 | timeout_frozen_after = 7d | |
5338 | ||
5339 | The first of these options specifies that failing bounce messages are to be | |
5340 | discarded after 2 days on the queue. The second specifies that any frozen | |
5341 | message (whether a bounce message or not) is to be timed out (and discarded) | |
5342 | after a week. In this configuration, the first setting ensures that no failing | |
5343 | bounce message ever lasts a week. | |
5344 | ||
2813c06e CE |
5345 | Exim queues it's messages in a spool directory. If you expect to have large |
5346 | queues, you may consider using this option. It splits the spool directory into | |
5347 | subdirectories to avoid file system degradation from many files in a single | |
5348 | directory, resulting in better performance. Manual manipulation of queued | |
5349 | messages becomes more complex (though fortunately not often needed). | |
5350 | ||
5351 | # split_spool_directory = true | |
5352 | ||
5353 | In an ideal world everybody follows the standards. For non-ASCII messages RFC | |
5354 | 2047 is a standard, allowing a maximum line length of 76 characters. Exim | |
5355 | adheres that standard and won't process messages which violate this standard. | |
5356 | (Even ${rfc2047:...} expansions will fail.) In particular, the Exim maintainers | |
5357 | have had multiple reports of problems from Russian administrators of issues | |
5358 | until they disable this check, because of some popular, yet buggy, mail | |
5359 | composition software. | |
5360 | ||
5361 | # check_rfc2047_length = false | |
5362 | ||
5363 | If you need to be strictly RFC compliant you may wish to disable the 8BITMIME | |
5364 | advertisement. Use this, if you exchange mails with systems that are not 8-bit | |
5365 | clean. | |
5366 | ||
5367 | # accept_8bitmime = false | |
5368 | ||
5369 | Libraries you use may depend on specific environment settings. This imposes a | |
5370 | security risk (e.g. PATH). There are two lists: keep_environment for the | |
5371 | variables to import as they are, and add_environment for variables we want to | |
5372 | set to a fixed value. Note that TZ is handled separately, by the $%timezone%$ | |
5373 | runtime option and by the TIMEZONE_DEFAULT buildtime option. | |
5374 | ||
5375 | # keep_environment = ^LDAP | |
5376 | # add_environment = PATH=/usr/bin::/bin | |
5377 | ||
420a0d19 CE |
5378 | |
5379 | 7.2 ACL configuration | |
5380 | --------------------- | |
5381 | ||
5382 | In the default configuration, the ACL section follows the main configuration. | |
5383 | It starts with the line | |
5384 | ||
5385 | begin acl | |
5386 | ||
5387 | and it contains the definitions of two ACLs, called acl_check_rcpt and | |
5388 | acl_check_data, that were referenced in the settings of acl_smtp_rcpt and | |
5389 | acl_smtp_data above. | |
5390 | ||
5391 | The first ACL is used for every RCPT command in an incoming SMTP message. Each | |
5392 | RCPT command specifies one of the message's recipients. The ACL statements are | |
5393 | considered in order, until the recipient address is either accepted or | |
5394 | rejected. The RCPT command is then accepted or rejected, according to the | |
5395 | result of the ACL processing. | |
5396 | ||
5397 | acl_check_rcpt: | |
5398 | ||
5399 | This line, consisting of a name terminated by a colon, marks the start of the | |
5400 | ACL, and names it. | |
5401 | ||
5402 | accept hosts = : | |
5403 | ||
5404 | This ACL statement accepts the recipient if the sending host matches the list. | |
5405 | But what does that strange list mean? It doesn't actually contain any host | |
5406 | names or IP addresses. The presence of the colon puts an empty item in the | |
5407 | list; Exim matches this only if the incoming message did not come from a remote | |
5408 | host, because in that case, the remote hostname is empty. The colon is | |
5409 | important. Without it, the list itself is empty, and can never match anything. | |
5410 | ||
5411 | What this statement is doing is to accept unconditionally all recipients in | |
5412 | messages that are submitted by SMTP from local processes using the standard | |
5413 | input and output (that is, not using TCP/IP). A number of MUAs operate in this | |
5414 | manner. | |
5415 | ||
5416 | deny message = Restricted characters in address | |
5417 | domains = +local_domains | |
5418 | local_parts = ^[.] : ^.*[@%!/|] | |
5419 | ||
5420 | deny message = Restricted characters in address | |
5421 | domains = !+local_domains | |
5422 | local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./ | |
5423 | ||
5424 | These statements are concerned with local parts that contain any of the | |
5425 | characters "@", "%", "!", "/", "|", or dots in unusual places. Although these | |
5426 | characters are entirely legal in local parts (in the case of "@" and leading | |
5427 | dots, only if correctly quoted), they do not commonly occur in Internet mail | |
5428 | addresses. | |
5429 | ||
5430 | The first three have in the past been associated with explicitly routed | |
5431 | addresses (percent is still sometimes used - see the percent_hack_domains | |
5432 | option). Addresses containing these characters are regularly tried by spammers | |
5433 | in an attempt to bypass relaying restrictions, and also by open relay testing | |
5434 | programs. Unless you really need them it is safest to reject these characters | |
5435 | at this early stage. This configuration is heavy-handed in rejecting these | |
5436 | characters for all messages it accepts from remote hosts. This is a deliberate | |
5437 | policy of being as safe as possible. | |
5438 | ||
5439 | The first rule above is stricter, and is applied to messages that are addressed | |
5440 | to one of the local domains handled by this host. This is implemented by the | |
5441 | first condition, which restricts it to domains that are listed in the | |
5442 | local_domains domain list. The "+" character is used to indicate a reference to | |
5443 | a named list. In this configuration, there is just one domain in local_domains, | |
5444 | but in general there may be many. | |
5445 | ||
5446 | The second condition on the first statement uses two regular expressions to | |
5447 | block local parts that begin with a dot or contain "@", "%", "!", "/", or "|". | |
5448 | If you have local accounts that include these characters, you will have to | |
5449 | modify this rule. | |
5450 | ||
5451 | Empty components (two dots in a row) are not valid in RFC 2822, but Exim allows | |
5452 | them because they have been encountered in practice. (Consider the common | |
5453 | convention of local parts constructed as " | |
5454 | first-initial.second-initial.family-name" when applied to someone like the | |
5455 | author of Exim, who has no second initial.) However, a local part starting with | |
5456 | a dot or containing "/../" can cause trouble if it is used as part of a file | |
5457 | name (for example, for a mailing list). This is also true for local parts that | |
5458 | contain slashes. A pipe symbol can also be troublesome if the local part is | |
5459 | incorporated unthinkingly into a shell command line. | |
5460 | ||
5461 | The second rule above applies to all other domains, and is less strict. This | |
5462 | allows your own users to send outgoing messages to sites that use slashes and | |
5463 | vertical bars in their local parts. It blocks local parts that begin with a | |
5464 | dot, slash, or vertical bar, but allows these characters within the local part. | |
5465 | However, the sequence "/../" is barred. The use of "@", "%", and "!" is | |
5466 | blocked, as before. The motivation here is to prevent your users (or your | |
5467 | users' viruses) from mounting certain kinds of attack on remote sites. | |
5468 | ||
5469 | accept local_parts = postmaster | |
5470 | domains = +local_domains | |
5471 | ||
5472 | This statement, which has two conditions, accepts an incoming address if the | |
5473 | local part is postmaster and the domain is one of those listed in the | |
5474 | local_domains domain list. The "+" character is used to indicate a reference to | |
5475 | a named list. In this configuration, there is just one domain in local_domains, | |
5476 | but in general there may be many. | |
5477 | ||
5478 | The presence of this statement means that mail to postmaster is never blocked | |
5479 | by any of the subsequent tests. This can be helpful while sorting out problems | |
5480 | in cases where the subsequent tests are incorrectly denying access. | |
5481 | ||
5482 | require verify = sender | |
5483 | ||
5484 | This statement requires the sender address to be verified before any subsequent | |
5485 | ACL statement can be used. If verification fails, the incoming recipient | |
5486 | address is refused. Verification consists of trying to route the address, to | |
5487 | see if a bounce message could be delivered to it. In the case of remote | |
5488 | addresses, basic verification checks only the domain, but callouts can be used | |
2813c06e | 5489 | for more verification if required. Section 43.44 discusses the details of |
420a0d19 CE |
5490 | address verification. |
5491 | ||
5492 | accept hosts = +relay_from_hosts | |
5493 | control = submission | |
5494 | ||
5495 | This statement accepts the address if the message is coming from one of the | |
5496 | hosts that are defined as being allowed to relay through this host. Recipient | |
5497 | verification is omitted here, because in many cases the clients are dumb MUAs | |
5498 | that do not cope well with SMTP error responses. For the same reason, the | |
5499 | second line specifies "submission mode" for messages that are accepted. This is | |
2813c06e | 5500 | described in detail in section 47.1; it causes Exim to fix messages that are |
420a0d19 CE |
5501 | deficient in some way, for example, because they lack a Date: header line. If |
5502 | you are actually relaying out from MTAs, you should probably add recipient | |
5503 | verification here, and disable submission mode. | |
5504 | ||
5505 | accept authenticated = * | |
5506 | control = submission | |
5507 | ||
5508 | This statement accepts the address if the client host has authenticated itself. | |
5509 | Submission mode is again specified, on the grounds that such messages are most | |
5510 | likely to come from MUAs. The default configuration does not define any | |
5511 | authenticators, though it does include some nearly complete commented-out | |
5512 | examples described in 7.7. This means that no client can in fact authenticate | |
5513 | until you complete the authenticator definitions. | |
5514 | ||
5515 | require message = relay not permitted | |
5516 | domains = +local_domains : +relay_to_domains | |
5517 | ||
5518 | This statement rejects the address if its domain is neither a local domain nor | |
5519 | one of the domains for which this host is a relay. | |
5520 | ||
5521 | require verify = recipient | |
5522 | ||
5523 | This statement requires the recipient address to be verified; if verification | |
5524 | fails, the address is rejected. | |
5525 | ||
5526 | # deny message = rejected because $sender_host_address \ | |
5527 | # is in a black list at $dnslist_domain\n\ | |
5528 | # $dnslist_text | |
5529 | # dnslists = black.list.example | |
5530 | # | |
5531 | # warn dnslists = black.list.example | |
5532 | # add_header = X-Warning: $sender_host_address is in \ | |
5533 | # a black list at $dnslist_domain | |
5534 | # log_message = found in $dnslist_domain | |
5535 | ||
5536 | These commented-out lines are examples of how you could configure Exim to check | |
5537 | sending hosts against a DNS black list. The first statement rejects messages | |
5538 | from blacklisted hosts, whereas the second just inserts a warning header line. | |
5539 | ||
5540 | # require verify = csa | |
5541 | ||
5542 | This commented-out line is an example of how you could turn on client SMTP | |
5543 | authorization (CSA) checking. Such checks do DNS lookups for special SRV | |
5544 | records. | |
5545 | ||
5546 | accept | |
5547 | ||
5548 | The final statement in the first ACL unconditionally accepts any recipient | |
5549 | address that has successfully passed all the previous tests. | |
5550 | ||
5551 | acl_check_data: | |
5552 | ||
5553 | This line marks the start of the second ACL, and names it. Most of the contents | |
5554 | of this ACL are commented out: | |
5555 | ||
5556 | # deny malware = * | |
5557 | # message = This message contains a virus \ | |
5558 | # ($malware_name). | |
5559 | ||
5560 | These lines are examples of how to arrange for messages to be scanned for | |
5561 | viruses when Exim has been compiled with the content-scanning extension, and a | |
5562 | suitable virus scanner is installed. If the message is found to contain a | |
5563 | virus, it is rejected with the given custom error message. | |
5564 | ||
5565 | # warn spam = nobody | |
5566 | # message = X-Spam_score: $spam_score\n\ | |
5567 | # X-Spam_score_int: $spam_score_int\n\ | |
5568 | # X-Spam_bar: $spam_bar\n\ | |
5569 | # X-Spam_report: $spam_report | |
5570 | ||
5571 | These lines are an example of how to arrange for messages to be scanned by | |
5572 | SpamAssassin when Exim has been compiled with the content-scanning extension, | |
5573 | and SpamAssassin has been installed. The SpamAssassin check is run with | |
5574 | "nobody" as its user parameter, and the results are added to the message as a | |
5575 | series of extra header line. In this case, the message is not rejected, | |
5576 | whatever the spam score. | |
5577 | ||
5578 | accept | |
5579 | ||
5580 | This final line in the DATA ACL accepts the message unconditionally. | |
5581 | ||
5582 | ||
5583 | 7.3 Router configuration | |
5584 | ------------------------ | |
5585 | ||
5586 | The router configuration comes next in the default configuration, introduced by | |
5587 | the line | |
5588 | ||
5589 | begin routers | |
5590 | ||
5591 | Routers are the modules in Exim that make decisions about where to send | |
5592 | messages. An address is passed to each router in turn, until it is either | |
5593 | accepted, or failed. This means that the order in which you define the routers | |
5594 | matters. Each router is fully described in its own chapter later in this | |
5595 | manual. Here we give only brief overviews. | |
5596 | ||
5597 | # domain_literal: | |
5598 | # driver = ipliteral | |
5599 | # domains = !+local_domains | |
5600 | # transport = remote_smtp | |
5601 | ||
5602 | This router is commented out because the majority of sites do not want to | |
5603 | support domain literal addresses (those of the form user@[10.9.8.7]). If you | |
5604 | uncomment this router, you also need to uncomment the setting of | |
5605 | allow_domain_literals in the main part of the configuration. | |
5606 | ||
5607 | dnslookup: | |
5608 | driver = dnslookup | |
5609 | domains = ! +local_domains | |
5610 | transport = remote_smtp | |
5611 | ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8 | |
5612 | no_more | |
5613 | ||
5614 | The first uncommented router handles addresses that do not involve any local | |
5615 | domains. This is specified by the line | |
5616 | ||
5617 | domains = ! +local_domains | |
5618 | ||
5619 | The domains option lists the domains to which this router applies, but the | |
5620 | exclamation mark is a negation sign, so the router is used only for domains | |
5621 | that are not in the domain list called local_domains (which was defined at the | |
5622 | start of the configuration). The plus sign before local_domains indicates that | |
5623 | it is referring to a named list. Addresses in other domains are passed on to | |
5624 | the following routers. | |
5625 | ||
5626 | The name of the router driver is dnslookup, and is specified by the driver | |
5627 | option. Do not be confused by the fact that the name of this router instance is | |
5628 | the same as the name of the driver. The instance name is arbitrary, but the | |
5629 | name set in the driver option must be one of the driver modules that is in the | |
5630 | Exim binary. | |
5631 | ||
5632 | The dnslookup router routes addresses by looking up their domains in the DNS in | |
5633 | order to obtain a list of hosts to which the address is routed. If the router | |
5634 | succeeds, the address is queued for the remote_smtp transport, as specified by | |
5635 | the transport option. If the router does not find the domain in the DNS, no | |
5636 | further routers are tried because of the no_more setting, so the address fails | |
5637 | and is bounced. | |
5638 | ||
5639 | The ignore_target_hosts option specifies a list of IP addresses that are to be | |
5640 | entirely ignored. This option is present because a number of cases have been | |
5641 | encountered where MX records in the DNS point to host names whose IP addresses | |
5642 | are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1). Completely ignoring | |
5643 | these IP addresses causes Exim to fail to route the email address, so it | |
5644 | bounces. Otherwise, Exim would log a routing problem, and continue to try to | |
5645 | deliver the message periodically until the address timed out. | |
5646 | ||
5647 | system_aliases: | |
5648 | driver = redirect | |
5649 | allow_fail | |
5650 | allow_defer | |
5651 | data = ${lookup{$local_part}lsearch{/etc/aliases}} | |
5652 | # user = exim | |
5653 | file_transport = address_file | |
5654 | pipe_transport = address_pipe | |
5655 | ||
5656 | Control reaches this and subsequent routers only for addresses in the local | |
5657 | domains. This router checks to see whether the local part is defined as an | |
5658 | alias in the /etc/aliases file, and if so, redirects it according to the data | |
5659 | that it looks up from that file. If no data is found for the local part, the | |
5660 | value of the data option is empty, causing the address to be passed to the next | |
5661 | router. | |
5662 | ||
5663 | /etc/aliases is a conventional name for the system aliases file that is often | |
5664 | used. That is why it is referenced by from the default configuration file. | |
5665 | However, you can change this by setting SYSTEM_ALIASES_FILE in Local/Makefile | |
5666 | before building Exim. | |
5667 | ||
5668 | userforward: | |
5669 | driver = redirect | |
5670 | check_local_user | |
5671 | # local_part_suffix = +* : -* | |
5672 | # local_part_suffix_optional | |
5673 | file = $home/.forward | |
5674 | # allow_filter | |
5675 | no_verify | |
5676 | no_expn | |
5677 | check_ancestor | |
5678 | file_transport = address_file | |
5679 | pipe_transport = address_pipe | |
5680 | reply_transport = address_reply | |
5681 | ||
5682 | This is the most complicated router in the default configuration. It is another | |
5683 | redirection router, but this time it is looking for forwarding data set up by | |
5684 | individual users. The check_local_user setting specifies a check that the local | |
5685 | part of the address is the login name of a local user. If it is not, the router | |
5686 | is skipped. The two commented options that follow check_local_user, namely: | |
5687 | ||
5688 | # local_part_suffix = +* : -* | |
5689 | # local_part_suffix_optional | |
5690 | ||
5691 | show how you can specify the recognition of local part suffixes. If the first | |
5692 | is uncommented, a suffix beginning with either a plus or a minus sign, followed | |
5693 | by any sequence of characters, is removed from the local part and placed in the | |
5694 | variable $local_part_suffix. The second suffix option specifies that the | |
5695 | presence of a suffix in the local part is optional. When a suffix is present, | |
5696 | the check for a local login uses the local part with the suffix removed. | |
5697 | ||
5698 | When a local user account is found, the file called .forward in the user's home | |
5699 | directory is consulted. If it does not exist, or is empty, the router declines. | |
5700 | Otherwise, the contents of .forward are interpreted as redirection data (see | |
5701 | chapter 22 for more details). | |
5702 | ||
5703 | Traditional .forward files contain just a list of addresses, pipes, or files. | |
5704 | Exim supports this by default. However, if allow_filter is set (it is commented | |
5705 | out by default), the contents of the file are interpreted as a set of Exim or | |
5706 | Sieve filtering instructions, provided the file begins with "#Exim filter" or " | |
5707 | #Sieve filter", respectively. User filtering is discussed in the separate | |
5708 | document entitled Exim's interfaces to mail filtering. | |
5709 | ||
5710 | The no_verify and no_expn options mean that this router is skipped when | |
5711 | verifying addresses, or when running as a consequence of an SMTP EXPN command. | |
5712 | There are two reasons for doing this: | |
5713 | ||
5714 | 1. Whether or not a local user has a .forward file is not really relevant when | |
5715 | checking an address for validity; it makes sense not to waste resources | |
5716 | doing unnecessary work. | |
5717 | ||
5718 | 2. More importantly, when Exim is verifying addresses or handling an EXPN | |
5719 | command during an SMTP session, it is running as the Exim user, not as | |
5720 | root. The group is the Exim group, and no additional groups are set up. It | |
5721 | may therefore not be possible for Exim to read users' .forward files at | |
5722 | this time. | |
5723 | ||
5724 | The setting of check_ancestor prevents the router from generating a new address | |
5725 | that is the same as any previous address that was redirected. (This works round | |
5726 | a problem concerning a bad interaction between aliasing and forwarding - see | |
5727 | section 22.5). | |
5728 | ||
5729 | The final three option settings specify the transports that are to be used when | |
5730 | forwarding generates a direct delivery to a file, or to a pipe, or sets up an | |
5731 | auto-reply, respectively. For example, if a .forward file contains | |
5732 | ||
5733 | a.nother@elsewhere.example, /home/spqr/archive | |
5734 | ||
5735 | the delivery to /home/spqr/archive is done by running the address_file | |
5736 | transport. | |
5737 | ||
5738 | localuser: | |
5739 | driver = accept | |
5740 | check_local_user | |
5741 | # local_part_suffix = +* : -* | |
5742 | # local_part_suffix_optional | |
5743 | transport = local_delivery | |
5744 | ||
5745 | The final router sets up delivery into local mailboxes, provided that the local | |
5746 | part is the name of a local login, by accepting the address and assigning it to | |
5747 | the local_delivery transport. Otherwise, we have reached the end of the | |
5748 | routers, so the address is bounced. The commented suffix settings fulfil the | |
5749 | same purpose as they do for the userforward router. | |
5750 | ||
5751 | ||
5752 | 7.4 Transport configuration | |
5753 | --------------------------- | |
5754 | ||
5755 | Transports define mechanisms for actually delivering messages. They operate | |
5756 | only when referenced from routers, so the order in which they are defined does | |
5757 | not matter. The transports section of the configuration starts with | |
5758 | ||
5759 | begin transports | |
5760 | ||
5761 | One remote transport and four local transports are defined. | |
5762 | ||
5763 | remote_smtp: | |
5764 | driver = smtp | |
5765 | hosts_try_prdr = * | |
5766 | ||
5767 | This transport is used for delivering messages over SMTP connections. The list | |
5768 | of remote hosts comes from the router. The hosts_try_prdr option enables an | |
5769 | efficiency SMTP option. It is negotiated between client and server and not | |
5770 | expected to cause problems but can be disabled if needed. All other options are | |
5771 | defaulted. | |
5772 | ||
5773 | local_delivery: | |
5774 | driver = appendfile | |
5775 | file = /var/mail/$local_part | |
5776 | delivery_date_add | |
5777 | envelope_to_add | |
5778 | return_path_add | |
5779 | # group = mail | |
5780 | # mode = 0660 | |
5781 | ||
5782 | This appendfile transport is used for local delivery to user mailboxes in | |
5783 | traditional BSD mailbox format. By default it runs under the uid and gid of the | |
5784 | local user, which requires the sticky bit to be set on the /var/mail directory. | |
5785 | Some systems use the alternative approach of running mail deliveries under a | |
5786 | particular group instead of using the sticky bit. The commented options show | |
5787 | how this can be done. | |
5788 | ||
5789 | Exim adds three headers to the message as it delivers it: Delivery-date:, | |
5790 | Envelope-to: and Return-path:. This action is requested by the three | |
5791 | similarly-named options above. | |
5792 | ||
5793 | address_pipe: | |
5794 | driver = pipe | |
5795 | return_output | |
5796 | ||
5797 | This transport is used for handling deliveries to pipes that are generated by | |
5798 | redirection (aliasing or users' .forward files). The return_output option | |
2813c06e CE |
5799 | specifies that any output on stdout or stderr generated by the pipe is to be |
5800 | returned to the sender. | |
420a0d19 CE |
5801 | |
5802 | address_file: | |
5803 | driver = appendfile | |
5804 | delivery_date_add | |
5805 | envelope_to_add | |
5806 | return_path_add | |
5807 | ||
5808 | This transport is used for handling deliveries to files that are generated by | |
5809 | redirection. The name of the file is not specified in this instance of | |
5810 | appendfile, because it comes from the redirect router. | |
5811 | ||
5812 | address_reply: | |
5813 | driver = autoreply | |
5814 | ||
5815 | This transport is used for handling automatic replies generated by users' | |
5816 | filter files. | |
5817 | ||
5818 | ||
5819 | 7.5 Default retry rule | |
5820 | ---------------------- | |
5821 | ||
5822 | The retry section of the configuration file contains rules which affect the way | |
5823 | Exim retries deliveries that cannot be completed at the first attempt. It is | |
5824 | introduced by the line | |
5825 | ||
5826 | begin retry | |
5827 | ||
5828 | In the default configuration, there is just one rule, which applies to all | |
5829 | errors: | |
5830 | ||
5831 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h | |
5832 | ||
5833 | This causes any temporarily failing address to be retried every 15 minutes for | |
5834 | 2 hours, then at intervals starting at one hour and increasing by a factor of | |
5835 | 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address | |
2813c06e CE |
5836 | is not delivered after 4 days of temporary failure, it is bounced. The time is |
5837 | measured from first failure, not from the time the message was received. | |
420a0d19 CE |
5838 | |
5839 | If the retry section is removed from the configuration, or is empty (that is, | |
5840 | if no retry rules are defined), Exim will not retry deliveries. This turns | |
5841 | temporary errors into permanent errors. | |
5842 | ||
5843 | ||
5844 | 7.6 Rewriting configuration | |
5845 | --------------------------- | |
5846 | ||
5847 | The rewriting section of the configuration, introduced by | |
5848 | ||
5849 | begin rewrite | |
5850 | ||
5851 | contains rules for rewriting addresses in messages as they arrive. There are no | |
5852 | rewriting rules in the default configuration file. | |
5853 | ||
5854 | ||
5855 | 7.7 Authenticators configuration | |
5856 | -------------------------------- | |
5857 | ||
5858 | The authenticators section of the configuration, introduced by | |
5859 | ||
5860 | begin authenticators | |
5861 | ||
5862 | defines mechanisms for the use of the SMTP AUTH command. The default | |
5863 | configuration file contains two commented-out example authenticators which | |
5864 | support plaintext username/password authentication using the standard PLAIN | |
5865 | mechanism and the traditional but non-standard LOGIN mechanism, with Exim | |
5866 | acting as the server. PLAIN and LOGIN are enough to support most MUA software. | |
5867 | ||
5868 | The example PLAIN authenticator looks like this: | |
5869 | ||
5870 | #PLAIN: | |
5871 | # driver = plaintext | |
5872 | # server_set_id = $auth2 | |
5873 | # server_prompts = : | |
5874 | # server_condition = Authentication is not yet configured | |
5875 | # server_advertise_condition = ${if def:tls_in_cipher } | |
5876 | ||
5877 | And the example LOGIN authenticator looks like this: | |
5878 | ||
5879 | #LOGIN: | |
5880 | # driver = plaintext | |
5881 | # server_set_id = $auth1 | |
5882 | # server_prompts = <| Username: | Password: | |
5883 | # server_condition = Authentication is not yet configured | |
5884 | # server_advertise_condition = ${if def:tls_in_cipher } | |
5885 | ||
5886 | The server_set_id option makes Exim remember the authenticated username in | |
5887 | $authenticated_id, which can be used later in ACLs or routers. The | |
5888 | server_prompts option configures the plaintext authenticator so that it | |
5889 | implements the details of the specific authentication mechanism, i.e. PLAIN or | |
5890 | LOGIN. The server_advertise_condition setting controls when Exim offers | |
5891 | authentication to clients; in the examples, this is only when TLS or SSL has | |
5892 | been started, so to enable the authenticators you also need to add support for | |
5893 | TLS as described in section 7.1. | |
5894 | ||
5895 | The server_condition setting defines how to verify that the username and | |
5896 | password are correct. In the examples it just produces an error message. To | |
5897 | make the authenticators work, you can use a string expansion expression like | |
5898 | one of the examples in chapter 34. | |
5899 | ||
5900 | Beware that the sequence of the parameters to PLAIN and LOGIN differ; the | |
5901 | usercode and password are in different positions. Chapter 34 covers both. | |
5902 | ||
5903 | ||
5904 | ||
5905 | =============================================================================== | |
5906 | 8. REGULAR EXPRESSIONS | |
5907 | ||
5908 | Exim supports the use of regular expressions in many of its options. It uses | |
5909 | the PCRE regular expression library; this provides regular expression matching | |
5910 | that is compatible with Perl 5. The syntax and semantics of regular expressions | |
2813c06e CE |
5911 | is discussed in online Perl manpages, in many Perl reference books, and also in |
5912 | Jeffrey Friedl's Mastering Regular Expressions, which is published by O'Reilly | |
5913 | (see http://www.oreilly.com/catalog/regex2/). | |
420a0d19 CE |
5914 | |
5915 | The documentation for the syntax and semantics of the regular expressions that | |
5916 | are supported by PCRE is included in the PCRE distribution, and no further | |
5917 | description is included here. The PCRE functions are called from Exim using the | |
5918 | default option settings (that is, with no PCRE options set), except that the | |
5919 | PCRE_CASELESS option is set when the matching is required to be | |
5920 | case-insensitive. | |
5921 | ||
5922 | In most cases, when a regular expression is required in an Exim configuration, | |
5923 | it has to start with a circumflex, in order to distinguish it from plain text | |
5924 | or an "ends with" wildcard. In this example of a configuration setting, the | |
5925 | second item in the colon-separated list is a regular expression. | |
5926 | ||
5927 | domains = a.b.c : ^\\d{3} : *.y.z : ... | |
5928 | ||
5929 | The doubling of the backslash is required because of string expansion that | |
5930 | precedes interpretation - see section 11.1 for more discussion of this issue, | |
5931 | and a way of avoiding the need for doubling backslashes. The regular expression | |
5932 | that is eventually used in this example contains just one backslash. The | |
5933 | circumflex is included in the regular expression, and has the normal effect of | |
5934 | "anchoring" it to the start of the string that is being matched. | |
5935 | ||
5936 | There are, however, two cases where a circumflex is not required for the | |
5937 | recognition of a regular expression: these are the match condition in a string | |
5938 | expansion, and the matches condition in an Exim filter file. In these cases, | |
5939 | the relevant string is always treated as a regular expression; if it does not | |
5940 | start with a circumflex, the expression is not anchored, and can match anywhere | |
5941 | in the subject string. | |
5942 | ||
5943 | In all cases, if you want a regular expression to match at the end of a string, | |
5944 | you must code the $ metacharacter to indicate this. For example: | |
5945 | ||
5946 | domains = ^\\d{3}\\.example | |
5947 | ||
5948 | matches the domain 123.example, but it also matches 123.example.com. You need | |
5949 | to use: | |
5950 | ||
5951 | domains = ^\\d{3}\\.example\$ | |
5952 | ||
5953 | if you want example to be the top-level domain. The backslash before the $ is | |
5954 | needed because string expansion also interprets dollar characters. | |
5955 | ||
5956 | ||
5957 | ||
5958 | =============================================================================== | |
5959 | 9. FILE AND DATABASE LOOKUPS | |
5960 | ||
5961 | Exim can be configured to look up data in files or databases as it processes | |
5962 | messages. Two different kinds of syntax are used: | |
5963 | ||
5964 | 1. A string that is to be expanded may contain explicit lookup requests. These | |
5965 | cause parts of the string to be replaced by data that is obtained from the | |
5966 | lookup. Lookups of this type are conditional expansion items. Different | |
5967 | results can be defined for the cases of lookup success and failure. See | |
2813c06e CE |
5968 | chapter 11, where string expansions are described in detail. The key for |
5969 | the lookup is specified as part of the string expansion. | |
420a0d19 CE |
5970 | |
5971 | 2. Lists of domains, hosts, and email addresses can contain lookup requests as | |
5972 | a way of avoiding excessively long linear lists. In this case, the data | |
5973 | that is returned by the lookup is often (but not always) discarded; whether | |
5974 | the lookup succeeds or fails is what really counts. These kinds of list are | |
2813c06e CE |
5975 | described in chapter 10. The key for the lookup is given by the context in |
5976 | which the list is expanded. | |
420a0d19 CE |
5977 | |
5978 | String expansions, lists, and lookups interact with each other in such a way | |
5979 | that there is no order in which to describe any one of them that does not | |
5980 | involve references to the others. Each of these three chapters makes more sense | |
5981 | if you have read the other two first. If you are reading this for the first | |
5982 | time, be aware that some of it will make a lot more sense after you have read | |
5983 | chapters 10 and 11. | |
5984 | ||
5985 | ||
5986 | 9.1 Examples of different lookup syntax | |
5987 | --------------------------------------- | |
5988 | ||
5989 | It is easy to confuse the two different kinds of lookup, especially as the | |
5990 | lists that may contain the second kind are always expanded before being | |
5991 | processed as lists. Therefore, they may also contain lookups of the first kind. | |
5992 | Be careful to distinguish between the following two examples: | |
5993 | ||
5994 | domains = ${lookup{$sender_host_address}lsearch{/some/file}} | |
5995 | domains = lsearch;/some/file | |
5996 | ||
5997 | The first uses a string expansion, the result of which must be a domain list. | |
5998 | No strings have been specified for a successful or a failing lookup; the | |
5999 | defaults in this case are the looked-up data and an empty string, respectively. | |
6000 | The expansion takes place before the string is processed as a list, and the | |
6001 | file that is searched could contain lines like this: | |
6002 | ||
6003 | 192.168.3.4: domain1:domain2:... | |
6004 | 192.168.1.9: domain3:domain4:... | |
6005 | ||
6006 | When the lookup succeeds, the result of the expansion is a list of domains (and | |
6007 | possibly other types of item that are allowed in domain lists). | |
6008 | ||
6009 | In the second example, the lookup is a single item in a domain list. It causes | |
6010 | Exim to use a lookup to see if the domain that is being processed can be found | |
6011 | in the file. The file could contains lines like this: | |
6012 | ||
6013 | domain1: | |
6014 | domain2: | |
6015 | ||
6016 | Any data that follows the keys is not relevant when checking that the domain | |
6017 | matches the list item. | |
6018 | ||
6019 | It is possible, though no doubt confusing, to use both kinds of lookup at once. | |
6020 | Consider a file containing lines like this: | |
6021 | ||
6022 | 192.168.5.6: lsearch;/another/file | |
6023 | ||
6024 | If the value of $sender_host_address is 192.168.5.6, expansion of the first | |
6025 | domains setting above generates the second setting, which therefore causes a | |
6026 | second lookup to occur. | |
6027 | ||
6028 | The rest of this chapter describes the different lookup types that are | |
6029 | available. Any of them can be used in any part of the configuration where a | |
6030 | lookup is permitted. | |
6031 | ||
6032 | ||
6033 | 9.2 Lookup types | |
6034 | ---------------- | |
6035 | ||
6036 | Two different types of data lookup are implemented: | |
6037 | ||
6038 | * The single-key type requires the specification of a file in which to look, | |
6039 | and a single key to search for. The key must be a non-empty string for the | |
6040 | lookup to succeed. The lookup type determines how the file is searched. | |
6041 | ||
6042 | * The query-style type accepts a generalized database query. No particular | |
6043 | key value is assumed by Exim for query-style lookups. You can use whichever | |
6044 | Exim variables you need to construct the database query. | |
6045 | ||
6046 | The code for each lookup type is in a separate source file that is included in | |
6047 | the binary of Exim only if the corresponding compile-time option is set. The | |
6048 | default settings in src/EDITME are: | |
6049 | ||
6050 | LOOKUP_DBM=yes | |
6051 | LOOKUP_LSEARCH=yes | |
6052 | ||
6053 | which means that only linear searching and DBM lookups are included by default. | |
6054 | For some types of lookup (e.g. SQL databases), you need to install appropriate | |
6055 | libraries and header files before building Exim. | |
6056 | ||
6057 | ||
6058 | 9.3 Single-key lookup types | |
6059 | --------------------------- | |
6060 | ||
6061 | The following single-key lookup types are implemented: | |
6062 | ||
6063 | * cdb: The given file is searched as a Constant DataBase file, using the key | |
6064 | string without a terminating binary zero. The cdb format is designed for | |
6065 | indexed files that are read frequently and never updated, except by total | |
6066 | re-creation. As such, it is particularly suitable for large files | |
6067 | containing aliases or other indexed data referenced by an MTA. Information | |
6068 | about cdb can be found in several places: | |
6069 | ||
6070 | http://www.pobox.com/~djb/cdb.html | |
6071 | ftp://ftp.corpit.ru/pub/tinycdb/ | |
6072 | http://packages.debian.org/stable/utils/freecdb.html | |
6073 | ||
6074 | A cdb distribution is not needed in order to build Exim with cdb support, | |
6075 | because the code for reading cdb files is included directly in Exim itself. | |
6076 | However, no means of building or testing cdb files is provided with Exim, | |
6077 | so you need to obtain a cdb distribution in order to do this. | |
6078 | ||
6079 | * dbm: Calls to DBM library functions are used to extract data from the given | |
6080 | DBM file by looking up the record with the given key. A terminating binary | |
6081 | zero is included in the key that is passed to the DBM library. See section | |
6082 | 4.4 for a discussion of DBM libraries. | |
6083 | ||
6084 | For all versions of Berkeley DB, Exim uses the DB_HASH style of database | |
6085 | when building DBM files using the exim_dbmbuild utility. However, when | |
6086 | using Berkeley DB versions 3 or 4, it opens existing databases for reading | |
6087 | with the DB_UNKNOWN option. This enables it to handle any of the types of | |
6088 | database that the library supports, and can be useful for accessing DBM | |
6089 | files created by other applications. (For earlier DB versions, DB_HASH is | |
6090 | always used.) | |
6091 | ||
6092 | * dbmjz: This is the same as dbm, except that the lookup key is interpreted | |
6093 | as an Exim list; the elements of the list are joined together with ASCII | |
6094 | NUL characters to form the lookup key. An example usage would be to | |
6095 | authenticate incoming SMTP calls using the passwords from Cyrus SASL's /etc | |
6096 | /sasldb2 file with the gsasl authenticator or Exim's own cram_md5 | |
6097 | authenticator. | |
6098 | ||
6099 | * dbmnz: This is the same as dbm, except that a terminating binary zero is | |
6100 | not included in the key that is passed to the DBM library. You may need | |
6101 | this if you want to look up data in files that are created by or shared | |
6102 | with some other application that does not use terminating zeros. For | |
6103 | example, you need to use dbmnz rather than dbm if you want to authenticate | |
6104 | incoming SMTP calls using the passwords from Courier's /etc/ | |
6105 | userdbshadow.dat file. Exim's utility program for creating DBM files ( | |
6106 | exim_dbmbuild) includes the zeros by default, but has an option to omit | |
2813c06e | 6107 | them (see section 53.9). |
420a0d19 CE |
6108 | |
6109 | * dsearch: The given file must be a directory; this is searched for an entry | |
6110 | whose name is the key by calling the lstat() function. The key may not | |
6111 | contain any forward slash characters. If lstat() succeeds, the result of | |
6112 | the lookup is the name of the entry, which may be a file, directory, | |
6113 | symbolic link, or any other kind of directory entry. An example of how this | |
2813c06e | 6114 | lookup can be used to support virtual domains is given in section 50.7. |
420a0d19 CE |
6115 | |
6116 | * iplsearch: The given file is a text file containing keys and data. A key is | |
6117 | terminated by a colon or white space or the end of the line. The keys in | |
6118 | the file must be IP addresses, or IP addresses with CIDR masks. Keys that | |
6119 | involve IPv6 addresses must be enclosed in quotes to prevent the first | |
6120 | internal colon being interpreted as a key terminator. For example: | |
6121 | ||
6122 | 1.2.3.4: data for 1.2.3.4 | |
6123 | 192.168.0.0/16: data for 192.168.0.0/16 | |
6124 | "abcd::cdab": data for abcd::cdab | |
6125 | "abcd:abcd::/32" data for abcd:abcd::/32 | |
6126 | ||
6127 | The key for an iplsearch lookup must be an IP address (without a mask). The | |
6128 | file is searched linearly, using the CIDR masks where present, until a | |
6129 | matching key is found. The first key that matches is used; there is no | |
6130 | attempt to find a "best" match. Apart from the way the keys are matched, | |
6131 | the processing for iplsearch is the same as for lsearch. | |
6132 | ||
6133 | Warning 1: Unlike most other single-key lookup types, a file of data for | |
6134 | iplsearch can not be turned into a DBM or cdb file, because those lookup | |
6135 | types support only literal keys. | |
6136 | ||
6137 | Warning 2: In a host list, you must always use net-iplsearch so that the | |
6138 | implicit key is the host's IP address rather than its name (see section | |
6139 | 10.12). | |
6140 | ||
6141 | * lsearch: The given file is a text file that is searched linearly for a line | |
6142 | beginning with the search key, terminated by a colon or white space or the | |
6143 | end of the line. The search is case-insensitive; that is, upper and lower | |
6144 | case letters are treated as the same. The first occurrence of the key that | |
6145 | is found in the file is used. | |
6146 | ||
6147 | White space between the key and the colon is permitted. The remainder of | |
6148 | the line, with leading and trailing white space removed, is the data. This | |
6149 | can be continued onto subsequent lines by starting them with any amount of | |
6150 | white space, but only a single space character is included in the data at | |
6151 | such a junction. If the data begins with a colon, the key must be | |
6152 | terminated by a colon, for example: | |
6153 | ||
6154 | baduser: :fail: | |
6155 | ||
6156 | Empty lines and lines beginning with # are ignored, even if they occur in | |
6157 | the middle of an item. This is the traditional textual format of alias | |
6158 | files. Note that the keys in an lsearch file are literal strings. There is | |
6159 | no wildcarding of any kind. | |
6160 | ||
6161 | In most lsearch files, keys are not required to contain colons or # | |
6162 | characters, or white space. However, if you need this feature, it is | |
6163 | available. If a key begins with a doublequote character, it is terminated | |
6164 | only by a matching quote (or end of line), and the normal escaping rules | |
2813c06e | 6165 | apply to its contents (see section 6.17). An optional colon is permitted |
420a0d19 CE |
6166 | after quoted keys (exactly as for unquoted keys). There is no special |
6167 | handling of quotes for the data part of an lsearch line. | |
6168 | ||
6169 | * nis: The given file is the name of a NIS map, and a NIS lookup is done with | |
6170 | the given key, without a terminating binary zero. There is a variant called | |
6171 | nis0 which does include the terminating binary zero in the key. This is | |
6172 | reportedly needed for Sun-style alias files. Exim does not recognize NIS | |
6173 | aliases; the full map names must be used. | |
6174 | ||
6175 | * wildlsearch or nwildlsearch: These search a file linearly, like lsearch, | |
6176 | but instead of being interpreted as a literal string, each key in the file | |
6177 | may be wildcarded. The difference between these two lookup types is that | |
6178 | for wildlsearch, each key in the file is string-expanded before being used, | |
6179 | whereas for nwildlsearch, no expansion takes place. | |
6180 | ||
6181 | Like lsearch, the testing is done case-insensitively. However, keys in the | |
6182 | file that are regular expressions can be made case-sensitive by the use of | |
6183 | "(-i)" within the pattern. The following forms of wildcard are recognized: | |
6184 | ||
6185 | 1. The string may begin with an asterisk to mean "ends with". For example: | |
6186 | ||
6187 | *.a.b.c data for anything.a.b.c | |
6188 | *fish data for anythingfish | |
6189 | ||
6190 | 2. The string may begin with a circumflex to indicate a regular | |
6191 | expression. For example, for wildlsearch: | |
6192 | ||
6193 | ^\N\d+\.a\.b\N data for <digits>.a.b | |
6194 | ||
6195 | Note the use of "\N" to disable expansion of the contents of the | |
6196 | regular expression. If you are using nwildlsearch, where the keys are | |
6197 | not string-expanded, the equivalent entry is: | |
6198 | ||
6199 | ^\d+\.a\.b data for <digits>.a.b | |
6200 | ||
6201 | The case-insensitive flag is set at the start of compiling the regular | |
6202 | expression, but it can be turned off by using "(-i)" at an appropriate | |
6203 | point. For example, to make the entire pattern case-sensitive: | |
6204 | ||
6205 | ^(?-i)\d+\.a\.b data for <digits>.a.b | |
6206 | ||
6207 | If the regular expression contains white space or colon characters, you | |
6208 | must either quote it (see lsearch above), or represent these characters | |
6209 | in other ways. For example, "\s" can be used for white space and "\x3A" | |
6210 | for a colon. This may be easier than quoting, because if you quote, you | |
6211 | have to escape all the backslashes inside the quotes. | |
6212 | ||
6213 | Note: It is not possible to capture substrings in a regular expression | |
6214 | match for later use, because the results of all lookups are cached. If | |
6215 | a lookup is repeated, the result is taken from the cache, and no actual | |
6216 | pattern matching takes place. The values of all the numeric variables | |
6217 | are unset after a (n)wildlsearch match. | |
6218 | ||
6219 | 3. Although I cannot see it being of much use, the general matching | |
6220 | function that is used to implement (n)wildlsearch means that the string | |
6221 | may begin with a lookup name terminated by a semicolon, and followed by | |
6222 | lookup data. For example: | |
6223 | ||
6224 | cdb;/some/file data for keys that match the file | |
6225 | ||
6226 | The data that is obtained from the nested lookup is discarded. | |
6227 | ||
6228 | Keys that do not match any of these patterns are interpreted literally. The | |
6229 | continuation rules for the data are the same as for lsearch, and keys may | |
6230 | be followed by optional colons. | |
6231 | ||
6232 | Warning: Unlike most other single-key lookup types, a file of data for (n) | |
6233 | wildlsearch can not be turned into a DBM or cdb file, because those lookup | |
6234 | types support only literal keys. | |
6235 | ||
6236 | ||
6237 | 9.4 Query-style lookup types | |
6238 | ---------------------------- | |
6239 | ||
6240 | The supported query-style lookup types are listed below. Further details about | |
6241 | many of them are given in later sections. | |
6242 | ||
6243 | * dnsdb: This does a DNS search for one or more records whose domain names | |
6244 | are given in the supplied query. The resulting data is the contents of the | |
6245 | records. See section 9.10. | |
6246 | ||
6247 | * ibase: This does a lookup in an InterBase database. | |
6248 | ||
6249 | * ldap: This does an LDAP lookup using a query in the form of a URL, and | |
6250 | returns attributes from a single entry. There is a variant called ldapm | |
6251 | that permits values from multiple entries to be returned. A third variant | |
6252 | called ldapdn returns the Distinguished Name of a single entry instead of | |
2813c06e | 6253 | any attribute values. See section 9.14. |
420a0d19 CE |
6254 | |
6255 | * mysql: The format of the query is an SQL statement that is passed to a | |
2813c06e | 6256 | MySQL database. See section 9.21. |
420a0d19 CE |
6257 | |
6258 | * nisplus: This does a NIS+ lookup using a query that can specify the name of | |
2813c06e | 6259 | the field to be returned. See section 9.20. |
420a0d19 CE |
6260 | |
6261 | * oracle: The format of the query is an SQL statement that is passed to an | |
2813c06e | 6262 | Oracle database. See section 9.21. |
420a0d19 CE |
6263 | |
6264 | * passwd is a query-style lookup with queries that are just user names. The | |
6265 | lookup calls getpwnam() to interrogate the system password data, and on | |
6266 | success, the result string is the same as you would get from an lsearch | |
6267 | lookup on a traditional /etc/passwd file, though with "*" for the password | |
6268 | value. For example: | |
6269 | ||
6270 | *:42:42:King Rat:/home/kr:/bin/bash | |
6271 | ||
6272 | * pgsql: The format of the query is an SQL statement that is passed to a | |
2813c06e CE |
6273 | PostgreSQL database. See section 9.21. |
6274 | ||
6275 | * redis: The format of the query is either a simple get or simple set, passed | |
6276 | to a Redis database. See section 9.21. | |
420a0d19 CE |
6277 | |
6278 | * sqlite: The format of the query is a file name followed by an SQL statement | |
2813c06e | 6279 | that is passed to an SQLite database. See section 9.26. |
420a0d19 CE |
6280 | |
6281 | * testdb: This is a lookup type that is used for testing Exim. It is not | |
6282 | likely to be useful in normal operation. | |
6283 | ||
6284 | * whoson: Whoson (http://whoson.sourceforge.net) is a protocol that allows a | |
6285 | server to check whether a particular (dynamically allocated) IP address is | |
6286 | currently allocated to a known (trusted) user and, optionally, to obtain | |
6287 | the identity of the said user. For SMTP servers, Whoson was popular at one | |
6288 | time for "POP before SMTP" authentication, but that approach has been | |
6289 | superseded by SMTP authentication. In Exim, Whoson can be used to implement | |
6290 | "POP before SMTP" checking using ACL statements such as | |
6291 | ||
6292 | require condition = \ | |
6293 | ${lookup whoson {$sender_host_address}{yes}{no}} | |
6294 | ||
6295 | The query consists of a single IP address. The value returned is the name | |
6296 | of the authenticated user, which is stored in the variable $value. However, | |
6297 | in this example, the data in $value is not used; the result of the lookup | |
6298 | is one of the fixed strings "yes" or "no". | |
6299 | ||
6300 | ||
6301 | 9.5 Temporary errors in lookups | |
6302 | ------------------------------- | |
6303 | ||
6304 | Lookup functions can return temporary error codes if the lookup cannot be | |
6305 | completed. For example, an SQL or LDAP database might be unavailable. For this | |
6306 | reason, it is not advisable to use a lookup that might do this for critical | |
6307 | options such as a list of local domains. | |
6308 | ||
6309 | When a lookup cannot be completed in a router or transport, delivery of the | |
6310 | message (to the relevant address) is deferred, as for any other temporary | |
6311 | error. In other circumstances Exim may assume the lookup has failed, or may | |
6312 | give up altogether. | |
6313 | ||
6314 | ||
6315 | 9.6 Default values in single-key lookups | |
6316 | ---------------------------------------- | |
6317 | ||
6318 | In this context, a "default value" is a value specified by the administrator | |
6319 | that is to be used if a lookup fails. | |
6320 | ||
6321 | Note: This section applies only to single-key lookups. For query-style lookups, | |
6322 | the facilities of the query language must be used. An attempt to specify a | |
6323 | default for a query-style lookup provokes an error. | |
6324 | ||
6325 | If "*" is added to a single-key lookup type (for example, lsearch*) and the | |
6326 | initial lookup fails, the key "*" is looked up in the file to provide a default | |
6327 | value. See also the section on partial matching below. | |
6328 | ||
6329 | Alternatively, if "*@" is added to a single-key lookup type (for example dbm*@) | |
6330 | then, if the initial lookup fails and the key contains an @ character, a second | |
6331 | lookup is done with everything before the last @ replaced by *. This makes it | |
6332 | possible to provide per-domain defaults in alias files that include the domains | |
6333 | in the keys. If the second lookup fails (or doesn't take place because there is | |
6334 | no @ in the key), "*" is looked up. For example, a redirect router might | |
6335 | contain: | |
6336 | ||
6337 | data = ${lookup{$local_part@$domain}lsearch*@{/etc/mix-aliases}} | |
6338 | ||
6339 | Suppose the address that is being processed is jane@eyre.example. Exim looks up | |
6340 | these keys, in this order: | |
6341 | ||
6342 | jane@eyre.example | |
6343 | *@eyre.example | |
6344 | * | |
6345 | ||
6346 | The data is taken from whichever key it finds first. Note: In an lsearch file, | |
6347 | this does not mean the first of these keys in the file. A complete scan is done | |
6348 | for each key, and only if it is not found at all does Exim move on to try the | |
6349 | next key. | |
6350 | ||
6351 | ||
6352 | 9.7 Partial matching in single-key lookups | |
6353 | ------------------------------------------ | |
6354 | ||
6355 | The normal operation of a single-key lookup is to search the file for an exact | |
6356 | match with the given key. However, in a number of situations where domains are | |
6357 | being looked up, it is useful to be able to do partial matching. In this case, | |
6358 | information in the file that has a key starting with "*." is matched by any | |
6359 | domain that ends with the components that follow the full stop. For example, if | |
6360 | a key in a DBM file is | |
6361 | ||
6362 | *.dates.fict.example | |
6363 | ||
6364 | then when partial matching is enabled this is matched by (amongst others) | |
6365 | 2001.dates.fict.example and 1984.dates.fict.example. It is also matched by | |
6366 | dates.fict.example, if that does not appear as a separate key in the file. | |
6367 | ||
6368 | Note: Partial matching is not available for query-style lookups. It is also not | |
6369 | available for any lookup items in address lists (see section 10.19). | |
6370 | ||
6371 | Partial matching is implemented by doing a series of separate lookups using | |
6372 | keys constructed by modifying the original subject key. This means that it can | |
6373 | be used with any of the single-key lookup types, provided that partial matching | |
6374 | keys beginning with a special prefix (default "*.") are included in the data | |
6375 | file. Keys in the file that do not begin with the prefix are matched only by | |
6376 | unmodified subject keys when partial matching is in use. | |
6377 | ||
6378 | Partial matching is requested by adding the string "partial-" to the front of | |
6379 | the name of a single-key lookup type, for example, partial-dbm. When this is | |
6380 | done, the subject key is first looked up unmodified; if that fails, "*." is | |
6381 | added at the start of the subject key, and it is looked up again. If that | |
6382 | fails, further lookups are tried with dot-separated components removed from the | |
6383 | start of the subject key, one-by-one, and "*." added on the front of what | |
6384 | remains. | |
6385 | ||
6386 | A minimum number of two non-* components are required. This can be adjusted by | |
6387 | including a number before the hyphen in the search type. For example, | |
6388 | partial3-lsearch specifies a minimum of three non-* components in the modified | |
6389 | keys. Omitting the number is equivalent to "partial2-". If the subject key is | |
6390 | 2250.dates.fict.example then the following keys are looked up when the minimum | |
6391 | number of non-* components is two: | |
6392 | ||
6393 | 2250.dates.fict.example | |
6394 | *.2250.dates.fict.example | |
6395 | *.dates.fict.example | |
6396 | *.fict.example | |
6397 | ||
6398 | As soon as one key in the sequence is successfully looked up, the lookup | |
6399 | finishes. | |
6400 | ||
6401 | The use of "*." as the partial matching prefix is a default that can be | |
6402 | changed. The motivation for this feature is to allow Exim to operate with file | |
6403 | formats that are used by other MTAs. A different prefix can be supplied in | |
6404 | parentheses instead of the hyphen after "partial". For example: | |
6405 | ||
6406 | domains = partial(.)lsearch;/some/file | |
6407 | ||
6408 | In this example, if the domain is a.b.c, the sequence of lookups is "a.b.c", | |
6409 | ".a.b.c", and ".b.c" (the default minimum of 2 non-wild components is | |
6410 | unchanged). The prefix may consist of any punctuation characters other than a | |
6411 | closing parenthesis. It may be empty, for example: | |
6412 | ||
6413 | domains = partial1()cdb;/some/file | |
6414 | ||
6415 | For this example, if the domain is a.b.c, the sequence of lookups is "a.b.c", | |
6416 | "b.c", and "c". | |
6417 | ||
6418 | If "partial0" is specified, what happens at the end (when the lookup with just | |
6419 | one non-wild component has failed, and the original key is shortened right down | |
6420 | to the null string) depends on the prefix: | |
6421 | ||
6422 | * If the prefix has zero length, the whole lookup fails. | |
6423 | ||
6424 | * If the prefix has length 1, a lookup for just the prefix is done. For | |
6425 | example, the final lookup for "partial0(.)" is for "." alone. | |
6426 | ||
6427 | * Otherwise, if the prefix ends in a dot, the dot is removed, and the | |
6428 | remainder is looked up. With the default prefix, therefore, the final | |
6429 | lookup is for "*" on its own. | |
6430 | ||
6431 | * Otherwise, the whole prefix is looked up. | |
6432 | ||
6433 | If the search type ends in "*" or "*@" (see section 9.6 above), the search for | |
6434 | an ultimate default that this implies happens after all partial lookups have | |
6435 | failed. If "partial0" is specified, adding "*" to the search type has no effect | |
6436 | with the default prefix, because the "*" key is already included in the | |
6437 | sequence of partial lookups. However, there might be a use for lookup types | |
6438 | such as "partial0(.)lsearch*". | |
6439 | ||
6440 | The use of "*" in lookup partial matching differs from its use as a wildcard in | |
6441 | domain lists and the like. Partial matching works only in terms of | |
6442 | dot-separated components; a key such as "*fict.example" in a database file is | |
6443 | useless, because the asterisk in a partial matching subject key is always | |
6444 | followed by a dot. | |
6445 | ||
6446 | ||
6447 | 9.8 Lookup caching | |
6448 | ------------------ | |
6449 | ||
6450 | Exim caches all lookup results in order to avoid needless repetition of | |
6451 | lookups. However, because (apart from the daemon) Exim operates as a collection | |
6452 | of independent, short-lived processes, this caching applies only within a | |
6453 | single Exim process. There is no inter-process lookup caching facility. | |
6454 | ||
6455 | For single-key lookups, Exim keeps the relevant files open in case there is | |
6456 | another lookup that needs them. In some types of configuration this can lead to | |
6457 | many files being kept open for messages with many recipients. To avoid hitting | |
6458 | the operating system limit on the number of simultaneously open files, Exim | |
6459 | closes the least recently used file when it needs to open more files than its | |
6460 | own internal limit, which can be changed via the lookup_open_max option. | |
6461 | ||
6462 | The single-key lookup files are closed and the lookup caches are flushed at | |
6463 | strategic points during delivery - for example, after all routing is complete. | |
6464 | ||
6465 | ||
6466 | 9.9 Quoting lookup data | |
6467 | ----------------------- | |
6468 | ||
6469 | When data from an incoming message is included in a query-style lookup, there | |
6470 | is the possibility of special characters in the data messing up the syntax of | |
6471 | the query. For example, a NIS+ query that contains | |
6472 | ||
6473 | [name=$local_part] | |
6474 | ||
6475 | will be broken if the local part happens to contain a closing square bracket. | |
6476 | For NIS+, data can be enclosed in double quotes like this: | |
6477 | ||
6478 | [name="$local_part"] | |
6479 | ||
6480 | but this still leaves the problem of a double quote in the data. The rule for | |
6481 | NIS+ is that double quotes must be doubled. Other lookup types have different | |
6482 | rules, and to cope with the differing requirements, an expansion operator of | |
6483 | the following form is provided: | |
6484 | ||
6485 | ${quote_<lookup-type>:<string>} | |
6486 | ||
6487 | For example, the safest way to write the NIS+ query is | |
6488 | ||
6489 | [name="${quote_nisplus:$local_part}"] | |
6490 | ||
6491 | See chapter 11 for full coverage of string expansions. The quote operator can | |
6492 | be used for all lookup types, but has no effect for single-key lookups, since | |
6493 | no quoting is ever needed in their key strings. | |
6494 | ||
6495 | ||
6496 | 9.10 More about dnsdb | |
6497 | --------------------- | |
6498 | ||
6499 | The dnsdb lookup type uses the DNS as its database. A simple query consists of | |
6500 | a record type and a domain name, separated by an equals sign. For example, an | |
6501 | expansion string could contain: | |
6502 | ||
6503 | ${lookup dnsdb{mx=a.b.example}{$value}fail} | |
6504 | ||
6505 | If the lookup succeeds, the result is placed in $value, which in this case is | |
6506 | used on its own as the result. If the lookup does not succeed, the "fail" | |
6507 | keyword causes a forced expansion failure - see section 11.4 for an explanation | |
6508 | of what this means. | |
6509 | ||
2813c06e CE |
6510 | The supported DNS record types are A, CNAME, MX, NS, PTR, SOA, SPF, SRV, TLSA |
6511 | and TXT, and, when Exim is compiled with IPv6 support, AAAA. If no type is | |
6512 | given, TXT is assumed. | |
420a0d19 | 6513 | |
2813c06e | 6514 | For any record type, if multiple records are found, the data is returned as a |
420a0d19 CE |
6515 | concatenation, with newline as the default separator. The order, of course, |
6516 | depends on the DNS resolver. You can specify a different separator character | |
6517 | between multiple records by putting a right angle-bracket followed immediately | |
6518 | by the new separator at the start of the query. For example: | |
6519 | ||
6520 | ${lookup dnsdb{>: a=host1.example}} | |
6521 | ||
6522 | It is permitted to specify a space as the separator character. Further white | |
2813c06e CE |
6523 | space is ignored. For lookup types that return multiple fields per record, an |
6524 | alternate field separator can be specified using a comma after the main | |
6525 | separator character, followed immediately by the field separator. | |
6526 | ||
6527 | When the type is PTR, the data can be an IP address, written as normal; | |
6528 | inversion and the addition of in-addr.arpa or ip6.arpa happens automatically. | |
6529 | For example: | |
6530 | ||
6531 | ${lookup dnsdb{ptr=192.168.4.5}{$value}fail} | |
6532 | ||
6533 | If the data for a PTR record is not a syntactically valid IP address, it is not | |
6534 | altered and nothing is added. | |
6535 | ||
6536 | For an MX lookup, both the preference value and the host name are returned for | |
6537 | each record, separated by a space. For an SRV lookup, the priority, weight, | |
6538 | port, and host name are returned for each record, separated by spaces. The | |
6539 | field separator can be modified as above. | |
420a0d19 CE |
6540 | |
6541 | For TXT records with multiple items of data, only the first item is returned, | |
2813c06e CE |
6542 | unless a field separator is specified. To concatenate items without a |
6543 | separator, use a semicolon instead. For SPF records the default behaviour is to | |
6544 | concatenate multiple items without using a separator. | |
420a0d19 CE |
6545 | |
6546 | ${lookup dnsdb{>\n,: txt=a.b.example}} | |
6547 | ${lookup dnsdb{>\n; txt=a.b.example}} | |
6548 | ${lookup dnsdb{spf=example.org}} | |
6549 | ||
6550 | It is permitted to specify a space as the separator character. Further white | |
6551 | space is ignored. | |
6552 | ||
2813c06e CE |
6553 | For an SOA lookup, while no result is obtained the lookup is redone with |
6554 | successively more leading components dropped from the given domain. Only the | |
6555 | primary-nameserver field is returned unless a field separator is specified. | |
6556 | ||
6557 | ${lookup dnsdb{>:,; soa=a.b.example.com}} | |
6558 | ||
6559 | ||
6560 | 9.11 Dnsdb lookup modifiers | |
6561 | --------------------------- | |
6562 | ||
6563 | Modifiers for dnsdb lookups are given by optional keywords, each followed by a | |
6564 | comma, that may appear before the record type. | |
6565 | ||
6566 | The dnsdb lookup fails only if all the DNS lookups fail. If there is a | |
6567 | temporary DNS error for any of them, the behaviour is controlled by a | |
6568 | defer-option modifier. The possible keywords are "defer_strict", "defer_never", | |
6569 | and "defer_lax". With "strict" behaviour, any temporary DNS error causes the | |
6570 | whole lookup to defer. With "never" behaviour, a temporary DNS error is | |
6571 | ignored, and the behaviour is as if the DNS lookup failed to find anything. | |
6572 | With "lax" behaviour, all the queries are attempted, but a temporary DNS error | |
6573 | causes the whole lookup to defer only if none of the other lookups succeed. The | |
6574 | default is "lax", so the following lookups are equivalent: | |
6575 | ||
6576 | ${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}} | |
6577 | ${lookup dnsdb{a=one.host.com:two.host.com}} | |
6578 | ||
6579 | Thus, in the default case, as long as at least one of the DNS lookups yields | |
6580 | some data, the lookup succeeds. | |
6581 | ||
6582 | Use of DNSSEC is controlled by a dnssec modifier. The possible keywords are | |
6583 | "dnssec_strict", "dnssec_lax", and "dnssec_never". With "strict" or "lax" | |
6584 | DNSSEC information is requested with the lookup. With "strict" a response from | |
6585 | the DNS resolver that is not labelled as authenticated data is treated as | |
6586 | equivalent to a temporary DNS error. The default is "never". | |
6587 | ||
6588 | See also the $lookup_dnssec_authenticated variable. | |
6589 | ||
6590 | Timeout for the dnsdb lookup can be controlled by a retrans modifier. The form | |
6591 | is "retrans_VAL" where VAL is an Exim time specification (e.g. "5s"). The | |
6592 | default value is set by the main configuration option dns_retrans. | |
6593 | ||
6594 | Retries for the dnsdb lookup can be controlled by a retry modifier. The form if | |
6595 | "retry_VAL" where VAL is an integer. The default count is set by the main | |
6596 | configuration option dns_retry. | |
6597 | ||
6598 | Dnsdb lookup results are cached within a single process (and its children). The | |
6599 | cache entry lifetime is limited to the smallest time-to-live (TTL) value of the | |
6600 | set of returned DNS records. | |
420a0d19 | 6601 | |
2813c06e CE |
6602 | |
6603 | 9.12 Pseudo dnsdb record types | |
420a0d19 CE |
6604 | ------------------------------ |
6605 | ||
6606 | By default, both the preference value and the host name are returned for each | |
6607 | MX record, separated by a space. If you want only host names, you can use the | |
6608 | pseudo-type MXH: | |
6609 | ||
6610 | ${lookup dnsdb{mxh=a.b.example}} | |
6611 | ||
6612 | In this case, the preference values are omitted, and just the host names are | |
6613 | returned. | |
6614 | ||
6615 | Another pseudo-type is ZNS (for "zone NS"). It performs a lookup for NS records | |
6616 | on the given domain, but if none are found, it removes the first component of | |
6617 | the domain name, and tries again. This process continues until NS records are | |
6618 | found or there are no more components left (or there is a DNS error). In other | |
6619 | words, it may return the name servers for a top-level domain, but it never | |
6620 | returns the root name servers. If there are no NS records for the top-level | |
6621 | domain, the lookup fails. Consider these examples: | |
6622 | ||
6623 | ${lookup dnsdb{zns=xxx.quercite.com}} | |
6624 | ${lookup dnsdb{zns=xxx.edu}} | |
6625 | ||
6626 | Assuming that in each case there are no NS records for the full domain name, | |
6627 | the first returns the name servers for quercite.com, and the second returns the | |
6628 | name servers for edu. | |
6629 | ||
6630 | You should be careful about how you use this lookup because, unless the | |
6631 | top-level domain does not exist, the lookup always returns some host names. The | |
6632 | sort of use to which this might be put is for seeing if the name servers for a | |
6633 | given domain are on a blacklist. You can probably assume that the name servers | |
6634 | for the high-level domains such as com or co.uk are not going to be on such a | |
6635 | list. | |
6636 | ||
6637 | A third pseudo-type is CSA (Client SMTP Authorization). This looks up SRV | |
2813c06e | 6638 | records according to the CSA rules, which are described in section 43.50. |
420a0d19 CE |
6639 | Although dnsdb supports SRV lookups directly, this is not sufficient because of |
6640 | the extra parent domain search behaviour of CSA. The result of a successful | |
6641 | lookup such as: | |
6642 | ||
6643 | ${lookup dnsdb {csa=$sender_helo_name}} | |
6644 | ||
6645 | has two space-separated fields: an authorization code and a target host name. | |
6646 | The authorization code can be "Y" for yes, "N" for no, "X" for explicit | |
6647 | authorization required but absent, or "?" for unknown. | |
6648 | ||
2813c06e CE |
6649 | The pseudo-type A+ performs an AAAA and then an A lookup. All results are |
6650 | returned; defer processing (see below) is handled separately for each lookup. | |
6651 | Example: | |
420a0d19 CE |
6652 | |
6653 | ${lookup dnsdb {>; a+=$sender_helo_name}} | |
6654 | ||
6655 | ||
2813c06e | 6656 | 9.13 Multiple dnsdb lookups |
420a0d19 CE |
6657 | --------------------------- |
6658 | ||
6659 | In the previous sections, dnsdb lookups for a single domain are described. | |
6660 | However, you can specify a list of domains or IP addresses in a single dnsdb | |
6661 | lookup. The list is specified in the normal Exim way, with colon as the default | |
6662 | separator, but with the ability to change this. For example: | |
6663 | ||
6664 | ${lookup dnsdb{one.domain.com:two.domain.com}} | |
6665 | ${lookup dnsdb{a=one.host.com:two.host.com}} | |
6666 | ${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}} | |
6667 | ||
6668 | In order to retain backwards compatibility, there is one special case: if the | |
6669 | lookup type is PTR and no change of separator is specified, Exim looks to see | |
6670 | if the rest of the string is precisely one IPv6 address. In this case, it does | |
6671 | not treat it as a list. | |
6672 | ||
6673 | The data from each lookup is concatenated, with newline separators by default, | |
6674 | in the same way that multiple DNS records for a single item are handled. A | |
6675 | different separator can be specified, as described above. | |
6676 | ||
420a0d19 | 6677 | |
2813c06e | 6678 | 9.14 More about LDAP |
420a0d19 CE |
6679 | -------------------- |
6680 | ||
6681 | The original LDAP implementation came from the University of Michigan; this has | |
6682 | become "Open LDAP", and there are now two different releases. Another | |
6683 | implementation comes from Netscape, and Solaris 7 and subsequent releases | |
6684 | contain inbuilt LDAP support. Unfortunately, though these are all compatible at | |
6685 | the lookup function level, their error handling is different. For this reason | |
6686 | it is necessary to set a compile-time variable when building Exim with LDAP, to | |
6687 | indicate which LDAP library is in use. One of the following should appear in | |
6688 | your Local/Makefile: | |
6689 | ||
6690 | LDAP_LIB_TYPE=UMICHIGAN | |
6691 | LDAP_LIB_TYPE=OPENLDAP1 | |
6692 | LDAP_LIB_TYPE=OPENLDAP2 | |
6693 | LDAP_LIB_TYPE=NETSCAPE | |
6694 | LDAP_LIB_TYPE=SOLARIS | |
6695 | ||
6696 | If LDAP_LIB_TYPE is not set, Exim assumes "OPENLDAP1", which has the same | |
6697 | interface as the University of Michigan version. | |
6698 | ||
6699 | There are three LDAP lookup types in Exim. These behave slightly differently in | |
6700 | the way they handle the results of a query: | |
6701 | ||
6702 | * ldap requires the result to contain just one entry; if there are more, it | |
6703 | gives an error. | |
6704 | ||
6705 | * ldapdn also requires the result to contain just one entry, but it is the | |
6706 | Distinguished Name that is returned rather than any attribute values. | |
6707 | ||
6708 | * ldapm permits the result to contain more than one entry; the attributes | |
6709 | from all of them are returned. | |
6710 | ||
6711 | For ldap and ldapm, if a query finds only entries with no attributes, Exim | |
6712 | behaves as if the entry did not exist, and the lookup fails. The format of the | |
6713 | data returned by a successful lookup is described in the next section. First we | |
6714 | explain how LDAP queries are coded. | |
6715 | ||
6716 | ||
2813c06e | 6717 | 9.15 Format of LDAP queries |
420a0d19 CE |
6718 | --------------------------- |
6719 | ||
6720 | An LDAP query takes the form of a URL as defined in RFC 2255. For example, in | |
6721 | the configuration of a redirect router one might have this setting: | |
6722 | ||
6723 | data = ${lookup ldap \ | |
6724 | {ldap:///cn=$local_part,o=University%20of%20Cambridge,\ | |
6725 | c=UK?mailbox?base?}} | |
6726 | ||
6727 | The URL may begin with "ldap" or "ldaps" if your LDAP library supports secure | |
6728 | (encrypted) LDAP connections. The second of these ensures that an encrypted TLS | |
6729 | connection is used. | |
6730 | ||
6731 | With sufficiently modern LDAP libraries, Exim supports forcing TLS over regular | |
6732 | LDAP connections, rather than the SSL-on-connect "ldaps". See the | |
6733 | ldap_start_tls option. | |
6734 | ||
6735 | Starting with Exim 4.83, the initialization of LDAP with TLS is more tightly | |
6736 | controlled. Every part of the TLS configuration can be configured by settings | |
6737 | in exim.conf. Depending on the version of the client libraries installed on | |
6738 | your system, some of the initialization may have required setting options in / | |
6739 | etc/ldap.conf or ~/.ldaprc to get TLS working with self-signed certificates. | |
6740 | This revealed a nuance where the current UID that exim was running as could | |
6741 | affect which config files it read. With Exim 4.83, these methods become | |
6742 | optional, only taking effect if not specifically set in exim.conf. | |
6743 | ||
6744 | ||
2813c06e | 6745 | 9.16 LDAP quoting |
420a0d19 CE |
6746 | ----------------- |
6747 | ||
6748 | Two levels of quoting are required in LDAP queries, the first for LDAP itself | |
6749 | and the second because the LDAP query is represented as a URL. Furthermore, | |
6750 | within an LDAP query, two different kinds of quoting are required. For this | |
6751 | reason, there are two different LDAP-specific quoting operators. | |
6752 | ||
6753 | The quote_ldap operator is designed for use on strings that are part of filter | |
6754 | specifications. Conceptually, it first does the following conversions on the | |
6755 | string: | |
6756 | ||
6757 | * => \2A | |
6758 | ( => \28 | |
6759 | ) => \29 | |
6760 | \ => \5C | |
6761 | ||
6762 | in accordance with RFC 2254. The resulting string is then quoted according to | |
6763 | the rules for URLs, that is, all non-alphanumeric characters except | |
6764 | ||
6765 | ! $ ' - . _ ( ) * + | |
6766 | ||
6767 | are converted to their hex values, preceded by a percent sign. For example: | |
6768 | ||
6769 | ${quote_ldap: a(bc)*, a<yz>; } | |
6770 | ||
6771 | yields | |
6772 | ||
6773 | %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20 | |
6774 | ||
6775 | Removing the URL quoting, this is (with a leading and a trailing space): | |
6776 | ||
6777 | a\28bc\29\2A, a<yz>; | |
6778 | ||
6779 | The quote_ldap_dn operator is designed for use on strings that are part of base | |
6780 | DN specifications in queries. Conceptually, it first converts the string by | |
6781 | inserting a backslash in front of any of the following characters: | |
6782 | ||
6783 | , + " \ < > ; | |
6784 | ||
6785 | It also inserts a backslash before any leading spaces or # characters, and | |
6786 | before any trailing spaces. (These rules are in RFC 2253.) The resulting string | |
6787 | is then quoted according to the rules for URLs. For example: | |
6788 | ||
6789 | ${quote_ldap_dn: a(bc)*, a<yz>; } | |
6790 | ||
6791 | yields | |
6792 | ||
6793 | %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20 | |
6794 | ||
6795 | Removing the URL quoting, this is (with a trailing space): | |
6796 | ||
6797 | \ a(bc)*\, a\<yz\>\;\ | |
6798 | ||
6799 | There are some further comments about quoting in the section on LDAP | |
6800 | authentication below. | |
6801 | ||
6802 | ||
2813c06e | 6803 | 9.17 LDAP connections |
420a0d19 CE |
6804 | --------------------- |
6805 | ||
6806 | The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP | |
6807 | is in use, via a Unix domain socket. The example given above does not specify | |
6808 | an LDAP server. A server that is reached by TCP/IP can be specified in a query | |
6809 | by starting it with | |
6810 | ||
6811 | ldap://<hostname>:<port>/... | |
6812 | ||
6813 | If the port (and preceding colon) are omitted, the standard LDAP port (389) is | |
6814 | used. When no server is specified in a query, a list of default servers is | |
6815 | taken from the ldap_default_servers configuration option. This supplies a | |
6816 | colon-separated list of servers which are tried in turn until one successfully | |
6817 | handles a query, or there is a serious error. Successful handling either | |
6818 | returns the requested data, or indicates that it does not exist. Serious errors | |
6819 | are syntactical, or multiple values when only a single value is expected. | |
6820 | Errors which cause the next server to be tried are connection failures, bind | |
6821 | failures, and timeouts. | |
6822 | ||
6823 | For each server name in the list, a port number can be given. The standard way | |
6824 | of specifying a host and port is to use a colon separator (RFC 1738). Because | |
6825 | ldap_default_servers is a colon-separated list, such colons have to be doubled. | |
6826 | For example | |
6827 | ||
6828 | ldap_default_servers = ldap1.example.com::145:ldap2.example.com | |
6829 | ||
6830 | If ldap_default_servers is unset, a URL with no server name is passed to the | |
6831 | LDAP library with no server name, and the library's default (normally the local | |
6832 | host) is used. | |
6833 | ||
6834 | If you are using the OpenLDAP library, you can connect to an LDAP server using | |
6835 | a Unix domain socket instead of a TCP/IP connection. This is specified by using | |
6836 | "ldapi" instead of "ldap" in LDAP queries. What follows here applies only to | |
6837 | OpenLDAP. If Exim is compiled with a different LDAP library, this feature is | |
6838 | not available. | |
6839 | ||
6840 | For this type of connection, instead of a host name for the server, a pathname | |
6841 | for the socket is required, and the port number is not relevant. The pathname | |
6842 | can be specified either as an item in ldap_default_servers, or inline in the | |
6843 | query. In the former case, you can have settings such as | |
6844 | ||
6845 | ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain | |
6846 | ||
6847 | When the pathname is given in the query, you have to escape the slashes as | |
6848 | "%2F" to fit in with the LDAP URL syntax. For example: | |
6849 | ||
6850 | ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=... | |
6851 | ||
6852 | When Exim processes an LDAP lookup and finds that the "hostname" is really a | |
6853 | pathname, it uses the Unix domain socket code, even if the query actually | |
6854 | specifies "ldap" or "ldaps". In particular, no encryption is used for a socket | |
6855 | connection. This behaviour means that you can use a setting of | |
6856 | ldap_default_servers such as in the example above with traditional "ldap" or | |
6857 | "ldaps" queries, and it will work. First, Exim tries a connection via the Unix | |
6858 | domain socket; if that fails, it tries a TCP/IP connection to the backup host. | |
6859 | ||
6860 | If an explicit "ldapi" type is given in a query when a host name is specified, | |
6861 | an error is diagnosed. However, if there are more items in ldap_default_servers | |
6862 | , they are tried. In other words: | |
6863 | ||
6864 | * Using a pathname with "ldap" or "ldaps" forces the use of the Unix domain | |
6865 | interface. | |
6866 | ||
6867 | * Using "ldapi" with a host name causes an error. | |
6868 | ||
6869 | Using "ldapi" with no host or path in the query, and no setting of | |
6870 | ldap_default_servers, does whatever the library does by default. | |
6871 | ||
6872 | ||
2813c06e | 6873 | 9.18 LDAP authentication and control information |
420a0d19 CE |
6874 | ------------------------------------------------ |
6875 | ||
6876 | The LDAP URL syntax provides no way of passing authentication and other control | |
6877 | information to the server. To make this possible, the URL in an LDAP query may | |
6878 | be preceded by any number of <name>=<value> settings, separated by spaces. If a | |
6879 | value contains spaces it must be enclosed in double quotes, and when double | |
6880 | quotes are used, backslash is interpreted in the usual way inside them. The | |
6881 | following names are recognized: | |
6882 | ||
6883 | DEREFERENCE set the dereferencing parameter | |
6884 | NETTIME set a timeout for a network operation | |
6885 | USER set the DN, for authenticating the LDAP bind | |
6886 | PASS set the password, likewise | |
6887 | REFERRALS set the referrals parameter | |
6888 | SERVERS set alternate server list for this query only | |
6889 | SIZE set the limit for the number of entries returned | |
6890 | TIME set the maximum waiting time for a query | |
6891 | ||
6892 | The value of the DEREFERENCE parameter must be one of the words "never", | |
6893 | "searching", "finding", or "always". The value of the REFERRALS parameter must | |
6894 | be "follow" (the default) or "nofollow". The latter stops the LDAP library from | |
6895 | trying to follow referrals issued by the LDAP server. | |
6896 | ||
6897 | The name CONNECT is an obsolete name for NETTIME, retained for backwards | |
6898 | compatibility. This timeout (specified as a number of seconds) is enforced from | |
6899 | the client end for operations that can be carried out over a network. | |
6900 | Specifically, it applies to network connections and calls to the ldap_result() | |
6901 | function. If the value is greater than zero, it is used if | |
6902 | LDAP_OPT_NETWORK_TIMEOUT is defined in the LDAP headers (OpenLDAP), or if | |
6903 | LDAP_X_OPT_CONNECT_TIMEOUT is defined in the LDAP headers (Netscape SDK 4.1). A | |
6904 | value of zero forces an explicit setting of "no timeout" for Netscape SDK; for | |
6905 | OpenLDAP no action is taken. | |
6906 | ||
6907 | The TIME parameter (also a number of seconds) is passed to the server to set a | |
6908 | server-side limit on the time taken to complete a search. | |
6909 | ||
6910 | The SERVERS parameter allows you to specify an alternate list of ldap servers | |
2813c06e CE |
6911 | to use for an individual lookup. The global ldap_default_servers option |
6912 | provides a default list of ldap servers, and a single lookup can specify a | |
6913 | single ldap server to use. But when you need to do a lookup with a list of | |
6914 | servers that is different than the default list (maybe different order, maybe a | |
6915 | completely different set of servers), the SERVERS parameter allows you to | |
6916 | specify this alternate list (colon-separated). | |
420a0d19 CE |
6917 | |
6918 | Here is an example of an LDAP query in an Exim lookup that uses some of these | |
6919 | values. This is a single line, folded to fit on the page: | |
6920 | ||
6921 | ${lookup ldap | |
6922 | {user="cn=manager,o=University of Cambridge,c=UK" pass=secret | |
6923 | ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)} | |
6924 | {$value}fail} | |
6925 | ||
6926 | The encoding of spaces as "%20" is a URL thing which should not be done for any | |
6927 | of the auxiliary data. Exim configuration settings that include lookups which | |
6928 | contain password information should be preceded by "hide" to prevent non-admin | |
6929 | users from using the -bP option to see their values. | |
6930 | ||
6931 | The auxiliary data items may be given in any order. The default is no | |
6932 | connection timeout (the system timeout is used), no user or password, no limit | |
6933 | on the number of entries returned, and no time limit on queries. | |
6934 | ||
6935 | When a DN is quoted in the USER= setting for LDAP authentication, Exim removes | |
6936 | any URL quoting that it may contain before passing it LDAP. Apparently some | |
6937 | libraries do this for themselves, but some do not. Removing the URL quoting has | |
6938 | two advantages: | |
6939 | ||
6940 | * It makes it possible to use the same quote_ldap_dn expansion for USER= DNs | |
6941 | as with DNs inside actual queries. | |
6942 | ||
6943 | * It permits spaces inside USER= DNs. | |
6944 | ||
6945 | For example, a setting such as | |
6946 | ||
6947 | USER=cn=${quote_ldap_dn:$1} | |
6948 | ||
6949 | should work even if $1 contains spaces. | |
6950 | ||
6951 | Expanded data for the PASS= value should be quoted using the quote expansion | |
6952 | operator, rather than the LDAP quote operators. The only reason this field | |
6953 | needs quoting is to ensure that it conforms to the Exim syntax, which does not | |
6954 | allow unquoted spaces. For example: | |
6955 | ||
6956 | PASS=${quote:$3} | |
6957 | ||
6958 | The LDAP authentication mechanism can be used to check passwords as part of | |
6959 | SMTP authentication. See the ldapauth expansion string condition in chapter 11. | |
6960 | ||
6961 | ||
2813c06e | 6962 | 9.19 Format of data returned by LDAP |
420a0d19 CE |
6963 | ------------------------------------ |
6964 | ||
6965 | The ldapdn lookup type returns the Distinguished Name from a single entry as a | |
6966 | sequence of values, for example | |
6967 | ||
2813c06e | 6968 | cn=manager,o=University of Cambridge,c=UK |
420a0d19 CE |
6969 | |
6970 | The ldap lookup type generates an error if more than one entry matches the | |
6971 | search filter, whereas ldapm permits this case, and inserts a newline in the | |
6972 | result between the data from different entries. It is possible for multiple | |
6973 | values to be returned for both ldap and ldapm, but in the former case you know | |
6974 | that whatever values are returned all came from a single entry in the | |
6975 | directory. | |
6976 | ||
6977 | In the common case where you specify a single attribute in your LDAP query, the | |
6978 | result is not quoted, and does not contain the attribute name. If the attribute | |
2813c06e CE |
6979 | has multiple values, they are separated by commas. Any comma that is part of an |
6980 | attribute's value is doubled. | |
420a0d19 CE |
6981 | |
6982 | If you specify multiple attributes, the result contains space-separated, quoted | |
6983 | strings, each preceded by the attribute name and an equals sign. Within the | |
6984 | quotes, the quote character, backslash, and newline are escaped with | |
6985 | backslashes, and commas are used to separate multiple values for the attribute. | |
2813c06e CE |
6986 | Any commas in attribute values are doubled (permitting treatment of the values |
6987 | as a comma-separated list). Apart from the escaping, the string within quotes | |
6988 | takes the same form as the output when a single attribute is requested. | |
6989 | Specifying no attributes is the same as specifying all of an entry's | |
6990 | attributes. | |
420a0d19 CE |
6991 | |
6992 | Here are some examples of the output format. The first line of each pair is an | |
6993 | LDAP query, and the second is the data that is returned. The attribute called | |
2813c06e CE |
6994 | attr1 has two values, one of them with an embedded comma, whereas attr2 has |
6995 | only one value. Both attributes are derived from attr (they have SUP attr in | |
6996 | their schema definitions). | |
420a0d19 CE |
6997 | |
6998 | ldap:///o=base?attr1?sub?(uid=fred) | |
2813c06e | 6999 | value1.1,value1,,2 |
420a0d19 CE |
7000 | |
7001 | ldap:///o=base?attr2?sub?(uid=fred) | |
7002 | value two | |
7003 | ||
2813c06e CE |
7004 | ldap:///o=base?attr?sub?(uid=fred) |
7005 | value1.1,value1,,2,value two | |
7006 | ||
420a0d19 | 7007 | ldap:///o=base?attr1,attr2?sub?(uid=fred) |
2813c06e | 7008 | attr1="value1.1,value1,,2" attr2="value two" |
420a0d19 CE |
7009 | |
7010 | ldap:///o=base??sub?(uid=fred) | |
2813c06e | 7011 | objectClass="top" attr1="value1.1,value1,,2" attr2="value two" |
420a0d19 | 7012 | |
2813c06e CE |
7013 | You can make use of Exim's -be option to run expansion tests and thereby check |
7014 | the results of LDAP lookups. The extract operator in string expansions can be | |
7015 | used to pick out individual fields from data that consists of key=value pairs. | |
7016 | The listextract operator should be used to pick out individual values of | |
7017 | attributes, even when only a single value is expected. The doubling of embedded | |
7018 | commas allows you to use the returned data as a comma separated list (using the | |
7019 | "<," syntax for changing the input list separator). | |
420a0d19 CE |
7020 | |
7021 | ||
2813c06e | 7022 | 9.20 More about NIS+ |
420a0d19 CE |
7023 | -------------------- |
7024 | ||
7025 | NIS+ queries consist of a NIS+ indexed name followed by an optional colon and | |
7026 | field name. If this is given, the result of a successful query is the contents | |
7027 | of the named field; otherwise the result consists of a concatenation of | |
7028 | field-name=field-value pairs, separated by spaces. Empty values and values | |
7029 | containing spaces are quoted. For example, the query | |
7030 | ||
7031 | [name=mg1456],passwd.org_dir | |
7032 | ||
7033 | might return the string | |
7034 | ||
7035 | name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre" | |
7036 | home=/home/mg1456 shell=/bin/bash shadow="" | |
7037 | ||
7038 | (split over two lines here to fit on the page), whereas | |
7039 | ||
7040 | [name=mg1456],passwd.org_dir:gcos | |
7041 | ||
7042 | would just return | |
7043 | ||
7044 | Martin Guerre | |
7045 | ||
7046 | with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry | |
7047 | for the given indexed key. The effect of the quote_nisplus expansion operator | |
7048 | is to double any quote characters within the text. | |
7049 | ||
7050 | ||
2813c06e | 7051 | 9.21 SQL lookups |
420a0d19 CE |
7052 | ---------------- |
7053 | ||
2813c06e CE |
7054 | Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, Redis, and |
7055 | SQLite databases. Queries for these databases contain SQL statements, so an | |
7056 | example might be | |
420a0d19 CE |
7057 | |
7058 | ${lookup mysql{select mailbox from users where id='userx'}\ | |
7059 | {$value}fail} | |
7060 | ||
7061 | If the result of the query contains more than one field, the data for each | |
7062 | field in the row is returned, preceded by its name, so the result of | |
7063 | ||
7064 | ${lookup pgsql{select home,name from users where id='userx'}\ | |
7065 | {$value}} | |
7066 | ||
7067 | might be | |
7068 | ||
7069 | home=/home/userx name="Mister X" | |
7070 | ||
7071 | Empty values and values containing spaces are double quoted, with embedded | |
7072 | quotes escaped by a backslash. If the result of the query contains just one | |
7073 | field, the value is passed back verbatim, without a field name, for example: | |
7074 | ||
7075 | Mister X | |
7076 | ||
7077 | If the result of the query yields more than one row, it is all concatenated, | |
7078 | with a newline between the data for each row. | |
7079 | ||
7080 | ||
2813c06e CE |
7081 | 9.22 More about MySQL, PostgreSQL, Oracle, InterBase, and Redis |
7082 | --------------------------------------------------------------- | |
420a0d19 | 7083 | |
2813c06e CE |
7084 | If any MySQL, PostgreSQL, Oracle, InterBase or Redis lookups are used, the |
7085 | mysql_servers, pgsql_servers, oracle_servers, ibase_servers, or redis_servers | |
7086 | option (as appropriate) must be set to a colon-separated list of server | |
7087 | information. (For MySQL and PostgreSQL, the global option need not be set if | |
7088 | all queries contain their own server information - see section 9.23.) For all | |
7089 | but Redis each item in the list is a slash-separated list of four items: host | |
7090 | name, database name, user name, and password. In the case of Oracle, the host | |
7091 | name field is used for the "service name", and the database name field is not | |
7092 | used and should be empty. For example: | |
420a0d19 CE |
7093 | |
7094 | hide oracle_servers = oracle.plc.example//userx/abcdwxyz | |
7095 | ||
7096 | Because password data is sensitive, you should always precede the setting with | |
7097 | "hide", to prevent non-admin users from obtaining the setting via the -bP | |
7098 | option. Here is an example where two MySQL servers are listed: | |
7099 | ||
7100 | hide mysql_servers = localhost/users/root/secret:\ | |
7101 | otherhost/users/root/othersecret | |
7102 | ||
7103 | For MySQL and PostgreSQL, a host may be specified as <name>:<port> but because | |
7104 | this is a colon-separated list, the colon has to be doubled. For each query, | |
7105 | these parameter groups are tried in order until a connection is made and a | |
7106 | query is successfully processed. The result of a query may be that no data is | |
7107 | found, but that is still a successful query. In other words, the list of | |
7108 | servers provides a backup facility, not a list of different places to look. | |
7109 | ||
2813c06e CE |
7110 | For Redis the global option need not be specified if all queries contain their |
7111 | own server information - see section 9.23. If specified, the option must be set | |
7112 | to a colon-separated list of server information. Each item in the list is a | |
7113 | slash-separated list of three items: host, database number, and password. | |
7114 | ||
7115 | 1. The host is required and may be either an IPv4 address and optional port | |
7116 | number (separated by a colon, which needs doubling due to the higher-level | |
7117 | list), or a Unix socket pathname enclosed in parentheses | |
7118 | ||
7119 | 2. The database number is optional; if present that number is selected in the | |
7120 | backend | |
7121 | ||
7122 | 3. The password is optional; if present it is used to authenticate to the | |
7123 | backend | |
7124 | ||
420a0d19 CE |
7125 | The quote_mysql, quote_pgsql, and quote_oracle expansion operators convert |
7126 | newline, tab, carriage return, and backspace to \n, \t, \r, and \b | |
7127 | respectively, and the characters single-quote, double-quote, and backslash | |
2813c06e | 7128 | itself are escaped with backslashes. |
420a0d19 | 7129 | |
2813c06e CE |
7130 | The quote_redis expansion operator escapes whitespace and backslash characters |
7131 | with a backslash. | |
420a0d19 | 7132 | |
2813c06e CE |
7133 | |
7134 | 9.23 Specifying the server in the query | |
420a0d19 CE |
7135 | --------------------------------------- |
7136 | ||
2813c06e CE |
7137 | For MySQL, PostgreSQL and Redis lookups (but not currently for Oracle and |
7138 | InterBase), it is possible to specify a list of servers with an individual | |
7139 | query. This is done by starting the query with | |
420a0d19 CE |
7140 | |
7141 | servers=server1:server2:server3:...; | |
7142 | ||
7143 | Each item in the list may take one of two forms: | |
7144 | ||
7145 | 1. If it contains no slashes it is assumed to be just a host name. The | |
7146 | appropriate global option (mysql_servers or pgsql_servers) is searched for | |
7147 | a host of the same name, and the remaining parameters (database, user, | |
7148 | password) are taken from there. | |
7149 | ||
7150 | 2. If it contains any slashes, it is taken as a complete parameter set. | |
7151 | ||
7152 | The list of servers is used in exactly the same way as the global list. Once a | |
7153 | connection to a server has happened and a query has been successfully executed, | |
7154 | processing of the lookup ceases. | |
7155 | ||
7156 | This feature is intended for use in master/slave situations where updates are | |
7157 | occurring and you want to update the master rather than a slave. If the master | |
7158 | is in the list as a backup for reading, you might have a global setting like | |
7159 | this: | |
7160 | ||
7161 | mysql_servers = slave1/db/name/pw:\ | |
7162 | slave2/db/name/pw:\ | |
7163 | master/db/name/pw | |
7164 | ||
7165 | In an updating lookup, you could then write: | |
7166 | ||
7167 | ${lookup mysql{servers=master; UPDATE ...} } | |
7168 | ||
7169 | That query would then be sent only to the master server. If, on the other hand, | |
7170 | the master is not to be used for reading, and so is not present in the global | |
7171 | option, you can still update it by a query of this form: | |
7172 | ||
7173 | ${lookup pgsql{servers=master/db/name/pw; UPDATE ...} } | |
7174 | ||
7175 | ||
2813c06e | 7176 | 9.24 Special MySQL features |
420a0d19 CE |
7177 | --------------------------- |
7178 | ||
7179 | For MySQL, an empty host name or the use of "localhost" in mysql_servers causes | |
7180 | a connection to the server on the local host by means of a Unix domain socket. | |
2813c06e CE |
7181 | An alternate socket can be specified in parentheses. An option group name for |
7182 | MySQL option files can be specified in square brackets; the default value is | |
7183 | "exim". The full syntax of each item in mysql_servers is: | |
420a0d19 | 7184 | |
2813c06e | 7185 | <hostname>::<port>(<socket name>)[<option group>]/<database>/<user>/<password> |
420a0d19 | 7186 | |
2813c06e | 7187 | Any of the four sub-parts of the first field can be omitted. For normal use on |
420a0d19 CE |
7188 | the local host it can be left blank or set to just "localhost". |
7189 | ||
7190 | No database need be supplied - but if it is absent here, it must be given in | |
7191 | the queries. | |
7192 | ||
7193 | If a MySQL query is issued that does not request any data (an insert, update, | |
7194 | or delete command), the result of the lookup is the number of rows affected. | |
7195 | ||
7196 | Warning: This can be misleading. If an update does not actually change anything | |
7197 | (for example, setting a field to the value it already has), the result is zero | |
7198 | because no rows are affected. | |
7199 | ||
7200 | ||
2813c06e | 7201 | 9.25 Special PostgreSQL features |
420a0d19 CE |
7202 | -------------------------------- |
7203 | ||
7204 | PostgreSQL lookups can also use Unix domain socket connections to the database. | |
7205 | This is usually faster and costs less CPU time than a TCP/IP connection. | |
7206 | However it can be used only if the mail server runs on the same machine as the | |
7207 | database server. A configuration line for PostgreSQL via Unix domain sockets | |
7208 | looks like this: | |
7209 | ||
7210 | hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ... | |
7211 | ||
7212 | In other words, instead of supplying a host name, a path to the socket is | |
7213 | given. The path name is enclosed in parentheses so that its slashes aren't | |
7214 | visually confused with the delimiters for the other server parameters. | |
7215 | ||
7216 | If a PostgreSQL query is issued that does not request any data (an insert, | |
7217 | update, or delete command), the result of the lookup is the number of rows | |
7218 | affected. | |
7219 | ||
7220 | ||
2813c06e | 7221 | 9.26 More about SQLite |
420a0d19 CE |
7222 | ---------------------- |
7223 | ||
7224 | SQLite is different to the other SQL lookups because a file name is required in | |
7225 | addition to the SQL query. An SQLite database is a single file, and there is no | |
7226 | daemon as in the other SQL databases. The interface to Exim requires the name | |
7227 | of the file, as an absolute path, to be given at the start of the query. It is | |
7228 | separated from the query by white space. This means that the path name cannot | |
7229 | contain white space. Here is a lookup expansion example: | |
7230 | ||
7231 | ${lookup sqlite {/some/thing/sqlitedb \ | |
7232 | select name from aliases where id='userx';}} | |
7233 | ||
7234 | In a list, the syntax is similar. For example: | |
7235 | ||
7236 | domainlist relay_to_domains = sqlite;/some/thing/sqlitedb \ | |
7237 | select * from relays where ip='$sender_host_address'; | |
7238 | ||
7239 | The only character affected by the quote_sqlite operator is a single quote, | |
7240 | which it doubles. | |
7241 | ||
7242 | The SQLite library handles multiple simultaneous accesses to the database | |
7243 | internally. Multiple readers are permitted, but only one process can update at | |
7244 | once. Attempts to access the database while it is being updated are rejected | |
7245 | after a timeout period, during which the SQLite library waits for the lock to | |
7246 | be released. In Exim, the default timeout is set to 5 seconds, but it can be | |
7247 | changed by means of the sqlite_lock_timeout option. | |
7248 | ||
7249 | ||
2813c06e CE |
7250 | 9.27 More about Redis |
7251 | --------------------- | |
7252 | ||
7253 | Redis is a non-SQL database. Commands are simple get and set. Examples: | |
7254 | ||
7255 | ${lookup redis{set keyname ${quote_redis:objvalue plus}}} | |
7256 | ${lookup redis{get keyname}} | |
7257 | ||
7258 | ||
420a0d19 CE |
7259 | |
7260 | =============================================================================== | |
7261 | 10. DOMAIN, HOST, ADDRESS, AND LOCAL PART LISTS | |
7262 | ||
7263 | A number of Exim configuration options contain lists of domains, hosts, email | |
7264 | addresses, or local parts. For example, the hold_domains option contains a list | |
7265 | of domains whose delivery is currently suspended. These lists are also used as | |
2813c06e | 7266 | data in ACL statements (see chapter 43), and as arguments to expansion |
420a0d19 CE |
7267 | conditions such as match_domain. |
7268 | ||
7269 | Each item in one of these lists is a pattern to be matched against a domain, | |
7270 | host, email address, or local part, respectively. In the sections below, the | |
7271 | different types of pattern for each case are described, but first we cover some | |
7272 | general facilities that apply to all four kinds of list. | |
7273 | ||
2813c06e CE |
7274 | Note that other parts of Exim use a string list which does not support all the |
7275 | complexity available in domain, host, address and local part lists. | |
7276 | ||
420a0d19 CE |
7277 | |
7278 | 10.1 Expansion of lists | |
7279 | ----------------------- | |
7280 | ||
2813c06e CE |
7281 | Each list is expanded as a single string before it is used. |
7282 | ||
7283 | Exception: the router headers_remove option, where list-item splitting is done | |
7284 | before string-expansion. | |
7285 | ||
7286 | The result of expansion must be a list, possibly containing empty items, which | |
7287 | is split up into separate items for matching. By default, colon is the | |
7288 | separator character, but this can be varied if necessary. See sections 6.20 and | |
7289 | 6.22 for details of the list syntax; the second of these discusses the way to | |
7290 | specify empty list items. | |
420a0d19 CE |
7291 | |
7292 | If the string expansion is forced to fail, Exim behaves as if the item it is | |
7293 | testing (domain, host, address, or local part) is not in the list. Other | |
7294 | expansion failures cause temporary errors. | |
7295 | ||
7296 | If an item in a list is a regular expression, backslashes, dollars and possibly | |
7297 | other special characters in the expression must be protected against | |
7298 | misinterpretation by the string expander. The easiest way to do this is to use | |
7299 | the "\N" expansion feature to indicate that the contents of the regular | |
7300 | expression should not be expanded. For example, in an ACL you might have: | |
7301 | ||
7302 | deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : \ | |
7303 | ${lookup{$domain}lsearch{/badsenders/bydomain}} | |
7304 | ||
7305 | The first item is a regular expression that is protected from expansion by "\ | |
7306 | N", whereas the second uses the expansion to obtain a list of unwanted senders | |
7307 | based on the receiving domain. | |
7308 | ||
7309 | ||
7310 | 10.2 Negated items in lists | |
7311 | --------------------------- | |
7312 | ||
7313 | Items in a list may be positive or negative. Negative items are indicated by a | |
7314 | leading exclamation mark, which may be followed by optional white space. A list | |
7315 | defines a set of items (domains, etc). When Exim processes one of these lists, | |
7316 | it is trying to find out whether a domain, host, address, or local part | |
7317 | (respectively) is in the set that is defined by the list. It works like this: | |
7318 | ||
7319 | The list is scanned from left to right. If a positive item is matched, the | |
7320 | subject that is being checked is in the set; if a negative item is matched, the | |
7321 | subject is not in the set. If the end of the list is reached without the | |
7322 | subject having matched any of the patterns, it is in the set if the last item | |
7323 | was a negative one, but not if it was a positive one. For example, the list in | |
7324 | ||
7325 | domainlist relay_to_domains = !a.b.c : *.b.c | |
7326 | ||
7327 | matches any domain ending in .b.c except for a.b.c. Domains that match neither | |
7328 | a.b.c nor *.b.c do not match, because the last item in the list is positive. | |
7329 | However, if the setting were | |
7330 | ||
7331 | domainlist relay_to_domains = !a.b.c | |
7332 | ||
7333 | then all domains other than a.b.c would match because the last item in the list | |
7334 | is negative. In other words, a list that ends with a negative item behaves as | |
7335 | if it had an extra item ":*" on the end. | |
7336 | ||
7337 | Another way of thinking about positive and negative items in lists is to read | |
7338 | the connector as "or" after a positive item and as "and" after a negative item. | |
7339 | ||
7340 | ||
7341 | 10.3 File names in lists | |
7342 | ------------------------ | |
7343 | ||
7344 | If an item in a domain, host, address, or local part list is an absolute file | |
7345 | name (beginning with a slash character), each line of the file is read and | |
7346 | processed as if it were an independent item in the list, except that further | |
7347 | file names are not allowed, and no expansion of the data from the file takes | |
7348 | place. Empty lines in the file are ignored, and the file may also contain | |
7349 | comment lines: | |
7350 | ||
7351 | * For domain and host lists, if a # character appears anywhere in a line of | |
7352 | the file, it and all following characters are ignored. | |
7353 | ||
7354 | * Because local parts may legitimately contain # characters, a comment in an | |
7355 | address list or local part list file is recognized only if # is preceded by | |
7356 | white space or the start of the line. For example: | |
7357 | ||
7358 | not#comment@x.y.z # but this is a comment | |
7359 | ||
7360 | Putting a file name in a list has the same effect as inserting each line of the | |
7361 | file as an item in the list (blank lines and comments excepted). However, there | |
7362 | is one important difference: the file is read each time the list is processed, | |
7363 | so if its contents vary over time, Exim's behaviour changes. | |
7364 | ||
7365 | If a file name is preceded by an exclamation mark, the sense of any match | |
7366 | within the file is inverted. For example, if | |
7367 | ||
7368 | hold_domains = !/etc/nohold-domains | |
7369 | ||
7370 | and the file contains the lines | |
7371 | ||
7372 | !a.b.c | |
7373 | *.b.c | |
7374 | ||
7375 | then a.b.c is in the set of domains defined by hold_domains, whereas any domain | |
7376 | matching "*.b.c" is not. | |
7377 | ||
7378 | ||
7379 | 10.4 An lsearch file is not an out-of-line list | |
7380 | ----------------------------------------------- | |
7381 | ||
7382 | As will be described in the sections that follow, lookups can be used in lists | |
7383 | to provide indexed methods of checking list membership. There has been some | |
7384 | confusion about the way lsearch lookups work in lists. Because an lsearch file | |
7385 | contains plain text and is scanned sequentially, it is sometimes thought that | |
7386 | it is allowed to contain wild cards and other kinds of non-constant pattern. | |
7387 | This is not the case. The keys in an lsearch file are always fixed strings, | |
7388 | just as for any other single-key lookup type. | |
7389 | ||
7390 | If you want to use a file to contain wild-card patterns that form part of a | |
7391 | list, just give the file name on its own, without a search type, as described | |
7392 | in the previous section. You could also use the wildlsearch or nwildlsearch, | |
7393 | but there is no advantage in doing this. | |
7394 | ||
7395 | ||
7396 | 10.5 Named lists | |
7397 | ---------------- | |
7398 | ||
7399 | A list of domains, hosts, email addresses, or local parts can be given a name | |
7400 | which is then used to refer to the list elsewhere in the configuration. This is | |
7401 | particularly convenient if the same list is required in several different | |
7402 | places. It also allows lists to be given meaningful names, which can improve | |
7403 | the readability of the configuration. For example, it is conventional to define | |
7404 | a domain list called local_domains for all the domains that are handled locally | |
7405 | on a host, using a configuration line such as | |
7406 | ||
7407 | domainlist local_domains = localhost:my.dom.example | |
7408 | ||
7409 | Named lists are referenced by giving their name preceded by a plus sign, so, | |
7410 | for example, a router that is intended to handle local domains would be | |
7411 | configured with the line | |
7412 | ||
7413 | domains = +local_domains | |
7414 | ||
7415 | The first router in a configuration is often one that handles all domains | |
7416 | except the local ones, using a configuration with a negated item like this: | |
7417 | ||
7418 | dnslookup: | |
7419 | driver = dnslookup | |
7420 | domains = ! +local_domains | |
7421 | transport = remote_smtp | |
7422 | no_more | |
7423 | ||
7424 | The four kinds of named list are created by configuration lines starting with | |
7425 | the words domainlist, hostlist, addresslist, or localpartlist, respectively. | |
7426 | Then there follows the name that you are defining, followed by an equals sign | |
7427 | and the list itself. For example: | |
7428 | ||
7429 | hostlist relay_from_hosts = 192.168.23.0/24 : my.friend.example | |
7430 | addresslist bad_senders = cdb;/etc/badsenders | |
7431 | ||
7432 | A named list may refer to other named lists: | |
7433 | ||
7434 | domainlist dom1 = first.example : second.example | |
7435 | domainlist dom2 = +dom1 : third.example | |
7436 | domainlist dom3 = fourth.example : +dom2 : fifth.example | |
7437 | ||
7438 | Warning: If the last item in a referenced list is a negative one, the effect | |
7439 | may not be what you intended, because the negation does not propagate out to | |
7440 | the higher level. For example, consider: | |
7441 | ||
7442 | domainlist dom1 = !a.b | |
7443 | domainlist dom2 = +dom1 : *.b | |
7444 | ||
7445 | The second list specifies "either in the dom1 list or *.b". The first list | |
7446 | specifies just "not a.b", so the domain x.y matches it. That means it matches | |
7447 | the second list as well. The effect is not the same as | |
7448 | ||
7449 | domainlist dom2 = !a.b : *.b | |
7450 | ||
7451 | where x.y does not match. It's best to avoid negation altogether in referenced | |
7452 | lists if you can. | |
7453 | ||
7454 | Named lists may have a performance advantage. When Exim is routing an address | |
7455 | or checking an incoming message, it caches the result of tests on named lists. | |
7456 | So, if you have a setting such as | |
7457 | ||
7458 | domains = +local_domains | |
7459 | ||
7460 | on several of your routers or in several ACL statements, the actual test is | |
7461 | done only for the first one. However, the caching works only if there are no | |
7462 | expansions within the list itself or any sublists that it references. In other | |
7463 | words, caching happens only for lists that are known to be the same each time | |
7464 | they are referenced. | |
7465 | ||
7466 | By default, there may be up to 16 named lists of each type. This limit can be | |
7467 | extended by changing a compile-time variable. The use of domain and host lists | |
7468 | is recommended for concepts such as local domains, relay domains, and relay | |
7469 | hosts. The default configuration is set up like this. | |
7470 | ||
7471 | ||
7472 | 10.6 Named lists compared with macros | |
7473 | ------------------------------------- | |
7474 | ||
7475 | At first sight, named lists might seem to be no different from macros in the | |
7476 | configuration file. However, macros are just textual substitutions. If you | |
7477 | write | |
7478 | ||
7479 | ALIST = host1 : host2 | |
7480 | auth_advertise_hosts = !ALIST | |
7481 | ||
7482 | it probably won't do what you want, because that is exactly the same as | |
7483 | ||
7484 | auth_advertise_hosts = !host1 : host2 | |
7485 | ||
7486 | Notice that the second host name is not negated. However, if you use a host | |
7487 | list, and write | |
7488 | ||
7489 | hostlist alist = host1 : host2 | |
7490 | auth_advertise_hosts = ! +alist | |
7491 | ||
7492 | the negation applies to the whole list, and so that is equivalent to | |
7493 | ||
7494 | auth_advertise_hosts = !host1 : !host2 | |
7495 | ||
7496 | ||
7497 | 10.7 Named list caching | |
7498 | ----------------------- | |
7499 | ||
7500 | While processing a message, Exim caches the result of checking a named list if | |
7501 | it is sure that the list is the same each time. In practice, this means that | |
7502 | the cache operates only if the list contains no $ characters, which guarantees | |
7503 | that it will not change when it is expanded. Sometimes, however, you may have | |
7504 | an expanded list that you know will be the same each time within a given | |
7505 | message. For example: | |
7506 | ||
7507 | domainlist special_domains = \ | |
7508 | ${lookup{$sender_host_address}cdb{/some/file}} | |
7509 | ||
7510 | This provides a list of domains that depends only on the sending host's IP | |
7511 | address. If this domain list is referenced a number of times (for example, in | |
7512 | several ACL lines, or in several routers) the result of the check is not cached | |
7513 | by default, because Exim does not know that it is going to be the same list | |
7514 | each time. | |
7515 | ||
7516 | By appending "_cache" to "domainlist" you can tell Exim to go ahead and cache | |
7517 | the result anyway. For example: | |
7518 | ||
7519 | domainlist_cache special_domains = ${lookup{... | |
7520 | ||
7521 | If you do this, you should be absolutely sure that caching is going to do the | |
7522 | right thing in all cases. When in doubt, leave it out. | |
7523 | ||
7524 | ||
7525 | 10.8 Domain lists | |
7526 | ----------------- | |
7527 | ||
7528 | Domain lists contain patterns that are to be matched against a mail domain. The | |
7529 | following types of item may appear in domain lists: | |
7530 | ||
7531 | * If a pattern consists of a single @ character, it matches the local host | |
7532 | name, as set by the primary_hostname option (or defaulted). This makes it | |
7533 | possible to use the same configuration file on several different hosts that | |
7534 | differ only in their names. | |
7535 | ||
7536 | * If a pattern consists of the string "@[]" it matches an IP address enclosed | |
7537 | in square brackets (as in an email address that contains a domain literal), | |
7538 | but only if that IP address is recognized as local for email routing | |
7539 | purposes. The local_interfaces and extra_local_interfaces options can be | |
7540 | used to control which of a host's several IP addresses are treated as | |
7541 | local. In today's Internet, the use of domain literals is controversial. | |
7542 | ||
7543 | * If a pattern consists of the string "@mx_any" it matches any domain that | |
7544 | has an MX record pointing to the local host or to any host that is listed | |
7545 | in hosts_treat_as_local. The items "@mx_primary" and "@mx_secondary" are | |
7546 | similar, except that the first matches only when a primary MX target is the | |
7547 | local host, and the second only when no primary MX target is the local | |
7548 | host, but a secondary MX target is. "Primary" means an MX record with the | |
7549 | lowest preference value - there may of course be more than one of them. | |
7550 | ||
7551 | The MX lookup that takes place when matching a pattern of this type is | |
7552 | performed with the resolver options for widening names turned off. Thus, | |
7553 | for example, a single-component domain will not be expanded by adding the | |
7554 | resolver's default domain. See the qualify_single and search_parents | |
7555 | options of the dnslookup router for a discussion of domain widening. | |
7556 | ||
7557 | Sometimes you may want to ignore certain IP addresses when using one of | |
7558 | these patterns. You can specify this by following the pattern with "/ignore | |
7559 | ="<ip list>, where <ip list> is a list of IP addresses. These addresses are | |
7560 | ignored when processing the pattern (compare the ignore_target_hosts option | |
7561 | on a router). For example: | |
7562 | ||
7563 | domains = @mx_any/ignore=127.0.0.1 | |
7564 | ||
7565 | This example matches any domain that has an MX record pointing to one of | |
7566 | the local host's IP addresses other than 127.0.0.1. | |
7567 | ||
7568 | The list of IP addresses is in fact processed by the same code that | |
7569 | processes host lists, so it may contain CIDR-coded network specifications | |
7570 | and it may also contain negative items. | |
7571 | ||
7572 | Because the list of IP addresses is a sublist within a domain list, you | |
7573 | have to be careful about delimiters if there is more than one address. Like | |
7574 | any other list, the default delimiter can be changed. Thus, you might have: | |
7575 | ||
7576 | domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \ | |
7577 | an.other.domain : ... | |
7578 | ||
7579 | so that the sublist uses semicolons for delimiters. When IPv6 addresses are | |
7580 | involved, it is easiest to change the delimiter for the main list as well: | |
7581 | ||
7582 | domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \ | |
7583 | an.other.domain ? ... | |
7584 | ||
7585 | * If a pattern starts with an asterisk, the remaining characters of the | |
7586 | pattern are compared with the terminating characters of the domain. The use | |
7587 | of "*" in domain lists differs from its use in partial matching lookups. In | |
7588 | a domain list, the character following the asterisk need not be a dot, | |
7589 | whereas partial matching works only in terms of dot-separated components. | |
7590 | For example, a domain list item such as "*key.ex" matches donkey.ex as well | |
7591 | as cipher.key.ex. | |
7592 | ||
7593 | * If a pattern starts with a circumflex character, it is treated as a regular | |
7594 | expression, and matched against the domain using a regular expression | |
7595 | matching function. The circumflex is treated as part of the regular | |
7596 | expression. Email domains are case-independent, so this regular expression | |
7597 | match is by default case-independent, but you can make it case-dependent by | |
7598 | starting it with "(?-i)". References to descriptions of the syntax of | |
7599 | regular expressions are given in chapter 8. | |
7600 | ||
7601 | Warning: Because domain lists are expanded before being processed, you must | |
7602 | escape any backslash and dollar characters in the regular expression, or | |
7603 | use the special "\N" sequence (see chapter 11) to specify that it is not to | |
7604 | be expanded (unless you really do want to build a regular expression by | |
7605 | expansion, of course). | |
7606 | ||
7607 | * If a pattern starts with the name of a single-key lookup type followed by a | |
7608 | semicolon (for example, "dbm;" or "lsearch;"), the remainder of the pattern | |
7609 | must be a file name in a suitable format for the lookup type. For example, | |
7610 | for "cdb;" it must be an absolute path: | |
7611 | ||
7612 | domains = cdb;/etc/mail/local_domains.cdb | |
7613 | ||
7614 | The appropriate type of lookup is done on the file using the domain name as | |
7615 | the key. In most cases, the data that is looked up is not used; Exim is | |
7616 | interested only in whether or not the key is present in the file. However, | |
7617 | when a lookup is used for the domains option on a router or a domains | |
7618 | condition in an ACL statement, the data is preserved in the $domain_data | |
7619 | variable and can be referred to in other router options or other statements | |
7620 | in the same ACL. | |
7621 | ||
7622 | * Any of the single-key lookup type names may be preceded by "partial"<n>"-", | |
7623 | where the <n> is optional, for example, | |
7624 | ||
7625 | domains = partial-dbm;/partial/domains | |
7626 | ||
7627 | This causes partial matching logic to be invoked; a description of how this | |
7628 | works is given in section 9.7. | |
7629 | ||
7630 | * Any of the single-key lookup types may be followed by an asterisk. This | |
7631 | causes a default lookup for a key consisting of a single asterisk to be | |
7632 | done if the original lookup fails. This is not a useful feature when using | |
7633 | a domain list to select particular domains (because any domain would | |
7634 | match), but it might have value if the result of the lookup is being used | |
7635 | via the $domain_data expansion variable. | |
7636 | ||
7637 | * If the pattern starts with the name of a query-style lookup type followed | |
7638 | by a semicolon (for example, "nisplus;" or "ldap;"), the remainder of the | |
7639 | pattern must be an appropriate query for the lookup type, as described in | |
7640 | chapter 9. For example: | |
7641 | ||
7642 | hold_domains = mysql;select domain from holdlist \ | |
7643 | where domain = '${quote_mysql:$domain}'; | |
7644 | ||
7645 | In most cases, the data that is looked up is not used (so for an SQL query, | |
7646 | for example, it doesn't matter what field you select). Exim is interested | |
7647 | only in whether or not the query succeeds. However, when a lookup is used | |
7648 | for the domains option on a router, the data is preserved in the | |
7649 | $domain_data variable and can be referred to in other options. | |
7650 | ||
7651 | * If none of the above cases apply, a caseless textual comparison is made | |
7652 | between the pattern and the domain. | |
7653 | ||
7654 | Here is an example that uses several different kinds of pattern: | |
7655 | ||
7656 | domainlist funny_domains = \ | |
7657 | @ : \ | |
7658 | lib.unseen.edu : \ | |
7659 | *.foundation.fict.example : \ | |
7660 | \N^[1-2]\d{3}\.fict\.example$\N : \ | |
7661 | partial-dbm;/opt/data/penguin/book : \ | |
7662 | nis;domains.byname : \ | |
7663 | nisplus;[name=$domain,status=local],domains.org_dir | |
7664 | ||
7665 | There are obvious processing trade-offs among the various matching modes. Using | |
7666 | an asterisk is faster than a regular expression, and listing a few names | |
7667 | explicitly probably is too. The use of a file or database lookup is expensive, | |
7668 | but may be the only option if hundreds of names are required. Because the | |
7669 | patterns are tested in order, it makes sense to put the most commonly matched | |
7670 | patterns earlier. | |
7671 | ||
7672 | ||
7673 | 10.9 Host lists | |
7674 | --------------- | |
7675 | ||
7676 | Host lists are used to control what remote hosts are allowed to do. For | |
7677 | example, some hosts may be allowed to use the local host as a relay, and some | |
7678 | may be permitted to use the SMTP ETRN command. Hosts can be identified in two | |
7679 | different ways, by name or by IP address. In a host list, some types of pattern | |
7680 | are matched to a host name, and some are matched to an IP address. You need to | |
7681 | be particularly careful with this when single-key lookups are involved, to | |
7682 | ensure that the right value is being used as the key. | |
7683 | ||
7684 | ||
7685 | 10.10 Special host list patterns | |
7686 | -------------------------------- | |
7687 | ||
7688 | If a host list item is the empty string, it matches only when no remote host is | |
7689 | involved. This is the case when a message is being received from a local | |
7690 | process using SMTP on the standard input, that is, when a TCP/IP connection is | |
7691 | not used. | |
7692 | ||
7693 | The special pattern "*" in a host list matches any host or no host. Neither the | |
7694 | IP address nor the name is actually inspected. | |
7695 | ||
7696 | ||
7697 | 10.11 Host list patterns that match by IP address | |
7698 | ------------------------------------------------- | |
7699 | ||
7700 | If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket, | |
7701 | the incoming address actually appears in the IPv6 host as "::ffff:"<v4address>. | |
7702 | When such an address is tested against a host list, it is converted into a | |
7703 | traditional IPv4 address first. (Not all operating systems accept IPv4 calls on | |
7704 | IPv6 sockets, as there have been some security concerns.) | |
7705 | ||
7706 | The following types of pattern in a host list check the remote host by | |
7707 | inspecting its IP address: | |
7708 | ||
7709 | * If the pattern is a plain domain name (not a regular expression, not | |
7710 | starting with *, not a lookup of any kind), Exim calls the operating system | |
7711 | function to find the associated IP address(es). Exim uses the newer | |
7712 | getipnodebyname() function when available, otherwise gethostbyname(). This | |
7713 | typically causes a forward DNS lookup of the name. The result is compared | |
7714 | with the IP address of the subject host. | |
7715 | ||
7716 | If there is a temporary problem (such as a DNS timeout) with the host name | |
7717 | lookup, a temporary error occurs. For example, if the list is being used in | |
7718 | an ACL condition, the ACL gives a "defer" response, usually leading to a | |
7719 | temporary SMTP error code. If no IP address can be found for the host name, | |
7720 | what happens is described in section 10.14 below. | |
7721 | ||
7722 | * If the pattern is "@", the primary host name is substituted and used as a | |
7723 | domain name, as just described. | |
7724 | ||
7725 | * If the pattern is an IP address, it is matched against the IP address of | |
7726 | the subject host. IPv4 addresses are given in the normal "dotted-quad" | |
7727 | notation. IPv6 addresses can be given in colon-separated format, but the | |
7728 | colons have to be doubled so as not to be taken as item separators when the | |
7729 | default list separator is used. IPv6 addresses are recognized even when | |
7730 | Exim is compiled without IPv6 support. This means that if they appear in a | |
7731 | host list on an IPv4-only host, Exim will not treat them as host names. | |
7732 | They are just addresses that can never match a client host. | |
7733 | ||
7734 | * If the pattern is "@[]", it matches the IP address of any IP interface on | |
7735 | the local host. For example, if the local host is an IPv4 host with one | |
7736 | interface address 10.45.23.56, these two ACL statements have the same | |
7737 | effect: | |
7738 | ||
7739 | accept hosts = 127.0.0.1 : 10.45.23.56 | |
7740 | accept hosts = @[] | |
7741 | ||
7742 | * If the pattern is an IP address followed by a slash and a mask length (for | |
7743 | example 10.11.42.0/24), it is matched against the IP address of the subject | |
7744 | host under the given mask. This allows, an entire network of hosts to be | |
7745 | included (or excluded) by a single item. The mask uses CIDR notation; it | |
7746 | specifies the number of address bits that must match, starting from the | |
7747 | most significant end of the address. | |
7748 | ||
7749 | Note: The mask is not a count of addresses, nor is it the high number of a | |
7750 | range of addresses. It is the number of bits in the network portion of the | |
7751 | address. The above example specifies a 24-bit netmask, so it matches all | |
7752 | 256 addresses in the 10.11.42.0 network. An item such as | |
7753 | ||
7754 | 192.168.23.236/31 | |
7755 | ||
7756 | matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value | |
7757 | of 32 for an IPv4 address is the same as no mask at all; just a single | |
7758 | address matches. | |
7759 | ||
7760 | Here is another example which shows an IPv4 and an IPv6 network: | |
7761 | ||
7762 | recipient_unqualified_hosts = 192.168.0.0/16: \ | |
7763 | 3ffe::ffff::836f::::/48 | |
7764 | ||
7765 | The doubling of list separator characters applies only when these items | |
7766 | appear inline in a host list. It is not required when indirecting via a | |
7767 | file. For example: | |
7768 | ||
7769 | recipient_unqualified_hosts = /opt/exim/unqualnets | |
7770 | ||
7771 | could make use of a file containing | |
7772 | ||
7773 | 172.16.0.0/12 | |
7774 | 3ffe:ffff:836f::/48 | |
7775 | ||
7776 | to have exactly the same effect as the previous example. When listing IPv6 | |
7777 | addresses inline, it is usually more convenient to use the facility for | |
7778 | changing separator characters. This list contains the same two networks: | |
7779 | ||
7780 | recipient_unqualified_hosts = <; 172.16.0.0/12; \ | |
7781 | 3ffe:ffff:836f::/48 | |
7782 | ||
7783 | The separator is changed to semicolon by the leading "<;" at the start of | |
7784 | the list. | |
7785 | ||
7786 | ||
7787 | 10.12 Host list patterns for single-key lookups by host address | |
7788 | --------------------------------------------------------------- | |
7789 | ||
7790 | When a host is to be identified by a single-key lookup of its complete IP | |
7791 | address, the pattern takes this form: | |
7792 | ||
7793 | net-<single-key-search-type>;<search-data> | |
7794 | ||
7795 | For example: | |
7796 | ||
7797 | hosts_lookup = net-cdb;/hosts-by-ip.db | |
7798 | ||
7799 | The text form of the IP address of the subject host is used as the lookup key. | |
7800 | IPv6 addresses are converted to an unabbreviated form, using lower case | |
7801 | letters, with dots as separators because colon is the key terminator in lsearch | |
7802 | files. [Colons can in fact be used in keys in lsearch files by quoting the | |
7803 | keys, but this is a facility that was added later.] The data returned by the | |
7804 | lookup is not used. | |
7805 | ||
7806 | Single-key lookups can also be performed using masked IP addresses, using | |
7807 | patterns of this form: | |
7808 | ||
7809 | net<number>-<single-key-search-type>;<search-data> | |
7810 | ||
7811 | For example: | |
7812 | ||
7813 | net24-dbm;/networks.db | |
7814 | ||
7815 | The IP address of the subject host is masked using <number> as the mask length. | |
7816 | A textual string is constructed from the masked value, followed by the mask, | |
7817 | and this is used as the lookup key. For example, if the host's IP address is | |
7818 | 192.168.34.6, the key that is looked up for the above example is "192.168.34.0/ | |
7819 | 24". | |
7820 | ||
7821 | When an IPv6 address is converted to a string, dots are normally used instead | |
7822 | of colons, so that keys in lsearch files need not contain colons (which | |
7823 | terminate lsearch keys). This was implemented some time before the ability to | |
7824 | quote keys was made available in lsearch files. However, the more recently | |
7825 | implemented iplsearch files do require colons in IPv6 keys (notated using the | |
7826 | quoting facility) so as to distinguish them from IPv4 keys. For this reason, | |
7827 | when the lookup type is iplsearch, IPv6 addresses are converted using colons | |
7828 | and not dots. In all cases, full, unabbreviated IPv6 addresses are always used. | |
7829 | ||
7830 | Ideally, it would be nice to tidy up this anomalous situation by changing to | |
7831 | colons in all cases, given that quoting is now available for lsearch. However, | |
7832 | this would be an incompatible change that might break some existing | |
7833 | configurations. | |
7834 | ||
7835 | Warning: Specifying net32- (for an IPv4 address) or net128- (for an IPv6 | |
7836 | address) is not the same as specifying just net- without a number. In the | |
7837 | former case the key strings include the mask value, whereas in the latter case | |
7838 | the IP address is used on its own. | |
7839 | ||
7840 | ||
7841 | 10.13 Host list patterns that match by host name | |
7842 | ------------------------------------------------ | |
7843 | ||
7844 | There are several types of pattern that require Exim to know the name of the | |
7845 | remote host. These are either wildcard patterns or lookups by name. (If a | |
7846 | complete hostname is given without any wildcarding, it is used to find an IP | |
7847 | address to match against, as described in section 10.11 above.) | |
7848 | ||
7849 | If the remote host name is not already known when Exim encounters one of these | |
7850 | patterns, it has to be found from the IP address. Although many sites on the | |
7851 | Internet are conscientious about maintaining reverse DNS data for their hosts, | |
7852 | there are also many that do not do this. Consequently, a name cannot always be | |
7853 | found, and this may lead to unwanted effects. Take care when configuring host | |
7854 | lists with wildcarded name patterns. Consider what will happen if a name cannot | |
7855 | be found. | |
7856 | ||
7857 | Because of the problems of determining host names from IP addresses, matching | |
7858 | against host names is not as common as matching against IP addresses. | |
7859 | ||
7860 | By default, in order to find a host name, Exim first does a reverse DNS lookup; | |
7861 | if no name is found in the DNS, the system function (gethostbyaddr() or | |
7862 | getipnodebyaddr() if available) is tried. The order in which these lookups are | |
7863 | done can be changed by setting the host_lookup_order option. For security, once | |
7864 | Exim has found one or more names, it looks up the IP addresses for these names | |
7865 | and compares them with the IP address that it started with. Only those names | |
7866 | whose IP addresses match are accepted. Any other names are discarded. If no | |
7867 | names are left, Exim behaves as if the host name cannot be found. In the most | |
7868 | common case there is only one name and one IP address. | |
7869 | ||
7870 | There are some options that control what happens if a host name cannot be | |
7871 | found. These are described in section 10.14 below. | |
7872 | ||
7873 | As a result of aliasing, hosts may have more than one name. When processing any | |
7874 | of the following types of pattern, all the host's names are checked: | |
7875 | ||
7876 | * If a pattern starts with "*" the remainder of the item must match the end | |
7877 | of the host name. For example, "*.b.c" matches all hosts whose names end in | |
7878 | .b.c. This special simple form is provided because this is a very common | |
7879 | requirement. Other kinds of wildcarding require the use of a regular | |
7880 | expression. | |
7881 | ||
7882 | * If the item starts with "^" it is taken to be a regular expression which is | |
7883 | matched against the host name. Host names are case-independent, so this | |
7884 | regular expression match is by default case-independent, but you can make | |
7885 | it case-dependent by starting it with "(?-i)". References to descriptions | |
7886 | of the syntax of regular expressions are given in chapter 8. For example, | |
7887 | ||
7888 | ^(a|b)\.c\.d$ | |
7889 | ||
7890 | is a regular expression that matches either of the two hosts a.c.d or b.c.d | |
7891 | . When a regular expression is used in a host list, you must take care that | |
7892 | backslash and dollar characters are not misinterpreted as part of the | |
7893 | string expansion. The simplest way to do this is to use "\N" to mark that | |
7894 | part of the string as non-expandable. For example: | |
7895 | ||
7896 | sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : .... | |
7897 | ||
7898 | Warning: If you want to match a complete host name, you must include the | |
7899 | "$" terminating metacharacter in the regular expression, as in the above | |
7900 | example. Without it, a match at the start of the host name is all that is | |
7901 | required. | |
7902 | ||
7903 | ||
7904 | 10.14 Behaviour when an IP address or name cannot be found | |
7905 | ---------------------------------------------------------- | |
7906 | ||
7907 | While processing a host list, Exim may need to look up an IP address from a | |
7908 | name (see section 10.11), or it may need to look up a host name from an IP | |
7909 | address (see section 10.13). In either case, the behaviour when it fails to | |
7910 | find the information it is seeking is the same. | |
7911 | ||
7912 | Note: This section applies to permanent lookup failures. It does not apply to | |
7913 | temporary DNS errors, whose handling is described in the next section. | |
7914 | ||
7915 | Exim parses a host list from left to right. If it encounters a permanent lookup | |
7916 | failure in any item in the host list before it has found a match, Exim treats | |
7917 | it as a failure and the default behavior is as if the host does not match the | |
7918 | list. This may not always be what you want to happen. To change Exim's | |
7919 | behaviour, the special items "+include_unknown" or "+ignore_unknown" may appear | |
7920 | in the list (at top level - they are not recognized in an indirected file). | |
7921 | ||
7922 | * If any item that follows "+include_unknown" requires information that | |
7923 | cannot found, Exim behaves as if the host does match the list. For example, | |
7924 | ||
7925 | host_reject_connection = +include_unknown:*.enemy.ex | |
7926 | ||
7927 | rejects connections from any host whose name matches "*.enemy.ex", and also | |
7928 | any hosts whose name it cannot find. | |
7929 | ||
7930 | * If any item that follows "+ignore_unknown" requires information that cannot | |
7931 | be found, Exim ignores that item and proceeds to the rest of the list. For | |
7932 | example: | |
7933 | ||
7934 | accept hosts = +ignore_unknown : friend.example : \ | |
7935 | 192.168.4.5 | |
7936 | ||
7937 | accepts from any host whose name is friend.example and from 192.168.4.5, | |
7938 | whether or not its host name can be found. Without "+ignore_unknown", if no | |
7939 | name can be found for 192.168.4.5, it is rejected. | |
7940 | ||
7941 | Both "+include_unknown" and "+ignore_unknown" may appear in the same list. The | |
7942 | effect of each one lasts until the next, or until the end of the list. | |
7943 | ||
7944 | ||
7945 | 10.15 Mixing wildcarded host names and addresses in host lists | |
7946 | -------------------------------------------------------------- | |
7947 | ||
7948 | This section explains the host/ip processing logic with the same concepts as | |
7949 | the previous section, but specifically addresses what happens when a wildcarded | |
7950 | hostname is one of the items in the hostlist. | |
7951 | ||
7952 | * If you have name lookups or wildcarded host names and IP addresses in the | |
7953 | same host list, you should normally put the IP addresses first. For | |
7954 | example, in an ACL you could have: | |
7955 | ||
7956 | accept hosts = 10.9.8.7 : *.friend.example | |
7957 | ||
7958 | The reason you normally would order it this way lies in the left-to-right | |
7959 | way that Exim processes lists. It can test IP addresses without doing any | |
7960 | DNS lookups, but when it reaches an item that requires a host name, it | |
7961 | fails if it cannot find a host name to compare with the pattern. If the | |
7962 | above list is given in the opposite order, the accept statement fails for a | |
7963 | host whose name cannot be found, even if its IP address is 10.9.8.7. | |
7964 | ||
7965 | * If you really do want to do the name check first, and still recognize the | |
7966 | IP address, you can rewrite the ACL like this: | |
7967 | ||
7968 | accept hosts = *.friend.example | |
7969 | accept hosts = 10.9.8.7 | |
7970 | ||
7971 | If the first accept fails, Exim goes on to try the second one. See chapter | |
2813c06e | 7972 | 43 for details of ACLs. Alternatively, you can use "+ignore_unknown", which |
420a0d19 CE |
7973 | was discussed in depth in the first example in this section. |
7974 | ||
7975 | ||
7976 | 10.16 Temporary DNS errors when looking up host information | |
7977 | ----------------------------------------------------------- | |
7978 | ||
7979 | A temporary DNS lookup failure normally causes a defer action (except when | |
7980 | dns_again_means_nonexist converts it into a permanent error). However, host | |
2813c06e | 7981 | lists can include "+ignore_defer" and "+include_defer", analogous to |
420a0d19 CE |
7982 | "+ignore_unknown" and "+include_unknown", as described in the previous section. |
7983 | These options should be used with care, probably only in non-critical host | |
7984 | lists such as whitelists. | |
7985 | ||
7986 | ||
7987 | 10.17 Host list patterns for single-key lookups by host name | |
7988 | ------------------------------------------------------------ | |
7989 | ||
7990 | If a pattern is of the form | |
7991 | ||
7992 | <single-key-search-type>;<search-data> | |
7993 | ||
7994 | for example | |
7995 | ||
7996 | dbm;/host/accept/list | |
7997 | ||
7998 | a single-key lookup is performed, using the host name as its key. If the lookup | |
7999 | succeeds, the host matches the item. The actual data that is looked up is not | |
8000 | used. | |
8001 | ||
8002 | Reminder: With this kind of pattern, you must have host names as keys in the | |
8003 | file, not IP addresses. If you want to do lookups based on IP addresses, you | |
8004 | must precede the search type with "net-" (see section 10.12). There is, | |
8005 | however, no reason why you could not use two items in the same list, one doing | |
8006 | an address lookup and one doing a name lookup, both using the same file. | |
8007 | ||
8008 | ||
8009 | 10.18 Host list patterns for query-style lookups | |
8010 | ------------------------------------------------ | |
8011 | ||
8012 | If a pattern is of the form | |
8013 | ||
8014 | <query-style-search-type>;<query> | |
8015 | ||
8016 | the query is obeyed, and if it succeeds, the host matches the item. The actual | |
8017 | data that is looked up is not used. The variables $sender_host_address and | |
8018 | $sender_host_name can be used in the query. For example: | |
8019 | ||
8020 | hosts_lookup = pgsql;\ | |
8021 | select ip from hostlist where ip='$sender_host_address' | |
8022 | ||
8023 | The value of $sender_host_address for an IPv6 address contains colons. You can | |
8024 | use the sg expansion item to change this if you need to. If you want to use | |
8025 | masked IP addresses in database queries, you can use the mask expansion | |
8026 | operator. | |
8027 | ||
8028 | If the query contains a reference to $sender_host_name, Exim automatically | |
8029 | looks up the host name if it has not already done so. (See section 10.13 for | |
8030 | comments on finding host names.) | |
8031 | ||
8032 | Historical note: prior to release 4.30, Exim would always attempt to find a | |
8033 | host name before running the query, unless the search type was preceded by | |
8034 | "net-". This is no longer the case. For backwards compatibility, "net-" is | |
8035 | still recognized for query-style lookups, but its presence or absence has no | |
8036 | effect. (Of course, for single-key lookups, "net-" is important. See section | |
8037 | 10.12.) | |
8038 | ||
8039 | ||
8040 | 10.19 Address lists | |
8041 | ------------------- | |
8042 | ||
8043 | Address lists contain patterns that are matched against mail addresses. There | |
8044 | is one special case to be considered: the sender address of a bounce message is | |
8045 | always empty. You can test for this by providing an empty item in an address | |
8046 | list. For example, you can set up a router to process bounce messages by using | |
8047 | this option setting: | |
8048 | ||
8049 | senders = : | |
8050 | ||
8051 | The presence of the colon creates an empty item. If you do not provide any | |
8052 | data, the list is empty and matches nothing. The empty sender can also be | |
8053 | detected by a regular expression that matches an empty string, and by a | |
8054 | query-style lookup that succeeds when $sender_address is empty. | |
8055 | ||
8056 | Non-empty items in an address list can be straightforward email addresses. For | |
8057 | example: | |
8058 | ||
8059 | senders = jbc@askone.example : hs@anacreon.example | |
8060 | ||
8061 | A certain amount of wildcarding is permitted. If a pattern contains an @ | |
8062 | character, but is not a regular expression and does not begin with a | |
8063 | semicolon-terminated lookup type (described below), the local part of the | |
8064 | subject address is compared with the local part of the pattern, which may start | |
8065 | with an asterisk. If the local parts match, the domain is checked in exactly | |
8066 | the same way as for a pattern in a domain list. For example, the domain can be | |
8067 | wildcarded, refer to a named list, or be a lookup: | |
8068 | ||
8069 | deny senders = *@*.spamming.site:\ | |
8070 | *@+hostile_domains:\ | |
8071 | bozo@partial-lsearch;/list/of/dodgy/sites:\ | |
8072 | *@dbm;/bad/domains.db | |
8073 | ||
8074 | If a local part that begins with an exclamation mark is required, it has to be | |
8075 | specified using a regular expression, because otherwise the exclamation mark is | |
8076 | treated as a sign of negation, as is standard in lists. | |
8077 | ||
8078 | If a non-empty pattern that is not a regular expression or a lookup does not | |
8079 | contain an @ character, it is matched against the domain part of the subject | |
8080 | address. The only two formats that are recognized this way are a literal | |
8081 | domain, or a domain pattern that starts with *. In both these cases, the effect | |
8082 | is the same as if "*@" preceded the pattern. For example: | |
8083 | ||
8084 | deny senders = enemy.domain : *.enemy.domain | |
8085 | ||
8086 | The following kinds of more complicated address list pattern can match any | |
8087 | address, including the empty address that is characteristic of bounce message | |
8088 | senders: | |
8089 | ||
8090 | * If (after expansion) a pattern starts with "^", a regular expression match | |
8091 | is done against the complete address, with the pattern as the regular | |
8092 | expression. You must take care that backslash and dollar characters are not | |
8093 | misinterpreted as part of the string expansion. The simplest way to do this | |
8094 | is to use "\N" to mark that part of the string as non-expandable. For | |
8095 | example: | |
8096 | ||
8097 | deny senders = \N^.*this.*@example\.com$\N : \ | |
8098 | \N^\d{8}.+@spamhaus.example$\N : ... | |
8099 | ||
8100 | The "\N" sequences are removed by the expansion, so these items do indeed | |
8101 | start with "^" by the time they are being interpreted as address patterns. | |
8102 | ||
8103 | * Complete addresses can be looked up by using a pattern that starts with a | |
8104 | lookup type terminated by a semicolon, followed by the data for the lookup. | |
8105 | For example: | |
8106 | ||
8107 | deny senders = cdb;/etc/blocked.senders : \ | |
8108 | mysql;select address from blocked where \ | |
8109 | address='${quote_mysql:$sender_address}' | |
8110 | ||
8111 | Both query-style and single-key lookup types can be used. For a single-key | |
8112 | lookup type, Exim uses the complete address as the key. However, empty keys | |
8113 | are not supported for single-key lookups, so a match against the empty | |
8114 | address always fails. This restriction does not apply to query-style | |
8115 | lookups. | |
8116 | ||
8117 | Partial matching for single-key lookups (section 9.7) cannot be used, and | |
8118 | is ignored if specified, with an entry being written to the panic log. | |
8119 | However, you can configure lookup defaults, as described in section 9.6, | |
8120 | but this is useful only for the "*@" type of default. For example, with | |
8121 | this lookup: | |
8122 | ||
8123 | accept senders = lsearch*@;/some/file | |
8124 | ||
8125 | the file could contains lines like this: | |
8126 | ||
8127 | user1@domain1.example | |
8128 | *@domain2.example | |
8129 | ||
8130 | and for the sender address nimrod@jaeger.example, the sequence of keys that | |
8131 | are tried is: | |
8132 | ||
8133 | nimrod@jaeger.example | |
8134 | *@jaeger.example | |
8135 | * | |
8136 | ||
8137 | Warning 1: Do not include a line keyed by "*" in the file, because that | |
8138 | would mean that every address matches, thus rendering the test useless. | |
8139 | ||
8140 | Warning 2: Do not confuse these two kinds of item: | |
8141 | ||
8142 | deny recipients = dbm*@;/some/file | |
8143 | deny recipients = *@dbm;/some/file | |
8144 | ||
8145 | The first does a whole address lookup, with defaulting, as just described, | |
8146 | because it starts with a lookup type. The second matches the local part and | |
8147 | domain independently, as described in a bullet point below. | |
8148 | ||
8149 | The following kinds of address list pattern can match only non-empty addresses. | |
8150 | If the subject address is empty, a match against any of these pattern types | |
8151 | always fails. | |
8152 | ||
8153 | * If a pattern starts with "@@" followed by a single-key lookup item (for | |
8154 | example, "@@lsearch;/some/file"), the address that is being checked is | |
8155 | split into a local part and a domain. The domain is looked up in the file. | |
8156 | If it is not found, there is no match. If it is found, the data that is | |
8157 | looked up from the file is treated as a colon-separated list of local part | |
8158 | patterns, each of which is matched against the subject local part in turn. | |
8159 | ||
8160 | The lookup may be a partial one, and/or one involving a search for a | |
8161 | default keyed by "*" (see section 9.6). The local part patterns that are | |
8162 | looked up can be regular expressions or begin with "*", or even be further | |
8163 | lookups. They may also be independently negated. For example, with | |
8164 | ||
8165 | deny senders = @@dbm;/etc/reject-by-domain | |
8166 | ||
8167 | the data from which the DBM file is built could contain lines like | |
8168 | ||
8169 | baddomain.com: !postmaster : * | |
8170 | ||
8171 | to reject all senders except postmaster from that domain. | |
8172 | ||
8173 | If a local part that actually begins with an exclamation mark is required, | |
8174 | it has to be specified using a regular expression. In lsearch files, an | |
8175 | entry may be split over several lines by indenting the second and | |
8176 | subsequent lines, but the separating colon must still be included at line | |
8177 | breaks. White space surrounding the colons is ignored. For example: | |
8178 | ||
8179 | aol.com: spammer1 : spammer2 : ^[0-9]+$ : | |
8180 | spammer3 : spammer4 | |
8181 | ||
8182 | As in all colon-separated lists in Exim, a colon can be included in an item | |
8183 | by doubling. | |
8184 | ||
8185 | If the last item in the list starts with a right angle-bracket, the | |
8186 | remainder of the item is taken as a new key to look up in order to obtain a | |
8187 | continuation list of local parts. The new key can be any sequence of | |
8188 | characters. Thus one might have entries like | |
8189 | ||
8190 | aol.com: spammer1 : spammer 2 : >* | |
8191 | xyz.com: spammer3 : >* | |
8192 | *: ^\d{8}$ | |
8193 | ||
8194 | in a file that was searched with @@dbm*, to specify a match for 8-digit | |
8195 | local parts for all domains, in addition to the specific local parts listed | |
8196 | for each domain. Of course, using this feature costs another lookup each | |
8197 | time a chain is followed, but the effort needed to maintain the data is | |
8198 | reduced. | |
8199 | ||
8200 | It is possible to construct loops using this facility, and in order to | |
8201 | catch them, the chains may be no more than fifty items long. | |
8202 | ||
8203 | * The @@<lookup> style of item can also be used with a query-style lookup, | |
8204 | but in this case, the chaining facility is not available. The lookup can | |
8205 | only return a single list of local parts. | |
8206 | ||
8207 | Warning: There is an important difference between the address list items in | |
8208 | these two examples: | |
8209 | ||
8210 | senders = +my_list | |
8211 | senders = *@+my_list | |
8212 | ||
8213 | In the first one, "my_list" is a named address list, whereas in the second | |
8214 | example it is a named domain list. | |
8215 | ||
8216 | ||
8217 | 10.20 Case of letters in address lists | |
8218 | -------------------------------------- | |
8219 | ||
8220 | Domains in email addresses are always handled caselessly, but for local parts | |
8221 | case may be significant on some systems (see caseful_local_part for how Exim | |
8222 | deals with this when routing addresses). However, RFC 2505 (Anti-Spam | |
8223 | Recommendations for SMTP MTAs) suggests that matching of addresses to blocking | |
8224 | lists should be done in a case-independent manner. Since most address lists in | |
8225 | Exim are used for this kind of control, Exim attempts to do this by default. | |
8226 | ||
8227 | The domain portion of an address is always lowercased before matching it to an | |
8228 | address list. The local part is lowercased by default, and any string | |
8229 | comparisons that take place are done caselessly. This means that the data in | |
8230 | the address list itself, in files included as plain file names, and in any file | |
8231 | that is looked up using the "@@" mechanism, can be in any case. However, the | |
8232 | keys in files that are looked up by a search type other than lsearch (which | |
8233 | works caselessly) must be in lower case, because these lookups are not | |
8234 | case-independent. | |
8235 | ||
8236 | To allow for the possibility of caseful address list matching, if an item in an | |
8237 | address list is the string "+caseful", the original case of the local part is | |
8238 | restored for any comparisons that follow, and string comparisons are no longer | |
8239 | case-independent. This does not affect the domain, which remains in lower case. | |
8240 | However, although independent matches on the domain alone are still performed | |
8241 | caselessly, regular expressions that match against an entire address become | |
8242 | case-sensitive after "+caseful" has been seen. | |
8243 | ||
8244 | ||
8245 | 10.21 Local part lists | |
8246 | ---------------------- | |
8247 | ||
8248 | Case-sensitivity in local part lists is handled in the same way as for address | |
8249 | lists, as just described. The "+caseful" item can be used if required. In a | |
8250 | setting of the local_parts option in a router with caseful_local_part set | |
8251 | false, the subject is lowercased and the matching is initially | |
8252 | case-insensitive. In this case, "+caseful" will restore case-sensitive matching | |
8253 | in the local part list, but not elsewhere in the router. If caseful_local_part | |
8254 | is set true in a router, matching in the local_parts option is case-sensitive | |
8255 | from the start. | |
8256 | ||
8257 | If a local part list is indirected to a file (see section 10.3), comments are | |
8258 | handled in the same way as address lists - they are recognized only if the # is | |
8259 | preceded by white space or the start of the line. Otherwise, local part lists | |
8260 | are matched in the same way as domain lists, except that the special items that | |
8261 | refer to the local host ("@", "@[]", "@mx_any", "@mx_primary", and | |
8262 | "@mx_secondary") are not recognized. Refer to section 10.8 for details of the | |
8263 | other available item types. | |
8264 | ||
8265 | ||
8266 | ||
8267 | =============================================================================== | |
8268 | 11. STRING EXPANSIONS | |
8269 | ||
8270 | Many strings in Exim's run time configuration are expanded before use. Some of | |
8271 | them are expanded every time they are used; others are expanded only once. | |
8272 | ||
8273 | When a string is being expanded it is copied verbatim from left to right except | |
8274 | when a dollar or backslash character is encountered. A dollar specifies the | |
8275 | start of a portion of the string that is interpreted and replaced as described | |
8276 | below in section 11.5 onwards. Backslash is used as an escape character, as | |
8277 | described in the following section. | |
8278 | ||
8279 | Whether a string is expanded depends upon the context. Usually this is solely | |
8280 | dependent upon the option for which a value is sought; in this documentation, | |
8281 | options for which string expansion is performed are marked with * after the | |
8282 | data type. ACL rules always expand strings. A couple of expansion conditions do | |
8283 | not expand some of the brace-delimited branches, for security reasons. | |
8284 | ||
8285 | ||
8286 | 11.1 Literal text in expanded strings | |
8287 | ------------------------------------- | |
8288 | ||
8289 | An uninterpreted dollar can be included in an expanded string by putting a | |
8290 | backslash in front of it. A backslash can be used to prevent any special | |
8291 | character being treated specially in an expansion, including backslash itself. | |
8292 | If the string appears in quotes in the configuration file, two backslashes are | |
8293 | required because the quotes themselves cause interpretation of backslashes when | |
2813c06e | 8294 | the string is read in (see section 6.17). |
420a0d19 CE |
8295 | |
8296 | A portion of the string can specified as non-expandable by placing it between | |
8297 | two occurrences of "\N". This is particularly useful for protecting regular | |
8298 | expressions, which often contain backslashes and dollar signs. For example: | |
8299 | ||
8300 | deny senders = \N^\d{8}[a-z]@some\.site\.example$\N | |
8301 | ||
8302 | On encountering the first "\N", the expander copies subsequent characters | |
8303 | without interpretation until it reaches the next "\N" or the end of the string. | |
8304 | ||
8305 | ||
8306 | 11.2 Character escape sequences in expanded strings | |
8307 | --------------------------------------------------- | |
8308 | ||
8309 | A backslash followed by one of the letters "n", "r", or "t" in an expanded | |
8310 | string is recognized as an escape sequence for the character newline, carriage | |
8311 | return, or tab, respectively. A backslash followed by up to three octal digits | |
8312 | is recognized as an octal encoding for a single character, and a backslash | |
8313 | followed by "x" and up to two hexadecimal digits is a hexadecimal encoding. | |
8314 | ||
8315 | These escape sequences are also recognized in quoted strings when they are read | |
8316 | in. Their interpretation in expansions as well is useful for unquoted strings, | |
8317 | and for other cases such as looked-up strings that are then expanded. | |
8318 | ||
8319 | ||
8320 | 11.3 Testing string expansions | |
8321 | ------------------------------ | |
8322 | ||
8323 | Many expansions can be tested by calling Exim with the -be option. This takes | |
8324 | the command arguments, or lines from the standard input if there are no | |
8325 | arguments, runs them through the string expansion code, and writes the results | |
8326 | to the standard output. Variables based on configuration values are set up, but | |
8327 | since no message is being processed, variables such as $local_part have no | |
8328 | value. Nevertheless the -be option can be useful for checking out file and | |
8329 | database lookups, and the use of expansion operators such as sg, substr and | |
8330 | nhash. | |
8331 | ||
8332 | Exim gives up its root privilege when it is called with the -be option, and | |
8333 | instead runs under the uid and gid it was called with, to prevent users from | |
8334 | using -be for reading files to which they do not have access. | |
8335 | ||
8336 | If you want to test expansions that include variables whose values are taken | |
8337 | from a message, there are two other options that can be used. The -bem option | |
8338 | is like -be except that it is followed by a file name. The file is read as a | |
8339 | message before doing the test expansions. For example: | |
8340 | ||
8341 | exim -bem /tmp/test.message '$h_subject:' | |
8342 | ||
8343 | The -Mset option is used in conjunction with -be and is followed by an Exim | |
8344 | message identifier. For example: | |
8345 | ||
8346 | exim -be -Mset 1GrA8W-0004WS-LQ '$recipients' | |
8347 | ||
8348 | This loads the message from Exim's spool before doing the test expansions, and | |
8349 | is therefore restricted to admin users. | |
8350 | ||
8351 | ||
8352 | 11.4 Forced expansion failure | |
8353 | ----------------------------- | |
8354 | ||
8355 | A number of expansions that are described in the following section have | |
8356 | alternative "true" and "false" substrings, enclosed in brace characters (which | |
8357 | are sometimes called "curly brackets"). Which of the two strings is used | |
8358 | depends on some condition that is evaluated as part of the expansion. If, | |
8359 | instead of a "false" substring, the word "fail" is used (not in braces), the | |
8360 | entire string expansion fails in a way that can be detected by the code that | |
8361 | requested the expansion. This is called "forced expansion failure", and its | |
8362 | consequences depend on the circumstances. In some cases it is no different from | |
8363 | any other expansion failure, but in others a different action may be taken. | |
8364 | Such variations are mentioned in the documentation of the option that is being | |
8365 | expanded. | |
8366 | ||
8367 | ||
8368 | 11.5 Expansion items | |
8369 | -------------------- | |
8370 | ||
8371 | The following items are recognized in expanded strings. White space may be used | |
8372 | between sub-items that are keywords or substrings enclosed in braces inside an | |
8373 | outer set of braces, to improve readability. Warning: Within braces, white | |
8374 | space is significant. | |
8375 | ||
8376 | $<variable name> or ${<variable name>} | |
8377 | ||
8378 | Substitute the contents of the named variable, for example: | |
8379 | ||
8380 | $local_part | |
8381 | ${domain} | |
8382 | ||
8383 | The second form can be used to separate the name from subsequent | |
8384 | alphanumeric characters. This form (using braces) is available only for | |
8385 | variables; it does not apply to message headers. The names of the variables | |
8386 | are given in section 11.9 below. If the name of a non-existent variable is | |
8387 | given, the expansion fails. | |
8388 | ||
8389 | ${<op>:<string>} | |
8390 | ||
8391 | The string is first itself expanded, and then the operation specified by < | |
8392 | op> is applied to it. For example: | |
8393 | ||
8394 | ${lc:$local_part} | |
8395 | ||
8396 | The string starts with the first character after the colon, which may be | |
8397 | leading white space. A list of operators is given in section 11.6 below. | |
8398 | The operator notation is used for simple expansion items that have just one | |
8399 | argument, because it reduces the number of braces and therefore makes the | |
8400 | string easier to understand. | |
8401 | ||
8402 | $bheader_<header name>: or $bh_<header name>: | |
8403 | ||
8404 | This item inserts "basic" header lines. It is described with the header | |
8405 | expansion item below. | |
8406 | ||
8407 | ${acl{<name>}{<arg>}...} | |
8408 | ||
8409 | The name and zero to nine argument strings are first expanded separately. | |
8410 | The expanded arguments are assigned to the variables $acl_arg1 to $acl_arg9 | |
8411 | in order. Any unused are made empty. The variable $acl_narg is set to the | |
2813c06e | 8412 | number of arguments. The named ACL (see chapter 43) is called and may use |
420a0d19 CE |
8413 | the variables; if another acl expansion is used the values are restored |
8414 | after it returns. If the ACL sets a value using a "message =" modifier and | |
8415 | returns accept or deny, the value becomes the result of the expansion. If | |
8416 | no message is set and the ACL returns accept or deny the expansion result | |
8417 | is an empty string. If the ACL returns defer the result is a forced-fail. | |
8418 | Otherwise the expansion fails. | |
8419 | ||
8420 | ${certextract{<field>}{<certificate>}{<string2>}{<string3>}} | |
8421 | ||
8422 | The <certificate> must be a variable of type certificate. The field name is | |
2813c06e | 8423 | expanded and used to retrieve the relevant field from the certificate. |
420a0d19 CE |
8424 | Supported fields are: |
8425 | ||
8426 | version | |
8427 | serial_number | |
8428 | subject RFC4514 DN | |
8429 | issuer RFC4514 DN | |
8430 | notbefore time | |
8431 | notafter time | |
8432 | sig_algorithm | |
8433 | signature | |
8434 | subj_altname tagged list | |
8435 | ocsp_uri list | |
8436 | crl_uri list | |
8437 | ||
8438 | If the field is found, <string2> is expanded, and replaces the whole item; | |
8439 | otherwise <string3> is used. During the expansion of <string2> the variable | |
8440 | $value contains the value that has been extracted. Afterwards, it is | |
8441 | restored to any previous value it might have had. | |
8442 | ||
8443 | If {<string3>} is omitted, the item is replaced by an empty string if the | |
8444 | key is not found. If {<string2>} is also omitted, the value that was | |
8445 | extracted is used. | |
8446 | ||
8447 | Some field names take optional modifiers, appended and separated by commas. | |
8448 | ||
8449 | The field selectors marked as "RFC4514" above output a Distinguished Name | |
8450 | string which is not quite parseable by Exim as a comma-separated tagged | |
2813c06e | 8451 | list (the exceptions being elements containing commas). RDN elements of a |
420a0d19 CE |
8452 | single type may be selected by a modifier of the type label; if so the |
8453 | expansion result is a list (newline-separated by default). The separator | |
2813c06e | 8454 | may be changed by another modifier of a right angle-bracket followed |
420a0d19 CE |
8455 | immediately by the new separator. Recognised RDN type labels include "CN", |
8456 | "O", "OU" and "DC". | |
8457 | ||
2813c06e CE |
8458 | The field selectors marked as "time" above take an optional modifier of |
8459 | "int" for which the result is the number of seconds since epoch. Otherwise | |
8460 | the result is a human-readable string in the timezone selected by the main | |
8461 | "timezone" option. | |
420a0d19 CE |
8462 | |
8463 | The field selectors marked as "list" above return a list, newline-separated | |
8464 | by default, (embedded separator characters in elements are doubled). The | |
8465 | separator may be changed by a modifier of a right angle-bracket followed | |
8466 | immediately by the new separator. | |
8467 | ||
8468 | The field selectors marked as "tagged" above prefix each list element with | |
8469 | a type string and an equals sign. Elements of only one type may be selected | |
2813c06e | 8470 | by a modifier which is one of "dns", "uri" or "mail"; if so the element |
420a0d19 CE |
8471 | tags are omitted. |
8472 | ||
8473 | If not otherwise noted field values are presented in human-readable form. | |
8474 | ||
8475 | ${dlfunc{<file>}{<function>}{<arg>}{<arg>}...} | |
8476 | ||
8477 | This expansion dynamically loads and then calls a locally-written C | |
8478 | function. This functionality is available only if Exim is compiled with | |
8479 | ||
8480 | EXPAND_DLFUNC=yes | |
8481 | ||
8482 | set in Local/Makefile. Once loaded, Exim remembers the dynamically loaded | |
8483 | object so that it doesn't reload the same object file in the same Exim | |
8484 | process (but of course Exim does start new processes frequently). | |
8485 | ||
8486 | There may be from zero to eight arguments to the function. When compiling a | |
8487 | local function that is to be called in this way, local_scan.h should be | |
8488 | included. The Exim variables and functions that are defined by that API are | |
8489 | also available for dynamically loaded functions. The function itself must | |
8490 | have the following type: | |
8491 | ||
8492 | int dlfunction(uschar **yield, int argc, uschar *argv[]) | |
8493 | ||
8494 | Where "uschar" is a typedef for "unsigned char" in local_scan.h. The | |
8495 | function should return one of the following values: | |
8496 | ||
8497 | "OK": Success. The string that is placed in the variable yield is put into | |
8498 | the expanded string that is being built. | |
8499 | ||
8500 | "FAIL": A non-forced expansion failure occurs, with the error message taken | |
8501 | from yield, if it is set. | |
8502 | ||
8503 | "FAIL_FORCED": A forced expansion failure occurs, with the error message | |
8504 | taken from yield if it is set. | |
8505 | ||
8506 | "ERROR": Same as "FAIL", except that a panic log entry is written. | |
8507 | ||
8508 | When compiling a function that is to be used in this way with gcc, you need | |
8509 | to add -shared to the gcc command. Also, in the Exim build-time | |
8510 | configuration, you must add -export-dynamic to EXTRALIBS. | |
8511 | ||
2813c06e CE |
8512 | ${env{<key>}{<string1>}{<string2>}} |
8513 | ||
8514 | The key is first expanded separately, and leading and trailing white space | |
8515 | removed. This is then searched for as a name in the environment. If a | |
8516 | variable is found then its value is placed in $value and <string1> is | |
8517 | expanded, otherwise <string2> is expanded. | |
8518 | ||
8519 | Instead of {<string2>} the word "fail" (not in curly brackets) can appear, | |
8520 | for example: | |
8521 | ||
8522 | ${env{USER}{$value} fail } | |
8523 | ||
8524 | This forces an expansion failure (see section 11.4); {<string1>} must be | |
8525 | present for "fail" to be recognized. | |
8526 | ||
8527 | If {<string2>} is omitted an empty string is substituted on search failure. | |
8528 | If {<string1>} is omitted the search result is substituted on search | |
8529 | success. | |
8530 | ||
8531 | The environment is adjusted by the keep_environment and add_environment | |
8532 | main section options. | |
8533 | ||
420a0d19 CE |
8534 | ${extract{<key>}{<string1>}{<string2>}{<string3>}} |
8535 | ||
8536 | The key and <string1> are first expanded separately. Leading and trailing | |
8537 | white space is removed from the key (but not from any of the strings). The | |
2813c06e CE |
8538 | key must not be empty and must not consist entirely of digits. The expanded |
8539 | <string1> must be of the form: | |
420a0d19 CE |
8540 | |
8541 | <key1> = <value1> <key2> = <value2> ... | |
8542 | ||
8543 | where the equals signs and spaces (but not both) are optional. If any of | |
8544 | the values contain white space, they must be enclosed in double quotes, and | |
8545 | any values that are enclosed in double quotes are subject to escape | |
2813c06e | 8546 | processing as described in section 6.17. The expanded <string1> is searched |
420a0d19 CE |
8547 | for the value that corresponds to the key. The search is case-insensitive. |
8548 | If the key is found, <string2> is expanded, and replaces the whole item; | |
8549 | otherwise <string3> is used. During the expansion of <string2> the variable | |
8550 | $value contains the value that has been extracted. Afterwards, it is | |
8551 | restored to any previous value it might have had. | |
8552 | ||
8553 | If {<string3>} is omitted, the item is replaced by an empty string if the | |
8554 | key is not found. If {<string2>} is also omitted, the value that was | |
8555 | extracted is used. Thus, for example, these two expansions are identical, | |
8556 | and yield "2001": | |
8557 | ||
8558 | ${extract{gid}{uid=1984 gid=2001}} | |
8559 | ${extract{gid}{uid=1984 gid=2001}{$value}} | |
8560 | ||
8561 | Instead of {<string3>} the word "fail" (not in curly brackets) can appear, | |
8562 | for example: | |
8563 | ||
8564 | ${extract{Z}{A=... B=...}{$value} fail } | |
8565 | ||
8566 | This forces an expansion failure (see section 11.4); {<string2>} must be | |
8567 | present for "fail" to be recognized. | |
8568 | ||
8569 | ${extract{<number>}{<separators>}{<string1>}{<string2>}{<string3>}} | |
8570 | ||
8571 | The <number> argument must consist entirely of decimal digits, apart from | |
8572 | leading and trailing white space, which is ignored. This is what | |
8573 | distinguishes this form of extract from the previous kind. It behaves in | |
8574 | the same way, except that, instead of extracting a named field, it extracts | |
8575 | from <string1> the field whose number is given as the first argument. You | |
8576 | can use $value in <string2> or "fail" instead of <string3> as before. | |
8577 | ||
8578 | The fields in the string are separated by any one of the characters in the | |
8579 | separator string. These may include space or tab characters. The first | |
8580 | field is numbered one. If the number is negative, the fields are counted | |
8581 | from the end of the string, with the rightmost one numbered -1. If the | |
8582 | number given is zero, the entire string is returned. If the modulus of the | |
8583 | number is greater than the number of fields in the string, the result is | |
8584 | the expansion of <string3>, or the empty string if <string3> is not | |
8585 | provided. For example: | |
8586 | ||
8587 | ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}} | |
8588 | ||
8589 | yields "42", and | |
8590 | ||
8591 | ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}} | |
8592 | ||
8593 | yields "99". Two successive separators mean that the field between them is | |
8594 | empty (for example, the fifth field above). | |
8595 | ||
8596 | ${filter{<string>}{<condition>}} | |
8597 | ||
8598 | After expansion, <string> is interpreted as a list, colon-separated by | |
8599 | default, but the separator can be changed in the usual way. For each item | |
8600 | in this list, its value is place in $item, and then the condition is | |
8601 | evaluated. If the condition is true, $item is added to the output as an | |
8602 | item in a new list; if the condition is false, the item is discarded. The | |
8603 | separator used for the output list is the same as the one used for the | |
8604 | input, but a separator setting is not included in the output. For example: | |
8605 | ||
8606 | ${filter{a:b:c}{!eq{$item}{b}} | |
8607 | ||
8608 | yields "a:c". At the end of the expansion, the value of $item is restored | |
8609 | to what it was before. See also the map and reduce expansion items. | |
8610 | ||
8611 | ${hash{<string1>}{<string2>}{<string3>}} | |
8612 | ||
8613 | This is a textual hashing function, and was the first to be implemented in | |
8614 | early versions of Exim. In current releases, there are other hashing | |
8615 | functions (numeric, MD5, and SHA-1), which are described below. | |
8616 | ||
8617 | The first two strings, after expansion, must be numbers. Call them <m> and | |
8618 | <n>. If you are using fixed values for these numbers, that is, if <string1> | |
8619 | and <string2> do not change when they are expanded, you can use the simpler | |
8620 | operator notation that avoids some of the braces: | |
8621 | ||
8622 | ${hash_<n>_<m>:<string>} | |
8623 | ||
8624 | The second number is optional (in both notations). If <n> is greater than | |
8625 | or equal to the length of the string, the expansion item returns the | |
8626 | string. Otherwise it computes a new string of length <n> by applying a | |
8627 | hashing function to the string. The new string consists of characters taken | |
8628 | from the first <m> characters of the string | |
8629 | ||
8630 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789 | |
8631 | ||
8632 | If <m> is not present the value 26 is used, so that only lower case letters | |
8633 | appear. For example: | |
8634 | ||
8635 | $hash{3}{monty}} yields jmg | |
8636 | $hash{5}{monty}} yields monty | |
8637 | $hash{4}{62}{monty python}} yields fbWx | |
8638 | ||
8639 | $header_<header name>: or $h_<header name>:, $bheader_<header name>: or $bh_< | |
8640 | header name>:, $rheader_<header name>: or $rh_<header name>: | |
8641 | ||
8642 | Substitute the contents of the named message header line, for example | |
8643 | ||
8644 | $header_reply-to: | |
8645 | ||
8646 | The newline that terminates a header line is not included in the expansion, | |
8647 | but internal newlines (caused by splitting the header line over several | |
8648 | physical lines) may be present. | |
8649 | ||
8650 | The difference between rheader, bheader, and header is in the way the data | |
8651 | in the header line is interpreted. | |
8652 | ||
2813c06e | 8653 | + rheader gives the original "raw" content of the header line, with no |
420a0d19 CE |
8654 | processing at all, and without the removal of leading and trailing |
8655 | white space. | |
8656 | ||
2813c06e | 8657 | + bheader removes leading and trailing white space, and then decodes |
420a0d19 CE |
8658 | base64 or quoted-printable MIME "words" within the header text, but |
8659 | does no character set translation. If decoding of what looks | |
8660 | superficially like a MIME "word" fails, the raw string is returned. If | |
8661 | decoding produces a binary zero character, it is replaced by a question | |
8662 | mark - this is what Exim does for binary zeros that are actually | |
8663 | received in header lines. | |
8664 | ||
2813c06e | 8665 | + header tries to translate the string as decoded by bheader to a |
420a0d19 CE |
8666 | standard character set. This is an attempt to produce the same string |
8667 | as would be displayed on a user's MUA. If translation fails, the | |
8668 | bheader string is returned. Translation is attempted only on operating | |
8669 | systems that support the iconv() function. This is indicated by the | |
8670 | compile-time macro HAVE_ICONV in a system Makefile or in Local/Makefile | |
8671 | . | |
8672 | ||
8673 | In a filter file, the target character set for header can be specified by a | |
8674 | command of the following form: | |
8675 | ||
8676 | headers charset "UTF-8" | |
8677 | ||
8678 | This command affects all references to $h_ (or $header_) expansions in | |
8679 | subsequently obeyed filter commands. In the absence of this command, the | |
8680 | target character set in a filter is taken from the setting of the | |
8681 | headers_charset option in the runtime configuration. The value of this | |
8682 | option defaults to the value of HEADERS_CHARSET in Local/Makefile. The | |
8683 | ultimate default is ISO-8859-1. | |
8684 | ||
8685 | Header names follow the syntax of RFC 2822, which states that they may | |
8686 | contain any printing characters except space and colon. Consequently, curly | |
8687 | brackets do not terminate header names, and should not be used to enclose | |
8688 | them as if they were variables. Attempting to do so causes a syntax error. | |
8689 | ||
8690 | Only header lines that are common to all copies of a message are visible to | |
8691 | this mechanism. These are the original header lines that are received with | |
8692 | the message, and any that are added by an ACL statement or by a system | |
8693 | filter. Header lines that are added to a particular copy of a message by a | |
8694 | router or transport are not accessible. | |
8695 | ||
2813c06e CE |
8696 | For incoming SMTP messages, no header lines are visible in |
8697 | ||
8698 | ACLs that are obeyed before the data phase completes, | |
8699 | ||
8700 | because the header structure is not set up until the message is received. | |
8701 | They are visible in DKIM, PRDR and DATA ACLs. Header lines that are added | |
8702 | in a RCPT ACL (for example) are saved until the message's incoming header | |
8703 | lines are available, at which point they are added. | |
8704 | ||
8705 | When any of the above ACLs ar | |
8706 | ||
8707 | running, however, header lines added by earlier ACLs are visible. | |
420a0d19 CE |
8708 | |
8709 | Upper case and lower case letters are synonymous in header names. If the | |
8710 | following character is white space, the terminating colon may be omitted, | |
8711 | but this is not recommended, because you may then forget it when it is | |
2813c06e CE |
8712 | needed. When white space terminates the header name, this white space is |
8713 | included in the expanded string. If the message does not contain the given | |
8714 | header, the expansion item is replaced by an empty string. (See the def | |
8715 | condition in section 11.7 for a means of testing for the existence of a | |
8716 | header.) | |
420a0d19 CE |
8717 | |
8718 | If there is more than one header with the same name, they are all | |
8719 | concatenated to form the substitution string, up to a maximum length of | |
8720 | 64K. Unless rheader is being used, leading and trailing white space is | |
8721 | removed from each header before concatenation, and a completely empty | |
8722 | header is ignored. A newline character is then inserted between non-empty | |
8723 | headers, but there is no newline at the very end. For the header and | |
8724 | bheader expansion, for those headers that contain lists of addresses, a | |
8725 | comma is also inserted at the junctions between headers. This does not | |
8726 | happen for the rheader expansion. | |
8727 | ||
8728 | ${hmac{<hashname>}{<secret>}{<string>}} | |
8729 | ||
8730 | This function uses cryptographic hashing (either MD5 or SHA-1) to convert a | |
8731 | shared secret and some text into a message authentication code, as | |
8732 | specified in RFC 2104. This differs from "${md5:secret_text...}" or "$ | |
8733 | {sha1:secret_text...}" in that the hmac step adds a signature to the | |
8734 | cryptographic hash, allowing for authentication that is not possible with | |
8735 | MD5 or SHA-1 alone. The hash name must expand to either "md5" or "sha1" at | |
8736 | present. For example: | |
8737 | ||
8738 | ${hmac{md5}{somesecret}{$primary_hostname $tod_log}} | |
8739 | ||
8740 | For the hostname mail.example.com and time 2002-10-17 11:30:59, this | |
8741 | produces: | |
8742 | ||
8743 | dd97e3ba5d1a61b5006108f8c8252953 | |
8744 | ||
8745 | As an example of how this might be used, you might put in the main part of | |
8746 | an Exim configuration: | |
8747 | ||
8748 | SPAMSCAN_SECRET=cohgheeLei2thahw | |
8749 | ||
8750 | In a router or a transport you could then have: | |
8751 | ||
8752 | headers_add = \ | |
8753 | X-Spam-Scanned: ${primary_hostname} ${message_exim_id} \ | |
8754 | ${hmac{md5}{SPAMSCAN_SECRET}\ | |
8755 | {${primary_hostname},${message_exim_id},$h_message-id:}} | |
8756 | ||
8757 | Then given a message, you can check where it was scanned by looking at the | |
8758 | X-Spam-Scanned: header line. If you know the secret, you can check that | |
8759 | this header line is authentic by recomputing the authentication code from | |
8760 | the host name, message ID and the Message-id: header line. This can be done | |
8761 | using Exim's -be option, or by other means, for example by using the | |
8762 | hmac_md5_hex() function in Perl. | |
8763 | ||
8764 | ${if <condition> {<string1>}{<string2>}} | |
8765 | ||
8766 | If <condition> is true, <string1> is expanded and replaces the whole item; | |
8767 | otherwise <string2> is used. The available conditions are described in | |
8768 | section 11.7 below. For example: | |
8769 | ||
8770 | ${if eq {$local_part}{postmaster} {yes}{no} } | |
8771 | ||
8772 | The second string need not be present; if it is not and the condition is | |
8773 | not true, the item is replaced with nothing. Alternatively, the word "fail" | |
8774 | may be present instead of the second string (without any curly brackets). | |
8775 | In this case, the expansion is forced to fail if the condition is not true | |
8776 | (see section 11.4). | |
8777 | ||
8778 | If both strings are omitted, the result is the string "true" if the | |
8779 | condition is true, and the empty string if the condition is false. This | |
8780 | makes it less cumbersome to write custom ACL and router conditions. For | |
8781 | example, instead of | |
8782 | ||
8783 | condition = ${if >{$acl_m4}{3}{true}{false}} | |
8784 | ||
8785 | you can use | |
8786 | ||
8787 | condition = ${if >{$acl_m4}{3}} | |
8788 | ||
2813c06e CE |
8789 | ${imapfolder{<foldername>}} |
8790 | ||
8791 | This item converts a (possibly multilevel, or with non-ASCII characters) | |
8792 | folder specification to a Maildir name for filesystem use. For information | |
8793 | on internationalisation support see 59.2. | |
8794 | ||
420a0d19 CE |
8795 | ${length{<string1>}{<string2>}} |
8796 | ||
8797 | The length item is used to extract the initial portion of a string. Both | |
8798 | strings are expanded, and the first one must yield a number, <n>, say. If | |
8799 | you are using a fixed value for the number, that is, if <string1> does not | |
8800 | change when expanded, you can use the simpler operator notation that avoids | |
8801 | some of the braces: | |
8802 | ||
8803 | ${length_<n>:<string>} | |
8804 | ||
8805 | The result of this item is either the first <n> characters or the whole of | |
8806 | <string2>, whichever is the shorter. Do not confuse length with strlen, | |
8807 | which gives the length of a string. | |
8808 | ||
8809 | ${listextract{<number>}{<string1>}{<string2>}{<string3>}} | |
8810 | ||
8811 | The <number> argument must consist entirely of decimal digits, apart from | |
8812 | an optional leading minus, and leading and trailing white space (which is | |
8813 | ignored). | |
8814 | ||
8815 | After expansion, <string1> is interpreted as a list, colon-separated by | |
8816 | default, but the separator can be changed in the usual way. | |
8817 | ||
8818 | The first field of the list is numbered one. If the number is negative, the | |
8819 | fields are counted from the end of the list, with the rightmost one | |
8820 | numbered -1. The numbered element of the list is extracted and placed in | |
8821 | $value, then <string2> is expanded as the result. | |
8822 | ||
8823 | If the modulus of the number is zero or greater than the number of fields | |
8824 | in the string, the result is the expansion of <string3>. | |
8825 | ||
8826 | For example: | |
8827 | ||
8828 | ${listextract{2}{x:42:99}} | |
8829 | ||
8830 | yields "42", and | |
8831 | ||
8832 | ${listextract{-3}{<, x,42,99,& Mailer,,/bin/bash}{result: $value}} | |
8833 | ||
2813c06e | 8834 | yields "result: 42". |
420a0d19 CE |
8835 | |
8836 | If {<string3>} is omitted, an empty string is used for string3. If {< | |
8837 | string2>} is also omitted, the value that was extracted is used. You can | |
8838 | use "fail" instead of {<string3>} as in a string extract. | |
8839 | ||
8840 | ${lookup{<key>} <search type> {<file>} {<string1>} {<string2>}} | |
8841 | ||
8842 | This is the first of one of two different types of lookup item, which are | |
8843 | both described in the next item. | |
8844 | ||
8845 | ${lookup <search type> {<query>} {<string1>} {<string2>}} | |
8846 | ||
8847 | The two forms of lookup item specify data lookups in files and databases, | |
8848 | as discussed in chapter 9. The first form is used for single-key lookups, | |
8849 | and the second is used for query-style lookups. The <key>, <file>, and < | |
8850 | query> strings are expanded before use. | |
8851 | ||
8852 | If there is any white space in a lookup item which is part of a filter | |
8853 | command, a retry or rewrite rule, a routing rule for the manualroute | |
8854 | router, or any other place where white space is significant, the lookup | |
8855 | item must be enclosed in double quotes. The use of data lookups in users' | |
8856 | filter files may be locked out by the system administrator. | |
8857 | ||
8858 | If the lookup succeeds, <string1> is expanded and replaces the entire item. | |
8859 | During its expansion, the variable $value contains the data returned by the | |
8860 | lookup. Afterwards it reverts to the value it had previously (at the outer | |
8861 | level it is empty). If the lookup fails, <string2> is expanded and replaces | |
8862 | the entire item. If {<string2>} is omitted, the replacement is the empty | |
8863 | string on failure. If <string2> is provided, it can itself be a nested | |
8864 | lookup, thus providing a mechanism for looking up a default value when the | |
8865 | original lookup fails. | |
8866 | ||
8867 | If a nested lookup is used as part of <string1>, $value contains the data | |
8868 | for the outer lookup while the parameters of the second lookup are | |
8869 | expanded, and also while <string2> of the second lookup is expanded, should | |
8870 | the second lookup fail. Instead of {<string2>} the word "fail" can appear, | |
8871 | and in this case, if the lookup fails, the entire expansion is forced to | |
8872 | fail (see section 11.4). If both {<string1>} and {<string2>} are omitted, | |
8873 | the result is the looked up value in the case of a successful lookup, and | |
8874 | nothing in the case of failure. | |
8875 | ||
8876 | For single-key lookups, the string "partial" is permitted to precede the | |
8877 | search type in order to do partial matching, and * or *@ may follow a | |
8878 | search type to request default lookups if the key does not match (see | |
8879 | sections 9.6 and 9.7 for details). | |
8880 | ||
8881 | If a partial search is used, the variables $1 and $2 contain the wild and | |
8882 | non-wild parts of the key during the expansion of the replacement text. | |
8883 | They return to their previous values at the end of the lookup item. | |
8884 | ||
8885 | This example looks up the postmaster alias in the conventional alias file: | |
8886 | ||
8887 | ${lookup {postmaster} lsearch {/etc/aliases} {$value}} | |
8888 | ||
8889 | This example uses NIS+ to look up the full name of the user corresponding | |
8890 | to the local part of an address, forcing the expansion to fail if it is not | |
8891 | found: | |
8892 | ||
8893 | ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \ | |
8894 | {$value}fail} | |
8895 | ||
8896 | ${map{<string1>}{<string2>}} | |
8897 | ||
8898 | After expansion, <string1> is interpreted as a list, colon-separated by | |
8899 | default, but the separator can be changed in the usual way. For each item | |
8900 | in this list, its value is place in $item, and then <string2> is expanded | |
8901 | and added to the output as an item in a new list. The separator used for | |
8902 | the output list is the same as the one used for the input, but a separator | |
8903 | setting is not included in the output. For example: | |
8904 | ||
8905 | ${map{a:b:c}{[$item]}} ${map{<- x-y-z}{($item)}} | |
8906 | ||
8907 | expands to "[a]:[b]:[c] (x)-(y)-(z)". At the end of the expansion, the | |
8908 | value of $item is restored to what it was before. See also the filter and | |
8909 | reduce expansion items. | |
8910 | ||
8911 | ${nhash{<string1>}{<string2>}{<string3>}} | |
8912 | ||
8913 | The three strings are expanded; the first two must yield numbers. Call them | |
8914 | <n> and <m>. If you are using fixed values for these numbers, that is, if < | |
8915 | string1> and <string2> do not change when they are expanded, you can use | |
8916 | the simpler operator notation that avoids some of the braces: | |
8917 | ||
8918 | ${nhash_<n>_<m>:<string>} | |
8919 | ||
8920 | The second number is optional (in both notations). If there is only one | |
8921 | number, the result is a number in the range 0-<n>-1. Otherwise, the string | |
8922 | is processed by a div/mod hash function that returns two numbers, separated | |
8923 | by a slash, in the ranges 0 to <n>-1 and 0 to <m>-1, respectively. For | |
8924 | example, | |
8925 | ||
8926 | ${nhash{8}{64}{supercalifragilisticexpialidocious}} | |
8927 | ||
8928 | returns the string "6/33". | |
8929 | ||
8930 | ${perl{<subroutine>}{<arg>}{<arg>}...} | |
8931 | ||
8932 | This item is available only if Exim has been built to include an embedded | |
8933 | Perl interpreter. The subroutine name and the arguments are first | |
8934 | separately expanded, and then the Perl subroutine is called with those | |
8935 | arguments. No additional arguments need be given; the maximum number | |
8936 | permitted, including the name of the subroutine, is nine. | |
8937 | ||
8938 | The return value of the subroutine is inserted into the expanded string, | |
8939 | unless the return value is undef. In that case, the expansion fails in the | |
8940 | same way as an explicit "fail" on a lookup item. The return value is a | |
8941 | scalar. Whatever you return is evaluated in a scalar context. For example, | |
8942 | if you return the name of a Perl vector, the return value is the size of | |
8943 | the vector, not its contents. | |
8944 | ||
8945 | If the subroutine exits by calling Perl's die function, the expansion fails | |
8946 | with the error message that was passed to die. More details of the embedded | |
8947 | Perl facility are given in chapter 12. | |
8948 | ||
8949 | The redirect router has an option called forbid_filter_perl which locks out | |
8950 | the use of this expansion item in filter files. | |
8951 | ||
8952 | ${prvs{<address>}{<secret>}{<keynumber>}} | |
8953 | ||
8954 | The first argument is a complete email address and the second is secret | |
8955 | keystring. The third argument, specifying a key number, is optional. If | |
8956 | absent, it defaults to 0. The result of the expansion is a prvs-signed | |
8957 | email address, to be typically used with the return_path option on an smtp | |
8958 | transport as part of a bounce address tag validation (BATV) scheme. For | |
2813c06e | 8959 | more discussion and an example, see section 43.51. |
420a0d19 CE |
8960 | |
8961 | ${prvscheck{<address>}{<secret>}{<string>}} | |
8962 | ||
8963 | This expansion item is the complement of the prvs item. It is used for | |
8964 | checking prvs-signed addresses. If the expansion of the first argument does | |
8965 | not yield a syntactically valid prvs-signed address, the whole item expands | |
8966 | to the empty string. When the first argument does expand to a syntactically | |
8967 | valid prvs-signed address, the second argument is expanded, with the | |
8968 | prvs-decoded version of the address and the key number extracted from the | |
8969 | address in the variables $prvscheck_address and $prvscheck_keynum, | |
8970 | respectively. | |
8971 | ||
8972 | These two variables can be used in the expansion of the second argument to | |
8973 | retrieve the secret. The validity of the prvs-signed address is then | |
8974 | checked against the secret. The result is stored in the variable | |
8975 | $prvscheck_result, which is empty for failure or "1" for success. | |
8976 | ||
8977 | The third argument is optional; if it is missing, it defaults to an empty | |
8978 | string. This argument is now expanded. If the result is an empty string, | |
8979 | the result of the expansion is the decoded version of the address. This is | |
8980 | the case whether or not the signature was valid. Otherwise, the result of | |
8981 | the expansion is the expansion of the third argument. | |
8982 | ||
8983 | All three variables can be used in the expansion of the third argument. | |
8984 | However, once the expansion is complete, only $prvscheck_result remains | |
2813c06e | 8985 | set. For more discussion and an example, see section 43.51. |
420a0d19 CE |
8986 | |
8987 | ${readfile{<file name>}{<eol string>}} | |
8988 | ||
8989 | The file name and end-of-line string are first expanded separately. The | |
8990 | file is then read, and its contents replace the entire item. All newline | |
8991 | characters in the file are replaced by the end-of-line string if it is | |
8992 | present. Otherwise, newlines are left in the string. String expansion is | |
8993 | not applied to the contents of the file. If you want this, you must wrap | |
8994 | the item in an expand operator. If the file cannot be read, the string | |
8995 | expansion fails. | |
8996 | ||
8997 | The redirect router has an option called forbid_filter_readfile which locks | |
8998 | out the use of this expansion item in filter files. | |
8999 | ||
9000 | ${readsocket{<name>}{<request>}{<timeout>}{<eol string>}{<fail string>}} | |
9001 | ||
2813c06e CE |
9002 | This item inserts data from a Unix domain or TCP socket into the expanded |
9003 | string. The minimal way of using it uses just two arguments, as in these | |
9004 | examples: | |
420a0d19 CE |
9005 | |
9006 | ${readsocket{/socket/name}{request string}} | |
9007 | ${readsocket{inet:some.host:1234}{request string}} | |
9008 | ||
9009 | For a Unix domain socket, the first substring must be the path to the | |
9010 | socket. For an Internet socket, the first substring must contain "inet:" | |
9011 | followed by a host name or IP address, followed by a colon and a port, | |
9012 | which can be a number or the name of a TCP port in /etc/services. An IP | |
9013 | address may optionally be enclosed in square brackets. This is best for | |
9014 | IPv6 addresses. For example: | |
9015 | ||
9016 | ${readsocket{inet:[::1]:1234}{request string}} | |
9017 | ||
9018 | Only a single host name may be given, but if looking it up yields more than | |
9019 | one IP address, they are each tried in turn until a connection is made. For | |
9020 | both kinds of socket, Exim makes a connection, writes the request string | |
2813c06e CE |
9021 | unless it is an empty string; and no terminating NUL is ever sent) and |
9022 | reads from the socket until an end-of-file is read. A timeout of 5 seconds | |
9023 | is applied. Additional, optional arguments extend what can be done. | |
9024 | Firstly, you can vary the timeout. For example: | |
420a0d19 CE |
9025 | |
9026 | ${readsocket{/socket/name}{request string}{3s}} | |
9027 | ||
9028 | A fourth argument allows you to change any newlines that are in the data | |
9029 | that is read, in the same way as for readfile (see above). This example | |
9030 | turns them into spaces: | |
9031 | ||
9032 | ${readsocket{inet:127.0.0.1:3294}{request string}{3s}{ }} | |
9033 | ||
9034 | As with all expansions, the substrings are expanded before the processing | |
9035 | happens. Errors in these sub-expansions cause the expansion to fail. In | |
9036 | addition, the following errors can occur: | |
9037 | ||
2813c06e | 9038 | + Failure to create a socket file descriptor; |
420a0d19 | 9039 | |
2813c06e | 9040 | + Failure to connect the socket; |
420a0d19 | 9041 | |
2813c06e | 9042 | + Failure to write the request string; |
420a0d19 | 9043 | |
2813c06e | 9044 | + Timeout on reading from the socket. |
420a0d19 CE |
9045 | |
9046 | By default, any of these errors causes the expansion to fail. However, if | |
9047 | you supply a fifth substring, it is expanded and used when any of the above | |
9048 | errors occurs. For example: | |
9049 | ||
9050 | ${readsocket{/socket/name}{request string}{3s}{\n}\ | |
9051 | {socket failure}} | |
9052 | ||
9053 | You can test for the existence of a Unix domain socket by wrapping this | |
9054 | expansion in "${if exists", but there is a race condition between that test | |
9055 | and the actual opening of the socket, so it is safer to use the fifth | |
9056 | argument if you want to be absolutely sure of avoiding an expansion error | |
9057 | for a non-existent Unix domain socket, or a failure to connect to an | |
9058 | Internet socket. | |
9059 | ||
9060 | The redirect router has an option called forbid_filter_readsocket which | |
9061 | locks out the use of this expansion item in filter files. | |
9062 | ||
9063 | ${reduce{<string1>}{<string2>}{<string3>}} | |
9064 | ||
9065 | This operation reduces a list to a single, scalar string. After expansion, | |
9066 | <string1> is interpreted as a list, colon-separated by default, but the | |
9067 | separator can be changed in the usual way. Then <string2> is expanded and | |
9068 | assigned to the $value variable. After this, each item in the <string1> | |
9069 | list is assigned to $item in turn, and <string3> is expanded for each of | |
9070 | them. The result of that expansion is assigned to $value before the next | |
9071 | iteration. When the end of the list is reached, the final value of $value | |
9072 | is added to the expansion output. The reduce expansion item can be used in | |
9073 | a number of ways. For example, to add up a list of numbers: | |
9074 | ||
9075 | ${reduce {<, 1,2,3}{0}{${eval:$value+$item}}} | |
9076 | ||
9077 | The result of that expansion would be "6". The maximum of a list of numbers | |
9078 | can be found: | |
9079 | ||
9080 | ${reduce {3:0:9:4:6}{0}{${if >{$item}{$value}{$item}{$value}}}} | |
9081 | ||
9082 | At the end of a reduce expansion, the values of $item and $value are | |
9083 | restored to what they were before. See also the filter and map expansion | |
9084 | items. | |
9085 | ||
9086 | $rheader_<header name>: or $rh_<header name>: | |
9087 | ||
9088 | This item inserts "raw" header lines. It is described with the header | |
9089 | expansion item above. | |
9090 | ||
9091 | ${run{<command> <args>}{<string1>}{<string2>}} | |
9092 | ||
9093 | The command and its arguments are first expanded as one string. The string | |
9094 | is split apart into individual arguments by spaces, and then the command is | |
9095 | run in a separate process, but under the same uid and gid. As in other | |
9096 | command executions from Exim, a shell is not used by default. If the | |
9097 | command requires a shell, you must explicitly code it. | |
9098 | ||
9099 | Since the arguments are split by spaces, when there is a variable expansion | |
9100 | which has an empty result, it will cause the situation that the argument | |
9101 | will simply be omitted when the program is actually executed by Exim. If | |
9102 | the script/program requires a specific number of arguments and the expanded | |
9103 | variable could possibly result in this empty expansion, the variable must | |
9104 | be quoted. This is more difficult if the expanded variable itself could | |
9105 | result in a string containing quotes, because it would interfere with the | |
9106 | quotes around the command arguments. A possible guard against this is to | |
9107 | wrap the variable in the sg operator to change any quote marks to some | |
9108 | other character. | |
9109 | ||
9110 | The standard input for the command exists, but is empty. The standard | |
9111 | output and standard error are set to the same file descriptor. If the | |
9112 | command succeeds (gives a zero return code) <string1> is expanded and | |
9113 | replaces the entire item; during this expansion, the standard output/error | |
9114 | from the command is in the variable $value. If the command fails, <string2 | |
9115 | >, if present, is expanded and used. Once again, during the expansion, the | |
9116 | standard output/error from the command is in the variable $value. | |
9117 | ||
9118 | If <string2> is absent, the result is empty. Alternatively, <string2> can | |
9119 | be the word "fail" (not in braces) to force expansion failure if the | |
9120 | command does not succeed. If both strings are omitted, the result is | |
9121 | contents of the standard output/error on success, and nothing on failure. | |
9122 | ||
9123 | The standard output/error of the command is put in the variable $value. In | |
9124 | this ACL example, the output of a command is logged for the admin to | |
9125 | troubleshoot: | |
9126 | ||
9127 | warn condition = ${run{/usr/bin/id}{yes}{no}} | |
9128 | log_message = Output of id: $value | |
9129 | ||
9130 | If the command requires shell idioms, such as the > redirect operator, the | |
9131 | shell must be invoked directly, such as with: | |
9132 | ||
9133 | ${run{/bin/bash -c "/usr/bin/id >/tmp/id"}{yes}{yes}} | |
9134 | ||
9135 | The return code from the command is put in the variable $runrc, and this | |
9136 | remains set afterwards, so in a filter file you can do things like this: | |
9137 | ||
9138 | if "${run{x y z}{}}$runrc" is 1 then ... | |
9139 | elif $runrc is 2 then ... | |
9140 | ... | |
9141 | endif | |
9142 | ||
9143 | If execution of the command fails (for example, the command does not | |
9144 | exist), the return code is 127 - the same code that shells use for | |
9145 | non-existent commands. | |
9146 | ||
9147 | Warning: In a router or transport, you cannot assume the order in which | |
9148 | option values are expanded, except for those preconditions whose order of | |
9149 | testing is documented. Therefore, you cannot reliably expect to set $runrc | |
9150 | by the expansion of one option, and use it in another. | |
9151 | ||
9152 | The redirect router has an option called forbid_filter_run which locks out | |
9153 | the use of this expansion item in filter files. | |
9154 | ||
9155 | ${sg{<subject>}{<regex>}{<replacement>}} | |
9156 | ||
9157 | This item works like Perl's substitution operator (s) with the global (/g) | |
9158 | option; hence its name. However, unlike the Perl equivalent, Exim does not | |
9159 | modify the subject string; instead it returns the modified string for | |
9160 | insertion into the overall expansion. The item takes three arguments: the | |
9161 | subject string, a regular expression, and a substitution string. For | |
9162 | example: | |
9163 | ||
9164 | ${sg{abcdefabcdef}{abc}{xyz}} | |
9165 | ||
9166 | yields "xyzdefxyzdef". Because all three arguments are expanded before use, | |
9167 | if any $ or \ characters are required in the regular expression or in the | |
9168 | substitution string, they have to be escaped. For example: | |
9169 | ||
9170 | ${sg{abcdef}{^(...)(...)\$}{\$2\$1}} | |
9171 | ||
9172 | yields "defabc", and | |
9173 | ||
9174 | ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}} | |
9175 | ||
9176 | yields "K1=A K4=D K3=C". Note the use of "\N" to protect the contents of | |
9177 | the regular expression from string expansion. | |
9178 | ||
2813c06e CE |
9179 | ${sort{<string>}{<comparator>}{<extractor>}} |
9180 | ||
9181 | After expansion, <string> is interpreted as a list, colon-separated by | |
9182 | default, but the separator can be changed in the usual way. The <comparator | |
9183 | > argument is interpreted as the operator of a two-argument expansion | |
9184 | condition. The numeric operators plus ge, gt, le, lt (and ~i variants) are | |
9185 | supported. The comparison should return true when applied to two values if | |
9186 | the first value should sort before the second value. The <extractor> | |
9187 | expansion is applied repeatedly to elements of the list, the element being | |
9188 | placed in $item, to give values for comparison. | |
9189 | ||
9190 | The item result is a sorted list, with the original list separator, of the | |
9191 | list elements (in full) of the original. | |
9192 | ||
9193 | Examples: | |
9194 | ||
9195 | ${sort{3:2:1:4}{<}{$item}} | |
9196 | ||
9197 | sorts a list of numbers, and | |
9198 | ||
9199 | ${sort {${lookup dnsdb{>:,,mx=example.com}}} {<} {${listextract{1}{<,$item}}}} | |
9200 | ||
9201 | will sort an MX lookup into priority order. | |
9202 | ||
420a0d19 CE |
9203 | ${substr{<string1>}{<string2>}{<string3>}} |
9204 | ||
9205 | The three strings are expanded; the first two must yield numbers. Call them | |
9206 | <n> and <m>. If you are using fixed values for these numbers, that is, if < | |
9207 | string1> and <string2> do not change when they are expanded, you can use | |
9208 | the simpler operator notation that avoids some of the braces: | |
9209 | ||
9210 | ${substr_<n>_<m>:<string>} | |
9211 | ||
9212 | The second number is optional (in both notations). If it is absent in the | |
9213 | simpler format, the preceding underscore must also be omitted. | |
9214 | ||
9215 | The substr item can be used to extract more general substrings than length. | |
9216 | The first number, <n>, is a starting offset, and <m> is the length | |
9217 | required. For example | |
9218 | ||
9219 | ${substr{3}{2}{$local_part}} | |
9220 | ||
9221 | If the starting offset is greater than the string length the result is the | |
9222 | null string; if the length plus starting offset is greater than the string | |
9223 | length, the result is the right-hand part of the string, starting from the | |
9224 | given offset. The first character in the string has offset zero. | |
9225 | ||
9226 | The substr expansion item can take negative offset values to count from the | |
9227 | right-hand end of its operand. The last character is offset -1, the | |
9228 | second-last is offset -2, and so on. Thus, for example, | |
9229 | ||
9230 | ${substr{-5}{2}{1234567}} | |
9231 | ||
9232 | yields "34". If the absolute value of a negative offset is greater than the | |
9233 | length of the string, the substring starts at the beginning of the string, | |
9234 | and the length is reduced by the amount of overshoot. Thus, for example, | |
9235 | ||
9236 | ${substr{-5}{2}{12}} | |
9237 | ||
9238 | yields an empty string, but | |
9239 | ||
9240 | ${substr{-3}{2}{12}} | |
9241 | ||
9242 | yields "1". | |
9243 | ||
9244 | When the second number is omitted from substr, the remainder of the string | |
9245 | is taken if the offset is positive. If it is negative, all characters in | |
9246 | the string preceding the offset point are taken. For example, an offset of | |
9247 | -1 and no length, as in these semantically identical examples: | |
9248 | ||
9249 | ${substr_-1:abcde} | |
9250 | ${substr{-1}{abcde}} | |
9251 | ||
9252 | yields all but the last character of the string, that is, "abcd". | |
9253 | ||
9254 | ${tr{<subject>}{<characters>}{<replacements>}} | |
9255 | ||
9256 | This item does single-character translation on its subject string. The | |
9257 | second argument is a list of characters to be translated in the subject | |
9258 | string. Each matching character is replaced by the corresponding character | |
9259 | from the replacement list. For example | |
9260 | ||
9261 | ${tr{abcdea}{ac}{13}} | |
9262 | ||
9263 | yields "1b3de1". If there are duplicates in the second character string, | |
9264 | the last occurrence is used. If the third string is shorter than the | |
9265 | second, its last character is replicated. However, if it is empty, no | |
9266 | translation takes place. | |
9267 | ||
9268 | ||
9269 | 11.6 Expansion operators | |
9270 | ------------------------ | |
9271 | ||
9272 | For expansion items that perform transformations on a single argument string, | |
9273 | the "operator" notation is used because it is simpler and uses fewer braces. | |
9274 | The substring is first expanded before the operation is applied to it. The | |
9275 | following operations can be performed: | |
9276 | ||
9277 | ${address:<string>} | |
9278 | ||
9279 | The string is interpreted as an RFC 2822 address, as it might appear in a | |
9280 | header line, and the effective address is extracted from it. If the string | |
9281 | does not parse successfully, the result is empty. | |
9282 | ||
9283 | ${addresses:<string>} | |
9284 | ||
9285 | The string (after expansion) is interpreted as a list of addresses in RFC | |
9286 | 2822 format, such as can be found in a To: or Cc: header line. The | |
9287 | operative address (local-part@domain) is extracted from each item, and the | |
9288 | result of the expansion is a colon-separated list, with appropriate | |
9289 | doubling of colons should any happen to be present in the email addresses. | |
9290 | Syntactically invalid RFC2822 address items are omitted from the output. | |
9291 | ||
9292 | It is possible to specify a character other than colon for the output | |
9293 | separator by starting the string with > followed by the new separator | |
9294 | character. For example: | |
9295 | ||
9296 | ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)} | |
9297 | ||
9298 | expands to "ceo@up.stairs&sec@base.ment". Compare the address (singular) | |
9299 | expansion item, which extracts the working address from a single RFC2822 | |
9300 | address. See the filter, map, and reduce items for ways of processing | |
9301 | lists. | |
9302 | ||
9303 | To clarify "list of addresses in RFC 2822 format" mentioned above, Exim | |
9304 | follows a strict interpretation of header line formatting. Exim parses the | |
9305 | bare, unquoted portion of an email address and if it finds a comma, treats | |
2813c06e | 9306 | it as an email address separator. For the example header line: |
420a0d19 CE |
9307 | |
9308 | From: =?iso-8859-2?Q?Last=2C_First?= <user@example.com> | |
9309 | ||
9310 | The first example below demonstrates that Q-encoded email addresses are | |
9311 | parsed properly if it is given the raw header (in this example, | |
9312 | "$rheader_from:"). It does not see the comma because it's still encoded as | |
9313 | "=2C". The second example below is passed the contents of "$header_from:", | |
9314 | meaning it gets de-mimed. Exim sees the decoded "," so it treats it as two | |
9315 | email addresses. The third example shows that the presence of a comma is | |
9316 | skipped when it is quoted. | |
9317 | ||
9318 | # exim -be '${addresses:From: \ | |
9319 | =?iso-8859-2?Q?Last=2C_First?= <user@example.com>}' | |
9320 | user@example.com | |
9321 | # exim -be '${addresses:From: Last, First <user@example.com>}' | |
9322 | Last:user@example.com | |
9323 | # exim -be '${addresses:From: "Last, First" <user@example.com>}' | |
9324 | user@example.com | |
9325 | ||
2813c06e CE |
9326 | ${base32:<digits>} |
9327 | ||
9328 | The string must consist entirely of decimal digits. The number is converted | |
9329 | to base 32 and output as a (empty, for zero) string of characters. Only | |
9330 | lowercase letters are used. | |
9331 | ||
9332 | ${base32d:<base-32 digits>} | |
9333 | ||
9334 | The string must consist entirely of base-32 digits. The number is converted | |
9335 | to decimal and output as a string. | |
9336 | ||
420a0d19 CE |
9337 | ${base62:<digits>} |
9338 | ||
9339 | The string must consist entirely of decimal digits. The number is converted | |
9340 | to base 62 and output as a string of six characters, including leading | |
9341 | zeros. In the few operating environments where Exim uses base 36 instead of | |
9342 | base 62 for its message identifiers (because those systems do not have | |
9343 | case-sensitive file names), base 36 is used by this operator, despite its | |
9344 | name. Note: Just to be absolutely clear: this is not base64 encoding. | |
9345 | ||
9346 | ${base62d:<base-62 digits>} | |
9347 | ||
9348 | The string must consist entirely of base-62 digits, or, in operating | |
9349 | environments where Exim uses base 36 instead of base 62 for its message | |
9350 | identifiers, base-36 digits. The number is converted to decimal and output | |
9351 | as a string. | |
9352 | ||
2813c06e CE |
9353 | ${base64:<string>} |
9354 | ||
9355 | This operator converts a string into one that is base64 encoded. | |
9356 | ||
9357 | If the string is a single variable of type certificate, returns the base64 | |
9358 | encoding of the DER form of the certificate. | |
9359 | ||
9360 | ${base64d:<string>} | |
9361 | ||
9362 | This operator converts a base64-encoded string into the un-coded form. | |
9363 | ||
420a0d19 CE |
9364 | ${domain:<string>} |
9365 | ||
9366 | The string is interpreted as an RFC 2822 address and the domain is | |
9367 | extracted from it. If the string does not parse successfully, the result is | |
9368 | empty. | |
9369 | ||
9370 | ${escape:<string>} | |
9371 | ||
9372 | If the string contains any non-printing characters, they are converted to | |
9373 | escape sequences starting with a backslash. Whether characters with the | |
9374 | most significant bit set (so-called "8-bit characters") count as printing | |
9375 | or not is controlled by the print_topbitchars option. | |
9376 | ||
2813c06e CE |
9377 | ${escape8bit:<string>} |
9378 | ||
9379 | If the string contains and characters with the most significant bit set, | |
9380 | they are converted to escape sequences starting with a backslash. | |
9381 | Backslashes and DEL characters are also converted. | |
9382 | ||
420a0d19 CE |
9383 | ${eval:<string>} and ${eval10:<string>} |
9384 | ||
9385 | These items supports simple arithmetic and bitwise logical operations in | |
9386 | expansion strings. The string (after expansion) must be a conventional | |
9387 | arithmetic expression, but it is limited to basic arithmetic operators, | |
9388 | bitwise logical operators, and parentheses. All operations are carried out | |
9389 | using integer arithmetic. The operator priorities are as follows (the same | |
9390 | as in the C programming language): | |
9391 | ||
9392 | highest: not (~), negate (-) | |
9393 | multiply (*), divide (/), remainder (%) | |
9394 | plus (+), minus (-) | |
9395 | shift-left (<<), shift-right (>>) | |
9396 | and (&) | |
9397 | xor (^) | |
9398 | lowest: or (|) | |
9399 | ||
9400 | Binary operators with the same priority are evaluated from left to right. | |
9401 | White space is permitted before or after operators. | |
9402 | ||
9403 | For eval, numbers may be decimal, octal (starting with "0") or hexadecimal | |
9404 | (starting with "0x"). For eval10, all numbers are taken as decimal, even if | |
9405 | they start with a leading zero; hexadecimal numbers are not permitted. This | |
9406 | can be useful when processing numbers extracted from dates or times, which | |
9407 | often do have leading zeros. | |
9408 | ||
9409 | A number may be followed by "K", "M" or "G" to multiply it by 1024, | |
9410 | 1024*1024 or 1024*1024*1024, respectively. Negative numbers are supported. | |
9411 | The result of the computation is a decimal representation of the answer | |
9412 | (without "K", "M" or "G"). For example: | |
9413 | ||
9414 | ${eval:1+1} yields 2 | |
9415 | ${eval:1+2*3} yields 7 | |
9416 | ${eval:(1+2)*3} yields 9 | |
9417 | ${eval:2+42%5} yields 4 | |
9418 | ${eval:0xc&5} yields 4 | |
9419 | ${eval:0xc|5} yields 13 | |
9420 | ${eval:0xc^5} yields 9 | |
9421 | ${eval:0xc>>1} yields 6 | |
9422 | ${eval:0xc<<1} yields 24 | |
9423 | ${eval:~255&0x1234} yields 4608 | |
9424 | ${eval:-(~255&0x1234)} yields -4608 | |
9425 | ||
9426 | As a more realistic example, in an ACL you might have | |
9427 | ||
9428 | deny message = Too many bad recipients | |
9429 | condition = \ | |
9430 | ${if and { \ | |
9431 | {>{$rcpt_count}{10}} \ | |
9432 | { \ | |
9433 | < \ | |
9434 | {$recipients_count} \ | |
9435 | {${eval:$rcpt_count/2}} \ | |
9436 | } \ | |
9437 | }{yes}{no}} | |
9438 | ||
9439 | The condition is true if there have been more than 10 RCPT commands and | |
9440 | fewer than half of them have resulted in a valid recipient. | |
9441 | ||
9442 | ${expand:<string>} | |
9443 | ||
9444 | The expand operator causes a string to be expanded for a second time. For | |
9445 | example, | |
9446 | ||
9447 | ${expand:${lookup{$domain}dbm{/some/file}{$value}}} | |
9448 | ||
9449 | first looks up a string in a file while expanding the operand for expand, | |
9450 | and then re-expands what it has found. | |
9451 | ||
9452 | ${from_utf8:<string>} | |
9453 | ||
9454 | The world is slowly moving towards Unicode, although there are no standards | |
9455 | for email yet. However, other applications (including some databases) are | |
9456 | starting to store data in Unicode, using UTF-8 encoding. This operator | |
9457 | converts from a UTF-8 string to an ISO-8859-1 string. UTF-8 code values | |
9458 | greater than 255 are converted to underscores. The input must be a valid | |
9459 | UTF-8 string. If it is not, the result is an undefined sequence of bytes. | |
9460 | ||
9461 | Unicode code points with values less than 256 are compatible with ASCII and | |
9462 | ISO-8859-1 (also known as Latin-1). For example, character 169 is the | |
9463 | copyright symbol in both cases, though the way it is encoded is different. | |
9464 | In UTF-8, more than one byte is needed for characters with code values | |
9465 | greater than 127, whereas ISO-8859-1 is a single-byte encoding (but thereby | |
9466 | limited to 256 characters). This makes translation from UTF-8 to ISO-8859-1 | |
9467 | straightforward. | |
9468 | ||
9469 | ${hash_<n>_<m>:<string>} | |
9470 | ||
9471 | The hash operator is a simpler interface to the hashing function that can | |
9472 | be used when the two parameters are fixed numbers (as opposed to strings | |
9473 | that change when expanded). The effect is the same as | |
9474 | ||
9475 | ${hash{<n>}{<m>}{<string>}} | |
9476 | ||
9477 | See the description of the general hash item above for details. The | |
9478 | abbreviation h can be used when hash is used as an operator. | |
9479 | ||
9480 | ${hex2b64:<hexstring>} | |
9481 | ||
9482 | This operator converts a hex string into one that is base64 encoded. This | |
9483 | can be useful for processing the output of the MD5 and SHA-1 hashing | |
9484 | functions. | |
9485 | ||
9486 | ${hexquote:<string>} | |
9487 | ||
9488 | This operator converts non-printable characters in a string into a hex | |
9489 | escape form. Byte values between 33 (!) and 126 (~) inclusive are left as | |
9490 | is, and other byte values are converted to "\xNN", for example a byte value | |
9491 | 127 is converted to "\x7f". | |
9492 | ||
2813c06e CE |
9493 | ${ipv6denorm:<string>} |
9494 | ||
9495 | This expands an IPv6 address to a full eight-element colon-separated set of | |
9496 | hex digits including leading zeroes. A trailing ipv4-style dotted-decimal | |
9497 | set is converted to hex. Pure IPv4 addresses are converted to IPv4-mapped | |
9498 | IPv6. | |
9499 | ||
9500 | ${ipv6norm:<string>} | |
9501 | ||
9502 | This converts an IPv6 address to canonical form. Leading zeroes of groups | |
9503 | are omitted, and the longest set of zero-valued groups is replaced with a | |
9504 | double colon. A trailing ipv4-style dotted-decimal set is converted to hex. | |
9505 | Pure IPv4 addresses are converted to IPv4-mapped IPv6. | |
9506 | ||
420a0d19 CE |
9507 | ${lc:<string>} |
9508 | ||
9509 | This forces the letters in the string into lower-case, for example: | |
9510 | ||
9511 | ${lc:$local_part} | |
9512 | ||
9513 | ${length_<number>:<string>} | |
9514 | ||
9515 | The length operator is a simpler interface to the length function that can | |
9516 | be used when the parameter is a fixed number (as opposed to a string that | |
9517 | changes when expanded). The effect is the same as | |
9518 | ||
9519 | ${length{<number>}{<string>}} | |
9520 | ||
9521 | See the description of the general length item above for details. Note that | |
9522 | length is not the same as strlen. The abbreviation l can be used when | |
9523 | length is used as an operator. | |
9524 | ||
9525 | ${listcount:<string>} | |
9526 | ||
9527 | The string is interpreted as a list and the number of items is returned. | |
9528 | ||
9529 | ${listnamed:<name>} and ${listnamed_<type>:<name>} | |
9530 | ||
9531 | The name is interpreted as a named list and the content of the list is | |
9532 | returned, expanding any referenced lists, re-quoting as needed for | |
9533 | colon-separation. If the optional type is given it must be one of "a", "d", | |
9534 | "h" or "l" and selects address-, domain-, host- or localpart- lists to | |
9535 | search among respectively. Otherwise all types are searched in an undefined | |
9536 | order and the first matching list is returned. | |
9537 | ||
9538 | ${local_part:<string>} | |
9539 | ||
9540 | The string is interpreted as an RFC 2822 address and the local part is | |
9541 | extracted from it. If the string does not parse successfully, the result is | |
9542 | empty. | |
9543 | ||
9544 | ${mask:<IP address>/<bit count>} | |
9545 | ||
9546 | If the form of the string to be operated on is not an IP address followed | |
9547 | by a slash and an integer (that is, a network address in CIDR notation), | |
9548 | the expansion fails. Otherwise, this operator converts the IP address to | |
9549 | binary, masks off the least significant bits according to the bit count, | |
9550 | and converts the result back to text, with mask appended. For example, | |
9551 | ||
9552 | ${mask:10.111.131.206/28} | |
9553 | ||
9554 | returns the string "10.111.131.192/28". Since this operation is expected to | |
9555 | be mostly used for looking up masked addresses in files, the result for an | |
9556 | IPv6 address uses dots to separate components instead of colons, because | |
9557 | colon terminates a key string in lsearch files. So, for example, | |
9558 | ||
9559 | ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99} | |
9560 | ||
9561 | returns the string | |
9562 | ||
9563 | 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99 | |
9564 | ||
9565 | Letters in IPv6 addresses are always output in lower case. | |
9566 | ||
9567 | ${md5:<string>} | |
9568 | ||
9569 | The md5 operator computes the MD5 hash value of the string, and returns it | |
9570 | as a 32-digit hexadecimal number, in which any letters are in lower case. | |
9571 | ||
2813c06e CE |
9572 | If the string is a single variable of type certificate, returns the MD5 |
9573 | hash fingerprint of the certificate. | |
9574 | ||
420a0d19 CE |
9575 | ${nhash_<n>_<m>:<string>} |
9576 | ||
9577 | The nhash operator is a simpler interface to the numeric hashing function | |
9578 | that can be used when the two parameters are fixed numbers (as opposed to | |
9579 | strings that change when expanded). The effect is the same as | |
9580 | ||
9581 | ${nhash{<n>}{<m>}{<string>}} | |
9582 | ||
9583 | See the description of the general nhash item above for details. | |
9584 | ||
9585 | ${quote:<string>} | |
9586 | ||
9587 | The quote operator puts its argument into double quotes if it is an empty | |
9588 | string or contains anything other than letters, digits, underscores, dots, | |
9589 | and hyphens. Any occurrences of double quotes and backslashes are escaped | |
9590 | with a backslash. Newlines and carriage returns are converted to "\n" and " | |
9591 | \r", respectively For example, | |
9592 | ||
9593 | ${quote:ab"*"cd} | |
9594 | ||
9595 | becomes | |
9596 | ||
9597 | "ab\"*\"cd" | |
9598 | ||
9599 | The place where this is useful is when the argument is a substitution from | |
9600 | a variable or a message header. | |
9601 | ||
9602 | ${quote_local_part:<string>} | |
9603 | ||
9604 | This operator is like quote, except that it quotes the string only if | |
9605 | required to do so by the rules of RFC 2822 for quoting local parts. For | |
9606 | example, a plus sign would not cause quoting (but it would for quote). If | |
9607 | you are creating a new email address from the contents of $local_part (or | |
9608 | any other unknown data), you should always use this operator. | |
9609 | ||
9610 | ${quote_<lookup-type>:<string>} | |
9611 | ||
9612 | This operator applies lookup-specific quoting rules to the string. Each | |
9613 | query-style lookup type has its own quoting rules which are described with | |
9614 | the lookups in chapter 9. For example, | |
9615 | ||
9616 | ${quote_ldap:two * two} | |
9617 | ||
9618 | returns | |
9619 | ||
9620 | two%20%5C2A%20two | |
9621 | ||
9622 | For single-key lookup types, no quoting is ever necessary and this operator | |
9623 | yields an unchanged string. | |
9624 | ||
9625 | ${randint:<n>} | |
9626 | ||
9627 | This operator returns a somewhat random number which is less than the | |
9628 | supplied number and is at least 0. The quality of this randomness depends | |
9629 | on how Exim was built; the values are not suitable for keying material. If | |
9630 | Exim is linked against OpenSSL then RAND_pseudo_bytes() is used. If Exim is | |
9631 | linked against GnuTLS then gnutls_rnd(GNUTLS_RND_NONCE) is used, for | |
9632 | versions of GnuTLS with that function. Otherwise, the implementation may be | |
9633 | arc4random(), random() seeded by srandomdev() or srandom(), or a custom | |
9634 | implementation even weaker than random(). | |
9635 | ||
9636 | ${reverse_ip:<ipaddr>} | |
9637 | ||
9638 | This operator reverses an IP address; for IPv4 addresses, the result is in | |
2813c06e | 9639 | dotted-quad decimal form, while for IPv6 addresses the result is in |
420a0d19 CE |
9640 | dotted-nibble hexadecimal form. In both cases, this is the "natural" form |
9641 | for DNS. For example, | |
9642 | ||
9643 | ${reverse_ip:192.0.2.4} | |
9644 | ${reverse_ip:2001:0db8:c42:9:1:abcd:192.0.2.127} | |
9645 | ||
9646 | returns | |
9647 | ||
9648 | 4.2.0.192 | |
9649 | f.7.2.0.0.0.0.c.d.c.b.a.1.0.0.0.9.0.0.0.2.4.c.0.8.b.d.0.1.0.0.2 | |
9650 | ||
9651 | ${rfc2047:<string>} | |
9652 | ||
9653 | This operator encodes text according to the rules of RFC 2047. This is an | |
9654 | encoding that is used in header lines to encode non-ASCII characters. It is | |
9655 | assumed that the input string is in the encoding specified by the | |
2813c06e | 9656 | headers_charset option, which gets its default at build time. If the string |
420a0d19 CE |
9657 | contains only characters in the range 33-126, and no instances of the |
9658 | characters | |
9659 | ||
9660 | ? = ( ) < > @ , ; : \ " . [ ] _ | |
9661 | ||
9662 | it is not modified. Otherwise, the result is the RFC 2047 encoding of the | |
9663 | string, using as many "encoded words" as necessary to encode all the | |
9664 | characters. | |
9665 | ||
9666 | ${rfc2047d:<string>} | |
9667 | ||
9668 | This operator decodes strings that are encoded as per RFC 2047. Binary zero | |
9669 | bytes are replaced by question marks. Characters are converted into the | |
9670 | character set defined by headers_charset. Overlong RFC 2047 "words" are not | |
9671 | recognized unless check_rfc2047_length is set false. | |
9672 | ||
9673 | Note: If you use $header_xxx: (or $h_xxx:) to access a header line, RFC | |
9674 | 2047 decoding is done automatically. You do not need to use this operator | |
9675 | as well. | |
9676 | ||
9677 | ${rxquote:<string>} | |
9678 | ||
9679 | The rxquote operator inserts a backslash before any non-alphanumeric | |
9680 | characters in its argument. This is useful when substituting the values of | |
9681 | variables or headers inside regular expressions. | |
9682 | ||
9683 | ${sha1:<string>} | |
9684 | ||
9685 | The sha1 operator computes the SHA-1 hash value of the string, and returns | |
9686 | it as a 40-digit hexadecimal number, in which any letters are in upper | |
9687 | case. | |
9688 | ||
2813c06e CE |
9689 | If the string is a single variable of type certificate, returns the SHA-1 |
9690 | hash fingerprint of the certificate. | |
9691 | ||
9692 | ${sha256:<string>} | |
9693 | ||
9694 | The sha256 operator computes the SHA-256 hash value of the string and | |
9695 | returns it as a 64-digit hexadecimal number, in which any letters are in | |
9696 | upper case. | |
9697 | ||
9698 | If the string is a single variable of type certificate, returns the SHA-256 | |
9699 | hash fingerprint of the certificate. | |
9700 | ||
9701 | ${sha3:<string>}, ${sha3_<n>:<string>} | |
9702 | ||
9703 | The sha3 operator computes the SHA3-256 hash value of the string and | |
9704 | returns it as a 64-digit hexadecimal number, in which any letters are in | |
9705 | upper case. | |
420a0d19 | 9706 | |
2813c06e CE |
9707 | If a number is appended, separated by an underbar, it specifies the output |
9708 | length. Values of 224, 256, 384 and 512 are accepted; with 256 being the | |
9709 | default. | |
9710 | ||
9711 | The sha3 expansion item is only supported if Exim has been compiled with | |
9712 | GnuTLS 3.5.0 or later. | |
420a0d19 CE |
9713 | |
9714 | ${stat:<string>} | |
9715 | ||
9716 | The string, after expansion, must be a file path. A call to the stat() | |
9717 | function is made for this path. If stat() fails, an error occurs and the | |
9718 | expansion fails. If it succeeds, the data from the stat replaces the item, | |
9719 | as a series of <name>=<value> pairs, where the values are all numerical, | |
9720 | except for the value of "smode". The names are: "mode" (giving the mode as | |
9721 | a 4-digit octal number), "smode" (giving the mode in symbolic format as a | |
9722 | 10-character string, as for the ls command), "inode", "device", "links", | |
9723 | "uid", "gid", "size", "atime", "mtime", and "ctime". You can extract | |
9724 | individual fields using the extract expansion item. | |
9725 | ||
9726 | The use of the stat expansion in users' filter files can be locked out by | |
9727 | the system administrator. Warning: The file size may be incorrect on 32-bit | |
9728 | systems for files larger than 2GB. | |
9729 | ||
9730 | ${str2b64:<string>} | |
9731 | ||
2813c06e | 9732 | Now deprecated, a synonym for the base64 expansion operator. |
420a0d19 CE |
9733 | |
9734 | ${strlen:<string>} | |
9735 | ||
9736 | The item is replace by the length of the expanded string, expressed as a | |
9737 | decimal number. Note: Do not confuse strlen with length. | |
9738 | ||
9739 | ${substr_<start>_<length>:<string>} | |
9740 | ||
9741 | The substr operator is a simpler interface to the substr function that can | |
9742 | be used when the two parameters are fixed numbers (as opposed to strings | |
9743 | that change when expanded). The effect is the same as | |
9744 | ||
9745 | ${substr{<start>}{<length>}{<string>}} | |
9746 | ||
9747 | See the description of the general substr item above for details. The | |
9748 | abbreviation s can be used when substr is used as an operator. | |
9749 | ||
9750 | ${time_eval:<string>} | |
9751 | ||
9752 | This item converts an Exim time interval such as "2d4h5m" into a number of | |
9753 | seconds. | |
9754 | ||
9755 | ${time_interval:<string>} | |
9756 | ||
9757 | The argument (after sub-expansion) must be a sequence of decimal digits | |
9758 | that represents an interval of time as a number of seconds. It is converted | |
9759 | into a number of larger units and output in Exim's normal time format, for | |
9760 | example, "1w3d4h2m6s". | |
9761 | ||
9762 | ${uc:<string>} | |
9763 | ||
9764 | This forces the letters in the string into upper-case. | |
9765 | ||
9766 | ${utf8clean:<string>} | |
9767 | ||
9768 | This replaces any invalid utf-8 sequence in the string by the character "? | |
9769 | ". | |
9770 | ||
2813c06e CE |
9771 | ${utf8_domain_to_alabel:<string>}, ${utf8_domain_from_alabel:<string>}, $ |
9772 | {utf8_localpart_to_alabel:<string>}, ${utf8_localpart_from_alabel:<string>} | |
9773 | ||
9774 | These convert EAI mail name components between UTF-8 and a-label forms. For | |
9775 | information on internationalisation support see 59.1. | |
9776 | ||
420a0d19 CE |
9777 | |
9778 | 11.7 Expansion conditions | |
9779 | ------------------------- | |
9780 | ||
9781 | The following conditions are available for testing by the ${if construct while | |
9782 | expanding strings: | |
9783 | ||
9784 | !<condition> | |
9785 | ||
9786 | Preceding any condition with an exclamation mark negates the result of the | |
9787 | condition. | |
9788 | ||
9789 | <symbolic operator> {<string1>}{<string2>} | |
9790 | ||
9791 | There are a number of symbolic operators for doing numeric comparisons. | |
9792 | They are: | |
9793 | ||
9794 | = equal | |
9795 | == equal | |
9796 | > greater | |
9797 | >= greater or equal | |
9798 | < less | |
9799 | <= less or equal | |
9800 | ||
9801 | For example: | |
9802 | ||
9803 | ${if >{$message_size}{10M} ... | |
9804 | ||
9805 | Note that the general negation operator provides for inequality testing. | |
9806 | The two strings must take the form of optionally signed decimal integers, | |
9807 | optionally followed by one of the letters "K", "M" or "G" (in either upper | |
9808 | or lower case), signifying multiplication by 1024, 1024*1024 or | |
9809 | 1024*1024*1024, respectively. As a special case, the numerical value of an | |
9810 | empty string is taken as zero. | |
9811 | ||
9812 | In all cases, a relative comparator OP is testing if <string1> OP <string2 | |
9813 | >; the above example is checking if $message_size is larger than 10M, not | |
9814 | if 10M is larger than $message_size. | |
9815 | ||
9816 | acl {{<name>}{<arg1>}{<arg2>}...} | |
9817 | ||
9818 | The name and zero to nine argument strings are first expanded separately. | |
9819 | The expanded arguments are assigned to the variables $acl_arg1 to $acl_arg9 | |
9820 | in order. Any unused are made empty. The variable $acl_narg is set to the | |
2813c06e | 9821 | number of arguments. The named ACL (see chapter 43) is called and may use |
420a0d19 CE |
9822 | the variables; if another acl expansion is used the values are restored |
9823 | after it returns. If the ACL sets a value using a "message =" modifier the | |
9824 | variable $value becomes the result of the expansion, otherwise it is empty. | |
9825 | If the ACL returns accept the condition is true; if deny, false. If the ACL | |
9826 | returns defer the result is a forced-fail. | |
9827 | ||
9828 | bool {<string>} | |
9829 | ||
9830 | This condition turns a string holding a true or false representation into a | |
9831 | boolean state. It parses "true", "false", "yes" and "no" | |
9832 | (case-insensitively); also integer numbers map to true if non-zero, false | |
9833 | if zero. An empty string is treated as false. Leading and trailing | |
9834 | whitespace is ignored; thus a string consisting only of whitespace is | |
9835 | false. All other string values will result in expansion failure. | |
9836 | ||
9837 | When combined with ACL variables, this expansion condition will let you | |
9838 | make decisions in one place and act on those decisions in another place. | |
9839 | For example: | |
9840 | ||
9841 | ${if bool{$acl_m_privileged_sender} ... | |
9842 | ||
9843 | bool_lax {<string>} | |
9844 | ||
9845 | Like bool, this condition turns a string into a boolean state. But where | |
9846 | bool accepts a strict set of strings, bool_lax uses the same loose | |
9847 | definition that the Router condition option uses. The empty string and the | |
9848 | values "false", "no" and "0" map to false, all others map to true. Leading | |
9849 | and trailing whitespace is ignored. | |
9850 | ||
9851 | Note that where "bool{00}" is false, "bool_lax{00}" is true. | |
9852 | ||
9853 | crypteq {<string1>}{<string2>} | |
9854 | ||
9855 | This condition is included in the Exim binary if it is built to support any | |
9856 | authentication mechanisms (see chapter 33). Otherwise, it is necessary to | |
9857 | define SUPPORT_CRYPTEQ in Local/Makefile to get crypteq included in the | |
9858 | binary. | |
9859 | ||
9860 | The crypteq condition has two arguments. The first is encrypted and | |
9861 | compared against the second, which is already encrypted. The second string | |
9862 | may be in the LDAP form for storing encrypted strings, which starts with | |
9863 | the encryption type in curly brackets, followed by the data. If the second | |
9864 | string does not begin with "{" it is assumed to be encrypted with crypt() | |
9865 | or crypt16() (see below), since such strings cannot begin with "{". | |
9866 | Typically this will be a field from a password file. An example of an | |
9867 | encrypted string in LDAP form is: | |
9868 | ||
9869 | {md5}CY9rzUYh03PK3k6DJie09g== | |
9870 | ||
9871 | If such a string appears directly in an expansion, the curly brackets have | |
9872 | to be quoted, because they are part of the expansion syntax. For example: | |
9873 | ||
9874 | ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}} | |
9875 | ||
9876 | The following encryption types (whose names are matched case-independently) | |
9877 | are supported: | |
9878 | ||
2813c06e | 9879 | + {md5} computes the MD5 digest of the first string, and expresses this |
420a0d19 CE |
9880 | as printable characters to compare with the remainder of the second |
9881 | string. If the length of the comparison string is 24, Exim assumes that | |
9882 | it is base64 encoded (as in the above example). If the length is 32, | |
9883 | Exim assumes that it is a hexadecimal encoding of the MD5 digest. If | |
9884 | the length not 24 or 32, the comparison fails. | |
9885 | ||
2813c06e | 9886 | + {sha1} computes the SHA-1 digest of the first string, and expresses |
420a0d19 CE |
9887 | this as printable characters to compare with the remainder of the |
9888 | second string. If the length of the comparison string is 28, Exim | |
9889 | assumes that it is base64 encoded. If the length is 40, Exim assumes | |
9890 | that it is a hexadecimal encoding of the SHA-1 digest. If the length is | |
9891 | not 28 or 40, the comparison fails. | |
9892 | ||
2813c06e | 9893 | + {crypt} calls the crypt() function, which traditionally used to use |
420a0d19 CE |
9894 | only the first eight characters of the password. However, in modern |
9895 | operating systems this is no longer true, and in many cases the entire | |
9896 | password is used, whatever its length. | |
9897 | ||
2813c06e | 9898 | + {crypt16} calls the crypt16() function, which was originally created to |
420a0d19 CE |
9899 | use up to 16 characters of the password in some operating systems. |
9900 | Again, in modern operating systems, more characters may be used. | |
9901 | ||
9902 | Exim has its own version of crypt16(), which is just a double call to crypt | |
9903 | (). For operating systems that have their own version, setting HAVE_CRYPT16 | |
9904 | in Local/Makefile when building Exim causes it to use the operating system | |
9905 | version instead of its own. This option is set by default in the | |
9906 | OS-dependent Makefile for those operating systems that are known to support | |
9907 | crypt16(). | |
9908 | ||
9909 | Some years after Exim's crypt16() was implemented, a user discovered that | |
9910 | it was not using the same algorithm as some operating systems' versions. It | |
9911 | turns out that as well as crypt16() there is a function called bigcrypt() | |
9912 | in some operating systems. This may or may not use the same algorithm, and | |
9913 | both of them may be different to Exim's built-in crypt16(). | |
9914 | ||
9915 | However, since there is now a move away from the traditional crypt() | |
9916 | functions towards using SHA1 and other algorithms, tidying up this area of | |
9917 | Exim is seen as very low priority. | |
9918 | ||
9919 | If you do not put a encryption type (in curly brackets) in a crypteq | |
9920 | comparison, the default is usually either "{crypt}" or "{crypt16}", as | |
9921 | determined by the setting of DEFAULT_CRYPT in Local/Makefile. The default | |
9922 | default is "{crypt}". Whatever the default, you can always use either | |
9923 | function by specifying it explicitly in curly brackets. | |
9924 | ||
9925 | def:<variable name> | |
9926 | ||
9927 | The def condition must be followed by the name of one of the expansion | |
9928 | variables defined in section 11.9. The condition is true if the variable | |
9929 | does not contain the empty string. For example: | |
9930 | ||
9931 | ${if def:sender_ident {from $sender_ident}} | |
9932 | ||
9933 | Note that the variable name is given without a leading $ character. If the | |
9934 | variable does not exist, the expansion fails. | |
9935 | ||
9936 | def:header_<header name>: or def:h_<header name>: | |
9937 | ||
9938 | This condition is true if a message is being processed and the named header | |
9939 | exists in the message. For example, | |
9940 | ||
9941 | ${if def:header_reply-to:{$h_reply-to:}{$h_from:}} | |
9942 | ||
9943 | Note: No $ appears before header_ or h_ in the condition, and the header | |
9944 | name must be terminated by a colon if white space does not follow. | |
9945 | ||
9946 | eq {<string1>}{<string2>}, eqi {<string1>}{<string2>} | |
9947 | ||
9948 | The two substrings are first expanded. The condition is true if the two | |
9949 | resulting strings are identical. For eq the comparison includes the case of | |
9950 | letters, whereas for eqi the comparison is case-independent. | |
9951 | ||
9952 | exists {<file name>} | |
9953 | ||
9954 | The substring is first expanded and then interpreted as an absolute path. | |
9955 | The condition is true if the named file (or directory) exists. The | |
9956 | existence test is done by calling the stat() function. The use of the | |
9957 | exists test in users' filter files may be locked out by the system | |
9958 | administrator. | |
9959 | ||
9960 | first_delivery | |
9961 | ||
9962 | This condition, which has no data, is true during a message's first | |
9963 | delivery attempt. It is false during any subsequent delivery attempts. | |
9964 | ||
9965 | forall{<a list>}{<a condition>}, forany{<a list>}{<a condition>} | |
9966 | ||
9967 | These conditions iterate over a list. The first argument is expanded to | |
9968 | form the list. By default, the list separator is a colon, but it can be | |
9969 | changed by the normal method. The second argument is interpreted as a | |
9970 | condition that is to be applied to each item in the list in turn. During | |
9971 | the interpretation of the condition, the current list item is placed in a | |
9972 | variable called $item. | |
9973 | ||
2813c06e | 9974 | + For forany, interpretation stops if the condition is true for any item, |
420a0d19 CE |
9975 | and the result of the whole condition is true. If the condition is |
9976 | false for all items in the list, the overall condition is false. | |
9977 | ||
2813c06e | 9978 | + For forall, interpretation stops if the condition is false for any |
420a0d19 CE |
9979 | item, and the result of the whole condition is false. If the condition |
9980 | is true for all items in the list, the overall condition is true. | |
9981 | ||
9982 | Note that negation of forany means that the condition must be false for all | |
9983 | items for the overall condition to succeed, and negation of forall means | |
9984 | that the condition must be false for at least one item. In this example, | |
9985 | the list separator is changed to a comma: | |
9986 | ||
9987 | ${if forany{<, $recipients}{match{$item}{^user3@}}{yes}{no}} | |
9988 | ||
9989 | The value of $item is saved and restored while forany or forall is being | |
9990 | processed, to enable these expansion items to be nested. | |
9991 | ||
9992 | To scan a named list, expand it with the listnamed operator. | |
9993 | ||
9994 | ge {<string1>}{<string2>}, gei {<string1>}{<string2>} | |
9995 | ||
9996 | The two substrings are first expanded. The condition is true if the first | |
9997 | string is lexically greater than or equal to the second string. For ge the | |
9998 | comparison includes the case of letters, whereas for gei the comparison is | |
9999 | case-independent. | |
10000 | ||
10001 | gt {<string1>}{<string2>}, gti {<string1>}{<string2>} | |
10002 | ||
10003 | The two substrings are first expanded. The condition is true if the first | |
10004 | string is lexically greater than the second string. For gt the comparison | |
10005 | includes the case of letters, whereas for gti the comparison is | |
10006 | case-independent. | |
10007 | ||
10008 | inlist {<string1>}{<string2>}, inlisti {<string1>}{<string2>} | |
10009 | ||
10010 | Both strings are expanded; the second string is treated as a list of simple | |
10011 | strings; if the first string is a member of the second, then the condition | |
10012 | is true. | |
10013 | ||
10014 | These are simpler to use versions of the more powerful forany condition. | |
10015 | Examples, and the forany equivalents: | |
10016 | ||
10017 | ${if inlist{needle}{foo:needle:bar}} | |
10018 | ${if forany{foo:needle:bar}{eq{$item}{needle}}} | |
10019 | ${if inlisti{Needle}{fOo:NeeDLE:bAr}} | |
10020 | ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}} | |
10021 | ||
10022 | isip {<string>}, isip4 {<string>}, isip6 {<string>} | |
10023 | ||
10024 | The substring is first expanded, and then tested to see if it has the form | |
10025 | of an IP address. Both IPv4 and IPv6 addresses are valid for isip, whereas | |
10026 | isip4 and isip6 test specifically for IPv4 or IPv6 addresses. | |
10027 | ||
10028 | For an IPv4 address, the test is for four dot-separated components, each of | |
10029 | which consists of from one to three digits. For an IPv6 address, up to | |
10030 | eight colon-separated components are permitted, each containing from one to | |
10031 | four hexadecimal digits. There may be fewer than eight components if an | |
10032 | empty component (adjacent colons) is present. Only one empty component is | |
10033 | permitted. | |
10034 | ||
10035 | Note: The checks are just on the form of the address; actual numerical | |
10036 | values are not considered. Thus, for example, 999.999.999.999 passes the | |
10037 | IPv4 check. The main use of these tests is to distinguish between IP | |
10038 | addresses and host names, or between IPv4 and IPv6 addresses. For example, | |
10039 | you could use | |
10040 | ||
10041 | ${if isip4{$sender_host_address}... | |
10042 | ||
10043 | to test which IP version an incoming SMTP connection is using. | |
10044 | ||
10045 | ldapauth {<ldap query>} | |
10046 | ||
2813c06e | 10047 | This condition supports user authentication using LDAP. See section 9.14 |
420a0d19 CE |
10048 | for details of how to use LDAP in lookups and the syntax of queries. For |
10049 | this use, the query must contain a user name and password. The query itself | |
10050 | is not used, and can be empty. The condition is true if the password is not | |
10051 | empty, and the user name and password are accepted by the LDAP server. An | |
10052 | empty password is rejected without calling LDAP because LDAP binds with an | |
10053 | empty password are considered anonymous regardless of the username, and | |
10054 | will succeed in most configurations. See chapter 33 for details of SMTP | |
10055 | authentication, and chapter 34 for an example of how this can be used. | |
10056 | ||
10057 | le {<string1>}{<string2>}, lei {<string1>}{<string2>} | |
10058 | ||
10059 | The two substrings are first expanded. The condition is true if the first | |
10060 | string is lexically less than or equal to the second string. For le the | |
10061 | comparison includes the case of letters, whereas for lei the comparison is | |
10062 | case-independent. | |
10063 | ||
10064 | lt {<string1>}{<string2>}, lti {<string1>}{<string2>} | |
10065 | ||
10066 | The two substrings are first expanded. The condition is true if the first | |
10067 | string is lexically less than the second string. For lt the comparison | |
10068 | includes the case of letters, whereas for lti the comparison is | |
10069 | case-independent. | |
10070 | ||
10071 | match {<string1>}{<string2>} | |
10072 | ||
10073 | The two substrings are first expanded. The second is then treated as a | |
10074 | regular expression and applied to the first. Because of the pre-expansion, | |
10075 | if the regular expression contains dollar, or backslash characters, they | |
10076 | must be escaped. Care must also be taken if the regular expression contains | |
10077 | braces (curly brackets). A closing brace must be escaped so that it is not | |
10078 | taken as a premature termination of <string2>. The easiest approach is to | |
10079 | use the "\N" feature to disable expansion of the regular expression. For | |
10080 | example, | |
10081 | ||
10082 | ${if match {$local_part}{\N^\d{3}\N} ... | |
10083 | ||
10084 | If the whole expansion string is in double quotes, further escaping of | |
10085 | backslashes is also required. | |
10086 | ||
10087 | The condition is true if the regular expression match succeeds. The regular | |
10088 | expression is not required to begin with a circumflex metacharacter, but if | |
10089 | there is no circumflex, the expression is not anchored, and it may match | |
10090 | anywhere in the subject, not just at the start. If you want the pattern to | |
10091 | match at the end of the subject, you must include the "$" metacharacter at | |
10092 | an appropriate point. | |
10093 | ||
10094 | At the start of an if expansion the values of the numeric variable | |
10095 | substitutions $1 etc. are remembered. Obeying a match condition that | |
10096 | succeeds causes them to be reset to the substrings of that condition and | |
10097 | they will have these values during the expansion of the success string. At | |
10098 | the end of the if expansion, the previous values are restored. After | |
10099 | testing a combination of conditions using or, the subsequent values of the | |
10100 | numeric variables are those of the condition that succeeded. | |
10101 | ||
10102 | match_address {<string1>}{<string2>} | |
10103 | ||
10104 | See match_local_part. | |
10105 | ||
10106 | match_domain {<string1>}{<string2>} | |
10107 | ||
10108 | See match_local_part. | |
10109 | ||
10110 | match_ip {<string1>}{<string2>} | |
10111 | ||
10112 | This condition matches an IP address to a list of IP address patterns. It | |
10113 | must be followed by two argument strings. The first (after expansion) must | |
10114 | be an IP address or an empty string. The second (not expanded) is a | |
10115 | restricted host list that can match only an IP address, not a host name. | |
10116 | For example: | |
10117 | ||
10118 | ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}} | |
10119 | ||
10120 | The specific types of host list item that are permitted in the list are: | |
10121 | ||
2813c06e | 10122 | + An IP address, optionally with a CIDR mask. |
420a0d19 | 10123 | |
2813c06e | 10124 | + A single asterisk, which matches any IP address. |
420a0d19 | 10125 | |
2813c06e | 10126 | + An empty item, which matches only if the IP address is empty. This |
420a0d19 CE |
10127 | could be useful for testing for a locally submitted message or one from |
10128 | specific hosts in a single test such as | |
10129 | ||
10130 | ${if match_ip{$sender_host_address}{:4.3.2.1:...}{...}{...}} | |
10131 | ||
10132 | where the first item in the list is the empty string. | |
10133 | ||
2813c06e | 10134 | + The item @[] matches any of the local host's interface addresses. |
420a0d19 | 10135 | |
2813c06e | 10136 | + Single-key lookups are assumed to be like "net-" style lookups in host |
420a0d19 CE |
10137 | lists, even if "net-" is not specified. There is never any attempt to |
10138 | turn the IP address into a host name. The most common type of linear | |
10139 | search for match_ip is likely to be iplsearch, in which the file can | |
10140 | contain CIDR masks. For example: | |
10141 | ||
10142 | ${if match_ip{$sender_host_address}{iplsearch;/some/file}... | |
10143 | ||
10144 | It is of course possible to use other kinds of lookup, and in such a | |
10145 | case, you do need to specify the "net-" prefix if you want to specify a | |
10146 | specific address mask, for example: | |
10147 | ||
10148 | ${if match_ip{$sender_host_address}{net24-dbm;/some/file}... | |
10149 | ||
10150 | However, unless you are combining a match_ip condition with others, it | |
10151 | is just as easy to use the fact that a lookup is itself a condition, | |
10152 | and write: | |
10153 | ||
10154 | ${lookup{${mask:$sender_host_address/24}}dbm{/a/file}... | |
10155 | ||
10156 | Note that <string2> is not itself subject to string expansion, unless Exim | |
10157 | was built with the EXPAND_LISTMATCH_RHS option. | |
10158 | ||
10159 | Consult section 10.11 for further details of these patterns. | |
10160 | ||
10161 | match_local_part {<string1>}{<string2>} | |
10162 | ||
10163 | This condition, together with match_address and match_domain, make it | |
10164 | possible to test domain, address, and local part lists within expansions. | |
10165 | Each condition requires two arguments: an item and a list to match. A | |
10166 | trivial example is: | |
10167 | ||
10168 | ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}} | |
10169 | ||
10170 | In each case, the second argument may contain any of the allowable items | |
10171 | for a list of the appropriate type. Also, because the second argument | |
10172 | (after expansion) is a standard form of list, it is possible to refer to a | |
10173 | named list. Thus, you can use conditions like this: | |
10174 | ||
10175 | ${if match_domain{$domain}{+local_domains}{... | |
10176 | ||
10177 | For address lists, the matching starts off caselessly, but the "+caseful" | |
10178 | item can be used, as in all address lists, to cause subsequent items to | |
10179 | have their local parts matched casefully. Domains are always matched | |
10180 | caselessly. | |
10181 | ||
10182 | Note that <string2> is not itself subject to string expansion, unless Exim | |
10183 | was built with the EXPAND_LISTMATCH_RHS option. | |
10184 | ||
10185 | Note: Host lists are not supported in this way. This is because hosts have | |
10186 | two identities: a name and an IP address, and it is not clear how to | |
10187 | specify cleanly how such a test would work. However, IP addresses can be | |
10188 | matched using match_ip. | |
10189 | ||
10190 | pam {<string1>:<string2>:...} | |
10191 | ||
10192 | Pluggable Authentication Modules (http://www.kernel.org/pub/linux/libs/pam/ | |
10193 | ) are a facility that is available in the latest releases of Solaris and in | |
10194 | some GNU/Linux distributions. The Exim support, which is intended for use | |
10195 | in conjunction with the SMTP AUTH command, is available only if Exim is | |
10196 | compiled with | |
10197 | ||
10198 | SUPPORT_PAM=yes | |
10199 | ||
10200 | in Local/Makefile. You probably need to add -lpam to EXTRALIBS, and in some | |
10201 | releases of GNU/Linux -ldl is also needed. | |
10202 | ||
10203 | The argument string is first expanded, and the result must be a | |
10204 | colon-separated list of strings. Leading and trailing white space is | |
10205 | ignored. The PAM module is initialized with the service name "exim" and the | |
10206 | user name taken from the first item in the colon-separated data string (< | |
10207 | string1>). The remaining items in the data string are passed over in | |
10208 | response to requests from the authentication function. In the simple case | |
10209 | there will only be one request, for a password, so the data consists of | |
10210 | just two strings. | |
10211 | ||
10212 | There can be problems if any of the strings are permitted to contain colon | |
10213 | characters. In the usual way, these have to be doubled to avoid being taken | |
10214 | as separators. If the data is being inserted from a variable, the sg | |
10215 | expansion item can be used to double any existing colons. For example, the | |
10216 | configuration of a LOGIN authenticator might contain this setting: | |
10217 | ||
10218 | server_condition = ${if pam{$auth1:${sg{$auth2}{:}{::}}}} | |
10219 | ||
10220 | For a PLAIN authenticator you could use: | |
10221 | ||
10222 | server_condition = ${if pam{$auth2:${sg{$auth3}{:}{::}}}} | |
10223 | ||
10224 | In some operating systems, PAM authentication can be done only from a | |
10225 | process running as root. Since Exim is running as the Exim user when | |
10226 | receiving messages, this means that PAM cannot be used directly in those | |
10227 | systems. A patched version of the pam_unix module that comes with the Linux | |
10228 | PAM package is available from http://www.e-admin.de/pam_exim/. The patched | |
10229 | module allows one special uid/gid combination, in addition to root, to | |
10230 | authenticate. If you build the patched module to allow the Exim user and | |
10231 | group, PAM can then be used from an Exim authenticator. | |
10232 | ||
10233 | pwcheck {<string1>:<string2>} | |
10234 | ||
10235 | This condition supports user authentication using the Cyrus pwcheck daemon. | |
10236 | This is one way of making it possible for passwords to be checked by a | |
10237 | process that is not running as root. Note: The use of pwcheck is now | |
10238 | deprecated. Its replacement is saslauthd (see below). | |
10239 | ||
10240 | The pwcheck support is not included in Exim by default. You need to specify | |
10241 | the location of the pwcheck daemon's socket in Local/Makefile before | |
10242 | building Exim. For example: | |
10243 | ||
10244 | CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck | |
10245 | ||
10246 | You do not need to install the full Cyrus software suite in order to use | |
10247 | the pwcheck daemon. You can compile and install just the daemon alone from | |
10248 | the Cyrus SASL library. Ensure that exim is the only user that has access | |
10249 | to the /var/pwcheck directory. | |
10250 | ||
10251 | The pwcheck condition takes one argument, which must be the user name and | |
10252 | password, separated by a colon. For example, in a LOGIN authenticator | |
10253 | configuration, you might have this: | |
10254 | ||
10255 | server_condition = ${if pwcheck{$auth1:$auth2}} | |
10256 | ||
10257 | Again, for a PLAIN authenticator configuration, this would be: | |
10258 | ||
10259 | server_condition = ${if pwcheck{$auth2:$auth3}} | |
10260 | ||
10261 | queue_running | |
10262 | ||
10263 | This condition, which has no data, is true during delivery attempts that | |
10264 | are initiated by queue runner processes, and false otherwise. | |
10265 | ||
10266 | radius {<authentication string>} | |
10267 | ||
10268 | Radius authentication (RFC 2865) is supported in a similar way to PAM. You | |
10269 | must set RADIUS_CONFIG_FILE in Local/Makefile to specify the location of | |
10270 | the Radius client configuration file in order to build Exim with Radius | |
10271 | support. | |
10272 | ||
10273 | With just that one setting, Exim expects to be linked with the radiusclient | |
10274 | library, using the original API. If you are using release 0.4.0 or later of | |
10275 | this library, you need to set | |
10276 | ||
10277 | RADIUS_LIB_TYPE=RADIUSCLIENTNEW | |
10278 | ||
10279 | in Local/Makefile when building Exim. You can also link Exim with the | |
10280 | libradius library that comes with FreeBSD. To do this, set | |
10281 | ||
10282 | RADIUS_LIB_TYPE=RADLIB | |
10283 | ||
10284 | in Local/Makefile, in addition to setting RADIUS_CONFIGURE_FILE. You may | |
10285 | also have to supply a suitable setting in EXTRALIBS so that the Radius | |
10286 | library can be found when Exim is linked. | |
10287 | ||
10288 | The string specified by RADIUS_CONFIG_FILE is expanded and passed to the | |
10289 | Radius client library, which calls the Radius server. The condition is true | |
10290 | if the authentication is successful. For example: | |
10291 | ||
10292 | server_condition = ${if radius{<arguments>}} | |
10293 | ||
10294 | saslauthd {{<user>}{<password>}{<service>}{<realm>}} | |
10295 | ||
10296 | This condition supports user authentication using the Cyrus saslauthd | |
10297 | daemon. This replaces the older pwcheck daemon, which is now deprecated. | |
10298 | Using this daemon is one way of making it possible for passwords to be | |
10299 | checked by a process that is not running as root. | |
10300 | ||
10301 | The saslauthd support is not included in Exim by default. You need to | |
10302 | specify the location of the saslauthd daemon's socket in Local/Makefile | |
10303 | before building Exim. For example: | |
10304 | ||
10305 | CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux | |
10306 | ||
10307 | You do not need to install the full Cyrus software suite in order to use | |
10308 | the saslauthd daemon. You can compile and install just the daemon alone | |
10309 | from the Cyrus SASL library. | |
10310 | ||
10311 | Up to four arguments can be supplied to the saslauthd condition, but only | |
10312 | two are mandatory. For example: | |
10313 | ||
10314 | server_condition = ${if saslauthd{{$auth1}{$auth2}}} | |
10315 | ||
10316 | The service and the realm are optional (which is why the arguments are | |
10317 | enclosed in their own set of braces). For details of the meaning of the | |
10318 | service and realm, and how to run the daemon, consult the Cyrus | |
10319 | documentation. | |
10320 | ||
10321 | ||
10322 | 11.8 Combining expansion conditions | |
10323 | ----------------------------------- | |
10324 | ||
10325 | Several conditions can be tested at once by combining them using the and and or | |
10326 | combination conditions. Note that and and or are complete conditions on their | |
10327 | own, and precede their lists of sub-conditions. Each sub-condition must be | |
10328 | enclosed in braces within the overall braces that contain the list. No | |
10329 | repetition of if is used. | |
10330 | ||
10331 | or {{<cond1>}{<cond2>}...} | |
10332 | ||
10333 | The sub-conditions are evaluated from left to right. The condition is true | |
10334 | if any one of the sub-conditions is true. For example, | |
10335 | ||
10336 | ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}... | |
10337 | ||
10338 | When a true sub-condition is found, the following ones are parsed but not | |
10339 | evaluated. If there are several "match" sub-conditions the values of the | |
10340 | numeric variables afterwards are taken from the first one that succeeds. | |
10341 | ||
10342 | and {{<cond1>}{<cond2>}...} | |
10343 | ||
10344 | The sub-conditions are evaluated from left to right. The condition is true | |
10345 | if all of the sub-conditions are true. If there are several "match" | |
10346 | sub-conditions, the values of the numeric variables afterwards are taken | |
10347 | from the last one. When a false sub-condition is found, the following ones | |
10348 | are parsed but not evaluated. | |
10349 | ||
10350 | ||
10351 | 11.9 Expansion variables | |
10352 | ------------------------ | |
10353 | ||
10354 | This section contains an alphabetical list of all the expansion variables. Some | |
10355 | of them are available only when Exim is compiled with specific options such as | |
10356 | support for TLS or the content scanning extension. | |
10357 | ||
10358 | $0, $1, etc | |
10359 | ||
10360 | When a match expansion condition succeeds, these variables contain the | |
10361 | captured substrings identified by the regular expression during subsequent | |
2813c06e CE |
10362 | processing of the success string of the containing if expansion item. In |
10363 | the expansion condition case they do not retain their values afterwards; in | |
10364 | fact, their previous values are restored at the end of processing an if | |
10365 | item. The numerical variables may also be set externally by some other | |
10366 | matching process which precedes the expansion of the string. For example, | |
10367 | the commands available in Exim filter files include an if command with its | |
10368 | own regular expression matching condition. | |
420a0d19 CE |
10369 | |
10370 | $acl_arg1, $acl_arg2, etc | |
10371 | ||
10372 | Within an acl condition, expansion condition or expansion item any | |
10373 | arguments are copied to these variables, any unused variables being made | |
10374 | empty. | |
10375 | ||
10376 | $acl_c... | |
10377 | ||
10378 | Values can be placed in these variables by the set modifier in an ACL. They | |
10379 | can be given any name that starts with $acl_c and is at least six | |
10380 | characters long, but the sixth character must be either a digit or an | |
10381 | underscore. For example: $acl_c5, $acl_c_mycount. The values of the | |
10382 | $acl_c... variables persist throughout the lifetime of an SMTP connection. | |
10383 | They can be used to pass information between ACLs and between different | |
10384 | invocations of the same ACL. When a message is received, the values of | |
10385 | these variables are saved with the message, and can be accessed by filters, | |
10386 | routers, and transports during subsequent delivery. | |
10387 | ||
10388 | $acl_m... | |
10389 | ||
10390 | These variables are like the $acl_c... variables, except that their values | |
10391 | are reset after a message has been received. Thus, if several messages are | |
10392 | received in one SMTP connection, $acl_m... values are not passed on from | |
10393 | one message to the next, as $acl_c... values are. The $acl_m... variables | |
10394 | are also reset by MAIL, RSET, EHLO, HELO, and after starting a TLS session. | |
10395 | When a message is received, the values of these variables are saved with | |
10396 | the message, and can be accessed by filters, routers, and transports during | |
10397 | subsequent delivery. | |
10398 | ||
10399 | $acl_narg | |
10400 | ||
10401 | Within an acl condition, expansion condition or expansion item this | |
10402 | variable has the number of arguments. | |
10403 | ||
10404 | $acl_verify_message | |
10405 | ||
10406 | After an address verification has failed, this variable contains the | |
10407 | failure message. It retains its value for use in subsequent modifiers. The | |
10408 | message can be preserved by coding like this: | |
10409 | ||
10410 | warn !verify = sender | |
10411 | set acl_m0 = $acl_verify_message | |
10412 | ||
10413 | You can use $acl_verify_message during the expansion of the message or | |
10414 | log_message modifiers, to include information about the verification | |
10415 | failure. | |
10416 | ||
10417 | $address_data | |
10418 | ||
10419 | This variable is set by means of the address_data option in routers. The | |
10420 | value then remains with the address while it is processed by subsequent | |
10421 | routers and eventually a transport. If the transport is handling multiple | |
10422 | addresses, the value from the first address is used. See chapter 15 for | |
10423 | more details. Note: The contents of $address_data are visible in user | |
10424 | filter files. | |
10425 | ||
10426 | If $address_data is set when the routers are called from an ACL to verify a | |
10427 | recipient address, the final value is still in the variable for subsequent | |
10428 | conditions and modifiers of the ACL statement. If routing the address | |
10429 | caused it to be redirected to just one address, the child address is also | |
10430 | routed as part of the verification, and in this case the final value of | |
10431 | $address_data is from the child's routing. | |
10432 | ||
10433 | If $address_data is set when the routers are called from an ACL to verify a | |
10434 | sender address, the final value is also preserved, but this time in | |
10435 | $sender_address_data, to distinguish it from data from a recipient address. | |
10436 | ||
10437 | In both cases (recipient and sender verification), the value does not | |
10438 | persist after the end of the current ACL statement. If you want to preserve | |
10439 | these values for longer, you can save them in ACL variables. | |
10440 | ||
10441 | $address_file | |
10442 | ||
10443 | When, as a result of aliasing, forwarding, or filtering, a message is | |
10444 | directed to a specific file, this variable holds the name of the file when | |
10445 | the transport is running. At other times, the variable is empty. For | |
10446 | example, using the default configuration, if user r2d2 has a .forward file | |
10447 | containing | |
10448 | ||
10449 | /home/r2d2/savemail | |
10450 | ||
10451 | then when the address_file transport is running, $address_file contains the | |
10452 | text string "/home/r2d2/savemail". For Sieve filters, the value may be | |
10453 | "inbox" or a relative folder name. It is then up to the transport | |
10454 | configuration to generate an appropriate absolute path to the relevant | |
10455 | file. | |
10456 | ||
10457 | $address_pipe | |
10458 | ||
10459 | When, as a result of aliasing or forwarding, a message is directed to a | |
10460 | pipe, this variable holds the pipe command when the transport is running. | |
10461 | ||
10462 | $auth1 - $auth3 | |
10463 | ||
2813c06e | 10464 | These variables are used in SMTP authenticators (see chapters 34-41). |
420a0d19 CE |
10465 | Elsewhere, they are empty. |
10466 | ||
10467 | $authenticated_id | |
10468 | ||
10469 | When a server successfully authenticates a client it may be configured to | |
10470 | preserve some of the authentication information in the variable | |
10471 | $authenticated_id (see chapter 33). For example, a user/password | |
10472 | authenticator configuration might preserve the user name for use in the | |
10473 | routers. Note that this is not the same information that is saved in | |
10474 | $sender_host_authenticated. When a message is submitted locally (that is, | |
10475 | not over a TCP connection) the value of $authenticated_id is normally the | |
10476 | login name of the calling process. However, a trusted user can override | |
10477 | this by means of the -oMai command line option. | |
10478 | ||
10479 | $authenticated_fail_id | |
10480 | ||
10481 | When an authentication attempt fails, the variable $authenticated_fail_id | |
10482 | will contain the failed authentication id. If more than one authentication | |
10483 | id is attempted, it will contain only the last one. The variable is | |
10484 | available for processing in the ACL's, generally the quit or notquit ACL. A | |
10485 | message to a local recipient could still be accepted without requiring | |
10486 | authentication, which means this variable could also be visible in all of | |
10487 | the ACL's as well. | |
10488 | ||
10489 | $authenticated_sender | |
10490 | ||
10491 | When acting as a server, Exim takes note of the AUTH= parameter on an | |
10492 | incoming SMTP MAIL command if it believes the sender is sufficiently | |
10493 | trusted, as described in section 33.2. Unless the data is the string "<>", | |
10494 | it is set as the authenticated sender of the message, and the value is | |
10495 | available during delivery in the $authenticated_sender variable. If the | |
10496 | sender is not trusted, Exim accepts the syntax of AUTH=, but ignores the | |
10497 | data. | |
10498 | ||
10499 | When a message is submitted locally (that is, not over a TCP connection), | |
10500 | the value of $authenticated_sender is an address constructed from the login | |
10501 | name of the calling process and $qualify_domain, except that a trusted user | |
10502 | can override this by means of the -oMas command line option. | |
10503 | ||
10504 | $authentication_failed | |
10505 | ||
10506 | This variable is set to "1" in an Exim server if a client issues an AUTH | |
10507 | command that does not succeed. Otherwise it is set to "0". This makes it | |
10508 | possible to distinguish between "did not try to authenticate" ( | |
10509 | $sender_host_authenticated is empty and $authentication_failed is set to | |
10510 | "0") and "tried to authenticate but failed" ($sender_host_authenticated is | |
10511 | empty and $authentication_failed is set to "1"). Failure includes any | |
10512 | negative response to an AUTH command, including (for example) an attempt to | |
10513 | use an undefined mechanism. | |
10514 | ||
10515 | $av_failed | |
10516 | ||
10517 | This variable is available when Exim is compiled with the content-scanning | |
10518 | extension. It is set to "0" by default, but will be set to "1" if any | |
10519 | problem occurs with the virus scanner (specified by av_scanner) during the | |
10520 | ACL malware condition. | |
10521 | ||
10522 | $body_linecount | |
10523 | ||
10524 | When a message is being received or delivered, this variable contains the | |
10525 | number of lines in the message's body. See also $message_linecount. | |
10526 | ||
10527 | $body_zerocount | |
10528 | ||
10529 | When a message is being received or delivered, this variable contains the | |
10530 | number of binary zero bytes (ASCII NULs) in the message's body. | |
10531 | ||
10532 | $bounce_recipient | |
10533 | ||
10534 | This is set to the recipient address of a bounce message while Exim is | |
10535 | creating it. It is useful if a customized bounce message text file is in | |
2813c06e | 10536 | use (see chapter 49). |
420a0d19 CE |
10537 | |
10538 | $bounce_return_size_limit | |
10539 | ||
10540 | This contains the value set in the bounce_return_size_limit option, rounded | |
10541 | up to a multiple of 1000. It is useful when a customized error message text | |
2813c06e | 10542 | file is in use (see chapter 49). |
420a0d19 CE |
10543 | |
10544 | $caller_gid | |
10545 | ||
10546 | The real group id under which the process that called Exim was running. | |
10547 | This is not the same as the group id of the originator of a message (see | |
10548 | $originator_gid). If Exim re-execs itself, this variable in the new | |
10549 | incarnation normally contains the Exim gid. | |
10550 | ||
10551 | $caller_uid | |
10552 | ||
10553 | The real user id under which the process that called Exim was running. This | |
10554 | is not the same as the user id of the originator of a message (see | |
10555 | $originator_uid). If Exim re-execs itself, this variable in the new | |
10556 | incarnation normally contains the Exim uid. | |
10557 | ||
2813c06e | 10558 | $callout_address |
420a0d19 | 10559 | |
2813c06e CE |
10560 | After a callout for verification, spamd or malware daemon service, the |
10561 | address that was connected to. | |
420a0d19 CE |
10562 | |
10563 | $compile_number | |
10564 | ||
10565 | The building process for Exim keeps a count of the number of times it has | |
10566 | been compiled. This serves to distinguish different compilations of the | |
10567 | same version of the program. | |
10568 | ||
2813c06e | 10569 | $config_dir |
420a0d19 | 10570 | |
2813c06e CE |
10571 | The directory name of the main configuration file. That is, the content of |
10572 | $config_file with the last component stripped. The value does not contain | |
10573 | the trailing slash. If $config_file does not contain a slash, $config_dir | |
10574 | is ".". | |
420a0d19 | 10575 | |
2813c06e | 10576 | $config_file |
420a0d19 | 10577 | |
2813c06e CE |
10578 | The name of the main configuration file Exim is using. |
10579 | ||
10580 | $dkim_cur_signer, $dkim_verify_status, $dkim_verify_reason, $dkim_domain, | |
10581 | $dkim_identity, $dkim_selector, $dkim_algo, $dkim_canon_body, | |
10582 | $dkim_canon_headers, $dkim_copiedheaders, $dkim_bodylength, $dkim_created, | |
10583 | $dkim_expires, $dkim_headernames, $dkim_key_testing, $dkim_key_nosubdomains | |
10584 | , $dkim_key_srvtype, $dkim_key_granularity, $dkim_key_notes, | |
10585 | $dkim_key_length | |
10586 | ||
10587 | These variables are only available within the DKIM ACL. For details see | |
10588 | chapter 57. | |
10589 | ||
10590 | $dkim_signers | |
10591 | ||
10592 | When a message has been received this variable contains a colon-separated | |
10593 | list of signer domains and identities for the message. For details see | |
10594 | chapter 57. | |
420a0d19 CE |
10595 | |
10596 | $dnslist_domain, $dnslist_matched, $dnslist_text, $dnslist_value | |
10597 | ||
10598 | When a DNS (black) list lookup succeeds, these variables are set to contain | |
10599 | the following data from the lookup: the list's domain name, the key that | |
10600 | was looked up, the contents of any associated TXT record, and the value | |
2813c06e | 10601 | from the main A record. See section 43.32 for more details. |
420a0d19 CE |
10602 | |
10603 | $domain | |
10604 | ||
10605 | When an address is being routed, or delivered on its own, this variable | |
10606 | contains the domain. Uppercase letters in the domain are converted into | |
10607 | lower case for $domain. | |
10608 | ||
10609 | Global address rewriting happens when a message is received, so the value | |
10610 | of $domain during routing and delivery is the value after rewriting. | |
10611 | $domain is set during user filtering, but not during system filtering, | |
10612 | because a message may have many recipients and the system filter is called | |
10613 | just once. | |
10614 | ||
10615 | When more than one address is being delivered at once (for example, several | |
10616 | RCPT commands in one SMTP delivery), $domain is set only if they all have | |
10617 | the same domain. Transports can be restricted to handling only one domain | |
10618 | at a time if the value of $domain is required at transport time - this is | |
10619 | the default for local transports. For further details of the environment in | |
10620 | which local transports are run, see chapter 23. | |
10621 | ||
10622 | At the end of a delivery, if all deferred addresses have the same domain, | |
10623 | it is set in $domain during the expansion of delay_warning_condition. | |
10624 | ||
10625 | The $domain variable is also used in some other circumstances: | |
10626 | ||
2813c06e | 10627 | + When an ACL is running for a RCPT command, $domain contains the domain |
420a0d19 CE |
10628 | of the recipient address. The domain of the sender address is in |
10629 | $sender_address_domain at both MAIL time and at RCPT time. $domain is | |
10630 | not normally set during the running of the MAIL ACL. However, if the | |
10631 | sender address is verified with a callout during the MAIL ACL, the | |
10632 | sender domain is placed in $domain during the expansions of hosts, | |
10633 | interface, and port in the smtp transport. | |
10634 | ||
2813c06e | 10635 | + When a rewrite item is being processed (see chapter 31), $domain |
420a0d19 CE |
10636 | contains the domain portion of the address that is being rewritten; it |
10637 | can be used in the expansion of the replacement address, for example, | |
10638 | to rewrite domains by file lookup. | |
10639 | ||
2813c06e | 10640 | + With one important exception, whenever a domain list is being scanned, |
420a0d19 CE |
10641 | $domain contains the subject domain. Exception: When a domain list in a |
10642 | sender_domains condition in an ACL is being processed, the subject | |
10643 | domain is in $sender_address_domain and not in $domain. It works this | |
10644 | way so that, in a RCPT ACL, the sender domain list can be dependent on | |
10645 | the recipient domain (which is what is in $domain at this time). | |
10646 | ||
2813c06e CE |
10647 | + When the smtp_etrn_command option is being expanded, $domain contains |
10648 | the complete argument of the ETRN command (see section 48.8). | |
420a0d19 CE |
10649 | |
10650 | $domain_data | |
10651 | ||
10652 | When the domains option on a router matches a domain by means of a lookup, | |
10653 | the data read by the lookup is available during the running of the router | |
10654 | as $domain_data. In addition, if the driver routes the address to a | |
10655 | transport, the value is available in that transport. If the transport is | |
10656 | handling multiple addresses, the value from the first address is used. | |
10657 | ||
10658 | $domain_data is also set when the domains condition in an ACL matches a | |
10659 | domain by means of a lookup. The data read by the lookup is available | |
10660 | during the rest of the ACL statement. In all other situations, this | |
10661 | variable expands to nothing. | |
10662 | ||
10663 | $exim_gid | |
10664 | ||
10665 | This variable contains the numerical value of the Exim group id. | |
10666 | ||
10667 | $exim_path | |
10668 | ||
10669 | This variable contains the path to the Exim binary. | |
10670 | ||
10671 | $exim_uid | |
10672 | ||
10673 | This variable contains the numerical value of the Exim user id. | |
10674 | ||
2813c06e | 10675 | $exim_version |
420a0d19 | 10676 | |
2813c06e CE |
10677 | This variable contains the version string of the Exim build. The first |
10678 | character is a major version number, currently 4. Then after a dot, the | |
10679 | next group of digits is a minor version number. There may be other | |
10680 | characters following the minor version. | |
420a0d19 CE |
10681 | |
10682 | $header_<name> | |
10683 | ||
10684 | This is not strictly an expansion variable. It is expansion syntax for | |
10685 | inserting the message header line with the given name. Note that the name | |
10686 | must be terminated by colon or white space, because it may contain a wide | |
10687 | variety of characters. Note also that braces must not be used. | |
10688 | ||
10689 | $headers_added | |
10690 | ||
10691 | Within an ACL this variable contains the headers added so far by the ACL | |
2813c06e | 10692 | modifier add_header (section 43.24). The headers are a newline-separated |
420a0d19 CE |
10693 | list. |
10694 | ||
10695 | $home | |
10696 | ||
10697 | When the check_local_user option is set for a router, the user's home | |
10698 | directory is placed in $home when the check succeeds. In particular, this | |
10699 | means it is set during the running of users' filter files. A router may | |
10700 | also explicitly set a home directory for use by a transport; this can be | |
10701 | overridden by a setting on the transport itself. | |
10702 | ||
10703 | When running a filter test via the -bf option, $home is set to the value of | |
2813c06e CE |
10704 | the environment variable HOME, which is subject to the keep_environment and |
10705 | add_environment main config options. | |
420a0d19 CE |
10706 | |
10707 | $host | |
10708 | ||
10709 | If a router assigns an address to a transport (any transport), and passes a | |
10710 | list of hosts with the address, the value of $host when the transport | |
10711 | starts to run is the name of the first host on the list. Note that this | |
10712 | applies both to local and remote transports. | |
10713 | ||
10714 | For the smtp transport, if there is more than one host, the value of $host | |
10715 | changes as the transport works its way through the list. In particular, | |
10716 | when the smtp transport is expanding its options for encryption using TLS, | |
10717 | or for specifying a transport filter (see chapter 24), $host contains the | |
10718 | name of the host to which it is connected. | |
10719 | ||
10720 | When used in the client part of an authenticator configuration (see chapter | |
10721 | 33), $host contains the name of the server to which the client is | |
10722 | connected. | |
10723 | ||
10724 | $host_address | |
10725 | ||
10726 | This variable is set to the remote host's IP address whenever $host is set | |
10727 | for a remote connection. It is also set to the IP address that is being | |
10728 | checked when the ignore_target_hosts option is being processed. | |
10729 | ||
10730 | $host_data | |
10731 | ||
10732 | If a hosts condition in an ACL is satisfied by means of a lookup, the | |
10733 | result of the lookup is made available in the $host_data variable. This | |
10734 | allows you, for example, to do things like this: | |
10735 | ||
10736 | deny hosts = net-lsearch;/some/file | |
10737 | message = $host_data | |
10738 | ||
10739 | $host_lookup_deferred | |
10740 | ||
10741 | This variable normally contains "0", as does $host_lookup_failed. When a | |
10742 | message comes from a remote host and there is an attempt to look up the | |
10743 | host's name from its IP address, and the attempt is not successful, one of | |
10744 | these variables is set to "1". | |
10745 | ||
2813c06e | 10746 | + If the lookup receives a definite negative response (for example, a DNS |
420a0d19 CE |
10747 | lookup succeeded, but no records were found), $host_lookup_failed is |
10748 | set to "1". | |
10749 | ||
2813c06e | 10750 | + If there is any kind of problem during the lookup, such that Exim |
420a0d19 CE |
10751 | cannot tell whether or not the host name is defined (for example, a |
10752 | timeout for a DNS lookup), $host_lookup_deferred is set to "1". | |
10753 | ||
10754 | Looking up a host's name from its IP address consists of more than just a | |
10755 | single reverse lookup. Exim checks that a forward lookup of at least one of | |
10756 | the names it receives from a reverse lookup yields the original IP address. | |
10757 | If this is not the case, Exim does not accept the looked up name(s), and | |
10758 | $host_lookup_failed is set to "1". Thus, being able to find a name from an | |
10759 | IP address (for example, the existence of a PTR record in the DNS) is not | |
10760 | sufficient on its own for the success of a host name lookup. If the reverse | |
10761 | lookup succeeds, but there is a lookup problem such as a timeout when | |
10762 | checking the result, the name is not accepted, and $host_lookup_deferred is | |
10763 | set to "1". See also $sender_host_name. | |
10764 | ||
10765 | $host_lookup_failed | |
10766 | ||
10767 | See $host_lookup_deferred. | |
10768 | ||
2813c06e CE |
10769 | $host_port |
10770 | ||
10771 | This variable is set to the remote host's TCP port whenever $host is set | |
10772 | for an outbound connection. | |
10773 | ||
10774 | $initial_cwd | |
10775 | ||
10776 | This variable contains the full path name of the initial working directory | |
10777 | of the current Exim process. This may differ from the current working | |
10778 | directory, as Exim changes this to "/" during early startup, and to | |
10779 | $spool_directory later. | |
10780 | ||
420a0d19 CE |
10781 | $inode |
10782 | ||
10783 | The only time this variable is set is while expanding the directory_file | |
10784 | option in the appendfile transport. The variable contains the inode number | |
10785 | of the temporary file which is about to be renamed. It can be used to | |
10786 | construct a unique name for the file. | |
10787 | ||
10788 | $interface_address | |
10789 | ||
10790 | This is an obsolete name for $received_ip_address. | |
10791 | ||
10792 | $interface_port | |
10793 | ||
10794 | This is an obsolete name for $received_port. | |
10795 | ||
10796 | $item | |
10797 | ||
10798 | This variable is used during the expansion of forall and forany conditions | |
10799 | (see section 11.7), and filter, map, and reduce items (see section 11.7). | |
10800 | In other circumstances, it is empty. | |
10801 | ||
10802 | $ldap_dn | |
10803 | ||
10804 | This variable, which is available only when Exim is compiled with LDAP | |
10805 | support, contains the DN from the last entry in the most recently | |
10806 | successful LDAP lookup. | |
10807 | ||
10808 | $load_average | |
10809 | ||
10810 | This variable contains the system load average, multiplied by 1000 so that | |
10811 | it is an integer. For example, if the load average is 0.21, the value of | |
10812 | the variable is 210. The value is recomputed every time the variable is | |
10813 | referenced. | |
10814 | ||
10815 | $local_part | |
10816 | ||
10817 | When an address is being routed, or delivered on its own, this variable | |
10818 | contains the local part. When a number of addresses are being delivered | |
10819 | together (for example, multiple RCPT commands in an SMTP session), | |
10820 | $local_part is not set. | |
10821 | ||
10822 | Global address rewriting happens when a message is received, so the value | |
10823 | of $local_part during routing and delivery is the value after rewriting. | |
10824 | $local_part is set during user filtering, but not during system filtering, | |
10825 | because a message may have many recipients and the system filter is called | |
10826 | just once. | |
10827 | ||
10828 | If a local part prefix or suffix has been recognized, it is not included in | |
10829 | the value of $local_part during routing and subsequent delivery. The values | |
10830 | of any prefix or suffix are in $local_part_prefix and $local_part_suffix, | |
10831 | respectively. | |
10832 | ||
10833 | When a message is being delivered to a file, pipe, or autoreply transport | |
10834 | as a result of aliasing or forwarding, $local_part is set to the local part | |
10835 | of the parent address, not to the file name or command (see $address_file | |
10836 | and $address_pipe). | |
10837 | ||
10838 | When an ACL is running for a RCPT command, $local_part contains the local | |
10839 | part of the recipient address. | |
10840 | ||
10841 | When a rewrite item is being processed (see chapter 31), $local_part | |
10842 | contains the local part of the address that is being rewritten; it can be | |
10843 | used in the expansion of the replacement address, for example. | |
10844 | ||
10845 | In all cases, all quoting is removed from the local part. For example, for | |
10846 | both the addresses | |
10847 | ||
10848 | "abc:xyz"@test.example | |
10849 | abc\:xyz@test.example | |
10850 | ||
10851 | the value of $local_part is | |
10852 | ||
10853 | abc:xyz | |
10854 | ||
10855 | If you use $local_part to create another address, you should always wrap it | |
10856 | inside a quoting operator. For example, in a redirect router you could | |
10857 | have: | |
10858 | ||
10859 | data = ${quote_local_part:$local_part}@new.domain.example | |
10860 | ||
10861 | Note: The value of $local_part is normally lower cased. If you want to | |
10862 | process local parts in a case-dependent manner in a router, you can set the | |
10863 | caseful_local_part option (see chapter 15). | |
10864 | ||
10865 | $local_part_data | |
10866 | ||
10867 | When the local_parts option on a router matches a local part by means of a | |
10868 | lookup, the data read by the lookup is available during the running of the | |
10869 | router as $local_part_data. In addition, if the driver routes the address | |
10870 | to a transport, the value is available in that transport. If the transport | |
10871 | is handling multiple addresses, the value from the first address is used. | |
10872 | ||
10873 | $local_part_data is also set when the local_parts condition in an ACL | |
10874 | matches a local part by means of a lookup. The data read by the lookup is | |
10875 | available during the rest of the ACL statement. In all other situations, | |
10876 | this variable expands to nothing. | |
10877 | ||
10878 | $local_part_prefix | |
10879 | ||
10880 | When an address is being routed or delivered, and a specific prefix for the | |
10881 | local part was recognized, it is available in this variable, having been | |
10882 | removed from $local_part. | |
10883 | ||
10884 | $local_part_suffix | |
10885 | ||
10886 | When an address is being routed or delivered, and a specific suffix for the | |
10887 | local part was recognized, it is available in this variable, having been | |
10888 | removed from $local_part. | |
10889 | ||
10890 | $local_scan_data | |
10891 | ||
10892 | This variable contains the text returned by the local_scan() function when | |
2813c06e | 10893 | a message is received. See chapter 45 for more details. |
420a0d19 CE |
10894 | |
10895 | $local_user_gid | |
10896 | ||
10897 | See $local_user_uid. | |
10898 | ||
10899 | $local_user_uid | |
10900 | ||
10901 | This variable and $local_user_gid are set to the uid and gid after the | |
10902 | check_local_user router precondition succeeds. This means that their values | |
10903 | are available for the remaining preconditions (senders, require_files, and | |
10904 | condition), for the address_data expansion, and for any router-specific | |
10905 | expansions. At all other times, the values in these variables are "(uid_t) | |
10906 | (-1)" and "(gid_t)(-1)", respectively. | |
10907 | ||
10908 | $localhost_number | |
10909 | ||
10910 | This contains the expanded value of the localhost_number option. The | |
10911 | expansion happens after the main options have been read. | |
10912 | ||
10913 | $log_inodes | |
10914 | ||
10915 | The number of free inodes in the disk partition where Exim's log files are | |
10916 | being written. The value is recalculated whenever the variable is | |
10917 | referenced. If the relevant file system does not have the concept of | |
10918 | inodes, the value of is -1. See also the check_log_inodes option. | |
10919 | ||
10920 | $log_space | |
10921 | ||
10922 | The amount of free space (as a number of kilobytes) in the disk partition | |
10923 | where Exim's log files are being written. The value is recalculated | |
10924 | whenever the variable is referenced. If the operating system does not have | |
10925 | the ability to find the amount of free space (only true for experimental | |
10926 | systems), the space value is -1. See also the check_log_space option. | |
10927 | ||
10928 | $lookup_dnssec_authenticated | |
10929 | ||
10930 | This variable is set after a DNS lookup done by a dnsdb lookup expansion, | |
10931 | dnslookup router or smtp transport. It will be empty if DNSSEC was not | |
10932 | requested, "no" if the result was not labelled as authenticated data and | |
2813c06e CE |
10933 | "yes" if it was. Results that are labelled as authoritative answer that |
10934 | match the dns_trust_aa configuration variable count also as authenticated | |
10935 | data. | |
420a0d19 CE |
10936 | |
10937 | $mailstore_basename | |
10938 | ||
10939 | This variable is set only when doing deliveries in "mailstore" format in | |
10940 | the appendfile transport. During the expansion of the mailstore_prefix, | |
10941 | mailstore_suffix, message_prefix, and message_suffix options, it contains | |
10942 | the basename of the files that are being written, that is, the name without | |
10943 | the ".tmp", ".env", or ".msg" suffix. At all other times, this variable is | |
10944 | empty. | |
10945 | ||
10946 | $malware_name | |
10947 | ||
10948 | This variable is available when Exim is compiled with the content-scanning | |
10949 | extension. It is set to the name of the virus that was found when the ACL | |
2813c06e | 10950 | malware condition is true (see section 44.1). |
420a0d19 CE |
10951 | |
10952 | $max_received_linelength | |
10953 | ||
10954 | This variable contains the number of bytes in the longest line that was | |
10955 | received as part of the message, not counting the line termination | |
10956 | character(s). | |
10957 | ||
10958 | $message_age | |
10959 | ||
10960 | This variable is set at the start of a delivery attempt to contain the | |
10961 | number of seconds since the message was received. It does not change during | |
10962 | a single delivery attempt. | |
10963 | ||
10964 | $message_body | |
10965 | ||
10966 | This variable contains the initial portion of a message's body while it is | |
10967 | being delivered, and is intended mainly for use in filter files. The | |
10968 | maximum number of characters of the body that are put into the variable is | |
10969 | set by the message_body_visible configuration option; the default is 500. | |
10970 | ||
10971 | By default, newlines are converted into spaces in $message_body, to make it | |
10972 | easier to search for phrases that might be split over a line break. | |
10973 | However, this can be disabled by setting message_body_newlines to be true. | |
10974 | Binary zeros are always converted into spaces. | |
10975 | ||
10976 | $message_body_end | |
10977 | ||
10978 | This variable contains the final portion of a message's body while it is | |
10979 | being delivered. The format and maximum size are as for $message_body. | |
10980 | ||
10981 | $message_body_size | |
10982 | ||
10983 | When a message is being delivered, this variable contains the size of the | |
10984 | body in bytes. The count starts from the character after the blank line | |
10985 | that separates the body from the header. Newlines are included in the | |
10986 | count. See also $message_size, $body_linecount, and $body_zerocount. | |
10987 | ||
10988 | $message_exim_id | |
10989 | ||
10990 | When a message is being received or delivered, this variable contains the | |
10991 | unique message id that is generated and used by Exim to identify the | |
10992 | message. An id is not created for a message until after its header has been | |
10993 | successfully received. Note: This is not the contents of the Message-ID: | |
10994 | header line; it is the local id that Exim assigns to the message, for | |
10995 | example: "1BXTIK-0001yO-VA". | |
10996 | ||
10997 | $message_headers | |
10998 | ||
10999 | This variable contains a concatenation of all the header lines when a | |
11000 | message is being processed, except for lines added by routers or | |
11001 | transports. The header lines are separated by newline characters. Their | |
11002 | contents are decoded in the same way as a header line that is inserted by | |
11003 | bheader. | |
11004 | ||
11005 | $message_headers_raw | |
11006 | ||
11007 | This variable is like $message_headers except that no processing of the | |
11008 | contents of header lines is done. | |
11009 | ||
11010 | $message_id | |
11011 | ||
2813c06e | 11012 | This is an old name for $message_exim_id. It is now deprecated. |
420a0d19 CE |
11013 | |
11014 | $message_linecount | |
11015 | ||
11016 | This variable contains the total number of lines in the header and body of | |
11017 | the message. Compare $body_linecount, which is the count for the body only. | |
11018 | During the DATA and content-scanning ACLs, $message_linecount contains the | |
11019 | number of lines received. Before delivery happens (that is, before filters, | |
11020 | routers, and transports run) the count is increased to include the | |
11021 | Received: header line that Exim standardly adds, and also any other header | |
11022 | lines that are added by ACLs. The blank line that separates the message | |
11023 | header from the body is not counted. | |
11024 | ||
11025 | As with the special case of $message_size, during the expansion of the | |
11026 | appendfile transport's maildir_tag option in maildir format, the value of | |
11027 | $message_linecount is the precise size of the number of newlines in the | |
11028 | file that has been written (minus one for the blank line between the header | |
11029 | and the body). | |
11030 | ||
11031 | Here is an example of the use of this variable in a DATA ACL: | |
11032 | ||
11033 | deny message = Too many lines in message header | |
11034 | condition = \ | |
11035 | ${if <{250}{${eval:$message_linecount - $body_linecount}}} | |
11036 | ||
11037 | In the MAIL and RCPT ACLs, the value is zero because at that stage the | |
11038 | message has not yet been received. | |
11039 | ||
11040 | $message_size | |
11041 | ||
11042 | When a message is being processed, this variable contains its size in | |
11043 | bytes. In most cases, the size includes those headers that were received | |
11044 | with the message, but not those (such as Envelope-to:) that are added to | |
11045 | individual deliveries as they are written. However, there is one special | |
11046 | case: during the expansion of the maildir_tag option in the appendfile | |
11047 | transport while doing a delivery in maildir format, the value of | |
11048 | $message_size is the precise size of the file that has been written. See | |
11049 | also $message_body_size, $body_linecount, and $body_zerocount. | |
11050 | ||
11051 | While running a per message ACL (mail/rcpt/predata), $message_size contains | |
11052 | the size supplied on the MAIL command, or -1 if no size was given. The | |
11053 | value may not, of course, be truthful. | |
11054 | ||
11055 | $mime_xxx | |
11056 | ||
11057 | A number of variables whose names start with $mime are available when Exim | |
11058 | is compiled with the content-scanning extension. For details, see section | |
2813c06e | 11059 | 44.4. |
420a0d19 CE |
11060 | |
11061 | $n0 - $n9 | |
11062 | ||
11063 | These variables are counters that can be incremented by means of the add | |
11064 | command in filter files. | |
11065 | ||
11066 | $original_domain | |
11067 | ||
11068 | When a top-level address is being processed for delivery, this contains the | |
11069 | same value as $domain. However, if a "child" address (for example, | |
11070 | generated by an alias, forward, or filter file) is being processed, this | |
11071 | variable contains the domain of the original address (lower cased). This | |
11072 | differs from $parent_domain only when there is more than one level of | |
11073 | aliasing or forwarding. When more than one address is being delivered in a | |
11074 | single transport run, $original_domain is not set. | |
11075 | ||
11076 | If a new address is created by means of a deliver command in a system | |
11077 | filter, it is set up with an artificial "parent" address. This has the | |
11078 | local part system-filter and the default qualify domain. | |
11079 | ||
11080 | $original_local_part | |
11081 | ||
11082 | When a top-level address is being processed for delivery, this contains the | |
11083 | same value as $local_part, unless a prefix or suffix was removed from the | |
11084 | local part, because $original_local_part always contains the full local | |
11085 | part. When a "child" address (for example, generated by an alias, forward, | |
11086 | or filter file) is being processed, this variable contains the full local | |
11087 | part of the original address. | |
11088 | ||
11089 | If the router that did the redirection processed the local part | |
11090 | case-insensitively, the value in $original_local_part is in lower case. | |
11091 | This variable differs from $parent_local_part only when there is more than | |
11092 | one level of aliasing or forwarding. When more than one address is being | |
11093 | delivered in a single transport run, $original_local_part is not set. | |
11094 | ||
11095 | If a new address is created by means of a deliver command in a system | |
11096 | filter, it is set up with an artificial "parent" address. This has the | |
11097 | local part system-filter and the default qualify domain. | |
11098 | ||
11099 | $originator_gid | |
11100 | ||
11101 | This variable contains the value of $caller_gid that was set when the | |
11102 | message was received. For messages received via the command line, this is | |
11103 | the gid of the sending user. For messages received by SMTP over TCP/IP, | |
11104 | this is normally the gid of the Exim user. | |
11105 | ||
11106 | $originator_uid | |
11107 | ||
11108 | The value of $caller_uid that was set when the message was received. For | |
11109 | messages received via the command line, this is the uid of the sending | |
11110 | user. For messages received by SMTP over TCP/IP, this is normally the uid | |
11111 | of the Exim user. | |
11112 | ||
11113 | $parent_domain | |
11114 | ||
11115 | This variable is similar to $original_domain (see above), except that it | |
11116 | refers to the immediately preceding parent address. | |
11117 | ||
11118 | $parent_local_part | |
11119 | ||
11120 | This variable is similar to $original_local_part (see above), except that | |
11121 | it refers to the immediately preceding parent address. | |
11122 | ||
11123 | $pid | |
11124 | ||
11125 | This variable contains the current process id. | |
11126 | ||
11127 | $pipe_addresses | |
11128 | ||
11129 | This is not an expansion variable, but is mentioned here because the string | |
11130 | "$pipe_addresses" is handled specially in the command specification for the | |
11131 | pipe transport (chapter 29) and in transport filters (described under | |
11132 | transport_filter in chapter 24). It cannot be used in general expansion | |
11133 | strings, and provokes an "unknown variable" error if encountered. | |
11134 | ||
11135 | $primary_hostname | |
11136 | ||
11137 | This variable contains the value set by primary_hostname in the | |
11138 | configuration file, or read by the uname() function. If uname() returns a | |
11139 | single-component name, Exim calls gethostbyname() (or getipnodebyname() | |
11140 | where available) in an attempt to acquire a fully qualified host name. See | |
11141 | also $smtp_active_hostname. | |
11142 | ||
2813c06e CE |
11143 | $proxy_external_address, $proxy_external_port, $proxy_local_address, |
11144 | $proxy_local_port, $proxy_session | |
11145 | ||
11146 | These variables are only available when built with Proxy Protocol or SOCKS5 | |
11147 | support. For details see chapter 58.1. | |
11148 | ||
11149 | $prdr_requested | |
11150 | ||
11151 | This variable is set to "yes" if PRDR was requested by the client for the | |
11152 | current message, otherwise "no". | |
11153 | ||
420a0d19 CE |
11154 | $prvscheck_address |
11155 | ||
11156 | This variable is used in conjunction with the prvscheck expansion item, | |
2813c06e | 11157 | which is described in sections 11.5 and 43.51. |
420a0d19 CE |
11158 | |
11159 | $prvscheck_keynum | |
11160 | ||
11161 | This variable is used in conjunction with the prvscheck expansion item, | |
2813c06e | 11162 | which is described in sections 11.5 and 43.51. |
420a0d19 CE |
11163 | |
11164 | $prvscheck_result | |
11165 | ||
11166 | This variable is used in conjunction with the prvscheck expansion item, | |
2813c06e | 11167 | which is described in sections 11.5 and 43.51. |
420a0d19 CE |
11168 | |
11169 | $qualify_domain | |
11170 | ||
11171 | The value set for the qualify_domain option in the configuration file. | |
11172 | ||
11173 | $qualify_recipient | |
11174 | ||
11175 | The value set for the qualify_recipient option in the configuration file, | |
11176 | or if not set, the value of $qualify_domain. | |
11177 | ||
2813c06e CE |
11178 | $queue_name |
11179 | ||
11180 | The name of the spool queue in use; empty for the default queue. | |
11181 | ||
420a0d19 CE |
11182 | $rcpt_count |
11183 | ||
11184 | When a message is being received by SMTP, this variable contains the number | |
11185 | of RCPT commands received for the current message. If this variable is used | |
11186 | in a RCPT ACL, its value includes the current command. | |
11187 | ||
11188 | $rcpt_defer_count | |
11189 | ||
11190 | When a message is being received by SMTP, this variable contains the number | |
11191 | of RCPT commands in the current message that have previously been rejected | |
11192 | with a temporary (4xx) response. | |
11193 | ||
11194 | $rcpt_fail_count | |
11195 | ||
11196 | When a message is being received by SMTP, this variable contains the number | |
11197 | of RCPT commands in the current message that have previously been rejected | |
11198 | with a permanent (5xx) response. | |
11199 | ||
11200 | $received_count | |
11201 | ||
11202 | This variable contains the number of Received: header lines in the message, | |
11203 | including the one added by Exim (so its value is always greater than zero). | |
11204 | It is available in the DATA ACL, the non-SMTP ACL, and while routing and | |
11205 | delivering. | |
11206 | ||
11207 | $received_for | |
11208 | ||
11209 | If there is only a single recipient address in an incoming message, this | |
11210 | variable contains that address when the Received: header line is being | |
11211 | built. The value is copied after recipient rewriting has happened, but | |
11212 | before the local_scan() function is run. | |
11213 | ||
11214 | $received_ip_address | |
11215 | ||
11216 | As soon as an Exim server starts processing an incoming TCP/IP connection, | |
11217 | this variable is set to the address of the local IP interface, and | |
11218 | $received_port is set to the local port number. (The remote IP address and | |
11219 | port are in $sender_host_address and $sender_host_port.) When testing with | |
11220 | -bh, the port value is -1 unless it has been set using the -oMi command | |
11221 | line option. | |
11222 | ||
11223 | As well as being useful in ACLs (including the "connect" ACL), these | |
11224 | variable could be used, for example, to make the file name for a TLS | |
11225 | certificate depend on which interface and/or port is being used for the | |
11226 | incoming connection. The values of $received_ip_address and $received_port | |
11227 | are saved with any messages that are received, thus making these variables | |
2813c06e CE |
11228 | available at delivery time. For outbound connections see |
11229 | $sending_ip_address. | |
420a0d19 CE |
11230 | |
11231 | $received_port | |
11232 | ||
11233 | See $received_ip_address. | |
11234 | ||
11235 | $received_protocol | |
11236 | ||
11237 | When a message is being processed, this variable contains the name of the | |
11238 | protocol by which it was received. Most of the names used by Exim are | |
11239 | defined by RFCs 821, 2821, and 3848. They start with "smtp" (the client | |
11240 | used HELO) or "esmtp" (the client used EHLO). This can be followed by "s" | |
11241 | for secure (encrypted) and/or "a" for authenticated. Thus, for example, if | |
11242 | the protocol is set to "esmtpsa", the message was received over an | |
11243 | encrypted SMTP connection and the client was successfully authenticated. | |
11244 | ||
11245 | Exim uses the protocol name "smtps" for the case when encryption is | |
11246 | automatically set up on connection without the use of STARTTLS (see | |
11247 | tls_on_connect_ports), and the client uses HELO to initiate the encrypted | |
11248 | SMTP session. The name "smtps" is also used for the rare situation where | |
11249 | the client initially uses EHLO, sets up an encrypted connection using | |
11250 | STARTTLS, and then uses HELO afterwards. | |
11251 | ||
11252 | The -oMr option provides a way of specifying a custom protocol name for | |
11253 | messages that are injected locally by trusted callers. This is commonly | |
11254 | used to identify messages that are being re-injected after some kind of | |
11255 | scanning. | |
11256 | ||
11257 | $received_time | |
11258 | ||
11259 | This variable contains the date and time when the current message was | |
11260 | received, as a number of seconds since the start of the Unix epoch. | |
11261 | ||
11262 | $recipient_data | |
11263 | ||
11264 | This variable is set after an indexing lookup success in an ACL recipients | |
11265 | condition. It contains the data from the lookup, and the value remains set | |
11266 | until the next recipients test. Thus, you can do things like this: | |
11267 | ||
11268 | require recipients = cdb*@;/some/file | |
11269 | deny some further test involving $recipient_data | |
11270 | ||
11271 | Warning: This variable is set only when a lookup is used as an indexing | |
11272 | method in the address list, using the semicolon syntax as in the example | |
11273 | above. The variable is not set for a lookup that is used as part of the | |
11274 | string expansion that all such lists undergo before being interpreted. | |
11275 | ||
11276 | $recipient_verify_failure | |
11277 | ||
11278 | In an ACL, when a recipient verification fails, this variable contains | |
11279 | information about the failure. It is set to one of the following words: | |
11280 | ||
2813c06e | 11281 | + "qualify": The address was unqualified (no domain), and the message was |
420a0d19 CE |
11282 | neither local nor came from an exempted host. |
11283 | ||
2813c06e | 11284 | + "route": Routing failed. |
420a0d19 | 11285 | |
2813c06e | 11286 | + "mail": Routing succeeded, and a callout was attempted; rejection |
420a0d19 CE |
11287 | occurred at or before the MAIL command (that is, on initial connection, |
11288 | HELO, or MAIL). | |
11289 | ||
2813c06e | 11290 | + "recipient": The RCPT command in a callout was rejected. |
420a0d19 | 11291 | |
2813c06e | 11292 | + "postmaster": The postmaster check in a callout was rejected. |
420a0d19 CE |
11293 | |
11294 | The main use of this variable is expected to be to distinguish between | |
11295 | rejections of MAIL and rejections of RCPT. | |
11296 | ||
11297 | $recipients | |
11298 | ||
11299 | This variable contains a list of envelope recipients for a message. A comma | |
11300 | and a space separate the addresses in the replacement text. However, the | |
11301 | variable is not generally available, to prevent exposure of Bcc recipients | |
11302 | in unprivileged users' filter files. You can use $recipients only in these | |
11303 | cases: | |
11304 | ||
11305 | 1. In a system filter file. | |
11306 | ||
11307 | 2. In the ACLs associated with the DATA command and with non-SMTP | |
11308 | messages, that is, the ACLs defined by acl_smtp_predata, acl_smtp_data, | |
11309 | acl_smtp_mime, acl_not_smtp_start, acl_not_smtp, and acl_not_smtp_mime. | |
11310 | ||
11311 | 3. From within a local_scan() function. | |
11312 | ||
11313 | $recipients_count | |
11314 | ||
11315 | When a message is being processed, this variable contains the number of | |
11316 | envelope recipients that came with the message. Duplicates are not excluded | |
11317 | from the count. While a message is being received over SMTP, the number | |
11318 | increases for each accepted recipient. It can be referenced in an ACL. | |
11319 | ||
11320 | $regex_match_string | |
11321 | ||
11322 | This variable is set to contain the matching regular expression after a | |
2813c06e CE |
11323 | regex ACL condition has matched (see section 44.5). |
11324 | ||
11325 | $regex1, $regex2, etc | |
11326 | ||
11327 | When a regex or mime_regex ACL condition succeeds, these variables contain | |
11328 | the captured substrings identified by the regular expression. | |
420a0d19 CE |
11329 | |
11330 | $reply_address | |
11331 | ||
11332 | When a message is being processed, this variable contains the contents of | |
11333 | the Reply-To: header line if one exists and it is not empty, or otherwise | |
11334 | the contents of the From: header line. Apart from the removal of leading | |
11335 | white space, the value is not processed in any way. In particular, no RFC | |
11336 | 2047 decoding or character code translation takes place. | |
11337 | ||
11338 | $return_path | |
11339 | ||
11340 | When a message is being delivered, this variable contains the return path - | |
11341 | the sender field that will be sent as part of the envelope. It is not | |
11342 | enclosed in <> characters. At the start of routing an address, $return_path | |
11343 | has the same value as $sender_address, but if, for example, an incoming | |
11344 | message to a mailing list has been expanded by a router which specifies a | |
11345 | different address for bounce messages, $return_path subsequently contains | |
11346 | the new bounce address, whereas $sender_address always contains the | |
11347 | original sender address that was received with the message. In other words, | |
11348 | $sender_address contains the incoming envelope sender, and $return_path | |
11349 | contains the outgoing envelope sender. | |
11350 | ||
11351 | $return_size_limit | |
11352 | ||
11353 | This is an obsolete name for $bounce_return_size_limit. | |
11354 | ||
11355 | $router_name | |
11356 | ||
11357 | During the running of a router this variable contains its name. | |
11358 | ||
11359 | $runrc | |
11360 | ||
11361 | This variable contains the return code from a command that is run by the $ | |
11362 | {run...} expansion item. Warning: In a router or transport, you cannot | |
11363 | assume the order in which option values are expanded, except for those | |
11364 | preconditions whose order of testing is documented. Therefore, you cannot | |
11365 | reliably expect to set $runrc by the expansion of one option, and use it in | |
11366 | another. | |
11367 | ||
11368 | $self_hostname | |
11369 | ||
11370 | When an address is routed to a supposedly remote host that turns out to be | |
11371 | the local host, what happens is controlled by the self generic router | |
11372 | option. One of its values causes the address to be passed to another | |
11373 | router. When this happens, $self_hostname is set to the name of the local | |
11374 | host that the original router encountered. In other circumstances its | |
11375 | contents are null. | |
11376 | ||
11377 | $sender_address | |
11378 | ||
11379 | When a message is being processed, this variable contains the sender's | |
11380 | address that was received in the message's envelope. The case of letters in | |
11381 | the address is retained, in both the local part and the domain. For bounce | |
11382 | messages, the value of this variable is the empty string. See also | |
11383 | $return_path. | |
11384 | ||
11385 | $sender_address_data | |
11386 | ||
11387 | If $address_data is set when the routers are called from an ACL to verify a | |
11388 | sender address, the final value is preserved in $sender_address_data, to | |
11389 | distinguish it from data from a recipient address. The value does not | |
11390 | persist after the end of the current ACL statement. If you want to preserve | |
11391 | it for longer, you can save it in an ACL variable. | |
11392 | ||
11393 | $sender_address_domain | |
11394 | ||
11395 | The domain portion of $sender_address. | |
11396 | ||
11397 | $sender_address_local_part | |
11398 | ||
11399 | The local part portion of $sender_address. | |
11400 | ||
11401 | $sender_data | |
11402 | ||
11403 | This variable is set after a lookup success in an ACL senders condition or | |
11404 | in a router senders option. It contains the data from the lookup, and the | |
11405 | value remains set until the next senders test. Thus, you can do things like | |
11406 | this: | |
11407 | ||
11408 | require senders = cdb*@;/some/file | |
11409 | deny some further test involving $sender_data | |
11410 | ||
11411 | Warning: This variable is set only when a lookup is used as an indexing | |
11412 | method in the address list, using the semicolon syntax as in the example | |
11413 | above. The variable is not set for a lookup that is used as part of the | |
11414 | string expansion that all such lists undergo before being interpreted. | |
11415 | ||
11416 | $sender_fullhost | |
11417 | ||
11418 | When a message is received from a remote host, this variable contains the | |
11419 | host name and IP address in a single string. It ends with the IP address in | |
11420 | square brackets, followed by a colon and a port number if the logging of | |
11421 | ports is enabled. The format of the rest of the string depends on whether | |
11422 | the host issued a HELO or EHLO SMTP command, and whether the host name was | |
11423 | verified by looking up its IP address. (Looking up the IP address can be | |
11424 | forced by the host_lookup option, independent of verification.) A plain | |
11425 | host name at the start of the string is a verified host name; if this is | |
11426 | not present, verification either failed or was not requested. A host name | |
11427 | in parentheses is the argument of a HELO or EHLO command. This is omitted | |
11428 | if it is identical to the verified host name or to the host's IP address in | |
11429 | square brackets. | |
11430 | ||
2813c06e CE |
11431 | $sender_helo_dnssec |
11432 | ||
11433 | This boolean variable is true if a successful HELO verification was done | |
11434 | using DNS information the resolver library stated was authenticated data. | |
11435 | ||
420a0d19 CE |
11436 | $sender_helo_name |
11437 | ||
11438 | When a message is received from a remote host that has issued a HELO or | |
11439 | EHLO command, the argument of that command is placed in this variable. It | |
11440 | is also set if HELO or EHLO is used when a message is received using SMTP | |
11441 | locally via the -bs or -bS options. | |
11442 | ||
11443 | $sender_host_address | |
11444 | ||
2813c06e CE |
11445 | When a message is received from a remote host using SMTP, this variable |
11446 | contains that host's IP address. For locally non-SMTP submitted messages, | |
11447 | it is empty. | |
420a0d19 CE |
11448 | |
11449 | $sender_host_authenticated | |
11450 | ||
11451 | This variable contains the name (not the public name) of the authenticator | |
11452 | driver that successfully authenticated the client from which the message | |
11453 | was received. It is empty if there was no successful authentication. See | |
11454 | also $authenticated_id. | |
11455 | ||
11456 | $sender_host_dnssec | |
11457 | ||
11458 | If an attempt to populate $sender_host_name has been made (by reference, | |
11459 | hosts_lookup or otherwise) then this boolean will have been set true if, | |
2813c06e CE |
11460 | and only if, the resolver library states that both the reverse and forward |
11461 | DNS were authenticated data. At all other times, this variable is false. | |
420a0d19 CE |
11462 | |
11463 | It is likely that you will need to coerce DNSSEC support on in the resolver | |
11464 | library, by setting: | |
11465 | ||
11466 | dns_dnssec_ok = 1 | |
11467 | ||
11468 | Exim does not perform DNSSEC validation itself, instead leaving that to a | |
2813c06e | 11469 | validating resolver (e.g. unbound, or bind with suitable configuration). |
420a0d19 CE |
11470 | |
11471 | If you have changed host_lookup_order so that "bydns" is not the first | |
11472 | mechanism in the list, then this variable will be false. | |
11473 | ||
2813c06e CE |
11474 | This requires that your system resolver library support EDNS0 (and that |
11475 | DNSSEC flags exist in the system headers). If the resolver silently drops | |
11476 | all EDNS0 options, then this will have no effect. OpenBSD's asr resolver is | |
11477 | known to currently ignore EDNS0, documented in CAVEATS of asr_run(3). | |
11478 | ||
420a0d19 CE |
11479 | $sender_host_name |
11480 | ||
11481 | When a message is received from a remote host, this variable contains the | |
11482 | host's name as obtained by looking up its IP address. For messages received | |
11483 | by other means, this variable is empty. | |
11484 | ||
11485 | If the host name has not previously been looked up, a reference to | |
11486 | $sender_host_name triggers a lookup (for messages from remote hosts). A | |
11487 | looked up name is accepted only if it leads back to the original IP address | |
11488 | via a forward lookup. If either the reverse or the forward lookup fails to | |
11489 | find any data, or if the forward lookup does not yield the original IP | |
11490 | address, $sender_host_name remains empty, and $host_lookup_failed is set to | |
11491 | "1". | |
11492 | ||
11493 | However, if either of the lookups cannot be completed (for example, there | |
11494 | is a DNS timeout), $host_lookup_deferred is set to "1", and | |
11495 | $host_lookup_failed remains set to "0". | |
11496 | ||
11497 | Once $host_lookup_failed is set to "1", Exim does not try to look up the | |
11498 | host name again if there is a subsequent reference to $sender_host_name in | |
11499 | the same Exim process, but it does try again if $host_lookup_deferred is | |
11500 | set to "1". | |
11501 | ||
11502 | Exim does not automatically look up every calling host's name. If you want | |
11503 | maximum efficiency, you should arrange your configuration so that it avoids | |
11504 | these lookups altogether. The lookup happens only if one or more of the | |
11505 | following are true: | |
11506 | ||
2813c06e | 11507 | + A string containing $sender_host_name is expanded. |
420a0d19 | 11508 | |
2813c06e | 11509 | + The calling host matches the list in host_lookup. In the default |
420a0d19 CE |
11510 | configuration, this option is set to *, so it must be changed if |
11511 | lookups are to be avoided. (In the code, the default for host_lookup is | |
11512 | unset.) | |
11513 | ||
2813c06e | 11514 | + Exim needs the host name in order to test an item in a host list. The |
420a0d19 CE |
11515 | items that require this are described in sections 10.13 and 10.17. |
11516 | ||
2813c06e | 11517 | + The calling host matches helo_try_verify_hosts or helo_verify_hosts. In |
420a0d19 CE |
11518 | this case, the host name is required to compare with the name quoted in |
11519 | any EHLO or HELO commands that the client issues. | |
11520 | ||
2813c06e | 11521 | + The remote host issues a EHLO or HELO command that quotes one of the |
420a0d19 CE |
11522 | domains in helo_lookup_domains. The default value of this option is |
11523 | ||
11524 | helo_lookup_domains = @ : @[] | |
11525 | ||
11526 | which causes a lookup if a remote host (incorrectly) gives the server's | |
11527 | name or IP address in an EHLO or HELO command. | |
11528 | ||
11529 | $sender_host_port | |
11530 | ||
11531 | When a message is received from a remote host, this variable contains the | |
11532 | port number that was used on the remote host. | |
11533 | ||
11534 | $sender_ident | |
11535 | ||
11536 | When a message is received from a remote host, this variable contains the | |
11537 | identification received in response to an RFC 1413 request. When a message | |
11538 | has been received locally, this variable contains the login name of the | |
11539 | user that called Exim. | |
11540 | ||
11541 | $sender_rate_xxx | |
11542 | ||
11543 | A number of variables whose names begin $sender_rate_ are set as part of | |
2813c06e | 11544 | the ratelimit ACL condition. Details are given in section 43.38. |
420a0d19 CE |
11545 | |
11546 | $sender_rcvhost | |
11547 | ||
11548 | This is provided specifically for use in Received: headers. It starts with | |
11549 | either the verified host name (as obtained from a reverse DNS lookup) or, | |
11550 | if there is no verified host name, the IP address in square brackets. After | |
11551 | that there may be text in parentheses. When the first item is a verified | |
11552 | host name, the first thing in the parentheses is the IP address in square | |
11553 | brackets, followed by a colon and a port number if port logging is enabled. | |
11554 | When the first item is an IP address, the port is recorded as "port=xxxx" | |
11555 | inside the parentheses. | |
11556 | ||
11557 | There may also be items of the form "helo=xxxx" if HELO or EHLO was used | |
11558 | and its argument was not identical to the real host name or IP address, and | |
11559 | "ident=xxxx" if an RFC 1413 ident string is available. If all three items | |
11560 | are present in the parentheses, a newline and tab are inserted into the | |
11561 | string, to improve the formatting of the Received: header. | |
11562 | ||
11563 | $sender_verify_failure | |
11564 | ||
11565 | In an ACL, when a sender verification fails, this variable contains | |
11566 | information about the failure. The details are the same as for | |
11567 | $recipient_verify_failure. | |
11568 | ||
11569 | $sending_ip_address | |
11570 | ||
11571 | This variable is set whenever an outgoing SMTP connection to another host | |
11572 | has been set up. It contains the IP address of the local interface that is | |
11573 | being used. This is useful if a host that has more than one IP address | |
11574 | wants to take on different personalities depending on which one is being | |
11575 | used. For incoming connections, see $received_ip_address. | |
11576 | ||
11577 | $sending_port | |
11578 | ||
11579 | This variable is set whenever an outgoing SMTP connection to another host | |
11580 | has been set up. It contains the local port that is being used. For | |
11581 | incoming connections, see $received_port. | |
11582 | ||
11583 | $smtp_active_hostname | |
11584 | ||
11585 | During an incoming SMTP session, this variable contains the value of the | |
11586 | active host name, as specified by the smtp_active_hostname option. The | |
11587 | value of $smtp_active_hostname is saved with any message that is received, | |
11588 | so its value can be consulted during routing and delivery. | |
11589 | ||
11590 | $smtp_command | |
11591 | ||
11592 | During the processing of an incoming SMTP command, this variable contains | |
11593 | the entire command. This makes it possible to distinguish between HELO and | |
11594 | EHLO in the HELO ACL, and also to distinguish between commands such as | |
11595 | these: | |
11596 | ||
11597 | MAIL FROM:<> | |
11598 | MAIL FROM: <> | |
11599 | ||
11600 | For a MAIL command, extra parameters such as SIZE can be inspected. For a | |
11601 | RCPT command, the address in $smtp_command is the original address before | |
11602 | any rewriting, whereas the values in $local_part and $domain are taken from | |
11603 | the address after SMTP-time rewriting. | |
11604 | ||
11605 | $smtp_command_argument | |
11606 | ||
11607 | While an ACL is running to check an SMTP command, this variable contains | |
11608 | the argument, that is, the text that follows the command name, with leading | |
11609 | white space removed. Following the introduction of $smtp_command, this | |
11610 | variable is somewhat redundant, but is retained for backwards | |
11611 | compatibility. | |
11612 | ||
11613 | $smtp_count_at_connection_start | |
11614 | ||
11615 | This variable is set greater than zero only in processes spawned by the | |
11616 | Exim daemon for handling incoming SMTP connections. The name is | |
11617 | deliberately long, in order to emphasize what the contents are. When the | |
11618 | daemon accepts a new connection, it increments this variable. A copy of the | |
11619 | variable is passed to the child process that handles the connection, but | |
11620 | its value is fixed, and never changes. It is only an approximation of how | |
11621 | many incoming connections there actually are, because many other | |
11622 | connections may come and go while a single connection is being processed. | |
11623 | When a child process terminates, the daemon decrements its copy of the | |
11624 | variable. | |
11625 | ||
11626 | $sn0 - $sn9 | |
11627 | ||
11628 | These variables are copies of the values of the $n0 - $n9 accumulators that | |
11629 | were current at the end of the system filter file. This allows a system | |
11630 | filter file to set values that can be tested in users' filter files. For | |
11631 | example, a system filter could set a value indicating how likely it is that | |
11632 | a message is junk mail. | |
11633 | ||
11634 | $spam_xxx | |
11635 | ||
11636 | A number of variables whose names start with $spam are available when Exim | |
11637 | is compiled with the content-scanning extension. For details, see section | |
2813c06e | 11638 | 44.2. |
420a0d19 CE |
11639 | |
11640 | $spool_directory | |
11641 | ||
11642 | The name of Exim's spool directory. | |
11643 | ||
11644 | $spool_inodes | |
11645 | ||
11646 | The number of free inodes in the disk partition where Exim's spool files | |
11647 | are being written. The value is recalculated whenever the variable is | |
11648 | referenced. If the relevant file system does not have the concept of | |
11649 | inodes, the value of is -1. See also the check_spool_inodes option. | |
11650 | ||
11651 | $spool_space | |
11652 | ||
11653 | The amount of free space (as a number of kilobytes) in the disk partition | |
11654 | where Exim's spool files are being written. The value is recalculated | |
11655 | whenever the variable is referenced. If the operating system does not have | |
11656 | the ability to find the amount of free space (only true for experimental | |
11657 | systems), the space value is -1. For example, to check in an ACL that there | |
11658 | is at least 50 megabytes free on the spool, you could write: | |
11659 | ||
11660 | condition = ${if > {$spool_space}{50000}} | |
11661 | ||
11662 | See also the check_spool_space option. | |
11663 | ||
11664 | $thisaddress | |
11665 | ||
11666 | This variable is set only during the processing of the foranyaddress | |
11667 | command in a filter file. Its use is explained in the description of that | |
11668 | command, which can be found in the separate document entitled Exim's | |
11669 | interfaces to mail filtering. | |
11670 | ||
11671 | $tls_in_bits | |
11672 | ||
11673 | Contains an approximation of the TLS cipher's bit-strength on the inbound | |
11674 | connection; the meaning of this depends upon the TLS implementation used. | |
11675 | If TLS has not been negotiated, the value will be 0. The value of this is | |
11676 | automatically fed into the Cyrus SASL authenticator when acting as a | |
11677 | server, to specify the "external SSF" (a SASL term). | |
11678 | ||
11679 | The deprecated $tls_bits variable refers to the inbound side except when | |
11680 | used in the context of an outbound SMTP delivery, when it refers to the | |
11681 | outbound. | |
11682 | ||
11683 | $tls_out_bits | |
11684 | ||
11685 | Contains an approximation of the TLS cipher's bit-strength on an outbound | |
11686 | SMTP connection; the meaning of this depends upon the TLS implementation | |
11687 | used. If TLS has not been negotiated, the value will be 0. | |
11688 | ||
11689 | $tls_in_ourcert | |
11690 | ||
11691 | This variable refers to the certificate presented to the peer of an inbound | |
11692 | connection when the message was received. It is only useful as the argument | |
2813c06e CE |
11693 | of a certextract expansion item, md5, sha1 or sha256 operator, or a def |
11694 | condition. | |
420a0d19 CE |
11695 | |
11696 | $tls_in_peercert | |
11697 | ||
11698 | This variable refers to the certificate presented by the peer of an inbound | |
11699 | connection when the message was received. It is only useful as the argument | |
2813c06e CE |
11700 | of a certextract expansion item, md5, sha1 or sha256 operator, or a def |
11701 | condition. If certificate verification fails it may refer to a failing | |
11702 | chain element which is not the leaf. | |
420a0d19 CE |
11703 | |
11704 | $tls_out_ourcert | |
11705 | ||
11706 | This variable refers to the certificate presented to the peer of an | |
11707 | outbound connection. It is only useful as the argument of a certextract | |
2813c06e | 11708 | expansion item, md5, sha1 or sha256 operator, or a def condition. |
420a0d19 CE |
11709 | |
11710 | $tls_out_peercert | |
11711 | ||
11712 | This variable refers to the certificate presented by the peer of an | |
11713 | outbound connection. It is only useful as the argument of a certextract | |
2813c06e CE |
11714 | expansion item, md5, sha1 or sha256 operator, or a def condition. If |
11715 | certificate verification fails it may refer to a failing chain element | |
11716 | which is not the leaf. | |
420a0d19 CE |
11717 | |
11718 | $tls_in_certificate_verified | |
11719 | ||
11720 | This variable is set to "1" if a TLS certificate was verified when the | |
11721 | message was received, and "0" otherwise. | |
11722 | ||
2813c06e CE |
11723 | The deprecated $tls_certificate_verified variable refers to the inbound |
11724 | side except when used in the context of an outbound SMTP delivery, when it | |
420a0d19 CE |
11725 | refers to the outbound. |
11726 | ||
11727 | $tls_out_certificate_verified | |
11728 | ||
11729 | This variable is set to "1" if a TLS certificate was verified when an | |
11730 | outbound SMTP connection was made, and "0" otherwise. | |
11731 | ||
11732 | $tls_in_cipher | |
11733 | ||
11734 | When a message is received from a remote host over an encrypted SMTP | |
11735 | connection, this variable is set to the cipher suite that was negotiated, | |
11736 | for example DES-CBC3-SHA. In other circumstances, in particular, for | |
11737 | message received over unencrypted connections, the variable is empty. | |
2813c06e | 11738 | Testing $tls_in_cipher for emptiness is one way of distinguishing between |
420a0d19 CE |
11739 | encrypted and non-encrypted connections during ACL processing. |
11740 | ||
11741 | The deprecated $tls_cipher variable is the same as $tls_in_cipher during | |
11742 | message reception, but in the context of an outward SMTP delivery taking | |
11743 | place via the smtp transport becomes the same as $tls_out_cipher. | |
11744 | ||
11745 | $tls_out_cipher | |
11746 | ||
11747 | This variable is cleared before any outgoing SMTP connection is made, and | |
2813c06e | 11748 | then set to the outgoing cipher suite if one is negotiated. See chapter 42 |
420a0d19 CE |
11749 | for details of TLS support and chapter 30 for details of the smtp |
11750 | transport. | |
11751 | ||
11752 | $tls_in_ocsp | |
11753 | ||
11754 | When a message is received from a remote client connection the result of | |
11755 | any OCSP request from the client is encoded in this variable: | |
11756 | ||
11757 | 0 OCSP proof was not requested (default value) | |
11758 | 1 No response to request | |
11759 | 2 Response not verified | |
11760 | 3 Verification failed | |
11761 | 4 Verification succeeded | |
11762 | ||
11763 | $tls_out_ocsp | |
11764 | ||
11765 | When a message is sent to a remote host connection the result of any OCSP | |
11766 | request made is encoded in this variable. See $tls_in_ocsp for values. | |
11767 | ||
11768 | $tls_in_peerdn | |
11769 | ||
11770 | When a message is received from a remote host over an encrypted SMTP | |
11771 | connection, and Exim is configured to request a certificate from the | |
11772 | client, the value of the Distinguished Name of the certificate is made | |
2813c06e CE |
11773 | available in the $tls_in_peerdn during subsequent processing. If |
11774 | certificate verification fails it may refer to a failing chain element | |
11775 | which is not the leaf. | |
420a0d19 CE |
11776 | |
11777 | The deprecated $tls_peerdn variable refers to the inbound side except when | |
11778 | used in the context of an outbound SMTP delivery, when it refers to the | |
11779 | outbound. | |
11780 | ||
11781 | $tls_out_peerdn | |
11782 | ||
11783 | When a message is being delivered to a remote host over an encrypted SMTP | |
11784 | connection, and Exim is configured to request a certificate from the | |
11785 | server, the value of the Distinguished Name of the certificate is made | |
2813c06e CE |
11786 | available in the $tls_out_peerdn during subsequent processing. If |
11787 | certificate verification fails it may refer to a failing chain element | |
11788 | which is not the leaf. | |
420a0d19 CE |
11789 | |
11790 | $tls_in_sni | |
11791 | ||
11792 | When a TLS session is being established, if the client sends the Server | |
11793 | Name Indication extension, the value will be placed in this variable. If | |
11794 | the variable appears in tls_certificate then this option and some others, | |
2813c06e | 11795 | described in 42.10, will be re-expanded early in the TLS session, to permit |
420a0d19 CE |
11796 | a different certificate to be presented (and optionally a different key to |
11797 | be used) to the client, based upon the value of the SNI extension. | |
11798 | ||
11799 | The deprecated $tls_sni variable refers to the inbound side except when | |
11800 | used in the context of an outbound SMTP delivery, when it refers to the | |
11801 | outbound. | |
11802 | ||
11803 | $tls_out_sni | |
11804 | ||
11805 | During outbound SMTP deliveries, this variable reflects the value of the | |
11806 | tls_sni option on the transport. | |
11807 | ||
11808 | $tod_bsdinbox | |
11809 | ||
11810 | The time of day and the date, in the format required for BSD-style mailbox | |
11811 | files, for example: Thu Oct 17 17:14:09 1995. | |
11812 | ||
11813 | $tod_epoch | |
11814 | ||
11815 | The time and date as a number of seconds since the start of the Unix epoch. | |
11816 | ||
11817 | $tod_epoch_l | |
11818 | ||
11819 | The time and date as a number of microseconds since the start of the Unix | |
11820 | epoch. | |
11821 | ||
11822 | $tod_full | |
11823 | ||
11824 | A full version of the time and date, for example: Wed, 16 Oct 1995 09:51:40 | |
11825 | +0100. The timezone is always given as a numerical offset from UTC, with | |
11826 | positive values used for timezones that are ahead (east) of UTC, and | |
11827 | negative values for those that are behind (west). | |
11828 | ||
11829 | $tod_log | |
11830 | ||
11831 | The time and date in the format used for writing Exim's log files, for | |
11832 | example: 1995-10-12 15:32:29, but without a timezone. | |
11833 | ||
11834 | $tod_logfile | |
11835 | ||
11836 | This variable contains the date in the format yyyymmdd. This is the format | |
11837 | that is used for datestamping log files when log_file_path contains the | |
11838 | "%D" flag. | |
11839 | ||
11840 | $tod_zone | |
11841 | ||
11842 | This variable contains the numerical value of the local timezone, for | |
11843 | example: -0500. | |
11844 | ||
11845 | $tod_zulu | |
11846 | ||
11847 | This variable contains the UTC date and time in "Zulu" format, as specified | |
11848 | by ISO 8601, for example: 20030221154023Z. | |
11849 | ||
11850 | $transport_name | |
11851 | ||
11852 | During the running of a transport, this variable contains its name. | |
11853 | ||
11854 | $value | |
11855 | ||
11856 | This variable contains the result of an expansion lookup, extraction | |
11857 | operation, or external command, as described above. It is also used during | |
11858 | a reduce expansion. | |
11859 | ||
2813c06e CE |
11860 | $verify_mode |
11861 | ||
11862 | While a router or transport is being run in verify mode or for cutthrough | |
11863 | delivery, contains "S" for sender-verification or "R" for | |
11864 | recipient-verification. Otherwise, empty. | |
11865 | ||
420a0d19 CE |
11866 | $version_number |
11867 | ||
11868 | The version number of Exim. | |
11869 | ||
11870 | $warn_message_delay | |
11871 | ||
11872 | This variable is set only during the creation of a message warning about a | |
2813c06e | 11873 | delivery delay. Details of its use are explained in section 49.2. |
420a0d19 CE |
11874 | |
11875 | $warn_message_recipients | |
11876 | ||
11877 | This variable is set only during the creation of a message warning about a | |
2813c06e | 11878 | delivery delay. Details of its use are explained in section 49.2. |
420a0d19 CE |
11879 | |
11880 | ||
11881 | ||
11882 | =============================================================================== | |
11883 | 12. EMBEDDED PERL | |
11884 | ||
11885 | Exim can be built to include an embedded Perl interpreter. When this is done, | |
11886 | Perl subroutines can be called as part of the string expansion process. To make | |
11887 | use of the Perl support, you need version 5.004 or later of Perl installed on | |
11888 | your system. To include the embedded interpreter in the Exim binary, include | |
11889 | the line | |
11890 | ||
11891 | EXIM_PERL = perl.o | |
11892 | ||
11893 | in your Local/Makefile and then build Exim in the normal way. | |
11894 | ||
11895 | ||
11896 | 12.1 Setting up so Perl can be used | |
11897 | ----------------------------------- | |
11898 | ||
11899 | Access to Perl subroutines is via a global configuration option called | |
11900 | perl_startup and an expansion string operator ${perl ...}. If there is no | |
11901 | perl_startup option in the Exim configuration file then no Perl interpreter is | |
11902 | started and there is almost no overhead for Exim (since none of the Perl | |
11903 | library will be paged in unless used). If there is a perl_startup option then | |
11904 | the associated value is taken to be Perl code which is executed in a newly | |
11905 | created Perl interpreter. | |
11906 | ||
11907 | The value of perl_startup is not expanded in the Exim sense, so you do not need | |
11908 | backslashes before any characters to escape special meanings. The option should | |
11909 | usually be something like | |
11910 | ||
11911 | perl_startup = do '/etc/exim.pl' | |
11912 | ||
11913 | where /etc/exim.pl is Perl code which defines any subroutines you want to use | |
11914 | from Exim. Exim can be configured either to start up a Perl interpreter as soon | |
11915 | as it is entered, or to wait until the first time it is needed. Starting the | |
11916 | interpreter at the beginning ensures that it is done while Exim still has its | |
11917 | setuid privilege, but can impose an unnecessary overhead if Perl is not in fact | |
11918 | used in a particular run. Also, note that this does not mean that Exim is | |
11919 | necessarily running as root when Perl is called at a later time. By default, | |
11920 | the interpreter is started only when it is needed, but this can be changed in | |
11921 | two ways: | |
11922 | ||
11923 | * Setting perl_at_start (a boolean option) in the configuration requests a | |
11924 | startup when Exim is entered. | |
11925 | ||
11926 | * The command line option -ps also requests a startup when Exim is entered, | |
11927 | overriding the setting of perl_at_start. | |
11928 | ||
11929 | There is also a command line option -pd (for delay) which suppresses the | |
11930 | initial startup, even if perl_at_start is set. | |
11931 | ||
2813c06e CE |
11932 | * To provide more security executing Perl code via the embedded Perl |
11933 | interpreter, the perl_taintmode option can be set. This enables the taint | |
11934 | mode of the Perl interpreter. You are encouraged to set this option to a | |
11935 | true value. To avoid breaking existing installations, it defaults to false. | |
11936 | ||
420a0d19 CE |
11937 | |
11938 | 12.2 Calling Perl subroutines | |
11939 | ----------------------------- | |
11940 | ||
11941 | When the configuration file includes a perl_startup option you can make use of | |
11942 | the string expansion item to call the Perl subroutines that are defined by the | |
11943 | perl_startup code. The operator is used in any of the following forms: | |
11944 | ||
11945 | ${perl{foo}} | |
11946 | ${perl{foo}{argument}} | |
11947 | ${perl{foo}{argument1}{argument2} ... } | |
11948 | ||
11949 | which calls the subroutine foo with the given arguments. A maximum of eight | |
11950 | arguments may be passed. Passing more than this results in an expansion failure | |
11951 | with an error message of the form | |
11952 | ||
11953 | Too many arguments passed to Perl subroutine "foo" (max is 8) | |
11954 | ||
11955 | The return value of the Perl subroutine is evaluated in a scalar context before | |
11956 | it is passed back to Exim to be inserted into the expanded string. If the | |
11957 | return value is undef, the expansion is forced to fail in the same way as an | |
11958 | explicit "fail" on an if or lookup item. If the subroutine aborts by obeying | |
11959 | Perl's die function, the expansion fails with the error message that was passed | |
11960 | to die. | |
11961 | ||
11962 | ||
11963 | 12.3 Calling Exim functions from Perl | |
11964 | ------------------------------------- | |
11965 | ||
11966 | Within any Perl code called from Exim, the function Exim::expand_string() is | |
11967 | available to call back into Exim's string expansion function. For example, the | |
11968 | Perl code | |
11969 | ||
11970 | my $lp = Exim::expand_string('$local_part'); | |
11971 | ||
11972 | makes the current Exim $local_part available in the Perl variable $lp. Note | |
11973 | those are single quotes and not double quotes to protect against $local_part | |
11974 | being interpolated as a Perl variable. | |
11975 | ||
11976 | If the string expansion is forced to fail by a "fail" item, the result of | |
11977 | Exim::expand_string() is undef. If there is a syntax error in the expansion | |
11978 | string, the Perl call from the original expansion string fails with an | |
11979 | appropriate error message, in the same way as if die were used. | |
11980 | ||
11981 | Two other Exim functions are available for use from within Perl code. | |
11982 | Exim::debug_write() writes a string to the standard error stream if Exim's | |
11983 | debugging is enabled. If you want a newline at the end, you must supply it. | |
11984 | Exim::log_write() writes a string to Exim's main log, adding a leading | |
11985 | timestamp. In this case, you should not supply a terminating newline. | |
11986 | ||
11987 | ||
11988 | 12.4 Use of standard output and error by Perl | |
11989 | --------------------------------------------- | |
11990 | ||
11991 | You should not write to the standard error or output streams from within your | |
11992 | Perl code, as it is not defined how these are set up. In versions of Exim | |
11993 | before 4.50, it is possible for the standard output or error to refer to the | |
11994 | SMTP connection during message reception via the daemon. Writing to this stream | |
11995 | is certain to cause chaos. From Exim 4.50 onwards, the standard output and | |
11996 | error streams are connected to /dev/null in the daemon. The chaos is avoided, | |
11997 | but the output is lost. | |
11998 | ||
11999 | The Perl warn statement writes to the standard error stream by default. Calls | |
12000 | to warn may be embedded in Perl modules that you use, but over which you have | |
12001 | no control. When Exim starts up the Perl interpreter, it arranges for output | |
12002 | from the warn statement to be written to the Exim main log. You can change this | |
12003 | by including appropriate Perl magic somewhere in your Perl code. For example, | |
12004 | to discard warn output completely, you need this: | |
12005 | ||
12006 | $SIG{__WARN__} = sub { }; | |
12007 | ||
12008 | Whenever a warn is obeyed, the anonymous subroutine is called. In this example, | |
12009 | the code for the subroutine is empty, so it does nothing, but you can include | |
12010 | any Perl code that you like. The text of the warn message is passed as the | |
12011 | first subroutine argument. | |
12012 | ||
12013 | ||
12014 | ||
12015 | =============================================================================== | |
12016 | 13. STARTING THE DAEMON AND THE USE OF NETWORK INTERFACES | |
12017 | ||
12018 | A host that is connected to a TCP/IP network may have one or more physical | |
12019 | hardware network interfaces. Each of these interfaces may be configured as one | |
12020 | or more "logical" interfaces, which are the entities that a program actually | |
12021 | works with. Each of these logical interfaces is associated with an IP address. | |
12022 | In addition, TCP/IP software supports "loopback" interfaces (127.0.0.1 in IPv4 | |
12023 | and ::1 in IPv6), which do not use any physical hardware. Exim requires | |
12024 | knowledge about the host's interfaces for use in three different circumstances: | |
12025 | ||
12026 | 1. When a listening daemon is started, Exim needs to know which interfaces and | |
12027 | ports to listen on. | |
12028 | ||
12029 | 2. When Exim is routing an address, it needs to know which IP addresses are | |
12030 | associated with local interfaces. This is required for the correct | |
12031 | processing of MX lists by removing the local host and others with the same | |
12032 | or higher priority values. Also, Exim needs to detect cases when an address | |
12033 | is routed to an IP address that in fact belongs to the local host. Unless | |
12034 | the self router option or the allow_localhost option of the smtp transport | |
12035 | is set (as appropriate), this is treated as an error situation. | |
12036 | ||
12037 | 3. When Exim connects to a remote host, it may need to know which interface to | |
12038 | use for the outgoing connection. | |
12039 | ||
12040 | Exim's default behaviour is likely to be appropriate in the vast majority of | |
12041 | cases. If your host has only one interface, and you want all its IP addresses | |
12042 | to be treated in the same way, and you are using only the standard SMTP port, | |
12043 | you should not need to take any special action. The rest of this chapter does | |
12044 | not apply to you. | |
12045 | ||
12046 | In a more complicated situation you may want to listen only on certain | |
12047 | interfaces, or on different ports, and for this reason there are a number of | |
12048 | options that can be used to influence Exim's behaviour. The rest of this | |
12049 | chapter describes how they operate. | |
12050 | ||
12051 | When a message is received over TCP/IP, the interface and port that were | |
12052 | actually used are set in $received_ip_address and $received_port. | |
12053 | ||
12054 | ||
12055 | 13.1 Starting a listening daemon | |
12056 | -------------------------------- | |
12057 | ||
12058 | When a listening daemon is started (by means of the -bd command line option), | |
12059 | the interfaces and ports on which it listens are controlled by the following | |
12060 | options: | |
12061 | ||
12062 | * daemon_smtp_ports contains a list of default ports or service names. (For | |
12063 | backward compatibility, this option can also be specified in the singular.) | |
12064 | ||
12065 | * local_interfaces contains list of interface IP addresses on which to | |
12066 | listen. Each item may optionally also specify a port. | |
12067 | ||
12068 | The default list separator in both cases is a colon, but this can be changed as | |
2813c06e | 12069 | described in section 6.20. When IPv6 addresses are involved, it is usually best |
420a0d19 CE |
12070 | to change the separator to avoid having to double all the colons. For example: |
12071 | ||
12072 | local_interfaces = <; 127.0.0.1 ; \ | |
12073 | 192.168.23.65 ; \ | |
12074 | ::1 ; \ | |
12075 | 3ffe:ffff:836f::fe86:a061 | |
12076 | ||
12077 | There are two different formats for specifying a port along with an IP address | |
12078 | in local_interfaces: | |
12079 | ||
12080 | 1. The port is added onto the address with a dot separator. For example, to | |
12081 | listen on port 1234 on two different IP addresses: | |
12082 | ||
12083 | local_interfaces = <; 192.168.23.65.1234 ; \ | |
12084 | 3ffe:ffff:836f::fe86:a061.1234 | |
12085 | ||
12086 | 2. The IP address is enclosed in square brackets, and the port is added with a | |
12087 | colon separator, for example: | |
12088 | ||
12089 | local_interfaces = <; [192.168.23.65]:1234 ; \ | |
12090 | [3ffe:ffff:836f::fe86:a061]:1234 | |
12091 | ||
12092 | When a port is not specified, the value of daemon_smtp_ports is used. The | |
12093 | default setting contains just one port: | |
12094 | ||
12095 | daemon_smtp_ports = smtp | |
12096 | ||
12097 | If more than one port is listed, each interface that does not have its own port | |
12098 | specified listens on all of them. Ports that are listed in daemon_smtp_ports | |
12099 | can be identified either by name (defined in /etc/services) or by number. | |
12100 | However, when ports are given with individual IP addresses in local_interfaces, | |
12101 | only numbers (not names) can be used. | |
12102 | ||
12103 | ||
12104 | 13.2 Special IP listening addresses | |
12105 | ----------------------------------- | |
12106 | ||
12107 | The addresses 0.0.0.0 and ::0 are treated specially. They are interpreted as | |
12108 | "all IPv4 interfaces" and "all IPv6 interfaces", respectively. In each case, | |
12109 | Exim tells the TCP/IP stack to "listen on all IPvx interfaces" instead of | |
12110 | setting up separate listening sockets for each interface. The default value of | |
12111 | local_interfaces is | |
12112 | ||
12113 | local_interfaces = 0.0.0.0 | |
12114 | ||
12115 | when Exim is built without IPv6 support; otherwise it is: | |
12116 | ||
12117 | local_interfaces = <; ::0 ; 0.0.0.0 | |
12118 | ||
12119 | Thus, by default, Exim listens on all available interfaces, on the SMTP port. | |
12120 | ||
12121 | ||
12122 | 13.3 Overriding local_interfaces and daemon_smtp_ports | |
12123 | ------------------------------------------------------ | |
12124 | ||
12125 | The -oX command line option can be used to override the values of | |
12126 | daemon_smtp_ports and/or local_interfaces for a particular daemon instance. | |
12127 | Another way of doing this would be to use macros and the -D option. However, | |
12128 | -oX can be used by any admin user, whereas modification of the runtime | |
12129 | configuration by -D is allowed only when the caller is root or exim. | |
12130 | ||
12131 | The value of -oX is a list of items. The default colon separator can be changed | |
12132 | in the usual way if required. If there are any items that do not contain dots | |
12133 | or colons (that is, are not IP addresses), the value of daemon_smtp_ports is | |
12134 | replaced by the list of those items. If there are any items that do contain | |
12135 | dots or colons, the value of local_interfaces is replaced by those items. Thus, | |
12136 | for example, | |
12137 | ||
12138 | -oX 1225 | |
12139 | ||
12140 | overrides daemon_smtp_ports, but leaves local_interfaces unchanged, whereas | |
12141 | ||
12142 | -oX 192.168.34.5.1125 | |
12143 | ||
12144 | overrides local_interfaces, leaving daemon_smtp_ports unchanged. (However, | |
12145 | since local_interfaces now contains no items without ports, the value of | |
12146 | daemon_smtp_ports is no longer relevant in this example.) | |
12147 | ||
12148 | ||
12149 | 13.4 Support for the obsolete SSMTP (or SMTPS) protocol | |
12150 | ------------------------------------------------------- | |
12151 | ||
12152 | Exim supports the obsolete SSMTP protocol (also known as SMTPS) that was used | |
12153 | before the STARTTLS command was standardized for SMTP. Some legacy clients | |
12154 | still use this protocol. If the tls_on_connect_ports option is set to a list of | |
12155 | port numbers or service names, connections to those ports must use SSMTP. The | |
12156 | most common use of this option is expected to be | |
12157 | ||
12158 | tls_on_connect_ports = 465 | |
12159 | ||
12160 | because 465 is the usual port number used by the legacy clients. There is also | |
12161 | a command line option -tls-on-connect, which forces all ports to behave in this | |
12162 | way when a daemon is started. | |
12163 | ||
12164 | Warning: Setting tls_on_connect_ports does not of itself cause the daemon to | |
12165 | listen on those ports. You must still specify them in daemon_smtp_ports, | |
12166 | local_interfaces, or the -oX option. (This is because tls_on_connect_ports | |
12167 | applies to inetd connections as well as to connections via the daemon.) | |
12168 | ||
12169 | ||
12170 | 13.5 IPv6 address scopes | |
12171 | ------------------------ | |
12172 | ||
12173 | IPv6 addresses have "scopes", and a host with multiple hardware interfaces can, | |
12174 | in principle, have the same link-local IPv6 address on different interfaces. | |
12175 | Thus, additional information is needed, over and above the IP address, to | |
12176 | distinguish individual interfaces. A convention of using a percent sign | |
12177 | followed by something (often the interface name) has been adopted in some | |
12178 | cases, leading to addresses like this: | |
12179 | ||
12180 | fe80::202:b3ff:fe03:45c1%eth0 | |
12181 | ||
12182 | To accommodate this usage, a percent sign followed by an arbitrary string is | |
12183 | allowed at the end of an IPv6 address. By default, Exim calls getaddrinfo() to | |
12184 | convert a textual IPv6 address for actual use. This function recognizes the | |
12185 | percent convention in operating systems that support it, and it processes the | |
12186 | address appropriately. Unfortunately, some older libraries have problems with | |
12187 | getaddrinfo(). If | |
12188 | ||
12189 | IPV6_USE_INET_PTON=yes | |
12190 | ||
12191 | is set in Local/Makefile (or an OS-dependent Makefile) when Exim is built, Exim | |
12192 | uses inet_pton() to convert a textual IPv6 address for actual use, instead of | |
12193 | getaddrinfo(). (Before version 4.14, it always used this function.) Of course, | |
12194 | this means that the additional functionality of getaddrinfo() - recognizing | |
12195 | scoped addresses - is lost. | |
12196 | ||
12197 | ||
12198 | 13.6 Disabling IPv6 | |
12199 | ------------------- | |
12200 | ||
12201 | Sometimes it happens that an Exim binary that was compiled with IPv6 support is | |
12202 | run on a host whose kernel does not support IPv6. The binary will fall back to | |
12203 | using IPv4, but it may waste resources looking up AAAA records, and trying to | |
12204 | connect to IPv6 addresses, causing delays to mail delivery. If you set the | |
12205 | disable_ipv6 option true, even if the Exim binary has IPv6 support, no IPv6 | |
12206 | activities take place. AAAA records are never looked up, and any IPv6 addresses | |
12207 | that are listed in local_interfaces, data for the manualroute router, etc. are | |
12208 | ignored. If IP literals are enabled, the ipliteral router declines to handle | |
12209 | IPv6 literal addresses. | |
12210 | ||
12211 | On the other hand, when IPv6 is in use, there may be times when you want to | |
12212 | disable it for certain hosts or domains. You can use the dns_ipv4_lookup option | |
12213 | to globally suppress the lookup of AAAA records for specified domains, and you | |
12214 | can use the ignore_target_hosts generic router option to ignore IPv6 addresses | |
12215 | in an individual router. | |
12216 | ||
12217 | ||
12218 | 13.7 Examples of starting a listening daemon | |
12219 | -------------------------------------------- | |
12220 | ||
12221 | The default case in an IPv6 environment is | |
12222 | ||
12223 | daemon_smtp_ports = smtp | |
12224 | local_interfaces = <; ::0 ; 0.0.0.0 | |
12225 | ||
12226 | This specifies listening on the smtp port on all IPv6 and IPv4 interfaces. | |
12227 | Either one or two sockets may be used, depending on the characteristics of the | |
12228 | TCP/IP stack. (This is complicated and messy; for more information, read the | |
12229 | comments in the daemon.c source file.) | |
12230 | ||
12231 | To specify listening on ports 25 and 26 on all interfaces: | |
12232 | ||
12233 | daemon_smtp_ports = 25 : 26 | |
12234 | ||
12235 | (leaving local_interfaces at the default setting) or, more explicitly: | |
12236 | ||
12237 | local_interfaces = <; ::0.25 ; ::0.26 \ | |
12238 | 0.0.0.0.25 ; 0.0.0.0.26 | |
12239 | ||
12240 | To listen on the default port on all IPv4 interfaces, and on port 26 on the | |
12241 | IPv4 loopback address only: | |
12242 | ||
12243 | local_interfaces = 0.0.0.0 : 127.0.0.1.26 | |
12244 | ||
12245 | To specify listening on the default port on specific interfaces only: | |
12246 | ||
12247 | local_interfaces = 10.0.0.67 : 192.168.34.67 | |
12248 | ||
12249 | Warning: Such a setting excludes listening on the loopback interfaces. | |
12250 | ||
12251 | ||
12252 | 13.8 Recognizing the local host | |
12253 | ------------------------------- | |
12254 | ||
12255 | The local_interfaces option is also used when Exim needs to determine whether | |
12256 | or not an IP address refers to the local host. That is, the IP addresses of all | |
12257 | the interfaces on which a daemon is listening are always treated as local. | |
12258 | ||
12259 | For this usage, port numbers in local_interfaces are ignored. If either of the | |
12260 | items 0.0.0.0 or ::0 are encountered, Exim gets a complete list of available | |
12261 | interfaces from the operating system, and extracts the relevant (that is, IPv4 | |
12262 | or IPv6) addresses to use for checking. | |
12263 | ||
12264 | Some systems set up large numbers of virtual interfaces in order to provide | |
12265 | many virtual web servers. In this situation, you may want to listen for email | |
12266 | on only a few of the available interfaces, but nevertheless treat all | |
12267 | interfaces as local when routing. You can do this by setting | |
12268 | extra_local_interfaces to a list of IP addresses, possibly including the "all" | |
12269 | wildcard values. These addresses are recognized as local, but are not used for | |
12270 | listening. Consider this example: | |
12271 | ||
12272 | local_interfaces = <; 127.0.0.1 ; ::1 ; \ | |
12273 | 192.168.53.235 ; \ | |
12274 | 3ffe:2101:12:1:a00:20ff:fe86:a061 | |
12275 | ||
12276 | extra_local_interfaces = <; ::0 ; 0.0.0.0 | |
12277 | ||
12278 | The daemon listens on the loopback interfaces and just one IPv4 and one IPv6 | |
12279 | address, but all available interface addresses are treated as local when Exim | |
12280 | is routing. | |
12281 | ||
12282 | In some environments the local host name may be in an MX list, but with an IP | |
12283 | address that is not assigned to any local interface. In other cases it may be | |
12284 | desirable to treat other host names as if they referred to the local host. Both | |
12285 | these cases can be handled by setting the hosts_treat_as_local option. This | |
12286 | contains host names rather than IP addresses. When a host is referenced during | |
12287 | routing, either via an MX record or directly, it is treated as the local host | |
12288 | if its name matches hosts_treat_as_local, or if any of its IP addresses match | |
12289 | local_interfaces or extra_local_interfaces. | |
12290 | ||
12291 | ||
12292 | 13.9 Delivering to a remote host | |
12293 | -------------------------------- | |
12294 | ||
12295 | Delivery to a remote host is handled by the smtp transport. By default, it | |
12296 | allows the system's TCP/IP functions to choose which interface to use (if there | |
12297 | is more than one) when connecting to a remote host. However, the interface | |
12298 | option can be set to specify which interface is used. See the description of | |
12299 | the smtp transport in chapter 30 for more details. | |
12300 | ||
12301 | ||
12302 | ||
12303 | =============================================================================== | |
12304 | 14. MAIN CONFIGURATION | |
12305 | ||
12306 | The first part of the run time configuration file contains three types of item: | |
12307 | ||
12308 | * Macro definitions: These lines start with an upper case letter. See section | |
12309 | 6.4 for details of macro processing. | |
12310 | ||
12311 | * Named list definitions: These lines start with one of the words | |
12312 | "domainlist", "hostlist", "addresslist", or "localpartlist". Their use is | |
12313 | described in section 10.5. | |
12314 | ||
12315 | * Main configuration settings: Each setting occupies one line of the file | |
12316 | (with possible continuations). If any setting is preceded by the word | |
12317 | "hide", the -bP command line option displays its value to admin users only. | |
2813c06e | 12318 | See section 6.11 for a description of the syntax of these option settings. |
420a0d19 CE |
12319 | |
12320 | This chapter specifies all the main configuration options, along with their | |
12321 | types and default values. For ease of finding a particular option, they appear | |
12322 | in alphabetical order in section 14.23 below. However, because there are now so | |
12323 | many options, they are first listed briefly in functional groups, as an aid to | |
12324 | finding the name of the option you are looking for. Some options are listed in | |
12325 | more than one group. | |
12326 | ||
12327 | ||
12328 | 14.1 Miscellaneous | |
12329 | ------------------ | |
12330 | ||
12331 | bi_command to run for -bi command line option | |
2813c06e | 12332 | debug_store do extra internal checks |
420a0d19 CE |
12333 | disable_ipv6 do no IPv6 processing |
12334 | keep_malformed for broken files - should not happen | |
12335 | localhost_number for unique message ids in clusters | |
12336 | message_body_newlines retain newlines in $message_body | |
12337 | message_body_visible how much to show in $message_body | |
12338 | mua_wrapper run in "MUA wrapper" mode | |
12339 | print_topbitchars top-bit characters are printing | |
12340 | timezone force time zone | |
12341 | ||
12342 | ||
12343 | 14.2 Exim parameters | |
12344 | -------------------- | |
12345 | ||
12346 | exim_group override compiled-in value | |
12347 | exim_path override compiled-in value | |
12348 | exim_user override compiled-in value | |
12349 | primary_hostname default from uname() | |
12350 | split_spool_directory use multiple directories | |
12351 | spool_directory override compiled-in value | |
12352 | ||
12353 | ||
12354 | 14.3 Privilege controls | |
12355 | ----------------------- | |
12356 | ||
12357 | admin_groups groups that are Exim admin users | |
12358 | deliver_drop_privilege drop root for delivery processes | |
12359 | local_from_check insert Sender: if necessary | |
12360 | local_from_prefix for testing From: for local sender | |
12361 | local_from_suffix for testing From: for local sender | |
12362 | local_sender_retain keep Sender: from untrusted user | |
12363 | never_users do not run deliveries as these | |
12364 | prod_requires_admin forced delivery requires admin user | |
12365 | queue_list_requires_admin queue listing requires admin user | |
12366 | trusted_groups groups that are trusted | |
12367 | trusted_users users that are trusted | |
12368 | ||
12369 | ||
12370 | 14.4 Logging | |
12371 | ------------ | |
12372 | ||
2813c06e | 12373 | event_action custom logging |
420a0d19 CE |
12374 | hosts_connection_nolog exemption from connect logging |
12375 | log_file_path override compiled-in value | |
12376 | log_selector set/unset optional logging | |
12377 | log_timezone add timezone to log lines | |
12378 | message_logs create per-message logs | |
12379 | preserve_message_logs after message completion | |
12380 | process_log_path for SIGUSR1 and exiwhat | |
2813c06e | 12381 | slow_lookup_log control logging of slow DNS lookups |
420a0d19 CE |
12382 | syslog_duplication controls duplicate log lines on syslog |
12383 | syslog_facility set syslog "facility" field | |
2813c06e | 12384 | syslog_pid pid in syslog lines |
420a0d19 CE |
12385 | syslog_processname set syslog "ident" field |
12386 | syslog_timestamp timestamp syslog lines | |
12387 | write_rejectlog control use of message log | |
12388 | ||
12389 | ||
12390 | 14.5 Frozen messages | |
12391 | -------------------- | |
12392 | ||
12393 | auto_thaw sets time for retrying frozen messages | |
12394 | freeze_tell send message when freezing | |
12395 | move_frozen_messages to another directory | |
12396 | timeout_frozen_after keep frozen messages only so long | |
12397 | ||
12398 | ||
12399 | 14.6 Data lookups | |
12400 | ----------------- | |
12401 | ||
12402 | ibase_servers InterBase servers | |
12403 | ldap_ca_cert_dir dir of CA certs to verify LDAP server's | |
12404 | ldap_ca_cert_file file of CA certs to verify LDAP server's | |
12405 | ldap_cert_file client cert file for LDAP | |
12406 | ldap_cert_key client key file for LDAP | |
12407 | ldap_cipher_suite TLS negotiation preference control | |
12408 | ldap_default_servers used if no server in query | |
12409 | ldap_require_cert action to take without LDAP server cert | |
12410 | ldap_start_tls require TLS within LDAP | |
12411 | ldap_version set protocol version | |
12412 | lookup_open_max lookup files held open | |
12413 | mysql_servers default MySQL servers | |
12414 | oracle_servers Oracle servers | |
12415 | pgsql_servers default PostgreSQL servers | |
12416 | sqlite_lock_timeout as it says | |
12417 | ||
12418 | ||
12419 | 14.7 Message ids | |
12420 | ---------------- | |
12421 | ||
12422 | message_id_header_domain used to build Message-ID: header | |
12423 | message_id_header_text ditto | |
12424 | ||
12425 | ||
12426 | 14.8 Embedded Perl Startup | |
12427 | -------------------------- | |
12428 | ||
2813c06e CE |
12429 | perl_at_start always start the interpreter |
12430 | perl_startup code to obey when starting Perl | |
12431 | perl_taintmode enable taint mode in Perl | |
420a0d19 CE |
12432 | |
12433 | ||
12434 | 14.9 Daemon | |
12435 | ----------- | |
12436 | ||
12437 | daemon_smtp_ports default ports | |
12438 | daemon_startup_retries number of times to retry | |
12439 | daemon_startup_sleep time to sleep between tries | |
12440 | extra_local_interfaces not necessarily listened on | |
12441 | local_interfaces on which to listen, with optional ports | |
12442 | pid_file_path override compiled-in value | |
12443 | queue_run_max maximum simultaneous queue runners | |
12444 | ||
12445 | ||
12446 | 14.10 Resource control | |
12447 | ---------------------- | |
12448 | ||
12449 | check_log_inodes before accepting a message | |
12450 | check_log_space before accepting a message | |
12451 | check_spool_inodes before accepting a message | |
12452 | check_spool_space before accepting a message | |
12453 | deliver_queue_load_max no queue deliveries if load high | |
12454 | queue_only_load queue incoming if load high | |
12455 | queue_only_load_latch don't re-evaluate load for each message | |
12456 | queue_run_max maximum simultaneous queue runners | |
12457 | remote_max_parallel parallel SMTP delivery per message | |
12458 | smtp_accept_max simultaneous incoming connections | |
12459 | smtp_accept_max_nonmail non-mail commands | |
12460 | smtp_accept_max_nonmail_hosts hosts to which the limit applies | |
12461 | smtp_accept_max_per_connection messages per connection | |
12462 | smtp_accept_max_per_host connections from one host | |
12463 | smtp_accept_queue queue mail if more connections | |
12464 | smtp_accept_queue_per_connection queue if more messages per connection | |
12465 | smtp_accept_reserve only reserve hosts if more connections | |
12466 | smtp_check_spool_space from SIZE on MAIL command | |
12467 | smtp_connect_backlog passed to TCP/IP stack | |
12468 | smtp_load_reserve SMTP from reserved hosts if load high | |
12469 | smtp_reserve_hosts these are the reserve hosts | |
12470 | ||
12471 | ||
12472 | 14.11 Policy controls | |
12473 | --------------------- | |
12474 | ||
12475 | acl_not_smtp ACL for non-SMTP messages | |
12476 | acl_not_smtp_mime ACL for non-SMTP MIME parts | |
12477 | acl_not_smtp_start ACL for start of non-SMTP message | |
12478 | acl_smtp_auth ACL for AUTH | |
12479 | acl_smtp_connect ACL for connection | |
12480 | acl_smtp_data ACL for DATA | |
12481 | acl_smtp_data_prdr ACL for DATA, per-recipient | |
12482 | acl_smtp_dkim ACL for DKIM verification | |
12483 | acl_smtp_etrn ACL for ETRN | |
12484 | acl_smtp_expn ACL for EXPN | |
12485 | acl_smtp_helo ACL for EHLO or HELO | |
12486 | acl_smtp_mail ACL for MAIL | |
12487 | acl_smtp_mailauth ACL for AUTH on MAIL command | |
12488 | acl_smtp_mime ACL for MIME parts | |
2813c06e | 12489 | acl_smtp_notquit ACL for non-QUIT terminations |
420a0d19 CE |
12490 | acl_smtp_predata ACL for start of data |
12491 | acl_smtp_quit ACL for QUIT | |
12492 | acl_smtp_rcpt ACL for RCPT | |
12493 | acl_smtp_starttls ACL for STARTTLS | |
12494 | acl_smtp_vrfy ACL for VRFY | |
12495 | av_scanner specify virus scanner | |
12496 | check_rfc2047_length check length of RFC 2047 "encoded words" | |
12497 | dns_csa_search_limit control CSA parent search depth | |
12498 | dns_csa_use_reverse en/disable CSA IP reverse search | |
12499 | header_maxsize total size of message header | |
12500 | header_line_maxsize individual header line limit | |
12501 | helo_accept_junk_hosts allow syntactic junk from these hosts | |
12502 | helo_allow_chars allow illegal chars in HELO names | |
12503 | helo_lookup_domains lookup hostname for these HELO names | |
12504 | helo_try_verify_hosts HELO soft-checked for these hosts | |
12505 | helo_verify_hosts HELO hard-checked for these hosts | |
12506 | host_lookup host name looked up for these hosts | |
12507 | host_lookup_order order of DNS and local name lookups | |
2813c06e | 12508 | hosts_proxy use proxy protocol for these hosts |
420a0d19 CE |
12509 | host_reject_connection reject connection from these hosts |
12510 | hosts_treat_as_local useful in some cluster configurations | |
12511 | local_scan_timeout timeout for local_scan() | |
12512 | message_size_limit for all messages | |
12513 | percent_hack_domains recognize %-hack for these domains | |
12514 | spamd_address set interface to SpamAssassin | |
12515 | strict_acl_vars object to unset ACL variables | |
12516 | ||
12517 | ||
12518 | 14.12 Callout cache | |
12519 | ------------------- | |
12520 | ||
12521 | callout_domain_negative_expire timeout for negative domain cache item | |
12522 | callout_domain_positive_expire timeout for positive domain cache item | |
12523 | callout_negative_expire timeout for negative address cache item | |
12524 | callout_positive_expire timeout for positive address cache item | |
12525 | callout_random_local_part string to use for "random" testing | |
12526 | ||
12527 | ||
12528 | 14.13 TLS | |
12529 | --------- | |
12530 | ||
12531 | gnutls_compat_mode use GnuTLS compatibility mode | |
12532 | gnutls_allow_auto_pkcs11 allow GnuTLS to autoload PKCS11 modules | |
12533 | openssl_options adjust OpenSSL compatibility options | |
12534 | tls_advertise_hosts advertise TLS to these hosts | |
12535 | tls_certificate location of server certificate | |
12536 | tls_crl certificate revocation list | |
12537 | tls_dh_max_bits clamp D-H bit count suggestion | |
12538 | tls_dhparam DH parameters for server | |
2813c06e | 12539 | tls_eccurve EC curve selection for server |
420a0d19 CE |
12540 | tls_ocsp_file location of server certificate status proof |
12541 | tls_on_connect_ports specify SSMTP (SMTPS) ports | |
12542 | tls_privatekey location of server private key | |
12543 | tls_remember_esmtp don't reset after starting TLS | |
12544 | tls_require_ciphers specify acceptable ciphers | |
12545 | tls_try_verify_hosts try to verify client certificate | |
12546 | tls_verify_certificates expected client certificates | |
12547 | tls_verify_hosts insist on client certificate verify | |
12548 | ||
12549 | ||
12550 | 14.14 Local user handling | |
12551 | ------------------------- | |
12552 | ||
12553 | finduser_retries useful in NIS environments | |
12554 | gecos_name used when creating Sender: | |
12555 | gecos_pattern ditto | |
12556 | max_username_length for systems that truncate | |
12557 | unknown_login used when no login name found | |
12558 | unknown_username ditto | |
12559 | uucp_from_pattern for recognizing "From " lines | |
12560 | uucp_from_sender ditto | |
12561 | ||
12562 | ||
12563 | 14.15 All incoming messages (SMTP and non-SMTP) | |
12564 | ----------------------------------------------- | |
12565 | ||
12566 | header_maxsize total size of message header | |
12567 | header_line_maxsize individual header line limit | |
12568 | message_size_limit applies to all messages | |
12569 | percent_hack_domains recognize %-hack for these domains | |
12570 | received_header_text expanded to make Received: | |
12571 | received_headers_max for mail loop detection | |
12572 | recipients_max limit per message | |
12573 | recipients_max_reject permanently reject excess recipients | |
12574 | ||
12575 | ||
12576 | 14.16 Non-SMTP incoming messages | |
12577 | -------------------------------- | |
12578 | ||
12579 | receive_timeout for non-SMTP messages | |
12580 | ||
12581 | ||
12582 | 14.17 Incoming SMTP messages | |
12583 | ---------------------------- | |
12584 | ||
12585 | See also the Policy controls section above. | |
12586 | ||
2813c06e | 12587 | dkim_verify_signers DKIM domain for which DKIM ACL is run |
420a0d19 CE |
12588 | host_lookup host name looked up for these hosts |
12589 | host_lookup_order order of DNS and local name lookups | |
12590 | recipient_unqualified_hosts may send unqualified recipients | |
12591 | rfc1413_hosts make ident calls to these hosts | |
12592 | rfc1413_query_timeout zero disables ident calls | |
12593 | sender_unqualified_hosts may send unqualified senders | |
12594 | smtp_accept_keepalive some TCP/IP magic | |
12595 | smtp_accept_max simultaneous incoming connections | |
12596 | smtp_accept_max_nonmail non-mail commands | |
12597 | smtp_accept_max_nonmail_hosts hosts to which the limit applies | |
12598 | smtp_accept_max_per_connection messages per connection | |
12599 | smtp_accept_max_per_host connections from one host | |
12600 | smtp_accept_queue queue mail if more connections | |
12601 | smtp_accept_queue_per_connection queue if more messages per connection | |
12602 | smtp_accept_reserve only reserve hosts if more connections | |
12603 | smtp_active_hostname host name to use in messages | |
12604 | smtp_banner text for welcome banner | |
12605 | smtp_check_spool_space from SIZE on MAIL command | |
12606 | smtp_connect_backlog passed to TCP/IP stack | |
12607 | smtp_enforce_sync of SMTP command/responses | |
12608 | smtp_etrn_command what to run for ETRN | |
12609 | smtp_etrn_serialize only one at once | |
12610 | smtp_load_reserve only reserve hosts if this load | |
12611 | smtp_max_unknown_commands before dropping connection | |
12612 | smtp_ratelimit_hosts apply ratelimiting to these hosts | |
12613 | smtp_ratelimit_mail ratelimit for MAIL commands | |
12614 | smtp_ratelimit_rcpt ratelimit for RCPT commands | |
12615 | smtp_receive_timeout per command or data line | |
12616 | smtp_reserve_hosts these are the reserve hosts | |
12617 | smtp_return_error_details give detail on rejections | |
12618 | ||
12619 | ||
12620 | 14.18 SMTP extensions | |
12621 | --------------------- | |
12622 | ||
12623 | accept_8bitmime advertise 8BITMIME | |
12624 | auth_advertise_hosts advertise AUTH to these hosts | |
2813c06e CE |
12625 | chunking_advertise_hosts advertise CHUNKING to these hosts |
12626 | dsn_advertise_hosts advertise DSN extensions to these hosts | |
420a0d19 CE |
12627 | ignore_fromline_hosts allow "From " from these hosts |
12628 | ignore_fromline_local allow "From " from local SMTP | |
12629 | pipelining_advertise_hosts advertise pipelining to these hosts | |
12630 | prdr_enable advertise PRDR to all hosts | |
2813c06e | 12631 | smtputf8_advertise_hosts advertise SMTPUTF8 to these hosts |
420a0d19 CE |
12632 | tls_advertise_hosts advertise TLS to these hosts |
12633 | ||
12634 | ||
12635 | 14.19 Processing messages | |
12636 | ------------------------- | |
12637 | ||
12638 | allow_domain_literals recognize domain literal syntax | |
12639 | allow_mx_to_ip allow MX to point to IP address | |
12640 | allow_utf8_domains in addresses | |
12641 | check_rfc2047_length check length of RFC 2047 "encoded words" | |
12642 | delivery_date_remove from incoming messages | |
12643 | envelope_to_remove from incoming messages | |
12644 | extract_addresses_remove_arguments affects -t processing | |
12645 | headers_charset default for translations | |
12646 | qualify_domain default for senders | |
12647 | qualify_recipient default for recipients | |
12648 | return_path_remove from incoming messages | |
12649 | strip_excess_angle_brackets in addresses | |
12650 | strip_trailing_dot at end of addresses | |
12651 | untrusted_set_sender untrusted can set envelope sender | |
12652 | ||
12653 | ||
12654 | 14.20 System filter | |
12655 | ------------------- | |
12656 | ||
12657 | system_filter locate system filter | |
12658 | system_filter_directory_transport transport for delivery to a directory | |
12659 | system_filter_file_transport transport for delivery to a file | |
12660 | system_filter_group group for filter running | |
12661 | system_filter_pipe_transport transport for delivery to a pipe | |
12662 | system_filter_reply_transport transport for autoreply delivery | |
12663 | system_filter_user user for filter running | |
12664 | ||
12665 | ||
12666 | 14.21 Routing and delivery | |
12667 | -------------------------- | |
12668 | ||
12669 | disable_ipv6 do no IPv6 processing | |
12670 | dns_again_means_nonexist for broken domains | |
12671 | dns_check_names_pattern pre-DNS syntax check | |
12672 | dns_dnssec_ok parameter for resolver | |
12673 | dns_ipv4_lookup only v4 lookup for these domains | |
12674 | dns_retrans parameter for resolver | |
12675 | dns_retry parameter for resolver | |
2813c06e | 12676 | dns_trust_aa DNS zones trusted as authentic |
420a0d19 CE |
12677 | dns_use_edns0 parameter for resolver |
12678 | hold_domains hold delivery for these domains | |
12679 | local_interfaces for routing checks | |
12680 | queue_domains no immediate delivery for these | |
12681 | queue_only no immediate delivery at all | |
12682 | queue_only_file no immediate delivery if file exists | |
12683 | queue_only_load no immediate delivery if load is high | |
12684 | queue_only_load_latch don't re-evaluate load for each message | |
12685 | queue_only_override allow command line to override | |
12686 | queue_run_in_order order of arrival | |
12687 | queue_run_max of simultaneous queue runners | |
12688 | queue_smtp_domains no immediate SMTP delivery for these | |
12689 | remote_max_parallel parallel SMTP delivery per message | |
12690 | remote_sort_domains order of remote deliveries | |
12691 | retry_data_expire timeout for retry data | |
12692 | retry_interval_max safety net for retry rules | |
12693 | ||
12694 | ||
12695 | 14.22 Bounce and warning messages | |
12696 | --------------------------------- | |
12697 | ||
12698 | bounce_message_file content of bounce | |
12699 | bounce_message_text content of bounce | |
12700 | bounce_return_body include body if returning message | |
2813c06e | 12701 | bounce_return_linesize_limit limit on returned message line length |
420a0d19 CE |
12702 | bounce_return_message include original message in bounce |
12703 | bounce_return_size_limit limit on returned message | |
12704 | bounce_sender_authentication send authenticated sender with bounce | |
12705 | dsn_from set From: contents in bounces | |
12706 | errors_copy copy bounce messages | |
12707 | errors_reply_to Reply-to: in bounces | |
12708 | delay_warning time schedule | |
12709 | delay_warning_condition condition for warning messages | |
12710 | ignore_bounce_errors_after discard undeliverable bounces | |
12711 | smtp_return_error_details give detail on rejections | |
12712 | warn_message_file content of warning message | |
12713 | ||
12714 | ||
12715 | 14.23 Alphabetical list of main options | |
12716 | --------------------------------------- | |
12717 | ||
12718 | Those options that undergo string expansion before use are marked with *. | |
12719 | ||
2813c06e | 12720 | +-----------------------------------------------------+ |
420a0d19 | 12721 | |accept_8bitmime|Use: main|Type: boolean|Default: true| |
2813c06e | 12722 | +-----------------------------------------------------+ |
420a0d19 CE |
12723 | |
12724 | This option causes Exim to send 8BITMIME in its response to an SMTP EHLO | |
12725 | command, and to accept the BODY= parameter on MAIL commands. However, though | |
12726 | Exim is 8-bit clean, it is not a protocol converter, and it takes no steps to | |
12727 | do anything special with messages received by this route. | |
12728 | ||
12729 | Historically Exim kept this option off by default, but the maintainers feel | |
12730 | that in today's Internet, this causes more problems than it solves. It now | |
12731 | defaults to true. A more detailed analysis of the issues is provided by Dan | |
12732 | Bernstein: | |
12733 | ||
12734 | http://cr.yp.to/smtp/8bitmime.html | |
12735 | ||
12736 | To log received 8BITMIME status use | |
12737 | ||
12738 | log_selector = +8bitmime | |
12739 | ||
2813c06e | 12740 | +---------------------------------------------------+ |
420a0d19 | 12741 | |acl_not_smtp|Use: main|Type: string*|Default: unset| |
2813c06e | 12742 | +---------------------------------------------------+ |
420a0d19 CE |
12743 | |
12744 | This option defines the ACL that is run when a non-SMTP message has been read | |
2813c06e | 12745 | and is on the point of being accepted. See chapter 43 for further details. |
420a0d19 | 12746 | |
2813c06e | 12747 | +--------------------------------------------------------+ |
420a0d19 | 12748 | |acl_not_smtp_mime|Use: main|Type: string*|Default: unset| |
2813c06e | 12749 | +--------------------------------------------------------+ |
420a0d19 CE |
12750 | |
12751 | This option defines the ACL that is run for individual MIME parts of non-SMTP | |
12752 | messages. It operates in exactly the same way as acl_smtp_mime operates for | |
12753 | SMTP messages. | |
12754 | ||
2813c06e | 12755 | +---------------------------------------------------------+ |
420a0d19 | 12756 | |acl_not_smtp_start|Use: main|Type: string*|Default: unset| |
2813c06e | 12757 | +---------------------------------------------------------+ |
420a0d19 CE |
12758 | |
12759 | This option defines the ACL that is run before Exim starts reading a non-SMTP | |
2813c06e | 12760 | message. See chapter 43 for further details. |
420a0d19 | 12761 | |
2813c06e | 12762 | +----------------------------------------------------+ |
420a0d19 | 12763 | |acl_smtp_auth|Use: main|Type: string*|Default: unset| |
2813c06e | 12764 | +----------------------------------------------------+ |
420a0d19 CE |
12765 | |
12766 | This option defines the ACL that is run when an SMTP AUTH command is received. | |
2813c06e | 12767 | See chapter 43 for further details. |
420a0d19 | 12768 | |
2813c06e | 12769 | +-------------------------------------------------------+ |
420a0d19 | 12770 | |acl_smtp_connect|Use: main|Type: string*|Default: unset| |
2813c06e | 12771 | +-------------------------------------------------------+ |
420a0d19 CE |
12772 | |
12773 | This option defines the ACL that is run when an SMTP connection is received. | |
2813c06e | 12774 | See chapter 43 for further details. |
420a0d19 | 12775 | |
2813c06e | 12776 | +----------------------------------------------------+ |
420a0d19 | 12777 | |acl_smtp_data|Use: main|Type: string*|Default: unset| |
2813c06e | 12778 | +----------------------------------------------------+ |
420a0d19 CE |
12779 | |
12780 | This option defines the ACL that is run after an SMTP DATA command has been | |
12781 | processed and the message itself has been received, but before the final | |
2813c06e | 12782 | acknowledgment is sent. See chapter 43 for further details. |
420a0d19 | 12783 | |
2813c06e CE |
12784 | +----------------------------------------------------------+ |
12785 | |acl_smtp_data_prdr|Use: main|Type: string*|Default: accept| | |
12786 | +----------------------------------------------------------+ | |
420a0d19 CE |
12787 | |
12788 | This option defines the ACL that, if the PRDR feature has been negotiated, is | |
12789 | run for each recipient after an SMTP DATA command has been processed and the | |
12790 | message itself has been received, but before the acknowledgment is sent. See | |
2813c06e CE |
12791 | chapter 43 for further details. |
12792 | ||
12793 | +----------------------------------------------------+ | |
12794 | |acl_smtp_dkim|Use: main|Type: string*|Default: unset| | |
12795 | +----------------------------------------------------+ | |
420a0d19 | 12796 | |
2813c06e CE |
12797 | This option defines the ACL that is run for each DKIM signature (by default, or |
12798 | as specified in the dkim_verify_signers option) of a received message. See | |
12799 | chapter 57 for further details. | |
12800 | ||
12801 | +----------------------------------------------------+ | |
420a0d19 | 12802 | |acl_smtp_etrn|Use: main|Type: string*|Default: unset| |
2813c06e | 12803 | +----------------------------------------------------+ |
420a0d19 CE |
12804 | |
12805 | This option defines the ACL that is run when an SMTP ETRN command is received. | |
2813c06e | 12806 | See chapter 43 for further details. |
420a0d19 | 12807 | |
2813c06e | 12808 | +----------------------------------------------------+ |
420a0d19 | 12809 | |acl_smtp_expn|Use: main|Type: string*|Default: unset| |
2813c06e | 12810 | +----------------------------------------------------+ |
420a0d19 CE |
12811 | |
12812 | This option defines the ACL that is run when an SMTP EXPN command is received. | |
2813c06e | 12813 | See chapter 43 for further details. |
420a0d19 | 12814 | |
2813c06e | 12815 | +----------------------------------------------------+ |
420a0d19 | 12816 | |acl_smtp_helo|Use: main|Type: string*|Default: unset| |
2813c06e | 12817 | +----------------------------------------------------+ |
420a0d19 CE |
12818 | |
12819 | This option defines the ACL that is run when an SMTP EHLO or HELO command is | |
2813c06e | 12820 | received. See chapter 43 for further details. |
420a0d19 | 12821 | |
2813c06e | 12822 | +----------------------------------------------------+ |
420a0d19 | 12823 | |acl_smtp_mail|Use: main|Type: string*|Default: unset| |
2813c06e | 12824 | +----------------------------------------------------+ |
420a0d19 CE |
12825 | |
12826 | This option defines the ACL that is run when an SMTP MAIL command is received. | |
2813c06e | 12827 | See chapter 43 for further details. |
420a0d19 | 12828 | |
2813c06e | 12829 | +--------------------------------------------------------+ |
420a0d19 | 12830 | |acl_smtp_mailauth|Use: main|Type: string*|Default: unset| |
2813c06e | 12831 | +--------------------------------------------------------+ |
420a0d19 CE |
12832 | |
12833 | This option defines the ACL that is run when there is an AUTH parameter on a | |
2813c06e | 12834 | MAIL command. See chapter 43 for details of ACLs, and chapter 33 for details of |
420a0d19 CE |
12835 | authentication. |
12836 | ||
2813c06e | 12837 | +----------------------------------------------------+ |
420a0d19 | 12838 | |acl_smtp_mime|Use: main|Type: string*|Default: unset| |
2813c06e | 12839 | +----------------------------------------------------+ |
420a0d19 CE |
12840 | |
12841 | This option is available when Exim is built with the content-scanning | |
12842 | extension. It defines the ACL that is run for each MIME part in a message. See | |
2813c06e CE |
12843 | section 44.4 for details. |
12844 | ||
12845 | +-------------------------------------------------------+ | |
12846 | |acl_smtp_notquit|Use: main|Type: string*|Default: unset| | |
12847 | +-------------------------------------------------------+ | |
420a0d19 | 12848 | |
2813c06e CE |
12849 | This option defines the ACL that is run when an SMTP session ends without a |
12850 | QUIT command being received. See chapter 43 for further details. | |
12851 | ||
12852 | +-------------------------------------------------------+ | |
420a0d19 | 12853 | |acl_smtp_predata|Use: main|Type: string*|Default: unset| |
2813c06e | 12854 | +-------------------------------------------------------+ |
420a0d19 CE |
12855 | |
12856 | This option defines the ACL that is run when an SMTP DATA command is received, | |
2813c06e | 12857 | before the message itself is received. See chapter 43 for further details. |
420a0d19 | 12858 | |
2813c06e | 12859 | +----------------------------------------------------+ |
420a0d19 | 12860 | |acl_smtp_quit|Use: main|Type: string*|Default: unset| |
2813c06e | 12861 | +----------------------------------------------------+ |
420a0d19 CE |
12862 | |
12863 | This option defines the ACL that is run when an SMTP QUIT command is received. | |
2813c06e | 12864 | See chapter 43 for further details. |
420a0d19 | 12865 | |
2813c06e | 12866 | +----------------------------------------------------+ |
420a0d19 | 12867 | |acl_smtp_rcpt|Use: main|Type: string*|Default: unset| |
2813c06e | 12868 | +----------------------------------------------------+ |
420a0d19 CE |
12869 | |
12870 | This option defines the ACL that is run when an SMTP RCPT command is received. | |
2813c06e | 12871 | See chapter 43 for further details. |
420a0d19 | 12872 | |
2813c06e | 12873 | +--------------------------------------------------------+ |
420a0d19 | 12874 | |acl_smtp_starttls|Use: main|Type: string*|Default: unset| |
2813c06e | 12875 | +--------------------------------------------------------+ |
420a0d19 CE |
12876 | |
12877 | This option defines the ACL that is run when an SMTP STARTTLS command is | |
2813c06e | 12878 | received. See chapter 43 for further details. |
420a0d19 | 12879 | |
2813c06e | 12880 | +----------------------------------------------------+ |
420a0d19 | 12881 | |acl_smtp_vrfy|Use: main|Type: string*|Default: unset| |
2813c06e | 12882 | +----------------------------------------------------+ |
420a0d19 CE |
12883 | |
12884 | This option defines the ACL that is run when an SMTP VRFY command is received. | |
2813c06e CE |
12885 | See chapter 43 for further details. |
12886 | ||
12887 | +----------------------------------------------------------+ | |
12888 | |add_environment|Use: main|Type: string list|Default: empty| | |
12889 | +----------------------------------------------------------+ | |
420a0d19 | 12890 | |
2813c06e CE |
12891 | This option allows to set individual environment variables that the currently |
12892 | linked libraries and programs in child processes use. See 29.4 for the | |
12893 | environment of pipe transports. | |
12894 | ||
12895 | +--------------------------------------------------------+ | |
420a0d19 | 12896 | |admin_groups|Use: main|Type: string list*|Default: unset| |
2813c06e | 12897 | +--------------------------------------------------------+ |
420a0d19 CE |
12898 | |
12899 | This option is expanded just once, at the start of Exim's processing. If the | |
12900 | current group or any of the supplementary groups of an Exim caller is in this | |
12901 | colon-separated list, the caller has admin privileges. If all your system | |
12902 | programmers are in a specific group, for example, you can give them all Exim | |
12903 | admin privileges by putting that group in admin_groups. However, this does not | |
12904 | permit them to read Exim's spool files (whose group owner is the Exim gid). To | |
12905 | permit this, you have to add individuals to the Exim group. | |
12906 | ||
2813c06e | 12907 | +------------------------------------------------------------+ |
420a0d19 | 12908 | |allow_domain_literals|Use: main|Type: boolean|Default: false| |
2813c06e | 12909 | +------------------------------------------------------------+ |
420a0d19 CE |
12910 | |
12911 | If this option is set, the RFC 2822 domain literal format is permitted in email | |
12912 | addresses. The option is not set by default, because the domain literal format | |
12913 | is not normally required these days, and few people know about it. It has, | |
12914 | however, been exploited by mail abusers. | |
12915 | ||
12916 | Unfortunately, it seems that some DNS black list maintainers are using this | |
12917 | format to report black listing to postmasters. If you want to accept messages | |
12918 | addressed to your hosts by IP address, you need to set allow_domain_literals | |
12919 | true, and also to add "@[]" to the list of local domains (defined in the named | |
12920 | domain list local_domains in the default configuration). This "magic string" | |
12921 | matches the domain literal form of all the local host's IP addresses. | |
12922 | ||
2813c06e | 12923 | +-----------------------------------------------------+ |
420a0d19 | 12924 | |allow_mx_to_ip|Use: main|Type: boolean|Default: false| |
2813c06e | 12925 | +-----------------------------------------------------+ |
420a0d19 CE |
12926 | |
12927 | It appears that more and more DNS zone administrators are breaking the rules | |
12928 | and putting domain names that look like IP addresses on the right hand side of | |
12929 | MX records. Exim follows the rules and rejects this, giving an error message | |
2813c06e | 12930 | that explains the misconfiguration. However, some other MTAs support this |
420a0d19 CE |
12931 | practice, so to avoid "Why can't Exim do this?" complaints, allow_mx_to_ip |
12932 | exists, in order to enable this heinous activity. It is not recommended, except | |
12933 | when you have no other choice. | |
12934 | ||
2813c06e | 12935 | +---------------------------------------------------------+ |
420a0d19 | 12936 | |allow_utf8_domains|Use: main|Type: boolean|Default: false| |
2813c06e | 12937 | +---------------------------------------------------------+ |
420a0d19 CE |
12938 | |
12939 | Lots of discussion is going on about internationalized domain names. One camp | |
12940 | is strongly in favour of just using UTF-8 characters, and it seems that at | |
12941 | least two other MTAs permit this. This option allows Exim users to experiment | |
12942 | if they wish. | |
12943 | ||
12944 | If it is set true, Exim's domain parsing function allows valid UTF-8 | |
12945 | multicharacters to appear in domain name components, in addition to letters, | |
12946 | digits, and hyphens. However, just setting this option is not enough; if you | |
12947 | want to look up these domain names in the DNS, you must also adjust the value | |
12948 | of dns_check_names_pattern to match the extended form. A suitable setting is: | |
12949 | ||
12950 | dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\ | |
12951 | (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$ | |
12952 | ||
12953 | Alternatively, you can just disable this feature by setting | |
12954 | ||
12955 | dns_check_names_pattern = | |
12956 | ||
12957 | That is, set the option to an empty string so that no check is done. | |
12958 | ||
2813c06e | 12959 | +----------------------------------------------------------+ |
420a0d19 | 12960 | |auth_advertise_hosts|Use: main|Type: host list*|Default: *| |
2813c06e | 12961 | +----------------------------------------------------------+ |
420a0d19 CE |
12962 | |
12963 | If any server authentication mechanisms are configured, Exim advertises them in | |
12964 | response to an EHLO command only if the calling host matches this list. | |
12965 | Otherwise, Exim does not advertise AUTH. Exim does not accept AUTH commands | |
12966 | from clients to which it has not advertised the availability of AUTH. The | |
12967 | advertising of individual authentication mechanisms can be controlled by the | |
12968 | use of the server_advertise_condition generic authenticator option on the | |
12969 | individual authenticators. See chapter 33 for further details. | |
12970 | ||
12971 | Certain mail clients (for example, Netscape) require the user to provide a name | |
12972 | and password for authentication if AUTH is advertised, even though it may not | |
12973 | be needed (the host may accept messages from hosts on its local LAN without | |
12974 | authentication, for example). The auth_advertise_hosts option can be used to | |
12975 | make these clients more friendly by excluding them from the set of hosts to | |
12976 | which Exim advertises AUTH. | |
12977 | ||
12978 | If you want to advertise the availability of AUTH only when the connection is | |
12979 | encrypted using TLS, you can make use of the fact that the value of this option | |
12980 | is expanded, with a setting like this: | |
12981 | ||
12982 | auth_advertise_hosts = ${if eq{$tls_in_cipher}{}{}{*}} | |
12983 | ||
12984 | If $tls_in_cipher is empty, the session is not encrypted, and the result of the | |
12985 | expansion is empty, thus matching no hosts. Otherwise, the result of the | |
12986 | expansion is *, which matches all hosts. | |
12987 | ||
2813c06e | 12988 | +------------------------------------------+ |
420a0d19 | 12989 | |auto_thaw|Use: main|Type: time|Default: 0s| |
2813c06e | 12990 | +------------------------------------------+ |
420a0d19 CE |
12991 | |
12992 | If this option is set to a time greater than zero, a queue runner will try a | |
12993 | new delivery attempt on any frozen message, other than a bounce message, if | |
12994 | this much time has passed since it was frozen. This may result in the message | |
12995 | being re-frozen if nothing has changed since the last attempt. It is a way of | |
12996 | saying "keep on trying, even though there are big problems". | |
12997 | ||
12998 | Note: This is an old option, which predates timeout_frozen_after and | |
12999 | ignore_bounce_errors_after. It is retained for compatibility, but it is not | |
13000 | thought to be very useful any more, and its use should probably be avoided. | |
13001 | ||
2813c06e | 13002 | +----------------------------------------------------+ |
420a0d19 | 13003 | |av_scanner|Use: main|Type: string|Default: see below| |
2813c06e | 13004 | +----------------------------------------------------+ |
420a0d19 CE |
13005 | |
13006 | This option is available if Exim is built with the content-scanning extension. | |
13007 | It specifies which anti-virus scanner to use. The default value is: | |
13008 | ||
13009 | sophie:/var/run/sophie | |
13010 | ||
13011 | If the value of av_scanner starts with a dollar character, it is expanded | |
2813c06e | 13012 | before use. See section 44.1 for further details. |
420a0d19 | 13013 | |
2813c06e | 13014 | +------------------------------------------------+ |
420a0d19 | 13015 | |bi_command|Use: main|Type: string|Default: unset| |
2813c06e | 13016 | +------------------------------------------------+ |
420a0d19 CE |
13017 | |
13018 | This option supplies the name of a command that is run when Exim is called with | |
13019 | the -bi option (see chapter 5). The string value is just the command name, it | |
13020 | is not a complete command line. If an argument is required, it must come from | |
13021 | the -oA command line option. | |
13022 | ||
2813c06e | 13023 | +---------------------------------------------------------+ |
420a0d19 | 13024 | |bounce_message_file|Use: main|Type: string|Default: unset| |
2813c06e | 13025 | +---------------------------------------------------------+ |
420a0d19 CE |
13026 | |
13027 | This option defines a template file containing paragraphs of text to be used | |
13028 | for constructing bounce messages. Details of the file's contents are given in | |
2813c06e | 13029 | chapter 49. See also warn_message_file. |
420a0d19 | 13030 | |
2813c06e | 13031 | +---------------------------------------------------------+ |
420a0d19 | 13032 | |bounce_message_text|Use: main|Type: string|Default: unset| |
2813c06e | 13033 | +---------------------------------------------------------+ |
420a0d19 CE |
13034 | |
13035 | When this option is set, its contents are included in the default bounce | |
13036 | message immediately after "This message was created automatically by mail | |
13037 | delivery software." It is not used if bounce_message_file is set. | |
13038 | ||
2813c06e | 13039 | +--------------------------------------------------------+ |
420a0d19 | 13040 | |bounce_return_body|Use: main|Type: boolean|Default: true| |
2813c06e | 13041 | +--------------------------------------------------------+ |
420a0d19 CE |
13042 | |
13043 | This option controls whether the body of an incoming message is included in a | |
13044 | bounce message when bounce_return_message is true. The default setting causes | |
13045 | the entire message, both header and body, to be returned (subject to the value | |
13046 | of bounce_return_size_limit). If this option is false, only the message header | |
13047 | is included. In the case of a non-SMTP message containing an error that is | |
13048 | detected during reception, only those header lines preceding the point at which | |
13049 | the error was detected are returned. | |
13050 | ||
2813c06e CE |
13051 | +-----------------------------------------------------------------+ |
13052 | |bounce_return_linesize_limit|Use: main|Type: integer|Default: 998| | |
13053 | +-----------------------------------------------------------------+ | |
13054 | ||
13055 | This option sets a limit in bytes on the line length of messages that are | |
13056 | returned to senders due to delivery problems, when bounce_return_message is | |
13057 | true. The default value corresponds to RFC limits. If the message being | |
13058 | returned has lines longer than this value it is treated as if the | |
13059 | bounce_return_size_limit (below) restriction was exceeded. | |
13060 | ||
13061 | The option also applies to bounces returned when an error is detected during | |
13062 | reception of a message. In this case lines from the original are truncated. | |
13063 | ||
13064 | The option does not apply to messages generated by an autoreply transport. | |
13065 | ||
13066 | +-----------------------------------------------------------+ | |
420a0d19 | 13067 | |bounce_return_message|Use: main|Type: boolean|Default: true| |
2813c06e | 13068 | +-----------------------------------------------------------+ |
420a0d19 CE |
13069 | |
13070 | If this option is set false, none of the original message is included in bounce | |
13071 | messages generated by Exim. See also bounce_return_size_limit and | |
13072 | bounce_return_body. | |
13073 | ||
2813c06e | 13074 | +--------------------------------------------------------------+ |
420a0d19 | 13075 | |bounce_return_size_limit|Use: main|Type: integer|Default: 100K| |
2813c06e | 13076 | +--------------------------------------------------------------+ |
420a0d19 CE |
13077 | |
13078 | This option sets a limit in bytes on the size of messages that are returned to | |
13079 | senders as part of bounce messages when bounce_return_message is true. The | |
13080 | limit should be less than the value of the global message_size_limit and of any | |
13081 | message_size_limit settings on transports, to allow for the bounce text that | |
13082 | Exim generates. If this option is set to zero there is no limit. | |
13083 | ||
13084 | When the body of any message that is to be included in a bounce message is | |
13085 | greater than the limit, it is truncated, and a comment pointing this out is | |
13086 | added at the top. The actual cutoff may be greater than the value given, owing | |
13087 | to the use of buffering for transferring the message in chunks (typically 8K in | |
13088 | size). The idea is to save bandwidth on those undeliverable 15-megabyte | |
13089 | messages. | |
13090 | ||
2813c06e | 13091 | +------------------------------------------------------------------+ |
420a0d19 | 13092 | |bounce_sender_authentication|Use: main|Type: string|Default: unset| |
2813c06e | 13093 | +------------------------------------------------------------------+ |
420a0d19 CE |
13094 | |
13095 | This option provides an authenticated sender address that is sent with any | |
13096 | bounce messages generated by Exim that are sent over an authenticated SMTP | |
13097 | connection. A typical setting might be: | |
13098 | ||
13099 | bounce_sender_authentication = mailer-daemon@my.domain.example | |
13100 | ||
13101 | which would cause bounce messages to be sent using the SMTP command: | |
13102 | ||
13103 | MAIL FROM:<> AUTH=mailer-daemon@my.domain.example | |
13104 | ||
13105 | The value of bounce_sender_authentication must always be a complete email | |
13106 | address. | |
13107 | ||
2813c06e | 13108 | +---------------------------------------------------------------+ |
420a0d19 | 13109 | |callout_domain_negative_expire|Use: main|Type: time|Default: 3h| |
2813c06e | 13110 | +---------------------------------------------------------------+ |
420a0d19 CE |
13111 | |
13112 | This option specifies the expiry time for negative callout cache data for a | |
2813c06e CE |
13113 | domain. See section 43.45 for details of callout verification, and section |
13114 | 43.47 for details of the caching. | |
420a0d19 | 13115 | |
2813c06e | 13116 | +---------------------------------------------------------------+ |
420a0d19 | 13117 | |callout_domain_positive_expire|Use: main|Type: time|Default: 7d| |
2813c06e | 13118 | +---------------------------------------------------------------+ |
420a0d19 CE |
13119 | |
13120 | This option specifies the expiry time for positive callout cache data for a | |
2813c06e CE |
13121 | domain. See section 43.45 for details of callout verification, and section |
13122 | 43.47 for details of the caching. | |
420a0d19 | 13123 | |
2813c06e | 13124 | +--------------------------------------------------------+ |
420a0d19 | 13125 | |callout_negative_expire|Use: main|Type: time|Default: 2h| |
2813c06e | 13126 | +--------------------------------------------------------+ |
420a0d19 CE |
13127 | |
13128 | This option specifies the expiry time for negative callout cache data for an | |
2813c06e CE |
13129 | address. See section 43.45 for details of callout verification, and section |
13130 | 43.47 for details of the caching. | |
420a0d19 | 13131 | |
2813c06e | 13132 | +---------------------------------------------------------+ |
420a0d19 | 13133 | |callout_positive_expire|Use: main|Type: time|Default: 24h| |
2813c06e | 13134 | +---------------------------------------------------------+ |
420a0d19 CE |
13135 | |
13136 | This option specifies the expiry time for positive callout cache data for an | |
2813c06e CE |
13137 | address. See section 43.45 for details of callout verification, and section |
13138 | 43.47 for details of the caching. | |
420a0d19 | 13139 | |
2813c06e | 13140 | +--------------------------------------------------------------------+ |
420a0d19 | 13141 | |callout_random_local_part|Use: main|Type: string*|Default: see below| |
2813c06e | 13142 | +--------------------------------------------------------------------+ |
420a0d19 CE |
13143 | |
13144 | This option defines the "random" local part that can be used as part of callout | |
13145 | verification. The default value is | |
13146 | ||
13147 | $primary_hostname-$tod_epoch-testing | |
13148 | ||
2813c06e | 13149 | See section 43.46 for details of how this value is used. |
420a0d19 | 13150 | |
2813c06e CE |
13151 | +-----------------------------------------------------+ |
13152 | |check_log_inodes|Use: main|Type: integer|Default: 100| | |
13153 | +-----------------------------------------------------+ | |
420a0d19 CE |
13154 | |
13155 | See check_spool_space below. | |
13156 | ||
2813c06e CE |
13157 | +----------------------------------------------------+ |
13158 | |check_log_space|Use: main|Type: integer|Default: 10M| | |
13159 | +----------------------------------------------------+ | |
420a0d19 CE |
13160 | |
13161 | See check_spool_space below. | |
13162 | ||
2813c06e | 13163 | +----------------------------------------------------------+ |
420a0d19 | 13164 | |check_rfc2047_length|Use: main|Type: boolean|Default: true| |
2813c06e | 13165 | +----------------------------------------------------------+ |
420a0d19 CE |
13166 | |
13167 | RFC 2047 defines a way of encoding non-ASCII characters in headers using a | |
13168 | system of "encoded words". The RFC specifies a maximum length for an encoded | |
13169 | word; strings to be encoded that exceed this length are supposed to use | |
13170 | multiple encoded words. By default, Exim does not recognize encoded words that | |
13171 | exceed the maximum length. However, it seems that some software, in violation | |
13172 | of the RFC, generates overlong encoded words. If check_rfc2047_length is set | |
13173 | false, Exim recognizes encoded words of any length. | |
13174 | ||
2813c06e CE |
13175 | +-------------------------------------------------------+ |
13176 | |check_spool_inodes|Use: main|Type: integer|Default: 100| | |
13177 | +-------------------------------------------------------+ | |
420a0d19 CE |
13178 | |
13179 | See check_spool_space below. | |
13180 | ||
2813c06e CE |
13181 | +------------------------------------------------------+ |
13182 | |check_spool_space|Use: main|Type: integer|Default: 10M| | |
13183 | +------------------------------------------------------+ | |
420a0d19 CE |
13184 | |
13185 | The four check_... options allow for checking of disk resources before a | |
13186 | message is accepted. | |
13187 | ||
2813c06e CE |
13188 | When any of these options are nonzero, they apply to all incoming messages. If |
13189 | you want to apply different checks to different kinds of message, you can do so | |
13190 | by testing the variables $log_inodes, $log_space, $spool_inodes, and | |
13191 | $spool_space in an ACL with appropriate additional conditions. | |
420a0d19 CE |
13192 | |
13193 | check_spool_space and check_spool_inodes check the spool partition if either | |
13194 | value is greater than zero, for example: | |
13195 | ||
2813c06e | 13196 | check_spool_space = 100M |
420a0d19 CE |
13197 | check_spool_inodes = 100 |
13198 | ||
13199 | The spool partition is the one that contains the directory defined by | |
13200 | SPOOL_DIRECTORY in Local/Makefile. It is used for holding messages in transit. | |
13201 | ||
13202 | check_log_space and check_log_inodes check the partition in which log files are | |
13203 | written if either is greater than zero. These should be set only if | |
13204 | log_file_path and spool_directory refer to different partitions. | |
13205 | ||
13206 | If there is less space or fewer inodes than requested, Exim refuses to accept | |
13207 | incoming mail. In the case of SMTP input this is done by giving a 452 temporary | |
13208 | error response to the MAIL command. If ESMTP is in use and there was a SIZE | |
13209 | parameter on the MAIL command, its value is added to the check_spool_space | |
13210 | value, and the check is performed even if check_spool_space is zero, unless | |
13211 | no_smtp_check_spool_space is set. | |
13212 | ||
13213 | The values for check_spool_space and check_log_space are held as a number of | |
2813c06e CE |
13214 | kilobytes (though specified in bytes). If a non-multiple of 1024 is specified, |
13215 | it is rounded up. | |
420a0d19 CE |
13216 | |
13217 | For non-SMTP input and for batched SMTP input, the test is done at start-up; on | |
13218 | failure a message is written to stderr and Exim exits with a non-zero code, as | |
13219 | it obviously cannot send an error message of any kind. | |
13220 | ||
2813c06e CE |
13221 | There is a slight performance penalty for these checks. Versions of Exim |
13222 | preceding 4.88 had these disabled by default; high-rate installations confident | |
13223 | they will never run out of resources may wish to deliberately disable them. | |
13224 | ||
13225 | +--------------------------------------------------------------+ | |
13226 | |chunking_advertise_hosts|Use: main|Type: host list*|Default: *| | |
13227 | +--------------------------------------------------------------+ | |
13228 | ||
13229 | The CHUNKING extension (RFC3030) will be advertised in the EHLO message to | |
13230 | these hosts. Hosts may use the BDAT command as an alternate to DATA. | |
13231 | ||
13232 | +----------------------------------------------------+ | |
13233 | |debug_store|Use: main|Type: boolean|Default: "false"| | |
13234 | +----------------------------------------------------+ | |
13235 | ||
13236 | This option, when true, enables extra checking in Exim's internal memory | |
13237 | management. For use when a memory corruption issue is being investigated, it | |
13238 | should normally be left as default. | |
13239 | ||
13240 | +--------------------------------------------------------+ | |
420a0d19 | 13241 | |daemon_smtp_ports|Use: main|Type: string|Default: "smtp"| |
2813c06e | 13242 | +--------------------------------------------------------+ |
420a0d19 CE |
13243 | |
13244 | This option specifies one or more default SMTP ports on which the Exim daemon | |
13245 | listens. See chapter 13 for details of how it is used. For backward | |
13246 | compatibility, daemon_smtp_port (singular) is a synonym. | |
13247 | ||
2813c06e | 13248 | +---------------------------------------------------------+ |
420a0d19 | 13249 | |daemon_startup_retries|Use: main|Type: integer|Default: 9| |
2813c06e | 13250 | +---------------------------------------------------------+ |
420a0d19 CE |
13251 | |
13252 | This option, along with daemon_startup_sleep, controls the retrying done by the | |
13253 | daemon at startup when it cannot immediately bind a listening socket (typically | |
13254 | because the socket is already in use): daemon_startup_retries defines the | |
13255 | number of retries after the first failure, and daemon_startup_sleep defines the | |
13256 | length of time to wait between retries. | |
13257 | ||
2813c06e | 13258 | +------------------------------------------------------+ |
420a0d19 | 13259 | |daemon_startup_sleep|Use: main|Type: time|Default: 30s| |
2813c06e | 13260 | +------------------------------------------------------+ |
420a0d19 CE |
13261 | |
13262 | See daemon_startup_retries. | |
13263 | ||
2813c06e | 13264 | +----------------------------------------------------+ |
420a0d19 | 13265 | |delay_warning|Use: main|Type: time list|Default: 24h| |
2813c06e | 13266 | +----------------------------------------------------+ |
420a0d19 CE |
13267 | |
13268 | When a message is delayed, Exim sends a warning message to the sender at | |
13269 | intervals specified by this option. The data is a colon-separated list of times | |
13270 | after which to send warning messages. If the value of the option is an empty | |
13271 | string or a zero time, no warnings are sent. Up to 10 times may be given. If a | |
13272 | message has been on the queue for longer than the last time, the last interval | |
13273 | between the times is used to compute subsequent warning times. For example, | |
13274 | with | |
13275 | ||
13276 | delay_warning = 4h:8h:24h | |
13277 | ||
13278 | the first message is sent after 4 hours, the second after 8 hours, and the | |
13279 | third one after 24 hours. After that, messages are sent every 16 hours, because | |
13280 | that is the interval between the last two times on the list. If you set just | |
13281 | one time, it specifies the repeat interval. For example, with: | |
13282 | ||
13283 | delay_warning = 6h | |
13284 | ||
13285 | messages are repeated every six hours. To stop warnings after a given time, set | |
13286 | a very large time at the end of the list. For example: | |
13287 | ||
13288 | delay_warning = 2h:12h:99d | |
13289 | ||
13290 | Note that the option is only evaluated at the time a delivery attempt fails, | |
13291 | which depends on retry and queue-runner configuration. Typically retries will | |
13292 | be configured more frequently than warning messages. | |
13293 | ||
2813c06e | 13294 | +------------------------------------------------------------------+ |
420a0d19 | 13295 | |delay_warning_condition|Use: main|Type: string*|Default: see below| |
2813c06e | 13296 | +------------------------------------------------------------------+ |
420a0d19 CE |
13297 | |
13298 | The string is expanded at the time a warning message might be sent. If all the | |
13299 | deferred addresses have the same domain, it is set in $domain during the | |
13300 | expansion. Otherwise $domain is empty. If the result of the expansion is a | |
13301 | forced failure, an empty string, or a string matching any of "0", "no" or | |
13302 | "false" (the comparison being done caselessly) then the warning message is not | |
13303 | sent. The default is: | |
13304 | ||
13305 | delay_warning_condition = ${if or {\ | |
13306 | { !eq{$h_list-id:$h_list-post:$h_list-subscribe:}{} }\ | |
13307 | { match{$h_precedence:}{(?i)bulk|list|junk} }\ | |
13308 | { match{$h_auto-submitted:}{(?i)auto-generated|auto-replied} }\ | |
13309 | } {no}{yes}} | |
13310 | ||
13311 | This suppresses the sending of warnings for messages that contain List-ID:, | |
13312 | List-Post:, or List-Subscribe: headers, or have "bulk", "list" or "junk" in a | |
13313 | Precedence: header, or have "auto-generated" or "auto-replied" in an | |
13314 | Auto-Submitted: header. | |
13315 | ||
2813c06e | 13316 | +-------------------------------------------------------------+ |
420a0d19 | 13317 | |deliver_drop_privilege|Use: main|Type: boolean|Default: false| |
2813c06e | 13318 | +-------------------------------------------------------------+ |
420a0d19 CE |
13319 | |
13320 | If this option is set true, Exim drops its root privilege at the start of a | |
13321 | delivery process, and runs as the Exim user throughout. This severely restricts | |
13322 | the kinds of local delivery that are possible, but is viable in certain types | |
13323 | of configuration. There is a discussion about the use of root privilege in | |
2813c06e | 13324 | chapter 55. |
420a0d19 | 13325 | |
2813c06e | 13326 | +-----------------------------------------------------------------+ |
420a0d19 | 13327 | |deliver_queue_load_max|Use: main|Type: fixed-point|Default: unset| |
2813c06e | 13328 | +-----------------------------------------------------------------+ |
420a0d19 CE |
13329 | |
13330 | When this option is set, a queue run is abandoned if the system load average | |
13331 | becomes greater than the value of the option. The option has no effect on | |
13332 | ancient operating systems on which Exim cannot determine the load average. See | |
13333 | also queue_only_load and smtp_load_reserve. | |
13334 | ||
2813c06e | 13335 | +----------------------------------------------------------+ |
420a0d19 | 13336 | |delivery_date_remove|Use: main|Type: boolean|Default: true| |
2813c06e | 13337 | +----------------------------------------------------------+ |
420a0d19 CE |
13338 | |
13339 | Exim's transports have an option for adding a Delivery-date: header to a | |
13340 | message when it is delivered, in exactly the same way as Return-path: is | |
13341 | handled. Delivery-date: records the actual time of delivery. Such headers | |
13342 | should not be present in incoming messages, and this option causes them to be | |
13343 | removed at the time the message is received, to avoid any problems that might | |
13344 | occur when a delivered message is subsequently sent on to some other recipient. | |
13345 | ||
2813c06e | 13346 | +----------------------------------------------------+ |
420a0d19 | 13347 | |disable_fsync|Use: main|Type: boolean|Default: false| |
2813c06e | 13348 | +----------------------------------------------------+ |
420a0d19 CE |
13349 | |
13350 | This option is available only if Exim was built with the compile-time option | |
13351 | ENABLE_DISABLE_FSYNC. When this is not set, a reference to disable_fsync in a | |
13352 | runtime configuration generates an "unknown option" error. You should not build | |
13353 | Exim with ENABLE_DISABLE_FSYNC or set disable_fsync unless you really, really, | |
13354 | really understand what you are doing. No pre-compiled distributions of Exim | |
13355 | should ever make this option available. | |
13356 | ||
13357 | When disable_fsync is set true, Exim no longer calls fsync() to force updated | |
13358 | files' data to be written to disc before continuing. Unexpected events such as | |
13359 | crashes and power outages may cause data to be lost or scrambled. Here be | |
13360 | Dragons. Beware. | |
13361 | ||
2813c06e | 13362 | +---------------------------------------------------+ |
420a0d19 | 13363 | |disable_ipv6|Use: main|Type: boolean|Default: false| |
2813c06e | 13364 | +---------------------------------------------------+ |
420a0d19 CE |
13365 | |
13366 | If this option is set true, even if the Exim binary has IPv6 support, no IPv6 | |
13367 | activities take place. AAAA records are never looked up, and any IPv6 addresses | |
13368 | that are listed in local_interfaces, data for the manualroute router, etc. are | |
13369 | ignored. If IP literals are enabled, the ipliteral router declines to handle | |
13370 | IPv6 literal addresses. | |
13371 | ||
2813c06e CE |
13372 | +-----------------------------------------------------------------------+ |
13373 | |dkim_verify_signers|Use: main|Type: domain list*|Default: $dkim_signers| | |
13374 | +-----------------------------------------------------------------------+ | |
13375 | ||
13376 | This option gives a list of DKIM domains for which the DKIM ACL is run. It is | |
13377 | expanded after the message is received; by default it runs the ACL once for | |
13378 | each signature in the message. See chapter 57. | |
13379 | ||
13380 | +--------------------------------------------------------------------+ | |
420a0d19 | 13381 | |dns_again_means_nonexist|Use: main|Type: domain list*|Default: unset| |
2813c06e | 13382 | +--------------------------------------------------------------------+ |
420a0d19 CE |
13383 | |
13384 | DNS lookups give a "try again" response for the DNS errors "non-authoritative | |
13385 | host not found" and "SERVERFAIL". This can cause Exim to keep trying to deliver | |
13386 | a message, or to give repeated temporary errors to incoming mail. Sometimes the | |
13387 | effect is caused by a badly set up name server and may persist for a long time. | |
13388 | If a domain which exhibits this problem matches anything in | |
13389 | dns_again_means_nonexist, it is treated as if it did not exist. This option | |
13390 | should be used with care. You can make it apply to reverse lookups by a setting | |
13391 | such as this: | |
13392 | ||
13393 | dns_again_means_nonexist = *.in-addr.arpa | |
13394 | ||
13395 | This option applies to all DNS lookups that Exim does. It also applies when the | |
13396 | gethostbyname() or getipnodebyname() functions give temporary errors, since | |
13397 | these are most likely to be caused by DNS lookup problems. The dnslookup router | |
13398 | has some options of its own for controlling what happens when lookups for MX or | |
13399 | SRV records give temporary errors. These more specific options are applied | |
13400 | after this global option. | |
13401 | ||
2813c06e | 13402 | +-----------------------------------------------------------------+ |
420a0d19 | 13403 | |dns_check_names_pattern|Use: main|Type: string|Default: see below| |
2813c06e | 13404 | +-----------------------------------------------------------------+ |
420a0d19 CE |
13405 | |
13406 | When this option is set to a non-empty string, it causes Exim to check domain | |
13407 | names for characters that are not allowed in host names before handing them to | |
13408 | the DNS resolver, because some resolvers give temporary errors for names that | |
13409 | contain unusual characters. If a domain name contains any unwanted characters, | |
13410 | a "not found" result is forced, and the resolver is not called. The check is | |
13411 | done by matching the domain name against a regular expression, which is the | |
13412 | value of this option. The default pattern is | |
13413 | ||
13414 | dns_check_names_pattern = \ | |
13415 | (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9/-]*[^\W_])?)+$ | |
13416 | ||
13417 | which permits only letters, digits, slashes, and hyphens in components, but | |
13418 | they must start and end with a letter or digit. Slashes are not, in fact, | |
13419 | permitted in host names, but they are found in certain NS records (which can be | |
13420 | accessed in Exim by using a dnsdb lookup). If you set allow_utf8_domains, you | |
13421 | must modify this pattern, or set the option to an empty string. | |
13422 | ||
2813c06e | 13423 | +-------------------------------------------------------+ |
420a0d19 | 13424 | |dns_csa_search_limit|Use: main|Type: integer|Default: 5| |
2813c06e | 13425 | +-------------------------------------------------------+ |
420a0d19 CE |
13426 | |
13427 | This option controls the depth of parental searching for CSA SRV records in the | |
2813c06e | 13428 | DNS, as described in more detail in section 43.50. |
420a0d19 | 13429 | |
2813c06e | 13430 | +---------------------------------------------------------+ |
420a0d19 | 13431 | |dns_csa_use_reverse|Use: main|Type: boolean|Default: true| |
2813c06e | 13432 | +---------------------------------------------------------+ |
420a0d19 CE |
13433 | |
13434 | This option controls whether or not an IP address, given as a CSA domain, is | |
13435 | reversed and looked up in the reverse DNS, as described in more detail in | |
2813c06e | 13436 | section 43.50. |
420a0d19 | 13437 | |
2813c06e | 13438 | +-------------------------------------------------+ |
420a0d19 | 13439 | |dns_dnssec_ok|Use: main|Type: integer|Default: -1| |
2813c06e | 13440 | +-------------------------------------------------+ |
420a0d19 CE |
13441 | |
13442 | If this option is set to a non-negative number then Exim will initialise the | |
13443 | DNS resolver library to either use or not use DNSSEC, overriding the system | |
13444 | default. A value of 0 coerces DNSSEC off, a value of 1 coerces DNSSEC on. | |
13445 | ||
13446 | If the resolver library does not support DNSSEC then this option has no effect. | |
13447 | ||
2813c06e | 13448 | +-----------------------------------------------------------+ |
420a0d19 | 13449 | |dns_ipv4_lookup|Use: main|Type: domain list*|Default: unset| |
2813c06e | 13450 | +-----------------------------------------------------------+ |
420a0d19 CE |
13451 | |
13452 | When Exim is compiled with IPv6 support and disable_ipv6 is not set, it looks | |
13453 | for IPv6 address records (AAAA records) as well as IPv4 address records (A | |
13454 | records) when trying to find IP addresses for hosts, unless the host's domain | |
13455 | matches this list. | |
13456 | ||
13457 | This is a fudge to help with name servers that give big delays or otherwise do | |
13458 | not work for the AAAA record type. In due course, when the world's name servers | |
13459 | have all been upgraded, there should be no need for this option. | |
13460 | ||
2813c06e | 13461 | +--------------------------------------------+ |
420a0d19 | 13462 | |dns_retrans|Use: main|Type: time|Default: 0s| |
2813c06e | 13463 | +--------------------------------------------+ |
420a0d19 CE |
13464 | |
13465 | The options dns_retrans and dns_retry can be used to set the retransmission and | |
13466 | retry parameters for DNS lookups. Values of zero (the defaults) leave the | |
13467 | system default settings unchanged. The first value is the time between retries, | |
13468 | and the second is the number of retries. It isn't totally clear exactly how | |
13469 | these settings affect the total time a DNS lookup may take. I haven't found any | |
13470 | documentation about timeouts on DNS lookups; these parameter values are | |
13471 | available in the external resolver interface structure, but nowhere does it | |
2813c06e CE |
13472 | seem to describe how they are used or what you might want to set in them. See |
13473 | also the slow_lookup_log option. | |
420a0d19 | 13474 | |
2813c06e | 13475 | +--------------------------------------------+ |
420a0d19 | 13476 | |dns_retry|Use: main|Type: integer|Default: 0| |
2813c06e | 13477 | +--------------------------------------------+ |
420a0d19 CE |
13478 | |
13479 | See dns_retrans above. | |
13480 | ||
2813c06e CE |
13481 | +--------------------------------------------------------+ |
13482 | |dns_trust_aa|Use: main|Type: domain list*|Default: unset| | |
13483 | +--------------------------------------------------------+ | |
13484 | ||
13485 | If this option is set then lookup results marked with the AA bit (Authoritative | |
13486 | Answer) are trusted the same way as if they were DNSSEC-verified. The authority | |
13487 | section's name of the answer must match with this expanded domain list. | |
13488 | ||
13489 | Use this option only if you talk directly to a resolver that is authoritative | |
13490 | for some zones and does not set the AD (Authentic Data) bit in the answer. Some | |
13491 | DNS servers may have an configuration option to mark the answers from their own | |
13492 | zones as verified (they set the AD bit). Others do not have this option. It is | |
13493 | considered as poor practice using a resolver that is an authoritative server | |
13494 | for some zones. | |
13495 | ||
13496 | Use this option only if you really have to (e.g. if you want to use DANE for | |
13497 | remote delivery to a server that is listed in the DNS zones that your resolver | |
13498 | is authoritative for). | |
13499 | ||
13500 | If the DNS answer packet has the AA bit set and contains resource record in the | |
13501 | answer section, the name of the first NS record appearing in the authority | |
13502 | section is compared against the list. If the answer packet is authoritative but | |
13503 | the answer section is empty, the name of the first SOA record in the | |
13504 | authoritative section is used instead. | |
13505 | ||
13506 | +-------------------------------------------------+ | |
420a0d19 | 13507 | |dns_use_edns0|Use: main|Type: integer|Default: -1| |
2813c06e | 13508 | +-------------------------------------------------+ |
420a0d19 CE |
13509 | |
13510 | If this option is set to a non-negative number then Exim will initialise the | |
13511 | DNS resolver library to either use or not use EDNS0 extensions, overriding the | |
13512 | system default. A value of 0 coerces EDNS0 off, a value of 1 coerces EDNS0 on. | |
13513 | ||
13514 | If the resolver library does not support EDNS0 then this option has no effect. | |
13515 | ||
2813c06e CE |
13516 | OpenBSD's asr resolver routines are known to ignore the EDNS0 option; this |
13517 | means that DNSSEC will not work with Exim on that platform either, unless Exim | |
13518 | is linked against an alternative DNS client library. | |
13519 | ||
13520 | +----------------------------------------------+ | |
420a0d19 | 13521 | |drop_cr|Use: main|Type: boolean|Default: false| |
2813c06e | 13522 | +----------------------------------------------+ |
420a0d19 CE |
13523 | |
13524 | This is an obsolete option that is now a no-op. It used to affect the way Exim | |
13525 | handled CR and LF characters in incoming messages. What happens now is | |
2813c06e | 13526 | described in section 47.2. |
420a0d19 | 13527 | |
2813c06e CE |
13528 | +-------------------------------------------------------------+ |
13529 | |dsn_advertise_hosts|Use: main|Type: host list*|Default: unset| | |
13530 | +-------------------------------------------------------------+ | |
13531 | ||
13532 | DSN extensions (RFC3461) will be advertised in the EHLO message to, and | |
13533 | accepted from, these hosts. Hosts may use the NOTIFY and ENVID options on RCPT | |
13534 | TO commands, and RET and ORCPT options on MAIL FROM commands. A NOTIFY=SUCCESS | |
13535 | option requests success-DSN messages. A NOTIFY= option with no argument | |
13536 | requests that no delay or failure DSNs are sent. | |
13537 | ||
13538 | +---------------------------------------------------+ | |
420a0d19 | 13539 | |dsn_from|Use: main|Type: string*|Default: see below| |
2813c06e | 13540 | +---------------------------------------------------+ |
420a0d19 CE |
13541 | |
13542 | This option can be used to vary the contents of From: header lines in bounces | |
13543 | and other automatically generated messages ("Delivery Status Notifications" - | |
13544 | hence the name of the option). The default setting is: | |
13545 | ||
13546 | dsn_from = Mail Delivery System <Mailer-Daemon@$qualify_domain> | |
13547 | ||
13548 | The value is expanded every time it is needed. If the expansion fails, a panic | |
13549 | is logged, and the default value is used. | |
13550 | ||
2813c06e | 13551 | +--------------------------------------------------------+ |
420a0d19 | 13552 | |envelope_to_remove|Use: main|Type: boolean|Default: true| |
2813c06e | 13553 | +--------------------------------------------------------+ |
420a0d19 CE |
13554 | |
13555 | Exim's transports have an option for adding an Envelope-to: header to a message | |
13556 | when it is delivered, in exactly the same way as Return-path: is handled. | |
2813c06e CE |
13557 | Envelope-to: records the original recipient address from the message's envelope |
13558 | that caused the delivery to happen. Such headers should not be present in | |
13559 | incoming messages, and this option causes them to be removed at the time the | |
420a0d19 CE |
13560 | message is received, to avoid any problems that might occur when a delivered |
13561 | message is subsequently sent on to some other recipient. | |
13562 | ||
2813c06e | 13563 | +-------------------------------------------------------+ |
420a0d19 | 13564 | |errors_copy|Use: main|Type: string list*|Default: unset| |
2813c06e | 13565 | +-------------------------------------------------------+ |
420a0d19 CE |
13566 | |
13567 | Setting this option causes Exim to send bcc copies of bounce messages that it | |
13568 | generates to other addresses. Note: This does not apply to bounce messages | |
13569 | coming from elsewhere. The value of the option is a colon-separated list of | |
13570 | items. Each item consists of a pattern, terminated by white space, followed by | |
13571 | a comma-separated list of email addresses. If a pattern contains spaces, it | |
13572 | must be enclosed in double quotes. | |
13573 | ||
13574 | Each pattern is processed in the same way as a single item in an address list | |
13575 | (see section 10.19). When a pattern matches the recipient of the bounce | |
13576 | message, the message is copied to the addresses on the list. The items are | |
13577 | scanned in order, and once a matching one is found, no further items are | |
13578 | examined. For example: | |
13579 | ||
13580 | errors_copy = spqr@mydomain postmaster@mydomain.example :\ | |
13581 | rqps@mydomain hostmaster@mydomain.example,\ | |
13582 | postmaster@mydomain.example | |
13583 | ||
13584 | The address list is expanded before use. The expansion variables $local_part | |
13585 | and $domain are set from the original recipient of the error message, and if | |
13586 | there was any wildcard matching in the pattern, the expansion variables $0, $1, | |
13587 | etc. are set in the normal way. | |
13588 | ||
2813c06e | 13589 | +-----------------------------------------------------+ |
420a0d19 | 13590 | |errors_reply_to|Use: main|Type: string|Default: unset| |
2813c06e | 13591 | +-----------------------------------------------------+ |
420a0d19 CE |
13592 | |
13593 | By default, Exim's bounce and delivery warning messages contain the header line | |
13594 | ||
13595 | From: Mail Delivery System <Mailer-Daemon@qualify-domain> | |
13596 | ||
13597 | where qualify-domain is the value of the qualify_domain option. A warning | |
13598 | message that is generated by the quota_warn_message option in an appendfile | |
13599 | transport may contain its own From: header line that overrides the default. | |
13600 | ||
13601 | Experience shows that people reply to bounce messages. If the errors_reply_to | |
13602 | option is set, a Reply-To: header is added to bounce and warning messages. For | |
13603 | example: | |
13604 | ||
13605 | errors_reply_to = postmaster@my.domain.example | |
13606 | ||
13607 | The value of the option is not expanded. It must specify a valid RFC 2822 | |
13608 | address. However, if a warning message that is generated by the | |
13609 | quota_warn_message option in an appendfile transport contain its own Reply-To: | |
13610 | header line, the value of the errors_reply_to option is not used. | |
13611 | ||
2813c06e CE |
13612 | +---------------------------------------------------+ |
13613 | |event_action|Use: main|Type: string*|Default: unset| | |
13614 | +---------------------------------------------------+ | |
13615 | ||
13616 | This option declares a string to be expanded for Exim's events mechanism. For | |
13617 | details see chapter 60. | |
13618 | ||
13619 | +------------------------------------------------------------------+ | |
420a0d19 | 13620 | |exim_group|Use: main|Type: string|Default: compile-time configured| |
2813c06e | 13621 | +------------------------------------------------------------------+ |
420a0d19 CE |
13622 | |
13623 | This option changes the gid under which Exim runs when it gives up root | |
13624 | privilege. The default value is compiled into the binary. The value of this | |
13625 | option is used only when exim_user is also set. Unless it consists entirely of | |
13626 | digits, the string is looked up using getgrnam(), and failure causes a | |
2813c06e | 13627 | configuration error. See chapter 55 for a discussion of security issues. |
420a0d19 | 13628 | |
2813c06e | 13629 | +---------------------------------------------------+ |
420a0d19 | 13630 | |exim_path|Use: main|Type: string|Default: see below| |
2813c06e | 13631 | +---------------------------------------------------+ |
420a0d19 CE |
13632 | |
13633 | This option specifies the path name of the Exim binary, which is used when Exim | |
13634 | needs to re-exec itself. The default is set up to point to the file exim in the | |
13635 | directory configured at compile time by the BIN_DIRECTORY setting. It is | |
13636 | necessary to change exim_path if, exceptionally, Exim is run from some other | |
13637 | place. Warning: Do not use a macro to define the value of this option, because | |
13638 | you will break those Exim utilities that scan the configuration file to find | |
13639 | where the binary is. (They then use the -bP option to extract option settings | |
13640 | such as the value of spool_directory.) | |
13641 | ||
2813c06e | 13642 | +-----------------------------------------------------------------+ |
420a0d19 | 13643 | |exim_user|Use: main|Type: string|Default: compile-time configured| |
2813c06e | 13644 | +-----------------------------------------------------------------+ |
420a0d19 CE |
13645 | |
13646 | This option changes the uid under which Exim runs when it gives up root | |
13647 | privilege. The default value is compiled into the binary. Ownership of the run | |
13648 | time configuration file and the use of the -C and -D command line options is | |
13649 | checked against the values in the binary, not what is set here. | |
13650 | ||
13651 | Unless it consists entirely of digits, the string is looked up using getpwnam() | |
13652 | , and failure causes a configuration error. If exim_group is not also supplied, | |
2813c06e | 13653 | the gid is taken from the result of getpwnam() if it is used. See chapter 55 |
420a0d19 CE |
13654 | for a discussion of security issues. |
13655 | ||
2813c06e | 13656 | +-----------------------------------------------------------------+ |
420a0d19 | 13657 | |extra_local_interfaces|Use: main|Type: string list|Default: unset| |
2813c06e | 13658 | +-----------------------------------------------------------------+ |
420a0d19 CE |
13659 | |
13660 | This option defines network interfaces that are to be considered local when | |
13661 | routing, but which are not used for listening by the daemon. See section 13.8 | |
13662 | for details. | |
13663 | ||
2813c06e CE |
13664 | +------------------------------------------------------------------------+ |
13665 | |extract_addresses_remove_arguments|Use: main|Type: boolean|Default: true| | |
13666 | +------------------------------------------------------------------------+ | |
420a0d19 CE |
13667 | |
13668 | According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses | |
13669 | are present on the command line when the -t option is used to build an envelope | |
13670 | from a message's To:, Cc: and Bcc: headers, the command line addresses are | |
13671 | removed from the recipients list. This is also how Smail behaves. However, | |
13672 | other Sendmail documentation (the O'Reilly book) states that command line | |
13673 | addresses are added to those obtained from the header lines. When | |
13674 | extract_addresses_remove_arguments is true (the default), Exim subtracts | |
13675 | argument headers. If it is set false, Exim adds rather than removes argument | |
13676 | addresses. | |
13677 | ||
2813c06e | 13678 | +---------------------------------------------------+ |
420a0d19 | 13679 | |finduser_retries|Use: main|Type: integer|Default: 0| |
2813c06e | 13680 | +---------------------------------------------------+ |
420a0d19 CE |
13681 | |
13682 | On systems running NIS or other schemes in which user and group information is | |
13683 | distributed from a remote system, there can be times when getpwnam() and | |
13684 | related functions fail, even when given valid data, because things time out. | |
13685 | Unfortunately these failures cannot be distinguished from genuine "not found" | |
13686 | errors. If finduser_retries is set greater than zero, Exim will try that many | |
13687 | extra times to find a user or a group, waiting for one second between retries. | |
13688 | ||
13689 | You should not set this option greater than zero if your user information is in | |
13690 | a traditional /etc/passwd file, because it will cause Exim needlessly to search | |
13691 | the file multiple times for non-existent users, and also cause delay. | |
13692 | ||
2813c06e | 13693 | +-----------------------------------------------------------------------+ |
420a0d19 | 13694 | |freeze_tell|Use: main|Type: string list, comma separated|Default: unset| |
2813c06e | 13695 | +-----------------------------------------------------------------------+ |
420a0d19 CE |
13696 | |
13697 | On encountering certain errors, or when configured to do so in a system filter, | |
13698 | ACL, or special router, Exim freezes a message. This means that no further | |
13699 | delivery attempts take place until an administrator thaws the message, or the | |
13700 | auto_thaw, ignore_bounce_errors_after, or timeout_frozen_after feature cause it | |
13701 | to be processed. If freeze_tell is set, Exim generates a warning message | |
13702 | whenever it freezes something, unless the message it is freezing is a | |
13703 | locally-generated bounce message. (Without this exception there is the | |
13704 | possibility of looping.) The warning message is sent to the addresses supplied | |
13705 | as the comma-separated value of this option. If several of the message's | |
13706 | addresses cause freezing, only a single message is sent. If the freezing was | |
13707 | automatic, the reason(s) for freezing can be found in the message log. If you | |
13708 | configure freezing in a filter or ACL, you must arrange for any logging that | |
13709 | you require. | |
13710 | ||
2813c06e | 13711 | +-------------------------------------------------+ |
420a0d19 | 13712 | |gecos_name|Use: main|Type: string*|Default: unset| |
2813c06e | 13713 | +-------------------------------------------------+ |
420a0d19 CE |
13714 | |
13715 | Some operating systems, notably HP-UX, use the "gecos" field in the system | |
13716 | password file to hold other information in addition to users' real names. Exim | |
13717 | looks up this field for use when it is creating Sender: or From: headers. If | |
13718 | either gecos_pattern or gecos_name are unset, the contents of the field are | |
13719 | used unchanged, except that, if an ampersand is encountered, it is replaced by | |
13720 | the user's login name with the first character forced to upper case, since this | |
13721 | is a convention that is observed on many systems. | |
13722 | ||
13723 | When these options are set, gecos_pattern is treated as a regular expression | |
13724 | that is to be applied to the field (again with & replaced by the login name), | |
13725 | and if it matches, gecos_name is expanded and used as the user's name. | |
13726 | ||
13727 | Numeric variables such as $1, $2, etc. can be used in the expansion to pick up | |
13728 | sub-fields that were matched by the pattern. In HP-UX, where the user's name | |
13729 | terminates at the first comma, the following can be used: | |
13730 | ||
13731 | gecos_pattern = ([^,]*) | |
13732 | gecos_name = $1 | |
13733 | ||
2813c06e | 13734 | +---------------------------------------------------+ |
420a0d19 | 13735 | |gecos_pattern|Use: main|Type: string|Default: unset| |
2813c06e | 13736 | +---------------------------------------------------+ |
420a0d19 CE |
13737 | |
13738 | See gecos_name above. | |
13739 | ||
2813c06e | 13740 | +---------------------------------------------------------+ |
420a0d19 | 13741 | |gnutls_compat_mode|Use: main|Type: boolean|Default: unset| |
2813c06e | 13742 | +---------------------------------------------------------+ |
420a0d19 CE |
13743 | |
13744 | This option controls whether GnuTLS is used in compatibility mode in an Exim | |
13745 | server. This reduces security slightly, but improves interworking with older | |
13746 | implementations of TLS. | |
13747 | ||
13748 | option gnutls_allow_auto_pkcs11 main boolean unset This option will let GnuTLS | |
13749 | (2.12.0 or later) autoload PKCS11 modules with the p11-kit configuration files | |
13750 | in /etc/pkcs11/modules/. | |
13751 | ||
13752 | See http://www.gnutls.org/manual/gnutls.html#Smart-cards-and-HSMs for | |
13753 | documentation. | |
13754 | ||
2813c06e | 13755 | +---------------------------------------------------------+ |
420a0d19 | 13756 | |headers_charset|Use: main|Type: string|Default: see below| |
2813c06e | 13757 | +---------------------------------------------------------+ |
420a0d19 CE |
13758 | |
13759 | This option sets a default character set for translating from encoded MIME | |
13760 | "words" in header lines, when referenced by an $h_xxx expansion item. The | |
13761 | default is the value of HEADERS_CHARSET in Local/Makefile. The ultimate default | |
13762 | is ISO-8859-1. For more details see the description of header insertions in | |
13763 | section 11.5. | |
13764 | ||
2813c06e | 13765 | +---------------------------------------------------------+ |
420a0d19 | 13766 | |header_maxsize|Use: main|Type: integer|Default: see below| |
2813c06e | 13767 | +---------------------------------------------------------+ |
420a0d19 CE |
13768 | |
13769 | This option controls the overall maximum size of a message's header section. | |
13770 | The default is the value of HEADER_MAXSIZE in Local/Makefile; the default for | |
13771 | that is 1M. Messages with larger header sections are rejected. | |
13772 | ||
2813c06e | 13773 | +------------------------------------------------------+ |
420a0d19 | 13774 | |header_line_maxsize|Use: main|Type: integer|Default: 0| |
2813c06e | 13775 | +------------------------------------------------------+ |
420a0d19 CE |
13776 | |
13777 | This option limits the length of any individual header line in a message, after | |
13778 | all the continuations have been joined together. Messages with individual | |
13779 | header lines that are longer than the limit are rejected. The default value of | |
13780 | zero means "no limit". | |
13781 | ||
2813c06e | 13782 | +----------------------------------------------------------------+ |
420a0d19 | 13783 | |helo_accept_junk_hosts|Use: main|Type: host list*|Default: unset| |
2813c06e | 13784 | +----------------------------------------------------------------+ |
420a0d19 CE |
13785 | |
13786 | Exim checks the syntax of HELO and EHLO commands for incoming SMTP mail, and | |
13787 | gives an error response for invalid data. Unfortunately, there are some SMTP | |
13788 | clients that send syntactic junk. They can be accommodated by setting this | |
13789 | option. Note that this is a syntax check only. See helo_verify_hosts if you | |
13790 | want to do semantic checking. See also helo_allow_chars for a way of extending | |
13791 | the permitted character set. | |
13792 | ||
2813c06e | 13793 | +------------------------------------------------------+ |
420a0d19 | 13794 | |helo_allow_chars|Use: main|Type: string|Default: unset| |
2813c06e | 13795 | +------------------------------------------------------+ |
420a0d19 CE |
13796 | |
13797 | This option can be set to a string of rogue characters that are permitted in | |
13798 | all EHLO and HELO names in addition to the standard letters, digits, hyphens, | |
13799 | and dots. If you really must allow underscores, you can set | |
13800 | ||
13801 | helo_allow_chars = _ | |
13802 | ||
13803 | Note that the value is one string, not a list. | |
13804 | ||
2813c06e | 13805 | +-----------------------------------------------------------------+ |
420a0d19 | 13806 | |helo_lookup_domains|Use: main|Type: domain list*|Default: "@:@[]"| |
2813c06e | 13807 | +-----------------------------------------------------------------+ |
420a0d19 CE |
13808 | |
13809 | If the domain given by a client in a HELO or EHLO command matches this list, a | |
13810 | reverse lookup is done in order to establish the host's true name. The default | |
13811 | forces a lookup if the client host gives the server's name or any of its IP | |
13812 | addresses (in brackets), something that broken clients have been seen to do. | |
13813 | ||
2813c06e | 13814 | +---------------------------------------------------------------+ |
420a0d19 | 13815 | |helo_try_verify_hosts|Use: main|Type: host list*|Default: unset| |
2813c06e | 13816 | +---------------------------------------------------------------+ |
420a0d19 CE |
13817 | |
13818 | By default, Exim just checks the syntax of HELO and EHLO commands (see | |
13819 | helo_accept_junk_hosts and helo_allow_chars). However, some sites like to do | |
13820 | more extensive checking of the data supplied by these commands. The ACL | |
13821 | condition "verify = helo" is provided to make this possible. Formerly, it was | |
13822 | necessary also to set this option (helo_try_verify_hosts) to force the check to | |
13823 | occur. From release 4.53 onwards, this is no longer necessary. If the check has | |
13824 | not been done before "verify = helo" is encountered, it is done at that time. | |
13825 | Consequently, this option is obsolete. Its specification is retained here for | |
13826 | backwards compatibility. | |
13827 | ||
13828 | When an EHLO or HELO command is received, if the calling host matches | |
13829 | helo_try_verify_hosts, Exim checks that the host name given in the HELO or EHLO | |
13830 | command either: | |
13831 | ||
13832 | * is an IP literal matching the calling address of the host, or | |
13833 | ||
13834 | * matches the host name that Exim obtains by doing a reverse lookup of the | |
13835 | calling host address, or | |
13836 | ||
2813c06e | 13837 | * when looked up in DNS yields the calling host address. |
420a0d19 CE |
13838 | |
13839 | However, the EHLO or HELO command is not rejected if any of the checks fail. | |
13840 | Processing continues, but the result of the check is remembered, and can be | |
13841 | detected later in an ACL by the "verify = helo" condition. | |
13842 | ||
2813c06e CE |
13843 | If DNS was used for successful verification, the variable $helo_verify_dnssec |
13844 | records the DNSSEC status of the lookups. | |
13845 | ||
13846 | +-----------------------------------------------------------+ | |
420a0d19 | 13847 | |helo_verify_hosts|Use: main|Type: host list*|Default: unset| |
2813c06e | 13848 | +-----------------------------------------------------------+ |
420a0d19 CE |
13849 | |
13850 | Like helo_try_verify_hosts, this option is obsolete, and retained only for | |
13851 | backwards compatibility. For hosts that match this option, Exim checks the host | |
13852 | name given in the HELO or EHLO in the same way as for helo_try_verify_hosts. If | |
13853 | the check fails, the HELO or EHLO command is rejected with a 550 error, and | |
13854 | entries are written to the main and reject logs. If a MAIL command is received | |
13855 | before EHLO or HELO, it is rejected with a 503 error. | |
13856 | ||
2813c06e | 13857 | +--------------------------------------------------------+ |
420a0d19 | 13858 | |hold_domains|Use: main|Type: domain list*|Default: unset| |
2813c06e | 13859 | +--------------------------------------------------------+ |
420a0d19 CE |
13860 | |
13861 | This option allows mail for particular domains to be held on the queue | |
13862 | manually. The option is overridden if a message delivery is forced with the -M, | |
13863 | -qf, -Rf or -Sf options, and also while testing or verifying addresses using | |
13864 | -bt or -bv. Otherwise, if a domain matches an item in hold_domains, no routing | |
13865 | or delivery for that address is done, and it is deferred every time the message | |
13866 | is looked at. | |
13867 | ||
13868 | This option is intended as a temporary operational measure for delaying the | |
13869 | delivery of mail while some problem is being sorted out, or some new | |
13870 | configuration tested. If you just want to delay the processing of some domains | |
13871 | until a queue run occurs, you should use queue_domains or queue_smtp_domains, | |
13872 | not hold_domains. | |
13873 | ||
13874 | A setting of hold_domains does not override Exim's code for removing messages | |
13875 | from the queue if they have been there longer than the longest retry time in | |
13876 | any retry rule. If you want to hold messages for longer than the normal retry | |
13877 | times, insert a dummy retry rule with a long retry time. | |
13878 | ||
2813c06e | 13879 | +-----------------------------------------------------+ |
420a0d19 | 13880 | |host_lookup|Use: main|Type: host list*|Default: unset| |
2813c06e | 13881 | +-----------------------------------------------------+ |
420a0d19 CE |
13882 | |
13883 | Exim does not look up the name of a calling host from its IP address unless it | |
13884 | is required to compare against some host list, or the host matches | |
13885 | helo_try_verify_hosts or helo_verify_hosts, or the host matches this option | |
13886 | (which normally contains IP addresses rather than host names). The default | |
13887 | configuration file contains | |
13888 | ||
13889 | host_lookup = * | |
13890 | ||
13891 | which causes a lookup to happen for all hosts. If the expense of these lookups | |
13892 | is felt to be too great, the setting can be changed or removed. | |
13893 | ||
13894 | After a successful reverse lookup, Exim does a forward lookup on the name it | |
13895 | has obtained, to verify that it yields the IP address that it started with. If | |
13896 | this check fails, Exim behaves as if the name lookup failed. | |
13897 | ||
13898 | After any kind of failure, the host name (in $sender_host_name) remains unset, | |
13899 | and $host_lookup_failed is set to the string "1". See also | |
13900 | dns_again_means_nonexist, helo_lookup_domains, and "verify = | |
13901 | reverse_host_lookup" in ACLs. | |
13902 | ||
2813c06e | 13903 | +---------------------------------------------------------------------+ |
420a0d19 | 13904 | |host_lookup_order|Use: main|Type: string list|Default: "bydns:byaddr"| |
2813c06e | 13905 | +---------------------------------------------------------------------+ |
420a0d19 CE |
13906 | |
13907 | This option specifies the order of different lookup methods when Exim is trying | |
13908 | to find a host name from an IP address. The default is to do a DNS lookup | |
13909 | first, and then to try a local lookup (using gethostbyaddr() or equivalent) if | |
13910 | that fails. You can change the order of these lookups, or omit one entirely, if | |
13911 | you want. | |
13912 | ||
13913 | Warning: The "byaddr" method does not always yield aliases when there are | |
13914 | multiple PTR records in the DNS and the IP address is not listed in /etc/hosts. | |
13915 | Different operating systems give different results in this case. That is why | |
13916 | the default tries a DNS lookup first. | |
13917 | ||
2813c06e | 13918 | +----------------------------------------------------------------+ |
420a0d19 | 13919 | |host_reject_connection|Use: main|Type: host list*|Default: unset| |
2813c06e | 13920 | +----------------------------------------------------------------+ |
420a0d19 CE |
13921 | |
13922 | If this option is set, incoming SMTP calls from the hosts listed are rejected | |
13923 | as soon as the connection is made. This option is obsolete, and retained only | |
13924 | for backward compatibility, because nowadays the ACL specified by | |
13925 | acl_smtp_connect can also reject incoming connections immediately. | |
13926 | ||
13927 | The ability to give an immediate rejection (either by this option or using an | |
13928 | ACL) is provided for use in unusual cases. Many hosts will just try again, | |
13929 | sometimes without much delay. Normally, it is better to use an ACL to reject | |
2813c06e | 13930 | incoming messages at a later stage, such as after RCPT commands. See chapter 43 |
420a0d19 CE |
13931 | . |
13932 | ||
2813c06e | 13933 | +----------------------------------------------------------------+ |
420a0d19 | 13934 | |hosts_connection_nolog|Use: main|Type: host list*|Default: unset| |
2813c06e | 13935 | +----------------------------------------------------------------+ |
420a0d19 CE |
13936 | |
13937 | This option defines a list of hosts for which connection logging does not | |
13938 | happen, even though the smtp_connection log selector is set. For example, you | |
13939 | might want not to log SMTP connections from local processes, or from 127.0.0.1, | |
13940 | or from your local LAN. This option is consulted in the main loop of the | |
13941 | daemon; you should therefore strive to restrict its value to a short inline | |
13942 | list of IP addresses and networks. To disable logging SMTP connections from | |
13943 | local processes, you must create a host list with an empty item. For example: | |
13944 | ||
13945 | hosts_connection_nolog = : | |
13946 | ||
13947 | If the smtp_connection log selector is not set, this option has no effect. | |
13948 | ||
2813c06e CE |
13949 | +-----------------------------------------------------+ |
13950 | |hosts_proxy|Use: main|Type: host list*|Default: unset| | |
13951 | +-----------------------------------------------------+ | |
13952 | ||
13953 | This option enables use of Proxy Protocol proxies for incoming connections. For | |
13954 | details see section 58.1. | |
13955 | ||
13956 | +----------------------------------------------------------------+ | |
420a0d19 | 13957 | |hosts_treat_as_local|Use: main|Type: domain list*|Default: unset| |
2813c06e | 13958 | +----------------------------------------------------------------+ |
420a0d19 CE |
13959 | |
13960 | If this option is set, any host names that match the domain list are treated as | |
13961 | if they were the local host when Exim is scanning host lists obtained from MX | |
13962 | records or other sources. Note that the value of this option is a domain list, | |
13963 | not a host list, because it is always used to check host names, not IP | |
13964 | addresses. | |
13965 | ||
13966 | This option also applies when Exim is matching the special items "@mx_any", | |
13967 | "@mx_primary", and "@mx_secondary" in a domain list (see section 10.8), and | |
13968 | when checking the hosts option in the smtp transport for the local host (see | |
13969 | the allow_localhost option in that transport). See also local_interfaces, | |
13970 | extra_local_interfaces, and chapter 13, which contains a discussion about local | |
13971 | network interfaces and recognizing the local host. | |
13972 | ||
2813c06e | 13973 | +--------------------------------------------------------+ |
420a0d19 | 13974 | |ibase_servers|Use: main|Type: string list|Default: unset| |
2813c06e | 13975 | +--------------------------------------------------------+ |
420a0d19 CE |
13976 | |
13977 | This option provides a list of InterBase servers and associated connection | |
2813c06e | 13978 | data, to be used in conjunction with ibase lookups (see section 9.22). The |
420a0d19 CE |
13979 | option is available only if Exim has been built with InterBase support. |
13980 | ||
2813c06e | 13981 | +------------------------------------------------------------+ |
420a0d19 | 13982 | |ignore_bounce_errors_after|Use: main|Type: time|Default: 10w| |
2813c06e | 13983 | +------------------------------------------------------------+ |
420a0d19 CE |
13984 | |
13985 | This option affects the processing of bounce messages that cannot be delivered, | |
13986 | that is, those that suffer a permanent delivery failure. (Bounce messages that | |
13987 | suffer temporary delivery failures are of course retried in the usual way.) | |
13988 | ||
13989 | After a permanent delivery failure, bounce messages are frozen, because there | |
13990 | is no sender to whom they can be returned. When a frozen bounce message has | |
13991 | been on the queue for more than the given time, it is unfrozen at the next | |
13992 | queue run, and a further delivery is attempted. If delivery fails again, the | |
13993 | bounce message is discarded. This makes it possible to keep failed bounce | |
13994 | messages around for a shorter time than the normal maximum retry time for | |
13995 | frozen messages. For example, | |
13996 | ||
13997 | ignore_bounce_errors_after = 12h | |
13998 | ||
13999 | retries failed bounce message deliveries after 12 hours, discarding any further | |
14000 | failures. If the value of this option is set to a zero time period, bounce | |
14001 | failures are discarded immediately. Setting a very long time (as in the default | |
14002 | value) has the effect of disabling this option. For ways of automatically | |
14003 | dealing with other kinds of frozen message, see auto_thaw and | |
14004 | timeout_frozen_after. | |
14005 | ||
2813c06e | 14006 | +---------------------------------------------------------------+ |
420a0d19 | 14007 | |ignore_fromline_hosts|Use: main|Type: host list*|Default: unset| |
2813c06e | 14008 | +---------------------------------------------------------------+ |
420a0d19 CE |
14009 | |
14010 | Some broken SMTP clients insist on sending a UUCP-like "From " line before the | |
14011 | headers of a message. By default this is treated as the start of the message's | |
14012 | body, which means that any following headers are not recognized as such. Exim | |
14013 | can be made to ignore it by setting ignore_fromline_hosts to match those hosts | |
14014 | that insist on sending it. If the sender is actually a local process rather | |
14015 | than a remote host, and is using -bs to inject the messages, | |
14016 | ignore_fromline_local must be set to achieve this effect. | |
14017 | ||
2813c06e | 14018 | +------------------------------------------------------------+ |
420a0d19 | 14019 | |ignore_fromline_local|Use: main|Type: boolean|Default: false| |
2813c06e | 14020 | +------------------------------------------------------------+ |
420a0d19 CE |
14021 | |
14022 | See ignore_fromline_hosts above. | |
14023 | ||
2813c06e CE |
14024 | +-----------------------------------------------------------+ |
14025 | |keep_environment|Use: main|Type: string list|Default: unset| | |
14026 | +-----------------------------------------------------------+ | |
14027 | ||
14028 | This option contains a string list of environment variables to keep. You have | |
14029 | to trust these variables or you have to be sure that these variables do not | |
14030 | impose any security risk. Keep in mind that during the startup phase Exim is | |
14031 | running with an effective UID 0 in most installations. As the default value is | |
14032 | an empty list, the default environment for using libraries, running embedded | |
14033 | Perl code, or running external binaries is empty, and does not not even contain | |
14034 | PATH or HOME. | |
14035 | ||
14036 | Actually the list is interpreted as a list of patterns (10.1), except that it | |
14037 | is not expanded first. | |
14038 | ||
14039 | WARNING: Macro substitution is still done first, so having a macro FOO and | |
14040 | having FOO_HOME in your keep_environment option may have unexpected results. | |
14041 | You may work around this using a regular expression that does not match the | |
14042 | macro name: ^[F]OO_HOME$. | |
14043 | ||
14044 | Current versions of Exim issue a warning during startup if you do not mention | |
14045 | keep_environment in your runtime configuration file and if your current | |
14046 | environment is not empty. Future versions may not issue that warning anymore. | |
14047 | ||
14048 | See the add_environment main config option for a way to set environment | |
14049 | variables to a fixed value. The environment for pipe transports is handled | |
14050 | separately, see section 29.4 for details. | |
14051 | ||
14052 | +-----------------------------------------------+ | |
420a0d19 | 14053 | |keep_malformed|Use: main|Type: time|Default: 4d| |
2813c06e | 14054 | +-----------------------------------------------+ |
420a0d19 CE |
14055 | |
14056 | This option specifies the length of time to keep messages whose spool files | |
14057 | have been corrupted in some way. This should, of course, never happen. At the | |
14058 | next attempt to deliver such a message, it gets removed. The incident is | |
14059 | logged. | |
14060 | ||
2813c06e | 14061 | +------------------------------------------------------+ |
420a0d19 | 14062 | |ldap_ca_cert_dir|Use: main|Type: string|Default: unset| |
2813c06e | 14063 | +------------------------------------------------------+ |
420a0d19 CE |
14064 | |
14065 | This option indicates which directory contains CA certificates for verifying a | |
14066 | TLS certificate presented by an LDAP server. While Exim does not provide a | |
14067 | default value, your SSL library may. Analogous to tls_verify_certificates but | |
14068 | as a client-side option for LDAP and constrained to be a directory. | |
14069 | ||
2813c06e | 14070 | +-------------------------------------------------------+ |
420a0d19 | 14071 | |ldap_ca_cert_file|Use: main|Type: string|Default: unset| |
2813c06e | 14072 | +-------------------------------------------------------+ |
420a0d19 CE |
14073 | |
14074 | This option indicates which file contains CA certificates for verifying a TLS | |
14075 | certificate presented by an LDAP server. While Exim does not provide a default | |
14076 | value, your SSL library may. Analogous to tls_verify_certificates but as a | |
14077 | client-side option for LDAP and constrained to be a file. | |
14078 | ||
2813c06e | 14079 | +----------------------------------------------------+ |
420a0d19 | 14080 | |ldap_cert_file|Use: main|Type: string|Default: unset| |
2813c06e | 14081 | +----------------------------------------------------+ |
420a0d19 CE |
14082 | |
14083 | This option indicates which file contains an TLS client certificate which Exim | |
14084 | should present to the LDAP server during TLS negotiation. Should be used | |
14085 | together with ldap_cert_key. | |
14086 | ||
2813c06e | 14087 | +---------------------------------------------------+ |
420a0d19 | 14088 | |ldap_cert_key|Use: main|Type: string|Default: unset| |
2813c06e | 14089 | +---------------------------------------------------+ |
420a0d19 CE |
14090 | |
14091 | This option indicates which file contains the secret/private key to use to | |
14092 | prove identity to the LDAP server during TLS negotiation. Should be used | |
14093 | together with ldap_cert_file, which contains the identity to be proven. | |
14094 | ||
2813c06e | 14095 | +-------------------------------------------------------+ |
420a0d19 | 14096 | |ldap_cipher_suite|Use: main|Type: string|Default: unset| |
2813c06e | 14097 | +-------------------------------------------------------+ |
420a0d19 CE |
14098 | |
14099 | This controls the TLS cipher-suite negotiation during TLS negotiation with the | |
2813c06e | 14100 | LDAP server. See 42.4 for more details of the format of cipher-suite options |
420a0d19 CE |
14101 | with OpenSSL (as used by LDAP client libraries). |
14102 | ||
2813c06e | 14103 | +---------------------------------------------------------------+ |
420a0d19 | 14104 | |ldap_default_servers|Use: main|Type: string list|Default: unset| |
2813c06e | 14105 | +---------------------------------------------------------------+ |
420a0d19 CE |
14106 | |
14107 | This option provides a list of LDAP servers which are tried in turn when an | |
2813c06e | 14108 | LDAP query does not contain a server. See section 9.15 for details of LDAP |
420a0d19 CE |
14109 | queries. This option is available only when Exim has been built with LDAP |
14110 | support. | |
14111 | ||
2813c06e | 14112 | +--------------------------------------------------------+ |
420a0d19 | 14113 | |ldap_require_cert|Use: main|Type: string|Default: unset.| |
2813c06e | 14114 | +--------------------------------------------------------+ |
420a0d19 CE |
14115 | |
14116 | This should be one of the values "hard", "demand", "allow", "try" or "never". A | |
14117 | value other than one of these is interpreted as "never". See the entry | |
14118 | "TLS_REQCERT" in your system man page for ldap.conf(5). Although Exim does not | |
14119 | set a default, the LDAP library probably defaults to hard/demand. | |
14120 | ||
2813c06e | 14121 | +-----------------------------------------------------+ |
420a0d19 | 14122 | |ldap_start_tls|Use: main|Type: boolean|Default: false| |
2813c06e | 14123 | +-----------------------------------------------------+ |
420a0d19 CE |
14124 | |
14125 | If set, Exim will attempt to negotiate TLS with the LDAP server when connecting | |
14126 | on a regular LDAP port. This is the LDAP equivalent of SMTP's "STARTTLS". This | |
14127 | is distinct from using "ldaps", which is the LDAP form of SSL-on-connect. In | |
14128 | the event of failure to negotiate TLS, the action taken is controlled by | |
14129 | ldap_require_cert. | |
14130 | ||
2813c06e CE |
14131 | This option is ignored for "ldapi" connections. |
14132 | ||
14133 | +---------------------------------------------------+ | |
420a0d19 | 14134 | |ldap_version|Use: main|Type: integer|Default: unset| |
2813c06e | 14135 | +---------------------------------------------------+ |
420a0d19 CE |
14136 | |
14137 | This option can be used to force Exim to set a specific protocol version for | |
14138 | LDAP. If it option is unset, it is shown by the -bP command line option as -1. | |
14139 | When this is the case, the default is 3 if LDAP_VERSION3 is defined in the LDAP | |
14140 | headers; otherwise it is 2. This option is available only when Exim has been | |
14141 | built with LDAP support. | |
14142 | ||
2813c06e | 14143 | +------------------------------------------------------+ |
420a0d19 | 14144 | |local_from_check|Use: main|Type: boolean|Default: true| |
2813c06e | 14145 | +------------------------------------------------------+ |
420a0d19 CE |
14146 | |
14147 | When a message is submitted locally (that is, not over a TCP/IP connection) by | |
14148 | an untrusted user, Exim removes any existing Sender: header line, and checks | |
14149 | that the From: header line matches the login of the calling user and the domain | |
14150 | specified by qualify_domain. | |
14151 | ||
14152 | Note: An unqualified address (no domain) in the From: header in a locally | |
14153 | submitted message is automatically qualified by Exim, unless the -bnq command | |
14154 | line option is used. | |
14155 | ||
14156 | You can use local_from_prefix and local_from_suffix to permit affixes on the | |
14157 | local part. If the From: header line does not match, Exim adds a Sender: header | |
14158 | with an address constructed from the calling user's login and the default | |
14159 | qualify domain. | |
14160 | ||
14161 | If local_from_check is set false, the From: header check is disabled, and no | |
14162 | Sender: header is ever added. If, in addition, you want to retain Sender: | |
14163 | header lines supplied by untrusted users, you must also set local_sender_retain | |
14164 | to be true. | |
14165 | ||
14166 | These options affect only the header lines in the message. The envelope sender | |
14167 | is still forced to be the login id at the qualify domain unless | |
14168 | untrusted_set_sender permits the user to supply an envelope sender. | |
14169 | ||
14170 | For messages received over TCP/IP, an ACL can specify "submission mode" to | |
2813c06e | 14171 | request similar header line checking. See section 47.16, which has more details |
420a0d19 CE |
14172 | about Sender: processing. |
14173 | ||
2813c06e | 14174 | +-------------------------------------------------------+ |
420a0d19 | 14175 | |local_from_prefix|Use: main|Type: string|Default: unset| |
2813c06e | 14176 | +-------------------------------------------------------+ |
420a0d19 CE |
14177 | |
14178 | When Exim checks the From: header line of locally submitted messages for | |
14179 | matching the login id (see local_from_check above), it can be configured to | |
14180 | ignore certain prefixes and suffixes in the local part of the address. This is | |
14181 | done by setting local_from_prefix and/or local_from_suffix to appropriate | |
14182 | lists, in the same form as the local_part_prefix and local_part_suffix router | |
14183 | options (see chapter 15). For example, if | |
14184 | ||
14185 | local_from_prefix = *- | |
14186 | ||
14187 | is set, a From: line containing | |
14188 | ||
14189 | From: anything-user@your.domain.example | |
14190 | ||
14191 | will not cause a Sender: header to be added if user@your.domain.example matches | |
14192 | the actual sender address that is constructed from the login name and qualify | |
14193 | domain. | |
14194 | ||
2813c06e | 14195 | +-------------------------------------------------------+ |
420a0d19 | 14196 | |local_from_suffix|Use: main|Type: string|Default: unset| |
2813c06e | 14197 | +-------------------------------------------------------+ |
420a0d19 CE |
14198 | |
14199 | See local_from_prefix above. | |
14200 | ||
2813c06e | 14201 | +---------------------------------------------------------------+ |
420a0d19 | 14202 | |local_interfaces|Use: main|Type: string list|Default: see below| |
2813c06e | 14203 | +---------------------------------------------------------------+ |
420a0d19 CE |
14204 | |
14205 | This option controls which network interfaces are used by the daemon for | |
14206 | listening; they are also used to identify the local host when routing. Chapter | |
14207 | 13 contains a full description of this option and the related options | |
14208 | daemon_smtp_ports, extra_local_interfaces, hosts_treat_as_local, and | |
14209 | tls_on_connect_ports. The default value for local_interfaces is | |
14210 | ||
14211 | local_interfaces = 0.0.0.0 | |
14212 | ||
14213 | when Exim is built without IPv6 support; otherwise it is | |
14214 | ||
14215 | local_interfaces = <; ::0 ; 0.0.0.0 | |
14216 | ||
2813c06e | 14217 | +---------------------------------------------------+ |
420a0d19 | 14218 | |local_scan_timeout|Use: main|Type: time|Default: 5m| |
2813c06e | 14219 | +---------------------------------------------------+ |
420a0d19 | 14220 | |
2813c06e | 14221 | This timeout applies to the local_scan() function (see chapter 45). Zero means |
420a0d19 CE |
14222 | "no timeout". If the timeout is exceeded, the incoming message is rejected with |
14223 | a temporary error if it is an SMTP message. For a non-SMTP message, the message | |
14224 | is dropped and Exim ends with a non-zero code. The incident is logged on the | |
14225 | main and reject logs. | |
14226 | ||
2813c06e | 14227 | +----------------------------------------------------------+ |
420a0d19 | 14228 | |local_sender_retain|Use: main|Type: boolean|Default: false| |
2813c06e | 14229 | +----------------------------------------------------------+ |
420a0d19 CE |
14230 | |
14231 | When a message is submitted locally (that is, not over a TCP/IP connection) by | |
14232 | an untrusted user, Exim removes any existing Sender: header line. If you do not | |
14233 | want this to happen, you must set local_sender_retain, and you must also set | |
14234 | local_from_check to be false (Exim will complain if you do not). See also the | |
2813c06e | 14235 | ACL modifier "control = suppress_local_fixups". Section 47.16 has more details |
420a0d19 CE |
14236 | about Sender: processing. |
14237 | ||
2813c06e | 14238 | +-------------------------------------------------------+ |
420a0d19 | 14239 | |localhost_number|Use: main|Type: string*|Default: unset| |
2813c06e | 14240 | +-------------------------------------------------------+ |
420a0d19 CE |
14241 | |
14242 | Exim's message ids are normally unique only within the local host. If | |
14243 | uniqueness among a set of hosts is required, each host must set a different | |
14244 | value for the localhost_number option. The string is expanded immediately after | |
14245 | reading the configuration file (so that a number can be computed from the host | |
14246 | name, for example) and the result of the expansion must be a number in the | |
14247 | range 0-16 (or 0-10 on operating systems with case-insensitive file systems). | |
14248 | This is available in subsequent string expansions via the variable | |
14249 | $localhost_number. When localhost_number is set, the final two characters of | |
14250 | the message id, instead of just being a fractional part of the time, are | |
14251 | computed from the time and the local host number as described in section 3.4. | |
14252 | ||
2813c06e | 14253 | +-----------------------------------------------------------------------+ |
420a0d19 | 14254 | |log_file_path|Use: main|Type: string list*|Default: set at compile time| |
2813c06e | 14255 | +-----------------------------------------------------------------------+ |
420a0d19 CE |
14256 | |
14257 | This option sets the path which is used to determine the names of Exim's log | |
14258 | files, or indicates that logging is to be to syslog, or both. It is expanded | |
14259 | when Exim is entered, so it can, for example, contain a reference to the host | |
2813c06e CE |
14260 | name. If no specific path is set for the log files at compile or run time, or |
14261 | if the option is unset at run time (i.e. "log_file_path = ") they are written | |
14262 | in a sub-directory called log in Exim's spool directory. Chapter 52 contains | |
14263 | further details about Exim's logging, and section 52.1 describes how the | |
14264 | contents of log_file_path are used. If this string is fixed at your | |
420a0d19 CE |
14265 | installation (contains no expansion variables) it is recommended that you do |
14266 | not set this option in the configuration file, but instead supply the path | |
14267 | using LOG_FILE_PATH in Local/Makefile so that it is available to Exim for | |
14268 | logging errors detected early on - in particular, failure to read the | |
14269 | configuration file. | |
14270 | ||
2813c06e | 14271 | +--------------------------------------------------+ |
420a0d19 | 14272 | |log_selector|Use: main|Type: string|Default: unset| |
2813c06e | 14273 | +--------------------------------------------------+ |
420a0d19 CE |
14274 | |
14275 | This option can be used to reduce or increase the number of things that Exim | |
14276 | writes to its log files. Its argument is made up of names preceded by plus or | |
14277 | minus characters. For example: | |
14278 | ||
14279 | log_selector = +arguments -retry_defer | |
14280 | ||
14281 | A list of possible names and what they control is given in the chapter on | |
2813c06e | 14282 | logging, in section 52.15. |
420a0d19 | 14283 | |
2813c06e | 14284 | +---------------------------------------------------+ |
420a0d19 | 14285 | |log_timezone|Use: main|Type: boolean|Default: false| |
2813c06e | 14286 | +---------------------------------------------------+ |
420a0d19 CE |
14287 | |
14288 | By default, the timestamps on log lines are in local time without the timezone. | |
14289 | This means that if your timezone changes twice a year, the timestamps in log | |
14290 | lines are ambiguous for an hour when the clocks go back. One way of avoiding | |
14291 | this problem is to set the timezone to UTC. An alternative is to set | |
14292 | log_timezone true. This turns on the addition of the timezone offset to | |
14293 | timestamps in log lines. Turning on this option can add quite a lot to the size | |
14294 | of log files because each line is extended by 6 characters. Note that the | |
14295 | $tod_log variable contains the log timestamp without the zone, but there is | |
14296 | another variable called $tod_zone that contains just the timezone offset. | |
14297 | ||
2813c06e | 14298 | +---------------------------------------------------+ |
420a0d19 | 14299 | |lookup_open_max|Use: main|Type: integer|Default: 25| |
2813c06e | 14300 | +---------------------------------------------------+ |
420a0d19 CE |
14301 | |
14302 | This option limits the number of simultaneously open files for single-key | |
14303 | lookups that use regular files (that is, lsearch, dbm, and cdb). Exim normally | |
14304 | keeps these files open during routing, because often the same file is required | |
14305 | several times. If the limit is reached, Exim closes the least recently used | |
14306 | file. Note that if you are using the ndbm library, it actually opens two files | |
14307 | for each logical DBM database, though it still counts as one for the purposes | |
14308 | of lookup_open_max. If you are getting "too many open files" errors with NDBM, | |
14309 | you need to reduce the value of lookup_open_max. | |
14310 | ||
2813c06e | 14311 | +------------------------------------------------------+ |
420a0d19 | 14312 | |max_username_length|Use: main|Type: integer|Default: 0| |
2813c06e | 14313 | +------------------------------------------------------+ |
420a0d19 CE |
14314 | |
14315 | Some operating systems are broken in that they truncate long arguments to | |
14316 | getpwnam() to eight characters, instead of returning "no such user". If this | |
14317 | option is set greater than zero, any attempt to call getpwnam() with an | |
14318 | argument that is longer behaves as if getpwnam() failed. | |
14319 | ||
2813c06e | 14320 | +---------------------------------------------------------+ |
420a0d19 | 14321 | |message_body_newlines|Use: main|Type: bool|Default: false| |
2813c06e | 14322 | +---------------------------------------------------------+ |
420a0d19 CE |
14323 | |
14324 | By default, newlines in the message body are replaced by spaces when setting | |
14325 | the $message_body and $message_body_end expansion variables. If this option is | |
14326 | set true, this no longer happens. | |
14327 | ||
2813c06e | 14328 | +---------------------------------------------------------+ |
420a0d19 | 14329 | |message_body_visible|Use: main|Type: integer|Default: 500| |
2813c06e | 14330 | +---------------------------------------------------------+ |
420a0d19 CE |
14331 | |
14332 | This option specifies how much of a message's body is to be included in the | |
14333 | $message_body and $message_body_end expansion variables. | |
14334 | ||
2813c06e | 14335 | +---------------------------------------------------------------+ |
420a0d19 | 14336 | |message_id_header_domain|Use: main|Type: string*|Default: unset| |
2813c06e | 14337 | +---------------------------------------------------------------+ |
420a0d19 CE |
14338 | |
14339 | If this option is set, the string is expanded and used as the right hand side | |
14340 | (domain) of the Message-ID: header that Exim creates if a locally-originated | |
14341 | incoming message does not have one. "Locally-originated" means "not received | |
14342 | over TCP/IP." Otherwise, the primary host name is used. Only letters, digits, | |
14343 | dot and hyphen are accepted; any other characters are replaced by hyphens. If | |
14344 | the expansion is forced to fail, or if the result is an empty string, the | |
14345 | option is ignored. | |
14346 | ||
2813c06e | 14347 | +-------------------------------------------------------------+ |
420a0d19 | 14348 | |message_id_header_text|Use: main|Type: string*|Default: unset| |
2813c06e | 14349 | +-------------------------------------------------------------+ |
420a0d19 CE |
14350 | |
14351 | If this variable is set, the string is expanded and used to augment the text of | |
14352 | the Message-id: header that Exim creates if a locally-originated incoming | |
14353 | message does not have one. The text of this header is required by RFC 2822 to | |
14354 | take the form of an address. By default, Exim uses its internal message id as | |
14355 | the local part, and the primary host name as the domain. If this option is set, | |
14356 | it is expanded, and provided the expansion is not forced to fail, and does not | |
14357 | yield an empty string, the result is inserted into the header immediately | |
14358 | before the @, separated from the internal message id by a dot. Any characters | |
14359 | that are illegal in an address are automatically converted into hyphens. This | |
14360 | means that variables such as $tod_log can be used, because the spaces and | |
14361 | colons will become hyphens. | |
14362 | ||
2813c06e | 14363 | +--------------------------------------------------+ |
420a0d19 | 14364 | |message_logs|Use: main|Type: boolean|Default: true| |
2813c06e | 14365 | +--------------------------------------------------+ |
420a0d19 CE |
14366 | |
14367 | If this option is turned off, per-message log files are not created in the | |
14368 | msglog spool sub-directory. This reduces the amount of disk I/O required by | |
14369 | Exim, by reducing the number of files involved in handling a message from a | |
14370 | minimum of four (header spool file, body spool file, delivery journal, and | |
14371 | per-message log) to three. The other major I/O activity is Exim's main log, | |
14372 | which is not affected by this option. | |
14373 | ||
2813c06e | 14374 | +-------------------------------------------------------+ |
420a0d19 | 14375 | |message_size_limit|Use: main|Type: string*|Default: 50M| |
2813c06e | 14376 | +-------------------------------------------------------+ |
420a0d19 CE |
14377 | |
14378 | This option limits the maximum size of message that Exim will process. The | |
14379 | value is expanded for each incoming connection so, for example, it can be made | |
14380 | to depend on the IP address of the remote host for messages arriving via TCP/ | |
14381 | IP. After expansion, the value must be a sequence of decimal digits, optionally | |
14382 | followed by K or M. | |
14383 | ||
14384 | Note: This limit cannot be made to depend on a message's sender or any other | |
14385 | properties of an individual message, because it has to be advertised in the | |
14386 | server's response to EHLO. String expansion failure causes a temporary error. A | |
14387 | value of zero means no limit, but its use is not recommended. See also | |
14388 | bounce_return_size_limit. | |
14389 | ||
14390 | Incoming SMTP messages are failed with a 552 error if the limit is exceeded; | |
14391 | locally-generated messages either get a stderr message or a delivery failure | |
14392 | message to the sender, depending on the -oe setting. Rejection of an oversized | |
14393 | message is logged in both the main and the reject logs. See also the generic | |
14394 | transport option message_size_limit, which limits the size of message that an | |
14395 | individual transport can process. | |
14396 | ||
14397 | If you use a virus-scanner and set this option to to a value larger than the | |
14398 | maximum size that your virus-scanner is configured to support, you may get | |
14399 | failures triggered by large mails. The right size to configure for the | |
14400 | virus-scanner depends upon what data is passed and the options in use but it's | |
2813c06e | 14401 | probably safest to just set it to a little larger than this value. E.g., with a |
420a0d19 CE |
14402 | default Exim message size of 50M and a default ClamAV StreamMaxLength of 10M, |
14403 | some problems may result. | |
14404 | ||
14405 | A value of 0 will disable size limit checking; Exim will still advertise the | |
14406 | SIZE extension in an EHLO response, but without a limit, so as to permit SMTP | |
14407 | clients to still indicate the message size along with the MAIL verb. | |
14408 | ||
2813c06e | 14409 | +-----------------------------------------------------------+ |
420a0d19 | 14410 | |move_frozen_messages|Use: main|Type: boolean|Default: false| |
2813c06e | 14411 | +-----------------------------------------------------------+ |
420a0d19 CE |
14412 | |
14413 | This option, which is available only if Exim has been built with the setting | |
14414 | ||
14415 | SUPPORT_MOVE_FROZEN_MESSAGES=yes | |
14416 | ||
14417 | in Local/Makefile, causes frozen messages and their message logs to be moved | |
14418 | from the input and msglog directories on the spool to Finput and Fmsglog, | |
14419 | respectively. There is currently no support in Exim or the standard utilities | |
14420 | for handling such moved messages, and they do not show up in lists generated by | |
14421 | -bp or by the Exim monitor. | |
14422 | ||
2813c06e | 14423 | +--------------------------------------------------+ |
420a0d19 | 14424 | |mua_wrapper|Use: main|Type: boolean|Default: false| |
2813c06e | 14425 | +--------------------------------------------------+ |
420a0d19 CE |
14426 | |
14427 | Setting this option true causes Exim to run in a very restrictive mode in which | |
2813c06e | 14428 | it passes messages synchronously to a smart host. Chapter 51 contains a full |
420a0d19 CE |
14429 | description of this facility. |
14430 | ||
2813c06e | 14431 | +--------------------------------------------------------+ |
420a0d19 | 14432 | |mysql_servers|Use: main|Type: string list|Default: unset| |
2813c06e | 14433 | +--------------------------------------------------------+ |
420a0d19 CE |
14434 | |
14435 | This option provides a list of MySQL servers and associated connection data, to | |
2813c06e | 14436 | be used in conjunction with mysql lookups (see section 9.22). The option is |
420a0d19 CE |
14437 | available only if Exim has been built with MySQL support. |
14438 | ||
2813c06e | 14439 | +-------------------------------------------------------+ |
420a0d19 | 14440 | |never_users|Use: main|Type: string list*|Default: unset| |
2813c06e | 14441 | +-------------------------------------------------------+ |
420a0d19 CE |
14442 | |
14443 | This option is expanded just once, at the start of Exim's processing. Local | |
14444 | message deliveries are normally run in processes that are setuid to the | |
14445 | recipient, and remote deliveries are normally run under Exim's own uid and gid. | |
14446 | It is usually desirable to prevent any deliveries from running as root, as a | |
14447 | safety precaution. | |
14448 | ||
14449 | When Exim is built, an option called FIXED_NEVER_USERS can be set to a list of | |
14450 | users that must not be used for local deliveries. This list is fixed in the | |
14451 | binary and cannot be overridden by the configuration file. By default, it | |
14452 | contains just the single user name "root". The never_users runtime option can | |
14453 | be used to add more users to the fixed list. | |
14454 | ||
14455 | If a message is to be delivered as one of the users on the fixed list or the | |
14456 | never_users list, an error occurs, and delivery is deferred. A common example | |
14457 | is | |
14458 | ||
14459 | never_users = root:daemon:bin | |
14460 | ||
14461 | Including root is redundant if it is also on the fixed list, but it does no | |
14462 | harm. This option overrides the pipe_as_creator option of the pipe transport | |
14463 | driver. | |
14464 | ||
2813c06e CE |
14465 | +-----------------------------------------------------------------------------+ |
14466 | |openssl_options|Use: main|Type: string list|Default: +no_sslv2 +single_dh_use| | |
14467 | +-----------------------------------------------------------------------------+ | |
420a0d19 CE |
14468 | |
14469 | This option allows an administrator to adjust the SSL options applied by | |
14470 | OpenSSL to connections. It is given as a space-separated list of items, each | |
14471 | one to be +added or -subtracted from the current value. | |
14472 | ||
14473 | This option is only available if Exim is built against OpenSSL. The values | |
14474 | available for this option vary according to the age of your OpenSSL install. | |
14475 | The "all" value controls a subset of flags which are available, typically the | |
14476 | bug workaround options. The SSL_CTX_set_options man page will list the values | |
14477 | known on your system and Exim should support all the "bug workaround" options | |
14478 | and many of the "modifying" options. The Exim names lose the leading "SSL_OP_" | |
14479 | and are lower-cased. | |
14480 | ||
14481 | Note that adjusting the options can have severe impact upon the security of SSL | |
14482 | as used by Exim. It is possible to disable safety checks and shoot yourself in | |
14483 | the foot in various unpleasant ways. This option should not be adjusted | |
14484 | lightly. An unrecognised item will be detected at startup, by invoking Exim | |
14485 | with the -bV flag. | |
14486 | ||
2813c06e CE |
14487 | The option affects Exim operating both as a server and as a client. |
14488 | ||
420a0d19 CE |
14489 | Historical note: prior to release 4.80, Exim defaulted this value to |
14490 | "+dont_insert_empty_fragments", which may still be needed for compatibility | |
14491 | with some clients, but which lowers security by increasing exposure to some now | |
14492 | infamous attacks. | |
14493 | ||
2813c06e | 14494 | Examples: |
420a0d19 CE |
14495 | |
14496 | # Make both old MS and old Eudora happy: | |
14497 | openssl_options = -all +microsoft_big_sslv3_buffer \ | |
14498 | +dont_insert_empty_fragments | |
14499 | ||
2813c06e CE |
14500 | # Disable older protocol versions: |
14501 | openssl_options = +no_sslv2 +no_sslv3 | |
14502 | ||
420a0d19 CE |
14503 | Possible options may include: |
14504 | ||
14505 | * "all" | |
14506 | ||
14507 | * "allow_unsafe_legacy_renegotiation" | |
14508 | ||
14509 | * "cipher_server_preference" | |
14510 | ||
14511 | * "dont_insert_empty_fragments" | |
14512 | ||
14513 | * "ephemeral_rsa" | |
14514 | ||
14515 | * "legacy_server_connect" | |
14516 | ||
14517 | * "microsoft_big_sslv3_buffer" | |
14518 | ||
14519 | * "microsoft_sess_id_bug" | |
14520 | ||
14521 | * "msie_sslv2_rsa_padding" | |
14522 | ||
14523 | * "netscape_challenge_bug" | |
14524 | ||
14525 | * "netscape_reuse_cipher_change_bug" | |
14526 | ||
14527 | * "no_compression" | |
14528 | ||
14529 | * "no_session_resumption_on_renegotiation" | |
14530 | ||
14531 | * "no_sslv2" | |
14532 | ||
14533 | * "no_sslv3" | |
14534 | ||
14535 | * "no_ticket" | |
14536 | ||
14537 | * "no_tlsv1" | |
14538 | ||
14539 | * "no_tlsv1_1" | |
14540 | ||
14541 | * "no_tlsv1_2" | |
14542 | ||
14543 | * "safari_ecdhe_ecdsa_bug" | |
14544 | ||
14545 | * "single_dh_use" | |
14546 | ||
14547 | * "single_ecdh_use" | |
14548 | ||
14549 | * "ssleay_080_client_dh_bug" | |
14550 | ||
14551 | * "sslref2_reuse_cert_type_bug" | |
14552 | ||
14553 | * "tls_block_padding_bug" | |
14554 | ||
14555 | * "tls_d5_bug" | |
14556 | ||
14557 | * "tls_rollback_bug" | |
14558 | ||
14559 | As an aside, the "safari_ecdhe_ecdsa_bug" item is a misnomer and affects all | |
14560 | clients connecting using the MacOS SecureTransport TLS facility prior to MacOS | |
14561 | 10.8.4, including email clients. If you see old MacOS clients failing to | |
14562 | negotiate TLS then this option value might help, provided that your OpenSSL | |
14563 | release is new enough to contain this work-around. This may be a situation | |
14564 | where you have to upgrade OpenSSL to get buggy clients working. | |
14565 | ||
2813c06e | 14566 | +---------------------------------------------------------+ |
420a0d19 | 14567 | |oracle_servers|Use: main|Type: string list|Default: unset| |
2813c06e | 14568 | +---------------------------------------------------------+ |
420a0d19 CE |
14569 | |
14570 | This option provides a list of Oracle servers and associated connection data, | |
2813c06e | 14571 | to be used in conjunction with oracle lookups (see section 9.22). The option is |
420a0d19 CE |
14572 | available only if Exim has been built with Oracle support. |
14573 | ||
2813c06e | 14574 | +----------------------------------------------------------------+ |
420a0d19 | 14575 | |percent_hack_domains|Use: main|Type: domain list*|Default: unset| |
2813c06e | 14576 | +----------------------------------------------------------------+ |
420a0d19 CE |
14577 | |
14578 | The "percent hack" is the convention whereby a local part containing a percent | |
14579 | sign is re-interpreted as a new email address, with the percent replaced by @. | |
14580 | This is sometimes called "source routing", though that term is also applied to | |
14581 | RFC 2822 addresses that begin with an @ character. If this option is set, Exim | |
14582 | implements the percent facility for those domains listed, but no others. This | |
14583 | happens before an incoming SMTP address is tested against an ACL. | |
14584 | ||
14585 | Warning: The "percent hack" has often been abused by people who are trying to | |
14586 | get round relaying restrictions. For this reason, it is best avoided if at all | |
14587 | possible. Unfortunately, a number of less security-conscious MTAs implement it | |
14588 | unconditionally. If you are running Exim on a gateway host, and routing mail | |
14589 | through to internal MTAs without processing the local parts, it is a good idea | |
14590 | to reject recipient addresses with percent characters in their local parts. | |
14591 | Exim's default configuration does this. | |
14592 | ||
2813c06e | 14593 | +----------------------------------------------------+ |
420a0d19 | 14594 | |perl_at_start|Use: main|Type: boolean|Default: false| |
2813c06e | 14595 | +----------------------------------------------------+ |
420a0d19 CE |
14596 | |
14597 | This option is available only when Exim is built with an embedded Perl | |
14598 | interpreter. See chapter 12 for details of its use. | |
14599 | ||
2813c06e | 14600 | +--------------------------------------------------+ |
420a0d19 | 14601 | |perl_startup|Use: main|Type: string|Default: unset| |
2813c06e | 14602 | +--------------------------------------------------+ |
420a0d19 CE |
14603 | |
14604 | This option is available only when Exim is built with an embedded Perl | |
14605 | interpreter. See chapter 12 for details of its use. | |
14606 | ||
2813c06e CE |
14607 | +---------------------------------------------------+ |
14608 | |perl_startup|Use: main|Type: boolean|Default: false| | |
14609 | +---------------------------------------------------+ | |
14610 | ||
14611 | This Option enables the taint mode of the embedded Perl interpreter. | |
14612 | ||
14613 | +--------------------------------------------------------+ | |
420a0d19 | 14614 | |pgsql_servers|Use: main|Type: string list|Default: unset| |
2813c06e | 14615 | +--------------------------------------------------------+ |
420a0d19 CE |
14616 | |
14617 | This option provides a list of PostgreSQL servers and associated connection | |
2813c06e | 14618 | data, to be used in conjunction with pgsql lookups (see section 9.22). The |
420a0d19 CE |
14619 | option is available only if Exim has been built with PostgreSQL support. |
14620 | ||
2813c06e | 14621 | +------------------------------------------------------------------+ |
420a0d19 | 14622 | |pid_file_path|Use: main|Type: string*|Default: set at compile time| |
2813c06e | 14623 | +------------------------------------------------------------------+ |
420a0d19 CE |
14624 | |
14625 | This option sets the name of the file to which the Exim daemon writes its | |
14626 | process id. The string is expanded, so it can contain, for example, references | |
14627 | to the host name: | |
14628 | ||
14629 | pid_file_path = /var/log/$primary_hostname/exim.pid | |
14630 | ||
14631 | If no path is set, the pid is written to the file exim-daemon.pid in Exim's | |
14632 | spool directory. The value set by the option can be overridden by the -oP | |
14633 | command line option. A pid file is not written if a "non-standard" daemon is | |
14634 | run by means of the -oX option, unless a path is explicitly supplied by -oP. | |
14635 | ||
2813c06e | 14636 | +----------------------------------------------------------------+ |
420a0d19 | 14637 | |pipelining_advertise_hosts|Use: main|Type: host list*|Default: *| |
2813c06e | 14638 | +----------------------------------------------------------------+ |
420a0d19 CE |
14639 | |
14640 | This option can be used to suppress the advertisement of the SMTP PIPELINING | |
14641 | extension to specific hosts. See also the no_pipelining control in section | |
2813c06e | 14642 | 43.22. When PIPELINING is not advertised and smtp_enforce_sync is true, an Exim |
420a0d19 CE |
14643 | server enforces strict synchronization for each SMTP command and response. When |
14644 | PIPELINING is advertised, Exim assumes that clients will use it; "out of order" | |
14645 | commands that are "expected" do not count as protocol errors (see | |
14646 | smtp_max_synprot_errors). | |
14647 | ||
2813c06e | 14648 | +--------------------------------------------------+ |
420a0d19 | 14649 | |prdr_enable|Use: main|Type: boolean|Default: false| |
2813c06e | 14650 | +--------------------------------------------------+ |
420a0d19 CE |
14651 | |
14652 | This option can be used to enable the Per-Recipient Data Response extension to | |
14653 | SMTP, defined by Eric Hall. If the option is set, PRDR is advertised by Exim | |
14654 | when operating as a server. If the client requests PRDR, and more than one | |
14655 | recipient, for a message an additional ACL is called for each recipient after | |
2813c06e | 14656 | the message content is received. See section 43.9. |
420a0d19 | 14657 | |
2813c06e | 14658 | +------------------------------------------------------------+ |
420a0d19 | 14659 | |preserve_message_logs|Use: main|Type: boolean|Default: false| |
2813c06e | 14660 | +------------------------------------------------------------+ |
420a0d19 CE |
14661 | |
14662 | If this option is set, message log files are not deleted when messages are | |
14663 | completed. Instead, they are moved to a sub-directory of the spool directory | |
14664 | called msglog.OLD, where they remain available for statistical or debugging | |
14665 | purposes. This is a dangerous option to set on systems with any appreciable | |
14666 | volume of mail. Use with care! | |
14667 | ||
2813c06e | 14668 | +----------------------------------------------------------+ |
420a0d19 | 14669 | |primary_hostname|Use: main|Type: string|Default: see below| |
2813c06e | 14670 | +----------------------------------------------------------+ |
420a0d19 CE |
14671 | |
14672 | This specifies the name of the current host. It is used in the default EHLO or | |
14673 | HELO command for outgoing SMTP messages (changeable via the helo_data option in | |
14674 | the smtp transport), and as the default for qualify_domain. The value is also | |
14675 | used by default in some SMTP response messages from an Exim server. This can be | |
14676 | changed dynamically by setting smtp_active_hostname. | |
14677 | ||
14678 | If primary_hostname is not set, Exim calls uname() to find the host name. If | |
14679 | this fails, Exim panics and dies. If the name returned by uname() contains only | |
14680 | one component, Exim passes it to gethostbyname() (or getipnodebyname() when | |
14681 | available) in order to obtain the fully qualified version. The variable | |
14682 | $primary_hostname contains the host name, whether set explicitly by this | |
14683 | option, or defaulted. | |
14684 | ||
2813c06e | 14685 | +--------------------------------------------------------+ |
420a0d19 | 14686 | |print_topbitchars|Use: main|Type: boolean|Default: false| |
2813c06e | 14687 | +--------------------------------------------------------+ |
420a0d19 CE |
14688 | |
14689 | By default, Exim considers only those characters whose codes lie in the range | |
14690 | 32-126 to be printing characters. In a number of circumstances (for example, | |
14691 | when writing log entries) non-printing characters are converted into escape | |
14692 | sequences, primarily to avoid messing up the layout. If print_topbitchars is | |
14693 | set, code values of 128 and above are also considered to be printing | |
14694 | characters. | |
14695 | ||
14696 | This option also affects the header syntax checks performed by the autoreply | |
14697 | transport, and whether Exim uses RFC 2047 encoding of the user's full name when | |
2813c06e | 14698 | constructing From: and Sender: addresses (as described in section 47.18). |
420a0d19 CE |
14699 | Setting this option can cause Exim to generate eight bit message headers that |
14700 | do not conform to the standards. | |
14701 | ||
2813c06e | 14702 | +------------------------------------------------------+ |
420a0d19 | 14703 | |process_log_path|Use: main|Type: string|Default: unset| |
2813c06e | 14704 | +------------------------------------------------------+ |
420a0d19 CE |
14705 | |
14706 | This option sets the name of the file to which an Exim process writes its | |
14707 | "process log" when sent a USR1 signal. This is used by the exiwhat utility | |
14708 | script. If this option is unset, the file called exim-process.info in Exim's | |
14709 | spool directory is used. The ability to specify the name explicitly can be | |
14710 | useful in environments where two different Exims are running, using different | |
14711 | spool directories. | |
14712 | ||
2813c06e | 14713 | +---------------------------------------------------------+ |
420a0d19 | 14714 | |prod_requires_admin|Use: main|Type: boolean|Default: true| |
2813c06e | 14715 | +---------------------------------------------------------+ |
420a0d19 CE |
14716 | |
14717 | The -M, -R, and -q command-line options require the caller to be an admin user | |
14718 | unless prod_requires_admin is set false. See also queue_list_requires_admin. | |
14719 | ||
2813c06e | 14720 | +--------------------------------------------------------+ |
420a0d19 | 14721 | |qualify_domain|Use: main|Type: string|Default: see below| |
2813c06e | 14722 | +--------------------------------------------------------+ |
420a0d19 CE |
14723 | |
14724 | This option specifies the domain name that is added to any envelope sender | |
14725 | addresses that do not have a domain qualification. It also applies to recipient | |
14726 | addresses if qualify_recipient is not set. Unqualified addresses are accepted | |
14727 | by default only for locally-generated messages. Qualification is also applied | |
14728 | to addresses in header lines such as From: and To: for locally-generated | |
14729 | messages, unless the -bnq command line option is used. | |
14730 | ||
14731 | Messages from external sources must always contain fully qualified addresses, | |
14732 | unless the sending host matches sender_unqualified_hosts or | |
14733 | recipient_unqualified_hosts (as appropriate), in which case incoming addresses | |
14734 | are qualified with qualify_domain or qualify_recipient as necessary. | |
14735 | Internally, Exim always works with fully qualified envelope addresses. If | |
14736 | qualify_domain is not set, it defaults to the primary_hostname value. | |
14737 | ||
2813c06e | 14738 | +-----------------------------------------------------------+ |
420a0d19 | 14739 | |qualify_recipient|Use: main|Type: string|Default: see below| |
2813c06e | 14740 | +-----------------------------------------------------------+ |
420a0d19 CE |
14741 | |
14742 | This option allows you to specify a different domain for qualifying recipient | |
14743 | addresses to the one that is used for senders. See qualify_domain above. | |
14744 | ||
2813c06e | 14745 | +---------------------------------------------------------+ |
420a0d19 | 14746 | |queue_domains|Use: main|Type: domain list*|Default: unset| |
2813c06e | 14747 | +---------------------------------------------------------+ |
420a0d19 CE |
14748 | |
14749 | This option lists domains for which immediate delivery is not required. A | |
14750 | delivery process is started whenever a message is received, but only those | |
14751 | domains that do not match are processed. All other deliveries wait until the | |
14752 | next queue run. See also hold_domains and queue_smtp_domains. | |
14753 | ||
2813c06e | 14754 | +---------------------------------------------------------------+ |
420a0d19 | 14755 | |queue_list_requires_admin|Use: main|Type: boolean|Default: true| |
2813c06e | 14756 | +---------------------------------------------------------------+ |
420a0d19 CE |
14757 | |
14758 | The -bp command-line option, which lists the messages that are on the queue, | |
14759 | requires the caller to be an admin user unless queue_list_requires_admin is set | |
14760 | false. See also prod_requires_admin. | |
14761 | ||
2813c06e | 14762 | +-------------------------------------------------+ |
420a0d19 | 14763 | |queue_only|Use: main|Type: boolean|Default: false| |
2813c06e | 14764 | +-------------------------------------------------+ |
420a0d19 CE |
14765 | |
14766 | If queue_only is set, a delivery process is not automatically started whenever | |
14767 | a message is received. Instead, the message waits on the queue for the next | |
14768 | queue run. Even if queue_only is false, incoming messages may not get delivered | |
14769 | immediately when certain conditions (such as heavy load) occur. | |
14770 | ||
14771 | The -odq command line has the same effect as queue_only. The -odb and -odi | |
14772 | command line options override queue_only unless queue_only_override is set | |
14773 | false. See also queue_only_file, queue_only_load, and smtp_accept_queue. | |
14774 | ||
2813c06e | 14775 | +-----------------------------------------------------+ |
420a0d19 | 14776 | |queue_only_file|Use: main|Type: string|Default: unset| |
2813c06e | 14777 | +-----------------------------------------------------+ |
420a0d19 CE |
14778 | |
14779 | This option can be set to a colon-separated list of absolute path names, each | |
14780 | one optionally preceded by "smtp". When Exim is receiving a message, it tests | |
14781 | for the existence of each listed path using a call to stat(). For each path | |
14782 | that exists, the corresponding queueing option is set. For paths with no | |
14783 | prefix, queue_only is set; for paths prefixed by "smtp", queue_smtp_domains is | |
14784 | set to match all domains. So, for example, | |
14785 | ||
14786 | queue_only_file = smtp/some/file | |
14787 | ||
14788 | causes Exim to behave as if queue_smtp_domains were set to "*" whenever /some/ | |
14789 | file exists. | |
14790 | ||
2813c06e | 14791 | +----------------------------------------------------------+ |
420a0d19 | 14792 | |queue_only_load|Use: main|Type: fixed-point|Default: unset| |
2813c06e | 14793 | +----------------------------------------------------------+ |
420a0d19 CE |
14794 | |
14795 | If the system load average is higher than this value, incoming messages from | |
14796 | all sources are queued, and no automatic deliveries are started. If this | |
14797 | happens during local or remote SMTP input, all subsequent messages received on | |
14798 | the same SMTP connection are queued by default, whatever happens to the load in | |
14799 | the meantime, but this can be changed by setting queue_only_load_latch false. | |
14800 | ||
14801 | Deliveries will subsequently be performed by queue runner processes. This | |
14802 | option has no effect on ancient operating systems on which Exim cannot | |
14803 | determine the load average. See also deliver_queue_load_max and | |
14804 | smtp_load_reserve. | |
14805 | ||
2813c06e | 14806 | +-----------------------------------------------------------+ |
420a0d19 | 14807 | |queue_only_load_latch|Use: main|Type: boolean|Default: true| |
2813c06e | 14808 | +-----------------------------------------------------------+ |
420a0d19 CE |
14809 | |
14810 | When this option is true (the default), once one message has been queued | |
14811 | because the load average is higher than the value set by queue_only_load, all | |
14812 | subsequent messages received on the same SMTP connection are also queued. This | |
14813 | is a deliberate choice; even though the load average may fall below the | |
14814 | threshold, it doesn't seem right to deliver later messages on the same | |
14815 | connection when not delivering earlier ones. However, there are special | |
14816 | circumstances such as very long-lived connections from scanning appliances | |
14817 | where this is not the best strategy. In such cases, queue_only_load_latch | |
14818 | should be set false. This causes the value of the load average to be | |
14819 | re-evaluated for each message. | |
14820 | ||
2813c06e | 14821 | +---------------------------------------------------------+ |
420a0d19 | 14822 | |queue_only_override|Use: main|Type: boolean|Default: true| |
2813c06e | 14823 | +---------------------------------------------------------+ |
420a0d19 CE |
14824 | |
14825 | When this option is true, the -odx command line options override the setting of | |
14826 | queue_only or queue_only_file in the configuration file. If queue_only_override | |
14827 | is set false, the -odx options cannot be used to override; they are accepted, | |
14828 | but ignored. | |
14829 | ||
2813c06e | 14830 | +---------------------------------------------------------+ |
420a0d19 | 14831 | |queue_run_in_order|Use: main|Type: boolean|Default: false| |
2813c06e | 14832 | +---------------------------------------------------------+ |
420a0d19 CE |
14833 | |
14834 | If this option is set, queue runs happen in order of message arrival instead of | |
14835 | in an arbitrary order. For this to happen, a complete list of the entire queue | |
14836 | must be set up before the deliveries start. When the queue is all held in a | |
14837 | single directory (the default), a single list is created for both the ordered | |
14838 | and the non-ordered cases. However, if split_spool_directory is set, a single | |
14839 | list is not created when queue_run_in_order is false. In this case, the | |
14840 | sub-directories are processed one at a time (in a random order), and this | |
14841 | avoids setting up one huge list for the whole queue. Thus, setting | |
14842 | queue_run_in_order with split_spool_directory may degrade performance when the | |
14843 | queue is large, because of the extra work in setting up the single, large list. | |
14844 | In most situations, queue_run_in_order should not be set. | |
14845 | ||
2813c06e CE |
14846 | +-------------------------------------------------+ |
14847 | |queue_run_max|Use: main|Type: integer*|Default: 5| | |
14848 | +-------------------------------------------------+ | |
420a0d19 CE |
14849 | |
14850 | This controls the maximum number of queue runner processes that an Exim daemon | |
14851 | can run simultaneously. This does not mean that it starts them all at once, but | |
14852 | rather that if the maximum number are still running when the time comes to | |
14853 | start another one, it refrains from starting another one. This can happen with | |
14854 | very large queues and/or very sluggish deliveries. This option does not, | |
14855 | however, interlock with other processes, so additional queue runners can be | |
14856 | started by other means, or by killing and restarting the daemon. | |
14857 | ||
14858 | Setting this option to zero does not suppress queue runs; rather, it disables | |
14859 | the limit, allowing any number of simultaneous queue runner processes to be | |
14860 | run. If you do not want queue runs to occur, omit the -qxx setting on the | |
14861 | daemon's command line. | |
14862 | ||
2813c06e CE |
14863 | To set limits for different named queues use an expansion depending on the |
14864 | $queue_name variable. | |
14865 | ||
14866 | +--------------------------------------------------------------+ | |
420a0d19 | 14867 | |queue_smtp_domains|Use: main|Type: domain list*|Default: unset| |
2813c06e | 14868 | +--------------------------------------------------------------+ |
420a0d19 CE |
14869 | |
14870 | When this option is set, a delivery process is started whenever a message is | |
14871 | received, routing is performed, and local deliveries take place. However, if | |
14872 | any SMTP deliveries are required for domains that match queue_smtp_domains, | |
14873 | they are not immediately delivered, but instead the message waits on the queue | |
14874 | for the next queue run. Since routing of the message has taken place, Exim | |
14875 | knows to which remote hosts it must be delivered, and so when the queue run | |
14876 | happens, multiple messages for the same host are delivered over a single SMTP | |
14877 | connection. The -odqs command line option causes all SMTP deliveries to be | |
14878 | queued in this way, and is equivalent to setting queue_smtp_domains to "*". See | |
14879 | also hold_domains and queue_domains. | |
14880 | ||
2813c06e | 14881 | +------------------------------------------------+ |
420a0d19 | 14882 | |receive_timeout|Use: main|Type: time|Default: 0s| |
2813c06e | 14883 | +------------------------------------------------+ |
420a0d19 CE |
14884 | |
14885 | This option sets the timeout for accepting a non-SMTP message, that is, the | |
14886 | maximum time that Exim waits when reading a message on the standard input. If | |
14887 | the value is zero, it will wait for ever. This setting is overridden by the -or | |
14888 | command line option. The timeout for incoming SMTP messages is controlled by | |
14889 | smtp_receive_timeout. | |
14890 | ||
2813c06e | 14891 | +---------------------------------------------------------------+ |
420a0d19 | 14892 | |received_header_text|Use: main|Type: string*|Default: see below| |
2813c06e | 14893 | +---------------------------------------------------------------+ |
420a0d19 CE |
14894 | |
14895 | This string defines the contents of the Received: message header that is added | |
14896 | to each message, except for the timestamp, which is automatically added on at | |
14897 | the end (preceded by a semicolon). The string is expanded each time it is used. | |
14898 | If the expansion yields an empty string, no Received: header line is added to | |
14899 | the message. Otherwise, the string should start with the text "Received:" and | |
14900 | conform to the RFC 2822 specification for Received: header lines. The default | |
14901 | setting is: | |
14902 | ||
14903 | received_header_text = Received: \ | |
14904 | ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\ | |
14905 | {${if def:sender_ident \ | |
14906 | {from ${quote_local_part:$sender_ident} }}\ | |
14907 | ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\ | |
14908 | by $primary_hostname \ | |
14909 | ${if def:received_protocol {with $received_protocol}} \ | |
14910 | ${if def:tls_in_cipher {($tls_in_cipher)\n\t}}\ | |
14911 | (Exim $version_number)\n\t\ | |
14912 | ${if def:sender_address \ | |
14913 | {(envelope-from <$sender_address>)\n\t}}\ | |
14914 | id $message_exim_id\ | |
14915 | ${if def:received_for {\n\tfor $received_for}} | |
14916 | ||
14917 | The reference to the TLS cipher is omitted when Exim is built without TLS | |
14918 | support. The use of conditional expansions ensures that this works for both | |
14919 | locally generated messages and messages received from remote hosts, giving | |
14920 | header lines such as the following: | |
14921 | ||
14922 | Received: from scrooge.carol.example ([192.168.12.25] ident=root) | |
14923 | by marley.carol.example with esmtp (Exim 4.00) | |
14924 | (envelope-from <bob@carol.example>) | |
14925 | id 16IOWa-00019l-00 | |
14926 | for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000 | |
14927 | Received: by scrooge.carol.example with local (Exim 4.00) | |
14928 | id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000 | |
14929 | ||
14930 | Until the body of the message has been received, the timestamp is the time when | |
14931 | the message started to be received. Once the body has arrived, and all policy | |
14932 | checks have taken place, the timestamp is updated to the time at which the | |
14933 | message was accepted. | |
14934 | ||
2813c06e | 14935 | +--------------------------------------------------------+ |
420a0d19 | 14936 | |received_headers_max|Use: main|Type: integer|Default: 30| |
2813c06e | 14937 | +--------------------------------------------------------+ |
420a0d19 CE |
14938 | |
14939 | When a message is to be delivered, the number of Received: headers is counted, | |
14940 | and if it is greater than this parameter, a mail loop is assumed to have | |
14941 | occurred, the delivery is abandoned, and an error message is generated. This | |
14942 | applies to both local and remote deliveries. | |
14943 | ||
2813c06e | 14944 | +---------------------------------------------------------------------+ |
420a0d19 | 14945 | |recipient_unqualified_hosts|Use: main|Type: host list*|Default: unset| |
2813c06e | 14946 | +---------------------------------------------------------------------+ |
420a0d19 CE |
14947 | |
14948 | This option lists those hosts from which Exim is prepared to accept unqualified | |
14949 | recipient addresses in message envelopes. The addresses are made fully | |
14950 | qualified by the addition of the qualify_recipient value. This option also | |
14951 | affects message header lines. Exim does not reject unqualified recipient | |
14952 | addresses in headers, but it qualifies them only if the message came from a | |
14953 | host that matches recipient_unqualified_hosts, or if the message was submitted | |
14954 | locally (not using TCP/IP), and the -bnq option was not set. | |
14955 | ||
2813c06e | 14956 | +-------------------------------------------------+ |
420a0d19 | 14957 | |recipients_max|Use: main|Type: integer|Default: 0| |
2813c06e | 14958 | +-------------------------------------------------+ |
420a0d19 CE |
14959 | |
14960 | If this option is set greater than zero, it specifies the maximum number of | |
14961 | original recipients for any message. Additional recipients that are generated | |
14962 | by aliasing or forwarding do not count. SMTP messages get a 452 response for | |
14963 | all recipients over the limit; earlier recipients are delivered as normal. | |
14964 | Non-SMTP messages with too many recipients are failed, and no deliveries are | |
14965 | done. | |
14966 | ||
14967 | Note: The RFCs specify that an SMTP server should accept at least 100 RCPT | |
14968 | commands in a single message. | |
14969 | ||
2813c06e | 14970 | +------------------------------------------------------------+ |
420a0d19 | 14971 | |recipients_max_reject|Use: main|Type: boolean|Default: false| |
2813c06e | 14972 | +------------------------------------------------------------+ |
420a0d19 CE |
14973 | |
14974 | If this option is set true, Exim rejects SMTP messages containing too many | |
14975 | recipients by giving 552 errors to the surplus RCPT commands, and a 554 error | |
14976 | to the eventual DATA command. Otherwise (the default) it gives a 452 error to | |
14977 | the surplus RCPT commands and accepts the message on behalf of the initial set | |
14978 | of recipients. The remote server should then re-send the message for the | |
14979 | remaining recipients at a later time. | |
14980 | ||
2813c06e | 14981 | +------------------------------------------------------+ |
420a0d19 | 14982 | |remote_max_parallel|Use: main|Type: integer|Default: 2| |
2813c06e | 14983 | +------------------------------------------------------+ |
420a0d19 CE |
14984 | |
14985 | This option controls parallel delivery of one message to a number of remote | |
14986 | hosts. If the value is less than 2, parallel delivery is disabled, and Exim | |
14987 | does all the remote deliveries for a message one by one. Otherwise, if a single | |
14988 | message has to be delivered to more than one remote host, or if several copies | |
14989 | have to be sent to the same remote host, up to remote_max_parallel deliveries | |
14990 | are done simultaneously. If more than remote_max_parallel deliveries are | |
14991 | required, the maximum number of processes are started, and as each one | |
14992 | finishes, another is begun. The order of starting processes is the same as if | |
14993 | sequential delivery were being done, and can be controlled by the | |
14994 | remote_sort_domains option. If parallel delivery takes place while running with | |
14995 | debugging turned on, the debugging output from each delivery process is tagged | |
14996 | with its process id. | |
14997 | ||
14998 | This option controls only the maximum number of parallel deliveries for one | |
14999 | message in one Exim delivery process. Because Exim has no central queue | |
15000 | manager, there is no way of controlling the total number of simultaneous | |
15001 | deliveries if the configuration allows a delivery attempt as soon as a message | |
15002 | is received. | |
15003 | ||
15004 | If you want to control the total number of deliveries on the system, you need | |
15005 | to set the queue_only option. This ensures that all incoming messages are added | |
15006 | to the queue without starting a delivery process. Then set up an Exim daemon to | |
15007 | start queue runner processes at appropriate intervals (probably fairly often, | |
15008 | for example, every minute), and limit the total number of queue runners by | |
15009 | setting the queue_run_max parameter. Because each queue runner delivers only | |
15010 | one message at a time, the maximum number of deliveries that can then take | |
15011 | place at once is queue_run_max multiplied by remote_max_parallel. | |
15012 | ||
15013 | If it is purely remote deliveries you want to control, use queue_smtp_domains | |
15014 | instead of queue_only. This has the added benefit of doing the SMTP routing | |
15015 | before queueing, so that several messages for the same host will eventually get | |
15016 | delivered down the same connection. | |
15017 | ||
2813c06e | 15018 | +---------------------------------------------------------------+ |
420a0d19 | 15019 | |remote_sort_domains|Use: main|Type: domain list*|Default: unset| |
2813c06e | 15020 | +---------------------------------------------------------------+ |
420a0d19 CE |
15021 | |
15022 | When there are a number of remote deliveries for a message, they are sorted by | |
15023 | domain into the order given by this list. For example, | |
15024 | ||
15025 | remote_sort_domains = *.cam.ac.uk:*.uk | |
15026 | ||
15027 | would attempt to deliver to all addresses in the cam.ac.uk domain first, then | |
15028 | to those in the uk domain, then to any others. | |
15029 | ||
2813c06e | 15030 | +--------------------------------------------------+ |
420a0d19 | 15031 | |retry_data_expire|Use: main|Type: time|Default: 7d| |
2813c06e | 15032 | +--------------------------------------------------+ |
420a0d19 CE |
15033 | |
15034 | This option sets a "use before" time on retry information in Exim's hints | |
15035 | database. Any older retry data is ignored. This means that, for example, once a | |
15036 | host has not been tried for 7 days, Exim behaves as if it has no knowledge of | |
15037 | past failures. | |
15038 | ||
2813c06e | 15039 | +----------------------------------------------------+ |
420a0d19 | 15040 | |retry_interval_max|Use: main|Type: time|Default: 24h| |
2813c06e | 15041 | +----------------------------------------------------+ |
420a0d19 CE |
15042 | |
15043 | Chapter 32 describes Exim's mechanisms for controlling the intervals between | |
15044 | delivery attempts for messages that cannot be delivered straight away. This | |
15045 | option sets an overall limit to the length of time between retries. It cannot | |
15046 | be set greater than 24 hours; any attempt to do so forces the default value. | |
15047 | ||
2813c06e | 15048 | +--------------------------------------------------------+ |
420a0d19 | 15049 | |return_path_remove|Use: main|Type: boolean|Default: true| |
2813c06e | 15050 | +--------------------------------------------------------+ |
420a0d19 CE |
15051 | |
15052 | RFC 2821, section 4.4, states that an SMTP server must insert a Return-path: | |
15053 | header line into a message when it makes a "final delivery". The Return-path: | |
15054 | header preserves the sender address as received in the MAIL command. This | |
15055 | description implies that this header should not be present in an incoming | |
15056 | message. If return_path_remove is true, any existing Return-path: headers are | |
15057 | removed from messages at the time they are received. Exim's transports have | |
15058 | options for adding Return-path: headers at the time of delivery. They are | |
15059 | normally used only for final local deliveries. | |
15060 | ||
2813c06e | 15061 | +-------------------------------------------------------+ |
420a0d19 | 15062 | |return_size_limit|Use: main|Type: integer|Default: 100K| |
2813c06e | 15063 | +-------------------------------------------------------+ |
420a0d19 CE |
15064 | |
15065 | This option is an obsolete synonym for bounce_return_size_limit. | |
15066 | ||
2813c06e CE |
15067 | +-----------------------------------------------------+ |
15068 | |rfc1413_hosts|Use: main|Type: host list*|Default: @[]| | |
15069 | +-----------------------------------------------------+ | |
420a0d19 CE |
15070 | |
15071 | RFC 1413 identification calls are made to any client host which matches an item | |
2813c06e CE |
15072 | in the list. The default value specifies just this host, being any local |
15073 | interface for the system. | |
420a0d19 | 15074 | |
2813c06e CE |
15075 | +------------------------------------------------------+ |
15076 | |rfc1413_query_timeout|Use: main|Type: time|Default: 0s| | |
15077 | +------------------------------------------------------+ | |
420a0d19 CE |
15078 | |
15079 | This sets the timeout on RFC 1413 identification calls. If it is set to zero, | |
15080 | no RFC 1413 calls are ever made. | |
15081 | ||
2813c06e | 15082 | +------------------------------------------------------------------+ |
420a0d19 | 15083 | |sender_unqualified_hosts|Use: main|Type: host list*|Default: unset| |
2813c06e | 15084 | +------------------------------------------------------------------+ |
420a0d19 CE |
15085 | |
15086 | This option lists those hosts from which Exim is prepared to accept unqualified | |
15087 | sender addresses. The addresses are made fully qualified by the addition of | |
15088 | qualify_domain. This option also affects message header lines. Exim does not | |
15089 | reject unqualified addresses in headers that contain sender addresses, but it | |
15090 | qualifies them only if the message came from a host that matches | |
15091 | sender_unqualified_hosts, or if the message was submitted locally (not using | |
15092 | TCP/IP), and the -bnq option was not set. | |
15093 | ||
2813c06e CE |
15094 | +----------------------------------------------------------+ |
15095 | |set_environment|Use: main|Type: string list|Default: empty| | |
15096 | +----------------------------------------------------------+ | |
15097 | ||
15098 | This option allows to set individual environment variables that the currently | |
15099 | linked libraries and programs in child processes use. The default list is | |
15100 | empty, | |
15101 | ||
15102 | +--------------------------------------------------+ | |
15103 | |slow_lookup_log|Use: main|Type: integer|Default: 0| | |
15104 | +--------------------------------------------------+ | |
15105 | ||
15106 | This option controls logging of slow lookups. If the value is nonzero it is | |
15107 | taken as a number of milliseconds and lookups taking longer than this are | |
15108 | logged. Currently this applies only to DNS lookups. | |
15109 | ||
15110 | +-----------------------------------------------------------+ | |
420a0d19 | 15111 | |smtp_accept_keepalive|Use: main|Type: boolean|Default: true| |
2813c06e | 15112 | +-----------------------------------------------------------+ |
420a0d19 CE |
15113 | |
15114 | This option controls the setting of the SO_KEEPALIVE option on incoming TCP/IP | |
15115 | socket connections. When set, it causes the kernel to probe idle connections | |
15116 | periodically, by sending packets with "old" sequence numbers. The other end of | |
15117 | the connection should send an acknowledgment if the connection is still okay or | |
15118 | a reset if the connection has been aborted. The reason for doing this is that | |
15119 | it has the beneficial effect of freeing up certain types of connection that can | |
15120 | get stuck when the remote host is disconnected without tidying up the TCP/IP | |
15121 | call properly. The keepalive mechanism takes several hours to detect | |
15122 | unreachable hosts. | |
15123 | ||
2813c06e | 15124 | +---------------------------------------------------+ |
420a0d19 | 15125 | |smtp_accept_max|Use: main|Type: integer|Default: 20| |
2813c06e | 15126 | +---------------------------------------------------+ |
420a0d19 CE |
15127 | |
15128 | This option specifies the maximum number of simultaneous incoming SMTP calls | |
15129 | that Exim will accept. It applies only to the listening daemon; there is no | |
15130 | control (in Exim) when incoming SMTP is being handled by inetd. If the value is | |
15131 | set to zero, no limit is applied. However, it is required to be non-zero if | |
15132 | either smtp_accept_max_per_host or smtp_accept_queue is set. See also | |
15133 | smtp_accept_reserve and smtp_load_reserve. | |
15134 | ||
15135 | A new SMTP connection is immediately rejected if the smtp_accept_max limit has | |
15136 | been reached. If not, Exim first checks smtp_accept_max_per_host. If that limit | |
15137 | has not been reached for the client host, smtp_accept_reserve and | |
15138 | smtp_load_reserve are then checked before accepting the connection. | |
15139 | ||
2813c06e | 15140 | +-----------------------------------------------------------+ |
420a0d19 | 15141 | |smtp_accept_max_nonmail|Use: main|Type: integer|Default: 10| |
2813c06e | 15142 | +-----------------------------------------------------------+ |
420a0d19 CE |
15143 | |
15144 | Exim counts the number of "non-mail" commands in an SMTP session, and drops the | |
15145 | connection if there are too many. This option defines "too many". The check | |
15146 | catches some denial-of-service attacks, repeated failing AUTHs, or a mad client | |
15147 | looping sending EHLO, for example. The check is applied only if the client host | |
15148 | matches smtp_accept_max_nonmail_hosts. | |
15149 | ||
15150 | When a new message is expected, one occurrence of RSET is not counted. This | |
15151 | allows a client to send one RSET between messages (this is not necessary, but | |
15152 | some clients do it). Exim also allows one uncounted occurrence of HELO or EHLO, | |
15153 | and one occurrence of STARTTLS between messages. After starting up a TLS | |
15154 | session, another EHLO is expected, and so it too is not counted. The first | |
15155 | occurrence of AUTH in a connection, or immediately following STARTTLS is not | |
15156 | counted. Otherwise, all commands other than MAIL, RCPT, DATA, and QUIT are | |
15157 | counted. | |
15158 | ||
2813c06e | 15159 | +-------------------------------------------------------------------+ |
420a0d19 | 15160 | |smtp_accept_max_nonmail_hosts|Use: main|Type: host list*|Default: *| |
2813c06e | 15161 | +-------------------------------------------------------------------+ |
420a0d19 CE |
15162 | |
15163 | You can control which hosts are subject to the smtp_accept_max_nonmail check by | |
15164 | setting this option. The default value makes it apply to all hosts. By changing | |
15165 | the value, you can exclude any badly-behaved hosts that you have to live with. | |
15166 | ||
2813c06e | 15167 | +--------------------------------------------------------------------+ |
420a0d19 | 15168 | |smtp_accept_max_per_connection|Use: main|Type: integer|Default: 1000| |
2813c06e | 15169 | +--------------------------------------------------------------------+ |
420a0d19 CE |
15170 | |
15171 | The value of this option limits the number of MAIL commands that Exim is | |
15172 | prepared to accept over a single SMTP connection, whether or not each command | |
15173 | results in the transfer of a message. After the limit is reached, a 421 | |
15174 | response is given to subsequent MAIL commands. This limit is a safety | |
15175 | precaution against a client that goes mad (incidents of this type have been | |
15176 | seen). | |
15177 | ||
2813c06e | 15178 | +---------------------------------------------------------------+ |
420a0d19 | 15179 | |smtp_accept_max_per_host|Use: main|Type: string*|Default: unset| |
2813c06e | 15180 | +---------------------------------------------------------------+ |
420a0d19 CE |
15181 | |
15182 | This option restricts the number of simultaneous IP connections from a single | |
15183 | host (strictly, from a single IP address) to the Exim daemon. The option is | |
15184 | expanded, to enable different limits to be applied to different hosts by | |
15185 | reference to $sender_host_address. Once the limit is reached, additional | |
15186 | connection attempts from the same host are rejected with error code 421. This | |
15187 | is entirely independent of smtp_accept_reserve. The option's default value of | |
15188 | zero imposes no limit. If this option is set greater than zero, it is required | |
15189 | that smtp_accept_max be non-zero. | |
15190 | ||
15191 | Warning: When setting this option you should not use any expansion | |
15192 | constructions that take an appreciable amount of time. The expansion and test | |
15193 | happen in the main daemon loop, in order to reject additional connections | |
15194 | without forking additional processes (otherwise a denial-of-service attack | |
15195 | could cause a vast number or processes to be created). While the daemon is | |
15196 | doing this processing, it cannot accept any other incoming connections. | |
15197 | ||
2813c06e | 15198 | +----------------------------------------------------+ |
420a0d19 | 15199 | |smtp_accept_queue|Use: main|Type: integer|Default: 0| |
2813c06e | 15200 | +----------------------------------------------------+ |
420a0d19 CE |
15201 | |
15202 | If the number of simultaneous incoming SMTP connections being handled via the | |
15203 | listening daemon exceeds this value, messages received by SMTP are just placed | |
15204 | on the queue; no delivery processes are started automatically. The count is | |
15205 | fixed at the start of an SMTP connection. It cannot be updated in the | |
15206 | subprocess that receives messages, and so the queueing or not queueing applies | |
15207 | to all messages received in the same connection. | |
15208 | ||
15209 | A value of zero implies no limit, and clearly any non-zero value is useful only | |
15210 | if it is less than the smtp_accept_max value (unless that is zero). See also | |
15211 | queue_only, queue_only_load, queue_smtp_domains, and the various -odx command | |
15212 | line options. | |
15213 | ||
2813c06e | 15214 | +--------------------------------------------------------------------+ |
420a0d19 | 15215 | |smtp_accept_queue_per_connection|Use: main|Type: integer|Default: 10| |
2813c06e | 15216 | +--------------------------------------------------------------------+ |
420a0d19 CE |
15217 | |
15218 | This option limits the number of delivery processes that Exim starts | |
15219 | automatically when receiving messages via SMTP, whether via the daemon or by | |
15220 | the use of -bs or -bS. If the value of the option is greater than zero, and the | |
15221 | number of messages received in a single SMTP session exceeds this number, | |
15222 | subsequent messages are placed on the queue, but no delivery processes are | |
15223 | started. This helps to limit the number of Exim processes when a server | |
15224 | restarts after downtime and there is a lot of mail waiting for it on other | |
15225 | systems. On large systems, the default should probably be increased, and on | |
15226 | dial-in client systems it should probably be set to zero (that is, disabled). | |
15227 | ||
2813c06e | 15228 | +------------------------------------------------------+ |
420a0d19 | 15229 | |smtp_accept_reserve|Use: main|Type: integer|Default: 0| |
2813c06e | 15230 | +------------------------------------------------------+ |
420a0d19 CE |
15231 | |
15232 | When smtp_accept_max is set greater than zero, this option specifies a number | |
15233 | of SMTP connections that are reserved for connections from the hosts that are | |
15234 | specified in smtp_reserve_hosts. The value set in smtp_accept_max includes this | |
15235 | reserve pool. The specified hosts are not restricted to this number of | |
15236 | connections; the option specifies a minimum number of connection slots for | |
15237 | them, not a maximum. It is a guarantee that this group of hosts can always get | |
15238 | at least smtp_accept_reserve connections. However, the limit specified by | |
15239 | smtp_accept_max_per_host is still applied to each individual host. | |
15240 | ||
15241 | For example, if smtp_accept_max is set to 50 and smtp_accept_reserve is set to | |
15242 | 5, once there are 45 active connections (from any hosts), new connections are | |
15243 | accepted only from hosts listed in smtp_reserve_hosts, provided the other | |
15244 | criteria for acceptance are met. | |
15245 | ||
2813c06e | 15246 | +-----------------------------------------------------------+ |
420a0d19 | 15247 | |smtp_active_hostname|Use: main|Type: string*|Default: unset| |
2813c06e | 15248 | +-----------------------------------------------------------+ |
420a0d19 CE |
15249 | |
15250 | This option is provided for multi-homed servers that want to masquerade as | |
15251 | several different hosts. At the start of an incoming SMTP connection, its value | |
15252 | is expanded and used instead of the value of $primary_hostname in SMTP | |
15253 | responses. For example, it is used as domain name in the response to an | |
15254 | incoming HELO or EHLO command. | |
15255 | ||
15256 | The active hostname is placed in the $smtp_active_hostname variable, which is | |
15257 | saved with any messages that are received. It is therefore available for use in | |
15258 | routers and transports when the message is later delivered. | |
15259 | ||
15260 | If this option is unset, or if its expansion is forced to fail, or if the | |
15261 | expansion results in an empty string, the value of $primary_hostname is used. | |
15262 | Other expansion failures cause a message to be written to the main and panic | |
15263 | logs, and the SMTP command receives a temporary error. Typically, the value of | |
15264 | smtp_active_hostname depends on the incoming interface address. For example: | |
15265 | ||
15266 | smtp_active_hostname = ${if eq{$received_ip_address}{10.0.0.1}\ | |
15267 | {cox.mydomain}{box.mydomain}} | |
15268 | ||
15269 | Although $smtp_active_hostname is primarily concerned with incoming messages, | |
15270 | it is also used as the default for HELO commands in callout verification if | |
15271 | there is no remote transport from which to obtain a helo_data value. | |
15272 | ||
2813c06e | 15273 | +------------------------------------------------------+ |
420a0d19 | 15274 | |smtp_banner|Use: main|Type: string*|Default: see below| |
2813c06e | 15275 | +------------------------------------------------------+ |
420a0d19 CE |
15276 | |
15277 | This string, which is expanded every time it is used, is output as the initial | |
15278 | positive response to an SMTP connection. The default setting is: | |
15279 | ||
15280 | smtp_banner = $smtp_active_hostname ESMTP Exim \ | |
15281 | $version_number $tod_full | |
15282 | ||
15283 | Failure to expand the string causes a panic error. If you want to create a | |
15284 | multiline response to the initial SMTP connection, use "\n" in the string at | |
15285 | appropriate points, but not at the end. Note that the 220 code is not included | |
15286 | in this string. Exim adds it automatically (several times in the case of a | |
15287 | multiline response). | |
15288 | ||
2813c06e | 15289 | +------------------------------------------------------------+ |
420a0d19 | 15290 | |smtp_check_spool_space|Use: main|Type: boolean|Default: true| |
2813c06e | 15291 | +------------------------------------------------------------+ |
420a0d19 CE |
15292 | |
15293 | When this option is set, if an incoming SMTP session encounters the SIZE option | |
15294 | on a MAIL command, it checks that there is enough space in the spool | |
15295 | directory's partition to accept a message of that size, while still leaving | |
15296 | free the amount specified by check_spool_space (even if that value is zero). If | |
15297 | there isn't enough space, a temporary error code is returned. | |
15298 | ||
2813c06e | 15299 | +--------------------------------------------------------+ |
420a0d19 | 15300 | |smtp_connect_backlog|Use: main|Type: integer|Default: 20| |
2813c06e | 15301 | +--------------------------------------------------------+ |
420a0d19 CE |
15302 | |
15303 | This option specifies a maximum number of waiting SMTP connections. Exim passes | |
15304 | this value to the TCP/IP system when it sets up its listener. Once this number | |
15305 | of connections are waiting for the daemon's attention, subsequent connection | |
15306 | attempts are refused at the TCP/IP level. At least, that is what the manuals | |
15307 | say; in some circumstances such connection attempts have been observed to time | |
15308 | out instead. For large systems it is probably a good idea to increase the value | |
15309 | (to 50, say). It also gives some protection against denial-of-service attacks | |
15310 | by SYN flooding. | |
15311 | ||
2813c06e | 15312 | +-------------------------------------------------------+ |
420a0d19 | 15313 | |smtp_enforce_sync|Use: main|Type: boolean|Default: true| |
2813c06e | 15314 | +-------------------------------------------------------+ |
420a0d19 CE |
15315 | |
15316 | The SMTP protocol specification requires the client to wait for a response from | |
15317 | the server at certain points in the dialogue. Without PIPELINING these | |
15318 | synchronization points are after every command; with PIPELINING they are fewer, | |
15319 | but they still exist. | |
15320 | ||
15321 | Some spamming sites send out a complete set of SMTP commands without waiting | |
15322 | for any response. Exim protects against this by rejecting a message if the | |
15323 | client has sent further input when it should not have. The error response "554 | |
15324 | SMTP synchronization error" is sent, and the connection is dropped. Testing for | |
15325 | this error cannot be perfect because of transmission delays (unexpected input | |
15326 | may be on its way but not yet received when Exim checks). However, it does | |
15327 | detect many instances. | |
15328 | ||
15329 | The check can be globally disabled by setting smtp_enforce_sync false. If you | |
15330 | want to disable the check selectively (for example, only for certain hosts), | |
15331 | you can do so by an appropriate use of a control modifier in an ACL (see | |
2813c06e | 15332 | section 43.22). See also pipelining_advertise_hosts. |
420a0d19 | 15333 | |
2813c06e | 15334 | +--------------------------------------------------------+ |
420a0d19 | 15335 | |smtp_etrn_command|Use: main|Type: string*|Default: unset| |
2813c06e | 15336 | +--------------------------------------------------------+ |
420a0d19 CE |
15337 | |
15338 | If this option is set, the given command is run whenever an SMTP ETRN command | |
15339 | is received from a host that is permitted to issue such commands (see chapter | |
2813c06e | 15340 | 43). The string is split up into separate arguments which are independently |
420a0d19 CE |
15341 | expanded. The expansion variable $domain is set to the argument of the ETRN |
15342 | command, and no syntax checking is done on it. For example: | |
15343 | ||
15344 | smtp_etrn_command = /etc/etrn_command $domain \ | |
15345 | $sender_host_address | |
15346 | ||
15347 | A new process is created to run the command, but Exim does not wait for it to | |
15348 | complete. Consequently, its status cannot be checked. If the command cannot be | |
15349 | run, a line is written to the panic log, but the ETRN caller still receives a | |
15350 | 250 success response. Exim is normally running under its own uid when receiving | |
15351 | SMTP, so it is not possible for it to change the uid before running the | |
15352 | command. | |
15353 | ||
2813c06e | 15354 | +---------------------------------------------------------+ |
420a0d19 | 15355 | |smtp_etrn_serialize|Use: main|Type: boolean|Default: true| |
2813c06e | 15356 | +---------------------------------------------------------+ |
420a0d19 CE |
15357 | |
15358 | When this option is set, it prevents the simultaneous execution of more than | |
15359 | one identical command as a result of ETRN in an SMTP connection. See section | |
2813c06e | 15360 | 48.8 for details. |
420a0d19 | 15361 | |
2813c06e | 15362 | +------------------------------------------------------------+ |
420a0d19 | 15363 | |smtp_load_reserve|Use: main|Type: fixed-point|Default: unset| |
2813c06e | 15364 | +------------------------------------------------------------+ |
420a0d19 CE |
15365 | |
15366 | If the system load average ever gets higher than this, incoming SMTP calls are | |
15367 | accepted only from those hosts that match an entry in smtp_reserve_hosts. If | |
15368 | smtp_reserve_hosts is not set, no incoming SMTP calls are accepted when the | |
15369 | load is over the limit. The option has no effect on ancient operating systems | |
15370 | on which Exim cannot determine the load average. See also | |
15371 | deliver_queue_load_max and queue_only_load. | |
15372 | ||
2813c06e | 15373 | +----------------------------------------------------------+ |
420a0d19 | 15374 | |smtp_max_synprot_errors|Use: main|Type: integer|Default: 3| |
2813c06e | 15375 | +----------------------------------------------------------+ |
420a0d19 CE |
15376 | |
15377 | Exim rejects SMTP commands that contain syntax or protocol errors. In | |
15378 | particular, a syntactically invalid email address, as in this command: | |
15379 | ||
15380 | RCPT TO:<abc xyz@a.b.c> | |
15381 | ||
15382 | causes immediate rejection of the command, before any other tests are done. | |
15383 | (The ACL cannot be run if there is no valid address to set up for it.) An | |
15384 | example of a protocol error is receiving RCPT before MAIL. If there are too | |
15385 | many syntax or protocol errors in one SMTP session, the connection is dropped. | |
15386 | The limit is set by this option. | |
15387 | ||
15388 | When the PIPELINING extension to SMTP is in use, some protocol errors are | |
15389 | "expected", for instance, a RCPT command after a rejected MAIL command. Exim | |
15390 | assumes that PIPELINING will be used if it advertises it (see | |
15391 | pipelining_advertise_hosts), and in this situation, "expected" errors do not | |
15392 | count towards the limit. | |
15393 | ||
2813c06e | 15394 | +------------------------------------------------------------+ |
420a0d19 | 15395 | |smtp_max_unknown_commands|Use: main|Type: integer|Default: 3| |
2813c06e | 15396 | +------------------------------------------------------------+ |
420a0d19 CE |
15397 | |
15398 | If there are too many unrecognized commands in an incoming SMTP session, an | |
15399 | Exim server drops the connection. This is a defence against some kinds of abuse | |
15400 | that subvert web clients into making connections to SMTP ports; in these | |
15401 | circumstances, a number of non-SMTP command lines are sent first. | |
15402 | ||
2813c06e | 15403 | +--------------------------------------------------------------+ |
420a0d19 | 15404 | |smtp_ratelimit_hosts|Use: main|Type: host list*|Default: unset| |
2813c06e | 15405 | +--------------------------------------------------------------+ |
420a0d19 CE |
15406 | |
15407 | Some sites find it helpful to be able to limit the rate at which certain hosts | |
15408 | can send them messages, and the rate at which an individual message can specify | |
15409 | recipients. | |
15410 | ||
15411 | Exim has two rate-limiting facilities. This section describes the older | |
15412 | facility, which can limit rates within a single connection. The newer ratelimit | |
2813c06e | 15413 | ACL condition can limit rates across all connections. See section 43.38 for |
420a0d19 CE |
15414 | details of the newer facility. |
15415 | ||
15416 | When a host matches smtp_ratelimit_hosts, the values of smtp_ratelimit_mail and | |
15417 | smtp_ratelimit_rcpt are used to control the rate of acceptance of MAIL and RCPT | |
15418 | commands in a single SMTP session, respectively. Each option, if set, must | |
15419 | contain a set of four comma-separated values: | |
15420 | ||
15421 | * A threshold, before which there is no rate limiting. | |
15422 | ||
15423 | * An initial time delay. Unlike other times in Exim, numbers with decimal | |
15424 | fractional parts are allowed here. | |
15425 | ||
15426 | * A factor by which to increase the delay each time. | |
15427 | ||
15428 | * A maximum value for the delay. This should normally be less than 5 minutes, | |
15429 | because after that time, the client is liable to timeout the SMTP command. | |
15430 | ||
15431 | For example, these settings have been used successfully at the site which first | |
15432 | suggested this feature, for controlling mail from their customers: | |
15433 | ||
15434 | smtp_ratelimit_mail = 2,0.5s,1.05,4m | |
15435 | smtp_ratelimit_rcpt = 4,0.25s,1.015,4m | |
15436 | ||
15437 | The first setting specifies delays that are applied to MAIL commands after two | |
15438 | have been received over a single connection. The initial delay is 0.5 seconds, | |
15439 | increasing by a factor of 1.05 each time. The second setting applies delays to | |
15440 | RCPT commands when more than four occur in a single message. | |
15441 | ||
2813c06e | 15442 | +---------------------------------------------------------+ |
420a0d19 | 15443 | |smtp_ratelimit_mail|Use: main|Type: string|Default: unset| |
2813c06e | 15444 | +---------------------------------------------------------+ |
420a0d19 CE |
15445 | |
15446 | See smtp_ratelimit_hosts above. | |
15447 | ||
2813c06e | 15448 | +---------------------------------------------------------+ |
420a0d19 | 15449 | |smtp_ratelimit_rcpt|Use: main|Type: string|Default: unset| |
2813c06e | 15450 | +---------------------------------------------------------+ |
420a0d19 CE |
15451 | |
15452 | See smtp_ratelimit_hosts above. | |
15453 | ||
2813c06e CE |
15454 | +------------------------------------------------------+ |
15455 | |smtp_receive_timeout|Use: main|Type: time*|Default: 5m| | |
15456 | +------------------------------------------------------+ | |
420a0d19 CE |
15457 | |
15458 | This sets a timeout value for SMTP reception. It applies to all forms of SMTP | |
15459 | input, including batch SMTP. If a line of input (either an SMTP command or a | |
15460 | data line) is not received within this time, the SMTP connection is dropped and | |
15461 | the message is abandoned. A line is written to the log containing one of the | |
15462 | following messages: | |
15463 | ||
15464 | SMTP command timeout on connection from... | |
15465 | SMTP data timeout on connection from... | |
15466 | ||
15467 | The former means that Exim was expecting to read an SMTP command; the latter | |
15468 | means that it was in the DATA phase, reading the contents of a message. | |
15469 | ||
2813c06e CE |
15470 | If the first character of the option is a "$" the option is expanded before use |
15471 | and may depend on $sender_host_name, $sender_host_address and $sender_host_port | |
15472 | . | |
15473 | ||
420a0d19 CE |
15474 | The value set by this option can be overridden by the -os command-line option. |
15475 | A setting of zero time disables the timeout, but this should never be used for | |
15476 | SMTP over TCP/IP. (It can be useful in some cases of local input using -bs or | |
15477 | -bS.) For non-SMTP input, the reception timeout is controlled by | |
15478 | receive_timeout and -or. | |
15479 | ||
2813c06e | 15480 | +------------------------------------------------------------+ |
420a0d19 | 15481 | |smtp_reserve_hosts|Use: main|Type: host list*|Default: unset| |
2813c06e | 15482 | +------------------------------------------------------------+ |
420a0d19 CE |
15483 | |
15484 | This option defines hosts for which SMTP connections are reserved; see | |
15485 | smtp_accept_reserve and smtp_load_reserve above. | |
15486 | ||
2813c06e | 15487 | +----------------------------------------------------------------+ |
420a0d19 | 15488 | |smtp_return_error_details|Use: main|Type: boolean|Default: false| |
2813c06e | 15489 | +----------------------------------------------------------------+ |
420a0d19 CE |
15490 | |
15491 | In the default state, Exim uses bland messages such as "Administrative | |
15492 | prohibition" when it rejects SMTP commands for policy reasons. Many sysadmins | |
15493 | like this because it gives away little information to spammers. However, some | |
15494 | other sysadmins who are applying strict checking policies want to give out much | |
15495 | fuller information about failures. Setting smtp_return_error_details true | |
15496 | causes Exim to be more forthcoming. For example, instead of "Administrative | |
15497 | prohibition", it might give: | |
15498 | ||
15499 | 550-Rejected after DATA: '>' missing at end of address: | |
15500 | 550 failing address in "From" header is: <user@dom.ain | |
15501 | ||
2813c06e CE |
15502 | +--------------------------------------------------------------+ |
15503 | |smtputf8_advertise_hosts|Use: main|Type: host list*|Default: *| | |
15504 | +--------------------------------------------------------------+ | |
15505 | ||
15506 | When Exim is built with support for internationalised mail names, the | |
15507 | availability thereof is advertised in response to EHLO only to those client | |
15508 | hosts that match this option. See chapter 59 for details of Exim's support for | |
15509 | internationalisation. | |
15510 | ||
15511 | +-------------------------------------------------------+ | |
420a0d19 | 15512 | |spamd_address|Use: main|Type: string|Default: see below| |
2813c06e | 15513 | +-------------------------------------------------------+ |
420a0d19 CE |
15514 | |
15515 | This option is available when Exim is compiled with the content-scanning | |
15516 | extension. It specifies how Exim connects to SpamAssassin's spamd daemon. The | |
15517 | default value is | |
15518 | ||
15519 | 127.0.0.1 783 | |
15520 | ||
2813c06e | 15521 | See section 44.2 for more details. |
420a0d19 | 15522 | |
2813c06e | 15523 | +------------------------------------------------------------+ |
420a0d19 | 15524 | |split_spool_directory|Use: main|Type: boolean|Default: false| |
2813c06e | 15525 | +------------------------------------------------------------+ |
420a0d19 CE |
15526 | |
15527 | If this option is set, it causes Exim to split its input directory into 62 | |
15528 | subdirectories, each with a single alphanumeric character as its name. The | |
15529 | sixth character of the message id is used to allocate messages to | |
15530 | subdirectories; this is the least significant base-62 digit of the time of | |
15531 | arrival of the message. | |
15532 | ||
15533 | Splitting up the spool in this way may provide better performance on systems | |
15534 | where there are long mail queues, by reducing the number of files in any one | |
15535 | directory. The msglog directory is also split up in a similar way to the input | |
15536 | directory; however, if preserve_message_logs is set, all old msglog files are | |
15537 | still placed in the single directory msglog.OLD. | |
15538 | ||
15539 | It is not necessary to take any special action for existing messages when | |
15540 | changing split_spool_directory. Exim notices messages that are in the "wrong" | |
15541 | place, and continues to process them. If the option is turned off after a | |
15542 | period of being on, the subdirectories will eventually empty and be | |
15543 | automatically deleted. | |
15544 | ||
15545 | When split_spool_directory is set, the behaviour of queue runner processes | |
15546 | changes. Instead of creating a list of all messages in the queue, and then | |
15547 | trying to deliver each one in turn, it constructs a list of those in one | |
15548 | sub-directory and tries to deliver them, before moving on to the next | |
15549 | sub-directory. The sub-directories are processed in a random order. This | |
15550 | spreads out the scanning of the input directories, and uses less memory. It is | |
15551 | particularly beneficial when there are lots of messages on the queue. However, | |
15552 | if queue_run_in_order is set, none of this new processing happens. The entire | |
15553 | queue has to be scanned and sorted before any deliveries can start. | |
15554 | ||
2813c06e | 15555 | +--------------------------------------------------------------------+ |
420a0d19 | 15556 | |spool_directory|Use: main|Type: string*|Default: set at compile time| |
2813c06e | 15557 | +--------------------------------------------------------------------+ |
420a0d19 CE |
15558 | |
15559 | This defines the directory in which Exim keeps its spool, that is, the messages | |
15560 | it is waiting to deliver. The default value is taken from the compile-time | |
15561 | configuration setting, if there is one. If not, this option must be set. The | |
15562 | string is expanded, so it can contain, for example, a reference to | |
15563 | $primary_hostname. | |
15564 | ||
15565 | If the spool directory name is fixed on your installation, it is recommended | |
15566 | that you set it at build time rather than from this option, particularly if the | |
15567 | log files are being written to the spool directory (see log_file_path). | |
15568 | Otherwise log files cannot be used for errors that are detected early on, such | |
15569 | as failures in the configuration file. | |
15570 | ||
15571 | By using this option to override the compiled-in path, it is possible to run | |
15572 | tests of Exim without using the standard spool. | |
15573 | ||
2813c06e | 15574 | +----------------------------------------------------+ |
420a0d19 | 15575 | |sqlite_lock_timeout|Use: main|Type: time|Default: 5s| |
2813c06e | 15576 | +----------------------------------------------------+ |
420a0d19 CE |
15577 | |
15578 | This option controls the timeout that the sqlite lookup uses when trying to | |
2813c06e | 15579 | access an SQLite database. See section 9.26 for more details. |
420a0d19 | 15580 | |
2813c06e | 15581 | +------------------------------------------------------+ |
420a0d19 | 15582 | |strict_acl_vars|Use: main|Type: boolean|Default: false| |
2813c06e | 15583 | +------------------------------------------------------+ |
420a0d19 CE |
15584 | |
15585 | This option controls what happens if a syntactically valid but undefined ACL | |
15586 | variable is referenced. If it is false (the default), an empty string is | |
2813c06e | 15587 | substituted; if it is true, an error is generated. See section 43.19 for |
420a0d19 CE |
15588 | details of ACL variables. |
15589 | ||
2813c06e | 15590 | +------------------------------------------------------------------+ |
420a0d19 | 15591 | |strip_excess_angle_brackets|Use: main|Type: boolean|Default: false| |
2813c06e | 15592 | +------------------------------------------------------------------+ |
420a0d19 CE |
15593 | |
15594 | If this option is set, redundant pairs of angle brackets round "route-addr" | |
15595 | items in addresses are stripped. For example, <<xxx@a.b.c.d>> is treated as | |
15596 | <xxx@a.b.c.d>. If this is in the envelope and the message is passed on to | |
15597 | another MTA, the excess angle brackets are not passed on. If this option is not | |
15598 | set, multiple pairs of angle brackets cause a syntax error. | |
15599 | ||
2813c06e | 15600 | +---------------------------------------------------------+ |
420a0d19 | 15601 | |strip_trailing_dot|Use: main|Type: boolean|Default: false| |
2813c06e | 15602 | +---------------------------------------------------------+ |
420a0d19 CE |
15603 | |
15604 | If this option is set, a trailing dot at the end of a domain in an address is | |
15605 | ignored. If this is in the envelope and the message is passed on to another | |
15606 | MTA, the dot is not passed on. If this option is not set, a dot at the end of a | |
15607 | domain causes a syntax error. However, addresses in header lines are checked | |
15608 | only when an ACL requests header syntax checking. | |
15609 | ||
2813c06e | 15610 | +--------------------------------------------------------+ |
420a0d19 | 15611 | |syslog_duplication|Use: main|Type: boolean|Default: true| |
2813c06e | 15612 | +--------------------------------------------------------+ |
420a0d19 CE |
15613 | |
15614 | When Exim is logging to syslog, it writes the log lines for its three separate | |
15615 | logs at different syslog priorities so that they can in principle be separated | |
15616 | on the logging hosts. Some installations do not require this separation, and in | |
15617 | those cases, the duplication of certain log lines is a nuisance. If | |
15618 | syslog_duplication is set false, only one copy of any particular log line is | |
15619 | written to syslog. For lines that normally go to both the main log and the | |
15620 | reject log, the reject log version (possibly containing message header lines) | |
15621 | is written, at LOG_NOTICE priority. Lines that normally go to both the main and | |
15622 | the panic log are written at the LOG_ALERT priority. | |
15623 | ||
2813c06e | 15624 | +-----------------------------------------------------+ |
420a0d19 | 15625 | |syslog_facility|Use: main|Type: string|Default: unset| |
2813c06e | 15626 | +-----------------------------------------------------+ |
420a0d19 CE |
15627 | |
15628 | This option sets the syslog "facility" name, used when Exim is logging to | |
15629 | syslog. The value must be one of the strings "mail", "user", "news", "uucp", | |
15630 | "daemon", or "localx" where x is a digit between 0 and 7. If this option is | |
2813c06e CE |
15631 | unset, "mail" is used. See chapter 52 for details of Exim's logging. |
15632 | ||
15633 | +------------------------------------------------+ | |
15634 | |syslog_pid|Use: main|Type: boolean|Default: true| | |
15635 | +------------------------------------------------+ | |
420a0d19 | 15636 | |
2813c06e CE |
15637 | If syslog_pid is set false, the PID on Exim's log lines are omitted when these |
15638 | lines are sent to syslog. (Syslog normally prefixes the log lines with the PID | |
15639 | of the logging process automatically.) You need to enable the "+pid" log | |
15640 | selector item, if you want Exim to write it's PID into the logs.) See chapter | |
15641 | 52 for details of Exim's logging. | |
15642 | ||
15643 | +---------------------------------------------------------+ | |
420a0d19 | 15644 | |syslog_processname|Use: main|Type: string|Default: "exim"| |
2813c06e | 15645 | +---------------------------------------------------------+ |
420a0d19 CE |
15646 | |
15647 | This option sets the syslog "ident" name, used when Exim is logging to syslog. | |
2813c06e | 15648 | The value must be no longer than 32 characters. See chapter 52 for details of |
420a0d19 CE |
15649 | Exim's logging. |
15650 | ||
2813c06e | 15651 | +------------------------------------------------------+ |
420a0d19 | 15652 | |syslog_timestamp|Use: main|Type: boolean|Default: true| |
2813c06e | 15653 | +------------------------------------------------------+ |
420a0d19 CE |
15654 | |
15655 | If syslog_timestamp is set false, the timestamps on Exim's log lines are | |
2813c06e | 15656 | omitted when these lines are sent to syslog. See chapter 52 for details of |
420a0d19 CE |
15657 | Exim's logging. |
15658 | ||
2813c06e | 15659 | +----------------------------------------------------+ |
420a0d19 | 15660 | |system_filter|Use: main|Type: string*|Default: unset| |
2813c06e | 15661 | +----------------------------------------------------+ |
420a0d19 CE |
15662 | |
15663 | This option specifies an Exim filter file that is applied to all messages at | |
15664 | the start of each delivery attempt, before any routing is done. System filters | |
15665 | must be Exim filters; they cannot be Sieve filters. If the system filter | |
15666 | generates any deliveries to files or pipes, or any new mail messages, the | |
15667 | appropriate system_filter_..._transport option(s) must be set, to define which | |
2813c06e CE |
15668 | transports are to be used. Details of this facility are given in chapter 46. |
15669 | ||
15670 | A forced expansion failure results in no filter operation. | |
420a0d19 | 15671 | |
2813c06e | 15672 | +------------------------------------------------------------------------+ |
420a0d19 | 15673 | |system_filter_directory_transport|Use: main|Type: string*|Default: unset| |
2813c06e | 15674 | +------------------------------------------------------------------------+ |
420a0d19 CE |
15675 | |
15676 | This sets the name of the transport driver that is to be used when the save | |
15677 | command in a system message filter specifies a path ending in "/", implying | |
15678 | delivery of each message into a separate file in some directory. During the | |
15679 | delivery, the variable $address_file contains the path name. | |
15680 | ||
2813c06e | 15681 | +-------------------------------------------------------------------+ |
420a0d19 | 15682 | |system_filter_file_transport|Use: main|Type: string*|Default: unset| |
2813c06e | 15683 | +-------------------------------------------------------------------+ |
420a0d19 CE |
15684 | |
15685 | This sets the name of the transport driver that is to be used when the save | |
15686 | command in a system message filter specifies a path not ending in "/". During | |
15687 | the delivery, the variable $address_file contains the path name. | |
15688 | ||
2813c06e | 15689 | +---------------------------------------------------------+ |
420a0d19 | 15690 | |system_filter_group|Use: main|Type: string|Default: unset| |
2813c06e | 15691 | +---------------------------------------------------------+ |
420a0d19 CE |
15692 | |
15693 | This option is used only when system_filter_user is also set. It sets the gid | |
15694 | under which the system filter is run, overriding any gid that is associated | |
15695 | with the user. The value may be numerical or symbolic. | |
15696 | ||
2813c06e | 15697 | +-------------------------------------------------------------------+ |
420a0d19 | 15698 | |system_filter_pipe_transport|Use: main|Type: string*|Default: unset| |
2813c06e | 15699 | +-------------------------------------------------------------------+ |
420a0d19 CE |
15700 | |
15701 | This specifies the transport driver that is to be used when a pipe command is | |
15702 | used in a system filter. During the delivery, the variable $address_pipe | |
15703 | contains the pipe command. | |
15704 | ||
2813c06e | 15705 | +--------------------------------------------------------------------+ |
420a0d19 | 15706 | |system_filter_reply_transport|Use: main|Type: string*|Default: unset| |
2813c06e | 15707 | +--------------------------------------------------------------------+ |
420a0d19 CE |
15708 | |
15709 | This specifies the transport driver that is to be used when a mail command is | |
15710 | used in a system filter. | |
15711 | ||
2813c06e | 15712 | +--------------------------------------------------------+ |
420a0d19 | 15713 | |system_filter_user|Use: main|Type: string|Default: unset| |
2813c06e | 15714 | +--------------------------------------------------------+ |
420a0d19 CE |
15715 | |
15716 | If this option is set to root, the system filter is run in the main Exim | |
15717 | delivery process, as root. Otherwise, the system filter runs in a separate | |
15718 | process, as the given user, defaulting to the Exim run-time user. Unless the | |
15719 | string consists entirely of digits, it is looked up in the password data. | |
15720 | Failure to find the named user causes a configuration error. The gid is either | |
15721 | taken from the password data, or specified by system_filter_group. When the uid | |
15722 | is specified numerically, system_filter_group is required to be set. | |
15723 | ||
15724 | If the system filter generates any pipe, file, or reply deliveries, the uid | |
15725 | under which the filter is run is used when transporting them, unless a | |
15726 | transport option overrides. | |
15727 | ||
2813c06e | 15728 | +-------------------------------------------------+ |
420a0d19 | 15729 | |tcp_nodelay|Use: main|Type: boolean|Default: true| |
2813c06e | 15730 | +-------------------------------------------------+ |
420a0d19 CE |
15731 | |
15732 | If this option is set false, it stops the Exim daemon setting the TCP_NODELAY | |
15733 | option on its listening sockets. Setting TCP_NODELAY turns off the "Nagle | |
15734 | algorithm", which is a way of improving network performance in interactive | |
15735 | (character-by-character) situations. Turning it off should improve Exim's | |
15736 | performance a bit, so that is what happens by default. However, it appears that | |
15737 | some broken clients cannot cope, and time out. Hence this option. It affects | |
15738 | only those sockets that are set up for listening by the daemon. Sockets created | |
15739 | by the smtp transport for delivering mail always set TCP_NODELAY. | |
15740 | ||
2813c06e | 15741 | +-----------------------------------------------------+ |
420a0d19 | 15742 | |timeout_frozen_after|Use: main|Type: time|Default: 0s| |
2813c06e | 15743 | +-----------------------------------------------------+ |
420a0d19 CE |
15744 | |
15745 | If timeout_frozen_after is set to a time greater than zero, a frozen message of | |
15746 | any kind that has been on the queue for longer than the given time is | |
15747 | automatically cancelled at the next queue run. If the frozen message is a | |
15748 | bounce message, it is just discarded; otherwise, a bounce is sent to the | |
15749 | sender, in a similar manner to cancellation by the -Mg command line option. If | |
15750 | you want to timeout frozen bounce messages earlier than other kinds of frozen | |
15751 | message, see ignore_bounce_errors_after. | |
15752 | ||
15753 | Note: the default value of zero means no timeouts; with this setting, frozen | |
15754 | messages remain on the queue forever (except for any frozen bounce messages | |
15755 | that are released by ignore_bounce_errors_after). | |
15756 | ||
2813c06e | 15757 | +----------------------------------------------+ |
420a0d19 | 15758 | |timezone|Use: main|Type: string|Default: unset| |
2813c06e | 15759 | +----------------------------------------------+ |
420a0d19 CE |
15760 | |
15761 | The value of timezone is used to set the environment variable TZ while running | |
15762 | Exim (if it is different on entry). This ensures that all timestamps created by | |
15763 | Exim are in the required timezone. If you want all your timestamps to be in UTC | |
15764 | (aka GMT) you should set | |
15765 | ||
15766 | timezone = UTC | |
15767 | ||
15768 | The default value is taken from TIMEZONE_DEFAULT in Local/Makefile, or, if that | |
15769 | is not set, from the value of the TZ environment variable when Exim is built. | |
15770 | If timezone is set to the empty string, either at build or run time, any | |
15771 | existing TZ variable is removed from the environment when Exim runs. This is | |
15772 | appropriate behaviour for obtaining wall-clock time on some, but unfortunately | |
15773 | not all, operating systems. | |
15774 | ||
2813c06e CE |
15775 | +---------------------------------------------------------+ |
15776 | |tls_advertise_hosts|Use: main|Type: host list*|Default: *| | |
15777 | +---------------------------------------------------------+ | |
420a0d19 CE |
15778 | |
15779 | When Exim is built with support for TLS encrypted connections, the availability | |
15780 | of the STARTTLS command to set up an encrypted session is advertised in | |
15781 | response to EHLO only to those client hosts that match this option. See chapter | |
2813c06e CE |
15782 | 42 for details of Exim's support for TLS. Note that the default value requires |
15783 | that a certificate be supplied using the tls_certificate option. If TLS support | |
15784 | for incoming connections is not required the tls_advertise_hosts option should | |
15785 | be set empty. | |
420a0d19 | 15786 | |
2813c06e | 15787 | +------------------------------------------------------+ |
420a0d19 | 15788 | |tls_certificate|Use: main|Type: string*|Default: unset| |
2813c06e | 15789 | +------------------------------------------------------+ |
420a0d19 CE |
15790 | |
15791 | The value of this option is expanded, and must then be the absolute path to a | |
15792 | file which contains the server's certificates. The server's private key is also | |
2813c06e | 15793 | assumed to be in this file if tls_privatekey is unset. See chapter 42 for |
420a0d19 CE |
15794 | further details. |
15795 | ||
15796 | Note: The certificates defined by this option are used only when Exim is | |
15797 | receiving incoming messages as a server. If you want to supply certificates for | |
15798 | use when sending messages as a client, you must set the tls_certificate option | |
15799 | in the relevant smtp transport. | |
15800 | ||
15801 | If the option contains $tls_out_sni and Exim is built against OpenSSL, then if | |
15802 | the OpenSSL build supports TLS extensions and the TLS client sends the Server | |
2813c06e | 15803 | Name Indication extension, then this option and others documented in 42.10 will |
420a0d19 CE |
15804 | be re-expanded. |
15805 | ||
2813c06e CE |
15806 | If this option is unset or empty a fresh self-signed certificate will be |
15807 | generated for every connection. | |
15808 | ||
15809 | +----------------------------------------------+ | |
420a0d19 | 15810 | |tls_crl|Use: main|Type: string*|Default: unset| |
2813c06e | 15811 | +----------------------------------------------+ |
420a0d19 CE |
15812 | |
15813 | This option specifies a certificate revocation list. The expanded value must be | |
15814 | the name of a file that contains a CRL in PEM format. | |
15815 | ||
2813c06e | 15816 | See 42.10 for discussion of when this option might be re-expanded. |
420a0d19 | 15817 | |
2813c06e | 15818 | +-----------------------------------------------------+ |
420a0d19 | 15819 | |tls_dh_max_bits|Use: main|Type: integer|Default: 2236| |
2813c06e | 15820 | +-----------------------------------------------------+ |
420a0d19 CE |
15821 | |
15822 | The number of bits used for Diffie-Hellman key-exchange may be suggested by the | |
15823 | chosen TLS library. That value might prove to be too high for interoperability. | |
15824 | This option provides a maximum clamp on the value suggested, trading off | |
15825 | security for interoperability. | |
15826 | ||
15827 | The value must be at least 1024. | |
15828 | ||
15829 | The value 2236 was chosen because, at time of adding the option, it was the | |
15830 | hard-coded maximum value supported by the NSS cryptographic library, as used by | |
15831 | Thunderbird, while GnuTLS was suggesting 2432 bits as normal. | |
15832 | ||
15833 | If you prefer more security and are willing to break some clients, raise this | |
15834 | number. | |
15835 | ||
15836 | Note that the value passed to GnuTLS for *generating* a new prime may be a | |
15837 | little less than this figure, because GnuTLS is inexact and may produce a | |
15838 | larger prime than requested. | |
15839 | ||
2813c06e | 15840 | +--------------------------------------------------+ |
420a0d19 | 15841 | |tls_dhparam|Use: main|Type: string*|Default: unset| |
2813c06e | 15842 | +--------------------------------------------------+ |
420a0d19 CE |
15843 | |
15844 | The value of this option is expanded and indicates the source of DH parameters | |
15845 | to be used by Exim. | |
15846 | ||
2813c06e CE |
15847 | Note: The Exim Maintainers strongly recommend using a filename with |
15848 | site-generated local DH parameters, which has been supported across all | |
15849 | versions of Exim. The other specific constants available are a fallback so that | |
15850 | even when "unconfigured", Exim can offer Perfect Forward Secrecy in older | |
15851 | ciphersuites in TLS. | |
15852 | ||
15853 | If tls_dhparam is a filename starting with a "/", then it names a file from | |
15854 | which DH parameters should be loaded. If the file exists, it should hold a | |
15855 | PEM-encoded PKCS#3 representation of the DH prime. If the file does not exist, | |
15856 | for OpenSSL it is an error. For GnuTLS, Exim will attempt to create the file | |
15857 | and fill it with a generated DH prime. For OpenSSL, if the DH bit-count from | |
15858 | loading the file is greater than tls_dh_max_bits then it will be ignored, and | |
15859 | treated as though the tls_dhparam were set to "none". | |
420a0d19 CE |
15860 | |
15861 | If this option expands to the string "none", then no DH parameters will be | |
15862 | loaded by Exim. | |
15863 | ||
15864 | If this option expands to the string "historic" and Exim is using GnuTLS, then | |
15865 | Exim will attempt to load a file from inside the spool directory. If the file | |
2813c06e | 15866 | does not exist, Exim will attempt to create it. See section 42.3 for further |
420a0d19 CE |
15867 | details. |
15868 | ||
15869 | If Exim is using OpenSSL and this option is empty or unset, then Exim will load | |
2813c06e CE |
15870 | a default DH prime; the default is Exim-specific but lacks verifiable |
15871 | provenance. | |
15872 | ||
15873 | In older versions of Exim the default was the 2048 bit prime described in | |
15874 | section 2.2 of RFC 5114, "2048-bit MODP Group with 224-bit Prime Order | |
15875 | Subgroup", which in IKE is assigned number 23. | |
420a0d19 CE |
15876 | |
15877 | Otherwise, the option must expand to the name used by Exim for any of a number | |
2813c06e CE |
15878 | of DH primes specified in RFC 2409, RFC 3526, RFC 5114, RFC 7919, or from other |
15879 | sources. As names, Exim uses a standard specified name, else "ike" followed by | |
15880 | the number used by IKE, or "default" which corresponds to | |
15881 | "exim.dev.20160529.3". | |
420a0d19 | 15882 | |
2813c06e CE |
15883 | The available standard primes are: "ffdhe2048", "ffdhe3072", "ffdhe4096", |
15884 | "ffdhe6144", "ffdhe8192", "ike1", "ike2", "ike5", "ike14", "ike15", "ike16", | |
15885 | "ike17", "ike18", "ike22", "ike23" and "ike24". | |
15886 | ||
15887 | The available additional primes are: "exim.dev.20160529.1", | |
15888 | "exim.dev.20160529.2" and "exim.dev.20160529.3". | |
420a0d19 CE |
15889 | |
15890 | Some of these will be too small to be accepted by clients. Some may be too | |
2813c06e CE |
15891 | large to be accepted by clients. The open cryptographic community has |
15892 | suspicions about the integrity of some of the later IKE values, which led into | |
15893 | RFC7919 providing new fixed constants (the "ffdhe" identifiers). | |
15894 | ||
15895 | At this point, all of the "ike" values should be considered obsolete; they're | |
15896 | still in Exim to avoid breaking unusual configurations, but are candidates for | |
15897 | removal the next time we have backwards-incompatible changes. | |
420a0d19 CE |
15898 | |
15899 | The TLS protocol does not negotiate an acceptable size for this; clients tend | |
15900 | to hard-drop connections if what is offered by the server is unacceptable, | |
15901 | whether too large or too small, and there's no provision for the client to tell | |
15902 | the server what these constraints are. Thus, as a server operator, you need to | |
15903 | make an educated guess as to what is most likely to work for your userbase. | |
15904 | ||
15905 | Some known size constraints suggest that a bit-size in the range 2048 to 2236 | |
15906 | is most likely to maximise interoperability. The upper bound comes from | |
15907 | applications using the Mozilla Network Security Services (NSS) library, which | |
15908 | used to set its "DH_MAX_P_BITS" upper-bound to 2236. This affects many mail | |
15909 | user agents (MUAs). The lower bound comes from Debian installs of Exim4 prior | |
15910 | to the 4.80 release, as Debian used to patch Exim to raise the minimum | |
15911 | acceptable bound from 1024 to 2048. | |
15912 | ||
2813c06e CE |
15913 | +---------------------------------------------------+ |
15914 | |tls_eccurve|Use: main|Type: string*|Default: "auto"| | |
15915 | +---------------------------------------------------+ | |
15916 | ||
15917 | This option selects a EC curve for use by Exim. | |
15918 | ||
15919 | After expansion it must contain a valid EC curve parameter, such as | |
15920 | "prime256v1", "secp384r1", or "P-512". Consult your OpenSSL manual for valid | |
15921 | selections. | |
15922 | ||
15923 | For OpenSSL versions before (and not including) 1.0.2, the string "auto" | |
15924 | selects "prime256v1". For more recent OpenSSL versions "auto" tells the library | |
15925 | to choose. | |
15926 | ||
15927 | If the option expands to an empty string, no EC curves will be enabled. | |
15928 | ||
15929 | +----------------------------------------------------+ | |
420a0d19 | 15930 | |tls_ocsp_file|Use: main|Type: string*|Default: unset| |
2813c06e | 15931 | +----------------------------------------------------+ |
420a0d19 CE |
15932 | |
15933 | This option must if set expand to the absolute path to a file which contains a | |
15934 | current status proof for the server's certificate, as obtained from the | |
15935 | Certificate Authority. | |
15936 | ||
2813c06e CE |
15937 | Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later). |
15938 | ||
15939 | +---------------------------------------------------------------+ | |
420a0d19 | 15940 | |tls_on_connect_ports|Use: main|Type: string list|Default: unset| |
2813c06e | 15941 | +---------------------------------------------------------------+ |
420a0d19 CE |
15942 | |
15943 | This option specifies a list of incoming SSMTP (aka SMTPS) ports that should | |
15944 | operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately | |
15945 | set up without waiting for the client to issue a STARTTLS command. For further | |
15946 | details, see section 13.4. | |
15947 | ||
2813c06e | 15948 | +-----------------------------------------------------+ |
420a0d19 | 15949 | |tls_privatekey|Use: main|Type: string*|Default: unset| |
2813c06e | 15950 | +-----------------------------------------------------+ |
420a0d19 CE |
15951 | |
15952 | The value of this option is expanded, and must then be the absolute path to a | |
15953 | file which contains the server's private key. If this option is unset, or if | |
15954 | the expansion is forced to fail, or the result is an empty string, the private | |
15955 | key is assumed to be in the same file as the server's certificates. See chapter | |
2813c06e | 15956 | 42 for further details. |
420a0d19 | 15957 | |
2813c06e | 15958 | See 42.10 for discussion of when this option might be re-expanded. |
420a0d19 | 15959 | |
2813c06e | 15960 | +---------------------------------------------------------+ |
420a0d19 | 15961 | |tls_remember_esmtp|Use: main|Type: boolean|Default: false| |
2813c06e | 15962 | +---------------------------------------------------------+ |
420a0d19 CE |
15963 | |
15964 | If this option is set true, Exim violates the RFCs by remembering that it is in | |
15965 | "esmtp" state after successfully negotiating a TLS session. This provides | |
15966 | support for broken clients that fail to send a new EHLO after starting a TLS | |
15967 | session. | |
15968 | ||
2813c06e | 15969 | +----------------------------------------------------------+ |
420a0d19 | 15970 | |tls_require_ciphers|Use: main|Type: string*|Default: unset| |
2813c06e | 15971 | +----------------------------------------------------------+ |
420a0d19 CE |
15972 | |
15973 | This option controls which ciphers can be used for incoming TLS connections. | |
15974 | The smtp transport has an option of the same name for controlling outgoing | |
15975 | connections. This option is expanded for each connection, so can be varied for | |
15976 | different clients if required. The value of this option must be a list of | |
15977 | permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control | |
15978 | in somewhat different ways. If GnuTLS is being used, the client controls the | |
2813c06e CE |
15979 | preference order of the available ciphers. Details are given in sections 42.4 |
15980 | and 42.5. | |
420a0d19 | 15981 | |
2813c06e | 15982 | +--------------------------------------------------------------+ |
420a0d19 | 15983 | |tls_try_verify_hosts|Use: main|Type: host list*|Default: unset| |
2813c06e | 15984 | +--------------------------------------------------------------+ |
420a0d19 CE |
15985 | |
15986 | See tls_verify_hosts below. | |
15987 | ||
2813c06e CE |
15988 | +---------------------------------------------------------------+ |
15989 | |tls_verify_certificates|Use: main|Type: string*|Default: system| | |
15990 | +---------------------------------------------------------------+ | |
420a0d19 | 15991 | |
2813c06e CE |
15992 | The value of this option is expanded, and must then be either the word "system" |
15993 | or the absolute path to a file or directory containing permitted certificates | |
15994 | for clients that match tls_verify_hosts or tls_try_verify_hosts. | |
15995 | ||
15996 | The "system" value for the option will use a system default location compiled | |
15997 | into the SSL library. This is not available for GnuTLS versions preceding | |
15998 | 3.0.20, and will be taken as empty; an explicit location must be specified. | |
15999 | ||
16000 | The use of a directory for the option value is not available for GnuTLS | |
16001 | versions preceding 3.3.6 and a single file must be used. | |
16002 | ||
16003 | With OpenSSL the certificates specified explicitly either by file or directory | |
16004 | are added to those given by the system default location. | |
420a0d19 CE |
16005 | |
16006 | These certificates should be for the certificate authorities trusted, rather | |
16007 | than the public cert of individual clients. With both OpenSSL and GnuTLS, if | |
16008 | the value is a file then the certificates are sent by Exim as a server to | |
16009 | connecting clients, defining the list of accepted certificate authorities. Thus | |
2813c06e CE |
16010 | the values defined should be considered public data. To avoid this, use the |
16011 | explicit directory version. | |
420a0d19 | 16012 | |
2813c06e | 16013 | See 42.10 for discussion of when this option might be re-expanded. |
420a0d19 CE |
16014 | |
16015 | A forced expansion failure or setting to an empty string is equivalent to being | |
16016 | unset. | |
16017 | ||
2813c06e | 16018 | +----------------------------------------------------------+ |
420a0d19 | 16019 | |tls_verify_hosts|Use: main|Type: host list*|Default: unset| |
2813c06e | 16020 | +----------------------------------------------------------+ |
420a0d19 CE |
16021 | |
16022 | This option, along with tls_try_verify_hosts, controls the checking of | |
16023 | certificates from clients. The expected certificates are defined by | |
16024 | tls_verify_certificates, which must be set. A configuration error occurs if | |
16025 | either tls_verify_hosts or tls_try_verify_hosts is set and | |
16026 | tls_verify_certificates is not set. | |
16027 | ||
16028 | Any client that matches tls_verify_hosts is constrained by | |
16029 | tls_verify_certificates. When the client initiates a TLS session, it must | |
16030 | present one of the listed certificates. If it does not, the connection is | |
16031 | aborted. Warning: Including a host in tls_verify_hosts does not require the | |
16032 | host to use TLS. It can still send SMTP commands through unencrypted | |
16033 | connections. Forcing a client to use TLS has to be done separately using an ACL | |
16034 | to reject inappropriate commands when the connection is not encrypted. | |
16035 | ||
16036 | A weaker form of checking is provided by tls_try_verify_hosts. If a client | |
16037 | matches this option (but not tls_verify_hosts), Exim requests a certificate and | |
16038 | checks it against tls_verify_certificates, but does not abort the connection if | |
16039 | there is no certificate or if it does not match. This state can be detected in | |
16040 | an ACL, which makes it possible to implement policies such as "accept for relay | |
16041 | only if a verified certificate has been received, but accept for local delivery | |
16042 | if encrypted, even without a verified certificate". | |
16043 | ||
16044 | Client hosts that match neither of these lists are not asked to present | |
16045 | certificates. | |
16046 | ||
2813c06e | 16047 | +----------------------------------------------------------+ |
420a0d19 | 16048 | |trusted_groups|Use: main|Type: string list*|Default: unset| |
2813c06e | 16049 | +----------------------------------------------------------+ |
420a0d19 CE |
16050 | |
16051 | This option is expanded just once, at the start of Exim's processing. If this | |
16052 | option is set, any process that is running in one of the listed groups, or | |
16053 | which has one of them as a supplementary group, is trusted. The groups can be | |
16054 | specified numerically or by name. See section 5.2 for details of what trusted | |
16055 | callers are permitted to do. If neither trusted_groups nor trusted_users is | |
16056 | set, only root and the Exim user are trusted. | |
16057 | ||
2813c06e | 16058 | +---------------------------------------------------------+ |
420a0d19 | 16059 | |trusted_users|Use: main|Type: string list*|Default: unset| |
2813c06e | 16060 | +---------------------------------------------------------+ |
420a0d19 CE |
16061 | |
16062 | This option is expanded just once, at the start of Exim's processing. If this | |
16063 | option is set, any process that is running as one of the listed users is | |
16064 | trusted. The users can be specified numerically or by name. See section 5.2 for | |
16065 | details of what trusted callers are permitted to do. If neither trusted_groups | |
16066 | nor trusted_users is set, only root and the Exim user are trusted. | |
16067 | ||
2813c06e | 16068 | +----------------------------------------------------+ |
420a0d19 | 16069 | |unknown_login|Use: main|Type: string*|Default: unset| |
2813c06e | 16070 | +----------------------------------------------------+ |
420a0d19 CE |
16071 | |
16072 | This is a specialized feature for use in unusual configurations. By default, if | |
16073 | the uid of the caller of Exim cannot be looked up using getpwuid(), Exim gives | |
16074 | up. The unknown_login option can be used to set a login name to be used in this | |
16075 | circumstance. It is expanded, so values like user$caller_uid can be set. When | |
16076 | unknown_login is used, the value of unknown_username is used for the user's | |
16077 | real name (gecos field), unless this has been set by the -F option. | |
16078 | ||
2813c06e | 16079 | +------------------------------------------------------+ |
420a0d19 | 16080 | |unknown_username|Use: main|Type: string|Default: unset| |
2813c06e | 16081 | +------------------------------------------------------+ |
420a0d19 CE |
16082 | |
16083 | See unknown_login. | |
16084 | ||
2813c06e | 16085 | +-----------------------------------------------------------------+ |
420a0d19 | 16086 | |untrusted_set_sender|Use: main|Type: address list*|Default: unset| |
2813c06e | 16087 | +-----------------------------------------------------------------+ |
420a0d19 CE |
16088 | |
16089 | When an untrusted user submits a message to Exim using the standard input, Exim | |
16090 | normally creates an envelope sender address from the user's login and the | |
16091 | default qualification domain. Data from the -f option (for setting envelope | |
16092 | senders on non-SMTP messages) or the SMTP MAIL command (if -bs or -bS is used) | |
16093 | is ignored. | |
16094 | ||
16095 | However, untrusted users are permitted to set an empty envelope sender address, | |
16096 | to declare that a message should never generate any bounces. For example: | |
16097 | ||
16098 | exim -f '<>' user@domain.example | |
16099 | ||
16100 | The untrusted_set_sender option allows you to permit untrusted users to set | |
16101 | other envelope sender addresses in a controlled way. When it is set, untrusted | |
16102 | users are allowed to set envelope sender addresses that match any of the | |
16103 | patterns in the list. Like all address lists, the string is expanded. The | |
16104 | identity of the user is in $sender_ident, so you can, for example, restrict | |
16105 | users to setting senders that start with their login ids followed by a hyphen | |
16106 | by a setting like this: | |
16107 | ||
16108 | untrusted_set_sender = ^$sender_ident- | |
16109 | ||
16110 | If you want to allow untrusted users to set envelope sender addresses without | |
16111 | restriction, you can use | |
16112 | ||
16113 | untrusted_set_sender = * | |
16114 | ||
16115 | The untrusted_set_sender option applies to all forms of local input, but only | |
16116 | to the setting of the envelope sender. It does not permit untrusted users to | |
16117 | use the other options which trusted user can use to override message | |
16118 | parameters. Furthermore, it does not stop Exim from removing an existing | |
16119 | Sender: header in the message, or from adding a Sender: header if necessary. | |
16120 | See local_sender_retain and local_from_check for ways of overriding these | |
2813c06e | 16121 | actions. The handling of the Sender: header is also described in section 47.16. |
420a0d19 CE |
16122 | |
16123 | The log line for a message's arrival shows the envelope sender following "<=". | |
16124 | For local messages, the user's login always follows, after "U=". In -bp | |
16125 | displays, and in the Exim monitor, if an untrusted user sets an envelope sender | |
16126 | address, the user's login is shown in parentheses after the sender address. | |
16127 | ||
2813c06e | 16128 | +-----------------------------------------------------------+ |
420a0d19 | 16129 | |uucp_from_pattern|Use: main|Type: string|Default: see below| |
2813c06e | 16130 | +-----------------------------------------------------------+ |
420a0d19 CE |
16131 | |
16132 | Some applications that pass messages to an MTA via a command line interface use | |
16133 | an initial line starting with "From " to pass the envelope sender. In | |
16134 | particular, this is used by UUCP software. Exim recognizes such a line by means | |
16135 | of a regular expression that is set in uucp_from_pattern. When the pattern | |
16136 | matches, the sender address is constructed by expanding the contents of | |
16137 | uucp_from_sender, provided that the caller of Exim is a trusted user. The | |
16138 | default pattern recognizes lines in the following two forms: | |
16139 | ||
16140 | From ph10 Fri Jan 5 12:35 GMT 1996 | |
16141 | From ph10 Fri, 7 Jan 97 14:00:00 GMT | |
16142 | ||
16143 | The pattern can be seen by running | |
16144 | ||
16145 | exim -bP uucp_from_pattern | |
16146 | ||
16147 | It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit | |
16148 | year in the second case. The first word after "From " is matched in the regular | |
16149 | expression by a parenthesized subpattern. The default value for | |
16150 | uucp_from_sender is "$1", which therefore just uses this first word ("ph10" in | |
16151 | the example above) as the message's sender. See also ignore_fromline_hosts. | |
16152 | ||
2813c06e | 16153 | +------------------------------------------------------+ |
420a0d19 | 16154 | |uucp_from_sender|Use: main|Type: string*|Default: "$1"| |
2813c06e | 16155 | +------------------------------------------------------+ |
420a0d19 CE |
16156 | |
16157 | See uucp_from_pattern above. | |
16158 | ||
2813c06e | 16159 | +-------------------------------------------------------+ |
420a0d19 | 16160 | |warn_message_file|Use: main|Type: string|Default: unset| |
2813c06e | 16161 | +-------------------------------------------------------+ |
420a0d19 CE |
16162 | |
16163 | This option defines a template file containing paragraphs of text to be used | |
16164 | for constructing the warning message which is sent by Exim when a message has | |
16165 | been on the queue for a specified amount of time, as specified by delay_warning | |
2813c06e | 16166 | . Details of the file's contents are given in chapter 49. See also |
420a0d19 CE |
16167 | bounce_message_file. |
16168 | ||
2813c06e | 16169 | +-----------------------------------------------------+ |
420a0d19 | 16170 | |write_rejectlog|Use: main|Type: boolean|Default: true| |
2813c06e | 16171 | +-----------------------------------------------------+ |
420a0d19 CE |
16172 | |
16173 | If this option is set false, Exim no longer writes anything to the reject log. | |
2813c06e | 16174 | See chapter 52 for details of what Exim writes to its logs. |
420a0d19 CE |
16175 | |
16176 | ||
16177 | ||
16178 | =============================================================================== | |
16179 | 15. GENERIC OPTIONS FOR ROUTERS | |
16180 | ||
16181 | This chapter describes the generic options that apply to all routers. Those | |
16182 | that are preconditions are marked with ** in the "use" field. | |
16183 | ||
16184 | For a general description of how a router operates, see sections 3.10 and 3.12. | |
16185 | The latter specifies the order in which the preconditions are tested. The order | |
16186 | of expansion of the options that provide data for a transport is: errors_to, | |
16187 | headers_add, headers_remove, transport. | |
16188 | ||
2813c06e | 16189 | +------------------------------------------------------+ |
420a0d19 | 16190 | |address_data|Use: routers|Type: string*|Default: unset| |
2813c06e | 16191 | +------------------------------------------------------+ |
420a0d19 CE |
16192 | |
16193 | The string is expanded just before the router is run, that is, after all the | |
16194 | precondition tests have succeeded. If the expansion is forced to fail, the | |
16195 | router declines, the value of address_data remains unchanged, and the more | |
16196 | option controls what happens next. Other expansion failures cause delivery of | |
16197 | the address to be deferred. | |
16198 | ||
16199 | When the expansion succeeds, the value is retained with the address, and can be | |
16200 | accessed using the variable $address_data in the current router, subsequent | |
16201 | routers, and the eventual transport. | |
16202 | ||
16203 | Warning: If the current or any subsequent router is a redirect router that runs | |
16204 | a user's filter file, the contents of $address_data are accessible in the | |
16205 | filter. This is not normally a problem, because such data is usually either not | |
16206 | confidential or it "belongs" to the current user, but if you do put | |
16207 | confidential data into $address_data you need to remember this point. | |
16208 | ||
16209 | Even if the router declines or passes, the value of $address_data remains with | |
16210 | the address, though it can be changed by another address_data setting on a | |
16211 | subsequent router. If a router generates child addresses, the value of | |
16212 | $address_data propagates to them. This also applies to the special kind of | |
16213 | "child" that is generated by a router with the unseen option. | |
16214 | ||
16215 | The idea of address_data is that you can use it to look up a lot of data for | |
16216 | the address once, and then pick out parts of the data later. For example, you | |
16217 | could use a single LDAP lookup to return a string of the form | |
16218 | ||
16219 | uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward | |
16220 | ||
16221 | In the transport you could pick out the mailbox by a setting such as | |
16222 | ||
16223 | file = ${extract{mailbox}{$address_data}} | |
16224 | ||
16225 | This makes the configuration file less messy, and also reduces the number of | |
16226 | lookups (though Exim does cache lookups). | |
16227 | ||
16228 | The address_data facility is also useful as a means of passing information from | |
16229 | one router to another, and from a router to a transport. In addition, if | |
16230 | $address_data is set by a router when verifying a recipient address from an | |
16231 | ACL, it remains available for use in the rest of the ACL statement. After | |
16232 | verifying a sender, the value is transferred to $sender_address_data. | |
16233 | ||
2813c06e | 16234 | +-------------------------------------------------------+ |
420a0d19 | 16235 | |address_test|Use: routers**|Type: boolean|Default: true| |
2813c06e | 16236 | +-------------------------------------------------------+ |
420a0d19 CE |
16237 | |
16238 | If this option is set false, the router is skipped when routing is being tested | |
16239 | by means of the -bt command line option. This can be a convenience when your | |
16240 | first router sends messages to an external scanner, because it saves you having | |
16241 | to set the "already scanned" indicator when testing real address routing. | |
16242 | ||
2813c06e | 16243 | +--------------------------------------------------------------+ |
420a0d19 | 16244 | |cannot_route_message|Use: routers|Type: string*|Default: unset| |
2813c06e | 16245 | +--------------------------------------------------------------+ |
420a0d19 CE |
16246 | |
16247 | This option specifies a text message that is used when an address cannot be | |
16248 | routed because Exim has run out of routers. The default message is "Unrouteable | |
16249 | address". This option is useful only on routers that have more set false, or on | |
16250 | the very last router in a configuration, because the value that is used is | |
16251 | taken from the last router that is considered. This includes a router that is | |
16252 | skipped because its preconditions are not met, as well as a router that | |
16253 | declines. For example, using the default configuration, you could put: | |
16254 | ||
16255 | cannot_route_message = Remote domain not found in DNS | |
16256 | ||
16257 | on the first router, which is a dnslookup router with more set false, and | |
16258 | ||
16259 | cannot_route_message = Unknown local user | |
16260 | ||
16261 | on the final router that checks for local users. If string expansion fails for | |
16262 | this option, the default message is used. Unless the expansion failure was | |
16263 | explicitly forced, a message about the failure is written to the main and panic | |
16264 | logs, in addition to the normal message about the routing failure. | |
16265 | ||
2813c06e | 16266 | +------------------------------------------------------------+ |
420a0d19 | 16267 | |caseful_local_part|Use: routers|Type: boolean|Default: false| |
2813c06e | 16268 | +------------------------------------------------------------+ |
420a0d19 CE |
16269 | |
16270 | By default, routers handle the local parts of addresses in a case-insensitive | |
16271 | manner, though the actual case is preserved for transmission with the message. | |
16272 | If you want the case of letters to be significant in a router, you must set | |
16273 | this option true. For individual router options that contain address or local | |
16274 | part lists (for example, local_parts), case-sensitive matching can be turned on | |
16275 | by "+caseful" as a list item. See section 10.20 for more details. | |
16276 | ||
16277 | The value of the $local_part variable is forced to lower case while a router is | |
16278 | running unless caseful_local_part is set. When a router assigns an address to a | |
16279 | transport, the value of $local_part when the transport runs is the same as it | |
16280 | was in the router. Similarly, when a router generates child addresses by | |
16281 | aliasing or forwarding, the values of $original_local_part and | |
16282 | $parent_local_part are those that were used by the redirecting router. | |
16283 | ||
16284 | This option applies to the processing of an address by a router. When a | |
16285 | recipient address is being processed in an ACL, there is a separate control | |
16286 | modifier that can be used to specify case-sensitive processing within the ACL | |
2813c06e | 16287 | (see section 43.22). |
420a0d19 | 16288 | |
2813c06e | 16289 | +------------------------------------------------------------+ |
420a0d19 | 16290 | |check_local_user|Use: routers**|Type: boolean|Default: false| |
2813c06e | 16291 | +------------------------------------------------------------+ |
420a0d19 CE |
16292 | |
16293 | When this option is true, Exim checks that the local part of the recipient | |
16294 | address (with affixes removed if relevant) is the name of an account on the | |
16295 | local system. The check is done by calling the getpwnam() function rather than | |
16296 | trying to read /etc/passwd directly. This means that other methods of holding | |
16297 | password data (such as NIS) are supported. If the local part is a local user, | |
16298 | $home is set from the password data, and can be tested in other preconditions | |
16299 | that are evaluated after this one (the order of evaluation is given in section | |
16300 | 3.12). However, the value of $home can be overridden by router_home_directory. | |
16301 | If the local part is not a local user, the router is skipped. | |
16302 | ||
16303 | If you want to check that the local part is either the name of a local user or | |
16304 | matches something else, you cannot combine check_local_user with a setting of | |
16305 | local_parts, because that specifies the logical and of the two conditions. | |
16306 | However, you can use a passwd lookup in a local_parts setting to achieve this. | |
16307 | For example: | |
16308 | ||
16309 | local_parts = passwd;$local_part : lsearch;/etc/other/users | |
16310 | ||
16311 | Note, however, that the side effects of check_local_user (such as setting up a | |
16312 | home directory) do not occur when a passwd lookup is used in a local_parts (or | |
16313 | any other) precondition. | |
16314 | ||
2813c06e | 16315 | +-----------------------------------------------------+ |
420a0d19 | 16316 | |condition|Use: routers**|Type: string*|Default: unset| |
2813c06e | 16317 | +-----------------------------------------------------+ |
420a0d19 CE |
16318 | |
16319 | This option specifies a general precondition test that has to succeed for the | |
16320 | router to be called. The condition option is the last precondition to be | |
16321 | evaluated (see section 3.12). The string is expanded, and if the result is a | |
16322 | forced failure, or an empty string, or one of the strings "0" or "no" or | |
16323 | "false" (checked without regard to the case of the letters), the router is | |
16324 | skipped, and the address is offered to the next one. | |
16325 | ||
16326 | If the result is any other value, the router is run (as this is the last | |
16327 | precondition to be evaluated, all the other preconditions must be true). | |
16328 | ||
16329 | This option is unusual in that multiple condition options may be present. All | |
16330 | condition options must succeed. | |
16331 | ||
16332 | The condition option provides a means of applying custom conditions to the | |
16333 | running of routers. Note that in the case of a simple conditional expansion, | |
16334 | the default expansion values are exactly what is wanted. For example: | |
16335 | ||
16336 | condition = ${if >{$message_age}{600}} | |
16337 | ||
16338 | Because of the default behaviour of the string expansion, this is equivalent to | |
16339 | ||
16340 | condition = ${if >{$message_age}{600}{true}{}} | |
16341 | ||
16342 | A multiple condition example, which succeeds: | |
16343 | ||
16344 | condition = ${if >{$message_age}{600}} | |
16345 | condition = ${if !eq{${lc:$local_part}}{postmaster}} | |
16346 | condition = foobar | |
16347 | ||
16348 | If the expansion fails (other than forced failure) delivery is deferred. Some | |
16349 | of the other precondition options are common special cases that could in fact | |
16350 | be specified using condition. | |
16351 | ||
2813c06e CE |
16352 | Historical note: We have condition on ACLs and on Routers. Routers are far |
16353 | older, and use one set of semantics. ACLs are newer and when they were created, | |
16354 | the ACL condition process was given far stricter parse semantics. The bool{} | |
16355 | expansion condition uses the same rules as ACLs. The bool_lax{} expansion | |
16356 | condition uses the same rules as Routers. More pointedly, the bool_lax{} was | |
16357 | written to match the existing Router rules processing behavior. | |
16358 | ||
16359 | This is best illustrated in an example: | |
16360 | ||
16361 | # If used in an ACL condition will fail with a syntax error, but | |
16362 | # in a router condition any extra characters are treated as a string | |
16363 | ||
16364 | $ exim -be '${if eq {${lc:GOOGLE.com}} {google.com}} {yes} {no}}' | |
16365 | true {yes} {no}} | |
16366 | ||
16367 | $ exim -be '${if eq {${lc:WHOIS.com}} {google.com}} {yes} {no}}' | |
16368 | {yes} {no}} | |
16369 | ||
16370 | In each example above, the if statement actually ends after "{google.com}}". | |
16371 | Since no true or false braces were defined, the default if behavior is to | |
16372 | return a boolean true or a null answer (which evaluates to false). The rest of | |
16373 | the line is then treated as a string. So the first example resulted in the | |
16374 | boolean answer "true" with the string " {yes} {no}}" appended to it. The second | |
16375 | example resulted in the null output (indicating false) with the string " {yes} | |
16376 | {no}}" appended to it. | |
16377 | ||
16378 | In fact you can put excess forward braces in too. In the router condition, | |
16379 | Exim's parser only looks for "{" symbols when they mean something, like after a | |
16380 | "$" or when required as part of a conditional. But otherwise "{" and "}" are | |
16381 | treated as ordinary string characters. | |
16382 | ||
16383 | Thus, in a Router, the above expansion strings will both always evaluate true, | |
16384 | as the result of expansion is a non-empty string which doesn't match an | |
16385 | explicit false value. This can be tricky to debug. By contrast, in an ACL | |
16386 | either of those strings will always result in an expansion error because the | |
16387 | result doesn't look sufficiently boolean. | |
16388 | ||
16389 | +-----------------------------------------------------+ | |
420a0d19 | 16390 | |debug_print|Use: routers|Type: string*|Default: unset| |
2813c06e | 16391 | +-----------------------------------------------------+ |
420a0d19 CE |
16392 | |
16393 | If this option is set and debugging is enabled (see the -d command line option) | |
16394 | or in address-testing mode (see the -bt command line option), the string is | |
16395 | expanded and included in the debugging output. If expansion of the string | |
16396 | fails, the error message is written to the debugging output, and Exim carries | |
16397 | on processing. This option is provided to help with checking out the values of | |
16398 | variables and so on when debugging router configurations. For example, if a | |
16399 | condition option appears not to be working, debug_print can be used to output | |
16400 | the variables it references. The output happens after checks for domains, | |
16401 | local_parts, and check_local_user but before any other preconditions are | |
16402 | tested. A newline is added to the text if it does not end with one. The | |
16403 | variable $router_name contains the name of the router. | |
16404 | ||
2813c06e | 16405 | +---------------------------------------------------------+ |
420a0d19 | 16406 | |disable_logging|Use: routers|Type: boolean|Default: false| |
2813c06e | 16407 | +---------------------------------------------------------+ |
420a0d19 CE |
16408 | |
16409 | If this option is set true, nothing is logged for any routing errors or for any | |
16410 | deliveries caused by this router. You should not set this option unless you | |
16411 | really, really know what you are doing. See also the generic transport option | |
16412 | of the same name. | |
16413 | ||
2813c06e CE |
16414 | +---------------------------------------------------------------------+ |
16415 | |dnssec_request_domains|Use: routers|Type: domain list*|Default: unset| | |
16416 | +---------------------------------------------------------------------+ | |
16417 | ||
16418 | DNS lookups for domains matching dnssec_request_domains will be done with the | |
16419 | dnssec request bit set. This applies to all of the SRV, MX, AAAA, A lookup | |
16420 | sequence. | |
16421 | ||
16422 | +---------------------------------------------------------------------+ | |
16423 | |dnssec_require_domains|Use: routers|Type: domain list*|Default: unset| | |
16424 | +---------------------------------------------------------------------+ | |
16425 | ||
16426 | DNS lookups for domains matching dnssec_require_domains will be done with the | |
16427 | dnssec request bit set. Any returns not having the Authenticated Data bit (AD | |
16428 | bit) set will be ignored and logged as a host-lookup failure. This applies to | |
16429 | all of the SRV, MX, AAAA, A lookup sequence. | |
16430 | ||
16431 | +--------------------------------------------------------+ | |
420a0d19 | 16432 | |domains|Use: routers**|Type: domain list*|Default: unset| |
2813c06e | 16433 | +--------------------------------------------------------+ |
420a0d19 CE |
16434 | |
16435 | If this option is set, the router is skipped unless the current domain matches | |
16436 | the list. If the match is achieved by means of a file lookup, the data that the | |
16437 | lookup returned for the domain is placed in $domain_data for use in string | |
16438 | expansions of the driver's private options. See section 3.12 for a list of the | |
16439 | order in which preconditions are evaluated. | |
16440 | ||
2813c06e | 16441 | +-----------------------------------------------+ |
420a0d19 | 16442 | |driver|Use: routers|Type: string|Default: unset| |
2813c06e | 16443 | +-----------------------------------------------+ |
420a0d19 CE |
16444 | |
16445 | This option must always be set. It specifies which of the available routers is | |
16446 | to be used. | |
16447 | ||
2813c06e CE |
16448 | +-----------------------------------------------------+ |
16449 | |dsn_lasthop|Use: routers|Type: boolean|Default: false| | |
16450 | +-----------------------------------------------------+ | |
16451 | ||
16452 | If this option is set true, and extended DSN (RFC3461) processing is in effect, | |
16453 | Exim will not pass on DSN requests to downstream DSN-aware hosts but will | |
16454 | instead send a success DSN as if the next hop does not support DSN. Not | |
16455 | effective on redirect routers. | |
16456 | ||
16457 | +---------------------------------------------------+ | |
420a0d19 | 16458 | |errors_to|Use: routers|Type: string*|Default: unset| |
2813c06e | 16459 | +---------------------------------------------------+ |
420a0d19 CE |
16460 | |
16461 | If a router successfully handles an address, it may assign the address to a | |
16462 | transport for delivery or it may generate child addresses. In both cases, if | |
16463 | there is a delivery problem during later processing, the resulting bounce | |
16464 | message is sent to the address that results from expanding this string, | |
16465 | provided that the address verifies successfully. The errors_to option is | |
16466 | expanded before headers_add, headers_remove, and transport. | |
16467 | ||
16468 | The errors_to setting associated with an address can be overridden if it | |
16469 | subsequently passes through other routers that have their own errors_to | |
16470 | settings, or if the message is delivered by a transport with a return_path | |
16471 | setting. | |
16472 | ||
16473 | If errors_to is unset, or the expansion is forced to fail, or the result of the | |
16474 | expansion fails to verify, the errors address associated with the incoming | |
16475 | address is used. At top level, this is the envelope sender. A non-forced | |
16476 | expansion failure causes delivery to be deferred. | |
16477 | ||
16478 | If an address for which errors_to has been set ends up being delivered over | |
16479 | SMTP, the envelope sender for that delivery is the errors_to value, so that any | |
16480 | bounces that are generated by other MTAs on the delivery route are also sent | |
16481 | there. You can set errors_to to the empty string by either of these settings: | |
16482 | ||
16483 | errors_to = | |
16484 | errors_to = "" | |
16485 | ||
16486 | An expansion item that yields an empty string has the same effect. If you do | |
16487 | this, a locally detected delivery error for addresses processed by this router | |
16488 | no longer gives rise to a bounce message; the error is discarded. If the | |
16489 | address is delivered to a remote host, the return path is set to "<>", unless | |
16490 | overridden by the return_path option on the transport. | |
16491 | ||
16492 | If for some reason you want to discard local errors, but use a non-empty MAIL | |
16493 | command for remote delivery, you can preserve the original return path in | |
16494 | $address_data in the router, and reinstate it in the transport by setting | |
16495 | return_path. | |
16496 | ||
16497 | The most common use of errors_to is to direct mailing list bounces to the | |
2813c06e CE |
16498 | manager of the list, as described in section 50.2, or to implement VERP |
16499 | (Variable Envelope Return Paths) (see section 50.6). | |
420a0d19 | 16500 | |
2813c06e | 16501 | +-----------------------------------------------+ |
420a0d19 | 16502 | |expn|Use: routers**|Type: boolean|Default: true| |
2813c06e | 16503 | +-----------------------------------------------+ |
420a0d19 CE |
16504 | |
16505 | If this option is turned off, the router is skipped when testing an address as | |
16506 | a result of processing an SMTP EXPN command. You might, for example, want to | |
16507 | turn it off on a router for users' .forward files, while leaving it on for the | |
16508 | system alias file. See section 3.12 for a list of the order in which | |
16509 | preconditions are evaluated. | |
16510 | ||
2813c06e | 16511 | The use of the SMTP EXPN command is controlled by an ACL (see chapter 43). When |
420a0d19 CE |
16512 | Exim is running an EXPN command, it is similar to testing an address with -bt. |
16513 | Compare VRFY, whose counterpart is -bv. | |
16514 | ||
2813c06e | 16515 | +-----------------------------------------------------+ |
420a0d19 | 16516 | |fail_verify|Use: routers|Type: boolean|Default: false| |
2813c06e | 16517 | +-----------------------------------------------------+ |
420a0d19 CE |
16518 | |
16519 | Setting this option has the effect of setting both fail_verify_sender and | |
16520 | fail_verify_recipient to the same value. | |
16521 | ||
2813c06e | 16522 | +---------------------------------------------------------------+ |
420a0d19 | 16523 | |fail_verify_recipient|Use: routers|Type: boolean|Default: false| |
2813c06e | 16524 | +---------------------------------------------------------------+ |
420a0d19 CE |
16525 | |
16526 | If this option is true and an address is accepted by this router when verifying | |
16527 | a recipient, verification fails. | |
16528 | ||
2813c06e | 16529 | +------------------------------------------------------------+ |
420a0d19 | 16530 | |fail_verify_sender|Use: routers|Type: boolean|Default: false| |
2813c06e | 16531 | +------------------------------------------------------------+ |
420a0d19 CE |
16532 | |
16533 | If this option is true and an address is accepted by this router when verifying | |
16534 | a sender, verification fails. | |
16535 | ||
2813c06e | 16536 | +------------------------------------------------------------+ |
420a0d19 | 16537 | |fallback_hosts|Use: routers|Type: string list|Default: unset| |
2813c06e | 16538 | +------------------------------------------------------------+ |
420a0d19 CE |
16539 | |
16540 | String expansion is not applied to this option. The argument must be a | |
16541 | colon-separated list of host names or IP addresses. The list separator can be | |
2813c06e | 16542 | changed (see section 6.20), and a port can be specified with each name or |
420a0d19 CE |
16543 | address. In fact, the format of each item is exactly the same as defined for |
16544 | the list of hosts in a manualroute router (see section 20.5). | |
16545 | ||
16546 | If a router queues an address for a remote transport, this host list is | |
16547 | associated with the address, and used instead of the transport's fallback host | |
16548 | list. If hosts_randomize is set on the transport, the order of the list is | |
16549 | randomized for each use. See the fallback_hosts option of the smtp transport | |
16550 | for further details. | |
16551 | ||
2813c06e | 16552 | +---------------------------------------------------+ |
420a0d19 | 16553 | |group|Use: routers|Type: string*|Default: see below| |
2813c06e | 16554 | +---------------------------------------------------+ |
420a0d19 CE |
16555 | |
16556 | When a router queues an address for a transport, and the transport does not | |
16557 | specify a group, the group given here is used when running the delivery | |
16558 | process. The group may be specified numerically or by name. If expansion fails, | |
16559 | the error is logged and delivery is deferred. The default is unset, unless | |
16560 | check_local_user is set, when the default is taken from the password | |
16561 | information. See also initgroups and user and the discussion in chapter 23. | |
16562 | ||
2813c06e | 16563 | +---------------------------------------------------+ |
420a0d19 | 16564 | |headers_add|Use: routers|Type: list*|Default: unset| |
2813c06e CE |
16565 | +---------------------------------------------------+ |
16566 | ||
16567 | This option specifies a list of text headers, newline-separated (by default, | |
16568 | changeable in the usual way), that is associated with any addresses that are | |
16569 | accepted by the router. Each item is separately expanded, at routing time. | |
16570 | However, this option has no effect when an address is just being verified. The | |
16571 | way in which the text is used to add header lines at transport time is | |
16572 | described in section 47.17. New header lines are not actually added until the | |
16573 | message is in the process of being transported. This means that references to | |
16574 | header lines in string expansions in the transport's configuration do not "see" | |
16575 | the added header lines. | |
420a0d19 CE |
16576 | |
16577 | The headers_add option is expanded after errors_to, but before headers_remove | |
16578 | and transport. If an item is empty, or if an item expansion is forced to fail, | |
16579 | the item has no effect. Other expansion failures are treated as configuration | |
16580 | errors. | |
16581 | ||
16582 | Unlike most options, headers_add can be specified multiple times for a router; | |
16583 | all listed headers are added. | |
16584 | ||
16585 | Warning 1: The headers_add option cannot be used for a redirect router that has | |
16586 | the one_time option set. | |
16587 | ||
16588 | Warning 2: If the unseen option is set on the router, all header additions are | |
16589 | deleted when the address is passed on to subsequent routers. For a redirect | |
16590 | router, if a generated address is the same as the incoming address, this can | |
16591 | lead to duplicate addresses with different header modifications. Exim does not | |
16592 | do duplicate deliveries (except, in certain circumstances, to pipes -- see | |
16593 | section 22.7), but it is undefined which of the duplicates is discarded, so | |
16594 | this ambiguous situation should be avoided. The repeat_use option of the | |
16595 | redirect router may be of help. | |
16596 | ||
2813c06e | 16597 | +------------------------------------------------------+ |
420a0d19 | 16598 | |headers_remove|Use: routers|Type: list*|Default: unset| |
2813c06e CE |
16599 | +------------------------------------------------------+ |
16600 | ||
16601 | This option specifies a list of text headers, colon-separated (by default, | |
16602 | changeable in the usual way), that is associated with any addresses that are | |
16603 | accepted by the router. Each item is separately expanded, at routing time. | |
16604 | However, this option has no effect when an address is just being verified. The | |
16605 | way in which the text is used to remove header lines at transport time is | |
16606 | described in section 47.17. Header lines are not actually removed until the | |
16607 | message is in the process of being transported. This means that references to | |
16608 | header lines in string expansions in the transport's configuration still "see" | |
16609 | the original header lines. | |
420a0d19 CE |
16610 | |
16611 | The headers_remove option is expanded after errors_to and headers_add, but | |
16612 | before transport. If an item expansion is forced to fail, the item has no | |
16613 | effect. Other expansion failures are treated as configuration errors. | |
16614 | ||
16615 | Unlike most options, headers_remove can be specified multiple times for a | |
16616 | router; all listed headers are removed. | |
16617 | ||
16618 | Warning 1: The headers_remove option cannot be used for a redirect router that | |
16619 | has the one_time option set. | |
16620 | ||
16621 | Warning 2: If the unseen option is set on the router, all header removal | |
16622 | requests are deleted when the address is passed on to subsequent routers, and | |
16623 | this can lead to problems with duplicates -- see the similar warning for | |
16624 | headers_add above. | |
16625 | ||
2813c06e CE |
16626 | Warning 3: Because of the separate expansion of the list items, items that |
16627 | contain a list separator must have it doubled. To avoid this, change the list | |
16628 | separator (6.21). | |
16629 | ||
16630 | +----------------------------------------------------------------+ | |
420a0d19 | 16631 | |ignore_target_hosts|Use: routers|Type: host list*|Default: unset| |
2813c06e | 16632 | +----------------------------------------------------------------+ |
420a0d19 CE |
16633 | |
16634 | Although this option is a host list, it should normally contain IP address | |
16635 | entries rather than names. If any host that is looked up by the router has an | |
16636 | IP address that matches an item in this list, Exim behaves as if that IP | |
16637 | address did not exist. This option allows you to cope with rogue DNS entries | |
16638 | like | |
16639 | ||
16640 | remote.domain.example. A 127.0.0.1 | |
16641 | ||
16642 | by setting | |
16643 | ||
16644 | ignore_target_hosts = 127.0.0.1 | |
16645 | ||
16646 | on the relevant router. If all the hosts found by a dnslookup router are | |
16647 | discarded in this way, the router declines. In a conventional configuration, an | |
16648 | attempt to mail to such a domain would normally provoke the "unrouteable | |
16649 | domain" error, and an attempt to verify an address in the domain would fail. | |
16650 | Similarly, if ignore_target_hosts is set on an ipliteral router, the router | |
16651 | declines if presented with one of the listed addresses. | |
16652 | ||
16653 | You can use this option to disable the use of IPv4 or IPv6 for mail delivery by | |
16654 | means of the first or the second of the following settings, respectively: | |
16655 | ||
16656 | ignore_target_hosts = 0.0.0.0/0 | |
16657 | ignore_target_hosts = <; 0::0/0 | |
16658 | ||
16659 | The pattern in the first line matches all IPv4 addresses, whereas the pattern | |
16660 | in the second line matches all IPv6 addresses. | |
16661 | ||
16662 | This option may also be useful for ignoring link-local and site-local IPv6 | |
16663 | addresses. Because, like all host lists, the value of ignore_target_hosts is | |
16664 | expanded before use as a list, it is possible to make it dependent on the | |
16665 | domain that is being routed. | |
16666 | ||
16667 | During its expansion, $host_address is set to the IP address that is being | |
16668 | checked. | |
16669 | ||
2813c06e | 16670 | +----------------------------------------------------+ |
420a0d19 | 16671 | |initgroups|Use: routers|Type: boolean|Default: false| |
2813c06e | 16672 | +----------------------------------------------------+ |
420a0d19 CE |
16673 | |
16674 | If the router queues an address for a transport, and this option is true, and | |
16675 | the uid supplied by the router is not overridden by the transport, the | |
16676 | initgroups() function is called when running the transport to ensure that any | |
16677 | additional groups associated with the uid are set up. See also group and user | |
16678 | and the discussion in chapter 23. | |
16679 | ||
2813c06e | 16680 | +-----------------------------------------------------------------+ |
420a0d19 | 16681 | |local_part_prefix|Use: routers**|Type: string list|Default: unset| |
2813c06e | 16682 | +-----------------------------------------------------------------+ |
420a0d19 CE |
16683 | |
16684 | If this option is set, the router is skipped unless the local part starts with | |
16685 | one of the given strings, or local_part_prefix_optional is true. See section | |
16686 | 3.12 for a list of the order in which preconditions are evaluated. | |
16687 | ||
16688 | The list is scanned from left to right, and the first prefix that matches is | |
16689 | used. A limited form of wildcard is available; if the prefix begins with an | |
16690 | asterisk, it matches the longest possible sequence of arbitrary characters at | |
16691 | the start of the local part. An asterisk should therefore always be followed by | |
16692 | some character that does not occur in normal local parts. Wildcarding can be | |
2813c06e | 16693 | used to set up multiple user mailboxes, as described in section 50.8. |
420a0d19 CE |
16694 | |
16695 | During the testing of the local_parts option, and while the router is running, | |
16696 | the prefix is removed from the local part, and is available in the expansion | |
16697 | variable $local_part_prefix. When a message is being delivered, if the router | |
16698 | accepts the address, this remains true during subsequent delivery by a | |
16699 | transport. In particular, the local part that is transmitted in the RCPT | |
16700 | command for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default. | |
16701 | This behaviour can be overridden by setting rcpt_include_affixes true on the | |
16702 | relevant transport. | |
16703 | ||
16704 | When an address is being verified, local_part_prefix affects only the behaviour | |
16705 | of the router. If the callout feature of verification is in use, this means | |
16706 | that the full address, including the prefix, will be used during the callout. | |
16707 | ||
16708 | The prefix facility is commonly used to handle local parts of the form | |
16709 | owner-something. Another common use is to support local parts of the form | |
16710 | real-username to bypass a user's .forward file - helpful when trying to tell a | |
16711 | user their forwarding is broken - by placing a router like this one immediately | |
16712 | before the router that handles .forward files: | |
16713 | ||
16714 | real_localuser: | |
16715 | driver = accept | |
16716 | local_part_prefix = real- | |
16717 | check_local_user | |
16718 | transport = local_delivery | |
16719 | ||
16720 | For security, it would probably be a good idea to restrict the use of this | |
16721 | router to locally-generated messages, using a condition such as this: | |
16722 | ||
16723 | condition = ${if match {$sender_host_address}\ | |
16724 | {\N^(|127\.0\.0\.1)$\N}} | |
16725 | ||
16726 | If both local_part_prefix and local_part_suffix are set for a router, both | |
16727 | conditions must be met if not optional. Care must be taken if wildcards are | |
16728 | used in both a prefix and a suffix on the same router. Different separator | |
16729 | characters must be used to avoid ambiguity. | |
16730 | ||
2813c06e | 16731 | +--------------------------------------------------------------------+ |
420a0d19 | 16732 | |local_part_prefix_optional|Use: routers|Type: boolean|Default: false| |
2813c06e | 16733 | +--------------------------------------------------------------------+ |
420a0d19 CE |
16734 | |
16735 | See local_part_prefix above. | |
16736 | ||
2813c06e | 16737 | +-----------------------------------------------------------------+ |
420a0d19 | 16738 | |local_part_suffix|Use: routers**|Type: string list|Default: unset| |
2813c06e | 16739 | +-----------------------------------------------------------------+ |
420a0d19 CE |
16740 | |
16741 | This option operates in the same way as local_part_prefix, except that the | |
16742 | local part must end (rather than start) with the given string, the | |
16743 | local_part_suffix_optional option determines whether the suffix is mandatory, | |
16744 | and the wildcard * character, if present, must be the last character of the | |
16745 | suffix. This option facility is commonly used to handle local parts of the form | |
16746 | something-request and multiple user mailboxes of the form username-foo. | |
16747 | ||
2813c06e | 16748 | +--------------------------------------------------------------------+ |
420a0d19 | 16749 | |local_part_suffix_optional|Use: routers|Type: boolean|Default: false| |
2813c06e | 16750 | +--------------------------------------------------------------------+ |
420a0d19 CE |
16751 | |
16752 | See local_part_suffix above. | |
16753 | ||
2813c06e | 16754 | +----------------------------------------------------------------+ |
420a0d19 | 16755 | |local_parts|Use: routers**|Type: local part list*|Default: unset| |
2813c06e | 16756 | +----------------------------------------------------------------+ |
420a0d19 CE |
16757 | |
16758 | The router is run only if the local part of the address matches the list. See | |
16759 | section 3.12 for a list of the order in which preconditions are evaluated, and | |
16760 | section 10.21 for a discussion of local part lists. Because the string is | |
16761 | expanded, it is possible to make it depend on the domain, for example: | |
16762 | ||
16763 | local_parts = dbm;/usr/local/specials/$domain | |
16764 | ||
16765 | If the match is achieved by a lookup, the data that the lookup returned for the | |
16766 | local part is placed in the variable $local_part_data for use in expansions of | |
16767 | the router's private options. You might use this option, for example, if you | |
16768 | have a large number of local virtual domains, and you want to send all | |
16769 | postmaster mail to the same place without having to set up an alias in each | |
16770 | virtual domain: | |
16771 | ||
16772 | postmaster: | |
16773 | driver = redirect | |
16774 | local_parts = postmaster | |
16775 | data = postmaster@real.domain.example | |
16776 | ||
2813c06e | 16777 | +----------------------------------------------------------+ |
420a0d19 | 16778 | |log_as_local|Use: routers|Type: boolean|Default: see below| |
2813c06e | 16779 | +----------------------------------------------------------+ |
420a0d19 CE |
16780 | |
16781 | Exim has two logging styles for delivery, the idea being to make local | |
16782 | deliveries stand out more visibly from remote ones. In the "local" style, the | |
16783 | recipient address is given just as the local part, without a domain. The use of | |
16784 | this style is controlled by this option. It defaults to true for the accept | |
16785 | router, and false for all the others. This option applies only when a router | |
16786 | assigns an address to a transport. It has no effect on routers that redirect | |
16787 | addresses. | |
16788 | ||
2813c06e | 16789 | +----------------------------------------------+ |
420a0d19 | 16790 | |more|Use: routers|Type: boolean*|Default: true| |
2813c06e | 16791 | +----------------------------------------------+ |
420a0d19 CE |
16792 | |
16793 | The result of string expansion for this option must be a valid boolean value, | |
16794 | that is, one of the strings "yes", "no", "true", or "false". Any other result | |
16795 | causes an error, and delivery is deferred. If the expansion is forced to fail, | |
16796 | the default value for the option (true) is used. Other failures cause delivery | |
16797 | to be deferred. | |
16798 | ||
16799 | If this option is set false, and the router declines to handle the address, no | |
16800 | further routers are tried, routing fails, and the address is bounced. However, | |
16801 | if the router explicitly passes an address to the following router by means of | |
16802 | the setting | |
16803 | ||
16804 | self = pass | |
16805 | ||
16806 | or otherwise, the setting of more is ignored. Also, the setting of more does | |
16807 | not affect the behaviour if one of the precondition tests fails. In that case, | |
16808 | the address is always passed to the next router. | |
16809 | ||
16810 | Note that address_data is not considered to be a precondition. If its expansion | |
16811 | is forced to fail, the router declines, and the value of more controls what | |
16812 | happens next. | |
16813 | ||
2813c06e | 16814 | +---------------------------------------------------------+ |
420a0d19 | 16815 | |pass_on_timeout|Use: routers|Type: boolean|Default: false| |
2813c06e | 16816 | +---------------------------------------------------------+ |
420a0d19 CE |
16817 | |
16818 | If a router times out during a host lookup, it normally causes deferral of the | |
16819 | address. If pass_on_timeout is set, the address is passed on to the next | |
16820 | router, overriding no_more. This may be helpful for systems that are | |
16821 | intermittently connected to the Internet, or those that want to pass to a smart | |
16822 | host any messages that cannot immediately be delivered. | |
16823 | ||
16824 | There are occasional other temporary errors that can occur while doing DNS | |
16825 | lookups. They are treated in the same way as a timeout, and this option applies | |
16826 | to all of them. | |
16827 | ||
2813c06e | 16828 | +----------------------------------------------------+ |
420a0d19 | 16829 | |pass_router|Use: routers|Type: string|Default: unset| |
2813c06e | 16830 | +----------------------------------------------------+ |
420a0d19 CE |
16831 | |
16832 | Routers that recognize the generic self option (dnslookup, ipliteral, and | |
16833 | manualroute) are able to return "pass", forcing routing to continue, and | |
16834 | overriding a false setting of more. When one of these routers returns "pass", | |
16835 | the address is normally handed on to the next router in sequence. This can be | |
16836 | changed by setting pass_router to the name of another router. However (unlike | |
16837 | redirect_router) the named router must be below the current router, to avoid | |
16838 | loops. Note that this option applies only to the special case of "pass". It | |
16839 | does not apply when a router returns "decline" because it cannot handle an | |
16840 | address. | |
16841 | ||
2813c06e | 16842 | +--------------------------------------------------------+ |
420a0d19 | 16843 | |redirect_router|Use: routers|Type: string|Default: unset| |
2813c06e | 16844 | +--------------------------------------------------------+ |
420a0d19 CE |
16845 | |
16846 | Sometimes an administrator knows that it is pointless to reprocess addresses | |
16847 | generated from alias or forward files with the same router again. For example, | |
16848 | if an alias file translates real names into login ids there is no point | |
16849 | searching the alias file a second time, especially if it is a large file. | |
16850 | ||
16851 | The redirect_router option can be set to the name of any router instance. It | |
16852 | causes the routing of any generated addresses to start at the named router | |
16853 | instead of at the first router. This option has no effect if the router in | |
16854 | which it is set does not generate new addresses. | |
16855 | ||
2813c06e | 16856 | +--------------------------------------------------------------+ |
420a0d19 | 16857 | |require_files|Use: routers**|Type: string list*|Default: unset| |
2813c06e | 16858 | +--------------------------------------------------------------+ |
420a0d19 CE |
16859 | |
16860 | This option provides a general mechanism for predicating the running of a | |
16861 | router on the existence or non-existence of certain files or directories. | |
16862 | Before running a router, as one of its precondition tests, Exim works its way | |
16863 | through the require_files list, expanding each item separately. | |
16864 | ||
16865 | Because the list is split before expansion, any colons in expansion items must | |
16866 | be doubled, or the facility for using a different list separator must be used. | |
16867 | If any expansion is forced to fail, the item is ignored. Other expansion | |
16868 | failures cause routing of the address to be deferred. | |
16869 | ||
16870 | If any expanded string is empty, it is ignored. Otherwise, except as described | |
16871 | below, each string must be a fully qualified file path, optionally preceded by | |
16872 | "!". The paths are passed to the stat() function to test for the existence of | |
16873 | the files or directories. The router is skipped if any paths not preceded by "! | |
16874 | " do not exist, or if any paths preceded by "!" do exist. | |
16875 | ||
16876 | If stat() cannot determine whether a file exists or not, delivery of the | |
16877 | message is deferred. This can happen when NFS-mounted filesystems are | |
16878 | unavailable. | |
16879 | ||
16880 | This option is checked after the domains, local_parts, and senders options, so | |
16881 | you cannot use it to check for the existence of a file in which to look up a | |
16882 | domain, local part, or sender. (See section 3.12 for a full list of the order | |
16883 | in which preconditions are evaluated.) However, as these options are all | |
16884 | expanded, you can use the exists expansion condition to make such tests. The | |
16885 | require_files option is intended for checking files that the router may be | |
16886 | going to use internally, or which are needed by a transport (for example | |
16887 | .procmailrc). | |
16888 | ||
16889 | During delivery, the stat() function is run as root, but there is a facility | |
16890 | for some checking of the accessibility of a file by another user. This is not a | |
16891 | proper permissions check, but just a "rough" check that operates as follows: | |
16892 | ||
16893 | If an item in a require_files list does not contain any forward slash | |
16894 | characters, it is taken to be the user (and optional group, separated by a | |
16895 | comma) to be checked for subsequent files in the list. If no group is specified | |
16896 | but the user is specified symbolically, the gid associated with the uid is | |
16897 | used. For example: | |
16898 | ||
16899 | require_files = mail:/some/file | |
16900 | require_files = $local_part:$home/.procmailrc | |
16901 | ||
16902 | If a user or group name in a require_files list does not exist, the | |
16903 | require_files condition fails. | |
16904 | ||
16905 | Exim performs the check by scanning along the components of the file path, and | |
16906 | checking the access for the given uid and gid. It checks for "x" access on | |
16907 | directories, and "r" access on the final file. Note that this means that file | |
16908 | access control lists, if the operating system has them, are ignored. | |
16909 | ||
16910 | Warning 1: When the router is being run to verify addresses for an incoming | |
16911 | SMTP message, Exim is not running as root, but under its own uid. This may | |
16912 | affect the result of a require_files check. In particular, stat() may yield the | |
16913 | error EACCES ("Permission denied"). This means that the Exim user is not | |
16914 | permitted to read one of the directories on the file's path. | |
16915 | ||
16916 | Warning 2: Even when Exim is running as root while delivering a message, stat() | |
16917 | can yield EACCES for a file in an NFS directory that is mounted without root | |
16918 | access. In this case, if a check for access by a particular user is requested, | |
16919 | Exim creates a subprocess that runs as that user, and tries the check again in | |
16920 | that process. | |
16921 | ||
16922 | The default action for handling an unresolved EACCES is to consider it to be | |
16923 | caused by a configuration error, and routing is deferred because the existence | |
16924 | or non-existence of the file cannot be determined. However, in some | |
16925 | circumstances it may be desirable to treat this condition as if the file did | |
16926 | not exist. If the file name (or the exclamation mark that precedes the file | |
16927 | name for non-existence) is preceded by a plus sign, the EACCES error is treated | |
16928 | as if the file did not exist. For example: | |
16929 | ||
16930 | require_files = +/some/file | |
16931 | ||
16932 | If the router is not an essential part of verification (for example, it handles | |
16933 | users' .forward files), another solution is to set the verify option false so | |
16934 | that the router is skipped when verifying. | |
16935 | ||
2813c06e | 16936 | +------------------------------------------------------------------+ |
420a0d19 | 16937 | |retry_use_local_part|Use: routers|Type: boolean|Default: see below| |
2813c06e | 16938 | +------------------------------------------------------------------+ |
420a0d19 CE |
16939 | |
16940 | When a delivery suffers a temporary routing failure, a retry record is created | |
16941 | in Exim's hints database. For addresses whose routing depends only on the | |
16942 | domain, the key for the retry record should not involve the local part, but for | |
16943 | other addresses, both the domain and the local part should be included. | |
16944 | Usually, remote routing is of the former kind, and local routing is of the | |
16945 | latter kind. | |
16946 | ||
16947 | This option controls whether the local part is used to form the key for retry | |
16948 | hints for addresses that suffer temporary errors while being handled by this | |
16949 | router. The default value is true for any router that has check_local_user set, | |
16950 | and false otherwise. Note that this option does not apply to hints keys for | |
16951 | transport delays; they are controlled by a generic transport option of the same | |
16952 | name. | |
16953 | ||
16954 | The setting of retry_use_local_part applies only to the router on which it | |
16955 | appears. If the router generates child addresses, they are routed | |
16956 | independently; this setting does not become attached to them. | |
16957 | ||
2813c06e | 16958 | +---------------------------------------------------------------+ |
420a0d19 | 16959 | |router_home_directory|Use: routers|Type: string*|Default: unset| |
2813c06e | 16960 | +---------------------------------------------------------------+ |
420a0d19 CE |
16961 | |
16962 | This option sets a home directory for use while the router is running. (Compare | |
16963 | transport_home_directory, which sets a home directory for later transporting.) | |
16964 | In particular, if used on a redirect router, this option sets a value for $home | |
16965 | while a filter is running. The value is expanded; forced expansion failure | |
16966 | causes the option to be ignored - other failures cause the router to defer. | |
16967 | ||
16968 | Expansion of router_home_directory happens immediately after the | |
16969 | check_local_user test (if configured), before any further expansions take | |
16970 | place. (See section 3.12 for a list of the order in which preconditions are | |
16971 | evaluated.) While the router is running, router_home_directory overrides the | |
16972 | value of $home that came from check_local_user. | |
16973 | ||
16974 | When a router accepts an address and assigns it to a local transport (including | |
16975 | the cases when a redirect router generates a pipe, file, or autoreply | |
16976 | delivery), the home directory setting for the transport is taken from the first | |
16977 | of these values that is set: | |
16978 | ||
16979 | * The home_directory option on the transport; | |
16980 | ||
16981 | * The transport_home_directory option on the router; | |
16982 | ||
16983 | * The password data if check_local_user is set on the router; | |
16984 | ||
16985 | * The router_home_directory option on the router. | |
16986 | ||
16987 | In other words, router_home_directory overrides the password data for the | |
16988 | router, but not for the transport. | |
16989 | ||
2813c06e | 16990 | +----------------------------------------------+ |
420a0d19 | 16991 | |self|Use: routers|Type: string|Default: freeze| |
2813c06e | 16992 | +----------------------------------------------+ |
420a0d19 CE |
16993 | |
16994 | This option applies to those routers that use a recipient address to find a | |
16995 | list of remote hosts. Currently, these are the dnslookup, ipliteral, and | |
16996 | manualroute routers. Certain configurations of the queryprogram router can also | |
16997 | specify a list of remote hosts. Usually such routers are configured to send the | |
16998 | message to a remote host via an smtp transport. The self option specifies what | |
16999 | happens when the first host on the list turns out to be the local host. The way | |
17000 | in which Exim checks for the local host is described in section 13.8. | |
17001 | ||
17002 | Normally this situation indicates either an error in Exim's configuration (for | |
17003 | example, the router should be configured not to process this domain), or an | |
17004 | error in the DNS (for example, the MX should not point to this host). For this | |
17005 | reason, the default action is to log the incident, defer the address, and | |
17006 | freeze the message. The following alternatives are provided for use in special | |
17007 | cases: | |
17008 | ||
17009 | defer | |
17010 | ||
17011 | Delivery of the message is tried again later, but the message is not | |
17012 | frozen. | |
17013 | ||
17014 | reroute: <domain> | |
17015 | ||
17016 | The domain is changed to the given domain, and the address is passed back | |
17017 | to be reprocessed by the routers. No rewriting of headers takes place. This | |
17018 | behaviour is essentially a redirection. | |
17019 | ||
17020 | reroute: rewrite: <domain> | |
17021 | ||
17022 | The domain is changed to the given domain, and the address is passed back | |
17023 | to be reprocessed by the routers. Any headers that contain the original | |
17024 | domain are rewritten. | |
17025 | ||
17026 | pass | |
17027 | ||
17028 | The router passes the address to the next router, or to the router named in | |
17029 | the pass_router option if it is set. This overrides no_more. During | |
17030 | subsequent routing and delivery, the variable $self_hostname contains the | |
17031 | name of the local host that the router encountered. This can be used to | |
17032 | distinguish between different cases for hosts with multiple names. The | |
17033 | combination | |
17034 | ||
17035 | self = pass | |
17036 | no_more | |
17037 | ||
17038 | ensures that only those addresses that routed to the local host are passed | |
17039 | on. Without no_more, addresses that were declined for other reasons would | |
17040 | also be passed to the next router. | |
17041 | ||
17042 | fail | |
17043 | ||
17044 | Delivery fails and an error report is generated. | |
17045 | ||
17046 | send | |
17047 | ||
17048 | The anomaly is ignored and the address is queued for the transport. This | |
17049 | setting should be used with extreme caution. For an smtp transport, it | |
17050 | makes sense only in cases where the program that is listening on the SMTP | |
17051 | port is not this version of Exim. That is, it must be some other MTA, or | |
17052 | Exim with a different configuration file that handles the domain in another | |
17053 | way. | |
17054 | ||
2813c06e | 17055 | +---------------------------------------------------------+ |
420a0d19 | 17056 | |senders|Use: routers**|Type: address list*|Default: unset| |
2813c06e | 17057 | +---------------------------------------------------------+ |
420a0d19 CE |
17058 | |
17059 | If this option is set, the router is skipped unless the message's sender | |
17060 | address matches something on the list. See section 3.12 for a list of the order | |
17061 | in which preconditions are evaluated. | |
17062 | ||
17063 | There are issues concerning verification when the running of routers is | |
17064 | dependent on the sender. When Exim is verifying the address in an errors_to | |
17065 | setting, it sets the sender to the null string. When using the -bt option to | |
17066 | check a configuration file, it is necessary also to use the -f option to set an | |
17067 | appropriate sender. For incoming mail, the sender is unset when verifying the | |
17068 | sender, but is available when verifying any recipients. If the SMTP VRFY | |
17069 | command is enabled, it must be used after MAIL if the sender address matters. | |
17070 | ||
2813c06e | 17071 | +--------------------------------------------------------------+ |
420a0d19 | 17072 | |translate_ip_address|Use: routers|Type: string*|Default: unset| |
2813c06e | 17073 | +--------------------------------------------------------------+ |
420a0d19 CE |
17074 | |
17075 | There exist some rare networking situations (for example, packet radio) where | |
17076 | it is helpful to be able to translate IP addresses generated by normal routing | |
17077 | mechanisms into other IP addresses, thus performing a kind of manual IP | |
17078 | routing. This should be done only if the normal IP routing of the TCP/IP stack | |
17079 | is inadequate or broken. Because this is an extremely uncommon requirement, the | |
17080 | code to support this option is not included in the Exim binary unless | |
17081 | SUPPORT_TRANSLATE_IP_ADDRESS=yes is set in Local/Makefile. | |
17082 | ||
17083 | The translate_ip_address string is expanded for every IP address generated by | |
17084 | the router, with the generated address set in $host_address. If the expansion | |
17085 | is forced to fail, no action is taken. For any other expansion error, delivery | |
17086 | of the message is deferred. If the result of the expansion is an IP address, | |
17087 | that replaces the original address; otherwise the result is assumed to be a | |
17088 | host name - this is looked up using gethostbyname() (or getipnodebyname() when | |
17089 | available) to produce one or more replacement IP addresses. For example, to | |
17090 | subvert all IP addresses in some specific networks, this could be added to a | |
17091 | router: | |
17092 | ||
17093 | translate_ip_address = \ | |
17094 | ${lookup{${mask:$host_address/26}}lsearch{/some/file}\ | |
17095 | {$value}fail}} | |
17096 | ||
17097 | The file would contain lines like | |
17098 | ||
17099 | 10.2.3.128/26 some.host | |
17100 | 10.8.4.34/26 10.44.8.15 | |
17101 | ||
17102 | You should not make use of this facility unless you really understand what you | |
17103 | are doing. | |
17104 | ||
2813c06e | 17105 | +---------------------------------------------------+ |
420a0d19 | 17106 | |transport|Use: routers|Type: string*|Default: unset| |
2813c06e | 17107 | +---------------------------------------------------+ |
420a0d19 CE |
17108 | |
17109 | This option specifies the transport to be used when a router accepts an address | |
17110 | and sets it up for delivery. A transport is never needed if a router is used | |
17111 | only for verification. The value of the option is expanded at routing time, | |
17112 | after the expansion of errors_to, headers_add, and headers_remove, and result | |
17113 | must be the name of one of the configured transports. If it is not, delivery is | |
17114 | deferred. | |
17115 | ||
17116 | The transport option is not used by the redirect router, but it does have some | |
17117 | private options that set up transports for pipe and file deliveries (see | |
17118 | chapter 22). | |
17119 | ||
2813c06e | 17120 | +---------------------------------------------------------------------+ |
420a0d19 | 17121 | |transport_current_directory|Use: routers|Type: string*|Default: unset| |
2813c06e | 17122 | +---------------------------------------------------------------------+ |
420a0d19 CE |
17123 | |
17124 | This option associates a current directory with any address that is routed to a | |
17125 | local transport. This can happen either because a transport is explicitly | |
17126 | configured for the router, or because it generates a delivery to a file or a | |
17127 | pipe. During the delivery process (that is, at transport time), this option | |
17128 | string is expanded and is set as the current directory, unless overridden by a | |
17129 | setting on the transport. If the expansion fails for any reason, including | |
17130 | forced failure, an error is logged, and delivery is deferred. See chapter 23 | |
17131 | for details of the local delivery environment. | |
17132 | ||
2813c06e | 17133 | +----------------------------------------------------------------------+ |
420a0d19 | 17134 | |transport_home_directory|Use: routers|Type: string*|Default: see below| |
2813c06e | 17135 | +----------------------------------------------------------------------+ |
420a0d19 CE |
17136 | |
17137 | This option associates a home directory with any address that is routed to a | |
17138 | local transport. This can happen either because a transport is explicitly | |
17139 | configured for the router, or because it generates a delivery to a file or a | |
17140 | pipe. During the delivery process (that is, at transport time), the option | |
17141 | string is expanded and is set as the home directory, unless overridden by a | |
17142 | setting of home_directory on the transport. If the expansion fails for any | |
17143 | reason, including forced failure, an error is logged, and delivery is deferred. | |
17144 | ||
17145 | If the transport does not specify a home directory, and | |
17146 | transport_home_directory is not set for the router, the home directory for the | |
17147 | transport is taken from the password data if check_local_user is set for the | |
17148 | router. Otherwise it is taken from router_home_directory if that option is set; | |
17149 | if not, no home directory is set for the transport. | |
17150 | ||
17151 | See chapter 23 for further details of the local delivery environment. | |
17152 | ||
2813c06e | 17153 | +-------------------------------------------------+ |
420a0d19 | 17154 | |unseen|Use: routers|Type: boolean*|Default: false| |
2813c06e | 17155 | +-------------------------------------------------+ |
420a0d19 CE |
17156 | |
17157 | The result of string expansion for this option must be a valid boolean value, | |
17158 | that is, one of the strings "yes", "no", "true", or "false". Any other result | |
17159 | causes an error, and delivery is deferred. If the expansion is forced to fail, | |
17160 | the default value for the option (false) is used. Other failures cause delivery | |
17161 | to be deferred. | |
17162 | ||
17163 | When this option is set true, routing does not cease if the router accepts the | |
17164 | address. Instead, a copy of the incoming address is passed to the next router, | |
17165 | overriding a false setting of more. There is little point in setting more false | |
17166 | if unseen is always true, but it may be useful in cases when the value of | |
17167 | unseen contains expansion items (and therefore, presumably, is sometimes true | |
17168 | and sometimes false). | |
17169 | ||
17170 | Setting the unseen option has a similar effect to the unseen command qualifier | |
17171 | in filter files. It can be used to cause copies of messages to be delivered to | |
17172 | some other destination, while also carrying out a normal delivery. In effect, | |
17173 | the current address is made into a "parent" that has two children - one that is | |
17174 | delivered as specified by this router, and a clone that goes on to be routed | |
17175 | further. For this reason, unseen may not be combined with the one_time option | |
17176 | in a redirect router. | |
17177 | ||
17178 | Warning: Header lines added to the address (or specified for removal) by this | |
17179 | router or by previous routers affect the "unseen" copy of the message only. The | |
17180 | clone that continues to be processed by further routers starts with no added | |
17181 | headers and none specified for removal. For a redirect router, if a generated | |
17182 | address is the same as the incoming address, this can lead to duplicate | |
17183 | addresses with different header modifications. Exim does not do duplicate | |
17184 | deliveries (except, in certain circumstances, to pipes -- see section 22.7), | |
17185 | but it is undefined which of the duplicates is discarded, so this ambiguous | |
17186 | situation should be avoided. The repeat_use option of the redirect router may | |
17187 | be of help. | |
17188 | ||
17189 | Unlike the handling of header modifications, any data that was set by the | |
17190 | address_data option in the current or previous routers is passed on to | |
17191 | subsequent routers. | |
17192 | ||
2813c06e | 17193 | +--------------------------------------------------+ |
420a0d19 | 17194 | |user|Use: routers|Type: string*|Default: see below| |
2813c06e | 17195 | +--------------------------------------------------+ |
420a0d19 CE |
17196 | |
17197 | When a router queues an address for a transport, and the transport does not | |
17198 | specify a user, the user given here is used when running the delivery process. | |
17199 | The user may be specified numerically or by name. If expansion fails, the error | |
17200 | is logged and delivery is deferred. This user is also used by the redirect | |
17201 | router when running a filter file. The default is unset, except when | |
17202 | check_local_user is set. In this case, the default is taken from the password | |
17203 | information. If the user is specified as a name, and group is not set, the | |
17204 | group associated with the user is used. See also initgroups and group and the | |
17205 | discussion in chapter 23. | |
17206 | ||
2813c06e | 17207 | +-------------------------------------------------+ |
420a0d19 | 17208 | |verify|Use: routers**|Type: boolean|Default: true| |
2813c06e | 17209 | +-------------------------------------------------+ |
420a0d19 CE |
17210 | |
17211 | Setting this option has the effect of setting verify_sender and | |
17212 | verify_recipient to the same value. | |
17213 | ||
2813c06e | 17214 | +-------------------------------------------------------+ |
420a0d19 | 17215 | |verify_only|Use: routers**|Type: boolean|Default: false| |
2813c06e | 17216 | +-------------------------------------------------------+ |
420a0d19 CE |
17217 | |
17218 | If this option is set, the router is used only when verifying an address, | |
17219 | delivering in cutthrough mode or testing with the -bv option, not when actually | |
17220 | doing a delivery, testing with the -bt option, or running the SMTP EXPN | |
17221 | command. It can be further restricted to verifying only senders or recipients | |
17222 | by means of verify_sender and verify_recipient. | |
17223 | ||
17224 | Warning: When the router is being run to verify addresses for an incoming SMTP | |
17225 | message, Exim is not running as root, but under its own uid. If the router | |
17226 | accesses any files, you need to make sure that they are accessible to the Exim | |
17227 | user or group. | |
17228 | ||
2813c06e | 17229 | +-----------------------------------------------------------+ |
420a0d19 | 17230 | |verify_recipient|Use: routers**|Type: boolean|Default: true| |
2813c06e | 17231 | +-----------------------------------------------------------+ |
420a0d19 CE |
17232 | |
17233 | If this option is false, the router is skipped when verifying recipient | |
17234 | addresses, delivering in cutthrough mode or testing recipient verification | |
17235 | using -bv. See section 3.12 for a list of the order in which preconditions are | |
2813c06e | 17236 | evaluated. See also the $verify_mode variable. |
420a0d19 | 17237 | |
2813c06e | 17238 | +--------------------------------------------------------+ |
420a0d19 | 17239 | |verify_sender|Use: routers**|Type: boolean|Default: true| |
2813c06e | 17240 | +--------------------------------------------------------+ |
420a0d19 CE |
17241 | |
17242 | If this option is false, the router is skipped when verifying sender addresses | |
17243 | or testing sender verification using -bvs. See section 3.12 for a list of the | |
2813c06e | 17244 | order in which preconditions are evaluated. See also the $verify_mode variable. |
420a0d19 CE |
17245 | |
17246 | ||
17247 | ||
17248 | =============================================================================== | |
17249 | 16. THE ACCEPT ROUTER | |
17250 | ||
17251 | The accept router has no private options of its own. Unless it is being used | |
17252 | purely for verification (see verify_only) a transport is required to be defined | |
17253 | by the generic transport option. If the preconditions that are specified by | |
17254 | generic options are met, the router accepts the address and queues it for the | |
17255 | given transport. The most common use of this router is for setting up | |
17256 | deliveries to local mailboxes. For example: | |
17257 | ||
17258 | localusers: | |
17259 | driver = accept | |
17260 | domains = mydomain.example | |
17261 | check_local_user | |
17262 | transport = local_delivery | |
17263 | ||
17264 | The domains condition in this example checks the domain of the address, and | |
17265 | check_local_user checks that the local part is the login of a local user. When | |
17266 | both preconditions are met, the accept router runs, and queues the address for | |
17267 | the local_delivery transport. | |
17268 | ||
17269 | ||
17270 | ||
17271 | =============================================================================== | |
17272 | 17. THE DNSLOOKUP ROUTER | |
17273 | ||
17274 | The dnslookup router looks up the hosts that handle mail for the recipient's | |
17275 | domain in the DNS. A transport must always be set for this router, unless | |
17276 | verify_only is set. | |
17277 | ||
17278 | If SRV support is configured (see check_srv below), Exim first searches for SRV | |
17279 | records. If none are found, or if SRV support is not configured, MX records are | |
17280 | looked up. If no MX records exist, address records are sought. However, | |
17281 | mx_domains can be set to disable the direct use of address records. | |
17282 | ||
17283 | MX records of equal priority are sorted by Exim into a random order. Exim then | |
17284 | looks for address records for the host names obtained from MX or SRV records. | |
17285 | When a host has more than one IP address, they are sorted into a random order, | |
17286 | except that IPv6 addresses are always sorted before IPv4 addresses. If all the | |
17287 | IP addresses found are discarded by a setting of the ignore_target_hosts | |
17288 | generic option, the router declines. | |
17289 | ||
17290 | Unless they have the highest priority (lowest MX value), MX records that point | |
17291 | to the local host, or to any host name that matches hosts_treat_as_local, are | |
17292 | discarded, together with any other MX records of equal or lower priority. | |
17293 | ||
17294 | If the host pointed to by the highest priority MX record, or looked up as an | |
17295 | address record, is the local host, or matches hosts_treat_as_local, what | |
17296 | happens is controlled by the generic self option. | |
17297 | ||
17298 | ||
17299 | 17.1 Problems with DNS lookups | |
17300 | ------------------------------ | |
17301 | ||
17302 | There have been problems with DNS servers when SRV records are looked up. Some | |
2813c06e | 17303 | misbehaving servers return a DNS error or timeout when a non-existent SRV |
420a0d19 CE |
17304 | record is sought. Similar problems have in the past been reported for MX |
17305 | records. The global dns_again_means_nonexist option can help with this problem, | |
17306 | but it is heavy-handed because it is a global option. | |
17307 | ||
17308 | For this reason, there are two options, srv_fail_domains and mx_fail_domains, | |
17309 | that control what happens when a DNS lookup in a dnslookup router results in a | |
17310 | DNS failure or a "try again" response. If an attempt to look up an SRV or MX | |
17311 | record causes one of these results, and the domain matches the relevant list, | |
17312 | Exim behaves as if the DNS had responded "no such record". In the case of an | |
17313 | SRV lookup, this means that the router proceeds to look for MX records; in the | |
17314 | case of an MX lookup, it proceeds to look for A or AAAA records, unless the | |
17315 | domain matches mx_domains, in which case routing fails. | |
17316 | ||
17317 | ||
17318 | 17.2 Declining addresses by dnslookup | |
17319 | ------------------------------------- | |
17320 | ||
17321 | There are a few cases where a dnslookup router will decline to accept an | |
17322 | address; if such a router is expected to handle "all remaining non-local | |
17323 | domains", then it is important to set no_more. | |
17324 | ||
2813c06e CE |
17325 | The router will defer rather than decline if the domain is found in the |
17326 | fail_defer_domains router option. | |
17327 | ||
420a0d19 CE |
17328 | Reasons for a dnslookup router to decline currently include: |
17329 | ||
17330 | * The domain does not exist in DNS | |
17331 | ||
17332 | * The domain exists but the MX record's host part is just "."; this is a | |
17333 | common convention (borrowed from SRV) used to indicate that there is no | |
17334 | such service for this domain and to not fall back to trying A/AAAA records. | |
17335 | ||
17336 | * Ditto, but for SRV records, when check_srv is set on this router. | |
17337 | ||
17338 | * MX record points to a non-existent host. | |
17339 | ||
17340 | * MX record points to an IP address and the main section option | |
17341 | allow_mx_to_ip is not set. | |
17342 | ||
17343 | * MX records exist and point to valid hosts, but all hosts resolve only to | |
17344 | addresses blocked by the ignore_target_hosts generic option on this router. | |
17345 | ||
17346 | * The domain is not syntactically valid (see also allow_utf8_domains and | |
17347 | dns_check_names_pattern for handling one variant of this) | |
17348 | ||
17349 | * check_secondary_mx is set on this router but the local host can not be | |
17350 | found in the MX records (see below) | |
17351 | ||
17352 | ||
17353 | 17.3 Private options for dnslookup | |
17354 | ---------------------------------- | |
17355 | ||
17356 | The private options for the dnslookup router are as follows: | |
17357 | ||
2813c06e | 17358 | +--------------------------------------------------------------+ |
420a0d19 | 17359 | |check_secondary_mx|Use: dnslookup|Type: boolean|Default: false| |
2813c06e | 17360 | +--------------------------------------------------------------+ |
420a0d19 CE |
17361 | |
17362 | If this option is set, the router declines unless the local host is found in | |
17363 | (and removed from) the list of hosts obtained by MX lookup. This can be used to | |
17364 | process domains for which the local host is a secondary mail exchanger | |
17365 | differently to other domains. The way in which Exim decides whether a host is | |
17366 | the local host is described in section 13.8. | |
17367 | ||
2813c06e | 17368 | +-----------------------------------------------------+ |
420a0d19 | 17369 | |check_srv|Use: dnslookup|Type: string*|Default: unset| |
2813c06e | 17370 | +-----------------------------------------------------+ |
420a0d19 CE |
17371 | |
17372 | The dnslookup router supports the use of SRV records (see RFC 2782) in addition | |
17373 | to MX and address records. The support is disabled by default. To enable SRV | |
17374 | support, set the check_srv option to the name of the service required. For | |
17375 | example, | |
17376 | ||
17377 | check_srv = smtp | |
17378 | ||
17379 | looks for SRV records that refer to the normal smtp service. The option is | |
17380 | expanded, so the service name can vary from message to message or address to | |
17381 | address. This might be helpful if SRV records are being used for a submission | |
17382 | service. If the expansion is forced to fail, the check_srv option is ignored, | |
17383 | and the router proceeds to look for MX records in the normal way. | |
17384 | ||
17385 | When the expansion succeeds, the router searches first for SRV records for the | |
17386 | given service (it assumes TCP protocol). A single SRV record with a host name | |
17387 | that consists of just a single dot indicates "no such service for this domain"; | |
17388 | if this is encountered, the router declines. If other kinds of SRV record are | |
17389 | found, they are used to construct a host list for delivery according to the | |
17390 | rules of RFC 2782. MX records are not sought in this case. | |
17391 | ||
17392 | When no SRV records are found, MX records (and address records) are sought in | |
17393 | the traditional way. In other words, SRV records take precedence over MX | |
17394 | records, just as MX records take precedence over address records. Note that | |
17395 | this behaviour is not sanctioned by RFC 2782, though a previous draft RFC | |
17396 | defined it. It is apparently believed that MX records are sufficient for email | |
17397 | and that SRV records should not be used for this purpose. However, SRV records | |
17398 | have an additional "weight" feature which some people might find useful when | |
17399 | trying to split an SMTP load between hosts of different power. | |
17400 | ||
17401 | See section 17.1 above for a discussion of Exim's behaviour when there is a DNS | |
17402 | lookup error. | |
17403 | ||
2813c06e CE |
17404 | +-------------------------------------------------------------------+ |
17405 | |fail_defer_domains|Use: dnslookup|Type: domain list*|Default: unset| | |
17406 | +-------------------------------------------------------------------+ | |
420a0d19 | 17407 | |
2813c06e CE |
17408 | DNS lookups for domains matching fail_defer_domains which find no matching |
17409 | record will cause the router to defer rather than the default behaviour of | |
17410 | decline. This maybe be useful for queueing messages for a newly created domain | |
17411 | while the DNS configuration is not ready. However, it will result in any | |
17412 | message with mistyped domains also being queued. | |
420a0d19 | 17413 | |
2813c06e | 17414 | +-----------------------------------------------------------+ |
420a0d19 | 17415 | |mx_domains|Use: dnslookup|Type: domain list*|Default: unset| |
2813c06e | 17416 | +-----------------------------------------------------------+ |
420a0d19 CE |
17417 | |
17418 | A domain that matches mx_domains is required to have either an MX or an SRV | |
17419 | record in order to be recognized. (The name of this option could be improved.) | |
17420 | For example, if all the mail hosts in fict.example are known to have MX | |
17421 | records, except for those in discworld.fict.example, you could use this | |
17422 | setting: | |
17423 | ||
17424 | mx_domains = ! *.discworld.fict.example : *.fict.example | |
17425 | ||
17426 | This specifies that messages addressed to a domain that matches the list but | |
17427 | has no MX record should be bounced immediately instead of being routed using | |
17428 | the address record. | |
17429 | ||
2813c06e | 17430 | +----------------------------------------------------------------+ |
420a0d19 | 17431 | |mx_fail_domains|Use: dnslookup|Type: domain list*|Default: unset| |
2813c06e | 17432 | +----------------------------------------------------------------+ |
420a0d19 CE |
17433 | |
17434 | If the DNS lookup for MX records for one of the domains in this list causes a | |
17435 | DNS lookup error, Exim behaves as if no MX records were found. See section 17.1 | |
17436 | for more discussion. | |
17437 | ||
2813c06e | 17438 | +---------------------------------------------------------+ |
420a0d19 | 17439 | |qualify_single|Use: dnslookup|Type: boolean|Default: true| |
2813c06e | 17440 | +---------------------------------------------------------+ |
420a0d19 CE |
17441 | |
17442 | When this option is true, the resolver option RES_DEFNAMES is set for DNS | |
17443 | lookups. Typically, but not standardly, this causes the resolver to qualify | |
17444 | single-component names with the default domain. For example, on a machine | |
17445 | called dictionary.ref.example, the domain thesaurus would be changed to | |
17446 | thesaurus.ref.example inside the resolver. For details of what your resolver | |
17447 | actually does, consult your man pages for resolver and resolv.conf. | |
17448 | ||
2813c06e | 17449 | +----------------------------------------------------------+ |
420a0d19 | 17450 | |rewrite_headers|Use: dnslookup|Type: boolean|Default: true| |
2813c06e | 17451 | +----------------------------------------------------------+ |
420a0d19 CE |
17452 | |
17453 | If the domain name in the address that is being processed is not fully | |
17454 | qualified, it may be expanded to its full form by a DNS lookup. For example, if | |
17455 | an address is specified as dormouse@teaparty, the domain might be expanded to | |
17456 | teaparty.wonderland.fict.example. Domain expansion can also occur as a result | |
17457 | of setting the widen_domains option. If rewrite_headers is true, all | |
17458 | occurrences of the abbreviated domain name in any Bcc:, Cc:, From:, Reply-to:, | |
17459 | Sender:, and To: header lines of the message are rewritten with the full domain | |
17460 | name. | |
17461 | ||
17462 | This option should be turned off only when it is known that no message is ever | |
17463 | going to be sent outside an environment where the abbreviation makes sense. | |
17464 | ||
17465 | When an MX record is looked up in the DNS and matches a wildcard record, name | |
17466 | servers normally return a record containing the name that has been looked up, | |
17467 | making it impossible to detect whether a wildcard was present or not. However, | |
17468 | some name servers have recently been seen to return the wildcard entry. If the | |
17469 | name returned by a DNS lookup begins with an asterisk, it is not used for | |
17470 | header rewriting. | |
17471 | ||
2813c06e | 17472 | +--------------------------------------------------------------------+ |
420a0d19 | 17473 | |same_domain_copy_routing|Use: dnslookup|Type: boolean|Default: false| |
2813c06e | 17474 | +--------------------------------------------------------------------+ |
420a0d19 CE |
17475 | |
17476 | Addresses with the same domain are normally routed by the dnslookup router to | |
17477 | the same list of hosts. However, this cannot be presumed, because the router | |
17478 | options and preconditions may refer to the local part of the address. By | |
17479 | default, therefore, Exim routes each address in a message independently. DNS | |
17480 | servers run caches, so repeated DNS lookups are not normally expensive, and in | |
17481 | any case, personal messages rarely have more than a few recipients. | |
17482 | ||
17483 | If you are running mailing lists with large numbers of subscribers at the same | |
17484 | domain, and you are using a dnslookup router which is independent of the local | |
17485 | part, you can set same_domain_copy_routing to bypass repeated DNS lookups for | |
17486 | identical domains in one message. In this case, when dnslookup routes an | |
17487 | address to a remote transport, any other unrouted addresses in the message that | |
17488 | have the same domain are automatically given the same routing without | |
17489 | processing them independently, provided the following conditions are met: | |
17490 | ||
17491 | * No router that processed the address specified headers_add or | |
17492 | headers_remove. | |
17493 | ||
17494 | * The router did not change the address in any way, for example, by | |
17495 | "widening" the domain. | |
17496 | ||
2813c06e | 17497 | +----------------------------------------------------------+ |
420a0d19 | 17498 | |search_parents|Use: dnslookup|Type: boolean|Default: false| |
2813c06e | 17499 | +----------------------------------------------------------+ |
420a0d19 CE |
17500 | |
17501 | When this option is true, the resolver option RES_DNSRCH is set for DNS | |
17502 | lookups. This is different from the qualify_single option in that it applies to | |
17503 | domains containing dots. Typically, but not standardly, it causes the resolver | |
17504 | to search for the name in the current domain and in parent domains. For | |
17505 | example, on a machine in the fict.example domain, if looking up | |
17506 | teaparty.wonderland failed, the resolver would try | |
17507 | teaparty.wonderland.fict.example. For details of what your resolver actually | |
17508 | does, consult your man pages for resolver and resolv.conf. | |
17509 | ||
17510 | Setting this option true can cause problems in domains that have a wildcard MX | |
17511 | record, because any domain that does not have its own MX record matches the | |
17512 | local wildcard. | |
17513 | ||
2813c06e | 17514 | +-----------------------------------------------------------------+ |
420a0d19 | 17515 | |srv_fail_domains|Use: dnslookup|Type: domain list*|Default: unset| |
2813c06e | 17516 | +-----------------------------------------------------------------+ |
420a0d19 CE |
17517 | |
17518 | If the DNS lookup for SRV records for one of the domains in this list causes a | |
17519 | DNS lookup error, Exim behaves as if no SRV records were found. See section | |
17520 | 17.1 for more discussion. | |
17521 | ||
2813c06e | 17522 | +-------------------------------------------------------------+ |
420a0d19 | 17523 | |widen_domains|Use: dnslookup|Type: string list|Default: unset| |
2813c06e | 17524 | +-------------------------------------------------------------+ |
420a0d19 CE |
17525 | |
17526 | If a DNS lookup fails and this option is set, each of its strings in turn is | |
17527 | added onto the end of the domain, and the lookup is tried again. For example, | |
17528 | if | |
17529 | ||
17530 | widen_domains = fict.example:ref.example | |
17531 | ||
17532 | is set and a lookup of klingon.dictionary fails, | |
17533 | klingon.dictionary.fict.example is looked up, and if this fails, | |
17534 | klingon.dictionary.ref.example is tried. Note that the qualify_single and | |
17535 | search_parents options can cause some widening to be undertaken inside the DNS | |
17536 | resolver. widen_domains is not applied to sender addresses when verifying, | |
17537 | unless rewrite_headers is false (not the default). | |
17538 | ||
17539 | ||
17540 | 17.4 Effect of qualify_single and search_parents | |
17541 | ------------------------------------------------ | |
17542 | ||
17543 | When a domain from an envelope recipient is changed by the resolver as a result | |
17544 | of the qualify_single or search_parents options, Exim rewrites the | |
17545 | corresponding address in the message's header lines unless rewrite_headers is | |
17546 | set false. Exim then re-routes the address, using the full domain. | |
17547 | ||
17548 | These two options affect only the DNS lookup that takes place inside the router | |
17549 | for the domain of the address that is being routed. They do not affect lookups | |
17550 | such as that implied by | |
17551 | ||
17552 | domains = @mx_any | |
17553 | ||
17554 | that may happen while processing a router precondition before the router is | |
17555 | entered. No widening ever takes place for these lookups. | |
17556 | ||
17557 | ||
17558 | ||
17559 | =============================================================================== | |
17560 | 18. THE IPLITERAL ROUTER | |
17561 | ||
17562 | This router has no private options. Unless it is being used purely for | |
17563 | verification (see verify_only) a transport is required to be defined by the | |
17564 | generic transport option. The router accepts the address if its domain part | |
17565 | takes the form of an RFC 2822 domain literal. For example, the ipliteral router | |
17566 | handles the address | |
17567 | ||
17568 | root@[192.168.1.1] | |
17569 | ||
17570 | by setting up delivery to the host with that IP address. IPv4 domain literals | |
17571 | consist of an IPv4 address enclosed in square brackets. IPv6 domain literals | |
17572 | are similar, but the address is preceded by "ipv6:". For example: | |
17573 | ||
17574 | postmaster@[ipv6:fe80::a00:20ff:fe86:a061.5678] | |
17575 | ||
17576 | Exim allows "ipv4:" before IPv4 addresses, for consistency, and on the grounds | |
17577 | that sooner or later somebody will try it. | |
17578 | ||
17579 | If the IP address matches something in ignore_target_hosts, the router | |
17580 | declines. If an IP literal turns out to refer to the local host, the generic | |
17581 | self option determines what happens. | |
17582 | ||
17583 | The RFCs require support for domain literals; however, their use is | |
17584 | controversial in today's Internet. If you want to use this router, you must | |
17585 | also set the main configuration option allow_domain_literals. Otherwise, Exim | |
17586 | will not recognize the domain literal syntax in addresses. | |
17587 | ||
17588 | ||
17589 | ||
17590 | =============================================================================== | |
17591 | 19. THE IPLOOKUP ROUTER | |
17592 | ||
17593 | The iplookup router was written to fulfil a specific requirement in Cambridge | |
17594 | University (which in fact no longer exists). For this reason, it is not | |
17595 | included in the binary of Exim by default. If you want to include it, you must | |
17596 | set | |
17597 | ||
17598 | ROUTER_IPLOOKUP=yes | |
17599 | ||
17600 | in your Local/Makefile configuration file. | |
17601 | ||
17602 | The iplookup router routes an address by sending it over a TCP or UDP | |
17603 | connection to one or more specific hosts. The host can then return the same or | |
17604 | a different address - in effect rewriting the recipient address in the | |
17605 | message's envelope. The new address is then passed on to subsequent routers. If | |
17606 | this process fails, the address can be passed on to other routers, or delivery | |
17607 | can be deferred. Since iplookup is just a rewriting router, a transport must | |
17608 | not be specified for it. | |
17609 | ||
2813c06e | 17610 | +-----------------------------------------------+ |
420a0d19 | 17611 | |hosts|Use: iplookup|Type: string|Default: unset| |
2813c06e | 17612 | +-----------------------------------------------+ |
420a0d19 CE |
17613 | |
17614 | This option must be supplied. Its value is a colon-separated list of host | |
17615 | names. The hosts are looked up using gethostbyname() (or getipnodebyname() when | |
17616 | available) and are tried in order until one responds to the query. If none | |
17617 | respond, what happens is controlled by optional. | |
17618 | ||
2813c06e | 17619 | +---------------------------------------------------+ |
420a0d19 | 17620 | |optional|Use: iplookup|Type: boolean|Default: false| |
2813c06e | 17621 | +---------------------------------------------------+ |
420a0d19 CE |
17622 | |
17623 | If optional is true, if no response is obtained from any host, the address is | |
17624 | passed to the next router, overriding no_more. If optional is false, delivery | |
17625 | to the address is deferred. | |
17626 | ||
2813c06e | 17627 | +-------------------------------------------+ |
420a0d19 | 17628 | |port|Use: iplookup|Type: integer|Default: 0| |
2813c06e | 17629 | +-------------------------------------------+ |
420a0d19 CE |
17630 | |
17631 | This option must be supplied. It specifies the port number for the TCP or UDP | |
17632 | call. | |
17633 | ||
2813c06e | 17634 | +------------------------------------------------+ |
420a0d19 | 17635 | |protocol|Use: iplookup|Type: string|Default: udp| |
2813c06e | 17636 | +------------------------------------------------+ |
420a0d19 CE |
17637 | |
17638 | This option can be set to "udp" or "tcp" to specify which of the two protocols | |
17639 | is to be used. | |
17640 | ||
2813c06e | 17641 | +----------------------------------------------------+ |
420a0d19 | 17642 | |query|Use: iplookup|Type: string*|Default: see below| |
2813c06e | 17643 | +----------------------------------------------------+ |
420a0d19 CE |
17644 | |
17645 | This defines the content of the query that is sent to the remote hosts. The | |
17646 | default value is: | |
17647 | ||
17648 | $local_part@$domain $local_part@$domain | |
17649 | ||
17650 | The repetition serves as a way of checking that a response is to the correct | |
17651 | query in the default case (see response_pattern below). | |
17652 | ||
2813c06e | 17653 | +--------------------------------------------------+ |
420a0d19 | 17654 | |reroute|Use: iplookup|Type: string*|Default: unset| |
2813c06e | 17655 | +--------------------------------------------------+ |
420a0d19 CE |
17656 | |
17657 | If this option is not set, the rerouted address is precisely the byte string | |
17658 | returned by the remote host, up to the first white space, if any. If set, the | |
17659 | string is expanded to form the rerouted address. It can include parts matched | |
17660 | in the response by response_pattern by means of numeric variables such as $1, | |
17661 | $2, etc. The variable $0 refers to the entire input string, whether or not a | |
17662 | pattern is in use. In all cases, the rerouted address must end up in the form | |
17663 | local_part@domain. | |
17664 | ||
2813c06e | 17665 | +----------------------------------------------------------+ |
420a0d19 | 17666 | |response_pattern|Use: iplookup|Type: string|Default: unset| |
2813c06e | 17667 | +----------------------------------------------------------+ |
420a0d19 CE |
17668 | |
17669 | This option can be set to a regular expression that is applied to the string | |
17670 | returned from the remote host. If the pattern does not match the response, the | |
17671 | router declines. If response_pattern is not set, no checking of the response is | |
17672 | done, unless the query was defaulted, in which case there is a check that the | |
17673 | text returned after the first white space is the original address. This checks | |
17674 | that the answer that has been received is in response to the correct question. | |
17675 | For example, if the response is just a new domain, the following could be used: | |
17676 | ||
17677 | response_pattern = ^([^@]+)$ | |
17678 | reroute = $local_part@$1 | |
17679 | ||
2813c06e | 17680 | +--------------------------------------------+ |
420a0d19 | 17681 | |timeout|Use: iplookup|Type: time|Default: 5s| |
2813c06e | 17682 | +--------------------------------------------+ |
420a0d19 CE |
17683 | |
17684 | This specifies the amount of time to wait for a response from the remote | |
17685 | machine. The same timeout is used for the connect() function for a TCP call. It | |
17686 | does not apply to UDP. | |
17687 | ||
17688 | ||
17689 | ||
17690 | =============================================================================== | |
17691 | 20. THE MANUALROUTE ROUTER | |
17692 | ||
17693 | The manualroute router is so-called because it provides a way of manually | |
17694 | routing an address according to its domain. It is mainly used when you want to | |
17695 | route addresses to remote hosts according to your own rules, bypassing the | |
17696 | normal DNS routing that looks up MX records. However, manualroute can also | |
17697 | route to local transports, a facility that may be useful if you want to save | |
17698 | messages for dial-in hosts in local files. | |
17699 | ||
17700 | The manualroute router compares a list of domain patterns with the domain it is | |
17701 | trying to route. If there is no match, the router declines. Each pattern has | |
17702 | associated with it a list of hosts and some other optional data, which may | |
17703 | include a transport. The combination of a pattern and its data is called a | |
17704 | "routing rule". For patterns that do not have an associated transport, the | |
17705 | generic transport option must specify a transport, unless the router is being | |
17706 | used purely for verification (see verify_only). | |
17707 | ||
17708 | In the case of verification, matching the domain pattern is sufficient for the | |
17709 | router to accept the address. When actually routing an address for delivery, an | |
17710 | address that matches a domain pattern is queued for the associated transport. | |
17711 | If the transport is not a local one, a host list must be associated with the | |
17712 | pattern; IP addresses are looked up for the hosts, and these are passed to the | |
17713 | transport along with the mail address. For local transports, a host list is | |
17714 | optional. If it is present, it is passed in $host as a single text string. | |
17715 | ||
17716 | The list of routing rules can be provided as an inline string in route_list, or | |
17717 | the data can be obtained by looking up the domain in a file or database by | |
17718 | setting route_data. Only one of these settings may appear in any one instance | |
17719 | of manualroute. The format of routing rules is described below, following the | |
17720 | list of private options. | |
17721 | ||
17722 | ||
17723 | 20.1 Private options for manualroute | |
17724 | ------------------------------------ | |
17725 | ||
17726 | The private options for the manualroute router are as follows: | |
17727 | ||
2813c06e | 17728 | +-------------------------------------------------------------+ |
420a0d19 | 17729 | |host_all_ignored|Use: manualroute|Type: string|Default: defer| |
2813c06e | 17730 | +-------------------------------------------------------------+ |
420a0d19 CE |
17731 | |
17732 | See host_find_failed. | |
17733 | ||
2813c06e | 17734 | +--------------------------------------------------------------+ |
420a0d19 | 17735 | |host_find_failed|Use: manualroute|Type: string|Default: freeze| |
2813c06e | 17736 | +--------------------------------------------------------------+ |
420a0d19 CE |
17737 | |
17738 | This option controls what happens when manualroute tries to find an IP address | |
17739 | for a host, and the host does not exist. The option can be set to one of the | |
17740 | following values: | |
17741 | ||
17742 | decline | |
17743 | defer | |
17744 | fail | |
17745 | freeze | |
17746 | ignore | |
17747 | pass | |
17748 | ||
17749 | The default ("freeze") assumes that this state is a serious configuration | |
17750 | error. The difference between "pass" and "decline" is that the former forces | |
17751 | the address to be passed to the next router (or the router defined by | |
17752 | pass_router), overriding no_more, whereas the latter passes the address to the | |
17753 | next router only if more is true. | |
17754 | ||
17755 | The value "ignore" causes Exim to completely ignore a host whose IP address | |
17756 | cannot be found. If all the hosts in the list are ignored, the behaviour is | |
17757 | controlled by the host_all_ignored option. This takes the same values as | |
17758 | host_find_failed, except that it cannot be set to "ignore". | |
17759 | ||
17760 | The host_find_failed option applies only to a definite "does not exist" state; | |
17761 | if a host lookup gets a temporary error, delivery is deferred unless the | |
17762 | generic pass_on_timeout option is set. | |
17763 | ||
2813c06e | 17764 | +-------------------------------------------------------------+ |
420a0d19 | 17765 | |hosts_randomize|Use: manualroute|Type: boolean|Default: false| |
2813c06e | 17766 | +-------------------------------------------------------------+ |
420a0d19 CE |
17767 | |
17768 | If this option is set, the order of the items in a host list in a routing rule | |
17769 | is randomized each time the list is used, unless an option in the routing rule | |
17770 | overrides (see below). Randomizing the order of a host list can be used to do | |
17771 | crude load sharing. However, if more than one mail address is routed by the | |
17772 | same router to the same host list, the host lists are considered to be the same | |
17773 | (even though they may be randomized into different orders) for the purpose of | |
17774 | deciding whether to batch the deliveries into a single SMTP transaction. | |
17775 | ||
17776 | When hosts_randomize is true, a host list may be split into groups whose order | |
17777 | is separately randomized. This makes it possible to set up MX-like behaviour. | |
17778 | The boundaries between groups are indicated by an item that is just "+" in the | |
17779 | host list. For example: | |
17780 | ||
17781 | route_list = * host1:host2:host3:+:host4:host5 | |
17782 | ||
17783 | The order of the first three hosts and the order of the last two hosts is | |
17784 | randomized for each use, but the first three always end up before the last two. | |
17785 | If hosts_randomize is not set, a "+" item in the list is ignored. If a | |
17786 | randomized host list is passed to an smtp transport that also has | |
17787 | hosts_randomize set, the list is not re-randomized. | |
17788 | ||
2813c06e | 17789 | +--------------------------------------------------------+ |
420a0d19 | 17790 | |route_data|Use: manualroute|Type: string*|Default: unset| |
2813c06e | 17791 | +--------------------------------------------------------+ |
420a0d19 CE |
17792 | |
17793 | If this option is set, it must expand to yield the data part of a routing rule. | |
17794 | Typically, the expansion string includes a lookup based on the domain. For | |
17795 | example: | |
17796 | ||
17797 | route_data = ${lookup{$domain}dbm{/etc/routes}} | |
17798 | ||
17799 | If the expansion is forced to fail, or the result is an empty string, the | |
17800 | router declines. Other kinds of expansion failure cause delivery to be | |
17801 | deferred. | |
17802 | ||
2813c06e | 17803 | +------------------------------------------------------------+ |
420a0d19 | 17804 | |route_list|Use: manualroute|Type: string list|Default: unset| |
2813c06e | 17805 | +------------------------------------------------------------+ |
420a0d19 CE |
17806 | |
17807 | This string is a list of routing rules, in the form defined below. Note that, | |
17808 | unlike most string lists, the items are separated by semicolons. This is so | |
17809 | that they may contain colon-separated host lists. | |
17810 | ||
2813c06e | 17811 | +----------------------------------------------------------------------+ |
420a0d19 | 17812 | |same_domain_copy_routing|Use: manualroute|Type: boolean|Default: false| |
2813c06e | 17813 | +----------------------------------------------------------------------+ |
420a0d19 CE |
17814 | |
17815 | Addresses with the same domain are normally routed by the manualroute router to | |
17816 | the same list of hosts. However, this cannot be presumed, because the router | |
17817 | options and preconditions may refer to the local part of the address. By | |
17818 | default, therefore, Exim routes each address in a message independently. DNS | |
17819 | servers run caches, so repeated DNS lookups are not normally expensive, and in | |
17820 | any case, personal messages rarely have more than a few recipients. | |
17821 | ||
17822 | If you are running mailing lists with large numbers of subscribers at the same | |
17823 | domain, and you are using a manualroute router which is independent of the | |
17824 | local part, you can set same_domain_copy_routing to bypass repeated DNS lookups | |
17825 | for identical domains in one message. In this case, when manualroute routes an | |
17826 | address to a remote transport, any other unrouted addresses in the message that | |
17827 | have the same domain are automatically given the same routing without | |
17828 | processing them independently. However, this is only done if headers_add and | |
17829 | headers_remove are unset. | |
17830 | ||
17831 | ||
17832 | 20.2 Routing rules in route_list | |
17833 | -------------------------------- | |
17834 | ||
17835 | The value of route_list is a string consisting of a sequence of routing rules, | |
17836 | separated by semicolons. If a semicolon is needed in a rule, it can be entered | |
17837 | as two semicolons. Alternatively, the list separator can be changed as | |
2813c06e | 17838 | described (for colon-separated lists) in section 6.20. Empty rules are ignored. |
420a0d19 CE |
17839 | The format of each rule is |
17840 | ||
17841 | <domain pattern> <list of hosts> <options> | |
17842 | ||
17843 | The following example contains two rules, each with a simple domain pattern and | |
17844 | no options: | |
17845 | ||
17846 | route_list = \ | |
17847 | dict.ref.example mail-1.ref.example:mail-2.ref.example ; \ | |
17848 | thes.ref.example mail-3.ref.example:mail-4.ref.example | |
17849 | ||
17850 | The three parts of a rule are separated by white space. The pattern and the | |
17851 | list of hosts can be enclosed in quotes if necessary, and if they are, the | |
17852 | usual quoting rules apply. Each rule in a route_list must start with a single | |
17853 | domain pattern, which is the only mandatory item in the rule. The pattern is in | |
17854 | the same format as one item in a domain list (see section 10.8), except that it | |
17855 | may not be the name of an interpolated file. That is, it may be wildcarded, or | |
17856 | a regular expression, or a file or database lookup (with semicolons doubled, | |
17857 | because of the use of semicolon as a separator in a route_list). | |
17858 | ||
17859 | The rules in route_list are searched in order until one of the patterns matches | |
17860 | the domain that is being routed. The list of hosts and then options are then | |
17861 | used as described below. If there is no match, the router declines. When | |
17862 | route_list is set, route_data must not be set. | |
17863 | ||
17864 | ||
17865 | 20.3 Routing rules in route_data | |
17866 | -------------------------------- | |
17867 | ||
17868 | The use of route_list is convenient when there are only a small number of | |
17869 | routing rules. For larger numbers, it is easier to use a file or database to | |
17870 | hold the routing information, and use the route_data option instead. The value | |
17871 | of route_data is a list of hosts, followed by (optional) options. Most | |
17872 | commonly, route_data is set as a string that contains an expansion lookup. For | |
17873 | example, suppose we place two routing rules in a file like this: | |
17874 | ||
17875 | dict.ref.example: mail-1.ref.example:mail-2.ref.example | |
17876 | thes.ref.example: mail-3.ref.example:mail-4.ref.example | |
17877 | ||
17878 | This data can be accessed by setting | |
17879 | ||
17880 | route_data = ${lookup{$domain}lsearch{/the/file/name}} | |
17881 | ||
17882 | Failure of the lookup results in an empty string, causing the router to | |
17883 | decline. However, you do not have to use a lookup in route_data. The only | |
17884 | requirement is that the result of expanding the string is a list of hosts, | |
17885 | possibly followed by options, separated by white space. The list of hosts must | |
17886 | be enclosed in quotes if it contains white space. | |
17887 | ||
17888 | ||
17889 | 20.4 Format of the list of hosts | |
17890 | -------------------------------- | |
17891 | ||
17892 | A list of hosts, whether obtained via route_data or route_list, is always | |
17893 | separately expanded before use. If the expansion fails, the router declines. | |
17894 | The result of the expansion must be a colon-separated list of names and/or IP | |
17895 | addresses, optionally also including ports. The format of each item in the list | |
17896 | is described in the next section. The list separator can be changed as | |
2813c06e | 17897 | described in section 6.20. |
420a0d19 CE |
17898 | |
17899 | If the list of hosts was obtained from a route_list item, the following | |
17900 | variables are set during its expansion: | |
17901 | ||
17902 | * If the domain was matched against a regular expression, the numeric | |
17903 | variables $1, $2, etc. may be set. For example: | |
17904 | ||
17905 | route_list = ^domain(\d+) host-$1.text.example | |
17906 | ||
17907 | * $0 is always set to the entire domain. | |
17908 | ||
17909 | * $1 is also set when partial matching is done in a file lookup. | |
17910 | ||
17911 | * If the pattern that matched the domain was a lookup item, the data that was | |
17912 | looked up is available in the expansion variable $value. For example: | |
17913 | ||
17914 | route_list = lsearch;;/some/file.routes $value | |
17915 | ||
17916 | Note the doubling of the semicolon in the pattern that is necessary because | |
17917 | semicolon is the default route list separator. | |
17918 | ||
17919 | ||
17920 | 20.5 Format of one host item | |
17921 | ---------------------------- | |
17922 | ||
17923 | Each item in the list of hosts is either a host name or an IP address, | |
17924 | optionally with an attached port number. When no port is given, an IP address | |
17925 | is not enclosed in brackets. When a port is specified, it overrides the port | |
17926 | specification on the transport. The port is separated from the name or address | |
17927 | by a colon. This leads to some complications: | |
17928 | ||
17929 | * Because colon is the default separator for the list of hosts, either the | |
17930 | colon that specifies a port must be doubled, or the list separator must be | |
17931 | changed. The following two examples have the same effect: | |
17932 | ||
17933 | route_list = * "host1.tld::1225 : host2.tld::1226" | |
17934 | route_list = * "<+ host1.tld:1225 + host2.tld:1226" | |
17935 | ||
17936 | * When IPv6 addresses are involved, it gets worse, because they contain | |
17937 | colons of their own. To make this case easier, it is permitted to enclose | |
17938 | an IP address (either v4 or v6) in square brackets if a port number | |
17939 | follows. For example: | |
17940 | ||
17941 | route_list = * "</ [10.1.1.1]:1225 / [::1]:1226" | |
17942 | ||
17943 | ||
17944 | 20.6 How the list of hosts is used | |
17945 | ---------------------------------- | |
17946 | ||
17947 | When an address is routed to an smtp transport by manualroute, each of the | |
17948 | hosts is tried, in the order specified, when carrying out the SMTP delivery. | |
17949 | However, the order can be changed by setting the hosts_randomize option, either | |
17950 | on the router (see section 20.1 above), or on the transport. | |
17951 | ||
17952 | Hosts may be listed by name or by IP address. An unadorned name in the list of | |
17953 | hosts is interpreted as a host name. A name that is followed by "/MX" is | |
17954 | interpreted as an indirection to a sublist of hosts obtained by looking up MX | |
17955 | records in the DNS. For example: | |
17956 | ||
17957 | route_list = * x.y.z:p.q.r/MX:e.f.g | |
17958 | ||
17959 | If this feature is used with a port specifier, the port must come last. For | |
17960 | example: | |
17961 | ||
17962 | route_list = * dom1.tld/mx::1225 | |
17963 | ||
17964 | If the hosts_randomize option is set, the order of the items in the list is | |
17965 | randomized before any lookups are done. Exim then scans the list; for any name | |
17966 | that is not followed by "/MX" it looks up an IP address. If this turns out to | |
17967 | be an interface on the local host and the item is not the first in the list, | |
17968 | Exim discards it and any subsequent items. If it is the first item, what | |
17969 | happens is controlled by the self option of the router. | |
17970 | ||
17971 | A name on the list that is followed by "/MX" is replaced with the list of hosts | |
17972 | obtained by looking up MX records for the name. This is always a DNS lookup; | |
17973 | the bydns and byname options (see section 20.7 below) are not relevant here. | |
17974 | The order of these hosts is determined by the preference values in the MX | |
17975 | records, according to the usual rules. Because randomizing happens before the | |
17976 | MX lookup, it does not affect the order that is defined by MX preferences. | |
17977 | ||
17978 | If the local host is present in the sublist obtained from MX records, but is | |
17979 | not the most preferred host in that list, it and any equally or less preferred | |
17980 | hosts are removed before the sublist is inserted into the main list. | |
17981 | ||
17982 | If the local host is the most preferred host in the MX list, what happens | |
17983 | depends on where in the original list of hosts the "/MX" item appears. If it is | |
17984 | not the first item (that is, there are previous hosts in the main list), Exim | |
17985 | discards this name and any subsequent items in the main list. | |
17986 | ||
17987 | If the MX item is first in the list of hosts, and the local host is the most | |
17988 | preferred host, what happens is controlled by the self option of the router. | |
17989 | ||
17990 | DNS failures when lookup up the MX records are treated in the same way as DNS | |
17991 | failures when looking up IP addresses: pass_on_timeout and host_find_failed are | |
17992 | used when relevant. | |
17993 | ||
17994 | The generic ignore_target_hosts option applies to all hosts in the list, | |
17995 | whether obtained from an MX lookup or not. | |
17996 | ||
17997 | ||
17998 | 20.7 How the options are used | |
17999 | ----------------------------- | |
18000 | ||
18001 | The options are a sequence of words; in practice no more than three are ever | |
18002 | present. One of the words can be the name of a transport; this overrides the | |
18003 | transport option on the router for this particular routing rule only. The other | |
18004 | words (if present) control randomization of the list of hosts on a per-rule | |
18005 | basis, and how the IP addresses of the hosts are to be found when routing to a | |
18006 | remote transport. These options are as follows: | |
18007 | ||
18008 | * randomize: randomize the order of the hosts in this list, overriding the | |
18009 | setting of hosts_randomize for this routing rule only. | |
18010 | ||
18011 | * no_randomize: do not randomize the order of the hosts in this list, | |
18012 | overriding the setting of hosts_randomize for this routing rule only. | |
18013 | ||
18014 | * byname: use getipnodebyname() (gethostbyname() on older systems) to find IP | |
18015 | addresses. This function may ultimately cause a DNS lookup, but it may also | |
18016 | look in /etc/hosts or other sources of information. | |
18017 | ||
18018 | * bydns: look up address records for the hosts directly in the DNS; fail if | |
18019 | no address records are found. If there is a temporary DNS error (such as a | |
18020 | timeout), delivery is deferred. | |
18021 | ||
18022 | For example: | |
18023 | ||
18024 | route_list = domain1 host1:host2:host3 randomize bydns;\ | |
18025 | domain2 host4:host5 | |
18026 | ||
18027 | If neither byname nor bydns is given, Exim behaves as follows: First, a DNS | |
18028 | lookup is done. If this yields anything other than HOST_NOT_FOUND, that result | |
18029 | is used. Otherwise, Exim goes on to try a call to getipnodebyname() or | |
18030 | gethostbyname(), and the result of the lookup is the result of that call. | |
18031 | ||
18032 | Warning: It has been discovered that on some systems, if a DNS lookup called | |
18033 | via getipnodebyname() times out, HOST_NOT_FOUND is returned instead of | |
18034 | TRY_AGAIN. That is why the default action is to try a DNS lookup first. Only if | |
18035 | that gives a definite "no such host" is the local function called. | |
18036 | ||
18037 | If no IP address for a host can be found, what happens is controlled by the | |
18038 | host_find_failed option. | |
18039 | ||
18040 | When an address is routed to a local transport, IP addresses are not looked up. | |
18041 | The host list is passed to the transport in the $host variable. | |
18042 | ||
18043 | ||
18044 | 20.8 Manualroute examples | |
18045 | ------------------------- | |
18046 | ||
18047 | In some of the examples that follow, the presence of the remote_smtp transport, | |
18048 | as defined in the default configuration file, is assumed: | |
18049 | ||
18050 | * The manualroute router can be used to forward all external mail to a smart | |
18051 | host. If you have set up, in the main part of the configuration, a named | |
18052 | domain list that contains your local domains, for example: | |
18053 | ||
18054 | domainlist local_domains = my.domain.example | |
18055 | ||
18056 | You can arrange for all other domains to be routed to a smart host by | |
18057 | making your first router something like this: | |
18058 | ||
18059 | smart_route: | |
18060 | driver = manualroute | |
18061 | domains = !+local_domains | |
18062 | transport = remote_smtp | |
18063 | route_list = * smarthost.ref.example | |
18064 | ||
18065 | This causes all non-local addresses to be sent to the single host | |
18066 | smarthost.ref.example. If a colon-separated list of smart hosts is given, | |
18067 | they are tried in order (but you can use hosts_randomize to vary the order | |
18068 | each time). Another way of configuring the same thing is this: | |
18069 | ||
18070 | smart_route: | |
18071 | driver = manualroute | |
18072 | transport = remote_smtp | |
18073 | route_list = !+local_domains smarthost.ref.example | |
18074 | ||
18075 | There is no difference in behaviour between these two routers as they | |
18076 | stand. However, they behave differently if no_more is added to them. In the | |
18077 | first example, the router is skipped if the domain does not match the | |
18078 | domains precondition; the following router is always tried. If the router | |
18079 | runs, it always matches the domain and so can never decline. Therefore, | |
18080 | no_more would have no effect. In the second case, the router is never | |
18081 | skipped; it always runs. However, if it doesn't match the domain, it | |
18082 | declines. In this case no_more would prevent subsequent routers from | |
18083 | running. | |
18084 | ||
18085 | * A mail hub is a host which receives mail for a number of domains via MX | |
18086 | records in the DNS and delivers it via its own private routing mechanism. | |
18087 | Often the final destinations are behind a firewall, with the mail hub being | |
18088 | the one machine that can connect to machines both inside and outside the | |
18089 | firewall. The manualroute router is usually used on a mail hub to route | |
18090 | incoming messages to the correct hosts. For a small number of domains, the | |
18091 | routing can be inline, using the route_list option, but for a larger number | |
18092 | a file or database lookup is easier to manage. | |
18093 | ||
18094 | If the domain names are in fact the names of the machines to which the mail | |
18095 | is to be sent by the mail hub, the configuration can be quite simple. For | |
18096 | example: | |
18097 | ||
18098 | hub_route: | |
18099 | driver = manualroute | |
18100 | transport = remote_smtp | |
18101 | route_list = *.rhodes.tvs.example $domain | |
18102 | ||
18103 | This configuration routes domains that match "*.rhodes.tvs.example" to | |
18104 | hosts whose names are the same as the mail domains. A similar approach can | |
18105 | be taken if the host name can be obtained from the domain name by a string | |
18106 | manipulation that the expansion facilities can handle. Otherwise, a lookup | |
18107 | based on the domain can be used to find the host: | |
18108 | ||
18109 | through_firewall: | |
18110 | driver = manualroute | |
18111 | transport = remote_smtp | |
18112 | route_data = ${lookup {$domain} cdb {/internal/host/routes}} | |
18113 | ||
18114 | The result of the lookup must be the name or IP address of the host (or | |
18115 | hosts) to which the address is to be routed. If the lookup fails, the route | |
18116 | data is empty, causing the router to decline. The address then passes to | |
18117 | the next router. | |
18118 | ||
18119 | * You can use manualroute to deliver messages to pipes or files in batched | |
18120 | SMTP format for onward transportation by some other means. This is one way | |
18121 | of storing mail for a dial-up host when it is not connected. The route list | |
18122 | entry can be as simple as a single domain name in a configuration like | |
18123 | this: | |
18124 | ||
18125 | save_in_file: | |
18126 | driver = manualroute | |
18127 | transport = batchsmtp_appendfile | |
18128 | route_list = saved.domain.example | |
18129 | ||
18130 | though often a pattern is used to pick up more than one domain. If there | |
18131 | are several domains or groups of domains with different transport | |
18132 | requirements, different transports can be listed in the routing | |
18133 | information: | |
18134 | ||
18135 | save_in_file: | |
18136 | driver = manualroute | |
18137 | route_list = \ | |
18138 | *.saved.domain1.example $domain batch_appendfile; \ | |
18139 | *.saved.domain2.example \ | |
18140 | ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \ | |
18141 | batch_pipe | |
18142 | ||
18143 | The first of these just passes the domain in the $host variable, which | |
18144 | doesn't achieve much (since it is also in $domain), but the second does a | |
18145 | file lookup to find a value to pass, causing the router to decline to | |
18146 | handle the address if the lookup fails. | |
18147 | ||
18148 | * Routing mail directly to UUCP software is a specific case of the use of | |
18149 | manualroute in a gateway to another mail environment. This is an example of | |
18150 | one way it can be done: | |
18151 | ||
18152 | # Transport | |
18153 | uucp: | |
18154 | driver = pipe | |
18155 | user = nobody | |
18156 | command = /usr/local/bin/uux -r - \ | |
18157 | ${substr_-5:$host}!rmail ${local_part} | |
18158 | return_fail_output = true | |
18159 | ||
18160 | # Router | |
18161 | uucphost: | |
18162 | transport = uucp | |
18163 | driver = manualroute | |
18164 | route_data = \ | |
18165 | ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}} | |
18166 | ||
18167 | The file /usr/local/exim/uucphosts contains entries like | |
18168 | ||
18169 | darksite.ethereal.example: darksite.UUCP | |
18170 | ||
18171 | It can be set up more simply without adding and removing ".UUCP" but this | |
18172 | way makes clear the distinction between the domain name | |
18173 | darksite.ethereal.example and the UUCP host name darksite. | |
18174 | ||
18175 | ||
18176 | ||
18177 | =============================================================================== | |
18178 | 21. THE QUERYPROGRAM ROUTER | |
18179 | ||
18180 | The queryprogram router routes an address by running an external command and | |
18181 | acting on its output. This is an expensive way to route, and is intended mainly | |
18182 | for use in lightly-loaded systems, or for performing experiments. However, if | |
18183 | it is possible to use the precondition options (domains, local_parts, etc) to | |
18184 | skip this router for most addresses, it could sensibly be used in special | |
18185 | cases, even on a busy host. There are the following private options: | |
18186 | ||
2813c06e | 18187 | +------------------------------------------------------+ |
420a0d19 | 18188 | |command|Use: queryprogram|Type: string*|Default: unset| |
2813c06e | 18189 | +------------------------------------------------------+ |
420a0d19 CE |
18190 | |
18191 | This option must be set. It specifies the command that is to be run. The | |
18192 | command is split up into a command name and arguments, and then each is | |
18193 | expanded separately (exactly as for a pipe transport, described in chapter 29). | |
18194 | ||
2813c06e | 18195 | +-----------------------------------------------------------+ |
420a0d19 | 18196 | |command_group|Use: queryprogram|Type: string|Default: unset| |
2813c06e | 18197 | +-----------------------------------------------------------+ |
420a0d19 CE |
18198 | |
18199 | This option specifies a gid to be set when running the command while routing an | |
18200 | address for deliver. It must be set if command_user specifies a numerical uid. | |
18201 | If it begins with a digit, it is interpreted as the numerical value of the gid. | |
18202 | Otherwise it is looked up using getgrnam(). | |
18203 | ||
2813c06e | 18204 | +----------------------------------------------------------+ |
420a0d19 | 18205 | |command_user|Use: queryprogram|Type: string|Default: unset| |
2813c06e | 18206 | +----------------------------------------------------------+ |
420a0d19 CE |
18207 | |
18208 | This option must be set. It specifies the uid which is set when running the | |
18209 | command while routing an address for delivery. If the value begins with a | |
18210 | digit, it is interpreted as the numerical value of the uid. Otherwise, it is | |
18211 | looked up using getpwnam() to obtain a value for the uid and, if command_group | |
18212 | is not set, a value for the gid also. | |
18213 | ||
18214 | Warning: Changing uid and gid is possible only when Exim is running as root, | |
18215 | which it does during a normal delivery in a conventional configuration. | |
18216 | However, when an address is being verified during message reception, Exim is | |
18217 | usually running as the Exim user, not as root. If the queryprogram router is | |
18218 | called from a non-root process, Exim cannot change uid or gid before running | |
18219 | the command. In this circumstance the command runs under the current uid and | |
18220 | gid. | |
18221 | ||
2813c06e | 18222 | +-----------------------------------------------------------+ |
420a0d19 | 18223 | |current_directory|Use: queryprogram|Type: string|Default: /| |
2813c06e | 18224 | +-----------------------------------------------------------+ |
420a0d19 CE |
18225 | |
18226 | This option specifies an absolute path which is made the current directory | |
18227 | before running the command. | |
18228 | ||
2813c06e | 18229 | +------------------------------------------------+ |
420a0d19 | 18230 | |timeout|Use: queryprogram|Type: time|Default: 1h| |
2813c06e | 18231 | +------------------------------------------------+ |
420a0d19 CE |
18232 | |
18233 | If the command does not complete within the timeout period, its process group | |
18234 | is killed and the message is frozen. A value of zero time specifies no timeout. | |
18235 | ||
18236 | The standard output of the command is connected to a pipe, which is read when | |
18237 | the command terminates. It should consist of a single line of output, | |
18238 | containing up to five fields, separated by white space. The maximum length of | |
18239 | the line is 1023 characters. Longer lines are silently truncated. The first | |
18240 | field is one of the following words (case-insensitive): | |
18241 | ||
18242 | * Accept: routing succeeded; the remaining fields specify what to do (see | |
18243 | below). | |
18244 | ||
18245 | * Decline: the router declines; pass the address to the next router, unless | |
18246 | no_more is set. | |
18247 | ||
18248 | * Fail: routing failed; do not pass the address to any more routers. Any | |
18249 | subsequent text on the line is an error message. If the router is run as | |
18250 | part of address verification during an incoming SMTP message, the message | |
18251 | is included in the SMTP response. | |
18252 | ||
18253 | * Defer: routing could not be completed at this time; try again later. Any | |
18254 | subsequent text on the line is an error message which is logged. It is not | |
18255 | included in any SMTP response. | |
18256 | ||
18257 | * Freeze: the same as defer, except that the message is frozen. | |
18258 | ||
18259 | * Pass: pass the address to the next router (or the router specified by | |
18260 | pass_router), overriding no_more. | |
18261 | ||
18262 | * Redirect: the message is redirected. The remainder of the line is a list of | |
18263 | new addresses, which are routed independently, starting with the first | |
18264 | router, or the router specified by redirect_router, if set. | |
18265 | ||
18266 | When the first word is accept, the remainder of the line consists of a number | |
18267 | of keyed data values, as follows (split into two lines here, to fit on the | |
18268 | page): | |
18269 | ||
18270 | ACCEPT TRANSPORT=<transport> HOSTS=<list of hosts> | |
18271 | LOOKUP=byname|bydns DATA=<text> | |
18272 | ||
18273 | The data items can be given in any order, and all are optional. If no transport | |
18274 | is included, the transport specified by the generic transport option is used. | |
18275 | The list of hosts and the lookup type are needed only if the transport is an | |
18276 | smtp transport that does not itself supply a list of hosts. | |
18277 | ||
18278 | The format of the list of hosts is the same as for the manualroute router. As | |
18279 | well as host names and IP addresses with optional port numbers, as described in | |
18280 | section 20.5, it may contain names followed by "/MX" to specify sublists of | |
18281 | hosts that are obtained by looking up MX records (see section 20.6). | |
18282 | ||
18283 | If the lookup type is not specified, Exim behaves as follows when trying to | |
18284 | find an IP address for each host: First, a DNS lookup is done. If this yields | |
18285 | anything other than HOST_NOT_FOUND, that result is used. Otherwise, Exim goes | |
18286 | on to try a call to getipnodebyname() or gethostbyname(), and the result of the | |
18287 | lookup is the result of that call. | |
18288 | ||
18289 | If the DATA field is set, its value is placed in the $address_data variable. | |
18290 | For example, this return line | |
18291 | ||
18292 | accept hosts=x1.y.example:x2.y.example data="rule1" | |
18293 | ||
18294 | routes the address to the default transport, passing a list of two hosts. When | |
18295 | the transport runs, the string "rule1" is in $address_data. | |
18296 | ||
18297 | ||
18298 | ||
18299 | =============================================================================== | |
18300 | 22. THE REDIRECT ROUTER | |
18301 | ||
18302 | The redirect router handles several kinds of address redirection. Its most | |
18303 | common uses are for resolving local part aliases from a central alias file | |
18304 | (usually called /etc/aliases) and for handling users' personal .forward files, | |
18305 | but it has many other potential uses. The incoming address can be redirected in | |
18306 | several different ways: | |
18307 | ||
18308 | * It can be replaced by one or more new addresses which are themselves routed | |
18309 | independently. | |
18310 | ||
18311 | * It can be routed to be delivered to a given file or directory. | |
18312 | ||
18313 | * It can be routed to be delivered to a specified pipe command. | |
18314 | ||
18315 | * It can cause an automatic reply to be generated. | |
18316 | ||
18317 | * It can be forced to fail, optionally with a custom error message. | |
18318 | ||
18319 | * It can be temporarily deferred, optionally with a custom message. | |
18320 | ||
18321 | * It can be discarded. | |
18322 | ||
18323 | The generic transport option must not be set for redirect routers. However, | |
18324 | there are some private options which define transports for delivery to files | |
18325 | and pipes, and for generating autoreplies. See the file_transport, | |
18326 | pipe_transport and reply_transport descriptions below. | |
18327 | ||
2813c06e CE |
18328 | If success DSNs have been requested redirection triggers one and the DSN |
18329 | options are not passed any further. | |
18330 | ||
420a0d19 CE |
18331 | |
18332 | 22.1 Redirection data | |
18333 | --------------------- | |
18334 | ||
18335 | The router operates by interpreting a text string which it obtains either by | |
18336 | expanding the contents of the data option, or by reading the entire contents of | |
18337 | a file whose name is given in the file option. These two options are mutually | |
18338 | exclusive. The first is commonly used for handling system aliases, in a | |
18339 | configuration like this: | |
18340 | ||
18341 | system_aliases: | |
18342 | driver = redirect | |
18343 | data = ${lookup{$local_part}lsearch{/etc/aliases}} | |
18344 | ||
18345 | If the lookup fails, the expanded string in this example is empty. When the | |
18346 | expansion of data results in an empty string, the router declines. A forced | |
18347 | expansion failure also causes the router to decline; other expansion failures | |
18348 | cause delivery to be deferred. | |
18349 | ||
18350 | A configuration using file is commonly used for handling users' .forward files, | |
18351 | like this: | |
18352 | ||
18353 | userforward: | |
18354 | driver = redirect | |
18355 | check_local_user | |
18356 | file = $home/.forward | |
18357 | no_verify | |
18358 | ||
18359 | If the file does not exist, or causes no action to be taken (for example, it is | |
18360 | empty or consists only of comments), the router declines. Warning: This is not | |
18361 | the case when the file contains syntactically valid items that happen to yield | |
18362 | empty addresses, for example, items containing only RFC 2822 address comments. | |
18363 | ||
18364 | ||
18365 | 22.2 Forward files and address verification | |
18366 | ------------------------------------------- | |
18367 | ||
18368 | It is usual to set no_verify on redirect routers which handle users' .forward | |
18369 | files, as in the example above. There are two reasons for this: | |
18370 | ||
18371 | * When Exim is receiving an incoming SMTP message from a remote host, it is | |
18372 | running under the Exim uid, not as root. Exim is unable to change uid to | |
18373 | read the file as the user, and it may not be able to read it as the Exim | |
18374 | user. So in practice the router may not be able to operate. | |
18375 | ||
18376 | * However, even when the router can operate, the existence of a .forward file | |
18377 | is unimportant when verifying an address. What should be checked is whether | |
18378 | the local part is a valid user name or not. Cutting out the redirection | |
18379 | processing saves some resources. | |
18380 | ||
18381 | ||
18382 | 22.3 Interpreting redirection data | |
18383 | ---------------------------------- | |
18384 | ||
18385 | The contents of the data string, whether obtained from data or file, can be | |
18386 | interpreted in two different ways: | |
18387 | ||
18388 | * If the allow_filter option is set true, and the data begins with the text " | |
18389 | #Exim filter" or "#Sieve filter", it is interpreted as a list of filtering | |
18390 | instructions in the form of an Exim or Sieve filter file, respectively. | |
18391 | Details of the syntax and semantics of filter files are described in a | |
18392 | separate document entitled Exim's interfaces to mail filtering; this | |
18393 | document is intended for use by end users. | |
18394 | ||
18395 | * Otherwise, the data must be a comma-separated list of redirection items, as | |
18396 | described in the next section. | |
18397 | ||
18398 | When a message is redirected to a file (a "mail folder"), the file name given | |
18399 | in a non-filter redirection list must always be an absolute path. A filter may | |
18400 | generate a relative path - how this is handled depends on the transport's | |
18401 | configuration. See section 26.1 for a discussion of this issue for the | |
18402 | appendfile transport. | |
18403 | ||
18404 | ||
18405 | 22.4 Items in a non-filter redirection list | |
18406 | ------------------------------------------- | |
18407 | ||
18408 | When the redirection data is not an Exim or Sieve filter, for example, if it | |
18409 | comes from a conventional alias or forward file, it consists of a list of | |
18410 | addresses, file names, pipe commands, or certain special items (see section | |
18411 | 22.6 below). The special items can be individually enabled or disabled by means | |
18412 | of options whose names begin with allow_ or forbid_, depending on their default | |
18413 | values. The items in the list are separated by commas or newlines. If a comma | |
18414 | is required in an item, the entire item must be enclosed in double quotes. | |
18415 | ||
18416 | Lines starting with a # character are comments, and are ignored, and # may also | |
18417 | appear following a comma, in which case everything between the # and the next | |
18418 | newline character is ignored. | |
18419 | ||
18420 | If an item is entirely enclosed in double quotes, these are removed. Otherwise | |
18421 | double quotes are retained because some forms of mail address require their use | |
18422 | (but never to enclose the entire address). In the following description, "item" | |
18423 | refers to what remains after any surrounding double quotes have been removed. | |
18424 | ||
18425 | Warning: If you use an Exim expansion to construct a redirection address, and | |
18426 | the expansion contains a reference to $local_part, you should make use of the | |
18427 | quote_local_part expansion operator, in case the local part contains special | |
18428 | characters. For example, to redirect all mail for the domain obsolete.example, | |
18429 | retaining the existing local part, you could use this setting: | |
18430 | ||
18431 | data = ${quote_local_part:$local_part}@newdomain.example | |
18432 | ||
18433 | ||
18434 | 22.5 Redirecting to a local mailbox | |
18435 | ----------------------------------- | |
18436 | ||
18437 | A redirection item may safely be the same as the address currently under | |
18438 | consideration. This does not cause a routing loop, because a router is | |
18439 | automatically skipped if any ancestor of the address that is being processed is | |
18440 | the same as the current address and was processed by the current router. Such | |
18441 | an address is therefore passed to the following routers, so it is handled as if | |
18442 | there were no redirection. When making this loop-avoidance test, the complete | |
18443 | local part, including any prefix or suffix, is used. | |
18444 | ||
18445 | Specifying the same local part without a domain is a common usage in personal | |
18446 | filter files when the user wants to have messages delivered to the local | |
18447 | mailbox and also forwarded elsewhere. For example, the user whose login is cleo | |
18448 | might have a .forward file containing this: | |
18449 | ||
18450 | cleo, cleopatra@egypt.example | |
18451 | ||
18452 | For compatibility with other MTAs, such unqualified local parts may be preceded | |
18453 | by "\", but this is not a requirement for loop prevention. However, it does | |
18454 | make a difference if more than one domain is being handled synonymously. | |
18455 | ||
18456 | If an item begins with "\" and the rest of the item parses as a valid RFC 2822 | |
18457 | address that does not include a domain, the item is qualified using the domain | |
18458 | of the incoming address. In the absence of a leading "\", unqualified addresses | |
18459 | are qualified using the value in qualify_recipient, but you can force the | |
18460 | incoming domain to be used by setting qualify_preserve_domain. | |
18461 | ||
18462 | Care must be taken if there are alias names for local users. Consider an MTA | |
18463 | handling a single local domain where the system alias file contains: | |
18464 | ||
18465 | Sam.Reman: spqr | |
18466 | ||
18467 | Now suppose that Sam (whose login id is spqr) wants to save copies of messages | |
18468 | in the local mailbox, and also forward copies elsewhere. He creates this | |
18469 | forward file: | |
18470 | ||
18471 | Sam.Reman, spqr@reme.elsewhere.example | |
18472 | ||
18473 | With these settings, an incoming message addressed to Sam.Reman fails. The | |
18474 | redirect router for system aliases does not process Sam.Reman the second time | |
18475 | round, because it has previously routed it, and the following routers | |
18476 | presumably cannot handle the alias. The forward file should really contain | |
18477 | ||
18478 | spqr, spqr@reme.elsewhere.example | |
18479 | ||
18480 | but because this is such a common error, the check_ancestor option (see below) | |
18481 | exists to provide a way to get round it. This is normally set on a redirect | |
18482 | router that is handling users' .forward files. | |
18483 | ||
18484 | ||
18485 | 22.6 Special items in redirection lists | |
18486 | --------------------------------------- | |
18487 | ||
18488 | In addition to addresses, the following types of item may appear in redirection | |
18489 | lists (that is, in non-filter redirection data): | |
18490 | ||
18491 | * An item is treated as a pipe command if it begins with "|" and does not | |
18492 | parse as a valid RFC 2822 address that includes a domain. A transport for | |
18493 | running the command must be specified by the pipe_transport option. | |
18494 | Normally, either the router or the transport specifies a user and a group | |
18495 | under which to run the delivery. The default is to use the Exim user and | |
18496 | group. | |
18497 | ||
18498 | Single or double quotes can be used for enclosing the individual arguments | |
18499 | of the pipe command; no interpretation of escapes is done for single | |
18500 | quotes. If the command contains a comma character, it is necessary to put | |
18501 | the whole item in double quotes, for example: | |
18502 | ||
18503 | "|/some/command ready,steady,go" | |
18504 | ||
18505 | since items in redirection lists are terminated by commas. Do not, however, | |
18506 | quote just the command. An item such as | |
18507 | ||
18508 | |"/some/command ready,steady,go" | |
18509 | ||
18510 | is interpreted as a pipe with a rather strange command name, and no | |
18511 | arguments. | |
18512 | ||
18513 | Note that the above example assumes that the text comes from a lookup | |
18514 | source of some sort, so that the quotes are part of the data. If composing | |
18515 | a redirect router with a data option directly specifying this command, the | |
18516 | quotes will be used by the configuration parser to define the extent of one | |
18517 | string, but will not be passed down into the redirect router itself. There | |
18518 | are two main approaches to get around this: escape quotes to be part of the | |
18519 | data itself, or avoid using this mechanism and instead create a custom | |
18520 | transport with the command option set and reference that transport from an | |
18521 | accept router. | |
18522 | ||
18523 | * An item is interpreted as a path name if it begins with "/" and does not | |
18524 | parse as a valid RFC 2822 address that includes a domain. For example, | |
18525 | ||
18526 | /home/world/minbari | |
18527 | ||
18528 | is treated as a file name, but | |
18529 | ||
18530 | /s=molari/o=babylon/@x400gate.way | |
18531 | ||
18532 | is treated as an address. For a file name, a transport must be specified | |
18533 | using the file_transport option. However, if the generated path name ends | |
18534 | with a forward slash character, it is interpreted as a directory name | |
18535 | rather than a file name, and directory_transport is used instead. | |
18536 | ||
18537 | Normally, either the router or the transport specifies a user and a group | |
18538 | under which to run the delivery. The default is to use the Exim user and | |
18539 | group. | |
18540 | ||
18541 | However, if a redirection item is the path /dev/null, delivery to it is | |
18542 | bypassed at a high level, and the log entry shows "**bypassed**" instead of | |
18543 | a transport name. In this case the user and group are not used. | |
18544 | ||
18545 | * If an item is of the form | |
18546 | ||
18547 | :include:<path name> | |
18548 | ||
18549 | a list of further items is taken from the given file and included at that | |
18550 | point. Note: Such a file can not be a filter file; it is just an | |
18551 | out-of-line addition to the list. The items in the included list are | |
18552 | separated by commas or newlines and are not subject to expansion. If this | |
18553 | is the first item in an alias list in an lsearch file, a colon must be used | |
18554 | to terminate the alias name. This example is incorrect: | |
18555 | ||
18556 | list1 :include:/opt/lists/list1 | |
18557 | ||
18558 | It must be given as | |
18559 | ||
18560 | list1: :include:/opt/lists/list1 | |
18561 | ||
18562 | * Sometimes you want to throw away mail to a particular local part. Making | |
18563 | the data option expand to an empty string does not work, because that | |
2813c06e CE |
18564 | causes the router to decline. Instead, the alias item |
18565 | ||
18566 | :blackhole: | |
18567 | ||
18568 | can be used. It does what its name implies. No delivery is done, and no | |
18569 | error message is generated. This has the same effect as specifying /dev/ | |
18570 | null as a destination, but it can be independently disabled. | |
420a0d19 CE |
18571 | |
18572 | Warning: If :blackhole: appears anywhere in a redirection list, no delivery | |
18573 | is done for the original local part, even if other redirection items are | |
18574 | present. If you are generating a multi-item list (for example, by reading a | |
18575 | database) and need the ability to provide a no-op item, you must use /dev/ | |
18576 | null. | |
18577 | ||
18578 | * An attempt to deliver a particular address can be deferred or forced to | |
18579 | fail by redirection items of the form | |
18580 | ||
18581 | :defer: | |
18582 | :fail: | |
18583 | ||
18584 | respectively. When a redirection list contains such an item, it applies to | |
18585 | the entire redirection; any other items in the list are ignored. Any text | |
18586 | following :fail: or :defer: is placed in the error text associated with the | |
18587 | failure. For example, an alias file might contain: | |
18588 | ||
18589 | X.Employee: :fail: Gone away, no forwarding address | |
18590 | ||
18591 | In the case of an address that is being verified from an ACL or as the | |
18592 | subject of a VRFY command, the text is included in the SMTP error response | |
18593 | by default. The text is not included in the response to an EXPN command. In | |
18594 | non-SMTP cases the text is included in the error message that Exim | |
18595 | generates. | |
18596 | ||
18597 | By default, Exim sends a 451 SMTP code for a :defer:, and 550 for :fail:. | |
18598 | However, if the message starts with three digits followed by a space, | |
18599 | optionally followed by an extended code of the form n.n.n, also followed by | |
18600 | a space, and the very first digit is the same as the default error code, | |
18601 | the code from the message is used instead. If the very first digit is | |
18602 | incorrect, a panic error is logged, and the default code is used. You can | |
18603 | suppress the use of the supplied code in a redirect router by setting the | |
18604 | forbid_smtp_code option true. In this case, any SMTP code is quietly | |
18605 | ignored. | |
18606 | ||
18607 | In an ACL, an explicitly provided message overrides the default, but the | |
18608 | default message is available in the variable $acl_verify_message and can | |
18609 | therefore be included in a custom message if this is desired. | |
18610 | ||
18611 | Normally the error text is the rest of the redirection list - a comma does | |
18612 | not terminate it - but a newline does act as a terminator. Newlines are not | |
18613 | normally present in alias expansions. In lsearch lookups they are removed | |
18614 | as part of the continuation process, but they may exist in other kinds of | |
18615 | lookup and in :include: files. | |
18616 | ||
18617 | During routing for message delivery (as opposed to verification), a | |
18618 | redirection containing :fail: causes an immediate failure of the incoming | |
18619 | address, whereas :defer: causes the message to remain on the queue so that | |
18620 | a subsequent delivery attempt can happen at a later time. If an address is | |
18621 | deferred for too long, it will ultimately fail, because the normal retry | |
18622 | rules still apply. | |
18623 | ||
18624 | * Sometimes it is useful to use a single-key search type with a default (see | |
18625 | chapter 9) to look up aliases. However, there may be a need for exceptions | |
18626 | to the default. These can be handled by aliasing them to :unknown:. This | |
18627 | differs from :fail: in that it causes the redirect router to decline, | |
18628 | whereas :fail: forces routing to fail. A lookup which results in an empty | |
18629 | redirection list has the same effect. | |
18630 | ||
18631 | ||
18632 | 22.7 Duplicate addresses | |
18633 | ------------------------ | |
18634 | ||
18635 | Exim removes duplicate addresses from the list to which it is delivering, so as | |
18636 | to deliver just one copy to each address. This does not apply to deliveries | |
18637 | routed to pipes by different immediate parent addresses, but an indirect | |
18638 | aliasing scheme of the type | |
18639 | ||
18640 | pipe: |/some/command $local_part | |
18641 | localpart1: pipe | |
18642 | localpart2: pipe | |
18643 | ||
18644 | does not work with a message that is addressed to both local parts, because | |
18645 | when the second is aliased to the intermediate local part "pipe" it gets | |
18646 | discarded as being the same as a previously handled address. However, a scheme | |
18647 | such as | |
18648 | ||
18649 | localpart1: |/some/command $local_part | |
18650 | localpart2: |/some/command $local_part | |
18651 | ||
18652 | does result in two different pipe deliveries, because the immediate parents of | |
18653 | the pipes are distinct. | |
18654 | ||
18655 | ||
18656 | 22.8 Repeated redirection expansion | |
18657 | ----------------------------------- | |
18658 | ||
18659 | When a message cannot be delivered to all of its recipients immediately, | |
18660 | leading to two or more delivery attempts, redirection expansion is carried out | |
18661 | afresh each time for those addresses whose children were not all previously | |
18662 | delivered. If redirection is being used as a mailing list, this can lead to new | |
18663 | members of the list receiving copies of old messages. The one_time option can | |
18664 | be used to avoid this. | |
18665 | ||
18666 | ||
18667 | 22.9 Errors in redirection lists | |
18668 | -------------------------------- | |
18669 | ||
18670 | If skip_syntax_errors is set, a malformed address that causes a parsing error | |
18671 | is skipped, and an entry is written to the main log. This may be useful for | |
18672 | mailing lists that are automatically managed. Otherwise, if an error is | |
18673 | detected while generating the list of new addresses, the original address is | |
18674 | deferred. See also syntax_errors_to. | |
18675 | ||
18676 | ||
18677 | 22.10 Private options for the redirect router | |
18678 | --------------------------------------------- | |
18679 | ||
18680 | The private options for the redirect router are as follows: | |
18681 | ||
2813c06e | 18682 | +------------------------------------------------------+ |
420a0d19 | 18683 | |allow_defer|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18684 | +------------------------------------------------------+ |
420a0d19 CE |
18685 | |
18686 | Setting this option allows the use of :defer: in non-filter redirection data, | |
18687 | or the defer command in an Exim filter file. | |
18688 | ||
2813c06e | 18689 | +-----------------------------------------------------+ |
420a0d19 | 18690 | |allow_fail|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18691 | +-----------------------------------------------------+ |
420a0d19 CE |
18692 | |
18693 | If this option is true, the :fail: item can be used in a redirection list, and | |
18694 | the fail command may be used in an Exim filter file. | |
18695 | ||
2813c06e | 18696 | +-------------------------------------------------------+ |
420a0d19 | 18697 | |allow_filter|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18698 | +-------------------------------------------------------+ |
420a0d19 CE |
18699 | |
18700 | Setting this option allows Exim to interpret redirection data that starts with | |
18701 | "#Exim filter" or "#Sieve filter" as a set of filtering instructions. There are | |
18702 | some features of Exim filter files that some administrators may wish to lock | |
18703 | out; see the forbid_filter_xxx options below. | |
18704 | ||
18705 | It is also possible to lock out Exim filters or Sieve filters while allowing | |
18706 | the other type; see forbid_exim_filter and forbid_sieve_filter. | |
18707 | ||
18708 | The filter is run using the uid and gid set by the generic user and group | |
18709 | options. These take their defaults from the password data if check_local_user | |
18710 | is set, so in the normal case of users' personal filter files, the filter is | |
18711 | run as the relevant user. When allow_filter is set true, Exim insists that | |
18712 | either check_local_user or user is set. | |
18713 | ||
2813c06e | 18714 | +-------------------------------------------------------+ |
420a0d19 | 18715 | |allow_freeze|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18716 | +-------------------------------------------------------+ |
420a0d19 CE |
18717 | |
18718 | Setting this option allows the use of the freeze command in an Exim filter. | |
18719 | This command is more normally encountered in system filters, and is disabled by | |
18720 | default for redirection filters because it isn't something you usually want to | |
18721 | let ordinary users do. | |
18722 | ||
2813c06e | 18723 | +---------------------------------------------------------+ |
420a0d19 | 18724 | |check_ancestor|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18725 | +---------------------------------------------------------+ |
420a0d19 CE |
18726 | |
18727 | This option is concerned with handling generated addresses that are the same as | |
18728 | some address in the list of redirection ancestors of the current address. | |
18729 | Although it is turned off by default in the code, it is set in the default | |
18730 | configuration file for handling users' .forward files. It is recommended for | |
18731 | this use of the redirect router. | |
18732 | ||
18733 | When check_ancestor is set, if a generated address (including the domain) is | |
18734 | the same as any ancestor of the current address, it is replaced by a copy of | |
18735 | the current address. This helps in the case where local part A is aliased to B, | |
18736 | and B has a .forward file pointing back to A. For example, within a single | |
18737 | domain, the local part "Joe.Bloggs" is aliased to "jb" and jb/.forward | |
18738 | contains: | |
18739 | ||
18740 | \Joe.Bloggs, <other item(s)> | |
18741 | ||
18742 | Without the check_ancestor setting, either local part ("jb" or "joe.bloggs") | |
18743 | gets processed once by each router and so ends up as it was originally. If "jb" | |
18744 | is the real mailbox name, mail to "jb" gets delivered (having been turned into | |
18745 | "joe.bloggs" by the .forward file and back to "jb" by the alias), but mail to | |
18746 | "joe.bloggs" fails. Setting check_ancestor on the redirect router that handles | |
18747 | the .forward file prevents it from turning "jb" back into "joe.bloggs" when | |
18748 | that was the original address. See also the repeat_use option below. | |
18749 | ||
2813c06e | 18750 | +----------------------------------------------------------+ |
420a0d19 | 18751 | |check_group|Use: redirect|Type: boolean|Default: see below| |
2813c06e | 18752 | +----------------------------------------------------------+ |
420a0d19 CE |
18753 | |
18754 | When the file option is used, the group owner of the file is checked only when | |
18755 | this option is set. The permitted groups are those listed in the owngroups | |
18756 | option, together with the user's default group if check_local_user is set. If | |
18757 | the file has the wrong group, routing is deferred. The default setting for this | |
18758 | option is true if check_local_user is set and the modemask option permits the | |
18759 | group write bit, or if the owngroups option is set. Otherwise it is false, and | |
18760 | no group check occurs. | |
18761 | ||
2813c06e | 18762 | +----------------------------------------------------------+ |
420a0d19 | 18763 | |check_owner|Use: redirect|Type: boolean|Default: see below| |
2813c06e | 18764 | +----------------------------------------------------------+ |
420a0d19 CE |
18765 | |
18766 | When the file option is used, the owner of the file is checked only when this | |
18767 | option is set. If check_local_user is set, the local user is permitted; | |
18768 | otherwise the owner must be one of those listed in the owners option. The | |
18769 | default value for this option is true if check_local_user or owners is set. | |
18770 | Otherwise the default is false, and no owner check occurs. | |
18771 | ||
2813c06e | 18772 | +-----------------------------------------------+ |
420a0d19 | 18773 | |data|Use: redirect|Type: string*|Default: unset| |
2813c06e | 18774 | +-----------------------------------------------+ |
420a0d19 CE |
18775 | |
18776 | This option is mutually exclusive with file. One or other of them must be set, | |
18777 | but not both. The contents of data are expanded, and then used as the list of | |
18778 | forwarding items, or as a set of filtering instructions. If the expansion is | |
18779 | forced to fail, or the result is an empty string or a string that has no effect | |
18780 | (consists entirely of comments), the router declines. | |
18781 | ||
18782 | When filtering instructions are used, the string must begin with "#Exim | |
18783 | filter", and all comments in the string, including this initial one, must be | |
18784 | terminated with newline characters. For example: | |
18785 | ||
18786 | data = #Exim filter\n\ | |
18787 | if $h_to: contains Exim then save $home/mail/exim endif | |
18788 | ||
18789 | If you are reading the data from a database where newlines cannot be included, | |
18790 | you can use the ${sg} expansion item to turn the escape string of your choice | |
18791 | into a newline. | |
18792 | ||
2813c06e | 18793 | +--------------------------------------------------------------+ |
420a0d19 | 18794 | |directory_transport|Use: redirect|Type: string*|Default: unset| |
2813c06e | 18795 | +--------------------------------------------------------------+ |
420a0d19 CE |
18796 | |
18797 | A redirect router sets up a direct delivery to a directory when a path name | |
18798 | ending with a slash is specified as a new "address". The transport used is | |
18799 | specified by this option, which, after expansion, must be the name of a | |
18800 | configured transport. This should normally be an appendfile transport. | |
18801 | ||
2813c06e | 18802 | +-----------------------------------------------+ |
420a0d19 | 18803 | |file|Use: redirect|Type: string*|Default: unset| |
2813c06e | 18804 | +-----------------------------------------------+ |
420a0d19 CE |
18805 | |
18806 | This option specifies the name of a file that contains the redirection data. It | |
18807 | is mutually exclusive with the data option. The string is expanded before use; | |
18808 | if the expansion is forced to fail, the router declines. Other expansion | |
18809 | failures cause delivery to be deferred. The result of a successful expansion | |
18810 | must be an absolute path. The entire file is read and used as the redirection | |
18811 | data. If the data is an empty string or a string that has no effect (consists | |
18812 | entirely of comments), the router declines. | |
18813 | ||
18814 | If the attempt to open the file fails with a "does not exist" error, Exim runs | |
18815 | a check on the containing directory, unless ignore_enotdir is true (see below). | |
18816 | If the directory does not appear to exist, delivery is deferred. This can | |
18817 | happen when users' .forward files are in NFS-mounted directories, and there is | |
18818 | a mount problem. If the containing directory does exist, but the file does not, | |
18819 | the router declines. | |
18820 | ||
2813c06e | 18821 | +---------------------------------------------------------+ |
420a0d19 | 18822 | |file_transport|Use: redirect|Type: string*|Default: unset| |
2813c06e | 18823 | +---------------------------------------------------------+ |
420a0d19 CE |
18824 | |
18825 | A redirect router sets up a direct delivery to a file when a path name not | |
18826 | ending in a slash is specified as a new "address". The transport used is | |
18827 | specified by this option, which, after expansion, must be the name of a | |
18828 | configured transport. This should normally be an appendfile transport. When it | |
18829 | is running, the file name is in $address_file. | |
18830 | ||
2813c06e | 18831 | +-------------------------------------------------------------+ |
420a0d19 | 18832 | |filter_prepend_home|Use: redirect|Type: boolean|Default: true| |
2813c06e | 18833 | +-------------------------------------------------------------+ |
420a0d19 CE |
18834 | |
18835 | When this option is true, if a save command in an Exim filter specifies a | |
18836 | relative path, and $home is defined, it is automatically prepended to the | |
18837 | relative path. If this option is set false, this action does not happen. The | |
18838 | relative path is then passed to the transport unmodified. | |
18839 | ||
2813c06e | 18840 | +-----------------------------------------------------------+ |
420a0d19 | 18841 | |forbid_blackhole|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18842 | +-----------------------------------------------------------+ |
420a0d19 CE |
18843 | |
18844 | If this option is true, the :blackhole: item may not appear in a redirection | |
18845 | list. | |
18846 | ||
2813c06e | 18847 | +-------------------------------------------------------------+ |
420a0d19 | 18848 | |forbid_exim_filter|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18849 | +-------------------------------------------------------------+ |
420a0d19 CE |
18850 | |
18851 | If this option is set true, only Sieve filters are permitted when allow_filter | |
18852 | is true. | |
18853 | ||
2813c06e | 18854 | +------------------------------------------------------+ |
420a0d19 | 18855 | |forbid_file|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18856 | +------------------------------------------------------+ |
420a0d19 CE |
18857 | |
18858 | If this option is true, this router may not generate a new address that | |
18859 | specifies delivery to a local file or directory, either from a filter or from a | |
18860 | conventional forward file. This option is forced to be true if one_time is set. | |
18861 | It applies to Sieve filters as well as to Exim filters, but if true, it locks | |
18862 | out the Sieve's "keep" facility. | |
18863 | ||
2813c06e | 18864 | +---------------------------------------------------------------+ |
420a0d19 | 18865 | |forbid_filter_dlfunc|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18866 | +---------------------------------------------------------------+ |
420a0d19 CE |
18867 | |
18868 | If this option is true, string expansions in Exim filters are not allowed to | |
18869 | make use of the dlfunc expansion facility to run dynamically loaded functions. | |
18870 | ||
2813c06e | 18871 | +-------------------------------------------------------------------+ |
420a0d19 | 18872 | |forbid_filter_existstest|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18873 | +-------------------------------------------------------------------+ |
420a0d19 CE |
18874 | |
18875 | If this option is true, string expansions in Exim filters are not allowed to | |
18876 | make use of the exists condition or the stat expansion item. | |
18877 | ||
2813c06e | 18878 | +-----------------------------------------------------------------+ |
420a0d19 | 18879 | |forbid_filter_logwrite|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18880 | +-----------------------------------------------------------------+ |
420a0d19 CE |
18881 | |
18882 | If this option is true, use of the logging facility in Exim filters is not | |
18883 | permitted. Logging is in any case available only if the filter is being run | |
18884 | under some unprivileged uid (which is normally the case for ordinary users' | |
18885 | .forward files). | |
18886 | ||
2813c06e | 18887 | +---------------------------------------------------------------+ |
420a0d19 | 18888 | |forbid_filter_lookup|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18889 | +---------------------------------------------------------------+ |
420a0d19 CE |
18890 | |
18891 | If this option is true, string expansions in Exim filter files are not allowed | |
18892 | to make use of lookup items. | |
18893 | ||
2813c06e | 18894 | +-------------------------------------------------------------+ |
420a0d19 | 18895 | |forbid_filter_perl|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18896 | +-------------------------------------------------------------+ |
420a0d19 CE |
18897 | |
18898 | This option has an effect only if Exim is built with embedded Perl support. If | |
18899 | it is true, string expansions in Exim filter files are not allowed to make use | |
18900 | of the embedded Perl support. | |
18901 | ||
2813c06e | 18902 | +-----------------------------------------------------------------+ |
420a0d19 | 18903 | |forbid_filter_readfile|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18904 | +-----------------------------------------------------------------+ |
420a0d19 CE |
18905 | |
18906 | If this option is true, string expansions in Exim filter files are not allowed | |
18907 | to make use of readfile items. | |
18908 | ||
2813c06e | 18909 | +-------------------------------------------------------------------+ |
420a0d19 | 18910 | |forbid_filter_readsocket|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18911 | +-------------------------------------------------------------------+ |
420a0d19 CE |
18912 | |
18913 | If this option is true, string expansions in Exim filter files are not allowed | |
18914 | to make use of readsocket items. | |
18915 | ||
2813c06e | 18916 | +--------------------------------------------------------------+ |
420a0d19 | 18917 | |forbid_filter_reply|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18918 | +--------------------------------------------------------------+ |
420a0d19 CE |
18919 | |
18920 | If this option is true, this router may not generate an automatic reply | |
18921 | message. Automatic replies can be generated only from Exim or Sieve filter | |
18922 | files, not from traditional forward files. This option is forced to be true if | |
18923 | one_time is set. | |
18924 | ||
2813c06e | 18925 | +------------------------------------------------------------+ |
420a0d19 | 18926 | |forbid_filter_run|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18927 | +------------------------------------------------------------+ |
420a0d19 CE |
18928 | |
18929 | If this option is true, string expansions in Exim filter files are not allowed | |
18930 | to make use of run items. | |
18931 | ||
2813c06e | 18932 | +---------------------------------------------------------+ |
420a0d19 | 18933 | |forbid_include|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18934 | +---------------------------------------------------------+ |
420a0d19 CE |
18935 | |
18936 | If this option is true, items of the form | |
18937 | ||
18938 | :include:<path name> | |
18939 | ||
18940 | are not permitted in non-filter redirection lists. | |
18941 | ||
2813c06e | 18942 | +------------------------------------------------------+ |
420a0d19 | 18943 | |forbid_pipe|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18944 | +------------------------------------------------------+ |
420a0d19 CE |
18945 | |
18946 | If this option is true, this router may not generate a new address which | |
18947 | specifies delivery to a pipe, either from an Exim filter or from a conventional | |
18948 | forward file. This option is forced to be true if one_time is set. | |
18949 | ||
2813c06e | 18950 | +--------------------------------------------------------------+ |
420a0d19 | 18951 | |forbid_sieve_filter|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18952 | +--------------------------------------------------------------+ |
420a0d19 CE |
18953 | |
18954 | If this option is set true, only Exim filters are permitted when allow_filter | |
18955 | is true. | |
18956 | ||
2813c06e | 18957 | +-----------------------------------------------------------+ |
420a0d19 | 18958 | |forbid_smtp_code|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18959 | +-----------------------------------------------------------+ |
420a0d19 CE |
18960 | |
18961 | If this option is set true, any SMTP error codes that are present at the start | |
18962 | of messages specified for ":defer:" or ":fail:" are quietly ignored, and the | |
18963 | default codes (451 and 550, respectively) are always used. | |
18964 | ||
2813c06e | 18965 | +---------------------------------------------------------------+ |
420a0d19 | 18966 | |hide_child_in_errmsg|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18967 | +---------------------------------------------------------------+ |
420a0d19 CE |
18968 | |
18969 | If this option is true, it prevents Exim from quoting a child address if it | |
18970 | generates a bounce or delay message for it. Instead it says "an address | |
18971 | generated from <the top level address>". Of course, this applies only to | |
18972 | bounces generated locally. If a message is forwarded to another host, its | |
18973 | bounce may well quote the generated address. | |
18974 | ||
2813c06e | 18975 | +--------------------------------------------------------+ |
420a0d19 | 18976 | |ignore_eacces|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18977 | +--------------------------------------------------------+ |
420a0d19 CE |
18978 | |
18979 | If this option is set and an attempt to open a redirection file yields the | |
18980 | EACCES error (permission denied), the redirect router behaves as if the file | |
18981 | did not exist. | |
18982 | ||
2813c06e | 18983 | +---------------------------------------------------------+ |
420a0d19 | 18984 | |ignore_enotdir|Use: redirect|Type: boolean|Default: false| |
2813c06e | 18985 | +---------------------------------------------------------+ |
420a0d19 CE |
18986 | |
18987 | If this option is set and an attempt to open a redirection file yields the | |
18988 | ENOTDIR error (something on the path is not a directory), the redirect router | |
18989 | behaves as if the file did not exist. | |
18990 | ||
18991 | Setting ignore_enotdir has another effect as well: When a redirect router that | |
18992 | has the file option set discovers that the file does not exist (the ENOENT | |
18993 | error), it tries to stat() the parent directory, as a check against unmounted | |
18994 | NFS directories. If the parent can not be statted, delivery is deferred. | |
18995 | However, it seems wrong to do this check when ignore_enotdir is set, because | |
18996 | that option tells Exim to ignore "something on the path is not a directory" | |
18997 | (the ENOTDIR error). This is a confusing area, because it seems that some | |
18998 | operating systems give ENOENT where others give ENOTDIR. | |
18999 | ||
2813c06e | 19000 | +-----------------------------------------------------------+ |
420a0d19 | 19001 | |include_directory|Use: redirect|Type: string|Default: unset| |
2813c06e | 19002 | +-----------------------------------------------------------+ |
420a0d19 CE |
19003 | |
19004 | If this option is set, the path names of any :include: items in a redirection | |
19005 | list must start with this directory. | |
19006 | ||
2813c06e | 19007 | +-------------------------------------------------------+ |
420a0d19 | 19008 | |modemask|Use: redirect|Type: octal integer|Default: 022| |
2813c06e | 19009 | +-------------------------------------------------------+ |
420a0d19 CE |
19010 | |
19011 | This specifies mode bits which must not be set for a file specified by the file | |
19012 | option. If any of the forbidden bits are set, delivery is deferred. | |
19013 | ||
2813c06e | 19014 | +---------------------------------------------------+ |
420a0d19 | 19015 | |one_time|Use: redirect|Type: boolean|Default: false| |
2813c06e | 19016 | +---------------------------------------------------+ |
420a0d19 CE |
19017 | |
19018 | Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection | |
19019 | files each time it tries to deliver a message causes a problem when one or more | |
19020 | of the generated addresses fails be delivered at the first attempt. The problem | |
19021 | is not one of duplicate delivery - Exim is clever enough to handle that - but | |
19022 | of what happens when the redirection list changes during the time that the | |
19023 | message is on Exim's queue. This is particularly true in the case of mailing | |
19024 | lists, where new subscribers might receive copies of messages that were posted | |
19025 | before they subscribed. | |
19026 | ||
19027 | If one_time is set and any addresses generated by the router fail to deliver at | |
19028 | the first attempt, the failing addresses are added to the message as "top | |
19029 | level" addresses, and the parent address that generated them is marked | |
19030 | "delivered". Thus, redirection does not happen again at the next delivery | |
19031 | attempt. | |
19032 | ||
19033 | Warning 1: Any header line addition or removal that is specified by this router | |
19034 | would be lost if delivery did not succeed at the first attempt. For this | |
19035 | reason, the headers_add and headers_remove generic options are not permitted | |
19036 | when one_time is set. | |
19037 | ||
19038 | Warning 2: To ensure that the router generates only addresses (as opposed to | |
19039 | pipe or file deliveries or auto-replies) forbid_file, forbid_pipe, and | |
19040 | forbid_filter_reply are forced to be true when one_time is set. | |
19041 | ||
19042 | Warning 3: The unseen generic router option may not be set with one_time. | |
19043 | ||
19044 | The original top-level address is remembered with each of the generated | |
19045 | addresses, and is output in any log messages. However, any intermediate parent | |
19046 | addresses are not recorded. This makes a difference to the log only if | |
19047 | all_parents log selector is set. It is expected that one_time will typically be | |
19048 | used for mailing lists, where there is normally just one level of expansion. | |
19049 | ||
2813c06e | 19050 | +-----------------------------------------------------+ |
420a0d19 | 19051 | |owners|Use: redirect|Type: string list|Default: unset| |
2813c06e | 19052 | +-----------------------------------------------------+ |
420a0d19 CE |
19053 | |
19054 | This specifies a list of permitted owners for the file specified by file. This | |
19055 | list is in addition to the local user when check_local_user is set. See | |
19056 | check_owner above. | |
19057 | ||
2813c06e | 19058 | +--------------------------------------------------------+ |
420a0d19 | 19059 | |owngroups|Use: redirect|Type: string list|Default: unset| |
2813c06e | 19060 | +--------------------------------------------------------+ |
420a0d19 CE |
19061 | |
19062 | This specifies a list of permitted groups for the file specified by file. The | |
19063 | list is in addition to the local user's primary group when check_local_user is | |
19064 | set. See check_group above. | |
19065 | ||
2813c06e | 19066 | +---------------------------------------------------------+ |
420a0d19 | 19067 | |pipe_transport|Use: redirect|Type: string*|Default: unset| |
2813c06e | 19068 | +---------------------------------------------------------+ |
420a0d19 CE |
19069 | |
19070 | A redirect router sets up a direct delivery to a pipe when a string starting | |
19071 | with a vertical bar character is specified as a new "address". The transport | |
19072 | used is specified by this option, which, after expansion, must be the name of a | |
19073 | configured transport. This should normally be a pipe transport. When the | |
19074 | transport is run, the pipe command is in $address_pipe. | |
19075 | ||
2813c06e | 19076 | +---------------------------------------------------------+ |
420a0d19 | 19077 | |qualify_domain|Use: redirect|Type: string*|Default: unset| |
2813c06e | 19078 | +---------------------------------------------------------+ |
420a0d19 CE |
19079 | |
19080 | If this option is set, and an unqualified address (one without a domain) is | |
19081 | generated, and that address would normally be qualified by the global setting | |
19082 | in qualify_recipient, it is instead qualified with the domain specified by | |
19083 | expanding this string. If the expansion fails, the router declines. If you want | |
19084 | to revert to the default, you can have the expansion generate | |
19085 | $qualify_recipient. | |
19086 | ||
19087 | This option applies to all unqualified addresses generated by Exim filters, but | |
19088 | for traditional .forward files, it applies only to addresses that are not | |
19089 | preceded by a backslash. Sieve filters cannot generate unqualified addresses. | |
19090 | ||
2813c06e | 19091 | +------------------------------------------------------------------+ |
420a0d19 | 19092 | |qualify_preserve_domain|Use: redirect|Type: boolean|Default: false| |
2813c06e | 19093 | +------------------------------------------------------------------+ |
420a0d19 CE |
19094 | |
19095 | If this option is set, the router's local qualify_domain option must not be set | |
19096 | (a configuration error occurs if it is). If an unqualified address (one without | |
19097 | a domain) is generated, it is qualified with the domain of the parent address | |
19098 | (the immediately preceding ancestor) instead of the global qualify_recipient | |
19099 | value. In the case of a traditional .forward file, this applies whether or not | |
19100 | the address is preceded by a backslash. | |
19101 | ||
2813c06e | 19102 | +----------------------------------------------------+ |
420a0d19 | 19103 | |repeat_use|Use: redirect|Type: boolean|Default: true| |
2813c06e | 19104 | +----------------------------------------------------+ |
420a0d19 CE |
19105 | |
19106 | If this option is set false, the router is skipped for a child address that has | |
19107 | any ancestor that was routed by this router. This test happens before any of | |
19108 | the other preconditions are tested. Exim's default anti-looping rules skip only | |
19109 | when the ancestor is the same as the current address. See also check_ancestor | |
19110 | above and the generic redirect_router option. | |
19111 | ||
2813c06e | 19112 | +----------------------------------------------------------+ |
420a0d19 | 19113 | |reply_transport|Use: redirect|Type: string*|Default: unset| |
2813c06e | 19114 | +----------------------------------------------------------+ |
420a0d19 CE |
19115 | |
19116 | A redirect router sets up an automatic reply when a mail or vacation command is | |
19117 | used in a filter file. The transport used is specified by this option, which, | |
19118 | after expansion, must be the name of a configured transport. This should | |
19119 | normally be an autoreply transport. Other transports are unlikely to do | |
19120 | anything sensible or useful. | |
19121 | ||
2813c06e | 19122 | +-------------------------------------------------+ |
420a0d19 | 19123 | |rewrite|Use: redirect|Type: boolean|Default: true| |
2813c06e | 19124 | +-------------------------------------------------+ |
420a0d19 CE |
19125 | |
19126 | If this option is set false, addresses generated by the router are not subject | |
19127 | to address rewriting. Otherwise, they are treated like new addresses and are | |
19128 | rewritten according to the global rewriting rules. | |
19129 | ||
2813c06e | 19130 | +-----------------------------------------------------------+ |
420a0d19 | 19131 | |sieve_subaddress|Use: redirect|Type: string*|Default: unset| |
2813c06e | 19132 | +-----------------------------------------------------------+ |
420a0d19 CE |
19133 | |
19134 | The value of this option is passed to a Sieve filter to specify the :subaddress | |
19135 | part of an address. | |
19136 | ||
2813c06e | 19137 | +------------------------------------------------------------+ |
420a0d19 | 19138 | |sieve_useraddress|Use: redirect|Type: string*|Default: unset| |
2813c06e | 19139 | +------------------------------------------------------------+ |
420a0d19 CE |
19140 | |
19141 | The value of this option is passed to a Sieve filter to specify the :user part | |
19142 | of an address. However, if it is unset, the entire original local part | |
19143 | (including any prefix or suffix) is used for :user. | |
19144 | ||
2813c06e | 19145 | +-------------------------------------------------------------------+ |
420a0d19 | 19146 | |sieve_vacation_directory|Use: redirect|Type: string*|Default: unset| |
2813c06e | 19147 | +-------------------------------------------------------------------+ |
420a0d19 CE |
19148 | |
19149 | To enable the "vacation" extension for Sieve filters, you must set | |
19150 | sieve_vacation_directory to the directory where vacation databases are held (do | |
19151 | not put anything else in that directory), and ensure that the reply_transport | |
19152 | option refers to an autoreply transport. Each user needs their own directory; | |
19153 | Exim will create it if necessary. | |
19154 | ||
2813c06e | 19155 | +-------------------------------------------------------------+ |
420a0d19 | 19156 | |skip_syntax_errors|Use: redirect|Type: boolean|Default: false| |
2813c06e | 19157 | +-------------------------------------------------------------+ |
420a0d19 CE |
19158 | |
19159 | If skip_syntax_errors is set, syntactically malformed addresses in non-filter | |
19160 | redirection data are skipped, and each failing address is logged. If | |
19161 | syntax_errors_to is set, a message is sent to the address it defines, giving | |
19162 | details of the failures. If syntax_errors_text is set, its contents are | |
19163 | expanded and placed at the head of the error message generated by | |
19164 | syntax_errors_to. Usually it is appropriate to set syntax_errors_to to be the | |
19165 | same address as the generic errors_to option. The skip_syntax_errors option is | |
19166 | often used when handling mailing lists. | |
19167 | ||
19168 | If all the addresses in a redirection list are skipped because of syntax | |
19169 | errors, the router declines to handle the original address, and it is passed to | |
19170 | the following routers. | |
19171 | ||
19172 | If skip_syntax_errors is set when an Exim filter is interpreted, any syntax | |
19173 | error in the filter causes filtering to be abandoned without any action being | |
19174 | taken. The incident is logged, and the router declines to handle the address, | |
19175 | so it is passed to the following routers. | |
19176 | ||
19177 | Syntax errors in a Sieve filter file cause the "keep" action to occur. This | |
19178 | action is specified by RFC 3028. The values of skip_syntax_errors, | |
19179 | syntax_errors_to, and syntax_errors_text are not used. | |
19180 | ||
19181 | skip_syntax_errors can be used to specify that errors in users' forward lists | |
19182 | or filter files should not prevent delivery. The syntax_errors_to option, used | |
19183 | with an address that does not get redirected, can be used to notify users of | |
19184 | these errors, by means of a router like this: | |
19185 | ||
19186 | userforward: | |
19187 | driver = redirect | |
19188 | allow_filter | |
19189 | check_local_user | |
19190 | file = $home/.forward | |
19191 | file_transport = address_file | |
19192 | pipe_transport = address_pipe | |
19193 | reply_transport = address_reply | |
19194 | no_verify | |
19195 | skip_syntax_errors | |
19196 | syntax_errors_to = real-$local_part@$domain | |
19197 | syntax_errors_text = \ | |
19198 | This is an automatically generated message. An error has\n\ | |
19199 | been found in your .forward file. Details of the error are\n\ | |
19200 | reported below. While this error persists, you will receive\n\ | |
19201 | a copy of this message for every message that is addressed\n\ | |
19202 | to you. If your .forward file is a filter file, or if it is\n\ | |
19203 | a non-filter file containing no valid forwarding addresses,\n\ | |
19204 | a copy of each incoming message will be put in your normal\n\ | |
19205 | mailbox. If a non-filter file contains at least one valid\n\ | |
19206 | forwarding address, forwarding to the valid addresses will\n\ | |
19207 | happen, and those will be the only deliveries that occur. | |
19208 | ||
19209 | You also need a router to ensure that local addresses that are prefixed by | |
19210 | "real-" are recognized, but not forwarded or filtered. For example, you could | |
19211 | put this immediately before the userforward router: | |
19212 | ||
19213 | real_localuser: | |
19214 | driver = accept | |
19215 | check_local_user | |
19216 | local_part_prefix = real- | |
19217 | transport = local_delivery | |
19218 | ||
19219 | For security, it would probably be a good idea to restrict the use of this | |
19220 | router to locally-generated messages, using a condition such as this: | |
19221 | ||
19222 | condition = ${if match {$sender_host_address}\ | |
19223 | {\N^(|127\.0\.0\.1)$\N}} | |
19224 | ||
2813c06e | 19225 | +-------------------------------------------------------------+ |
420a0d19 | 19226 | |syntax_errors_text|Use: redirect|Type: string*|Default: unset| |
2813c06e | 19227 | +-------------------------------------------------------------+ |
420a0d19 CE |
19228 | |
19229 | See skip_syntax_errors above. | |
19230 | ||
2813c06e | 19231 | +----------------------------------------------------------+ |
420a0d19 | 19232 | |syntax_errors_to|Use: redirect|Type: string|Default: unset| |
2813c06e | 19233 | +----------------------------------------------------------+ |
420a0d19 CE |
19234 | |
19235 | See skip_syntax_errors above. | |
19236 | ||
19237 | ||
19238 | ||
19239 | =============================================================================== | |
19240 | 23. ENVIRONMENT FOR RUNNING LOCAL TRANSPORTS | |
19241 | ||
19242 | Local transports handle deliveries to files and pipes. (The autoreply transport | |
19243 | can be thought of as similar to a pipe.) Exim always runs transports in | |
19244 | subprocesses, under specified uids and gids. Typical deliveries to local | |
19245 | mailboxes run under the uid and gid of the local user. | |
19246 | ||
19247 | Exim also sets a specific current directory while running the transport; for | |
19248 | some transports a home directory setting is also relevant. The pipe transport | |
19249 | is the only one that sets up environment variables; see section 29.4 for | |
19250 | details. | |
19251 | ||
19252 | The values used for the uid, gid, and the directories may come from several | |
19253 | different places. In many cases, the router that handles the address associates | |
19254 | settings with that address as a result of its check_local_user, group, or user | |
19255 | options. However, values may also be given in the transport's own | |
19256 | configuration, and these override anything that comes from the router. | |
19257 | ||
19258 | ||
19259 | 23.1 Concurrent deliveries | |
19260 | -------------------------- | |
19261 | ||
19262 | If two different messages for the same local recipient arrive more or less | |
19263 | simultaneously, the two delivery processes are likely to run concurrently. When | |
19264 | the appendfile transport is used to write to a file, Exim applies locking rules | |
19265 | to stop concurrent processes from writing to the same file at the same time. | |
19266 | ||
19267 | However, when you use a pipe transport, it is up to you to arrange any locking | |
19268 | that is needed. Here is a silly example: | |
19269 | ||
19270 | my_transport: | |
19271 | driver = pipe | |
19272 | command = /bin/sh -c 'cat >>/some/file' | |
19273 | ||
19274 | This is supposed to write the message at the end of the file. However, if two | |
19275 | messages arrive at the same time, the file will be scrambled. You can use the | |
2813c06e | 19276 | exim_lock utility program (see section 53.15) to lock a file using the same |
420a0d19 CE |
19277 | algorithm that Exim itself uses. |
19278 | ||
19279 | ||
19280 | 23.2 Uids and gids | |
19281 | ------------------ | |
19282 | ||
19283 | All transports have the options group and user. If group is set, it overrides | |
19284 | any group that the router set in the address, even if user is not set for the | |
19285 | transport. This makes it possible, for example, to run local mail delivery | |
19286 | under the uid of the recipient (set by the router), but in a special group (set | |
19287 | by the transport). For example: | |
19288 | ||
19289 | # Routers ... | |
19290 | # User/group are set by check_local_user in this router | |
19291 | local_users: | |
19292 | driver = accept | |
19293 | check_local_user | |
19294 | transport = group_delivery | |
19295 | ||
19296 | # Transports ... | |
19297 | # This transport overrides the group | |
19298 | group_delivery: | |
19299 | driver = appendfile | |
19300 | file = /var/spool/mail/$local_part | |
19301 | group = mail | |
19302 | ||
19303 | If user is set for a transport, its value overrides what is set in the address | |
19304 | by the router. If user is non-numeric and group is not set, the gid associated | |
19305 | with the user is used. If user is numeric, group must be set. | |
19306 | ||
19307 | When the uid is taken from the transport's configuration, the initgroups() | |
19308 | function is called for the groups associated with that uid if the initgroups | |
19309 | option is set for the transport. When the uid is not specified by the | |
19310 | transport, but is associated with the address by a router, the option for | |
19311 | calling initgroups() is taken from the router configuration. | |
19312 | ||
19313 | The pipe transport contains the special option pipe_as_creator. If this is set | |
19314 | and user is not set, the uid of the process that called Exim to receive the | |
19315 | message is used, and if group is not set, the corresponding original gid is | |
19316 | also used. | |
19317 | ||
19318 | This is the detailed preference order for obtaining a gid; the first of the | |
19319 | following that is set is used: | |
19320 | ||
19321 | * A group setting of the transport; | |
19322 | ||
19323 | * A group setting of the router; | |
19324 | ||
19325 | * A gid associated with a user setting of the router, either as a result of | |
19326 | check_local_user or an explicit non-numeric user setting; | |
19327 | ||
19328 | * The group associated with a non-numeric user setting of the transport; | |
19329 | ||
19330 | * In a pipe transport, the creator's gid if deliver_as_creator is set and the | |
19331 | uid is the creator's uid; | |
19332 | ||
19333 | * The Exim gid if the Exim uid is being used as a default. | |
19334 | ||
19335 | If, for example, the user is specified numerically on the router and there are | |
19336 | no group settings, no gid is available. In this situation, an error occurs. | |
19337 | This is different for the uid, for which there always is an ultimate default. | |
19338 | The first of the following that is set is used: | |
19339 | ||
19340 | * A user setting of the transport; | |
19341 | ||
19342 | * In a pipe transport, the creator's uid if deliver_as_creator is set; | |
19343 | ||
19344 | * A user setting of the router; | |
19345 | ||
19346 | * A check_local_user setting of the router; | |
19347 | ||
19348 | * The Exim uid. | |
19349 | ||
19350 | Of course, an error will still occur if the uid that is chosen is on the | |
19351 | never_users list. | |
19352 | ||
19353 | ||
19354 | 23.3 Current and home directories | |
19355 | --------------------------------- | |
19356 | ||
19357 | Routers may set current and home directories for local transports by means of | |
19358 | the transport_current_directory and transport_home_directory options. However, | |
19359 | if the transport's current_directory or home_directory options are set, they | |
19360 | override the router's values. In detail, the home directory for a local | |
19361 | transport is taken from the first of these values that is set: | |
19362 | ||
19363 | * The home_directory option on the transport; | |
19364 | ||
19365 | * The transport_home_directory option on the router; | |
19366 | ||
19367 | * The password data if check_local_user is set on the router; | |
19368 | ||
19369 | * The router_home_directory option on the router. | |
19370 | ||
19371 | The current directory is taken from the first of these values that is set: | |
19372 | ||
19373 | * The current_directory option on the transport; | |
19374 | ||
19375 | * The transport_current_directory option on the router. | |
19376 | ||
19377 | If neither the router nor the transport sets a current directory, Exim uses the | |
19378 | value of the home directory, if it is set. Otherwise it sets the current | |
19379 | directory to / before running a local transport. | |
19380 | ||
19381 | ||
19382 | 23.4 Expansion variables derived from the address | |
19383 | ------------------------------------------------- | |
19384 | ||
19385 | Normally a local delivery is handling a single address, and in that case the | |
19386 | variables such as $domain and $local_part are set during local deliveries. | |
19387 | However, in some circumstances more than one address may be handled at once | |
19388 | (for example, while writing batch SMTP for onward transmission by some other | |
19389 | means). In this case, the variables associated with the local part are never | |
19390 | set, $domain is set only if all the addresses have the same domain, and | |
19391 | $original_domain is never set. | |
19392 | ||
19393 | ||
19394 | ||
19395 | =============================================================================== | |
19396 | 24. GENERIC OPTIONS FOR TRANSPORTS | |
19397 | ||
19398 | The following generic options apply to all transports: | |
19399 | ||
2813c06e | 19400 | +------------------------------------------------------+ |
420a0d19 | 19401 | |body_only|Use: transports|Type: boolean|Default: false| |
2813c06e | 19402 | +------------------------------------------------------+ |
420a0d19 CE |
19403 | |
19404 | If this option is set, the message's headers are not transported. It is | |
19405 | mutually exclusive with headers_only. If it is used with the appendfile or pipe | |
19406 | transports, the settings of message_prefix and message_suffix should be | |
19407 | checked, because this option does not automatically suppress them. | |
19408 | ||
2813c06e | 19409 | +--------------------------------------------------------------+ |
420a0d19 | 19410 | |current_directory|Use: transports|Type: string*|Default: unset| |
2813c06e | 19411 | +--------------------------------------------------------------+ |
420a0d19 CE |
19412 | |
19413 | This specifies the current directory that is to be set while running the | |
19414 | transport, overriding any value that may have been set by the router. If the | |
19415 | expansion fails for any reason, including forced failure, an error is logged, | |
19416 | and delivery is deferred. | |
19417 | ||
2813c06e | 19418 | +------------------------------------------------------------+ |
420a0d19 | 19419 | |disable_logging|Use: transports|Type: boolean|Default: false| |
2813c06e | 19420 | +------------------------------------------------------------+ |
420a0d19 CE |
19421 | |
19422 | If this option is set true, nothing is logged for any deliveries by the | |
19423 | transport or for any transport errors. You should not set this option unless | |
19424 | you really, really know what you are doing. | |
19425 | ||
2813c06e | 19426 | +--------------------------------------------------------+ |
420a0d19 | 19427 | |debug_print|Use: transports|Type: string*|Default: unset| |
2813c06e | 19428 | +--------------------------------------------------------+ |
420a0d19 CE |
19429 | |
19430 | If this option is set and debugging is enabled (see the -d command line | |
19431 | option), the string is expanded and included in the debugging output when the | |
19432 | transport is run. If expansion of the string fails, the error message is | |
19433 | written to the debugging output, and Exim carries on processing. This facility | |
19434 | is provided to help with checking out the values of variables and so on when | |
19435 | debugging driver configurations. For example, if a headers_add option is not | |
19436 | working properly, debug_print could be used to output the variables it | |
19437 | references. A newline is added to the text if it does not end with one. The | |
19438 | variables $transport_name and $router_name contain the name of the transport | |
19439 | and the router that called it. | |
19440 | ||
2813c06e | 19441 | +--------------------------------------------------------------+ |
420a0d19 | 19442 | |delivery_date_add|Use: transports|Type: boolean|Default: false| |
2813c06e | 19443 | +--------------------------------------------------------------+ |
420a0d19 CE |
19444 | |
19445 | If this option is true, a Delivery-date: header is added to the message. This | |
19446 | gives the actual time the delivery was made. As this is not a standard header, | |
19447 | Exim has a configuration option (delivery_date_remove) which requests its | |
19448 | removal from incoming messages, so that delivered messages can safely be resent | |
19449 | to other recipients. | |
19450 | ||
2813c06e | 19451 | +--------------------------------------------------+ |
420a0d19 | 19452 | |driver|Use: transports|Type: string|Default: unset| |
2813c06e | 19453 | +--------------------------------------------------+ |
420a0d19 CE |
19454 | |
19455 | This specifies which of the available transport drivers is to be used. There is | |
19456 | no default, and this option must be set for every transport. | |
19457 | ||
2813c06e | 19458 | +------------------------------------------------------------+ |
420a0d19 | 19459 | |envelope_to_add|Use: transports|Type: boolean|Default: false| |
2813c06e | 19460 | +------------------------------------------------------------+ |
420a0d19 CE |
19461 | |
19462 | If this option is true, an Envelope-to: header is added to the message. This | |
19463 | gives the original address(es) in the incoming envelope that caused this | |
19464 | delivery to happen. More than one address may be present if the transport is | |
19465 | configured to handle several addresses at once, or if more than one original | |
19466 | address was redirected to the same final address. As this is not a standard | |
19467 | header, Exim has a configuration option (envelope_to_remove) which requests its | |
19468 | removal from incoming messages, so that delivered messages can safely be resent | |
19469 | to other recipients. | |
19470 | ||
2813c06e CE |
19471 | +---------------------------------------------------------+ |
19472 | |event_action|Use: transports|Type: string*|Default: unset| | |
19473 | +---------------------------------------------------------+ | |
19474 | ||
19475 | This option declares a string to be expanded for Exim's events mechanism. For | |
19476 | details see chapter 60. | |
19477 | ||
19478 | +-------------------------------------------------------+ | |
420a0d19 | 19479 | |group|Use: transports|Type: string*|Default: Exim group| |
2813c06e | 19480 | +-------------------------------------------------------+ |
420a0d19 CE |
19481 | |
19482 | This option specifies a gid for running the transport process, overriding any | |
19483 | value that the router supplies, and also overriding any value associated with | |
19484 | user (see below). | |
19485 | ||
2813c06e | 19486 | +------------------------------------------------------+ |
420a0d19 | 19487 | |headers_add|Use: transports|Type: list*|Default: unset| |
2813c06e | 19488 | +------------------------------------------------------+ |
420a0d19 | 19489 | |
2813c06e CE |
19490 | This option specifies a list of text headers, newline-separated (by default, |
19491 | changeable in the usual way), which are (separately) expanded and added to the | |
19492 | header portion of a message as it is transported, as described in section 47.17 | |
19493 | . Additional header lines can also be specified by routers. If the result of | |
19494 | the expansion is an empty string, or if the expansion is forced to fail, no | |
19495 | action is taken. Other expansion failures are treated as errors and cause the | |
19496 | delivery to be deferred. | |
420a0d19 CE |
19497 | |
19498 | Unlike most options, headers_add can be specified multiple times for a | |
19499 | transport; all listed headers are added. | |
19500 | ||
2813c06e | 19501 | +---------------------------------------------------------+ |
420a0d19 | 19502 | |headers_only|Use: transports|Type: boolean|Default: false| |
2813c06e | 19503 | +---------------------------------------------------------+ |
420a0d19 CE |
19504 | |
19505 | If this option is set, the message's body is not transported. It is mutually | |
19506 | exclusive with body_only. If it is used with the appendfile or pipe transports, | |
19507 | the settings of message_prefix and message_suffix should be checked, since this | |
19508 | option does not automatically suppress them. | |
19509 | ||
2813c06e | 19510 | +---------------------------------------------------------+ |
420a0d19 | 19511 | |headers_remove|Use: transports|Type: list*|Default: unset| |
2813c06e | 19512 | +---------------------------------------------------------+ |
420a0d19 | 19513 | |
2813c06e CE |
19514 | This option specifies a list of header names, colon-separated (by default, |
19515 | changeable in the usual way); these headers are omitted from the message as it | |
19516 | is transported, as described in section 47.17. Header removal can also be | |
19517 | specified by routers. Each list item is separately expanded. If the result of | |
19518 | the expansion is an empty string, or if the expansion is forced to fail, no | |
19519 | action is taken. Other expansion failures are treated as errors and cause the | |
19520 | delivery to be deferred. | |
420a0d19 CE |
19521 | |
19522 | Unlike most options, headers_remove can be specified multiple times for a | |
2813c06e CE |
19523 | transport; all listed headers are removed. |
19524 | ||
19525 | Warning: Because of the separate expansion of the list items, items that | |
19526 | contain a list separator must have it doubled. To avoid this, change the list | |
19527 | separator (6.21). | |
420a0d19 | 19528 | |
2813c06e | 19529 | +-----------------------------------------------------------+ |
420a0d19 | 19530 | |headers_rewrite|Use: transports|Type: string|Default: unset| |
2813c06e | 19531 | +-----------------------------------------------------------+ |
420a0d19 CE |
19532 | |
19533 | This option allows addresses in header lines to be rewritten at transport time, | |
19534 | that is, as the message is being copied to its destination. The contents of the | |
19535 | option are a colon-separated list of rewriting rules. Each rule is in exactly | |
19536 | the same form as one of the general rewriting rules that are applied when a | |
19537 | message is received. These are described in chapter 31. For example, | |
19538 | ||
19539 | headers_rewrite = a@b c@d f : \ | |
19540 | x@y w@z | |
19541 | ||
19542 | changes a@b into c@d in From: header lines, and x@y into w@z in all | |
19543 | address-bearing header lines. The rules are applied to the header lines just | |
19544 | before they are written out at transport time, so they affect only those copies | |
19545 | of the message that pass through the transport. However, only the message's | |
19546 | original header lines, and any that were added by a system filter, are | |
19547 | rewritten. If a router or transport adds header lines, they are not affected by | |
19548 | this option. These rewriting rules are not applied to the envelope. You can | |
19549 | change the return path using return_path, but you cannot change envelope | |
19550 | recipients at this time. | |
19551 | ||
2813c06e | 19552 | +-----------------------------------------------------------+ |
420a0d19 | 19553 | |home_directory|Use: transports|Type: string*|Default: unset| |
2813c06e | 19554 | +-----------------------------------------------------------+ |
420a0d19 CE |
19555 | |
19556 | This option specifies a home directory setting for a local transport, | |
19557 | overriding any value that may be set by the router. The home directory is | |
19558 | placed in $home while expanding the transport's private options. It is also | |
19559 | used as the current directory if no current directory is set by the | |
19560 | current_directory option on the transport or the transport_current_directory | |
19561 | option on the router. If the expansion fails for any reason, including forced | |
19562 | failure, an error is logged, and delivery is deferred. | |
19563 | ||
2813c06e | 19564 | +-------------------------------------------------------+ |
420a0d19 | 19565 | |initgroups|Use: transports|Type: boolean|Default: false| |
2813c06e | 19566 | +-------------------------------------------------------+ |
420a0d19 CE |
19567 | |
19568 | If this option is true and the uid for the delivery process is provided by the | |
19569 | transport, the initgroups() function is called when running the transport to | |
19570 | ensure that any additional groups associated with the uid are set up. | |
19571 | ||
2813c06e CE |
19572 | +----------------------------------------------------------+ |
19573 | |max_parallel|Use: transports|Type: integer*|Default: unset| | |
19574 | +----------------------------------------------------------+ | |
19575 | ||
19576 | If this option is set and expands to an integer greater than zero it limits the | |
19577 | number of concurrent runs of the transport. The control does not apply to | |
19578 | shadow transports. | |
19579 | ||
19580 | Exim implements this control by means of a hints database in which a record is | |
19581 | incremented whenever a transport process is being created. The record is | |
19582 | decremented and possibly removed when the process terminates. Obviously there | |
19583 | is scope for records to get left lying around if there is a system or program | |
19584 | crash. To guard against this, Exim ignores any records that are more than six | |
19585 | hours old. | |
19586 | ||
19587 | If you use this option, you should also arrange to delete the relevant hints | |
19588 | database whenever your system reboots. The names of the files start with misc | |
19589 | and they are kept in the spool/db directory. There may be one or two files, | |
19590 | depending on the type of DBM in use. The same files are used for ETRN and smtp | |
19591 | transport serialization. | |
19592 | ||
19593 | +-----------------------------------------------------------+ | |
420a0d19 | 19594 | |message_size_limit|Use: transports|Type: string*|Default: 0| |
2813c06e | 19595 | +-----------------------------------------------------------+ |
420a0d19 CE |
19596 | |
19597 | This option controls the size of messages passed through the transport. It is | |
19598 | expanded before use; the result of the expansion must be a sequence of decimal | |
19599 | digits, optionally followed by K or M. If the expansion fails for any reason, | |
19600 | including forced failure, or if the result is not of the required form, | |
19601 | delivery is deferred. If the value is greater than zero and the size of a | |
19602 | message exceeds this limit, the address is failed. If there is any chance that | |
19603 | the resulting bounce message could be routed to the same transport, you should | |
19604 | ensure that return_size_limit is less than the transport's message_size_limit, | |
19605 | as otherwise the bounce message will fail to get delivered. | |
19606 | ||
2813c06e | 19607 | +-----------------------------------------------------------------+ |
420a0d19 | 19608 | |rcpt_include_affixes|Use: transports|Type: boolean|Default: false| |
2813c06e | 19609 | +-----------------------------------------------------------------+ |
420a0d19 CE |
19610 | |
19611 | When this option is false (the default), and an address that has had any | |
19612 | affixes (prefixes or suffixes) removed from the local part is delivered by any | |
19613 | form of SMTP or LMTP, the affixes are not included. For example, if a router | |
19614 | that contains | |
19615 | ||
19616 | local_part_prefix = *- | |
19617 | ||
19618 | routes the address abc-xyz@some.domain to an SMTP transport, the envelope is | |
19619 | delivered with | |
19620 | ||
19621 | RCPT TO:<xyz@some.domain> | |
19622 | ||
19623 | This is also the case when an ACL-time callout is being used to verify a | |
19624 | recipient address. However, if rcpt_include_affixes is set true, the whole | |
19625 | local part is included in the RCPT command. This option applies to BSMTP | |
19626 | deliveries by the appendfile and pipe transports as well as to the lmtp and | |
19627 | smtp transports. | |
19628 | ||
2813c06e | 19629 | +---------------------------------------------------------------------+ |
420a0d19 | 19630 | |retry_use_local_part|Use: transports|Type: boolean|Default: see below| |
2813c06e | 19631 | +---------------------------------------------------------------------+ |
420a0d19 CE |
19632 | |
19633 | When a delivery suffers a temporary failure, a retry record is created in | |
19634 | Exim's hints database. For remote deliveries, the key for the retry record is | |
19635 | based on the name and/or IP address of the failing remote host. For local | |
19636 | deliveries, the key is normally the entire address, including both the local | |
19637 | part and the domain. This is suitable for most common cases of local delivery | |
19638 | temporary failure - for example, exceeding a mailbox quota should delay only | |
19639 | deliveries to that mailbox, not to the whole domain. | |
19640 | ||
19641 | However, in some special cases you may want to treat a temporary local delivery | |
19642 | as a failure associated with the domain, and not with a particular local part. | |
19643 | (For example, if you are storing all mail for some domain in files.) You can do | |
19644 | this by setting retry_use_local_part false. | |
19645 | ||
19646 | For all the local transports, its default value is true. For remote transports, | |
19647 | the default value is false for tidiness, but changing the value has no effect | |
19648 | on a remote transport in the current implementation. | |
19649 | ||
2813c06e | 19650 | +--------------------------------------------------------+ |
420a0d19 | 19651 | |return_path|Use: transports|Type: string*|Default: unset| |
2813c06e | 19652 | +--------------------------------------------------------+ |
420a0d19 CE |
19653 | |
19654 | If this option is set, the string is expanded at transport time and replaces | |
19655 | the existing return path (envelope sender) value in the copy of the message | |
19656 | that is being delivered. An empty return path is permitted. This feature is | |
19657 | designed for remote deliveries, where the value of this option is used in the | |
19658 | SMTP MAIL command. If you set return_path for a local transport, the only | |
19659 | effect is to change the address that is placed in the Return-path: header line, | |
19660 | if one is added to the message (see the next option). | |
19661 | ||
19662 | Note: A changed return path is not logged unless you add | |
19663 | return_path_on_delivery to the log selector. | |
19664 | ||
19665 | The expansion can refer to the existing value via $return_path. This is either | |
19666 | the message's envelope sender, or an address set by the errors_to option on a | |
19667 | router. If the expansion is forced to fail, no replacement occurs; if it fails | |
19668 | for another reason, delivery is deferred. This option can be used to support | |
2813c06e | 19669 | VERP (Variable Envelope Return Paths) - see section 50.6. |
420a0d19 CE |
19670 | |
19671 | Note: If a delivery error is detected locally, including the case when a remote | |
19672 | server rejects a message at SMTP time, the bounce message is not sent to the | |
19673 | value of this option. It is sent to the previously set errors address. This | |
19674 | defaults to the incoming sender address, but can be changed by setting | |
19675 | errors_to in a router. | |
19676 | ||
2813c06e | 19677 | +------------------------------------------------------------+ |
420a0d19 | 19678 | |return_path_add|Use: transports|Type: boolean|Default: false| |
2813c06e | 19679 | +------------------------------------------------------------+ |
420a0d19 CE |
19680 | |
19681 | If this option is true, a Return-path: header is added to the message. Although | |
19682 | the return path is normally available in the prefix line of BSD mailboxes, this | |
19683 | is commonly not displayed by MUAs, and so the user does not have easy access to | |
19684 | it. | |
19685 | ||
19686 | RFC 2821 states that the Return-path: header is added to a message "when the | |
19687 | delivery SMTP server makes the final delivery". This implies that this header | |
19688 | should not be present in incoming messages. Exim has a configuration option, | |
19689 | return_path_remove, which requests removal of this header from incoming | |
19690 | messages, so that delivered messages can safely be resent to other recipients. | |
19691 | ||
2813c06e | 19692 | +-------------------------------------------------------------+ |
420a0d19 | 19693 | |shadow_condition|Use: transports|Type: string*|Default: unset| |
2813c06e | 19694 | +-------------------------------------------------------------+ |
420a0d19 CE |
19695 | |
19696 | See shadow_transport below. | |
19697 | ||
2813c06e | 19698 | +------------------------------------------------------------+ |
420a0d19 | 19699 | |shadow_transport|Use: transports|Type: string|Default: unset| |
2813c06e | 19700 | +------------------------------------------------------------+ |
420a0d19 CE |
19701 | |
19702 | A local transport may set the shadow_transport option to the name of another | |
19703 | local transport. Shadow remote transports are not supported. | |
19704 | ||
19705 | Whenever a delivery to the main transport succeeds, and either shadow_condition | |
19706 | is unset, or its expansion does not result in the empty string or one of the | |
19707 | strings "0" or "no" or "false", the message is also passed to the shadow | |
19708 | transport, with the same delivery address or addresses. If expansion fails, no | |
19709 | action is taken except that non-forced expansion failures cause a log line to | |
19710 | be written. | |
19711 | ||
19712 | The result of the shadow transport is discarded and does not affect the | |
19713 | subsequent processing of the message. Only a single level of shadowing is | |
19714 | provided; the shadow_transport option is ignored on any transport when it is | |
19715 | running as a shadow. Options concerned with output from pipes are also ignored. | |
19716 | The log line for the successful delivery has an item added on the end, of the | |
19717 | form | |
19718 | ||
19719 | ST=<shadow transport name> | |
19720 | ||
19721 | If the shadow transport did not succeed, the error message is put in | |
19722 | parentheses afterwards. Shadow transports can be used for a number of different | |
19723 | purposes, including keeping more detailed log information than Exim normally | |
19724 | provides, and implementing automatic acknowledgment policies based on message | |
19725 | headers that some sites insist on. | |
19726 | ||
2813c06e | 19727 | +-------------------------------------------------------------+ |
420a0d19 | 19728 | |transport_filter|Use: transports|Type: string*|Default: unset| |
2813c06e | 19729 | +-------------------------------------------------------------+ |
420a0d19 CE |
19730 | |
19731 | This option sets up a filtering (in the Unix shell sense) process for messages | |
19732 | at transport time. It should not be confused with mail filtering as set up by | |
2813c06e CE |
19733 | individual users or via a system filter. If unset, or expanding to an empty |
19734 | string, no filtering is done. | |
420a0d19 CE |
19735 | |
19736 | When the message is about to be written out, the command specified by | |
19737 | transport_filter is started up in a separate, parallel process, and the entire | |
19738 | message, including the header lines, is passed to it on its standard input | |
19739 | (this in fact is done from a third process, to avoid deadlock). The command | |
19740 | must be specified as an absolute path. | |
19741 | ||
19742 | The lines of the message that are written to the transport filter are | |
19743 | terminated by newline ("\n"). The message is passed to the filter before any | |
19744 | SMTP-specific processing, such as turning "\n" into "\r\n" and escaping lines | |
19745 | beginning with a dot, and also before any processing implied by the settings of | |
19746 | check_string and escape_string in the appendfile or pipe transports. | |
19747 | ||
19748 | The standard error for the filter process is set to the same destination as its | |
19749 | standard output; this is read and written to the message's ultimate | |
19750 | destination. The process that writes the message to the filter, the filter | |
19751 | itself, and the original process that reads the result and delivers it are all | |
19752 | run in parallel, like a shell pipeline. | |
19753 | ||
19754 | The filter can perform any transformations it likes, but of course should take | |
19755 | care not to break RFC 2822 syntax. Exim does not check the result, except to | |
19756 | test for a final newline when SMTP is in use. All messages transmitted over | |
19757 | SMTP must end with a newline, so Exim supplies one if it is missing. | |
19758 | ||
19759 | A transport filter can be used to provide content-scanning on a per-user basis | |
19760 | at delivery time if the only required effect of the scan is to modify the | |
19761 | message. For example, a content scan could insert a new header line containing | |
19762 | a spam score. This could be interpreted by a filter in the user's MUA. It is | |
19763 | not possible to discard a message at this stage. | |
19764 | ||
19765 | A problem might arise if the filter increases the size of a message that is | |
19766 | being sent down an SMTP connection. If the receiving SMTP server has indicated | |
19767 | support for the SIZE parameter, Exim will have sent the size of the message at | |
19768 | the start of the SMTP session. If what is actually sent is substantially more, | |
19769 | the server might reject the message. This can be worked round by setting the | |
19770 | size_addition option on the smtp transport, either to allow for additions to | |
19771 | the message, or to disable the use of SIZE altogether. | |
19772 | ||
19773 | The value of the transport_filter option is the command string for starting the | |
19774 | filter, which is run directly from Exim, not under a shell. The string is | |
19775 | parsed by Exim in the same way as a command string for the pipe transport: Exim | |
19776 | breaks it up into arguments and then expands each argument separately (see | |
19777 | section 29.3). Any kind of expansion failure causes delivery to be deferred. | |
19778 | The special argument $pipe_addresses is replaced by a number of arguments, one | |
19779 | for each address that applies to this delivery. (This isn't an ideal name for | |
19780 | this feature here, but as it was already implemented for the pipe transport, it | |
19781 | seemed sensible not to change it.) | |
19782 | ||
19783 | The expansion variables $host and $host_address are available when the | |
19784 | transport is a remote one. They contain the name and IP address of the host to | |
19785 | which the message is being sent. For example: | |
19786 | ||
19787 | transport_filter = /some/directory/transport-filter.pl \ | |
19788 | $host $host_address $sender_address $pipe_addresses | |
19789 | ||
19790 | Two problems arise if you want to use more complicated expansion items to | |
19791 | generate transport filter commands, both of which due to the fact that the | |
19792 | command is split up before expansion. | |
19793 | ||
19794 | * If an expansion item contains white space, you must quote it, so that it is | |
19795 | all part of the same command item. If the entire option setting is one such | |
19796 | expansion item, you have to take care what kind of quoting you use. For | |
19797 | example: | |
19798 | ||
19799 | transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}' | |
19800 | ||
19801 | This runs the command /bin/cmd1 if the host name is a.b.c, and /bin/cmd2 | |
19802 | otherwise. If double quotes had been used, they would have been stripped by | |
19803 | Exim when it read the option's value. When the value is used, if the single | |
19804 | quotes were missing, the line would be split into two items, "/bin/cmd${if" | |
19805 | and "eq{$host}{a.b.c}{1}{2}", and an error would occur when Exim tried to | |
19806 | expand the first one. | |
19807 | ||
19808 | * Except for the special case of $pipe_addresses that is mentioned above, an | |
19809 | expansion cannot generate multiple arguments, or a command name followed by | |
19810 | arguments. Consider this example: | |
19811 | ||
19812 | transport_filter = ${lookup{$host}lsearch{/a/file}\ | |
19813 | {$value}{/bin/cat}} | |
19814 | ||
19815 | The result of the lookup is interpreted as the name of the command, even if | |
19816 | it contains white space. The simplest way round this is to use a shell: | |
19817 | ||
19818 | transport_filter = /bin/sh -c ${lookup{$host}lsearch{/a/file}\ | |
19819 | {$value}{/bin/cat}} | |
19820 | ||
19821 | The filter process is run under the same uid and gid as the normal delivery. | |
19822 | For remote deliveries this is the Exim uid/gid by default. The command should | |
19823 | normally yield a zero return code. Transport filters are not supposed to fail. | |
19824 | A non-zero code is taken to mean that the transport filter encountered some | |
19825 | serious problem. Delivery of the message is deferred; the message remains on | |
19826 | the queue and is tried again later. It is not possible to cause a message to be | |
19827 | bounced from a transport filter. | |
19828 | ||
19829 | If a transport filter is set on an autoreply transport, the original message is | |
19830 | passed through the filter as it is being copied into the newly generated | |
19831 | message, which happens if the return_message option is set. | |
19832 | ||
2813c06e | 19833 | +---------------------------------------------------------------+ |
420a0d19 | 19834 | |transport_filter_timeout|Use: transports|Type: time|Default: 5m| |
2813c06e | 19835 | +---------------------------------------------------------------+ |
420a0d19 CE |
19836 | |
19837 | When Exim is reading the output of a transport filter, it applies a timeout | |
19838 | that can be set by this option. Exceeding the timeout is normally treated as a | |
19839 | temporary delivery failure. However, if a transport filter is used with a pipe | |
19840 | transport, a timeout in the transport filter is treated in the same way as a | |
19841 | timeout in the pipe command itself. By default, a timeout is a hard error, but | |
19842 | if the pipe transport's timeout_defer option is set true, it becomes a | |
19843 | temporary error. | |
19844 | ||
2813c06e | 19845 | +-----------------------------------------------------+ |
420a0d19 | 19846 | |user|Use: transports|Type: string*|Default: Exim user| |
2813c06e | 19847 | +-----------------------------------------------------+ |
420a0d19 CE |
19848 | |
19849 | This option specifies the user under whose uid the delivery process is to be | |
19850 | run, overriding any uid that may have been set by the router. If the user is | |
19851 | given as a name, the uid is looked up from the password data, and the | |
19852 | associated group is taken as the value of the gid to be used if the group | |
19853 | option is not set. | |
19854 | ||
19855 | For deliveries that use local transports, a user and group are normally | |
19856 | specified explicitly or implicitly (for example, as a result of | |
19857 | check_local_user) by the router or transport. | |
19858 | ||
19859 | For remote transports, you should leave this option unset unless you really are | |
19860 | sure you know what you are doing. When a remote transport is running, it needs | |
19861 | to be able to access Exim's hints databases, because each host may have its own | |
19862 | retry data. | |
19863 | ||
19864 | ||
19865 | ||
19866 | =============================================================================== | |
19867 | 25. ADDRESS BATCHING IN LOCAL TRANSPORTS | |
19868 | ||
19869 | The only remote transport (smtp) is normally configured to handle more than one | |
19870 | address at a time, so that when several addresses are routed to the same remote | |
19871 | host, just one copy of the message is sent. Local transports, however, normally | |
19872 | handle one address at a time. That is, a separate instance of the transport is | |
19873 | run for each address that is routed to the transport. A separate copy of the | |
19874 | message is delivered each time. | |
19875 | ||
19876 | In special cases, it may be desirable to handle several addresses at once in a | |
19877 | local transport, for example: | |
19878 | ||
19879 | * In an appendfile transport, when storing messages in files for later | |
19880 | delivery by some other means, a single copy of the message with multiple | |
19881 | recipients saves space. | |
19882 | ||
19883 | * In an lmtp transport, when delivering over "local SMTP" to some process, a | |
19884 | single copy saves time, and is the normal way LMTP is expected to work. | |
19885 | ||
19886 | * In a pipe transport, when passing the message to a scanner program or to | |
19887 | some other delivery mechanism such as UUCP, multiple recipients may be | |
19888 | acceptable. | |
19889 | ||
19890 | These three local transports all have the same options for controlling multiple | |
19891 | ("batched") deliveries, namely batch_max and batch_id. To save repeating the | |
19892 | information for each transport, these options are described here. | |
19893 | ||
19894 | The batch_max option specifies the maximum number of addresses that can be | |
19895 | delivered together in a single run of the transport. Its default value is one | |
19896 | (no batching). When more than one address is routed to a transport that has a | |
19897 | batch_max value greater than one, the addresses are delivered in a batch (that | |
19898 | is, in a single run of the transport with multiple recipients), subject to | |
19899 | certain conditions: | |
19900 | ||
19901 | * If any of the transport's options contain a reference to $local_part, no | |
19902 | batching is possible. | |
19903 | ||
19904 | * If any of the transport's options contain a reference to $domain, only | |
19905 | addresses with the same domain are batched. | |
19906 | ||
19907 | * If batch_id is set, it is expanded for each address, and only those | |
19908 | addresses with the same expanded value are batched. This allows you to | |
19909 | specify customized batching conditions. Failure of the expansion for any | |
19910 | reason, including forced failure, disables batching, but it does not stop | |
19911 | the delivery from taking place. | |
19912 | ||
19913 | * Batched addresses must also have the same errors address (where to send | |
19914 | delivery errors), the same header additions and removals, the same user and | |
19915 | group for the transport, and if a host list is present, the first host must | |
19916 | be the same. | |
19917 | ||
19918 | In the case of the appendfile and pipe transports, batching applies both when | |
19919 | the file or pipe command is specified in the transport, and when it is | |
19920 | specified by a redirect router, but all the batched addresses must of course be | |
19921 | routed to the same file or pipe command. These two transports have an option | |
19922 | called use_bsmtp, which causes them to deliver the message in "batched SMTP" | |
19923 | format, with the envelope represented as SMTP commands. The check_string and | |
19924 | escape_string options are forced to the values | |
19925 | ||
19926 | check_string = "." | |
19927 | escape_string = ".." | |
19928 | ||
19929 | when batched SMTP is in use. A full description of the batch SMTP mechanism is | |
2813c06e | 19930 | given in section 48.10. The lmtp transport does not have a use_bsmtp option, |
420a0d19 CE |
19931 | because it always delivers using the SMTP protocol. |
19932 | ||
19933 | If the generic envelope_to_add option is set for a batching transport, the | |
19934 | Envelope-to: header that is added to the message contains all the addresses | |
19935 | that are being processed together. If you are using a batching appendfile | |
19936 | transport without use_bsmtp, the only way to preserve the recipient addresses | |
19937 | is to set the envelope_to_add option. | |
19938 | ||
19939 | If you are using a pipe transport without BSMTP, and setting the transport's | |
19940 | command option, you can include $pipe_addresses as part of the command. This is | |
19941 | not a true variable; it is a bit of magic that causes each of the recipient | |
19942 | addresses to be inserted into the command as a separate argument. This provides | |
19943 | a way of accessing all the addresses that are being delivered in the batch. | |
19944 | Note: This is not possible for pipe commands that are specified by a redirect | |
19945 | router. | |
19946 | ||
19947 | ||
19948 | ||
19949 | =============================================================================== | |
19950 | 26. THE APPENDFILE TRANSPORT | |
19951 | ||
19952 | The appendfile transport delivers a message by appending it to an existing | |
19953 | file, or by creating an entirely new file in a specified directory. Single | |
19954 | files to which messages are appended can be in the traditional Unix mailbox | |
19955 | format, or optionally in the MBX format supported by the Pine MUA and | |
19956 | University of Washington IMAP daemon, inter alia. When each message is being | |
19957 | delivered as a separate file, "maildir" format can optionally be used to give | |
19958 | added protection against failures that happen part-way through the delivery. A | |
19959 | third form of separate-file delivery known as "mailstore" is also supported. | |
19960 | For all file formats, Exim attempts to create as many levels of directory as | |
19961 | necessary, provided that create_directory is set. | |
19962 | ||
19963 | The code for the optional formats is not included in the Exim binary by | |
19964 | default. It is necessary to set SUPPORT_MBX, SUPPORT_MAILDIR and/or | |
19965 | SUPPORT_MAILSTORE in Local/Makefile to have the appropriate code included. | |
19966 | ||
19967 | Exim recognizes system quota errors, and generates an appropriate message. Exim | |
19968 | also supports its own quota control within the transport, for use when the | |
19969 | system facility is unavailable or cannot be used for some reason. | |
19970 | ||
19971 | If there is an error while appending to a file (for example, quota exceeded or | |
19972 | partition filled), Exim attempts to reset the file's length and last | |
19973 | modification time back to what they were before. If there is an error while | |
19974 | creating an entirely new file, the new file is removed. | |
19975 | ||
19976 | Before appending to a file, a number of security checks are made, and the file | |
19977 | is locked. A detailed description is given below, after the list of private | |
19978 | options. | |
19979 | ||
19980 | The appendfile transport is most commonly used for local deliveries to users' | |
19981 | mailboxes. However, it can also be used as a pseudo-remote transport for | |
19982 | putting messages into files for remote delivery by some means other than Exim. | |
19983 | "Batch SMTP" format is often used in this case (see the use_bsmtp option). | |
19984 | ||
19985 | ||
19986 | 26.1 The file and directory options | |
19987 | ----------------------------------- | |
19988 | ||
19989 | The file option specifies a single file, to which the message is appended; the | |
19990 | directory option specifies a directory, in which a new file containing the | |
19991 | message is created. Only one of these two options can be set, and for normal | |
19992 | deliveries to mailboxes, one of them must be set. | |
19993 | ||
19994 | However, appendfile is also used for delivering messages to files or | |
19995 | directories whose names (or parts of names) are obtained from alias, | |
19996 | forwarding, or filtering operations (for example, a save command in a user's | |
19997 | Exim filter). When such a transport is running, $local_part contains the local | |
19998 | part that was aliased or forwarded, and $address_file contains the name (or | |
19999 | partial name) of the file or directory generated by the redirection operation. | |
20000 | There are two cases: | |
20001 | ||
20002 | * If neither file nor directory is set, the redirection operation must | |
20003 | specify an absolute path (one that begins with "/"). This is the most | |
20004 | common case when users with local accounts use filtering to sort mail into | |
20005 | different folders. See for example, the address_file transport in the | |
20006 | default configuration. If the path ends with a slash, it is assumed to be | |
20007 | the name of a directory. A delivery to a directory can also be forced by | |
20008 | setting maildir_format or mailstore_format. | |
20009 | ||
20010 | * If file or directory is set for a delivery from a redirection, it is used | |
20011 | to determine the file or directory name for the delivery. Normally, the | |
20012 | contents of $address_file are used in some way in the string expansion. | |
20013 | ||
20014 | As an example of the second case, consider an environment where users do not | |
20015 | have home directories. They may be permitted to use Exim filter commands of the | |
20016 | form: | |
20017 | ||
20018 | save folder23 | |
20019 | ||
20020 | or Sieve filter commands of the form: | |
20021 | ||
20022 | require "fileinto"; | |
20023 | fileinto "folder23"; | |
20024 | ||
20025 | In this situation, the expansion of file or directory in the transport must | |
20026 | transform the relative path into an appropriate absolute file name. In the case | |
20027 | of Sieve filters, the name inbox must be handled. It is the name that is used | |
20028 | as a result of a "keep" action in the filter. This example shows one way of | |
20029 | handling this requirement: | |
20030 | ||
20031 | file = ${if eq{$address_file}{inbox} \ | |
20032 | {/var/mail/$local_part} \ | |
20033 | {${if eq{${substr_0_1:$address_file}}{/} \ | |
20034 | {$address_file} \ | |
20035 | {$home/mail/$address_file} \ | |
20036 | }} \ | |
20037 | } | |
20038 | ||
20039 | With this setting of file, inbox refers to the standard mailbox location, | |
20040 | absolute paths are used without change, and other folders are in the mail | |
20041 | directory within the home directory. | |
20042 | ||
20043 | Note 1: While processing an Exim filter, a relative path such as folder23 is | |
20044 | turned into an absolute path if a home directory is known to the router. In | |
20045 | particular, this is the case if check_local_user is set. If you want to prevent | |
20046 | this happening at routing time, you can set router_home_directory empty. This | |
20047 | forces the router to pass the relative path to the transport. | |
20048 | ||
20049 | Note 2: An absolute path in $address_file is not treated specially; the file or | |
20050 | directory option is still used if it is set. | |
20051 | ||
20052 | ||
20053 | 26.2 Private options for appendfile | |
20054 | ----------------------------------- | |
20055 | ||
2813c06e | 20056 | +-------------------------------------------------------+ |
420a0d19 | 20057 | |allow_fifo|Use: appendfile|Type: boolean|Default: false| |
2813c06e | 20058 | +-------------------------------------------------------+ |
420a0d19 CE |
20059 | |
20060 | Setting this option permits delivery to named pipes (FIFOs) as well as to | |
20061 | regular files. If no process is reading the named pipe at delivery time, the | |
20062 | delivery is deferred. | |
20063 | ||
2813c06e | 20064 | +----------------------------------------------------------+ |
420a0d19 | 20065 | |allow_symlink|Use: appendfile|Type: boolean|Default: false| |
2813c06e | 20066 | +----------------------------------------------------------+ |
420a0d19 CE |
20067 | |
20068 | By default, appendfile will not deliver if the path name for the file is that | |
20069 | of a symbolic link. Setting this option relaxes that constraint, but there are | |
20070 | security issues involved in the use of symbolic links. Be sure you know what | |
20071 | you are doing if you set this. Details of exactly what this option affects are | |
20072 | included in the discussion which follows this list of options. | |
20073 | ||
2813c06e | 20074 | +-----------------------------------------------------+ |
420a0d19 | 20075 | |batch_id|Use: appendfile|Type: string*|Default: unset| |
2813c06e | 20076 | +-----------------------------------------------------+ |
420a0d19 CE |
20077 | |
20078 | See the description of local delivery batching in chapter 25. However, batching | |
20079 | is automatically disabled for appendfile deliveries that happen as a result of | |
20080 | forwarding or aliasing or other redirection directly to a file. | |
20081 | ||
2813c06e | 20082 | +--------------------------------------------------+ |
420a0d19 | 20083 | |batch_max|Use: appendfile|Type: integer|Default: 1| |
2813c06e | 20084 | +--------------------------------------------------+ |
420a0d19 CE |
20085 | |
20086 | See the description of local delivery batching in chapter 25. | |
20087 | ||
2813c06e | 20088 | +--------------------------------------------------------+ |
420a0d19 | 20089 | |check_group|Use: appendfile|Type: boolean|Default: false| |
2813c06e | 20090 | +--------------------------------------------------------+ |
420a0d19 CE |
20091 | |
20092 | When this option is set, the group owner of the file defined by the file option | |
20093 | is checked to see that it is the same as the group under which the delivery | |
20094 | process is running. The default setting is false because the default file mode | |
20095 | is 0600, which means that the group is irrelevant. | |
20096 | ||
2813c06e | 20097 | +-------------------------------------------------------+ |
420a0d19 | 20098 | |check_owner|Use: appendfile|Type: boolean|Default: true| |
2813c06e | 20099 | +-------------------------------------------------------+ |
420a0d19 CE |
20100 | |
20101 | When this option is set, the owner of the file defined by the file option is | |
20102 | checked to ensure that it is the same as the user under which the delivery | |
20103 | process is running. | |
20104 | ||
2813c06e | 20105 | +------------------------------------------------------------+ |
420a0d19 | 20106 | |check_string|Use: appendfile|Type: string|Default: see below| |
2813c06e | 20107 | +------------------------------------------------------------+ |
420a0d19 CE |
20108 | |
20109 | As appendfile writes the message, the start of each line is tested for matching | |
20110 | check_string, and if it does, the initial matching characters are replaced by | |
20111 | the contents of escape_string. The value of check_string is a literal string, | |
20112 | not a regular expression, and the case of any letters it contains is | |
20113 | significant. | |
20114 | ||
20115 | If use_bsmtp is set the values of check_string and escape_string are forced to | |
20116 | "." and ".." respectively, and any settings in the configuration are ignored. | |
20117 | Otherwise, they default to "From " and ">From " when the file option is set, | |
20118 | and unset when any of the directory, maildir, or mailstore options are set. | |
20119 | ||
20120 | The default settings, along with message_prefix and message_suffix, are | |
20121 | suitable for traditional "BSD" mailboxes, where a line beginning with "From " | |
20122 | indicates the start of a new message. All four options need changing if another | |
20123 | format is used. For example, to deliver to mailboxes in MMDF format: | |
20124 | ||
20125 | check_string = "\1\1\1\1\n" | |
20126 | escape_string = "\1\1\1\1 \n" | |
20127 | message_prefix = "\1\1\1\1\n" | |
20128 | message_suffix = "\1\1\1\1\n" | |
20129 | ||
2813c06e | 20130 | +------------------------------------------------------------+ |
420a0d19 | 20131 | |create_directory|Use: appendfile|Type: boolean|Default: true| |
2813c06e | 20132 | +------------------------------------------------------------+ |
420a0d19 CE |
20133 | |
20134 | When this option is true, Exim attempts to create any missing superior | |
20135 | directories for the file that it is about to write. A created directory's mode | |
20136 | is given by the directory_mode option. | |
20137 | ||
20138 | The group ownership of a newly created directory is highly dependent on the | |
20139 | operating system (and possibly the file system) that is being used. For | |
20140 | example, in Solaris, if the parent directory has the setgid bit set, its group | |
20141 | is propagated to the child; if not, the currently set group is used. However, | |
20142 | in FreeBSD, the parent's group is always used. | |
20143 | ||
2813c06e | 20144 | +----------------------------------------------------------+ |
420a0d19 | 20145 | |create_file|Use: appendfile|Type: string|Default: anywhere| |
2813c06e | 20146 | +----------------------------------------------------------+ |
420a0d19 CE |
20147 | |
20148 | This option constrains the location of files and directories that are created | |
20149 | by this transport. It applies to files defined by the file option and | |
20150 | directories defined by the directory option. In the case of maildir delivery, | |
20151 | it applies to the top level directory, not the maildir directories beneath. | |
20152 | ||
20153 | The option must be set to one of the words "anywhere", "inhome", or | |
20154 | "belowhome". In the second and third cases, a home directory must have been set | |
20155 | for the transport. This option is not useful when an explicit file name is | |
20156 | given for normal mailbox deliveries. It is intended for the case when file | |
20157 | names are generated from users' .forward files. These are usually handled by an | |
20158 | appendfile transport called address_file. See also file_must_exist. | |
20159 | ||
2813c06e | 20160 | +------------------------------------------------------+ |
420a0d19 | 20161 | |directory|Use: appendfile|Type: string*|Default: unset| |
2813c06e | 20162 | +------------------------------------------------------+ |
420a0d19 CE |
20163 | |
20164 | This option is mutually exclusive with the file option, but one of file or | |
20165 | directory must be set, unless the delivery is the direct result of a | |
20166 | redirection (see section 26.1). | |
20167 | ||
20168 | When directory is set, the string is expanded, and the message is delivered | |
20169 | into a new file or files in or below the given directory, instead of being | |
20170 | appended to a single mailbox file. A number of different formats are provided | |
20171 | (see maildir_format and mailstore_format), and see section 26.4 for further | |
20172 | details of this form of delivery. | |
20173 | ||
2813c06e | 20174 | +---------------------------------------------------------------+ |
420a0d19 | 20175 | |directory_file|Use: appendfile|Type: string*|Default: see below| |
2813c06e | 20176 | +---------------------------------------------------------------+ |
420a0d19 CE |
20177 | |
20178 | When directory is set, but neither maildir_format nor mailstore_format is set, | |
20179 | appendfile delivers each message into a file whose name is obtained by | |
20180 | expanding this string. The default value is: | |
20181 | ||
20182 | q${base62:$tod_epoch}-$inode | |
20183 | ||
20184 | This generates a unique name from the current time, in base 62 form, and the | |
20185 | inode of the file. The variable $inode is available only when expanding this | |
20186 | option. | |
20187 | ||
2813c06e | 20188 | +----------------------------------------------------------------+ |
420a0d19 | 20189 | |directory_mode|Use: appendfile|Type: octal integer|Default: 0700| |
2813c06e | 20190 | +----------------------------------------------------------------+ |
420a0d19 CE |
20191 | |
20192 | If appendfile creates any directories as a result of the create_directory | |
20193 | option, their mode is specified by this option. | |
20194 | ||
2813c06e | 20195 | +-------------------------------------------------------------------+ |
420a0d19 | 20196 | |escape_string|Use: appendfile|Type: string|Default: see description| |
2813c06e | 20197 | +-------------------------------------------------------------------+ |
420a0d19 CE |
20198 | |
20199 | See check_string above. | |
20200 | ||
2813c06e | 20201 | +-------------------------------------------------+ |
420a0d19 | 20202 | |file|Use: appendfile|Type: string*|Default: unset| |
2813c06e | 20203 | +-------------------------------------------------+ |
420a0d19 CE |
20204 | |
20205 | This option is mutually exclusive with the directory option, but one of file or | |
20206 | directory must be set, unless the delivery is the direct result of a | |
20207 | redirection (see section 26.1). The file option specifies a single file, to | |
20208 | which the message is appended. One or more of use_fcntl_lock, use_flock_lock, | |
20209 | or use_lockfile must be set with file. | |
20210 | ||
20211 | If you are using more than one host to deliver over NFS into the same | |
20212 | mailboxes, you should always use lock files. | |
20213 | ||
20214 | The string value is expanded for each delivery, and must yield an absolute | |
20215 | path. The most common settings of this option are variations on one of these | |
20216 | examples: | |
20217 | ||
20218 | file = /var/spool/mail/$local_part | |
20219 | file = /home/$local_part/inbox | |
20220 | file = $home/inbox | |
20221 | ||
20222 | In the first example, all deliveries are done into the same directory. If Exim | |
20223 | is configured to use lock files (see use_lockfile below) it must be able to | |
20224 | create a file in the directory, so the "sticky" bit must be turned on for | |
20225 | deliveries to be possible, or alternatively the group option can be used to run | |
20226 | the delivery under a group id which has write access to the directory. | |
20227 | ||
2813c06e | 20228 | +-------------------------------------------------------+ |
420a0d19 | 20229 | |file_format|Use: appendfile|Type: string|Default: unset| |
2813c06e | 20230 | +-------------------------------------------------------+ |
420a0d19 CE |
20231 | |
20232 | This option requests the transport to check the format of an existing file | |
20233 | before adding to it. The check consists of matching a specific string at the | |
20234 | start of the file. The value of the option consists of an even number of | |
20235 | colon-separated strings. The first of each pair is the test string, and the | |
20236 | second is the name of a transport. If the transport associated with a matched | |
20237 | string is not the current transport, control is passed over to the other | |
20238 | transport. For example, suppose the standard local_delivery transport has this | |
20239 | added to it: | |
20240 | ||
20241 | file_format = "From : local_delivery :\ | |
20242 | \1\1\1\1\n : local_mmdf_delivery" | |
20243 | ||
20244 | Mailboxes that begin with "From" are still handled by this transport, but if a | |
20245 | mailbox begins with four binary ones followed by a newline, control is passed | |
20246 | to a transport called local_mmdf_delivery, which presumably is configured to do | |
20247 | the delivery in MMDF format. If a mailbox does not exist or is empty, it is | |
20248 | assumed to match the current transport. If the start of a mailbox doesn't match | |
20249 | any string, or if the transport named for a given string is not defined, | |
20250 | delivery is deferred. | |
20251 | ||
2813c06e | 20252 | +------------------------------------------------------------+ |
420a0d19 | 20253 | |file_must_exist|Use: appendfile|Type: boolean|Default: false| |
2813c06e | 20254 | +------------------------------------------------------------+ |
420a0d19 CE |
20255 | |
20256 | If this option is true, the file specified by the file option must exist. A | |
20257 | temporary error occurs if it does not, causing delivery to be deferred. If this | |
20258 | option is false, the file is created if it does not exist. | |
20259 | ||
2813c06e | 20260 | +---------------------------------------------------------+ |
420a0d19 | 20261 | |lock_fcntl_timeout|Use: appendfile|Type: time|Default: 0s| |
2813c06e | 20262 | +---------------------------------------------------------+ |
420a0d19 CE |
20263 | |
20264 | By default, the appendfile transport uses non-blocking calls to fcntl() when | |
20265 | locking an open mailbox file. If the call fails, the delivery process sleeps | |
20266 | for lock_interval and tries again, up to lock_retries times. Non-blocking calls | |
20267 | are used so that the file is not kept open during the wait for the lock; the | |
20268 | reason for this is to make it as safe as possible for deliveries over NFS in | |
20269 | the case when processes might be accessing an NFS mailbox without using a lock | |
20270 | file. This should not be done, but misunderstandings and hence | |
20271 | misconfigurations are not unknown. | |
20272 | ||
20273 | On a busy system, however, the performance of a non-blocking lock approach is | |
20274 | not as good as using a blocking lock with a timeout. In this case, the waiting | |
20275 | is done inside the system call, and Exim's delivery process acquires the lock | |
20276 | and can proceed as soon as the previous lock holder releases it. | |
20277 | ||
20278 | If lock_fcntl_timeout is set to a non-zero time, blocking locks, with that | |
20279 | timeout, are used. There may still be some retrying: the maximum number of | |
20280 | retries is | |
20281 | ||
20282 | (lock_retries * lock_interval) / lock_fcntl_timeout | |
20283 | ||
20284 | rounded up to the next whole number. In other words, the total time during | |
20285 | which appendfile is trying to get a lock is roughly the same, unless | |
20286 | lock_fcntl_timeout is set very large. | |
20287 | ||
20288 | You should consider setting this option if you are getting a lot of delayed | |
20289 | local deliveries because of errors of the form | |
20290 | ||
20291 | failed to lock mailbox /some/file (fcntl) | |
20292 | ||
2813c06e | 20293 | +---------------------------------------------------------+ |
420a0d19 | 20294 | |lock_flock_timeout|Use: appendfile|Type: time|Default: 0s| |
2813c06e | 20295 | +---------------------------------------------------------+ |
420a0d19 CE |
20296 | |
20297 | This timeout applies to file locking when using flock() (see use_flock); the | |
20298 | timeout operates in a similar manner to lock_fcntl_timeout. | |
20299 | ||
2813c06e | 20300 | +----------------------------------------------------+ |
420a0d19 | 20301 | |lock_interval|Use: appendfile|Type: time|Default: 3s| |
2813c06e | 20302 | +----------------------------------------------------+ |
420a0d19 CE |
20303 | |
20304 | This specifies the time to wait between attempts to lock the file. See below | |
20305 | for details of locking. | |
20306 | ||
2813c06e | 20307 | +------------------------------------------------------+ |
420a0d19 | 20308 | |lock_retries|Use: appendfile|Type: integer|Default: 10| |
2813c06e | 20309 | +------------------------------------------------------+ |
420a0d19 CE |
20310 | |
20311 | This specifies the maximum number of attempts to lock the file. A value of zero | |
20312 | is treated as 1. See below for details of locking. | |
20313 | ||
2813c06e | 20314 | +---------------------------------------------------------------+ |
420a0d19 | 20315 | |lockfile_mode|Use: appendfile|Type: octal integer|Default: 0600| |
2813c06e | 20316 | +---------------------------------------------------------------+ |
420a0d19 CE |
20317 | |
20318 | This specifies the mode of the created lock file, when a lock file is being | |
20319 | used (see use_lockfile and use_mbx_lock). | |
20320 | ||
2813c06e | 20321 | +--------------------------------------------------------+ |
420a0d19 | 20322 | |lockfile_timeout|Use: appendfile|Type: time|Default: 30m| |
2813c06e | 20323 | +--------------------------------------------------------+ |
420a0d19 CE |
20324 | |
20325 | When a lock file is being used (see use_lockfile), if a lock file already | |
20326 | exists and is older than this value, it is assumed to have been left behind by | |
20327 | accident, and Exim attempts to remove it. | |
20328 | ||
2813c06e | 20329 | +--------------------------------------------------------------+ |
420a0d19 | 20330 | |mailbox_filecount|Use: appendfile|Type: string*|Default: unset| |
2813c06e | 20331 | +--------------------------------------------------------------+ |
420a0d19 CE |
20332 | |
20333 | If this option is set, it is expanded, and the result is taken as the current | |
20334 | number of files in the mailbox. It must be a decimal number, optionally | |
20335 | followed by K or M. This provides a way of obtaining this information from an | |
20336 | external source that maintains the data. | |
20337 | ||
2813c06e | 20338 | +---------------------------------------------------------+ |
420a0d19 | 20339 | |mailbox_size|Use: appendfile|Type: string*|Default: unset| |
2813c06e | 20340 | +---------------------------------------------------------+ |
420a0d19 CE |
20341 | |
20342 | If this option is set, it is expanded, and the result is taken as the current | |
20343 | size the mailbox. It must be a decimal number, optionally followed by K or M. | |
20344 | This provides a way of obtaining this information from an external source that | |
20345 | maintains the data. This is likely to be helpful for maildir deliveries where | |
20346 | it is computationally expensive to compute the size of a mailbox. | |
20347 | ||
2813c06e | 20348 | +-----------------------------------------------------------+ |
420a0d19 | 20349 | |maildir_format|Use: appendfile|Type: boolean|Default: false| |
2813c06e | 20350 | +-----------------------------------------------------------+ |
420a0d19 CE |
20351 | |
20352 | If this option is set with the directory option, the delivery is into a new | |
20353 | file, in the "maildir" format that is used by other mail software. When the | |
20354 | transport is activated directly from a redirect router (for example, the | |
20355 | address_file transport in the default configuration), setting maildir_format | |
20356 | causes the path received from the router to be treated as a directory, whether | |
20357 | or not it ends with "/". This option is available only if SUPPORT_MAILDIR is | |
20358 | present in Local/Makefile. See section 26.5 below for further details. | |
20359 | ||
2813c06e | 20360 | +-----------------------------------------------------------------------------+ |
420a0d19 | 20361 | |maildir_quota_directory_regex|Use: appendfile|Type: string|Default: See below| |
2813c06e | 20362 | +-----------------------------------------------------------------------------+ |
420a0d19 CE |
20363 | |
20364 | This option is relevant only when maildir_use_size_file is set. It defines a | |
20365 | regular expression for specifying directories, relative to the quota directory | |
20366 | (see quota_directory), that should be included in the quota calculation. The | |
20367 | default value is: | |
20368 | ||
20369 | maildir_quota_directory_regex = ^(?:cur|new|\..*)$ | |
20370 | ||
20371 | This includes the cur and new directories, and any maildir++ folders | |
20372 | (directories whose names begin with a dot). If you want to exclude the Trash | |
20373 | folder from the count (as some sites do), you need to change this setting to | |
20374 | ||
20375 | maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$ | |
20376 | ||
20377 | This uses a negative lookahead in the regular expression to exclude the | |
20378 | directory whose name is .Trash. When a directory is excluded from quota | |
20379 | calculations, quota processing is bypassed for any messages that are delivered | |
20380 | directly into that directory. | |
20381 | ||
2813c06e | 20382 | +---------------------------------------------------------+ |
420a0d19 | 20383 | |maildir_retries|Use: appendfile|Type: integer|Default: 10| |
2813c06e | 20384 | +---------------------------------------------------------+ |
420a0d19 CE |
20385 | |
20386 | This option specifies the number of times to retry when writing a file in | |
20387 | "maildir" format. See section 26.5 below. | |
20388 | ||
2813c06e | 20389 | +--------------------------------------------------------+ |
420a0d19 | 20390 | |maildir_tag|Use: appendfile|Type: string*|Default: unset| |
2813c06e | 20391 | +--------------------------------------------------------+ |
420a0d19 CE |
20392 | |
20393 | This option applies only to deliveries in maildir format, and is described in | |
20394 | section 26.5 below. | |
20395 | ||
2813c06e | 20396 | +-------------------------------------------------------------------+ |
420a0d19 | 20397 | |maildir_use_size_file|Use: appendfile*|Type: boolean|Default: false| |
2813c06e | 20398 | +-------------------------------------------------------------------+ |
420a0d19 CE |
20399 | |
20400 | The result of string expansion for this option must be a valid boolean value. | |
20401 | If it is true, it enables support for maildirsize files. Exim creates a | |
20402 | maildirsize file in a maildir if one does not exist, taking the quota from the | |
20403 | quota option of the transport. If quota is unset, the value is zero. See | |
20404 | maildir_quota_directory_regex above and section 26.5 below for further details. | |
20405 | ||
2813c06e | 20406 | +----------------------------------------------------------------------+ |
420a0d19 | 20407 | |maildirfolder_create_regex|Use: appendfile|Type: string|Default: unset| |
2813c06e | 20408 | +----------------------------------------------------------------------+ |
420a0d19 CE |
20409 | |
20410 | The value of this option is a regular expression. If it is unset, it has no | |
20411 | effect. Otherwise, before a maildir delivery takes place, the pattern is | |
20412 | matched against the name of the maildir directory, that is, the directory | |
20413 | containing the new and tmp subdirectories that will be used for the delivery. | |
20414 | If there is a match, Exim checks for the existence of a file called | |
20415 | maildirfolder in the directory, and creates it if it does not exist. See | |
20416 | section 26.5 for more details. | |
20417 | ||
2813c06e | 20418 | +-------------------------------------------------------------+ |
420a0d19 | 20419 | |mailstore_format|Use: appendfile|Type: boolean|Default: false| |
2813c06e | 20420 | +-------------------------------------------------------------+ |
420a0d19 CE |
20421 | |
20422 | If this option is set with the directory option, the delivery is into two new | |
20423 | files in "mailstore" format. The option is available only if SUPPORT_MAILSTORE | |
20424 | is present in Local/Makefile. See section 26.4 below for further details. | |
20425 | ||
2813c06e | 20426 | +-------------------------------------------------------------+ |
420a0d19 | 20427 | |mailstore_prefix|Use: appendfile|Type: string*|Default: unset| |
2813c06e | 20428 | +-------------------------------------------------------------+ |
420a0d19 CE |
20429 | |
20430 | This option applies only to deliveries in mailstore format, and is described in | |
20431 | section 26.4 below. | |
20432 | ||
2813c06e | 20433 | +-------------------------------------------------------------+ |
420a0d19 | 20434 | |mailstore_suffix|Use: appendfile|Type: string*|Default: unset| |
2813c06e | 20435 | +-------------------------------------------------------------+ |
420a0d19 CE |
20436 | |
20437 | This option applies only to deliveries in mailstore format, and is described in | |
20438 | section 26.4 below. | |
20439 | ||
2813c06e | 20440 | +-------------------------------------------------------+ |
420a0d19 | 20441 | |mbx_format|Use: appendfile|Type: boolean|Default: false| |
2813c06e | 20442 | +-------------------------------------------------------+ |
420a0d19 CE |
20443 | |
20444 | This option is available only if Exim has been compiled with SUPPORT_MBX set in | |
20445 | Local/Makefile. If mbx_format is set with the file option, the message is | |
20446 | appended to the mailbox file in MBX format instead of traditional Unix format. | |
20447 | This format is supported by Pine4 and its associated IMAP and POP daemons, by | |
20448 | means of the c-client library that they all use. | |
20449 | ||
20450 | Note: The message_prefix and message_suffix options are not automatically | |
20451 | changed by the use of mbx_format. They should normally be set empty when using | |
20452 | MBX format, so this option almost always appears in this combination: | |
20453 | ||
20454 | mbx_format = true | |
20455 | message_prefix = | |
20456 | message_suffix = | |
20457 | ||
20458 | If none of the locking options are mentioned in the configuration, use_mbx_lock | |
20459 | is assumed and the other locking options default to false. It is possible to | |
20460 | specify the other kinds of locking with mbx_format, but use_fcntl_lock and | |
20461 | use_mbx_lock are mutually exclusive. MBX locking interworks with c-client, | |
20462 | providing for shared access to the mailbox. It should not be used if any | |
20463 | program that does not use this form of locking is going to access the mailbox, | |
20464 | nor should it be used if the mailbox file is NFS mounted, because it works only | |
20465 | when the mailbox is accessed from a single host. | |
20466 | ||
20467 | If you set use_fcntl_lock with an MBX-format mailbox, you cannot use the | |
20468 | standard version of c-client, because as long as it has a mailbox open (this | |
20469 | means for the whole of a Pine or IMAP session), Exim will not be able to append | |
20470 | messages to it. | |
20471 | ||
2813c06e | 20472 | +---------------------------------------------------------------+ |
420a0d19 | 20473 | |message_prefix|Use: appendfile|Type: string*|Default: see below| |
2813c06e | 20474 | +---------------------------------------------------------------+ |
420a0d19 CE |
20475 | |
20476 | The string specified here is expanded and output at the start of every message. | |
20477 | The default is unset unless file is specified and use_bsmtp is not set, in | |
20478 | which case it is: | |
20479 | ||
20480 | message_prefix = "From ${if def:return_path{$return_path}\ | |
20481 | {MAILER-DAEMON}} $tod_bsdinbox\n" | |
20482 | ||
20483 | Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\ | |
20484 | n" in message_prefix. | |
20485 | ||
2813c06e | 20486 | +---------------------------------------------------------------+ |
420a0d19 | 20487 | |message_suffix|Use: appendfile|Type: string*|Default: see below| |
2813c06e | 20488 | +---------------------------------------------------------------+ |
420a0d19 CE |
20489 | |
20490 | The string specified here is expanded and output at the end of every message. | |
20491 | The default is unset unless file is specified and use_bsmtp is not set, in | |
20492 | which case it is a single newline character. The suffix can be suppressed by | |
20493 | setting | |
20494 | ||
20495 | message_suffix = | |
20496 | ||
20497 | Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\ | |
20498 | n" in message_suffix. | |
20499 | ||
2813c06e | 20500 | +------------------------------------------------------+ |
420a0d19 | 20501 | |mode|Use: appendfile|Type: octal integer|Default: 0600| |
2813c06e | 20502 | +------------------------------------------------------+ |
420a0d19 CE |
20503 | |
20504 | If the output file is created, it is given this mode. If it already exists and | |
20505 | has wider permissions, they are reduced to this mode. If it has narrower | |
20506 | permissions, an error occurs unless mode_fail_narrower is false. However, if | |
20507 | the delivery is the result of a save command in a filter file specifying a | |
20508 | particular mode, the mode of the output file is always forced to take that | |
20509 | value, and this option is ignored. | |
20510 | ||
2813c06e | 20511 | +--------------------------------------------------------------+ |
420a0d19 | 20512 | |mode_fail_narrower|Use: appendfile|Type: boolean|Default: true| |
2813c06e | 20513 | +--------------------------------------------------------------+ |
420a0d19 CE |
20514 | |
20515 | This option applies in the case when an existing mailbox file has a narrower | |
20516 | mode than that specified by the mode option. If mode_fail_narrower is true, the | |
20517 | delivery is deferred ("mailbox has the wrong mode"); otherwise Exim continues | |
20518 | with the delivery attempt, using the existing mode of the file. | |
20519 | ||
2813c06e | 20520 | +----------------------------------------------------------+ |
420a0d19 | 20521 | |notify_comsat|Use: appendfile|Type: boolean|Default: false| |
2813c06e | 20522 | +----------------------------------------------------------+ |
420a0d19 CE |
20523 | |
20524 | If this option is true, the comsat daemon is notified after every successful | |
20525 | delivery to a user mailbox. This is the daemon that notifies logged on users | |
20526 | about incoming mail. | |
20527 | ||
2813c06e | 20528 | +--------------------------------------------------+ |
420a0d19 | 20529 | |quota|Use: appendfile|Type: string*|Default: unset| |
2813c06e | 20530 | +--------------------------------------------------+ |
420a0d19 CE |
20531 | |
20532 | This option imposes a limit on the size of the file to which Exim is appending, | |
20533 | or to the total space used in the directory tree when the directory option is | |
20534 | set. In the latter case, computation of the space used is expensive, because | |
20535 | all the files in the directory (and any sub-directories) have to be | |
20536 | individually inspected and their sizes summed. (See quota_size_regex and | |
20537 | maildir_use_size_file for ways to avoid this in environments where users have | |
20538 | no shell access to their mailboxes). | |
20539 | ||
20540 | As there is no interlock against two simultaneous deliveries into a multi-file | |
20541 | mailbox, it is possible for the quota to be overrun in this case. For | |
20542 | single-file mailboxes, of course, an interlock is a necessity. | |
20543 | ||
20544 | A file's size is taken as its used value. Because of blocking effects, this may | |
20545 | be a lot less than the actual amount of disk space allocated to the file. If | |
20546 | the sizes of a number of files are being added up, the rounding effect can | |
20547 | become quite noticeable, especially on systems that have large block sizes. | |
20548 | Nevertheless, it seems best to stick to the used figure, because this is the | |
20549 | obvious value which users understand most easily. | |
20550 | ||
20551 | The value of the option is expanded, and must then be a numerical value | |
20552 | (decimal point allowed), optionally followed by one of the letters K, M, or G, | |
20553 | for kilobytes, megabytes, or gigabytes. If Exim is running on a system with | |
20554 | large file support (Linux and FreeBSD have this), mailboxes larger than 2G can | |
20555 | be handled. | |
20556 | ||
20557 | Note: A value of zero is interpreted as "no quota". | |
20558 | ||
20559 | The expansion happens while Exim is running as root, before it changes uid for | |
20560 | the delivery. This means that files that are inaccessible to the end user can | |
20561 | be used to hold quota values that are looked up in the expansion. When delivery | |
20562 | fails because this quota is exceeded, the handling of the error is as for | |
20563 | system quota failures. | |
20564 | ||
20565 | By default, Exim's quota checking mimics system quotas, and restricts the | |
20566 | mailbox to the specified maximum size, though the value is not accurate to the | |
20567 | last byte, owing to separator lines and additional headers that may get added | |
20568 | during message delivery. When a mailbox is nearly full, large messages may get | |
20569 | refused even though small ones are accepted, because the size of the current | |
20570 | message is added to the quota when the check is made. This behaviour can be | |
20571 | changed by setting quota_is_inclusive false. When this is done, the check for | |
20572 | exceeding the quota does not include the current message. Thus, deliveries | |
20573 | continue until the quota has been exceeded; thereafter, no further messages are | |
20574 | delivered. See also quota_warn_threshold. | |
20575 | ||
2813c06e | 20576 | +------------------------------------------------------------+ |
420a0d19 | 20577 | |quota_directory|Use: appendfile|Type: string*|Default: unset| |
2813c06e | 20578 | +------------------------------------------------------------+ |
420a0d19 CE |
20579 | |
20580 | This option defines the directory to check for quota purposes when delivering | |
20581 | into individual files. The default is the delivery directory, or, if a file | |
20582 | called maildirfolder exists in a maildir directory, the parent of the delivery | |
20583 | directory. | |
20584 | ||
2813c06e | 20585 | +--------------------------------------------------------+ |
420a0d19 | 20586 | |quota_filecount|Use: appendfile|Type: string*|Default: 0| |
2813c06e | 20587 | +--------------------------------------------------------+ |
420a0d19 CE |
20588 | |
20589 | This option applies when the directory option is set. It limits the total | |
20590 | number of files in the directory (compare the inode limit in system quotas). It | |
20591 | can only be used if quota is also set. The value is expanded; an expansion | |
20592 | failure causes delivery to be deferred. A value of zero is interpreted as "no | |
20593 | quota". | |
20594 | ||
2813c06e | 20595 | +--------------------------------------------------------------+ |
420a0d19 | 20596 | |quota_is_inclusive|Use: appendfile|Type: boolean|Default: true| |
2813c06e | 20597 | +--------------------------------------------------------------+ |
420a0d19 CE |
20598 | |
20599 | See quota above. | |
20600 | ||
2813c06e | 20601 | +------------------------------------------------------------+ |
420a0d19 | 20602 | |quota_size_regex|Use: appendfile|Type: string|Default: unset| |
2813c06e | 20603 | +------------------------------------------------------------+ |
420a0d19 CE |
20604 | |
20605 | This option applies when one of the delivery modes that writes a separate file | |
20606 | for each message is being used. When Exim wants to find the size of one of | |
20607 | these files in order to test the quota, it first checks quota_size_regex. If | |
20608 | this is set to a regular expression that matches the file name, and it captures | |
20609 | one string, that string is interpreted as a representation of the file's size. | |
20610 | The value of quota_size_regex is not expanded. | |
20611 | ||
20612 | This feature is useful only when users have no shell access to their mailboxes | |
20613 | - otherwise they could defeat the quota simply by renaming the files. This | |
20614 | facility can be used with maildir deliveries, by setting maildir_tag to add the | |
20615 | file length to the file name. For example: | |
20616 | ||
20617 | maildir_tag = ,S=$message_size | |
20618 | quota_size_regex = ,S=(\d+) | |
20619 | ||
20620 | An alternative to $message_size is $message_linecount, which contains the | |
20621 | number of lines in the message. | |
20622 | ||
20623 | The regular expression should not assume that the length is at the end of the | |
20624 | file name (even though maildir_tag puts it there) because maildir MUAs | |
20625 | sometimes add other information onto the ends of message file names. | |
20626 | ||
20627 | Section 26.7 contains further information. | |
20628 | ||
2813c06e | 20629 | +-------------------------------------------------------------------+ |
420a0d19 | 20630 | |quota_warn_message|Use: appendfile|Type: string*|Default: see below| |
2813c06e | 20631 | +-------------------------------------------------------------------+ |
420a0d19 CE |
20632 | |
20633 | See below for the use of this option. If it is not set when | |
20634 | quota_warn_threshold is set, it defaults to | |
20635 | ||
20636 | quota_warn_message = "\ | |
20637 | To: $local_part@$domain\n\ | |
20638 | Subject: Your mailbox\n\n\ | |
20639 | This message is automatically created \ | |
20640 | by mail delivery software.\n\n\ | |
20641 | The size of your mailbox has exceeded \ | |
20642 | a warning threshold that is\n\ | |
20643 | set by the system administrator.\n" | |
20644 | ||
2813c06e | 20645 | +-------------------------------------------------------------+ |
420a0d19 | 20646 | |quota_warn_threshold|Use: appendfile|Type: string*|Default: 0| |
2813c06e | 20647 | +-------------------------------------------------------------+ |
420a0d19 CE |
20648 | |
20649 | This option is expanded in the same way as quota (see above). If the resulting | |
20650 | value is greater than zero, and delivery of the message causes the size of the | |
20651 | file or total space in the directory tree to cross the given threshold, a | |
20652 | warning message is sent. If quota is also set, the threshold may be specified | |
20653 | as a percentage of it by following the value with a percent sign. For example: | |
20654 | ||
20655 | quota = 10M | |
20656 | quota_warn_threshold = 75% | |
20657 | ||
20658 | If quota is not set, a setting of quota_warn_threshold that ends with a percent | |
20659 | sign is ignored. | |
20660 | ||
20661 | The warning message itself is specified by the quota_warn_message option, and | |
20662 | it must start with a To: header line containing the recipient(s) of the warning | |
20663 | message. These do not necessarily have to include the recipient(s) of the | |
20664 | original message. A Subject: line should also normally be supplied. You can | |
20665 | include any other header lines that you want. If you do not include a From: | |
20666 | line, the default is: | |
20667 | ||
20668 | From: Mail Delivery System <mailer-daemon@$qualify_domain_sender> | |
20669 | ||
20670 | If you supply a Reply-To: line, it overrides the global errors_reply_to option. | |
20671 | ||
20672 | The quota option does not have to be set in order to use this option; they are | |
20673 | independent of one another except when the threshold is specified as a | |
20674 | percentage. | |
20675 | ||
2813c06e | 20676 | +------------------------------------------------------+ |
420a0d19 | 20677 | |use_bsmtp|Use: appendfile|Type: boolean|Default: false| |
2813c06e | 20678 | +------------------------------------------------------+ |
420a0d19 CE |
20679 | |
20680 | If this option is set true, appendfile writes messages in "batch SMTP" format, | |
20681 | with the envelope sender and recipient(s) included as SMTP commands. If you | |
20682 | want to include a leading HELO command with such messages, you can do so by | |
2813c06e | 20683 | setting the message_prefix option. See section 48.10 for details of batch SMTP. |
420a0d19 | 20684 | |
2813c06e | 20685 | +-----------------------------------------------------+ |
420a0d19 | 20686 | |use_crlf|Use: appendfile|Type: boolean|Default: false| |
2813c06e | 20687 | +-----------------------------------------------------+ |
420a0d19 CE |
20688 | |
20689 | This option causes lines to be terminated with the two-character CRLF sequence | |
20690 | (carriage return, linefeed) instead of just a linefeed character. In the case | |
20691 | of batched SMTP, the byte sequence written to the file is then an exact image | |
20692 | of what would be sent down a real SMTP connection. | |
20693 | ||
20694 | Note: The contents of the message_prefix and message_suffix options (which are | |
20695 | used to supply the traditional "From " and blank line separators in | |
20696 | Berkeley-style mailboxes) are written verbatim, so must contain their own | |
20697 | carriage return characters if these are needed. In cases where these options | |
20698 | have non-empty defaults, the values end with a single linefeed, so they must be | |
20699 | changed to end with "\r\n" if use_crlf is set. | |
20700 | ||
2813c06e | 20701 | +---------------------------------------------------------------+ |
420a0d19 | 20702 | |use_fcntl_lock|Use: appendfile|Type: boolean|Default: see below| |
2813c06e | 20703 | +---------------------------------------------------------------+ |
420a0d19 CE |
20704 | |
20705 | This option controls the use of the fcntl() function to lock a file for | |
20706 | exclusive use when a message is being appended. It is set by default unless | |
20707 | use_flock_lock is set. Otherwise, it should be turned off only if you know that | |
20708 | all your MUAs use lock file locking. When both use_fcntl_lock and | |
20709 | use_flock_lock are unset, use_lockfile must be set. | |
20710 | ||
2813c06e | 20711 | +-----------------------------------------------------------+ |
420a0d19 | 20712 | |use_flock_lock|Use: appendfile|Type: boolean|Default: false| |
2813c06e | 20713 | +-----------------------------------------------------------+ |
420a0d19 CE |
20714 | |
20715 | This option is provided to support the use of flock() for file locking, for the | |
20716 | few situations where it is needed. Most modern operating systems support fcntl | |
20717 | () and lockf() locking, and these two functions interwork with each other. Exim | |
20718 | uses fcntl() locking by default. | |
20719 | ||
20720 | This option is required only if you are using an operating system where flock() | |
20721 | is used by programs that access mailboxes (typically MUAs), and where flock() | |
20722 | does not correctly interwork with fcntl(). You can use both fcntl() and flock() | |
20723 | locking simultaneously if you want. | |
20724 | ||
20725 | Not all operating systems provide flock(). Some versions of Solaris do not have | |
20726 | it (and some, I think, provide a not quite right version built on top of lockf | |
20727 | ()). If the OS does not have flock(), Exim will be built without the ability to | |
20728 | use it, and any attempt to do so will cause a configuration error. | |
20729 | ||
20730 | Warning: flock() locks do not work on NFS files (unless flock() is just being | |
20731 | mapped onto fcntl() by the OS). | |
20732 | ||
2813c06e | 20733 | +-------------------------------------------------------------+ |
420a0d19 | 20734 | |use_lockfile|Use: appendfile|Type: boolean|Default: see below| |
2813c06e | 20735 | +-------------------------------------------------------------+ |
420a0d19 CE |
20736 | |
20737 | If this option is turned off, Exim does not attempt to create a lock file when | |
20738 | appending to a mailbox file. In this situation, the only locking is by fcntl(). | |
20739 | You should only turn use_lockfile off if you are absolutely sure that every MUA | |
20740 | that is ever going to look at your users' mailboxes uses fcntl() rather than a | |
20741 | lock file, and even then only when you are not delivering over NFS from more | |
20742 | than one host. | |
20743 | ||
20744 | In order to append to an NFS file safely from more than one host, it is | |
20745 | necessary to take out a lock before opening the file, and the lock file | |
20746 | achieves this. Otherwise, even with fcntl() locking, there is a risk of file | |
20747 | corruption. | |
20748 | ||
20749 | The use_lockfile option is set by default unless use_mbx_lock is set. It is not | |
20750 | possible to turn both use_lockfile and use_fcntl_lock off, except when | |
20751 | mbx_format is set. | |
20752 | ||
2813c06e | 20753 | +-------------------------------------------------------------+ |
420a0d19 | 20754 | |use_mbx_lock|Use: appendfile|Type: boolean|Default: see below| |
2813c06e | 20755 | +-------------------------------------------------------------+ |
420a0d19 CE |
20756 | |
20757 | This option is available only if Exim has been compiled with SUPPORT_MBX set in | |
20758 | Local/Makefile. Setting the option specifies that special MBX locking rules be | |
20759 | used. It is set by default if mbx_format is set and none of the locking options | |
20760 | are mentioned in the configuration. The locking rules are the same as are used | |
20761 | by the c-client library that underlies Pine and the IMAP4 and POP daemons that | |
20762 | come with it (see the discussion below). The rules allow for shared access to | |
20763 | the mailbox. However, this kind of locking does not work when the mailbox is | |
20764 | NFS mounted. | |
20765 | ||
20766 | You can set use_mbx_lock with either (or both) of use_fcntl_lock and | |
20767 | use_flock_lock to control what kind of locking is used in implementing the MBX | |
20768 | locking rules. The default is to use fcntl() if use_mbx_lock is set without | |
20769 | use_fcntl_lock or use_flock_lock. | |
20770 | ||
20771 | ||
20772 | 26.3 Operational details for appending | |
20773 | -------------------------------------- | |
20774 | ||
20775 | Before appending to a file, the following preparations are made: | |
20776 | ||
20777 | * If the name of the file is /dev/null, no action is taken, and a success | |
20778 | return is given. | |
20779 | ||
20780 | * If any directories on the file's path are missing, Exim creates them if the | |
20781 | create_directory option is set. A created directory's mode is given by the | |
20782 | directory_mode option. | |
20783 | ||
20784 | * If file_format is set, the format of an existing file is checked. If this | |
20785 | indicates that a different transport should be used, control is passed to | |
20786 | that transport. | |
20787 | ||
20788 | * If use_lockfile is set, a lock file is built in a way that will work | |
20789 | reliably over NFS, as follows: | |
20790 | ||
20791 | 1. Create a "hitching post" file whose name is that of the lock file with | |
20792 | the current time, primary host name, and process id added, by opening | |
20793 | for writing as a new file. If this fails with an access error, delivery | |
20794 | is deferred. | |
20795 | ||
20796 | 2. Close the hitching post file, and hard link it to the lock file name. | |
20797 | ||
20798 | 3. If the call to link() succeeds, creation of the lock file has | |
20799 | succeeded. Unlink the hitching post name. | |
20800 | ||
20801 | 4. Otherwise, use stat() to get information about the hitching post file, | |
20802 | and then unlink hitching post name. If the number of links is exactly | |
20803 | two, creation of the lock file succeeded but something (for example, an | |
20804 | NFS server crash and restart) caused this fact not to be communicated | |
20805 | to the link() call. | |
20806 | ||
20807 | 5. If creation of the lock file failed, wait for lock_interval and try | |
20808 | again, up to lock_retries times. However, since any program that writes | |
20809 | to a mailbox should complete its task very quickly, it is reasonable to | |
20810 | time out old lock files that are normally the result of user agent and | |
20811 | system crashes. If an existing lock file is older than lockfile_timeout | |
20812 | Exim attempts to unlink it before trying again. | |
20813 | ||
20814 | * A call is made to lstat() to discover whether the main file exists, and if | |
20815 | so, what its characteristics are. If lstat() fails for any reason other | |
20816 | than non-existence, delivery is deferred. | |
20817 | ||
20818 | * If the file does exist and is a symbolic link, delivery is deferred, unless | |
20819 | the allow_symlink option is set, in which case the ownership of the link is | |
20820 | checked, and then stat() is called to find out about the real file, which | |
20821 | is then subjected to the checks below. The check on the top-level link | |
20822 | ownership prevents one user creating a link for another's mailbox in a | |
20823 | sticky directory, though allowing symbolic links in this case is definitely | |
20824 | not a good idea. If there is a chain of symbolic links, the intermediate | |
20825 | ones are not checked. | |
20826 | ||
20827 | * If the file already exists but is not a regular file, or if the file's | |
20828 | owner and group (if the group is being checked - see check_group above) are | |
20829 | different from the user and group under which the delivery is running, | |
20830 | delivery is deferred. | |
20831 | ||
20832 | * If the file's permissions are more generous than specified, they are | |
20833 | reduced. If they are insufficient, delivery is deferred, unless | |
20834 | mode_fail_narrower is set false, in which case the delivery is tried using | |
20835 | the existing permissions. | |
20836 | ||
20837 | * The file's inode number is saved, and the file is then opened for | |
20838 | appending. If this fails because the file has vanished, appendfile behaves | |
20839 | as if it hadn't existed (see below). For any other failures, delivery is | |
20840 | deferred. | |
20841 | ||
20842 | * If the file is opened successfully, check that the inode number hasn't | |
20843 | changed, that it is still a regular file, and that the owner and | |
20844 | permissions have not changed. If anything is wrong, defer delivery and | |
20845 | freeze the message. | |
20846 | ||
20847 | * If the file did not exist originally, defer delivery if the file_must_exist | |
20848 | option is set. Otherwise, check that the file is being created in a | |
20849 | permitted directory if the create_file option is set (deferring on | |
20850 | failure), and then open for writing as a new file, with the O_EXCL and | |
20851 | O_CREAT options, except when dealing with a symbolic link (the | |
20852 | allow_symlink option must be set). In this case, which can happen if the | |
20853 | link points to a non-existent file, the file is opened for writing using | |
20854 | O_CREAT but not O_EXCL, because that prevents link following. | |
20855 | ||
20856 | * If opening fails because the file exists, obey the tests given above for | |
20857 | existing files. However, to avoid looping in a situation where the file is | |
20858 | being continuously created and destroyed, the exists/not-exists loop is | |
20859 | broken after 10 repetitions, and the message is then frozen. | |
20860 | ||
20861 | * If opening fails with any other error, defer delivery. | |
20862 | ||
20863 | * Once the file is open, unless both use_fcntl_lock and use_flock_lock are | |
20864 | false, it is locked using fcntl() or flock() or both. If use_mbx_lock is | |
20865 | false, an exclusive lock is requested in each case. However, if | |
20866 | use_mbx_lock is true, Exim takes out a shared lock on the open file, and an | |
20867 | exclusive lock on the file whose name is | |
20868 | ||
20869 | /tmp/.<device-number>.<inode-number> | |
20870 | ||
20871 | using the device and inode numbers of the open mailbox file, in accordance | |
20872 | with the MBX locking rules. This file is created with a mode that is | |
20873 | specified by the lockfile_mode option. | |
20874 | ||
20875 | If Exim fails to lock the file, there are two possible courses of action, | |
20876 | depending on the value of the locking timeout. This is obtained from | |
20877 | lock_fcntl_timeout or lock_flock_timeout, as appropriate. | |
20878 | ||
20879 | If the timeout value is zero, the file is closed, Exim waits for | |
20880 | lock_interval, and then goes back and re-opens the file as above and tries | |
20881 | to lock it again. This happens up to lock_retries times, after which the | |
20882 | delivery is deferred. | |
20883 | ||
20884 | If the timeout has a value greater than zero, blocking calls to fcntl() or | |
20885 | flock() are used (with the given timeout), so there has already been some | |
20886 | waiting involved by the time locking fails. Nevertheless, Exim does not | |
20887 | give up immediately. It retries up to | |
20888 | ||
20889 | (lock_retries * lock_interval) / <timeout> | |
20890 | ||
20891 | times (rounded up). | |
20892 | ||
20893 | At the end of delivery, Exim closes the file (which releases the fcntl() and/or | |
20894 | flock() locks) and then deletes the lock file if one was created. | |
20895 | ||
20896 | ||
20897 | 26.4 Operational details for delivery to a new file | |
20898 | --------------------------------------------------- | |
20899 | ||
20900 | When the directory option is set instead of file, each message is delivered | |
20901 | into a newly-created file or set of files. When appendfile is activated | |
20902 | directly from a redirect router, neither file nor directory is normally set, | |
20903 | because the path for delivery is supplied by the router. (See for example, the | |
20904 | address_file transport in the default configuration.) In this case, delivery is | |
20905 | to a new file if either the path name ends in "/", or the maildir_format or | |
20906 | mailstore_format option is set. | |
20907 | ||
20908 | No locking is required while writing the message to a new file, so the various | |
20909 | locking options of the transport are ignored. The "From" line that by default | |
20910 | separates messages in a single file is not normally needed, nor is the escaping | |
20911 | of message lines that start with "From", and there is no need to ensure a | |
20912 | newline at the end of each message. Consequently, the default values for | |
20913 | check_string, message_prefix, and message_suffix are all unset when any of | |
20914 | directory, maildir_format, or mailstore_format is set. | |
20915 | ||
20916 | If Exim is required to check a quota setting, it adds up the sizes of all the | |
20917 | files in the delivery directory by default. However, you can specify a | |
20918 | different directory by setting quota_directory. Also, for maildir deliveries | |
20919 | (see below) the maildirfolder convention is honoured. | |
20920 | ||
20921 | There are three different ways in which delivery to individual files can be | |
20922 | done, controlled by the settings of the maildir_format and mailstore_format | |
20923 | options. Note that code to support maildir or mailstore formats is not included | |
20924 | in the binary unless SUPPORT_MAILDIR or SUPPORT_MAILSTORE, respectively, is set | |
20925 | in Local/Makefile. | |
20926 | ||
20927 | In all three cases an attempt is made to create the directory and any necessary | |
20928 | sub-directories if they do not exist, provided that the create_directory option | |
20929 | is set (the default). The location of a created directory can be constrained by | |
20930 | setting create_file. A created directory's mode is given by the directory_mode | |
20931 | option. If creation fails, or if the create_directory option is not set when | |
20932 | creation is required, delivery is deferred. | |
20933 | ||
20934 | ||
20935 | 26.5 Maildir delivery | |
20936 | --------------------- | |
20937 | ||
20938 | If the maildir_format option is true, Exim delivers each message by writing it | |
20939 | to a file whose name is tmp/<stime>.H<mtime>P<pid>.<host> in the directory that | |
20940 | is defined by the directory option (the "delivery directory"). If the delivery | |
20941 | is successful, the file is renamed into the new subdirectory. | |
20942 | ||
20943 | In the file name, <stime> is the current time of day in seconds, and <mtime> is | |
20944 | the microsecond fraction of the time. After a maildir delivery, Exim checks | |
20945 | that the time-of-day clock has moved on by at least one microsecond before | |
20946 | terminating the delivery process. This guarantees uniqueness for the file name. | |
20947 | However, as a precaution, Exim calls stat() for the file before opening it. If | |
20948 | any response other than ENOENT (does not exist) is given, Exim waits 2 seconds | |
20949 | and tries again, up to maildir_retries times. | |
20950 | ||
20951 | Before Exim carries out a maildir delivery, it ensures that subdirectories | |
20952 | called new, cur, and tmp exist in the delivery directory. If they do not exist, | |
20953 | Exim tries to create them and any superior directories in their path, subject | |
20954 | to the create_directory and create_file options. If the | |
20955 | maildirfolder_create_regex option is set, and the regular expression it | |
20956 | contains matches the delivery directory, Exim also ensures that a file called | |
20957 | maildirfolder exists in the delivery directory. If a missing directory or | |
20958 | maildirfolder file cannot be created, delivery is deferred. | |
20959 | ||
20960 | These features make it possible to use Exim to create all the necessary files | |
20961 | and directories in a maildir mailbox, including subdirectories for maildir++ | |
20962 | folders. Consider this example: | |
20963 | ||
20964 | maildir_format = true | |
20965 | directory = /var/mail/$local_part\ | |
20966 | ${if eq{$local_part_suffix}{}{}\ | |
20967 | {/.${substr_1:$local_part_suffix}}} | |
20968 | maildirfolder_create_regex = /\.[^/]+$ | |
20969 | ||
20970 | If $local_part_suffix is empty (there was no suffix for the local part), | |
20971 | delivery is into a toplevel maildir with a name like /var/mail/pimbo (for the | |
20972 | user called pimbo). The pattern in maildirfolder_create_regex does not match | |
20973 | this name, so Exim will not look for or create the file /var/mail/pimbo/ | |
20974 | maildirfolder, though it will create /var/mail/pimbo/{cur,new,tmp} if | |
20975 | necessary. | |
20976 | ||
20977 | However, if $local_part_suffix contains "-eximusers" (for example), delivery is | |
20978 | into the maildir++ folder /var/mail/pimbo/.eximusers, which does match | |
20979 | maildirfolder_create_regex. In this case, Exim will create /var/mail/pimbo | |
20980 | /.eximusers/maildirfolder as well as the three maildir directories /var/mail/ | |
20981 | pimbo/.eximusers/{cur,new,tmp}. | |
20982 | ||
20983 | Warning: Take care when setting maildirfolder_create_regex that it does not | |
20984 | inadvertently match the toplevel maildir directory, because a maildirfolder | |
20985 | file at top level would completely break quota calculations. | |
20986 | ||
20987 | If Exim is required to check a quota setting before a maildir delivery, and | |
20988 | quota_directory is not set, it looks for a file called maildirfolder in the | |
20989 | maildir directory (alongside new, cur, tmp). If this exists, Exim assumes the | |
20990 | directory is a maildir++ folder directory, which is one level down from the | |
20991 | user's top level mailbox directory. This causes it to start at the parent | |
20992 | directory instead of the current directory when calculating the amount of space | |
20993 | used. | |
20994 | ||
20995 | One problem with delivering into a multi-file mailbox is that it is | |
20996 | computationally expensive to compute the size of the mailbox for quota | |
20997 | checking. Various approaches have been taken to reduce the amount of work | |
20998 | needed. The next two sections describe two of them. A third alternative is to | |
20999 | use some external process for maintaining the size data, and use the expansion | |
21000 | of the mailbox_size option as a way of importing it into Exim. | |
21001 | ||
21002 | ||
21003 | 26.6 Using tags to record message sizes | |
21004 | --------------------------------------- | |
21005 | ||
21006 | If maildir_tag is set, the string is expanded for each delivery. When the | |
21007 | maildir file is renamed into the new sub-directory, the tag is added to its | |
21008 | name. However, if adding the tag takes the length of the name to the point | |
21009 | where the test stat() call fails with ENAMETOOLONG, the tag is dropped and the | |
21010 | maildir file is created with no tag. | |
21011 | ||
21012 | Tags can be used to encode the size of files in their names; see | |
21013 | quota_size_regex above for an example. The expansion of maildir_tag happens | |
21014 | after the message has been written. The value of the $message_size variable is | |
21015 | set to the number of bytes actually written. If the expansion is forced to | |
21016 | fail, the tag is ignored, but a non-forced failure causes delivery to be | |
21017 | deferred. The expanded tag may contain any printing characters except "/". | |
21018 | Non-printing characters in the string are ignored; if the resulting string is | |
21019 | empty, it is ignored. If it starts with an alphanumeric character, a leading | |
21020 | colon is inserted; this default has not proven to be the path that popular | |
21021 | maildir implementations have chosen (but changing it in Exim would break | |
21022 | backwards compatibility). | |
21023 | ||
21024 | For one common implementation, you might set: | |
21025 | ||
21026 | maildir_tag = ,S=${message_size} | |
21027 | ||
21028 | but you should check the documentation of the other software to be sure. | |
21029 | ||
21030 | It is advisable to also set quota_size_regex when setting maildir_tag as this | |
21031 | allows Exim to extract the size from your tag, instead of having to stat() each | |
21032 | message file. | |
21033 | ||
21034 | ||
21035 | 26.7 Using a maildirsize file | |
21036 | ----------------------------- | |
21037 | ||
21038 | If maildir_use_size_file is true, Exim implements the maildir++ rules for | |
21039 | storing quota and message size information in a file called maildirsize within | |
21040 | the toplevel maildir directory. If this file does not exist, Exim creates it, | |
21041 | setting the quota from the quota option of the transport. If the maildir | |
21042 | directory itself does not exist, it is created before any attempt to write a | |
21043 | maildirsize file. | |
21044 | ||
21045 | The maildirsize file is used to hold information about the sizes of messages in | |
21046 | the maildir, thus speeding up quota calculations. The quota value in the file | |
21047 | is just a cache; if the quota is changed in the transport, the new value | |
21048 | overrides the cached value when the next message is delivered. The cache is | |
21049 | maintained for the benefit of other programs that access the maildir and need | |
21050 | to know the quota. | |
21051 | ||
21052 | If the quota option in the transport is unset or zero, the maildirsize file is | |
21053 | maintained (with a zero quota setting), but no quota is imposed. | |
21054 | ||
21055 | A regular expression is available for controlling which directories in the | |
21056 | maildir participate in quota calculations when a maildirsizefile is in use. See | |
21057 | the description of the maildir_quota_directory_regex option above for details. | |
21058 | ||
21059 | ||
21060 | 26.8 Mailstore delivery | |
21061 | ----------------------- | |
21062 | ||
21063 | If the mailstore_format option is true, each message is written as two files in | |
21064 | the given directory. A unique base name is constructed from the message id and | |
21065 | the current delivery process, and the files that are written use this base name | |
21066 | plus the suffixes .env and .msg. The .env file contains the message's envelope, | |
21067 | and the .msg file contains the message itself. The base name is placed in the | |
21068 | variable $mailstore_basename. | |
21069 | ||
21070 | During delivery, the envelope is first written to a file with the suffix .tmp. | |
21071 | The .msg file is then written, and when it is complete, the .tmp file is | |
21072 | renamed as the .env file. Programs that access messages in mailstore format | |
21073 | should wait for the presence of both a .msg and a .env file before accessing | |
21074 | either of them. An alternative approach is to wait for the absence of a .tmp | |
21075 | file. | |
21076 | ||
21077 | The envelope file starts with any text defined by the mailstore_prefix option, | |
21078 | expanded and terminated by a newline if there isn't one. Then follows the | |
21079 | sender address on one line, then all the recipient addresses, one per line. | |
21080 | There can be more than one recipient only if the batch_max option is set | |
21081 | greater than one. Finally, mailstore_suffix is expanded and the result appended | |
21082 | to the file, followed by a newline if it does not end with one. | |
21083 | ||
21084 | If expansion of mailstore_prefix or mailstore_suffix ends with a forced | |
21085 | failure, it is ignored. Other expansion errors are treated as serious | |
21086 | configuration errors, and delivery is deferred. The variable | |
21087 | $mailstore_basename is available for use during these expansions. | |
21088 | ||
21089 | ||
21090 | 26.9 Non-special new file delivery | |
21091 | ---------------------------------- | |
21092 | ||
21093 | If neither maildir_format nor mailstore_format is set, a single new file is | |
21094 | created directly in the named directory. For example, when delivering messages | |
21095 | into files in batched SMTP format for later delivery to some host (see section | |
2813c06e | 21096 | 48.10), a setting such as |
420a0d19 CE |
21097 | |
21098 | directory = /var/bsmtp/$host | |
21099 | ||
21100 | might be used. A message is written to a file with a temporary name, which is | |
21101 | then renamed when the delivery is complete. The final name is obtained by | |
21102 | expanding the contents of the directory_file option. | |
21103 | ||
21104 | ||
21105 | ||
21106 | =============================================================================== | |
21107 | 27. THE AUTOREPLY TRANSPORT | |
21108 | ||
21109 | The autoreply transport is not a true transport in that it does not cause the | |
21110 | message to be transmitted. Instead, it generates a new mail message as an | |
21111 | automatic reply to the incoming message. References: and Auto-Submitted: header | |
21112 | lines are included. These are constructed according to the rules in RFCs 2822 | |
21113 | and 3834, respectively. | |
21114 | ||
21115 | If the router that passes the message to this transport does not have the | |
21116 | unseen option set, the original message (for the current recipient) is not | |
21117 | delivered anywhere. However, when the unseen option is set on the router that | |
21118 | passes the message to this transport, routing of the address continues, so | |
21119 | another router can set up a normal message delivery. | |
21120 | ||
21121 | The autoreply transport is usually run as the result of mail filtering, a | |
21122 | "vacation" message being the standard example. However, it can also be run | |
21123 | directly from a router like any other transport. To reduce the possibility of | |
21124 | message cascades, messages created by the autoreply transport always have empty | |
21125 | envelope sender addresses, like bounce messages. | |
21126 | ||
21127 | The parameters of the message to be sent can be specified in the configuration | |
21128 | by options described below. However, these are used only when the address | |
21129 | passed to the transport does not contain its own reply information. When the | |
21130 | transport is run as a consequence of a mail or vacation command in a filter | |
21131 | file, the parameters of the message are supplied by the filter, and passed with | |
21132 | the address. The transport's options that define the message are then ignored | |
21133 | (so they are not usually set in this case). The message is specified entirely | |
21134 | by the filter or by the transport; it is never built from a mixture of options. | |
21135 | However, the file_optional, mode, and return_message options apply in all | |
21136 | cases. | |
21137 | ||
21138 | Autoreply is implemented as a local transport. When used as a result of a | |
21139 | command in a user's filter file, autoreply normally runs under the uid and gid | |
21140 | of the user, and with appropriate current and home directories (see chapter 23 | |
21141 | ). | |
21142 | ||
21143 | There is a subtle difference between routing a message to a pipe transport that | |
21144 | generates some text to be returned to the sender, and routing it to an | |
21145 | autoreply transport. This difference is noticeable only if more than one | |
21146 | address from the same message is so handled. In the case of a pipe, the | |
21147 | separate outputs from the different addresses are gathered up and returned to | |
21148 | the sender in a single message, whereas if autoreply is used, a separate | |
21149 | message is generated for each address that is passed to it. | |
21150 | ||
21151 | Non-printing characters are not permitted in the header lines generated for the | |
21152 | message that autoreply creates, with the exception of newlines that are | |
21153 | immediately followed by white space. If any non-printing characters are found, | |
21154 | the transport defers. Whether characters with the top bit set count as printing | |
21155 | characters or not is controlled by the print_topbitchars global option. | |
21156 | ||
21157 | If any of the generic options for manipulating headers (for example, | |
21158 | headers_add) are set on an autoreply transport, they apply to the copy of the | |
21159 | original message that is included in the generated message when return_message | |
21160 | is set. They do not apply to the generated message itself. | |
21161 | ||
21162 | If the autoreply transport receives return code 2 from Exim when it submits the | |
21163 | message, indicating that there were no recipients, it does not treat this as an | |
21164 | error. This means that autoreplies sent to $sender_address when this is empty | |
21165 | (because the incoming message is a bounce message) do not cause problems. They | |
21166 | are just discarded. | |
21167 | ||
21168 | ||
21169 | 27.1 Private options for autoreply | |
21170 | ---------------------------------- | |
21171 | ||
2813c06e | 21172 | +-----------------------------------------------+ |
420a0d19 | 21173 | |bcc|Use: autoreply|Type: string*|Default: unset| |
2813c06e | 21174 | +-----------------------------------------------+ |
420a0d19 CE |
21175 | |
21176 | This specifies the addresses that are to receive "blind carbon copies" of the | |
21177 | message when the message is specified by the transport. | |
21178 | ||
2813c06e | 21179 | +----------------------------------------------+ |
420a0d19 | 21180 | |cc|Use: autoreply|Type: string*|Default: unset| |
2813c06e | 21181 | +----------------------------------------------+ |
420a0d19 CE |
21182 | |
21183 | This specifies recipients of the message and the contents of the Cc: header | |
21184 | when the message is specified by the transport. | |
21185 | ||
2813c06e | 21186 | +------------------------------------------------+ |
420a0d19 | 21187 | |file|Use: autoreply|Type: string*|Default: unset| |
2813c06e | 21188 | +------------------------------------------------+ |
420a0d19 CE |
21189 | |
21190 | The contents of the file are sent as the body of the message when the message | |
21191 | is specified by the transport. If both file and text are set, the text string | |
21192 | comes first. | |
21193 | ||
2813c06e | 21194 | +-------------------------------------------------------+ |
420a0d19 | 21195 | |file_expand|Use: autoreply|Type: boolean|Default: false| |
2813c06e | 21196 | +-------------------------------------------------------+ |
420a0d19 CE |
21197 | |
21198 | If this is set, the contents of the file named by the file option are subjected | |
21199 | to string expansion as they are added to the message. | |
21200 | ||
2813c06e | 21201 | +---------------------------------------------------------+ |
420a0d19 | 21202 | |file_optional|Use: autoreply|Type: boolean|Default: false| |
2813c06e | 21203 | +---------------------------------------------------------+ |
420a0d19 CE |
21204 | |
21205 | If this option is true, no error is generated if the file named by the file | |
21206 | option or passed with the address does not exist or cannot be read. | |
21207 | ||
2813c06e | 21208 | +------------------------------------------------+ |
420a0d19 | 21209 | |from|Use: autoreply|Type: string*|Default: unset| |
2813c06e | 21210 | +------------------------------------------------+ |
420a0d19 CE |
21211 | |
21212 | This specifies the contents of the From: header when the message is specified | |
21213 | by the transport. | |
21214 | ||
2813c06e | 21215 | +---------------------------------------------------+ |
420a0d19 | 21216 | |headers|Use: autoreply|Type: string*|Default: unset| |
2813c06e | 21217 | +---------------------------------------------------+ |
420a0d19 CE |
21218 | |
21219 | This specifies additional RFC 2822 headers that are to be added to the message | |
21220 | when the message is specified by the transport. Several can be given by using " | |
21221 | \n" to separate them. There is no check on the format. | |
21222 | ||
2813c06e | 21223 | +-----------------------------------------------+ |
420a0d19 | 21224 | |log|Use: autoreply|Type: string*|Default: unset| |
2813c06e | 21225 | +-----------------------------------------------+ |
420a0d19 CE |
21226 | |
21227 | This option names a file in which a record of every message sent is logged when | |
21228 | the message is specified by the transport. | |
21229 | ||
2813c06e | 21230 | +-----------------------------------------------------+ |
420a0d19 | 21231 | |mode|Use: autoreply|Type: octal integer|Default: 0600| |
2813c06e | 21232 | +-----------------------------------------------------+ |
420a0d19 CE |
21233 | |
21234 | If either the log file or the "once" file has to be created, this mode is used. | |
21235 | ||
2813c06e | 21236 | +------------------------------------------------------------+ |
420a0d19 | 21237 | |never_mail|Use: autoreply|Type: address list*|Default: unset| |
2813c06e | 21238 | +------------------------------------------------------------+ |
420a0d19 CE |
21239 | |
21240 | If any run of the transport creates a message with a recipient that matches any | |
21241 | item in the list, that recipient is quietly discarded. If all recipients are | |
21242 | discarded, no message is created. This applies both when the recipients are | |
21243 | generated by a filter and when they are specified in the transport. | |
21244 | ||
2813c06e | 21245 | +------------------------------------------------+ |
420a0d19 | 21246 | |once|Use: autoreply|Type: string*|Default: unset| |
2813c06e | 21247 | +------------------------------------------------+ |
420a0d19 CE |
21248 | |
21249 | This option names a file or DBM database in which a record of each To: | |
21250 | recipient is kept when the message is specified by the transport. Note: This | |
21251 | does not apply to Cc: or Bcc: recipients. | |
21252 | ||
21253 | If once is unset, or is set to an empty string, the message is always sent. By | |
21254 | default, if once is set to a non-empty file name, the message is not sent if a | |
21255 | potential recipient is already listed in the database. However, if the | |
21256 | once_repeat option specifies a time greater than zero, the message is sent if | |
21257 | that much time has elapsed since a message was last sent to this recipient. A | |
21258 | setting of zero time for once_repeat (the default) prevents a message from | |
21259 | being sent a second time - in this case, zero means infinity. | |
21260 | ||
21261 | If once_file_size is zero, a DBM database is used to remember recipients, and | |
21262 | it is allowed to grow as large as necessary. If once_file_size is set greater | |
21263 | than zero, it changes the way Exim implements the once option. Instead of using | |
21264 | a DBM file to record every recipient it sends to, it uses a regular file, whose | |
21265 | size will never get larger than the given value. | |
21266 | ||
21267 | In the file, Exim keeps a linear list of recipient addresses and the times at | |
21268 | which they were sent messages. If the file is full when a new address needs to | |
21269 | be added, the oldest address is dropped. If once_repeat is not set, this means | |
21270 | that a given recipient may receive multiple messages, but at unpredictable | |
21271 | intervals that depend on the rate of turnover of addresses in the file. If | |
21272 | once_repeat is set, it specifies a maximum time between repeats. | |
21273 | ||
2813c06e | 21274 | +------------------------------------------------------+ |
420a0d19 | 21275 | |once_file_size|Use: autoreply|Type: integer|Default: 0| |
2813c06e | 21276 | +------------------------------------------------------+ |
420a0d19 CE |
21277 | |
21278 | See once above. | |
21279 | ||
2813c06e | 21280 | +--------------------------------------------------+ |
420a0d19 | 21281 | |once_repeat|Use: autoreply|Type: time*|Default: 0s| |
2813c06e | 21282 | +--------------------------------------------------+ |
420a0d19 CE |
21283 | |
21284 | See once above. After expansion, the value of this option must be a valid time | |
21285 | value. | |
21286 | ||
2813c06e | 21287 | +----------------------------------------------------+ |
420a0d19 | 21288 | |reply_to|Use: autoreply|Type: string*|Default: unset| |
2813c06e | 21289 | +----------------------------------------------------+ |
420a0d19 CE |
21290 | |
21291 | This specifies the contents of the Reply-To: header when the message is | |
21292 | specified by the transport. | |
21293 | ||
2813c06e | 21294 | +----------------------------------------------------------+ |
420a0d19 | 21295 | |return_message|Use: autoreply|Type: boolean|Default: false| |
2813c06e | 21296 | +----------------------------------------------------------+ |
420a0d19 CE |
21297 | |
21298 | If this is set, a copy of the original message is returned with the new | |
21299 | message, subject to the maximum size set in the return_size_limit global | |
21300 | configuration option. | |
21301 | ||
2813c06e | 21302 | +---------------------------------------------------+ |
420a0d19 | 21303 | |subject|Use: autoreply|Type: string*|Default: unset| |
2813c06e | 21304 | +---------------------------------------------------+ |
420a0d19 CE |
21305 | |
21306 | This specifies the contents of the Subject: header when the message is | |
21307 | specified by the transport. It is tempting to quote the original subject in | |
21308 | automatic responses. For example: | |
21309 | ||
21310 | subject = Re: $h_subject: | |
21311 | ||
21312 | There is a danger in doing this, however. It may allow a third party to | |
21313 | subscribe your users to an opt-in mailing list, provided that the list accepts | |
21314 | bounce messages as subscription confirmations. Well-managed lists require a | |
21315 | non-bounce message to confirm a subscription, so the danger is relatively | |
21316 | small. | |
21317 | ||
2813c06e | 21318 | +------------------------------------------------+ |
420a0d19 | 21319 | |text|Use: autoreply|Type: string*|Default: unset| |
2813c06e | 21320 | +------------------------------------------------+ |
420a0d19 CE |
21321 | |
21322 | This specifies a single string to be used as the body of the message when the | |
21323 | message is specified by the transport. If both text and file are set, the text | |
21324 | comes first. | |
21325 | ||
2813c06e | 21326 | +----------------------------------------------+ |
420a0d19 | 21327 | |to|Use: autoreply|Type: string*|Default: unset| |
2813c06e | 21328 | +----------------------------------------------+ |
420a0d19 CE |
21329 | |
21330 | This specifies recipients of the message and the contents of the To: header | |
21331 | when the message is specified by the transport. | |
21332 | ||
21333 | ||
21334 | ||
21335 | =============================================================================== | |
21336 | 28. THE LMTP TRANSPORT | |
21337 | ||
21338 | The lmtp transport runs the LMTP protocol (RFC 2033) over a pipe to a specified | |
21339 | command or by interacting with a Unix domain socket. This transport is | |
21340 | something of a cross between the pipe and smtp transports. Exim also has | |
21341 | support for using LMTP over TCP/IP; this is implemented as an option for the | |
21342 | smtp transport. Because LMTP is expected to be of minority interest, the | |
21343 | default build-time configure in src/EDITME has it commented out. You need to | |
21344 | ensure that | |
21345 | ||
21346 | TRANSPORT_LMTP=yes | |
21347 | ||
21348 | is present in your Local/Makefile in order to have the lmtp transport included | |
21349 | in the Exim binary. The private options of the lmtp transport are as follows: | |
21350 | ||
2813c06e | 21351 | +-----------------------------------------------+ |
420a0d19 | 21352 | |batch_id|Use: lmtp|Type: string*|Default: unset| |
2813c06e | 21353 | +-----------------------------------------------+ |
420a0d19 CE |
21354 | |
21355 | See the description of local delivery batching in chapter 25. | |
21356 | ||
2813c06e | 21357 | +--------------------------------------------+ |
420a0d19 | 21358 | |batch_max|Use: lmtp|Type: integer|Default: 1| |
2813c06e | 21359 | +--------------------------------------------+ |
420a0d19 CE |
21360 | |
21361 | This limits the number of addresses that can be handled in a single delivery. | |
21362 | Most LMTP servers can handle several addresses at once, so it is normally a | |
21363 | good idea to increase this value. See the description of local delivery | |
21364 | batching in chapter 25. | |
21365 | ||
2813c06e | 21366 | +----------------------------------------------+ |
420a0d19 | 21367 | |command|Use: lmtp|Type: string*|Default: unset| |
2813c06e | 21368 | +----------------------------------------------+ |
420a0d19 CE |
21369 | |
21370 | This option must be set if socket is not set. The string is a command which is | |
21371 | run in a separate process. It is split up into a command name and list of | |
21372 | arguments, each of which is separately expanded (so expansion cannot change the | |
21373 | number of arguments). The command is run directly, not via a shell. The message | |
21374 | is passed to the new process using the standard input and output to operate the | |
21375 | LMTP protocol. | |
21376 | ||
2813c06e | 21377 | +---------------------------------------------------+ |
420a0d19 | 21378 | |ignore_quota|Use: lmtp|Type: boolean|Default: false| |
2813c06e | 21379 | +---------------------------------------------------+ |
420a0d19 CE |
21380 | |
21381 | If this option is set true, the string "IGNOREQUOTA" is added to RCPT commands, | |
21382 | provided that the LMTP server has advertised support for IGNOREQUOTA in its | |
21383 | response to the LHLO command. | |
21384 | ||
2813c06e | 21385 | +---------------------------------------------+ |
420a0d19 | 21386 | |socket|Use: lmtp|Type: string*|Default: unset| |
2813c06e | 21387 | +---------------------------------------------+ |
420a0d19 CE |
21388 | |
21389 | This option must be set if command is not set. The result of expansion must be | |
21390 | the name of a Unix domain socket. The transport connects to the socket and | |
21391 | delivers the message to it using the LMTP protocol. | |
21392 | ||
2813c06e | 21393 | +----------------------------------------+ |
420a0d19 | 21394 | |timeout|Use: lmtp|Type: time|Default: 5m| |
2813c06e | 21395 | +----------------------------------------+ |
420a0d19 CE |
21396 | |
21397 | The transport is aborted if the created process or Unix domain socket does not | |
21398 | respond to LMTP commands or message input within this timeout. Delivery is | |
21399 | deferred, and will be tried again later. Here is an example of a typical LMTP | |
21400 | transport: | |
21401 | ||
21402 | lmtp: | |
21403 | driver = lmtp | |
21404 | command = /some/local/lmtp/delivery/program | |
21405 | batch_max = 20 | |
21406 | user = exim | |
21407 | ||
21408 | This delivers up to 20 addresses at a time, in a mixture of domains if | |
21409 | necessary, running as the user exim. | |
21410 | ||
21411 | ||
21412 | ||
21413 | =============================================================================== | |
21414 | 29. THE PIPE TRANSPORT | |
21415 | ||
21416 | The pipe transport is used to deliver messages via a pipe to a command running | |
21417 | in another process. One example is the use of pipe as a pseudo-remote transport | |
21418 | for passing messages to some other delivery mechanism (such as UUCP). Another | |
21419 | is the use by individual users to automatically process their incoming | |
21420 | messages. The pipe transport can be used in one of the following ways: | |
21421 | ||
21422 | * A router routes one address to a transport in the normal way, and the | |
21423 | transport is configured as a pipe transport. In this case, $local_part | |
21424 | contains the local part of the address (as usual), and the command that is | |
21425 | run is specified by the command option on the transport. | |
21426 | ||
21427 | * If the batch_max option is set greater than 1 (the default is 1), the | |
21428 | transport can handle more than one address in a single run. In this case, | |
21429 | when more than one address is routed to the transport, $local_part is not | |
21430 | set (because it is not unique). However, the pseudo-variable | |
21431 | $pipe_addresses (described in section 29.3 below) contains all the | |
21432 | addresses that are routed to the transport. | |
21433 | ||
21434 | * A router redirects an address directly to a pipe command (for example, from | |
21435 | an alias or forward file). In this case, $address_pipe contains the text of | |
21436 | the pipe command, and the command option on the transport is ignored unless | |
21437 | force_command is set. If only one address is being transported (batch_max | |
21438 | is not greater than one, or only one address was redirected to this pipe | |
21439 | command), $local_part contains the local part that was redirected. | |
21440 | ||
21441 | The pipe transport is a non-interactive delivery method. Exim can also deliver | |
21442 | messages over pipes using the LMTP interactive protocol. This is implemented by | |
21443 | the lmtp transport. | |
21444 | ||
21445 | In the case when pipe is run as a consequence of an entry in a local user's | |
21446 | .forward file, the command runs under the uid and gid of that user. In other | |
21447 | cases, the uid and gid have to be specified explicitly, either on the transport | |
21448 | or on the router that handles the address. Current and "home" directories are | |
21449 | also controllable. See chapter 23 for details of the local delivery environment | |
21450 | and chapter 25 for a discussion of local delivery batching. | |
21451 | ||
21452 | ||
21453 | 29.1 Concurrent delivery | |
21454 | ------------------------ | |
21455 | ||
21456 | If two messages arrive at almost the same time, and both are routed to a pipe | |
21457 | delivery, the two pipe transports may be run concurrently. You must ensure that | |
21458 | any pipe commands you set up are robust against this happening. If the commands | |
2813c06e CE |
21459 | write to a file, the exim_lock utility might be of use. Alternatively the |
21460 | max_parallel option could be used with a value of "1" to enforce serialization. | |
420a0d19 CE |
21461 | |
21462 | ||
21463 | 29.2 Returned status and data | |
21464 | ----------------------------- | |
21465 | ||
21466 | If the command exits with a non-zero return code, the delivery is deemed to | |
21467 | have failed, unless either the ignore_status option is set (in which case the | |
21468 | return code is treated as zero), or the return code is one of those listed in | |
21469 | the temp_errors option, which are interpreted as meaning "try again later". In | |
21470 | this case, delivery is deferred. Details of a permanent failure are logged, but | |
21471 | are not included in the bounce message, which merely contains "local delivery | |
21472 | failed". | |
21473 | ||
21474 | If the command exits on a signal and the freeze_signal option is set then the | |
21475 | message will be frozen in the queue. If that option is not set, a bounce will | |
21476 | be sent as normal. | |
21477 | ||
21478 | If the return code is greater than 128 and the command being run is a shell | |
21479 | script, it normally means that the script was terminated by a signal whose | |
21480 | value is the return code minus 128. The freeze_signal option does not apply in | |
21481 | this case. | |
21482 | ||
21483 | If Exim is unable to run the command (that is, if execve() fails), the return | |
21484 | code is set to 127. This is the value that a shell returns if it is asked to | |
21485 | run a non-existent command. The wording for the log line suggests that a | |
21486 | non-existent command may be the problem. | |
21487 | ||
21488 | The return_output option can affect the result of a pipe delivery. If it is set | |
21489 | and the command produces any output on its standard output or standard error | |
21490 | streams, the command is considered to have failed, even if it gave a zero | |
21491 | return code or if ignore_status is set. The output from the command is included | |
21492 | as part of the bounce message. The return_fail_output option is similar, except | |
21493 | that output is returned only when the command exits with a failure return code, | |
21494 | that is, a value other than zero or a code that matches temp_errors. | |
21495 | ||
21496 | ||
21497 | 29.3 How the command is run | |
21498 | --------------------------- | |
21499 | ||
21500 | The command line is (by default) broken down into a command name and arguments | |
21501 | by the pipe transport itself. The allow_commands and restrict_to_path options | |
21502 | can be used to restrict the commands that may be run. | |
21503 | ||
21504 | Unquoted arguments are delimited by white space. If an argument appears in | |
21505 | double quotes, backslash is interpreted as an escape character in the usual | |
21506 | way. If an argument appears in single quotes, no escaping is done. | |
21507 | ||
21508 | String expansion is applied to the command line except when it comes from a | |
21509 | traditional .forward file (commands from a filter file are expanded). The | |
21510 | expansion is applied to each argument in turn rather than to the whole line. | |
21511 | For this reason, any string expansion item that contains white space must be | |
21512 | quoted so as to be contained within a single argument. A setting such as | |
21513 | ||
21514 | command = /some/path ${if eq{$local_part}{postmaster}{xx}{yy}} | |
21515 | ||
21516 | will not work, because the expansion item gets split between several arguments. | |
21517 | You have to write | |
21518 | ||
21519 | command = /some/path "${if eq{$local_part}{postmaster}{xx}{yy}}" | |
21520 | ||
21521 | to ensure that it is all in one argument. The expansion is done in this way, | |
21522 | argument by argument, so that the number of arguments cannot be changed as a | |
21523 | result of expansion, and quotes or backslashes in inserted variables do not | |
21524 | interact with external quoting. However, this leads to problems if you want to | |
21525 | generate multiple arguments (or the command name plus arguments) from a single | |
21526 | expansion. In this situation, the simplest solution is to use a shell. For | |
21527 | example: | |
21528 | ||
21529 | command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}} | |
21530 | ||
21531 | Special handling takes place when an argument consists of precisely the text | |
21532 | "$pipe_addresses". This is not a general expansion variable; the only place | |
21533 | this string is recognized is when it appears as an argument for a pipe or | |
21534 | transport filter command. It causes each address that is being handled to be | |
21535 | inserted in the argument list at that point as a separate argument. This avoids | |
21536 | any problems with spaces or shell metacharacters, and is of use when a pipe | |
21537 | transport is handling groups of addresses in a batch. | |
21538 | ||
21539 | If force_command is enabled on the transport, Special handling takes place for | |
21540 | an argument that consists of precisely the text "$address_pipe". It is handled | |
21541 | similarly to $pipe_addresses above. It is expanded and each argument is | |
21542 | inserted in the argument list at that point as a separate argument. The | |
21543 | "$address_pipe" item does not need to be the only item in the argument; in | |
21544 | fact, if it were then force_command should behave as a no-op. Rather, it should | |
21545 | be used to adjust the command run while preserving the argument vector | |
21546 | separation. | |
21547 | ||
21548 | After splitting up into arguments and expansion, the resulting command is run | |
21549 | in a subprocess directly from the transport, not under a shell. The message | |
21550 | that is being delivered is supplied on the standard input, and the standard | |
21551 | output and standard error are both connected to a single pipe that is read by | |
21552 | Exim. The max_output option controls how much output the command may produce, | |
21553 | and the return_output and return_fail_output options control what is done with | |
21554 | it. | |
21555 | ||
21556 | Not running the command under a shell (by default) lessens the security risks | |
21557 | in cases when a command from a user's filter file is built out of data that was | |
21558 | taken from an incoming message. If a shell is required, it can of course be | |
21559 | explicitly specified as the command to be run. However, there are circumstances | |
21560 | where existing commands (for example, in .forward files) expect to be run under | |
21561 | a shell and cannot easily be modified. To allow for these cases, there is an | |
21562 | option called use_shell, which changes the way the pipe transport works. | |
21563 | Instead of breaking up the command line as just described, it expands it as a | |
21564 | single string and passes the result to /bin/sh. The restrict_to_path option and | |
21565 | the $pipe_addresses facility cannot be used with use_shell, and the whole | |
21566 | mechanism is inherently less secure. | |
21567 | ||
21568 | ||
21569 | 29.4 Environment variables | |
21570 | -------------------------- | |
21571 | ||
21572 | The environment variables listed below are set up when the command is invoked. | |
21573 | This list is a compromise for maximum compatibility with other MTAs. Note that | |
21574 | the environment option can be used to add additional variables to this | |
2813c06e CE |
21575 | environment. The environment for the pipe transport is not subject to the |
21576 | add_environment and keep_environment main config options. | |
420a0d19 CE |
21577 | |
21578 | DOMAIN the domain of the address | |
21579 | HOME the home directory, if set | |
21580 | HOST the host name when called from a router (see below) | |
21581 | LOCAL_PART see below | |
21582 | LOCAL_PART_PREFIX see below | |
21583 | LOCAL_PART_SUFFIX see below | |
21584 | LOGNAME see below | |
21585 | MESSAGE_ID Exim's local ID for the message | |
21586 | PATH as specified by the path option below | |
21587 | QUALIFY_DOMAIN the sender qualification domain | |
21588 | RECIPIENT the complete recipient address | |
21589 | SENDER the sender of the message (empty if a bounce) | |
21590 | SHELL /bin/sh | |
21591 | TZ the value of the timezone option, if set | |
21592 | USER see below | |
21593 | ||
21594 | When a pipe transport is called directly from (for example) an accept router, | |
21595 | LOCAL_PART is set to the local part of the address. When it is called as a | |
21596 | result of a forward or alias expansion, LOCAL_PART is set to the local part of | |
21597 | the address that was expanded. In both cases, any affixes are removed from the | |
21598 | local part, and made available in LOCAL_PART_PREFIX and LOCAL_PART_SUFFIX, | |
21599 | respectively. LOGNAME and USER are set to the same value as LOCAL_PART for | |
21600 | compatibility with other MTAs. | |
21601 | ||
21602 | HOST is set only when a pipe transport is called from a router that associates | |
21603 | hosts with an address, typically when using pipe as a pseudo-remote transport. | |
21604 | HOST is set to the first host name specified by the router. | |
21605 | ||
21606 | If the transport's generic home_directory option is set, its value is used for | |
21607 | the HOME environment variable. Otherwise, a home directory may be set by the | |
21608 | router's transport_home_directory option, which defaults to the user's home | |
21609 | directory if check_local_user is set. | |
21610 | ||
21611 | ||
21612 | 29.5 Private options for pipe | |
21613 | ----------------------------- | |
21614 | ||
2813c06e | 21615 | +----------------------------------------------------------+ |
420a0d19 | 21616 | |allow_commands|Use: pipe|Type: string list*|Default: unset| |
2813c06e | 21617 | +----------------------------------------------------------+ |
420a0d19 CE |
21618 | |
21619 | The string is expanded, and is then interpreted as a colon-separated list of | |
21620 | permitted commands. If restrict_to_path is not set, the only commands permitted | |
21621 | are those in the allow_commands list. They need not be absolute paths; the path | |
21622 | option is still used for relative paths. If restrict_to_path is set with | |
21623 | allow_commands, the command must either be in the allow_commands list, or a | |
21624 | name without any slashes that is found on the path. In other words, if neither | |
21625 | allow_commands nor restrict_to_path is set, there is no restriction on the | |
21626 | command, but otherwise only commands that are permitted by one or the other are | |
21627 | allowed. For example, if | |
21628 | ||
21629 | allow_commands = /usr/bin/vacation | |
21630 | ||
21631 | and restrict_to_path is not set, the only permitted command is /usr/bin/ | |
21632 | vacation. The allow_commands option may not be set if use_shell is set. | |
21633 | ||
2813c06e | 21634 | +-----------------------------------------------+ |
420a0d19 | 21635 | |batch_id|Use: pipe|Type: string*|Default: unset| |
2813c06e | 21636 | +-----------------------------------------------+ |
420a0d19 CE |
21637 | |
21638 | See the description of local delivery batching in chapter 25. | |
21639 | ||
2813c06e | 21640 | +--------------------------------------------+ |
420a0d19 | 21641 | |batch_max|Use: pipe|Type: integer|Default: 1| |
2813c06e | 21642 | +--------------------------------------------+ |
420a0d19 CE |
21643 | |
21644 | This limits the number of addresses that can be handled in a single delivery. | |
21645 | See the description of local delivery batching in chapter 25. | |
21646 | ||
2813c06e | 21647 | +--------------------------------------------------+ |
420a0d19 | 21648 | |check_string|Use: pipe|Type: string|Default: unset| |
2813c06e | 21649 | +--------------------------------------------------+ |
420a0d19 CE |
21650 | |
21651 | As pipe writes the message, the start of each line is tested for matching | |
21652 | check_string, and if it does, the initial matching characters are replaced by | |
21653 | the contents of escape_string, provided both are set. The value of check_string | |
21654 | is a literal string, not a regular expression, and the case of any letters it | |
21655 | contains is significant. When use_bsmtp is set, the contents of check_string | |
21656 | and escape_string are forced to values that implement the SMTP escaping | |
21657 | protocol. Any settings made in the configuration file are ignored. | |
21658 | ||
2813c06e | 21659 | +----------------------------------------------+ |
420a0d19 | 21660 | |command|Use: pipe|Type: string*|Default: unset| |
2813c06e | 21661 | +----------------------------------------------+ |
420a0d19 CE |
21662 | |
21663 | This option need not be set when pipe is being used to deliver to pipes | |
21664 | obtained directly from address redirections. In other cases, the option must be | |
21665 | set, to provide a command to be run. It need not yield an absolute path (see | |
21666 | the path option below). The command is split up into separate arguments by | |
21667 | Exim, and each argument is separately expanded, as described in section 29.3 | |
21668 | above. | |
21669 | ||
2813c06e | 21670 | +--------------------------------------------------+ |
420a0d19 | 21671 | |environment|Use: pipe|Type: string*|Default: unset| |
2813c06e | 21672 | +--------------------------------------------------+ |
420a0d19 CE |
21673 | |
21674 | This option is used to add additional variables to the environment in which the | |
21675 | command runs (see section 29.4 for the default list). Its value is a string | |
21676 | which is expanded, and then interpreted as a colon-separated list of | |
21677 | environment settings of the form <name>=<value>. | |
21678 | ||
2813c06e | 21679 | +---------------------------------------------------+ |
420a0d19 | 21680 | |escape_string|Use: pipe|Type: string|Default: unset| |
2813c06e | 21681 | +---------------------------------------------------+ |
420a0d19 CE |
21682 | |
21683 | See check_string above. | |
21684 | ||
2813c06e | 21685 | +-------------------------------------------------------+ |
420a0d19 | 21686 | |freeze_exec_fail|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21687 | +-------------------------------------------------------+ |
420a0d19 CE |
21688 | |
21689 | Failure to exec the command in a pipe transport is by default treated like any | |
21690 | other failure while running the command. However, if freeze_exec_fail is set, | |
21691 | failure to exec is treated specially, and causes the message to be frozen, | |
21692 | whatever the setting of ignore_status. | |
21693 | ||
2813c06e | 21694 | +----------------------------------------------------+ |
420a0d19 | 21695 | |freeze_signal|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21696 | +----------------------------------------------------+ |
420a0d19 CE |
21697 | |
21698 | Normally if the process run by a command in a pipe transport exits on a signal, | |
21699 | a bounce message is sent. If freeze_signal is set, the message will be frozen | |
21700 | in Exim's queue instead. | |
21701 | ||
2813c06e | 21702 | +----------------------------------------------------+ |
420a0d19 | 21703 | |force_command|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21704 | +----------------------------------------------------+ |
420a0d19 CE |
21705 | |
21706 | Normally when a router redirects an address directly to a pipe command the | |
21707 | command option on the transport is ignored. If force_command is set, the | |
21708 | command option will used. This is especially useful for forcing a wrapper or | |
21709 | additional argument to be added to the command. For example: | |
21710 | ||
21711 | command = /usr/bin/remote_exec myhost -- $address_pipe | |
21712 | force_command | |
21713 | ||
21714 | Note that $address_pipe is handled specially in command when force_command is | |
21715 | set, expanding out to the original argument vector as separate items, similarly | |
21716 | to a Unix shell ""$@"" construct. | |
21717 | ||
2813c06e | 21718 | +----------------------------------------------------+ |
420a0d19 | 21719 | |ignore_status|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21720 | +----------------------------------------------------+ |
420a0d19 CE |
21721 | |
21722 | If this option is true, the status returned by the subprocess that is set up to | |
21723 | run the command is ignored, and Exim behaves as if zero had been returned. | |
21724 | Otherwise, a non-zero status or termination by signal causes an error return | |
21725 | from the transport unless the status value is one of those listed in | |
21726 | temp_errors; these cause the delivery to be deferred and tried again later. | |
21727 | ||
21728 | Note: This option does not apply to timeouts, which do not return a status. See | |
21729 | the timeout_defer option for how timeouts are handled. | |
21730 | ||
2813c06e | 21731 | +-------------------------------------------------------+ |
420a0d19 | 21732 | |log_defer_output|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21733 | +-------------------------------------------------------+ |
420a0d19 CE |
21734 | |
21735 | If this option is set, and the status returned by the command is one of the | |
21736 | codes listed in temp_errors (that is, delivery was deferred), and any output | |
2813c06e CE |
21737 | was produced on stdout or stderr, the first line of it is written to the main |
21738 | log. | |
420a0d19 | 21739 | |
2813c06e | 21740 | +------------------------------------------------------+ |
420a0d19 | 21741 | |log_fail_output|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21742 | +------------------------------------------------------+ |
420a0d19 | 21743 | |
2813c06e CE |
21744 | If this option is set, and the command returns any output on stdout or stderr, |
21745 | and also ends with a return code that is neither zero nor one of the return | |
21746 | codes listed in temp_errors (that is, the delivery failed), the first line of | |
21747 | output is written to the main log. This option and log_output are mutually | |
21748 | exclusive. Only one of them may be set. | |
420a0d19 | 21749 | |
2813c06e | 21750 | +-------------------------------------------------+ |
420a0d19 | 21751 | |log_output|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21752 | +-------------------------------------------------+ |
420a0d19 | 21753 | |
2813c06e CE |
21754 | If this option is set and the command returns any output on stdout or stderr, |
21755 | the first line of output is written to the main log, whatever the return code. | |
21756 | This option and log_fail_output are mutually exclusive. Only one of them may be | |
21757 | set. | |
420a0d19 | 21758 | |
2813c06e | 21759 | +-----------------------------------------------+ |
420a0d19 | 21760 | |max_output|Use: pipe|Type: integer|Default: 20K| |
2813c06e | 21761 | +-----------------------------------------------+ |
420a0d19 CE |
21762 | |
21763 | This specifies the maximum amount of output that the command may produce on its | |
21764 | standard output and standard error file combined. If the limit is exceeded, the | |
21765 | process running the command is killed. This is intended as a safety measure to | |
21766 | catch runaway processes. The limit is applied independently of the settings of | |
21767 | the options that control what is done with such output (for example, | |
21768 | return_output). Because of buffering effects, the amount of output may exceed | |
21769 | the limit by a small amount before Exim notices. | |
21770 | ||
2813c06e | 21771 | +---------------------------------------------------------+ |
420a0d19 | 21772 | |message_prefix|Use: pipe|Type: string*|Default: see below| |
2813c06e | 21773 | +---------------------------------------------------------+ |
420a0d19 CE |
21774 | |
21775 | The string specified here is expanded and output at the start of every message. | |
21776 | The default is unset if use_bsmtp is set. Otherwise it is | |
21777 | ||
21778 | message_prefix = \ | |
21779 | From ${if def:return_path{$return_path}{MAILER-DAEMON}}\ | |
21780 | ${tod_bsdinbox}\n | |
21781 | ||
21782 | This is required by the commonly used /usr/bin/vacation program. However, it | |
21783 | must not be present if delivery is to the Cyrus IMAP server, or to the tmail | |
21784 | local delivery agent. The prefix can be suppressed by setting | |
21785 | ||
21786 | message_prefix = | |
21787 | ||
21788 | Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\ | |
21789 | n" in message_prefix. | |
21790 | ||
2813c06e | 21791 | +---------------------------------------------------------+ |
420a0d19 | 21792 | |message_suffix|Use: pipe|Type: string*|Default: see below| |
2813c06e | 21793 | +---------------------------------------------------------+ |
420a0d19 CE |
21794 | |
21795 | The string specified here is expanded and output at the end of every message. | |
21796 | The default is unset if use_bsmtp is set. Otherwise it is a single newline. The | |
21797 | suffix can be suppressed by setting | |
21798 | ||
21799 | message_suffix = | |
21800 | ||
21801 | Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\ | |
21802 | n" in message_suffix. | |
21803 | ||
2813c06e CE |
21804 | +---------------------------------------------------+ |
21805 | |path|Use: pipe|Type: string*|Default: /bin:/usr/bin| | |
21806 | +---------------------------------------------------+ | |
420a0d19 | 21807 | |
2813c06e | 21808 | This option is expanded and |
420a0d19 | 21809 | |
2813c06e CE |
21810 | specifies the string that is set up in the PATH environment variable of the |
21811 | subprocess. If the command option does not yield an absolute path name, the | |
21812 | command is sought in the PATH directories, in the usual way. Warning: This does | |
21813 | not apply to a command specified as a transport filter. | |
420a0d19 | 21814 | |
2813c06e | 21815 | +------------------------------------------------------+ |
420a0d19 | 21816 | |permit_coredump|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21817 | +------------------------------------------------------+ |
420a0d19 CE |
21818 | |
21819 | Normally Exim inhibits core-dumps during delivery. If you have a need to get a | |
21820 | core-dump of a pipe command, enable this command. This enables core-dumps | |
21821 | during delivery and affects both the Exim binary and the pipe command run. It | |
21822 | is recommended that this option remain off unless and until you have a need for | |
21823 | it and that this only be enabled when needed, as the risk of excessive resource | |
21824 | consumption can be quite high. Note also that Exim is typically installed as a | |
21825 | setuid binary and most operating systems will inhibit coredumps of these by | |
21826 | default, so further OS-specific action may be required. | |
21827 | ||
2813c06e | 21828 | +------------------------------------------------------+ |
420a0d19 | 21829 | |pipe_as_creator|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21830 | +------------------------------------------------------+ |
420a0d19 CE |
21831 | |
21832 | If the generic user option is not set and this option is true, the delivery | |
21833 | process is run under the uid that was in force when Exim was originally called | |
21834 | to accept the message. If the group id is not otherwise set (via the generic | |
21835 | group option), the gid that was in force when Exim was originally called to | |
21836 | accept the message is used. | |
21837 | ||
2813c06e | 21838 | +-------------------------------------------------------+ |
420a0d19 | 21839 | |restrict_to_path|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21840 | +-------------------------------------------------------+ |
420a0d19 CE |
21841 | |
21842 | When this option is set, any command name not listed in allow_commands must | |
21843 | contain no slashes. The command is searched for only in the directories listed | |
21844 | in the path option. This option is intended for use in the case when a pipe | |
21845 | command has been generated from a user's .forward file. This is usually handled | |
21846 | by a pipe transport called address_pipe. | |
21847 | ||
2813c06e | 21848 | +---------------------------------------------------------+ |
420a0d19 | 21849 | |return_fail_output|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21850 | +---------------------------------------------------------+ |
420a0d19 CE |
21851 | |
21852 | If this option is true, and the command produced any output and ended with a | |
21853 | return code other than zero or one of the codes listed in temp_errors (that is, | |
21854 | the delivery failed), the output is returned in the bounce message. However, if | |
21855 | the message has a null sender (that is, it is itself a bounce message), output | |
21856 | from the command is discarded. This option and return_output are mutually | |
21857 | exclusive. Only one of them may be set. | |
21858 | ||
2813c06e | 21859 | +----------------------------------------------------+ |
420a0d19 | 21860 | |return_output|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21861 | +----------------------------------------------------+ |
420a0d19 CE |
21862 | |
21863 | If this option is true, and the command produced any output, the delivery is | |
21864 | deemed to have failed whatever the return code from the command, and the output | |
21865 | is returned in the bounce message. Otherwise, the output is just discarded. | |
21866 | However, if the message has a null sender (that is, it is a bounce message), | |
21867 | output from the command is always discarded, whatever the setting of this | |
21868 | option. This option and return_fail_output are mutually exclusive. Only one of | |
21869 | them may be set. | |
21870 | ||
2813c06e | 21871 | +----------------------------------------------------------+ |
420a0d19 | 21872 | |temp_errors|Use: pipe|Type: string list|Default: see below| |
2813c06e | 21873 | +----------------------------------------------------------+ |
420a0d19 CE |
21874 | |
21875 | This option contains either a colon-separated list of numbers, or a single | |
21876 | asterisk. If ignore_status is false and return_output is not set, and the | |
21877 | command exits with a non-zero return code, the failure is treated as temporary | |
21878 | and the delivery is deferred if the return code matches one of the numbers, or | |
21879 | if the setting is a single asterisk. Otherwise, non-zero return codes are | |
21880 | treated as permanent errors. The default setting contains the codes defined by | |
21881 | EX_TEMPFAIL and EX_CANTCREAT in sysexits.h. If Exim is compiled on a system | |
21882 | that does not define these macros, it assumes values of 75 and 73, | |
21883 | respectively. | |
21884 | ||
2813c06e | 21885 | +----------------------------------------+ |
420a0d19 | 21886 | |timeout|Use: pipe|Type: time|Default: 1h| |
2813c06e | 21887 | +----------------------------------------+ |
420a0d19 CE |
21888 | |
21889 | If the command fails to complete within this time, it is killed. This normally | |
21890 | causes the delivery to fail (but see timeout_defer). A zero time interval | |
21891 | specifies no timeout. In order to ensure that any subprocesses created by the | |
21892 | command are also killed, Exim makes the initial process a process group leader, | |
21893 | and kills the whole process group on a timeout. However, this can be defeated | |
21894 | if one of the processes starts a new process group. | |
21895 | ||
2813c06e | 21896 | +----------------------------------------------------+ |
420a0d19 | 21897 | |timeout_defer|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21898 | +----------------------------------------------------+ |
420a0d19 CE |
21899 | |
21900 | A timeout in a pipe transport, either in the command that the transport runs, | |
21901 | or in a transport filter that is associated with it, is by default treated as a | |
21902 | hard error, and the delivery fails. However, if timeout_defer is set true, both | |
21903 | kinds of timeout become temporary errors, causing the delivery to be deferred. | |
21904 | ||
2813c06e | 21905 | +------------------------------------------------+ |
420a0d19 | 21906 | |umask|Use: pipe|Type: octal integer|Default: 022| |
2813c06e | 21907 | +------------------------------------------------+ |
420a0d19 CE |
21908 | |
21909 | This specifies the umask setting for the subprocess that runs the command. | |
21910 | ||
2813c06e | 21911 | +------------------------------------------------+ |
420a0d19 | 21912 | |use_bsmtp|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21913 | +------------------------------------------------+ |
420a0d19 CE |
21914 | |
21915 | If this option is set true, the pipe transport writes messages in "batch SMTP" | |
21916 | format, with the envelope sender and recipient(s) included as SMTP commands. If | |
21917 | you want to include a leading HELO command with such messages, you can do so by | |
2813c06e | 21918 | setting the message_prefix option. See section 48.10 for details of batch SMTP. |
420a0d19 | 21919 | |
2813c06e | 21920 | +---------------------------------------------------------+ |
420a0d19 | 21921 | |use_classresources|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21922 | +---------------------------------------------------------+ |
420a0d19 CE |
21923 | |
21924 | This option is available only when Exim is running on FreeBSD, NetBSD, or BSD/ | |
21925 | OS. If it is set true, the setclassresources() function is used to set resource | |
21926 | limits when a pipe transport is run to perform a delivery. The limits for the | |
21927 | uid under which the pipe is to run are obtained from the login class database. | |
21928 | ||
2813c06e | 21929 | +-----------------------------------------------+ |
420a0d19 | 21930 | |use_crlf|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21931 | +-----------------------------------------------+ |
420a0d19 CE |
21932 | |
21933 | This option causes lines to be terminated with the two-character CRLF sequence | |
21934 | (carriage return, linefeed) instead of just a linefeed character. In the case | |
21935 | of batched SMTP, the byte sequence written to the pipe is then an exact image | |
21936 | of what would be sent down a real SMTP connection. | |
21937 | ||
21938 | The contents of the message_prefix and message_suffix options are written | |
21939 | verbatim, so must contain their own carriage return characters if these are | |
21940 | needed. When use_bsmtp is not set, the default values for both message_prefix | |
21941 | and message_suffix end with a single linefeed, so their values must be changed | |
21942 | to end with "\r\n" if use_crlf is set. | |
21943 | ||
2813c06e | 21944 | +------------------------------------------------+ |
420a0d19 | 21945 | |use_shell|Use: pipe|Type: boolean|Default: false| |
2813c06e | 21946 | +------------------------------------------------+ |
420a0d19 CE |
21947 | |
21948 | If this option is set, it causes the command to be passed to /bin/sh instead of | |
21949 | being run directly from the transport, as described in section 29.3. This is | |
21950 | less secure, but is needed in some situations where the command is expected to | |
21951 | be run under a shell and cannot easily be modified. The allow_commands and | |
21952 | restrict_to_path options, and the "$pipe_addresses" facility are incompatible | |
21953 | with use_shell. The command is expanded as a single string, and handed to /bin/ | |
21954 | sh as data for its -c option. | |
21955 | ||
21956 | ||
21957 | 29.6 Using an external local delivery agent | |
21958 | ------------------------------------------- | |
21959 | ||
21960 | The pipe transport can be used to pass all messages that require local delivery | |
21961 | to a separate local delivery agent such as procmail. When doing this, care must | |
21962 | be taken to ensure that the pipe is run under an appropriate uid and gid. In | |
21963 | some configurations one wants this to be a uid that is trusted by the delivery | |
21964 | agent to supply the correct sender of the message. It may be necessary to | |
21965 | recompile or reconfigure the delivery agent so that it trusts an appropriate | |
21966 | user. The following is an example transport and router configuration for | |
21967 | procmail: | |
21968 | ||
21969 | # transport | |
21970 | procmail_pipe: | |
21971 | driver = pipe | |
21972 | command = /usr/local/bin/procmail -d $local_part | |
21973 | return_path_add | |
21974 | delivery_date_add | |
21975 | envelope_to_add | |
21976 | check_string = "From " | |
21977 | escape_string = ">From " | |
21978 | umask = 077 | |
21979 | user = $local_part | |
21980 | group = mail | |
21981 | ||
21982 | # router | |
21983 | procmail: | |
21984 | driver = accept | |
21985 | check_local_user | |
21986 | transport = procmail_pipe | |
21987 | ||
21988 | In this example, the pipe is run as the local user, but with the group set to | |
21989 | mail. An alternative is to run the pipe as a specific user such as mail or exim | |
21990 | , but in this case you must arrange for procmail to trust that user to supply a | |
21991 | correct sender address. If you do not specify either a group or a user option, | |
21992 | the pipe command is run as the local user. The home directory is the user's | |
21993 | home directory by default. | |
21994 | ||
21995 | Note: The command that the pipe transport runs does not begin with | |
21996 | ||
21997 | IFS=" " | |
21998 | ||
21999 | as shown in some procmail documentation, because Exim does not by default use a | |
22000 | shell to run pipe commands. | |
22001 | ||
22002 | The next example shows a transport and a router for a system where local | |
22003 | deliveries are handled by the Cyrus IMAP server. | |
22004 | ||
22005 | # transport | |
22006 | local_delivery_cyrus: | |
22007 | driver = pipe | |
22008 | command = /usr/cyrus/bin/deliver \ | |
22009 | -m ${substr_1:$local_part_suffix} -- $local_part | |
22010 | user = cyrus | |
22011 | group = mail | |
22012 | return_output | |
22013 | log_output | |
22014 | message_prefix = | |
22015 | message_suffix = | |
22016 | ||
22017 | # router | |
22018 | local_user_cyrus: | |
22019 | driver = accept | |
22020 | check_local_user | |
22021 | local_part_suffix = .* | |
22022 | transport = local_delivery_cyrus | |
22023 | ||
22024 | Note the unsetting of message_prefix and message_suffix, and the use of | |
22025 | return_output to cause any text written by Cyrus to be returned to the sender. | |
22026 | ||
22027 | ||
22028 | ||
22029 | =============================================================================== | |
22030 | 30. THE SMTP TRANSPORT | |
22031 | ||
22032 | The smtp transport delivers messages over TCP/IP connections using the SMTP or | |
22033 | LMTP protocol. The list of hosts to try can either be taken from the address | |
22034 | that is being processed (having been set up by the router), or specified | |
22035 | explicitly for the transport. Timeout and retry processing (see chapter 32) is | |
22036 | applied to each IP address independently. | |
22037 | ||
22038 | ||
22039 | 30.1 Multiple messages on a single connection | |
22040 | --------------------------------------------- | |
22041 | ||
22042 | The sending of multiple messages over a single TCP/IP connection can arise in | |
22043 | two ways: | |
22044 | ||
22045 | * If a message contains more than max_rcpt (see below) addresses that are | |
22046 | routed to the same host, more than one copy of the message has to be sent | |
22047 | to that host. In this situation, multiple copies may be sent in a single | |
22048 | run of the smtp transport over a single TCP/IP connection. (What Exim | |
22049 | actually does when it has too many addresses to send in one message also | |
22050 | depends on the value of the global remote_max_parallel option. Details are | |
2813c06e | 22051 | given in section 48.1.) |
420a0d19 CE |
22052 | |
22053 | * When a message has been successfully delivered over a TCP/IP connection, | |
22054 | Exim looks in its hints database to see if there are any other messages | |
22055 | awaiting a connection to the same host. If there are, a new delivery | |
22056 | process is started for one of them, and the current TCP/IP connection is | |
22057 | passed on to it. The new process may in turn send multiple copies and | |
22058 | possibly create yet another process. | |
22059 | ||
22060 | For each copy sent over the same TCP/IP connection, a sequence counter is | |
22061 | incremented, and if it ever gets to the value of connection_max_messages, no | |
22062 | further messages are sent over that connection. | |
22063 | ||
22064 | ||
22065 | 30.2 Use of the $host and $host_address variables | |
22066 | ------------------------------------------------- | |
22067 | ||
22068 | At the start of a run of the smtp transport, the values of $host and | |
22069 | $host_address are the name and IP address of the first host on the host list | |
22070 | passed by the router. However, when the transport is about to connect to a | |
22071 | specific host, and while it is connected to that host, $host and $host_address | |
22072 | are set to the values for that host. These are the values that are in force | |
22073 | when the helo_data, hosts_try_auth, interface, serialize_hosts, and the various | |
22074 | TLS options are expanded. | |
22075 | ||
22076 | ||
22077 | 30.3 Use of $tls_cipher and $tls_peerdn | |
22078 | --------------------------------------- | |
22079 | ||
22080 | At the start of a run of the smtp transport, the values of $tls_bits, | |
22081 | $tls_cipher, $tls_peerdn and $tls_sni are the values that were set when the | |
22082 | message was received. These are the values that are used for options that are | |
22083 | expanded before any SMTP connections are made. Just before each connection is | |
22084 | made, these four variables are emptied. If TLS is subsequently started, they | |
22085 | are set to the appropriate values for the outgoing connection, and these are | |
22086 | the values that are in force when any authenticators are run and when the | |
22087 | authenticated_sender option is expanded. | |
22088 | ||
22089 | These variables are deprecated in favour of $tls_in_cipher et. al. and will be | |
22090 | removed in a future release. | |
22091 | ||
22092 | ||
22093 | 30.4 Private options for smtp | |
22094 | ----------------------------- | |
22095 | ||
22096 | The private options of the smtp transport are as follows: | |
22097 | ||
2813c06e | 22098 | +------------------------------------------------------------------+ |
420a0d19 | 22099 | |address_retry_include_sender|Use: smtp|Type: boolean|Default: true| |
2813c06e | 22100 | +------------------------------------------------------------------+ |
420a0d19 CE |
22101 | |
22102 | When an address is delayed because of a 4xx response to a RCPT command, it is | |
22103 | the combination of sender and recipient that is delayed in subsequent queue | |
22104 | runs until the retry time is reached. You can delay the recipient without | |
22105 | reference to the sender (which is what earlier versions of Exim did), by | |
22106 | setting address_retry_include_sender false. However, this can lead to problems | |
22107 | with servers that regularly issue 4xx responses to RCPT commands. | |
22108 | ||
2813c06e | 22109 | +------------------------------------------------------+ |
420a0d19 | 22110 | |allow_localhost|Use: smtp|Type: boolean|Default: false| |
2813c06e | 22111 | +------------------------------------------------------+ |
420a0d19 CE |
22112 | |
22113 | When a host specified in hosts or fallback_hosts (see below) turns out to be | |
22114 | the local host, or is listed in hosts_treat_as_local, delivery is deferred by | |
22115 | default. However, if allow_localhost is set, Exim goes on to do the delivery | |
22116 | anyway. This should be used only in special cases when the configuration | |
22117 | ensures that no looping will result (for example, a differently configured Exim | |
22118 | is listening on the port to which the message is sent). | |
22119 | ||
2813c06e | 22120 | +-----------------------------------------------------------+ |
420a0d19 | 22121 | |authenticated_sender|Use: smtp|Type: string*|Default: unset| |
2813c06e | 22122 | +-----------------------------------------------------------+ |
420a0d19 CE |
22123 | |
22124 | When Exim has authenticated as a client, or if authenticated_sender_force is | |
22125 | true, this option sets a value for the AUTH= item on outgoing MAIL commands, | |
22126 | overriding any existing authenticated sender value. If the string expansion is | |
22127 | forced to fail, the option is ignored. Other expansion failures cause delivery | |
22128 | to be deferred. If the result of expansion is an empty string, that is also | |
22129 | ignored. | |
22130 | ||
22131 | The expansion happens after the outgoing connection has been made and TLS | |
22132 | started, if required. This means that the $host, $host_address, $tls_out_cipher | |
22133 | , and $tls_out_peerdn variables are set according to the particular connection. | |
22134 | ||
22135 | If the SMTP session is not authenticated, the expansion of authenticated_sender | |
22136 | still happens (and can cause the delivery to be deferred if it fails), but no | |
22137 | AUTH= item is added to MAIL commands unless authenticated_sender_force is true. | |
22138 | ||
22139 | This option allows you to use the smtp transport in LMTP mode to deliver mail | |
22140 | to Cyrus IMAP and provide the proper local part as the "authenticated sender", | |
22141 | via a setting such as: | |
22142 | ||
22143 | authenticated_sender = $local_part | |
22144 | ||
22145 | This removes the need for IMAP subfolders to be assigned special ACLs to allow | |
22146 | direct delivery to those subfolders. | |
22147 | ||
22148 | Because of expected uses such as that just described for Cyrus (when no domain | |
22149 | is involved), there is no checking on the syntax of the provided value. | |
22150 | ||
2813c06e | 22151 | +-----------------------------------------------------------------+ |
420a0d19 | 22152 | |authenticated_sender_force|Use: smtp|Type: boolean|Default: false| |
2813c06e | 22153 | +-----------------------------------------------------------------+ |
420a0d19 CE |
22154 | |
22155 | If this option is set true, the authenticated_sender option's value is used for | |
22156 | the AUTH= item on outgoing MAIL commands, even if Exim has not authenticated as | |
22157 | a client. | |
22158 | ||
2813c06e | 22159 | +------------------------------------------------+ |
420a0d19 | 22160 | |command_timeout|Use: smtp|Type: time|Default: 5m| |
2813c06e | 22161 | +------------------------------------------------+ |
420a0d19 CE |
22162 | |
22163 | This sets a timeout for receiving a response to an SMTP command that has been | |
22164 | sent out. It is also used when waiting for the initial banner line from the | |
22165 | remote host. Its value must not be zero. | |
22166 | ||
2813c06e | 22167 | +------------------------------------------------+ |
420a0d19 | 22168 | |connect_timeout|Use: smtp|Type: time|Default: 5m| |
2813c06e | 22169 | +------------------------------------------------+ |
420a0d19 CE |
22170 | |
22171 | This sets a timeout for the connect() function, which sets up a TCP/IP call to | |
22172 | a remote host. A setting of zero allows the system timeout (typically several | |
22173 | minutes) to act. To have any effect, the value of this option must be less than | |
22174 | the system timeout. However, it has been observed that on some systems there is | |
22175 | no system timeout, which is why the default value for this option is 5 minutes, | |
22176 | a value recommended by RFC 1123. | |
22177 | ||
2813c06e | 22178 | +------------------------------------------------------------+ |
420a0d19 | 22179 | |connection_max_messages|Use: smtp|Type: integer|Default: 500| |
2813c06e | 22180 | +------------------------------------------------------------+ |
420a0d19 CE |
22181 | |
22182 | This controls the maximum number of separate message deliveries that are sent | |
22183 | over a single TCP/IP connection. If the value is zero, there is no limit. For | |
22184 | testing purposes, this value can be overridden by the -oB command line option. | |
22185 | ||
2813c06e | 22186 | +---------------------------------------------+ |
420a0d19 | 22187 | |data_timeout|Use: smtp|Type: time|Default: 5m| |
2813c06e | 22188 | +---------------------------------------------+ |
420a0d19 CE |
22189 | |
22190 | This sets a timeout for the transmission of each block in the data portion of | |
22191 | the message. As a result, the overall timeout for a message depends on the size | |
22192 | of the message. Its value must not be zero. See also final_timeout. | |
22193 | ||
2813c06e CE |
22194 | +--------------------------------------------------+ |
22195 | |dkim_domain|Use: smtp|Type: string*|Default: unset| | |
22196 | +--------------------------------------------------+ | |
22197 | ||
22198 | +----------------------------------------------------+ | |
22199 | |dkim_selector|Use: smtp|Type: string*|Default: unset| | |
22200 | +----------------------------------------------------+ | |
22201 | ||
22202 | +-------------------------------------------------------+ | |
22203 | |dkim_private_key|Use: smtp|Type: string*|Default: unset| | |
22204 | +-------------------------------------------------------+ | |
22205 | ||
22206 | +-------------------------------------------------+ | |
22207 | |dkim_canon|Use: smtp|Type: string*|Default: unset| | |
22208 | +-------------------------------------------------+ | |
22209 | ||
22210 | +--------------------------------------------------+ | |
22211 | |dkim_strict|Use: smtp|Type: string*|Default: unset| | |
22212 | +--------------------------------------------------+ | |
22213 | ||
22214 | +--------------------------------------------------------+ | |
22215 | |dkim_sign_headers|Use: smtp|Type: string*|Default: unset| | |
22216 | +--------------------------------------------------------+ | |
22217 | ||
22218 | DKIM signing options. For details see section 57.1. | |
22219 | ||
22220 | +--------------------------------------------------------+ | |
420a0d19 | 22221 | |delay_after_cutoff|Use: smtp|Type: boolean|Default: true| |
2813c06e | 22222 | +--------------------------------------------------------+ |
420a0d19 CE |
22223 | |
22224 | This option controls what happens when all remote IP addresses for a given | |
22225 | domain have been inaccessible for so long that they have passed their retry | |
22226 | cutoff times. | |
22227 | ||
22228 | In the default state, if the next retry time has not been reached for any of | |
22229 | them, the address is bounced without trying any deliveries. In other words, | |
22230 | Exim delays retrying an IP address after the final cutoff time until a new | |
22231 | retry time is reached, and can therefore bounce an address without ever trying | |
22232 | a delivery, when machines have been down for a long time. Some people are | |
22233 | unhappy at this prospect, so... | |
22234 | ||
22235 | If delay_after_cutoff is set false, Exim behaves differently. If all IP | |
22236 | addresses are past their final cutoff time, Exim tries to deliver to those IP | |
22237 | addresses that have not been tried since the message arrived. If there are | |
22238 | none, of if they all fail, the address is bounced. In other words, it does not | |
22239 | delay when a new message arrives, but immediately tries those expired IP | |
22240 | addresses that haven't been tried since the message arrived. If there is a | |
22241 | continuous stream of messages for the dead hosts, unsetting delay_after_cutoff | |
22242 | means that there will be many more attempts to deliver to them. | |
22243 | ||
2813c06e | 22244 | +--------------------------------------------------------+ |
420a0d19 | 22245 | |dns_qualify_single|Use: smtp|Type: boolean|Default: true| |
2813c06e | 22246 | +--------------------------------------------------------+ |
420a0d19 CE |
22247 | |
22248 | If the hosts or fallback_hosts option is being used, and the gethostbyname | |
22249 | option is false, the RES_DEFNAMES resolver option is set. See the | |
22250 | qualify_single option in chapter 17 for more details. | |
22251 | ||
2813c06e | 22252 | +---------------------------------------------------------+ |
420a0d19 | 22253 | |dns_search_parents|Use: smtp|Type: boolean|Default: false| |
2813c06e | 22254 | +---------------------------------------------------------+ |
420a0d19 CE |
22255 | |
22256 | If the hosts or fallback_hosts option is being used, and the gethostbyname | |
22257 | option is false, the RES_DNSRCH resolver option is set. See the search_parents | |
22258 | option in chapter 17 for more details. | |
22259 | ||
2813c06e | 22260 | +------------------------------------------------------------------+ |
420a0d19 | 22261 | |dnssec_request_domains|Use: smtp|Type: domain list*|Default: unset| |
2813c06e | 22262 | +------------------------------------------------------------------+ |
420a0d19 CE |
22263 | |
22264 | DNS lookups for domains matching dnssec_request_domains will be done with the | |
2813c06e | 22265 | dnssec request bit set. This applies to all of the SRV, MX, AAAA, A lookup |
420a0d19 CE |
22266 | sequence. |
22267 | ||
2813c06e | 22268 | +------------------------------------------------------------------+ |
420a0d19 | 22269 | |dnssec_require_domains|Use: smtp|Type: domain list*|Default: unset| |
2813c06e | 22270 | +------------------------------------------------------------------+ |
420a0d19 | 22271 | |
2813c06e | 22272 | DNS lookups for domains matching dnssec_require_domains will be done with the |
420a0d19 | 22273 | dnssec request bit set. Any returns not having the Authenticated Data bit (AD |
2813c06e CE |
22274 | bit) set will be ignored and logged as a host-lookup failure. This applies to |
22275 | all of the SRV, MX, AAAA, A lookup sequence. | |
420a0d19 | 22276 | |
2813c06e | 22277 | +-------------------------------------------+ |
420a0d19 | 22278 | |dscp|Use: smtp|Type: string*|Default: unset| |
2813c06e | 22279 | +-------------------------------------------+ |
420a0d19 CE |
22280 | |
22281 | This option causes the DSCP value associated with a socket to be set to one of | |
22282 | a number of fixed strings or to numeric value. The -bI:dscp option may be used | |
22283 | to ask Exim which names it knows of. Common values include "throughput", | |
22284 | "mincost", and on newer systems "ef", "af41", etc. Numeric values may be in the | |
22285 | range 0 to 0x3F. | |
22286 | ||
22287 | The outbound packets from Exim will be marked with this value in the header | |
22288 | (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no guarantee | |
22289 | that these values will have any effect, not be stripped by networking | |
22290 | equipment, or do much of anything without cooperation with your Network | |
22291 | Engineer and those of all network operators between the source and destination. | |
22292 | ||
2813c06e | 22293 | +---------------------------------------------------------+ |
420a0d19 | 22294 | |fallback_hosts|Use: smtp|Type: string list|Default: unset| |
2813c06e | 22295 | +---------------------------------------------------------+ |
420a0d19 CE |
22296 | |
22297 | String expansion is not applied to this option. The argument must be a | |
22298 | colon-separated list of host names or IP addresses, optionally also including | |
2813c06e | 22299 | port numbers, though the separator can be changed, as described in section 6.20 |
420a0d19 CE |
22300 | . Each individual item in the list is the same as an item in a route_list |
22301 | setting for the manualroute router, as described in section 20.5. | |
22302 | ||
22303 | Fallback hosts can also be specified on routers, which associate them with the | |
22304 | addresses they process. As for the hosts option without hosts_override, | |
22305 | fallback_hosts specified on the transport is used only if the address does not | |
22306 | have its own associated fallback host list. Unlike hosts, a setting of | |
22307 | fallback_hosts on an address is not overridden by hosts_override. However, | |
22308 | hosts_randomize does apply to fallback host lists. | |
22309 | ||
22310 | If Exim is unable to deliver to any of the hosts for a particular address, and | |
22311 | the errors are not permanent rejections, the address is put on a separate | |
22312 | transport queue with its host list replaced by the fallback hosts, unless the | |
22313 | address was routed via MX records and the current host was in the original MX | |
22314 | list. In that situation, the fallback host list is not used. | |
22315 | ||
22316 | Once normal deliveries are complete, the fallback queue is delivered by | |
22317 | re-running the same transports with the new host lists. If several failing | |
22318 | addresses have the same fallback hosts (and max_rcpt permits it), a single copy | |
22319 | of the message is sent. | |
22320 | ||
22321 | The resolution of the host names on the fallback list is controlled by the | |
22322 | gethostbyname option, as for the hosts option. Fallback hosts apply both to | |
22323 | cases when the host list comes with the address and when it is taken from hosts | |
22324 | . This option provides a "use a smart host only if delivery fails" facility. | |
22325 | ||
2813c06e | 22326 | +-----------------------------------------------+ |
420a0d19 | 22327 | |final_timeout|Use: smtp|Type: time|Default: 10m| |
2813c06e | 22328 | +-----------------------------------------------+ |
420a0d19 CE |
22329 | |
22330 | This is the timeout that applies while waiting for the response to the final | |
22331 | line containing just "." that terminates a message. Its value must not be zero. | |
22332 | ||
2813c06e | 22333 | +----------------------------------------------------+ |
420a0d19 | 22334 | |gethostbyname|Use: smtp|Type: boolean|Default: false| |
2813c06e | 22335 | +----------------------------------------------------+ |
420a0d19 CE |
22336 | |
22337 | If this option is true when the hosts and/or fallback_hosts options are being | |
22338 | used, names are looked up using gethostbyname() (or getipnodebyname() when | |
22339 | available) instead of using the DNS. Of course, that function may in fact use | |
22340 | the DNS, but it may also consult other sources of information such as /etc/ | |
22341 | hosts. | |
22342 | ||
2813c06e | 22343 | +---------------------------------------------------------+ |
420a0d19 | 22344 | |gnutls_compat_mode|Use: smtp|Type: boolean|Default: unset| |
2813c06e | 22345 | +---------------------------------------------------------+ |
420a0d19 CE |
22346 | |
22347 | This option controls whether GnuTLS is used in compatibility mode in an Exim | |
22348 | server. This reduces security slightly, but improves interworking with older | |
22349 | implementations of TLS. | |
22350 | ||
2813c06e | 22351 | +----------------------------------------------------+ |
420a0d19 | 22352 | |helo_data|Use: smtp|Type: string*|Default: see below| |
2813c06e | 22353 | +----------------------------------------------------+ |
420a0d19 CE |
22354 | |
22355 | The value of this option is expanded after a connection to a another host has | |
22356 | been set up. The result is used as the argument for the EHLO, HELO, or LHLO | |
22357 | command that starts the outgoing SMTP or LMTP session. The default value of the | |
22358 | option is: | |
22359 | ||
22360 | $primary_hostname | |
22361 | ||
22362 | During the expansion, the variables $host and $host_address are set to the | |
22363 | identity of the remote host, and the variables $sending_ip_address and | |
22364 | $sending_port are set to the local IP address and port number that are being | |
22365 | used. These variables can be used to generate different values for different | |
22366 | servers or different local IP addresses. For example, if you want the string | |
22367 | that is used for helo_data to be obtained by a DNS lookup of the outgoing | |
22368 | interface address, you could use this: | |
22369 | ||
22370 | helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\ | |
22371 | {$primary_hostname}} | |
22372 | ||
22373 | The use of helo_data applies both to sending messages and when doing callouts. | |
22374 | ||
2813c06e | 22375 | +-------------------------------------------------+ |
420a0d19 | 22376 | |hosts|Use: smtp|Type: string list*|Default: unset| |
2813c06e | 22377 | +-------------------------------------------------+ |
420a0d19 CE |
22378 | |
22379 | Hosts are associated with an address by a router such as dnslookup, which finds | |
22380 | the hosts by looking up the address domain in the DNS, or by manualroute, which | |
22381 | has lists of hosts in its configuration. However, email addresses can be passed | |
22382 | to the smtp transport by any router, and not all of them can provide an | |
22383 | associated list of hosts. | |
22384 | ||
22385 | The hosts option specifies a list of hosts to be used if the address being | |
22386 | processed does not have any hosts associated with it. The hosts specified by | |
22387 | hosts are also used, whether or not the address has its own hosts, if | |
22388 | hosts_override is set. | |
22389 | ||
22390 | The string is first expanded, before being interpreted as a colon-separated | |
22391 | list of host names or IP addresses, possibly including port numbers. The | |
22392 | separator may be changed to something other than colon, as described in section | |
2813c06e | 22393 | 6.20. Each individual item in the list is the same as an item in a route_list |
420a0d19 CE |
22394 | setting for the manualroute router, as described in section 20.5. However, note |
22395 | that the "/MX" facility of the manualroute router is not available here. | |
22396 | ||
22397 | If the expansion fails, delivery is deferred. Unless the failure was caused by | |
22398 | the inability to complete a lookup, the error is logged to the panic log as | |
22399 | well as the main log. Host names are looked up either by searching directly for | |
22400 | address records in the DNS or by calling gethostbyname() (or getipnodebyname() | |
22401 | when available), depending on the setting of the gethostbyname option. When | |
22402 | Exim is compiled with IPv6 support, if a host that is looked up in the DNS has | |
22403 | both IPv4 and IPv6 addresses, both types of address are used. | |
22404 | ||
22405 | During delivery, the hosts are tried in order, subject to their retry status, | |
22406 | unless hosts_randomize is set. | |
22407 | ||
2813c06e | 22408 | +-----------------------------------------------------------+ |
420a0d19 | 22409 | |hosts_avoid_esmtp|Use: smtp|Type: host list*|Default: unset| |
2813c06e | 22410 | +-----------------------------------------------------------+ |
420a0d19 CE |
22411 | |
22412 | This option is for use with broken hosts that announce ESMTP facilities (for | |
22413 | example, PIPELINING) and then fail to implement them properly. When a host | |
22414 | matches hosts_avoid_esmtp, Exim sends HELO rather than EHLO at the start of the | |
22415 | SMTP session. This means that it cannot use any of the ESMTP facilities such as | |
22416 | AUTH, PIPELINING, SIZE, and STARTTLS. | |
22417 | ||
2813c06e | 22418 | +----------------------------------------------------------------+ |
420a0d19 | 22419 | |hosts_avoid_pipelining|Use: smtp|Type: host list*|Default: unset| |
2813c06e | 22420 | +----------------------------------------------------------------+ |
420a0d19 CE |
22421 | |
22422 | Exim will not use the SMTP PIPELINING extension when delivering to any host | |
22423 | that matches this list, even if the server host advertises PIPELINING support. | |
22424 | ||
2813c06e | 22425 | +---------------------------------------------------------+ |
420a0d19 | 22426 | |hosts_avoid_tls|Use: smtp|Type: host list*|Default: unset| |
2813c06e | 22427 | +---------------------------------------------------------+ |
420a0d19 CE |
22428 | |
22429 | Exim will not try to start a TLS session when delivering to any host that | |
2813c06e | 22430 | matches this list. See chapter 42 for details of TLS. |
420a0d19 | 22431 | |
2813c06e CE |
22432 | +----------------------------------------------------------------+ |
22433 | |hosts_verify_avoid_tls|Use: smtp|Type: host list*|Default: unset| | |
22434 | +----------------------------------------------------------------+ | |
420a0d19 CE |
22435 | |
22436 | Exim will not try to start a TLS session for a verify callout, or when | |
2813c06e | 22437 | delivering in cutthrough mode, to any host that matches this list. |
420a0d19 | 22438 | |
2813c06e | 22439 | +------------------------------------------------+ |
420a0d19 | 22440 | |hosts_max_try|Use: smtp|Type: integer|Default: 5| |
2813c06e | 22441 | +------------------------------------------------+ |
420a0d19 CE |
22442 | |
22443 | This option limits the number of IP addresses that are tried for any one | |
22444 | delivery in cases where there are temporary delivery errors. Section 30.5 | |
22445 | describes in detail how the value of this option is used. | |
22446 | ||
2813c06e | 22447 | +-----------------------------------------------------------+ |
420a0d19 | 22448 | |hosts_max_try_hardlimit|Use: smtp|Type: integer|Default: 50| |
2813c06e | 22449 | +-----------------------------------------------------------+ |
420a0d19 CE |
22450 | |
22451 | This is an additional check on the maximum number of IP addresses that Exim | |
22452 | tries for any one delivery. Section 30.5 describes its use and why it exists. | |
22453 | ||
2813c06e | 22454 | +----------------------------------------------------------+ |
420a0d19 | 22455 | |hosts_nopass_tls|Use: smtp|Type: host list*|Default: unset| |
2813c06e | 22456 | +----------------------------------------------------------+ |
420a0d19 CE |
22457 | |
22458 | For any host that matches this list, a connection on which a TLS session has | |
22459 | been started will not be passed to a new delivery process for sending another | |
2813c06e | 22460 | message on the same connection. See section 42.11 for an explanation of when |
420a0d19 CE |
22461 | this might be needed. |
22462 | ||
2813c06e | 22463 | +-----------------------------------------------------+ |
420a0d19 | 22464 | |hosts_override|Use: smtp|Type: boolean|Default: false| |
2813c06e | 22465 | +-----------------------------------------------------+ |
420a0d19 CE |
22466 | |
22467 | If this option is set and the hosts option is also set, any hosts that are | |
22468 | attached to the address are ignored, and instead the hosts specified by the | |
22469 | hosts option are always used. This option does not apply to fallback_hosts. | |
22470 | ||
2813c06e | 22471 | +------------------------------------------------------+ |
420a0d19 | 22472 | |hosts_randomize|Use: smtp|Type: boolean|Default: false| |
2813c06e | 22473 | +------------------------------------------------------+ |
420a0d19 CE |
22474 | |
22475 | If this option is set, and either the list of hosts is taken from the hosts or | |
22476 | the fallback_hosts option, or the hosts supplied by the router were not | |
22477 | obtained from MX records (this includes fallback hosts from the router), and | |
22478 | were not randomized by the router, the order of trying the hosts is randomized | |
22479 | each time the transport runs. Randomizing the order of a host list can be used | |
22480 | to do crude load sharing. | |
22481 | ||
22482 | When hosts_randomize is true, a host list may be split into groups whose order | |
22483 | is separately randomized. This makes it possible to set up MX-like behaviour. | |
22484 | The boundaries between groups are indicated by an item that is just "+" in the | |
22485 | host list. For example: | |
22486 | ||
22487 | hosts = host1:host2:host3:+:host4:host5 | |
22488 | ||
22489 | The order of the first three hosts and the order of the last two hosts is | |
22490 | randomized for each use, but the first three always end up before the last two. | |
22491 | If hosts_randomize is not set, a "+" item in the list is ignored. | |
22492 | ||
2813c06e | 22493 | +------------------------------------------------------------+ |
420a0d19 | 22494 | |hosts_require_auth|Use: smtp|Type: host list*|Default: unset| |
2813c06e | 22495 | +------------------------------------------------------------+ |
420a0d19 CE |
22496 | |
22497 | This option provides a list of servers for which authentication must succeed | |
22498 | before Exim will try to transfer a message. If authentication fails for servers | |
22499 | which are not in this list, Exim tries to send unauthenticated. If | |
22500 | authentication fails for one of these servers, delivery is deferred. This | |
22501 | temporary error is detectable in the retry rules, so it can be turned into a | |
22502 | hard failure if required. See also hosts_try_auth, and chapter 33 for details | |
22503 | of authentication. | |
22504 | ||
2813c06e | 22505 | +--------------------------------------------------------+ |
420a0d19 | 22506 | |hosts_request_ocsp|Use: smtp|Type: host list*|Default: *| |
2813c06e | 22507 | +--------------------------------------------------------+ |
420a0d19 CE |
22508 | |
22509 | Exim will request a Certificate Status on a TLS session for any host that | |
22510 | matches this list. tls_verify_certificates should also be set for the | |
22511 | transport. | |
22512 | ||
2813c06e | 22513 | +------------------------------------------------------------+ |
420a0d19 | 22514 | |hosts_require_ocsp|Use: smtp|Type: host list*|Default: unset| |
2813c06e | 22515 | +------------------------------------------------------------+ |
420a0d19 CE |
22516 | |
22517 | Exim will request, and check for a valid Certificate Status being given, on a | |
22518 | TLS session for any host that matches this list. tls_verify_certificates should | |
22519 | also be set for the transport. | |
22520 | ||
2813c06e | 22521 | +-----------------------------------------------------------+ |
420a0d19 | 22522 | |hosts_require_tls|Use: smtp|Type: host list*|Default: unset| |
2813c06e | 22523 | +-----------------------------------------------------------+ |
420a0d19 CE |
22524 | |
22525 | Exim will insist on using a TLS session when delivering to any host that | |
2813c06e | 22526 | matches this list. See chapter 42 for details of TLS. Note: This option affects |
420a0d19 CE |
22527 | outgoing mail only. To insist on TLS for incoming messages, use an appropriate |
22528 | ACL. | |
22529 | ||
2813c06e | 22530 | +--------------------------------------------------------+ |
420a0d19 | 22531 | |hosts_try_auth|Use: smtp|Type: host list*|Default: unset| |
2813c06e | 22532 | +--------------------------------------------------------+ |
420a0d19 CE |
22533 | |
22534 | This option provides a list of servers to which, provided they announce | |
22535 | authentication support, Exim will attempt to authenticate as a client when it | |
22536 | connects. If authentication fails, Exim will try to transfer the message | |
22537 | unauthenticated. See also hosts_require_auth, and chapter 33 for details of | |
22538 | authentication. | |
22539 | ||
2813c06e CE |
22540 | +--------------------------------------------------------+ |
22541 | |hosts_try_chunking|Use: smtp|Type: host list*|Default: *| | |
22542 | +--------------------------------------------------------+ | |
22543 | ||
22544 | This option provides a list of servers to which, provided they announce | |
22545 | CHUNKING support, Exim will attempt to use BDAT commands rather than DATA. BDAT | |
22546 | will not be used in conjunction with a transport filter. | |
22547 | ||
22548 | +-------------------------------------------------------------+ | |
22549 | |hosts_try_fastopen|Use: smtp|Type: host list!!|Default: unset| | |
22550 | +-------------------------------------------------------------+ | |
22551 | ||
22552 | This option provides a list of servers to which, provided the facility is | |
22553 | supported by this system, Exim will attempt to perform a TCP Fast Open. No data | |
22554 | is sent on the SYN segment but, if the remote server also supports the | |
22555 | facility, it can send its SMTP banner immediately after the SYN,ACK segment. | |
22556 | This can save up to one round-trip time. | |
22557 | ||
22558 | The facility is only active for previously-contacted servers, as the initiator | |
22559 | must present a cookie in the SYN segment. | |
22560 | ||
22561 | On (at least some) current Linux distributions the facility must be enabled in | |
22562 | the kernel by the sysadmin before the support is usable. | |
22563 | ||
22564 | +----------------------------------------------------+ | |
22565 | |hosts_try_prdr|Use: smtp|Type: host list*|Default: *| | |
22566 | +----------------------------------------------------+ | |
420a0d19 CE |
22567 | |
22568 | This option provides a list of servers to which, provided they announce PRDR | |
2813c06e CE |
22569 | support, Exim will attempt to negotiate PRDR for multi-recipient messages. The |
22570 | option can usually be left as default. | |
420a0d19 | 22571 | |
2813c06e | 22572 | +-----------------------------------------------------+ |
420a0d19 | 22573 | |interface|Use: smtp|Type: string list*|Default: unset| |
2813c06e | 22574 | +-----------------------------------------------------+ |
420a0d19 CE |
22575 | |
22576 | This option specifies which interface to bind to when making an outgoing SMTP | |
22577 | call. The value is an IP address, not an interface name such as "eth0". Do not | |
22578 | confuse this with the interface address that was used when a message was | |
22579 | received, which is in $received_ip_address, formerly known as | |
22580 | $interface_address. The name was changed to minimize confusion with the | |
22581 | outgoing interface address. There is no variable that contains an outgoing | |
22582 | interface address because, unless it is set by this option, its value is | |
22583 | unknown. | |
22584 | ||
22585 | During the expansion of the interface option the variables $host and | |
22586 | $host_address refer to the host to which a connection is about to be made | |
22587 | during the expansion of the string. Forced expansion failure, or an empty | |
22588 | string result causes the option to be ignored. Otherwise, after expansion, the | |
22589 | string must be a list of IP addresses, colon-separated by default, but the | |
22590 | separator can be changed in the usual way. For example: | |
22591 | ||
22592 | interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061 | |
22593 | ||
22594 | The first interface of the correct type (IPv4 or IPv6) is used for the outgoing | |
22595 | connection. If none of them are the correct type, the option is ignored. If | |
22596 | interface is not set, or is ignored, the system's IP functions choose which | |
22597 | interface to use if the host has more than one. | |
22598 | ||
2813c06e | 22599 | +-----------------------------------------------+ |
420a0d19 | 22600 | |keepalive|Use: smtp|Type: boolean|Default: true| |
2813c06e | 22601 | +-----------------------------------------------+ |
420a0d19 CE |
22602 | |
22603 | This option controls the setting of SO_KEEPALIVE on outgoing TCP/IP socket | |
22604 | connections. When set, it causes the kernel to probe idle connections | |
22605 | periodically, by sending packets with "old" sequence numbers. The other end of | |
22606 | the connection should send a acknowledgment if the connection is still okay or | |
22607 | a reset if the connection has been aborted. The reason for doing this is that | |
22608 | it has the beneficial effect of freeing up certain types of connection that can | |
22609 | get stuck when the remote host is disconnected without tidying up the TCP/IP | |
22610 | call properly. The keepalive mechanism takes several hours to detect | |
22611 | unreachable hosts. | |
22612 | ||
2813c06e | 22613 | +--------------------------------------------------------+ |
420a0d19 | 22614 | |lmtp_ignore_quota|Use: smtp|Type: boolean|Default: false| |
2813c06e | 22615 | +--------------------------------------------------------+ |
420a0d19 CE |
22616 | |
22617 | If this option is set true when the protocol option is set to "lmtp", the | |
22618 | string "IGNOREQUOTA" is added to RCPT commands, provided that the LMTP server | |
22619 | has advertised support for IGNOREQUOTA in its response to the LHLO command. | |
22620 | ||
2813c06e | 22621 | +---------------------------------------------+ |
420a0d19 | 22622 | |max_rcpt|Use: smtp|Type: integer|Default: 100| |
2813c06e | 22623 | +---------------------------------------------+ |
420a0d19 CE |
22624 | |
22625 | This option limits the number of RCPT commands that are sent in a single SMTP | |
22626 | message transaction. Each set of addresses is treated independently, and so can | |
22627 | cause parallel connections to the same host if remote_max_parallel permits | |
22628 | this. | |
22629 | ||
2813c06e CE |
22630 | +---------------------------------------------------+ |
22631 | |multi_domain|Use: smtp|Type: boolean*|Default: true| | |
22632 | +---------------------------------------------------+ | |
420a0d19 CE |
22633 | |
22634 | When this option is set, the smtp transport can handle a number of addresses | |
22635 | containing a mixture of different domains provided they all resolve to the same | |
22636 | list of hosts. Turning the option off restricts the transport to handling only | |
22637 | one domain at a time. This is useful if you want to use $domain in an expansion | |
22638 | for the transport, because it is set only when there is a single domain | |
22639 | involved in a remote delivery. | |
22640 | ||
2813c06e CE |
22641 | It is expanded per-address and can depend on any of $address_data, $domain_data |
22642 | , $local_part_data, $host, $host_address and $host_port. | |
22643 | ||
22644 | +-----------------------------------------------+ | |
420a0d19 | 22645 | |port|Use: smtp|Type: string*|Default: see below| |
2813c06e | 22646 | +-----------------------------------------------+ |
420a0d19 CE |
22647 | |
22648 | This option specifies the TCP/IP port on the server to which Exim connects. | |
22649 | Note: Do not confuse this with the port that was used when a message was | |
22650 | received, which is in $received_port, formerly known as $interface_port. The | |
22651 | name was changed to minimize confusion with the outgoing port. There is no | |
22652 | variable that contains an outgoing port. | |
22653 | ||
22654 | If the value of this option begins with a digit it is taken as a port number; | |
22655 | otherwise it is looked up using getservbyname(). The default value is normally | |
22656 | "smtp", but if protocol is set to "lmtp", the default is "lmtp". If the | |
22657 | expansion fails, or if a port number cannot be found, delivery is deferred. | |
22658 | ||
2813c06e | 22659 | +---------------------------------------------+ |
420a0d19 | 22660 | |protocol|Use: smtp|Type: string|Default: smtp| |
2813c06e | 22661 | +---------------------------------------------+ |
420a0d19 CE |
22662 | |
22663 | If this option is set to "lmtp" instead of "smtp", the default value for the | |
22664 | port option changes to "lmtp", and the transport operates the LMTP protocol | |
22665 | (RFC 2033) instead of SMTP. This protocol is sometimes used for local | |
22666 | deliveries into closed message stores. Exim also has support for running LMTP | |
22667 | over a pipe to a local process - see chapter 28. | |
22668 | ||
2813c06e | 22669 | If this option is set to "smtps", the default value for the port option changes |
420a0d19 CE |
22670 | to "smtps", and the transport initiates TLS immediately after connecting, as an |
22671 | outbound SSL-on-connect, instead of using STARTTLS to upgrade. The Internet | |
22672 | standards bodies strongly discourage use of this mode. | |
22673 | ||
2813c06e CE |
22674 | +---------------------------------------------------------------+ |
22675 | |retry_include_ip_address|Use: smtp|Type: boolean*|Default: true| | |
22676 | +---------------------------------------------------------------+ | |
420a0d19 CE |
22677 | |
22678 | Exim normally includes both the host name and the IP address in the key it | |
22679 | constructs for indexing retry data after a temporary delivery failure. This | |
22680 | means that when one of several IP addresses for a host is failing, it gets | |
22681 | tried periodically (controlled by the retry rules), but use of the other IP | |
22682 | addresses is not affected. | |
22683 | ||
22684 | However, in some dialup environments hosts are assigned a different IP address | |
22685 | each time they connect. In this situation the use of the IP address as part of | |
22686 | the retry key leads to undesirable behaviour. Setting this option false causes | |
2813c06e CE |
22687 | Exim to use only the host name. Since it is expanded it can be made to depend |
22688 | on the host or domain. | |
420a0d19 | 22689 | |
2813c06e | 22690 | +---------------------------------------------------------+ |
420a0d19 | 22691 | |serialize_hosts|Use: smtp|Type: host list*|Default: unset| |
2813c06e | 22692 | +---------------------------------------------------------+ |
420a0d19 CE |
22693 | |
22694 | Because Exim operates in a distributed manner, if several messages for the same | |
22695 | host arrive at around the same time, more than one simultaneous connection to | |
22696 | the remote host can occur. This is not usually a problem except when there is a | |
22697 | slow link between the hosts. In that situation it may be helpful to restrict | |
22698 | Exim to one connection at a time. This can be done by setting serialize_hosts | |
22699 | to match the relevant hosts. | |
22700 | ||
22701 | Exim implements serialization by means of a hints database in which a record is | |
22702 | written whenever a process connects to one of the restricted hosts. The record | |
22703 | is deleted when the connection is completed. Obviously there is scope for | |
22704 | records to get left lying around if there is a system or program crash. To | |
22705 | guard against this, Exim ignores any records that are more than six hours old. | |
22706 | ||
22707 | If you set up this kind of serialization, you should also arrange to delete the | |
22708 | relevant hints database whenever your system reboots. The names of the files | |
22709 | start with misc and they are kept in the spool/db directory. There may be one | |
22710 | or two files, depending on the type of DBM in use. The same files are used for | |
22711 | ETRN serialization. | |
22712 | ||
2813c06e CE |
22713 | See also the max_parallel generic transport option. |
22714 | ||
22715 | +---------------------------------------------------+ | |
420a0d19 | 22716 | |size_addition|Use: smtp|Type: integer|Default: 1024| |
2813c06e | 22717 | +---------------------------------------------------+ |
420a0d19 CE |
22718 | |
22719 | If a remote SMTP server indicates that it supports the SIZE option of the MAIL | |
22720 | command, Exim uses this to pass over the message size at the start of an SMTP | |
22721 | transaction. It adds the value of size_addition to the value it sends, to allow | |
22722 | for headers and other text that may be added during delivery by configuration | |
22723 | options or in a transport filter. It may be necessary to increase this if a lot | |
22724 | of text is added to messages. | |
22725 | ||
22726 | Alternatively, if the value of size_addition is set negative, it disables the | |
22727 | use of the SIZE option altogether. | |
22728 | ||
2813c06e CE |
22729 | +--------------------------------------------------+ |
22730 | |socks_proxy|Use: smtp|Type: string*|Default: unset| | |
22731 | +--------------------------------------------------+ | |
22732 | ||
22733 | This option enables use of SOCKS proxies for connections made by the transport. | |
22734 | For details see section 58.2. | |
22735 | ||
22736 | +------------------------------------------------------+ | |
420a0d19 | 22737 | |tls_certificate|Use: smtp|Type: string*|Default: unset| |
2813c06e | 22738 | +------------------------------------------------------+ |
420a0d19 CE |
22739 | |
22740 | The value of this option must be the absolute path to a file which contains the | |
22741 | client's certificate, for possible use when sending a message over an encrypted | |
22742 | connection. The values of $host and $host_address are set to the name and | |
2813c06e | 22743 | address of the server during the expansion. See chapter 42 for details of TLS. |
420a0d19 CE |
22744 | |
22745 | Note: This option must be set if you want Exim to be able to use a TLS | |
22746 | certificate when sending messages as a client. The global option of the same | |
22747 | name specifies the certificate for Exim as a server; it is not automatically | |
22748 | assumed that the same certificate should be used when Exim is operating as a | |
22749 | client. | |
22750 | ||
2813c06e | 22751 | +----------------------------------------------+ |
420a0d19 | 22752 | |tls_crl|Use: smtp|Type: string*|Default: unset| |
2813c06e | 22753 | +----------------------------------------------+ |
420a0d19 CE |
22754 | |
22755 | This option specifies a certificate revocation list. The expanded value must be | |
22756 | the name of a file that contains a CRL in PEM format. | |
22757 | ||
2813c06e | 22758 | +-----------------------------------------------------+ |
420a0d19 | 22759 | |tls_dh_min_bits|Use: smtp|Type: integer|Default: 1024| |
2813c06e | 22760 | +-----------------------------------------------------+ |
420a0d19 CE |
22761 | |
22762 | When establishing a TLS session, if a ciphersuite which uses Diffie-Hellman key | |
22763 | agreement is negotiated, the server will provide a large prime number for use. | |
22764 | This option establishes the minimum acceptable size of that number. If the | |
22765 | parameter offered by the server is too small, then the TLS handshake will fail. | |
22766 | ||
22767 | Only supported when using GnuTLS. | |
22768 | ||
2813c06e | 22769 | +-----------------------------------------------------+ |
420a0d19 | 22770 | |tls_privatekey|Use: smtp|Type: string*|Default: unset| |
2813c06e | 22771 | +-----------------------------------------------------+ |
420a0d19 CE |
22772 | |
22773 | The value of this option must be the absolute path to a file which contains the | |
22774 | client's private key. This is used when sending a message over an encrypted | |
22775 | connection using a client certificate. The values of $host and $host_address | |
22776 | are set to the name and address of the server during the expansion. If this | |
22777 | option is unset, or the expansion is forced to fail, or the result is an empty | |
22778 | string, the private key is assumed to be in the same file as the certificate. | |
2813c06e | 22779 | See chapter 42 for details of TLS. |
420a0d19 | 22780 | |
2813c06e | 22781 | +----------------------------------------------------------+ |
420a0d19 | 22782 | |tls_require_ciphers|Use: smtp|Type: string*|Default: unset| |
2813c06e | 22783 | +----------------------------------------------------------+ |
420a0d19 CE |
22784 | |
22785 | The value of this option must be a list of permitted cipher suites, for use | |
22786 | when setting up an outgoing encrypted connection. (There is a global option of | |
22787 | the same name for controlling incoming connections.) The values of $host and | |
22788 | $host_address are set to the name and address of the server during the | |
2813c06e CE |
22789 | expansion. See chapter 42 for details of TLS; note that this option is used in |
22790 | different ways by OpenSSL and GnuTLS (see sections 42.4 and 42.5). For GnuTLS, | |
420a0d19 CE |
22791 | the order of the ciphers is a preference order. |
22792 | ||
2813c06e | 22793 | +----------------------------------------------+ |
420a0d19 | 22794 | |tls_sni|Use: smtp|Type: string*|Default: unset| |
2813c06e | 22795 | +----------------------------------------------+ |
420a0d19 CE |
22796 | |
22797 | If this option is set then it sets the $tls_out_sni variable and causes any TLS | |
22798 | session to pass this value as the Server Name Indication extension to the | |
22799 | remote side, which can be used by the remote side to select an appropriate | |
22800 | certificate and private key for the session. | |
22801 | ||
2813c06e | 22802 | See 42.10 for more information. |
420a0d19 CE |
22803 | |
22804 | Note that for OpenSSL, this feature requires a build of OpenSSL that supports | |
22805 | TLS extensions. | |
22806 | ||
2813c06e | 22807 | +-----------------------------------------------------------+ |
420a0d19 | 22808 | |tls_tempfail_tryclear|Use: smtp|Type: boolean|Default: true| |
2813c06e | 22809 | +-----------------------------------------------------------+ |
420a0d19 CE |
22810 | |
22811 | When the server host is not in hosts_require_tls, and there is a problem in | |
22812 | setting up a TLS session, this option determines whether or not Exim should try | |
22813 | to deliver the message unencrypted. If it is set false, delivery to the current | |
22814 | host is deferred; if there are other hosts, they are tried. If this option is | |
22815 | set true, Exim attempts to deliver unencrypted after a 4xx response to | |
22816 | STARTTLS. Also, if STARTTLS is accepted, but the subsequent TLS negotiation | |
22817 | fails, Exim closes the current connection (because it is in an unknown state), | |
22818 | opens a new one to the same host, and then tries the delivery in clear. | |
22819 | ||
2813c06e CE |
22820 | +----------------------------------------------------------+ |
22821 | |tls_try_verify_hosts|Use: smtp|Type: host list*|Default: *| | |
22822 | +----------------------------------------------------------+ | |
420a0d19 CE |
22823 | |
22824 | This option gives a list of hosts for which, on encrypted connections, | |
22825 | certificate verification will be tried but need not succeed. The | |
22826 | tls_verify_certificates option must also be set. Note that unless the host is | |
22827 | in this list TLS connections will be denied to hosts using self-signed | |
2813c06e | 22828 | certificates when tls_verify_certificates is matched. The |
420a0d19 CE |
22829 | $tls_out_certificate_verified variable is set when certificate verification |
22830 | succeeds. | |
22831 | ||
2813c06e CE |
22832 | +---------------------------------------------------------------+ |
22833 | |tls_verify_cert_hostnames|Use: smtp|Type: host list*|Default: *| | |
22834 | +---------------------------------------------------------------+ | |
22835 | ||
22836 | This option give a list of hosts for which, while verifying the server | |
22837 | certificate, checks will be included on the host name (note that this will | |
22838 | generally be the result of a DNS MX lookup) versus Subject and | |
22839 | Subject-Alternate-Name fields. Wildcard names are permitted limited to being | |
22840 | the initial component of a 3-or-more component FQDN. | |
22841 | ||
22842 | There is no equivalent checking on client certificates. | |
22843 | ||
22844 | +---------------------------------------------------------------+ | |
22845 | |tls_verify_certificates|Use: smtp|Type: string*|Default: system| | |
22846 | +---------------------------------------------------------------+ | |
420a0d19 | 22847 | |
2813c06e CE |
22848 | The value of this option must be either the word "system" or the absolute path |
22849 | to a file or directory containing permitted certificates for servers, for use | |
22850 | when setting up an encrypted connection. | |
420a0d19 | 22851 | |
2813c06e CE |
22852 | The "system" value for the option will use a location compiled into the SSL |
22853 | library. This is not available for GnuTLS versions preceding 3.0.20; a value of | |
22854 | "system" is taken as empty and an explicit location must be specified. | |
420a0d19 | 22855 | |
2813c06e CE |
22856 | The use of a directory for the option value is not available for GnuTLS |
22857 | versions preceding 3.3.6 and a single file must be used. | |
420a0d19 | 22858 | |
2813c06e CE |
22859 | With OpenSSL the certificates specified explicitly either by file or directory |
22860 | are added to those given by the system default location. | |
22861 | ||
22862 | The values of $host and $host_address are set to the name and address of the | |
22863 | server during the expansion of this option. See chapter 42 for details of TLS. | |
22864 | ||
22865 | For back-compatibility, if neither tls_verify_hosts nor tls_try_verify_hosts | |
22866 | are set (a single-colon empty list counts as being set) and certificate | |
22867 | verification fails the TLS connection is closed. | |
22868 | ||
22869 | +----------------------------------------------------------+ | |
22870 | |tls_verify_hosts|Use: smtp|Type: host list*|Default: unset| | |
22871 | +----------------------------------------------------------+ | |
22872 | ||
22873 | This option gives a list of hosts for which, on encrypted connections, | |
420a0d19 CE |
22874 | certificate verification must succeed. The tls_verify_certificates option must |
22875 | also be set. If both this option and tls_try_verify_hosts are unset operation | |
22876 | is as if this option selected all hosts. | |
22877 | ||
22878 | ||
22879 | 30.5 How the limits for the number of hosts to try are used | |
22880 | ----------------------------------------------------------- | |
22881 | ||
22882 | There are two options that are concerned with the number of hosts that are | |
22883 | tried when an SMTP delivery takes place. They are hosts_max_try and | |
22884 | hosts_max_try_hardlimit. | |
22885 | ||
22886 | The hosts_max_try option limits the number of hosts that are tried for a single | |
22887 | delivery. However, despite the term "host" in its name, the option actually | |
22888 | applies to each IP address independently. In other words, a multihomed host is | |
22889 | treated as several independent hosts, just as it is for retrying. | |
22890 | ||
22891 | Many of the larger ISPs have multiple MX records which often point to | |
22892 | multihomed hosts. As a result, a list of a dozen or more IP addresses may be | |
22893 | created as a result of routing one of these domains. | |
22894 | ||
22895 | Trying every single IP address on such a long list does not seem sensible; if | |
22896 | several at the top of the list fail, it is reasonable to assume there is some | |
22897 | problem that is likely to affect all of them. Roughly speaking, the value of | |
22898 | hosts_max_try is the maximum number that are tried before deferring the | |
22899 | delivery. However, the logic cannot be quite that simple. | |
22900 | ||
22901 | Firstly, IP addresses that are skipped because their retry times have not | |
22902 | arrived do not count, and in addition, addresses that are past their retry | |
22903 | limits are also not counted, even when they are tried. This means that when | |
22904 | some IP addresses are past their retry limits, more than the value of | |
22905 | hosts_max_retry may be tried. The reason for this behaviour is to ensure that | |
22906 | all IP addresses are considered before timing out an email address (but see | |
22907 | below for an exception). | |
22908 | ||
22909 | Secondly, when the hosts_max_try limit is reached, Exim looks down the host | |
22910 | list to see if there is a subsequent host with a different (higher valued) MX. | |
22911 | If there is, that host is considered next, and the current IP address is used | |
22912 | but not counted. This behaviour helps in the case of a domain with a retry rule | |
22913 | that hardly ever delays any hosts, as is now explained: | |
22914 | ||
22915 | Consider the case of a long list of hosts with one MX value, and a few with a | |
22916 | higher MX value. If hosts_max_try is small (the default is 5) only a few hosts | |
22917 | at the top of the list are tried at first. With the default retry rule, which | |
22918 | specifies increasing retry times, the higher MX hosts are eventually tried when | |
22919 | those at the top of the list are skipped because they have not reached their | |
22920 | retry times. | |
22921 | ||
22922 | However, it is common practice to put a fixed short retry time on domains for | |
22923 | large ISPs, on the grounds that their servers are rarely down for very long. | |
22924 | Unfortunately, these are exactly the domains that tend to resolve to long lists | |
22925 | of hosts. The short retry time means that the lowest MX hosts are tried every | |
22926 | time. The attempts may be in a different order because of random sorting, but | |
22927 | without the special MX check, the higher MX hosts would never be tried until | |
22928 | all the lower MX hosts had timed out (which might be several days), because | |
22929 | there are always some lower MX hosts that have reached their retry times. With | |
22930 | the special check, Exim considers at least one IP address from each MX value at | |
22931 | every delivery attempt, even if the hosts_max_try limit has already been | |
22932 | reached. | |
22933 | ||
22934 | The above logic means that hosts_max_try is not a hard limit, and in | |
22935 | particular, Exim normally eventually tries all the IP addresses before timing | |
22936 | out an email address. When hosts_max_try was implemented, this seemed a | |
22937 | reasonable thing to do. Recently, however, some lunatic DNS configurations have | |
22938 | been set up with hundreds of IP addresses for some domains. It can take a very | |
22939 | long time indeed for an address to time out in these cases. | |
22940 | ||
22941 | The hosts_max_try_hardlimit option was added to help with this problem. Exim | |
22942 | never tries more than this number of IP addresses; if it hits this limit and | |
22943 | they are all timed out, the email address is bounced, even though not all | |
22944 | possible IP addresses have been tried. | |
22945 | ||
22946 | ||
22947 | ||
22948 | =============================================================================== | |
22949 | 31. ADDRESS REWRITING | |
22950 | ||
22951 | There are some circumstances in which Exim automatically rewrites domains in | |
22952 | addresses. The two most common are when an address is given without a domain | |
22953 | (referred to as an "unqualified address") or when an address contains an | |
22954 | abbreviated domain that is expanded by DNS lookup. | |
22955 | ||
22956 | Unqualified envelope addresses are accepted only for locally submitted | |
22957 | messages, or for messages that are received from hosts matching | |
22958 | sender_unqualified_hosts or recipient_unqualified_hosts, as appropriate. | |
22959 | Unqualified addresses in header lines are qualified if they are in locally | |
22960 | submitted messages, or messages from hosts that are permitted to send | |
22961 | unqualified envelope addresses. Otherwise, unqualified addresses in header | |
22962 | lines are neither qualified nor rewritten. | |
22963 | ||
22964 | One situation in which Exim does not automatically rewrite a domain is when it | |
22965 | is the name of a CNAME record in the DNS. The older RFCs suggest that such a | |
22966 | domain should be rewritten using the "canonical" name, and some MTAs do this. | |
22967 | The new RFCs do not contain this suggestion. | |
22968 | ||
22969 | ||
22970 | 31.1 Explicitly configured address rewriting | |
22971 | -------------------------------------------- | |
22972 | ||
22973 | This chapter describes the rewriting rules that can be used in the main rewrite | |
22974 | section of the configuration file, and also in the generic headers_rewrite | |
22975 | option that can be set on any transport. | |
22976 | ||
22977 | Some people believe that configured address rewriting is a Mortal Sin. Others | |
22978 | believe that life is not possible without it. Exim provides the facility; you | |
22979 | do not have to use it. | |
22980 | ||
22981 | The main rewriting rules that appear in the "rewrite" section of the | |
22982 | configuration file are applied to addresses in incoming messages, both envelope | |
22983 | addresses and addresses in header lines. Each rule specifies the types of | |
22984 | address to which it applies. | |
22985 | ||
22986 | Whether or not addresses in header lines are rewritten depends on the origin of | |
22987 | the headers and the type of rewriting. Global rewriting, that is, rewriting | |
22988 | rules from the rewrite section of the configuration file, is applied only to | |
22989 | those headers that were received with the message. Header lines that are added | |
22990 | by ACLs or by a system filter or by individual routers or transports (which are | |
22991 | specific to individual recipient addresses) are not rewritten by the global | |
22992 | rules. | |
22993 | ||
22994 | Rewriting at transport time, by means of the headers_rewrite option, applies | |
22995 | all headers except those added by routers and transports. That is, as well as | |
22996 | the headers that were received with the message, it also applies to headers | |
22997 | that were added by an ACL or a system filter. | |
22998 | ||
22999 | In general, rewriting addresses from your own system or domain has some | |
23000 | legitimacy. Rewriting other addresses should be done only with great care and | |
23001 | in special circumstances. The author of Exim believes that rewriting should be | |
23002 | used sparingly, and mainly for "regularizing" addresses in your own domains. | |
23003 | Although it can sometimes be used as a routing tool, this is very strongly | |
23004 | discouraged. | |
23005 | ||
23006 | There are two commonly encountered circumstances where rewriting is used, as | |
23007 | illustrated by these examples: | |
23008 | ||
23009 | * The company whose domain is hitch.fict.example has a number of hosts that | |
23010 | exchange mail with each other behind a firewall, but there is only a single | |
23011 | gateway to the outer world. The gateway rewrites *.hitch.fict.example as | |
23012 | hitch.fict.example when sending mail off-site. | |
23013 | ||
23014 | * A host rewrites the local parts of its own users so that, for example, | |
23015 | fp42@hitch.fict.example becomes Ford.Prefect@hitch.fict.example. | |
23016 | ||
23017 | ||
23018 | 31.2 When does rewriting happen? | |
23019 | -------------------------------- | |
23020 | ||
23021 | Configured address rewriting can take place at several different stages of a | |
23022 | message's processing. | |
23023 | ||
23024 | At the start of an ACL for MAIL, the sender address may have been rewritten by | |
23025 | a special SMTP-time rewrite rule (see section 31.9), but no ordinary rewrite | |
23026 | rules have yet been applied. If, however, the sender address is verified in the | |
23027 | ACL, it is rewritten before verification, and remains rewritten thereafter. The | |
23028 | subsequent value of $sender_address is the rewritten address. This also applies | |
23029 | if sender verification happens in a RCPT ACL. Otherwise, when the sender | |
23030 | address is not verified, it is rewritten as soon as a message's header lines | |
23031 | have been received. | |
23032 | ||
23033 | Similarly, at the start of an ACL for RCPT, the current recipient's address may | |
23034 | have been rewritten by a special SMTP-time rewrite rule, but no ordinary | |
23035 | rewrite rules have yet been applied to it. However, the behaviour is different | |
23036 | from the sender address when a recipient is verified. The address is rewritten | |
23037 | for the verification, but the rewriting is not remembered at this stage. The | |
23038 | value of $local_part and $domain after verification are always the same as they | |
23039 | were before (that is, they contain the unrewritten - except for SMTP-time | |
23040 | rewriting - address). | |
23041 | ||
23042 | As soon as a message's header lines have been received, all the envelope | |
23043 | recipient addresses are permanently rewritten, and rewriting is also applied to | |
23044 | the addresses in the header lines (if configured). This happens before adding | |
23045 | any header lines that were specified in MAIL or RCPT ACLs, and before the DATA | |
23046 | ACL and local_scan() functions are run. | |
23047 | ||
23048 | When an address is being routed, either for delivery or for verification, | |
23049 | rewriting is applied immediately to child addresses that are generated by | |
23050 | redirection, unless no_rewrite is set on the router. | |
23051 | ||
23052 | At transport time, additional rewriting of addresses in header lines can be | |
23053 | specified by setting the generic headers_rewrite option on a transport. This | |
23054 | option contains rules that are identical in form to those in the rewrite | |
23055 | section of the configuration file. They are applied to the original message | |
23056 | header lines and any that were added by ACLs or a system filter. They are not | |
23057 | applied to header lines that are added by routers or the transport. | |
23058 | ||
23059 | The outgoing envelope sender can be rewritten by means of the return_path | |
23060 | transport option. However, it is not possible to rewrite envelope recipients at | |
23061 | transport time. | |
23062 | ||
23063 | ||
23064 | 31.3 Testing the rewriting rules that apply on input | |
23065 | ---------------------------------------------------- | |
23066 | ||
23067 | Exim's input rewriting configuration appears in a part of the run time | |
23068 | configuration file headed by "begin rewrite". It can be tested by the -brw | |
23069 | command line option. This takes an address (which can be a full RFC 2822 | |
23070 | address) as its argument. The output is a list of how the address would be | |
23071 | transformed by the rewriting rules for each of the different places it might | |
23072 | appear in an incoming message, that is, for each different header and for the | |
23073 | envelope sender and recipient fields. For example, | |
23074 | ||
23075 | exim -brw ph10@exim.workshop.example | |
23076 | ||
23077 | might produce the output | |
23078 | ||
23079 | sender: Philip.Hazel@exim.workshop.example | |
23080 | from: Philip.Hazel@exim.workshop.example | |
23081 | to: ph10@exim.workshop.example | |
23082 | cc: ph10@exim.workshop.example | |
23083 | bcc: ph10@exim.workshop.example | |
23084 | reply-to: Philip.Hazel@exim.workshop.example | |
23085 | env-from: Philip.Hazel@exim.workshop.example | |
23086 | env-to: ph10@exim.workshop.example | |
23087 | ||
23088 | which shows that rewriting has been set up for that address when used in any of | |
23089 | the source fields, but not when it appears as a recipient address. At the | |
23090 | present time, there is no equivalent way of testing rewriting rules that are | |
23091 | set for a particular transport. | |
23092 | ||
23093 | ||
23094 | 31.4 Rewriting rules | |
23095 | -------------------- | |
23096 | ||
23097 | The rewrite section of the configuration file consists of lines of rewriting | |
23098 | rules in the form | |
23099 | ||
23100 | <source pattern> <replacement> <flags> | |
23101 | ||
23102 | Rewriting rules that are specified for the headers_rewrite generic transport | |
23103 | option are given as a colon-separated list. Each item in the list takes the | |
23104 | same form as a line in the main rewriting configuration (except that any colons | |
23105 | must be doubled, of course). | |
23106 | ||
23107 | The formats of source patterns and replacement strings are described below. | |
23108 | Each is terminated by white space, unless enclosed in double quotes, in which | |
23109 | case normal quoting conventions apply inside the quotes. The flags are single | |
23110 | characters which may appear in any order. Spaces and tabs between them are | |
23111 | ignored. | |
23112 | ||
23113 | For each address that could potentially be rewritten, the rules are scanned in | |
23114 | order, and replacements for the address from earlier rules can themselves be | |
23115 | replaced by later rules (but see the "q" and "R" flags). | |
23116 | ||
23117 | The order in which addresses are rewritten is undefined, may change between | |
23118 | releases, and must not be relied on, with one exception: when a message is | |
23119 | received, the envelope sender is always rewritten first, before any header | |
23120 | lines are rewritten. For example, the replacement string for a rewrite of an | |
23121 | address in To: must not assume that the message's address in From: has (or has | |
23122 | not) already been rewritten. However, a rewrite of From: may assume that the | |
23123 | envelope sender has already been rewritten. | |
23124 | ||
23125 | The variables $local_part and $domain can be used in the replacement string to | |
23126 | refer to the address that is being rewritten. Note that lookup-driven rewriting | |
23127 | can be done by a rule of the form | |
23128 | ||
23129 | *@* ${lookup ... | |
23130 | ||
23131 | where the lookup key uses $1 and $2 or $local_part and $domain to refer to the | |
23132 | address that is being rewritten. | |
23133 | ||
23134 | ||
23135 | 31.5 Rewriting patterns | |
23136 | ----------------------- | |
23137 | ||
23138 | The source pattern in a rewriting rule is any item which may appear in an | |
23139 | address list (see section 10.19). It is in fact processed as a single-item | |
23140 | address list, which means that it is expanded before being tested against the | |
23141 | address. As always, if you use a regular expression as a pattern, you must take | |
23142 | care to escape dollar and backslash characters, or use the "\N" facility to | |
23143 | suppress string expansion within the regular expression. | |
23144 | ||
23145 | Domains in patterns should be given in lower case. Local parts in patterns are | |
23146 | case-sensitive. If you want to do case-insensitive matching of local parts, you | |
23147 | can use a regular expression that starts with "^(?i)". | |
23148 | ||
23149 | After matching, the numerical variables $1, $2, etc. may be set, depending on | |
23150 | the type of match which occurred. These can be used in the replacement string | |
23151 | to insert portions of the incoming address. $0 always refers to the complete | |
23152 | incoming address. When a regular expression is used, the numerical variables | |
23153 | are set from its capturing subexpressions. For other types of pattern they are | |
23154 | set as follows: | |
23155 | ||
23156 | * If a local part or domain starts with an asterisk, the numerical variables | |
23157 | refer to the character strings matched by asterisks, with $1 associated | |
23158 | with the first asterisk, and $2 with the second, if present. For example, | |
23159 | if the pattern | |
23160 | ||
23161 | *queen@*.fict.example | |
23162 | ||
23163 | is matched against the address hearts-queen@wonderland.fict.example then | |
23164 | ||
23165 | $0 = hearts-queen@wonderland.fict.example | |
23166 | $1 = hearts- | |
23167 | $2 = wonderland | |
23168 | ||
23169 | Note that if the local part does not start with an asterisk, but the domain | |
23170 | does, it is $1 that contains the wild part of the domain. | |
23171 | ||
23172 | * If the domain part of the pattern is a partial lookup, the wild and fixed | |
23173 | parts of the domain are placed in the next available numerical variables. | |
23174 | Suppose, for example, that the address foo@bar.baz.example is processed by | |
23175 | a rewriting rule of the form | |
23176 | ||
23177 | *@partial-dbm;/some/dbm/file <replacement string> | |
23178 | ||
23179 | and the key in the file that matches the domain is "*.baz.example". Then | |
23180 | ||
23181 | $1 = foo | |
23182 | $2 = bar | |
23183 | $3 = baz.example | |
23184 | ||
23185 | If the address foo@baz.example is looked up, this matches the same wildcard | |
23186 | file entry, and in this case $2 is set to the empty string, but $3 is still | |
23187 | set to baz.example. If a non-wild key is matched in a partial lookup, $2 is | |
23188 | again set to the empty string and $3 is set to the whole domain. For | |
23189 | non-partial domain lookups, no numerical variables are set. | |
23190 | ||
23191 | ||
23192 | 31.6 Rewriting replacements | |
23193 | --------------------------- | |
23194 | ||
23195 | If the replacement string for a rule is a single asterisk, addresses that match | |
23196 | the pattern and the flags are not rewritten, and no subsequent rewriting rules | |
23197 | are scanned. For example, | |
23198 | ||
23199 | hatta@lookingglass.fict.example * f | |
23200 | ||
23201 | specifies that hatta@lookingglass.fict.example is never to be rewritten in | |
23202 | From: headers. | |
23203 | ||
23204 | If the replacement string is not a single asterisk, it is expanded, and must | |
23205 | yield a fully qualified address. Within the expansion, the variables | |
23206 | $local_part and $domain refer to the address that is being rewritten. Any | |
23207 | letters they contain retain their original case - they are not lower cased. The | |
23208 | numerical variables are set up according to the type of pattern that matched | |
23209 | the address, as described above. If the expansion is forced to fail by the | |
23210 | presence of "fail" in a conditional or lookup item, rewriting by the current | |
23211 | rule is abandoned, but subsequent rules may take effect. Any other expansion | |
23212 | failure causes the entire rewriting operation to be abandoned, and an entry | |
23213 | written to the panic log. | |
23214 | ||
23215 | ||
23216 | 31.7 Rewriting flags | |
23217 | -------------------- | |
23218 | ||
23219 | There are three different kinds of flag that may appear on rewriting rules: | |
23220 | ||
23221 | * Flags that specify which headers and envelope addresses to rewrite: E, F, | |
23222 | T, b, c, f, h, r, s, t. | |
23223 | ||
23224 | * A flag that specifies rewriting at SMTP time: S. | |
23225 | ||
23226 | * Flags that control the rewriting process: Q, q, R, w. | |
23227 | ||
23228 | For rules that are part of the headers_rewrite generic transport option, E, F, | |
23229 | T, and S are not permitted. | |
23230 | ||
23231 | ||
23232 | 31.8 Flags specifying which headers and envelope addresses to rewrite | |
23233 | --------------------------------------------------------------------- | |
23234 | ||
23235 | If none of the following flag letters, nor the "S" flag (see section 31.9) are | |
23236 | present, a main rewriting rule applies to all headers and to both the sender | |
23237 | and recipient fields of the envelope, whereas a transport-time rewriting rule | |
23238 | just applies to all headers. Otherwise, the rewriting rule is skipped unless | |
23239 | the relevant addresses are being processed. | |
23240 | ||
23241 | E rewrite all envelope fields | |
23242 | F rewrite the envelope From field | |
23243 | T rewrite the envelope To field | |
23244 | b rewrite the Bcc: header | |
23245 | c rewrite the Cc: header | |
23246 | f rewrite the From: header | |
23247 | h rewrite all headers | |
23248 | r rewrite the Reply-To: header | |
23249 | s rewrite the Sender: header | |
23250 | t rewrite the To: header | |
23251 | ||
23252 | "All headers" means all of the headers listed above that can be selected | |
23253 | individually, plus their Resent- versions. It does not include other headers | |
23254 | such as Subject: etc. | |
23255 | ||
23256 | You should be particularly careful about rewriting Sender: headers, and | |
23257 | restrict this to special known cases in your own domains. | |
23258 | ||
23259 | ||
23260 | 31.9 The SMTP-time rewriting flag | |
23261 | --------------------------------- | |
23262 | ||
23263 | The rewrite flag "S" specifies a rewrite of incoming envelope addresses at SMTP | |
23264 | time, as soon as an address is received in a MAIL or RCPT command, and before | |
23265 | any other processing; even before syntax checking. The pattern is required to | |
23266 | be a regular expression, and it is matched against the whole of the data for | |
23267 | the command, including any surrounding angle brackets. | |
23268 | ||
23269 | This form of rewrite rule allows for the handling of addresses that are not | |
23270 | compliant with RFCs 2821 and 2822 (for example, "bang paths" in batched SMTP | |
23271 | input). Because the input is not required to be a syntactically valid address, | |
23272 | the variables $local_part and $domain are not available during the expansion of | |
23273 | the replacement string. The result of rewriting replaces the original address | |
23274 | in the MAIL or RCPT command. | |
23275 | ||
23276 | ||
23277 | 31.10 Flags controlling the rewriting process | |
23278 | --------------------------------------------- | |
23279 | ||
23280 | There are four flags which control the way the rewriting process works. These | |
23281 | take effect only when a rule is invoked, that is, when the address is of the | |
23282 | correct type (matches the flags) and matches the pattern: | |
23283 | ||
23284 | * If the "Q" flag is set on a rule, the rewritten address is permitted to be | |
23285 | an unqualified local part. It is qualified with qualify_recipient. In the | |
23286 | absence of "Q" the rewritten address must always include a domain. | |
23287 | ||
23288 | * If the "q" flag is set on a rule, no further rewriting rules are | |
23289 | considered, even if no rewriting actually takes place because of a "fail" | |
23290 | in the expansion. The "q" flag is not effective if the address is of the | |
23291 | wrong type (does not match the flags) or does not match the pattern. | |
23292 | ||
23293 | * The "R" flag causes a successful rewriting rule to be re-applied to the new | |
23294 | address, up to ten times. It can be combined with the "q" flag, to stop | |
23295 | rewriting once it fails to match (after at least one successful rewrite). | |
23296 | ||
23297 | * When an address in a header is rewritten, the rewriting normally applies | |
23298 | only to the working part of the address, with any comments and RFC 2822 | |
23299 | "phrase" left unchanged. For example, rewriting might change | |
23300 | ||
23301 | From: Ford Prefect <fp42@restaurant.hitch.fict.example> | |
23302 | ||
23303 | into | |
23304 | ||
23305 | From: Ford Prefect <prefectf@hitch.fict.example> | |
23306 | ||
23307 | Sometimes there is a need to replace the whole address item, and this can | |
23308 | be done by adding the flag letter "w" to a rule. If this is set on a rule | |
23309 | that causes an address in a header line to be rewritten, the entire address | |
23310 | is replaced, not just the working part. The replacement must be a complete | |
23311 | RFC 2822 address, including the angle brackets if necessary. If text | |
23312 | outside angle brackets contains a character whose value is greater than 126 | |
23313 | or less than 32 (except for tab), the text is encoded according to RFC | |
2813c06e CE |
23314 | 2047. The character set is taken from headers_charset, which gets its |
23315 | default at build time. | |
420a0d19 CE |
23316 | |
23317 | When the "w" flag is set on a rule that causes an envelope address to be | |
23318 | rewritten, all but the working part of the replacement address is | |
23319 | discarded. | |
23320 | ||
23321 | ||
23322 | 31.11 Rewriting examples | |
23323 | ------------------------ | |
23324 | ||
23325 | Here is an example of the two common rewriting paradigms: | |
23326 | ||
23327 | *@*.hitch.fict.example $1@hitch.fict.example | |
23328 | *@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\ | |
23329 | {$value}fail}@hitch.fict.example bctfrF | |
23330 | ||
23331 | Note the use of "fail" in the lookup expansion in the second rule, forcing the | |
23332 | string expansion to fail if the lookup does not succeed. In this context it has | |
23333 | the effect of leaving the original address unchanged, but Exim goes on to | |
23334 | consider subsequent rewriting rules, if any, because the "q" flag is not | |
23335 | present in that rule. An alternative to "fail" would be to supply $1 | |
23336 | explicitly, which would cause the rewritten address to be the same as before, | |
23337 | at the cost of a small bit of processing. Not supplying either of these is an | |
23338 | error, since the rewritten address would then contain no local part. | |
23339 | ||
23340 | The first example above replaces the domain with a superior, more general | |
23341 | domain. This may not be desirable for certain local parts. If the rule | |
23342 | ||
23343 | root@*.hitch.fict.example * | |
23344 | ||
23345 | were inserted before the first rule, rewriting would be suppressed for the | |
23346 | local part root at any domain ending in hitch.fict.example. | |
23347 | ||
23348 | Rewriting can be made conditional on a number of tests, by making use of ${if | |
23349 | in the expansion item. For example, to apply a rewriting rule only to messages | |
23350 | that originate outside the local host: | |
23351 | ||
23352 | *@*.hitch.fict.example "${if !eq {$sender_host_address}{}\ | |
23353 | {$1@hitch.fict.example}fail}" | |
23354 | ||
23355 | The replacement string is quoted in this example because it contains white | |
23356 | space. | |
23357 | ||
23358 | Exim does not handle addresses in the form of "bang paths". If it sees such an | |
23359 | address it treats it as an unqualified local part which it qualifies with the | |
23360 | local qualification domain (if the source of the message is local or if the | |
23361 | remote host is permitted to send unqualified addresses). Rewriting can | |
23362 | sometimes be used to handle simple bang paths with a fixed number of | |
23363 | components. For example, the rule | |
23364 | ||
23365 | \N^([^!]+)!(.*)@your.domain.example$\N $2@$1 | |
23366 | ||
23367 | rewrites a two-component bang path host.name!user as the domain address | |
23368 | user@host.name. However, there is a security implication in using this as a | |
23369 | global rewriting rule for envelope addresses. It can provide a backdoor method | |
23370 | for using your system as a relay, because the incoming addresses appear to be | |
23371 | local. If the bang path addresses are received via SMTP, it is safer to use the | |
23372 | "S" flag to rewrite them as they are received, so that relay checking can be | |
23373 | done on the rewritten addresses. | |
23374 | ||
23375 | ||
23376 | ||
23377 | =============================================================================== | |
23378 | 32. RETRY CONFIGURATION | |
23379 | ||
23380 | The "retry" section of the runtime configuration file contains a list of retry | |
23381 | rules that control how often Exim tries to deliver messages that cannot be | |
23382 | delivered at the first attempt. If there are no retry rules (the section is | |
23383 | empty or not present), there are no retries. In this situation, temporary | |
23384 | errors are treated as permanent. The default configuration contains a single, | |
23385 | general-purpose retry rule (see section 7.5). The -brt command line option can | |
23386 | be used to test which retry rule will be used for a given address, domain and | |
23387 | error. | |
23388 | ||
23389 | The most common cause of retries is temporary failure to deliver to a remote | |
23390 | host because the host is down, or inaccessible because of a network problem. | |
23391 | Exim's retry processing in this case is applied on a per-host (strictly, per IP | |
23392 | address) basis, not on a per-message basis. Thus, if one message has recently | |
23393 | been delayed, delivery of a new message to the same host is not immediately | |
23394 | tried, but waits for the host's retry time to arrive. If the retry_defer log | |
23395 | selector is set, the message "retry time not reached" is written to the main | |
2813c06e | 23396 | log whenever a delivery is skipped for this reason. Section 48.2 contains more |
420a0d19 CE |
23397 | details of the handling of errors during remote deliveries. |
23398 | ||
23399 | Retry processing applies to routing as well as to delivering, except as covered | |
23400 | in the next paragraph. The retry rules do not distinguish between these | |
23401 | actions. It is not possible, for example, to specify different behaviour for | |
23402 | failures to route the domain snark.fict.example and failures to deliver to the | |
23403 | host snark.fict.example. I didn't think anyone would ever need this added | |
23404 | complication, so did not implement it. However, although they share the same | |
23405 | retry rule, the actual retry times for routing and transporting a given domain | |
23406 | are maintained independently. | |
23407 | ||
23408 | When a delivery is not part of a queue run (typically an immediate delivery on | |
23409 | receipt of a message), the routers are always run, and local deliveries are | |
23410 | always attempted, even if retry times are set for them. This makes for better | |
23411 | behaviour if one particular message is causing problems (for example, causing | |
23412 | quota overflow, or provoking an error in a filter file). If such a delivery | |
23413 | suffers a temporary failure, the retry data is updated as normal, and | |
23414 | subsequent delivery attempts from queue runs occur only when the retry time for | |
23415 | the local address is reached. | |
23416 | ||
23417 | ||
23418 | 32.1 Changing retry rules | |
23419 | ------------------------- | |
23420 | ||
23421 | If you change the retry rules in your configuration, you should consider | |
23422 | whether or not to delete the retry data that is stored in Exim's spool area in | |
23423 | files with names like db/retry. Deleting any of Exim's hints files is always | |
23424 | safe; that is why they are called "hints". | |
23425 | ||
23426 | The hints retry data contains suggested retry times based on the previous | |
23427 | rules. In the case of a long-running problem with a remote host, it might | |
23428 | record the fact that the host has timed out. If your new rules increase the | |
23429 | timeout time for such a host, you should definitely remove the old retry data | |
23430 | and let Exim recreate it, based on the new rules. Otherwise Exim might bounce | |
23431 | messages that it should now be retaining. | |
23432 | ||
23433 | ||
23434 | 32.2 Format of retry rules | |
23435 | -------------------------- | |
23436 | ||
23437 | Each retry rule occupies one line and consists of three or four parts, | |
23438 | separated by white space: a pattern, an error name, an optional list of sender | |
23439 | addresses, and a list of retry parameters. The pattern and sender lists must be | |
23440 | enclosed in double quotes if they contain white space. The rules are searched | |
23441 | in order until one is found where the pattern, error name, and sender list (if | |
23442 | present) match the failing host or address, the error that occurred, and the | |
23443 | message's sender, respectively. | |
23444 | ||
23445 | The pattern is any single item that may appear in an address list (see section | |
23446 | 10.19). It is in fact processed as a one-item address list, which means that it | |
23447 | is expanded before being tested against the address that has been delayed. A | |
23448 | negated address list item is permitted. Address list processing treats a plain | |
23449 | domain name as if it were preceded by "*@", which makes it possible for many | |
23450 | retry rules to start with just a domain. For example, | |
23451 | ||
23452 | lookingglass.fict.example * F,24h,30m; | |
23453 | ||
23454 | provides a rule for any address in the lookingglass.fict.example domain, | |
23455 | whereas | |
23456 | ||
23457 | alice@lookingglass.fict.example * F,24h,30m; | |
23458 | ||
23459 | applies only to temporary failures involving the local part alice. In practice, | |
23460 | almost all rules start with a domain name pattern without a local part. | |
23461 | ||
23462 | Warning: If you use a regular expression in a retry rule pattern, it must match | |
23463 | a complete address, not just a domain, because that is how regular expressions | |
23464 | work in address lists. | |
23465 | ||
23466 | ^\Nxyz\d+\.abc\.example$\N * G,1h,10m,2 Wrong | |
23467 | ^\N[^@]+@xyz\d+\.abc\.example$\N * G,1h,10m,2 Right | |
23468 | ||
23469 | ||
23470 | 32.3 Choosing which retry rule to use for address errors | |
23471 | -------------------------------------------------------- | |
23472 | ||
23473 | When Exim is looking for a retry rule after a routing attempt has failed (for | |
23474 | example, after a DNS timeout), each line in the retry configuration is tested | |
23475 | against the complete address only if retry_use_local_part is set for the | |
23476 | router. Otherwise, only the domain is used, except when matching against a | |
23477 | regular expression, when the local part of the address is replaced with "*". A | |
23478 | domain on its own can match a domain pattern, or a pattern that starts with | |
23479 | "*@". By default, retry_use_local_part is true for routers where | |
23480 | check_local_user is true, and false for other routers. | |
23481 | ||
23482 | Similarly, when Exim is looking for a retry rule after a local delivery has | |
23483 | failed (for example, after a mailbox full error), each line in the retry | |
23484 | configuration is tested against the complete address only if | |
23485 | retry_use_local_part is set for the transport (it defaults true for all local | |
23486 | transports). | |
23487 | ||
23488 | However, when Exim is looking for a retry rule after a remote delivery attempt | |
23489 | suffers an address error (a 4xx SMTP response for a recipient address), the | |
23490 | whole address is always used as the key when searching the retry rules. The | |
23491 | rule that is found is used to create a retry time for the combination of the | |
23492 | failing address and the message's sender. It is the combination of sender and | |
23493 | recipient that is delayed in subsequent queue runs until its retry time is | |
23494 | reached. You can delay the recipient without regard to the sender by setting | |
23495 | address_retry_include_sender false in the smtp transport but this can lead to | |
23496 | problems with servers that regularly issue 4xx responses to RCPT commands. | |
23497 | ||
23498 | ||
23499 | 32.4 Choosing which retry rule to use for host and message errors | |
23500 | ----------------------------------------------------------------- | |
23501 | ||
23502 | For a temporary error that is not related to an individual address (for | |
23503 | example, a connection timeout), each line in the retry configuration is checked | |
23504 | twice. First, the name of the remote host is used as a domain name (preceded by | |
23505 | "*@" when matching a regular expression). If this does not match the line, the | |
23506 | domain from the email address is tried in a similar fashion. For example, | |
23507 | suppose the MX records for a.b.c.example are | |
23508 | ||
23509 | a.b.c.example MX 5 x.y.z.example | |
23510 | MX 6 p.q.r.example | |
23511 | MX 7 m.n.o.example | |
23512 | ||
23513 | and the retry rules are | |
23514 | ||
23515 | p.q.r.example * F,24h,30m; | |
23516 | a.b.c.example * F,4d,45m; | |
23517 | ||
23518 | and a delivery to the host x.y.z.example suffers a connection failure. The | |
23519 | first rule matches neither the host nor the domain, so Exim looks at the second | |
23520 | rule. This does not match the host, but it does match the domain, so it is used | |
23521 | to calculate the retry time for the host x.y.z.example. Meanwhile, Exim tries | |
23522 | to deliver to p.q.r.example. If this also suffers a host error, the first retry | |
23523 | rule is used, because it matches the host. | |
23524 | ||
23525 | In other words, temporary failures to deliver to host p.q.r.example use the | |
23526 | first rule to determine retry times, but for all the other hosts for the domain | |
23527 | a.b.c.example, the second rule is used. The second rule is also used if routing | |
23528 | to a.b.c.example suffers a temporary failure. | |
23529 | ||
23530 | Note: The host name is used when matching the patterns, not its IP address. | |
23531 | However, if a message is routed directly to an IP address without the use of a | |
23532 | host name, for example, if a manualroute router contains a setting such as: | |
23533 | ||
23534 | route_list = *.a.example 192.168.34.23 | |
23535 | ||
23536 | then the "host name" that is used when searching for a retry rule is the | |
23537 | textual form of the IP address. | |
23538 | ||
23539 | ||
23540 | 32.5 Retry rules for specific errors | |
23541 | ------------------------------------ | |
23542 | ||
23543 | The second field in a retry rule is the name of a particular error, or an | |
23544 | asterisk, which matches any error. The errors that can be tested for are: | |
23545 | ||
23546 | auth_failed | |
23547 | ||
23548 | Authentication failed when trying to send to a host in the | |
23549 | hosts_require_auth list in an smtp transport. | |
23550 | ||
23551 | data_4xx | |
23552 | ||
23553 | A 4xx error was received for an outgoing DATA command, either immediately | |
23554 | after the command, or after sending the message's data. | |
23555 | ||
23556 | mail_4xx | |
23557 | ||
23558 | A 4xx error was received for an outgoing MAIL command. | |
23559 | ||
23560 | rcpt_4xx | |
23561 | ||
23562 | A 4xx error was received for an outgoing RCPT command. | |
23563 | ||
23564 | For the three 4xx errors, either the first or both of the x's can be given as | |
23565 | specific digits, for example: "mail_45x" or "rcpt_436". For example, to | |
23566 | recognize 452 errors given to RCPT commands for addresses in a certain domain, | |
23567 | and have retries every ten minutes with a one-hour timeout, you could set up a | |
23568 | retry rule of this form: | |
23569 | ||
23570 | the.domain.name rcpt_452 F,1h,10m | |
23571 | ||
23572 | These errors apply to both outgoing SMTP (the smtp transport) and outgoing LMTP | |
23573 | (either the lmtp transport, or the smtp transport in LMTP mode). | |
23574 | ||
23575 | lost_connection | |
23576 | ||
23577 | A server unexpectedly closed the SMTP connection. There may, of course, | |
23578 | legitimate reasons for this (host died, network died), but if it repeats a | |
23579 | lot for the same host, it indicates something odd. | |
23580 | ||
2813c06e CE |
23581 | lookup |
23582 | ||
23583 | A DNS lookup for a host failed. Note that a dnslookup router will need to | |
23584 | have matched its fail_defer_domains option for this retry type to be | |
23585 | usable. Also note that a manualroute router will probably need its | |
23586 | host_find_failed option set to defer. | |
23587 | ||
420a0d19 CE |
23588 | refused_MX |
23589 | ||
23590 | A connection to a host obtained from an MX record was refused. | |
23591 | ||
23592 | refused_A | |
23593 | ||
23594 | A connection to a host not obtained from an MX record was refused. | |
23595 | ||
23596 | refused | |
23597 | ||
23598 | A connection was refused. | |
23599 | ||
23600 | timeout_connect_MX | |
23601 | ||
23602 | A connection attempt to a host obtained from an MX record timed out. | |
23603 | ||
23604 | timeout_connect_A | |
23605 | ||
23606 | A connection attempt to a host not obtained from an MX record timed out. | |
23607 | ||
23608 | timeout_connect | |
23609 | ||
23610 | A connection attempt timed out. | |
23611 | ||
23612 | timeout_MX | |
23613 | ||
23614 | There was a timeout while connecting or during an SMTP session with a host | |
23615 | obtained from an MX record. | |
23616 | ||
23617 | timeout_A | |
23618 | ||
23619 | There was a timeout while connecting or during an SMTP session with a host | |
23620 | not obtained from an MX record. | |
23621 | ||
23622 | timeout | |
23623 | ||
23624 | There was a timeout while connecting or during an SMTP session. | |
23625 | ||
23626 | tls_required | |
23627 | ||
23628 | The server was required to use TLS (it matched hosts_require_tls in the | |
23629 | smtp transport), but either did not offer TLS, or it responded with 4xx to | |
23630 | STARTTLS, or there was a problem setting up the TLS connection. | |
23631 | ||
23632 | quota | |
23633 | ||
23634 | A mailbox quota was exceeded in a local delivery by the appendfile | |
23635 | transport. | |
23636 | ||
23637 | quota_<time> | |
23638 | ||
23639 | A mailbox quota was exceeded in a local delivery by the appendfile | |
23640 | transport, and the mailbox has not been accessed for <time>. For example, | |
23641 | quota_4d applies to a quota error when the mailbox has not been accessed | |
23642 | for four days. | |
23643 | ||
23644 | The idea of quota_<time> is to make it possible to have shorter timeouts when | |
23645 | the mailbox is full and is not being read by its owner. Ideally, it should be | |
23646 | based on the last time that the user accessed the mailbox. However, it is not | |
23647 | always possible to determine this. Exim uses the following heuristic rules: | |
23648 | ||
23649 | * If the mailbox is a single file, the time of last access (the "atime") is | |
23650 | used. As no new messages are being delivered (because the mailbox is over | |
23651 | quota), Exim does not access the file, so this is the time of last user | |
23652 | access. | |
23653 | ||
23654 | * For a maildir delivery, the time of last modification of the new | |
23655 | subdirectory is used. As the mailbox is over quota, no new files are | |
23656 | created in the new subdirectory, because no new messages are being | |
23657 | delivered. Any change to the new subdirectory is therefore assumed to be | |
23658 | the result of an MUA moving a new message to the cur directory when it is | |
23659 | first read. The time that is used is therefore the last time that the user | |
23660 | read a new message. | |
23661 | ||
23662 | * For other kinds of multi-file mailbox, the time of last access cannot be | |
23663 | obtained, so a retry rule that uses this type of error field is never | |
23664 | matched. | |
23665 | ||
23666 | The quota errors apply both to system-enforced quotas and to Exim's own quota | |
23667 | mechanism in the appendfile transport. The quota error also applies when a | |
23668 | local delivery is deferred because a partition is full (the ENOSPC error). | |
23669 | ||
23670 | ||
23671 | 32.6 Retry rules for specified senders | |
23672 | -------------------------------------- | |
23673 | ||
23674 | You can specify retry rules that apply only when the failing message has a | |
23675 | specific sender. In particular, this can be used to define retry rules that | |
23676 | apply only to bounce messages. The third item in a retry rule can be of this | |
23677 | form: | |
23678 | ||
23679 | senders=<address list> | |
23680 | ||
23681 | The retry timings themselves are then the fourth item. For example: | |
23682 | ||
23683 | * rcpt_4xx senders=: F,1h,30m | |
23684 | ||
23685 | matches recipient 4xx errors for bounce messages sent to any address at any | |
23686 | host. If the address list contains white space, it must be enclosed in quotes. | |
23687 | For example: | |
23688 | ||
23689 | a.domain rcpt_452 senders="xb.dom : yc.dom" G,8h,10m,1.5 | |
23690 | ||
23691 | Warning: This facility can be unhelpful if it is used for host errors (which do | |
23692 | not depend on the recipient). The reason is that the sender is used only to | |
23693 | match the retry rule. Once the rule has been found for a host error, its | |
23694 | contents are used to set a retry time for the host, and this will apply to all | |
23695 | messages, not just those with specific senders. | |
23696 | ||
23697 | When testing retry rules using -brt, you can supply a sender using the -f | |
23698 | command line option, like this: | |
23699 | ||
23700 | exim -f "" -brt user@dom.ain | |
23701 | ||
23702 | If you do not set -f with -brt, a retry rule that contains a senders list is | |
23703 | never matched. | |
23704 | ||
23705 | ||
23706 | 32.7 Retry parameters | |
23707 | --------------------- | |
23708 | ||
23709 | The third (or fourth, if a senders list is present) field in a retry rule is a | |
23710 | sequence of retry parameter sets, separated by semicolons. Each set consists of | |
23711 | ||
23712 | <letter>,<cutoff time>,<arguments> | |
23713 | ||
23714 | The letter identifies the algorithm for computing a new retry time; the cutoff | |
23715 | time is the time beyond which this algorithm no longer applies, and the | |
23716 | arguments vary the algorithm's action. The cutoff time is measured from the | |
23717 | time that the first failure for the domain (combined with the local part if | |
23718 | relevant) was detected, not from the time the message was received. | |
23719 | ||
23720 | The available algorithms are: | |
23721 | ||
23722 | * F: retry at fixed intervals. There is a single time parameter specifying | |
23723 | the interval. | |
23724 | ||
23725 | * G: retry at geometrically increasing intervals. The first argument | |
23726 | specifies a starting value for the interval, and the second a multiplier, | |
23727 | which is used to increase the size of the interval at each retry. | |
23728 | ||
23729 | * H: retry at randomized intervals. The arguments are as for G. For each | |
23730 | retry, the previous interval is multiplied by the factor in order to get a | |
23731 | maximum for the next interval. The minimum interval is the first argument | |
23732 | of the parameter, and an actual interval is chosen randomly between them. | |
23733 | Such a rule has been found to be helpful in cluster configurations when all | |
23734 | the members of the cluster restart at once, and may therefore synchronize | |
23735 | their queue processing times. | |
23736 | ||
23737 | When computing the next retry time, the algorithm definitions are scanned in | |
23738 | order until one whose cutoff time has not yet passed is reached. This is then | |
23739 | used to compute a new retry time that is later than the current time. In the | |
23740 | case of fixed interval retries, this simply means adding the interval to the | |
23741 | current time. For geometrically increasing intervals, retry intervals are | |
23742 | computed from the rule's parameters until one that is greater than the previous | |
23743 | interval is found. The main configuration variable retry_interval_max limits | |
23744 | the maximum interval between retries. It cannot be set greater than "24h", | |
23745 | which is its default value. | |
23746 | ||
23747 | A single remote domain may have a number of hosts associated with it, and each | |
23748 | host may have more than one IP address. Retry algorithms are selected on the | |
23749 | basis of the domain name, but are applied to each IP address independently. If, | |
23750 | for example, a host has two IP addresses and one is unusable, Exim will | |
23751 | generate retry times for it and will not try to use it until its next retry | |
23752 | time comes. Thus the good IP address is likely to be tried first most of the | |
23753 | time. | |
23754 | ||
23755 | Retry times are hints rather than promises. Exim does not make any attempt to | |
23756 | run deliveries exactly at the computed times. Instead, a queue runner process | |
23757 | starts delivery processes for delayed messages periodically, and these attempt | |
23758 | new deliveries only for those addresses that have passed their next retry time. | |
23759 | If a new message arrives for a deferred address, an immediate delivery attempt | |
23760 | occurs only if the address has passed its retry time. In the absence of new | |
23761 | messages, the minimum time between retries is the interval between queue runner | |
23762 | processes. There is not much point in setting retry times of five minutes if | |
23763 | your queue runners happen only once an hour, unless there are a significant | |
23764 | number of incoming messages (which might be the case on a system that is | |
23765 | sending everything to a smart host, for example). | |
23766 | ||
23767 | The data in the retry hints database can be inspected by using the exim_dumpdb | |
2813c06e | 23768 | or exim_fixdb utility programs (see chapter 53). The latter utility can also be |
420a0d19 CE |
23769 | used to change the data. The exinext utility script can be used to find out |
23770 | what the next retry times are for the hosts associated with a particular mail | |
23771 | domain, and also for local deliveries that have been deferred. | |
23772 | ||
23773 | ||
23774 | 32.8 Retry rule examples | |
23775 | ------------------------ | |
23776 | ||
23777 | Here are some example retry rules: | |
23778 | ||
23779 | alice@wonderland.fict.example quota_5d F,7d,3h | |
23780 | wonderland.fict.example quota_5d | |
23781 | wonderland.fict.example * F,1h,15m; G,2d,1h,2; | |
23782 | lookingglass.fict.example * F,24h,30m; | |
23783 | * refused_A F,2h,20m; | |
23784 | * * F,2h,15m; G,16h,1h,1.5; F,5d,8h | |
23785 | ||
23786 | The first rule sets up special handling for mail to | |
23787 | alice@wonderland.fict.example when there is an over-quota error and the mailbox | |
23788 | has not been read for at least 5 days. Retries continue every three hours for 7 | |
23789 | days. The second rule handles over-quota errors for all other local parts at | |
23790 | wonderland.fict.example; the absence of a local part has the same effect as | |
23791 | supplying "*@". As no retry algorithms are supplied, messages that fail are | |
23792 | bounced immediately if the mailbox has not been read for at least 5 days. | |
23793 | ||
23794 | The third rule handles all other errors at wonderland.fict.example; retries | |
23795 | happen every 15 minutes for an hour, then with geometrically increasing | |
23796 | intervals until two days have passed since a delivery first failed. After the | |
23797 | first hour there is a delay of one hour, then two hours, then four hours, and | |
23798 | so on (this is a rather extreme example). | |
23799 | ||
23800 | The fourth rule controls retries for the domain lookingglass.fict.example. They | |
23801 | happen every 30 minutes for 24 hours only. The remaining two rules handle all | |
23802 | other domains, with special action for connection refusal from hosts that were | |
23803 | not obtained from an MX record. | |
23804 | ||
23805 | The final rule in a retry configuration should always have asterisks in the | |
23806 | first two fields so as to provide a general catch-all for any addresses that do | |
23807 | not have their own special handling. This example tries every 15 minutes for 2 | |
23808 | hours, then with intervals starting at one hour and increasing by a factor of | |
23809 | 1.5 up to 16 hours, then every 8 hours up to 5 days. | |
23810 | ||
23811 | ||
23812 | 32.9 Timeout of retry data | |
23813 | -------------------------- | |
23814 | ||
23815 | Exim timestamps the data that it writes to its retry hints database. When it | |
23816 | consults the data during a delivery it ignores any that is older than the value | |
23817 | set in retry_data_expire (default 7 days). If, for example, a host hasn't been | |
23818 | tried for 7 days, Exim will try to deliver to it immediately a message arrives, | |
23819 | and if that fails, it will calculate a retry time as if it were failing for the | |
23820 | first time. | |
23821 | ||
23822 | This improves the behaviour for messages routed to rarely-used hosts such as MX | |
23823 | backups. If such a host was down at one time, and happens to be down again when | |
23824 | Exim tries a month later, using the old retry data would imply that it had been | |
23825 | down all the time, which is not a justified assumption. | |
23826 | ||
23827 | If a host really is permanently dead, this behaviour causes a burst of retries | |
23828 | every now and again, but only if messages routed to it are rare. If there is a | |
23829 | message at least once every 7 days the retry data never expires. | |
23830 | ||
23831 | ||
23832 | 32.10 Long-term failures | |
23833 | ------------------------ | |
23834 | ||
23835 | Special processing happens when an email address has been failing for so long | |
23836 | that the cutoff time for the last algorithm is reached. For example, using the | |
23837 | default retry rule: | |
23838 | ||
23839 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h | |
23840 | ||
23841 | the cutoff time is four days. Reaching the retry cutoff is independent of how | |
23842 | long any specific message has been failing; it is the length of continuous | |
23843 | failure for the recipient address that counts. | |
23844 | ||
23845 | When the cutoff time is reached for a local delivery, or for all the IP | |
23846 | addresses associated with a remote delivery, a subsequent delivery failure | |
23847 | causes Exim to give up on the address, and a bounce message is generated. In | |
23848 | order to cater for new messages that use the failing address, a next retry time | |
23849 | is still computed from the final algorithm, and is used as follows: | |
23850 | ||
23851 | For local deliveries, one delivery attempt is always made for any subsequent | |
23852 | messages. If this delivery fails, the address fails immediately. The | |
23853 | post-cutoff retry time is not used. | |
23854 | ||
23855 | If the delivery is remote, there are two possibilities, controlled by the | |
23856 | delay_after_cutoff option of the smtp transport. The option is true by default. | |
23857 | Until the post-cutoff retry time for one of the IP addresses is reached, the | |
23858 | failing email address is bounced immediately, without a delivery attempt taking | |
23859 | place. After that time, one new delivery attempt is made to those IP addresses | |
23860 | that are past their retry times, and if that still fails, the address is | |
23861 | bounced and new retry times are computed. | |
23862 | ||
23863 | In other words, when all the hosts for a given email address have been failing | |
23864 | for a long time, Exim bounces rather then defers until one of the hosts' retry | |
23865 | times is reached. Then it tries once, and bounces if that attempt fails. This | |
23866 | behaviour ensures that few resources are wasted in repeatedly trying to deliver | |
23867 | to a broken destination, but if the host does recover, Exim will eventually | |
23868 | notice. | |
23869 | ||
23870 | If delay_after_cutoff is set false, Exim behaves differently. If all IP | |
23871 | addresses are past their final cutoff time, Exim tries to deliver to those IP | |
23872 | addresses that have not been tried since the message arrived. If there are no | |
23873 | suitable IP addresses, or if they all fail, the address is bounced. In other | |
23874 | words, it does not delay when a new message arrives, but tries the expired | |
23875 | addresses immediately, unless they have been tried since the message arrived. | |
23876 | If there is a continuous stream of messages for the failing domains, setting | |
23877 | delay_after_cutoff false means that there will be many more attempts to deliver | |
23878 | to permanently failing IP addresses than when delay_after_cutoff is true. | |
23879 | ||
23880 | ||
23881 | 32.11 Deliveries that work intermittently | |
23882 | ----------------------------------------- | |
23883 | ||
23884 | Some additional logic is needed to cope with cases where a host is | |
23885 | intermittently available, or when a message has some attribute that prevents | |
23886 | its delivery when others to the same address get through. In this situation, | |
23887 | because some messages are successfully delivered, the "retry clock" for the | |
23888 | host or address keeps getting reset by the successful deliveries, and so | |
23889 | failing messages remain on the queue for ever because the cutoff time is never | |
23890 | reached. | |
23891 | ||
23892 | Two exceptional actions are applied to prevent this happening. The first | |
23893 | applies to errors that are related to a message rather than a remote host. | |
2813c06e | 23894 | Section 48.2 has a discussion of the different kinds of error; examples of |
420a0d19 CE |
23895 | message-related errors are 4xx responses to MAIL or DATA commands, and quota |
23896 | failures. For this type of error, if a message's arrival time is earlier than | |
23897 | the "first failed" time for the error, the earlier time is used when scanning | |
23898 | the retry rules to decide when to try next and when to time out the address. | |
23899 | ||
23900 | The exceptional second action applies in all cases. If a message has been on | |
23901 | the queue for longer than the cutoff time of any applicable retry rule for a | |
23902 | given address, a delivery is attempted for that address, even if it is not yet | |
23903 | time, and if this delivery fails, the address is timed out. A new retry time is | |
23904 | not computed in this case, so that other messages for the same address are | |
23905 | considered immediately. | |
23906 | ||
23907 | ||
23908 | ||
23909 | =============================================================================== | |
23910 | 33. SMTP AUTHENTICATION | |
23911 | ||
23912 | The "authenticators" section of Exim's run time configuration is concerned with | |
23913 | SMTP authentication. This facility is an extension to the SMTP protocol, | |
23914 | described in RFC 2554, which allows a client SMTP host to authenticate itself | |
23915 | to a server. This is a common way for a server to recognize clients that are | |
23916 | permitted to use it as a relay. SMTP authentication is not of relevance to the | |
23917 | transfer of mail between servers that have no managerial connection with each | |
23918 | other. | |
23919 | ||
23920 | Very briefly, the way SMTP authentication works is as follows: | |
23921 | ||
23922 | * The server advertises a number of authentication mechanisms in response to | |
23923 | the client's EHLO command. | |
23924 | ||
23925 | * The client issues an AUTH command, naming a specific mechanism. The command | |
23926 | may, optionally, contain some authentication data. | |
23927 | ||
23928 | * The server may issue one or more challenges, to which the client must send | |
23929 | appropriate responses. In simple authentication mechanisms, the challenges | |
23930 | are just prompts for user names and passwords. The server does not have to | |
23931 | issue any challenges - in some mechanisms the relevant data may all be | |
23932 | transmitted with the AUTH command. | |
23933 | ||
23934 | * The server either accepts or denies authentication. | |
23935 | ||
23936 | * If authentication succeeds, the client may optionally make use of the AUTH | |
23937 | option on the MAIL command to pass an authenticated sender in subsequent | |
23938 | mail transactions. Authentication lasts for the remainder of the SMTP | |
23939 | connection. | |
23940 | ||
23941 | * If authentication fails, the client may give up, or it may try a different | |
23942 | authentication mechanism, or it may try transferring mail over the | |
23943 | unauthenticated connection. | |
23944 | ||
23945 | If you are setting up a client, and want to know which authentication | |
23946 | mechanisms the server supports, you can use Telnet to connect to port 25 (the | |
23947 | SMTP port) on the server, and issue an EHLO command. The response to this | |
23948 | includes the list of supported mechanisms. For example: | |
23949 | ||
23950 | $ telnet server.example 25 | |
23951 | Trying 192.168.34.25... | |
23952 | Connected to server.example. | |
23953 | Escape character is '^]'. | |
23954 | 220 server.example ESMTP Exim 4.20 ... | |
23955 | ehlo client.example | |
23956 | 250-server.example Hello client.example [10.8.4.5] | |
23957 | 250-SIZE 52428800 | |
23958 | 250-PIPELINING | |
23959 | 250-AUTH PLAIN | |
23960 | 250 HELP | |
23961 | ||
23962 | The second-last line of this example output shows that the server supports | |
23963 | authentication using the PLAIN mechanism. In Exim, the different authentication | |
23964 | mechanisms are configured by specifying authenticator drivers. Like the routers | |
23965 | and transports, which authenticators are included in the binary is controlled | |
23966 | by build-time definitions. The following are currently available, included by | |
23967 | setting | |
23968 | ||
23969 | AUTH_CRAM_MD5=yes | |
23970 | AUTH_CYRUS_SASL=yes | |
23971 | AUTH_DOVECOT=yes | |
23972 | AUTH_GSASL=yes | |
23973 | AUTH_HEIMDAL_GSSAPI=yes | |
23974 | AUTH_PLAINTEXT=yes | |
23975 | AUTH_SPA=yes | |
2813c06e | 23976 | AUTH_TLS=yes |
420a0d19 CE |
23977 | |
23978 | in Local/Makefile, respectively. The first of these supports the CRAM-MD5 | |
23979 | authentication mechanism (RFC 2195), and the second provides an interface to | |
23980 | the Cyrus SASL authentication library. The third is an interface to Dovecot's | |
23981 | authentication system, delegating the work via a socket interface. The fourth | |
23982 | provides an interface to the GNU SASL authentication library, which provides | |
23983 | mechanisms but typically not data sources. The fifth provides direct access to | |
23984 | Heimdal GSSAPI, geared for Kerberos, but supporting setting a server keytab. | |
23985 | The sixth can be configured to support the PLAIN authentication mechanism (RFC | |
23986 | 2595) or the LOGIN mechanism, which is not formally documented, but used by | |
23987 | several MUAs. The seventh authenticator supports Microsoft's Secure Password | |
2813c06e CE |
23988 | Authentication mechanism. The eighth is an Exim authenticator but not an SMTP |
23989 | one; instead it can use information from a TLS negotiation. | |
420a0d19 CE |
23990 | |
23991 | The authenticators are configured using the same syntax as other drivers (see | |
2813c06e | 23992 | section 6.23). If no authenticators are required, no authentication section |
420a0d19 CE |
23993 | need be present in the configuration file. Each authenticator can in principle |
23994 | have both server and client functions. When Exim is receiving SMTP mail, it is | |
23995 | acting as a server; when it is sending out messages over SMTP, it is acting as | |
23996 | a client. Authenticator configuration options are provided for use in both | |
23997 | these circumstances. | |
23998 | ||
23999 | To make it clear which options apply to which situation, the prefixes server_ | |
24000 | and client_ are used on option names that are specific to either the server or | |
24001 | the client function, respectively. Server and client functions are disabled if | |
24002 | none of their options are set. If an authenticator is to be used for both | |
24003 | server and client functions, a single definition, using both sets of options, | |
24004 | is required. For example: | |
24005 | ||
24006 | cram: | |
24007 | driver = cram_md5 | |
24008 | public_name = CRAM-MD5 | |
24009 | server_secret = ${if eq{$auth1}{ph10}{secret1}fail} | |
24010 | client_name = ph10 | |
24011 | client_secret = secret2 | |
24012 | ||
24013 | The server_ option is used when Exim is acting as a server, and the client_ | |
24014 | options when it is acting as a client. | |
24015 | ||
24016 | Descriptions of the individual authenticators are given in subsequent chapters. | |
24017 | The remainder of this chapter covers the generic options for the | |
24018 | authenticators, followed by general discussion of the way authentication works | |
24019 | in Exim. | |
24020 | ||
24021 | Beware: the meaning of $auth1, $auth2, ... varies on a per-driver and | |
24022 | per-mechanism basis. Please read carefully to determine which variables hold | |
24023 | account labels such as usercodes and which hold passwords or other | |
24024 | authenticating data. | |
24025 | ||
24026 | Note that some mechanisms support two different identifiers for accounts: the | |
24027 | authentication id and the authorization id. The contractions authn and authz | |
24028 | are commonly encountered. The American spelling is standard here. Conceptually, | |
24029 | authentication data such as passwords are tied to the identifier used to | |
24030 | authenticate; servers may have rules to permit one user to act as a second | |
24031 | user, so that after login the session is treated as though that second user had | |
24032 | logged in. That second user is the authorization id. A robust configuration | |
24033 | might confirm that the authz field is empty or matches the authn field. Often | |
24034 | this is just ignored. The authn can be considered as verified data, the authz | |
24035 | as an unverified request which the server might choose to honour. | |
24036 | ||
24037 | A realm is a text string, typically a domain name, presented by a server to a | |
24038 | client to help it select an account and credentials to use. In some mechanisms, | |
24039 | the client and server provably agree on the realm, but clients typically can | |
24040 | not treat the realm as secure data to be blindly trusted. | |
24041 | ||
24042 | ||
24043 | 33.1 Generic options for authenticators | |
24044 | --------------------------------------- | |
24045 | ||
2813c06e | 24046 | +-----------------------------------------------------------------+ |
420a0d19 | 24047 | |client_condition|Use: authenticators|Type: string*|Default: unset| |
2813c06e | 24048 | +-----------------------------------------------------------------+ |
420a0d19 CE |
24049 | |
24050 | When Exim is authenticating as a client, it skips any authenticator whose | |
24051 | client_condition expansion yields "0", "no", or "false". This can be used, for | |
24052 | example, to skip plain text authenticators when the connection is not encrypted | |
24053 | by a setting such as: | |
24054 | ||
24055 | client_condition = ${if !eq{$tls_out_cipher}{}} | |
24056 | ||
2813c06e | 24057 | +--------------------------------------------------------------+ |
420a0d19 | 24058 | |client_set_id|Use: authenticators|Type: string*|Default: unset| |
2813c06e | 24059 | +--------------------------------------------------------------+ |
420a0d19 CE |
24060 | |
24061 | When client authentication succeeds, this condition is expanded; the result is | |
2813c06e CE |
24062 | used in the log lines for outbound messages. Typically it will be the user name |
24063 | used for authentication. | |
420a0d19 | 24064 | |
2813c06e | 24065 | +------------------------------------------------------+ |
420a0d19 | 24066 | |driver|Use: authenticators|Type: string|Default: unset| |
2813c06e | 24067 | +------------------------------------------------------+ |
420a0d19 CE |
24068 | |
24069 | This option must always be set. It specifies which of the available | |
24070 | authenticators is to be used. | |
24071 | ||
2813c06e | 24072 | +-----------------------------------------------------------+ |
420a0d19 | 24073 | |public_name|Use: authenticators|Type: string|Default: unset| |
2813c06e | 24074 | +-----------------------------------------------------------+ |
420a0d19 CE |
24075 | |
24076 | This option specifies the name of the authentication mechanism that the driver | |
24077 | implements, and by which it is known to the outside world. These names should | |
24078 | contain only upper case letters, digits, underscores, and hyphens (RFC 2222), | |
24079 | but Exim in fact matches them caselessly. If public_name is not set, it | |
24080 | defaults to the driver's instance name. | |
24081 | ||
2813c06e | 24082 | +---------------------------------------------------------------------------+ |
420a0d19 | 24083 | |server_advertise_condition|Use: authenticators|Type: string*|Default: unset| |
2813c06e | 24084 | +---------------------------------------------------------------------------+ |
420a0d19 CE |
24085 | |
24086 | When a server is about to advertise an authentication mechanism, the condition | |
24087 | is expanded. If it yields the empty string, "0", "no", or "false", the | |
24088 | mechanism is not advertised. If the expansion fails, the mechanism is not | |
24089 | advertised. If the failure was not forced, and was not caused by a lookup | |
24090 | defer, the incident is logged. See section 33.3 below for further discussion. | |
24091 | ||
2813c06e | 24092 | +-----------------------------------------------------------------+ |
420a0d19 | 24093 | |server_condition|Use: authenticators|Type: string*|Default: unset| |
2813c06e | 24094 | +-----------------------------------------------------------------+ |
420a0d19 CE |
24095 | |
24096 | This option must be set for a plaintext server authenticator, where it is used | |
24097 | directly to control authentication. See section 34.2 for details. | |
24098 | ||
24099 | For the gsasl authenticator, this option is required for various mechanisms; | |
24100 | see chapter 38 for details. | |
24101 | ||
24102 | For the other authenticators, server_condition can be used as an additional | |
24103 | authentication or authorization mechanism that is applied after the other | |
24104 | authenticator conditions succeed. If it is set, it is expanded when the | |
24105 | authenticator would otherwise return a success code. If the expansion is forced | |
24106 | to fail, authentication fails. Any other expansion failure causes a temporary | |
24107 | error code to be returned. If the result of a successful expansion is an empty | |
24108 | string, "0", "no", or "false", authentication fails. If the result of the | |
24109 | expansion is "1", "yes", or "true", authentication succeeds. For any other | |
24110 | result, a temporary error code is returned, with the expanded string as the | |
24111 | error text. | |
24112 | ||
2813c06e | 24113 | +-------------------------------------------------------------------+ |
420a0d19 | 24114 | |server_debug_print|Use: authenticators|Type: string*|Default: unset| |
2813c06e | 24115 | +-------------------------------------------------------------------+ |
420a0d19 CE |
24116 | |
24117 | If this option is set and authentication debugging is enabled (see the -d | |
24118 | command line option), the string is expanded and included in the debugging | |
24119 | output when the authenticator is run as a server. This can help with checking | |
24120 | out the values of variables. If expansion of the string fails, the error | |
24121 | message is written to the debugging output, and Exim carries on processing. | |
24122 | ||
2813c06e | 24123 | +--------------------------------------------------------------+ |
420a0d19 | 24124 | |server_set_id|Use: authenticators|Type: string*|Default: unset| |
2813c06e | 24125 | +--------------------------------------------------------------+ |
420a0d19 CE |
24126 | |
24127 | When an Exim server successfully authenticates a client, this string is | |
24128 | expanded using data from the authentication, and preserved for any incoming | |
24129 | messages in the variable $authenticated_id. It is also included in the log | |
24130 | lines for incoming messages. For example, a user/password authenticator | |
24131 | configuration might preserve the user name that was used to authenticate, and | |
24132 | refer to it subsequently during delivery of the message. If expansion fails, | |
24133 | the option is ignored. | |
24134 | ||
2813c06e | 24135 | +---------------------------------------------------------------------------+ |
420a0d19 | 24136 | |server_mail_auth_condition|Use: authenticators|Type: string*|Default: unset| |
2813c06e | 24137 | +---------------------------------------------------------------------------+ |
420a0d19 CE |
24138 | |
24139 | This option allows a server to discard authenticated sender addresses supplied | |
24140 | as part of MAIL commands in SMTP connections that are authenticated by the | |
24141 | driver on which server_mail_auth_condition is set. The option is not used as | |
24142 | part of the authentication process; instead its (unexpanded) value is | |
24143 | remembered for later use. How it is used is described in the following section. | |
24144 | ||
24145 | ||
24146 | 33.2 The AUTH parameter on MAIL commands | |
24147 | ---------------------------------------- | |
24148 | ||
24149 | When a client supplied an AUTH= item on a MAIL command, Exim applies the | |
24150 | following checks before accepting it as the authenticated sender of the | |
24151 | message: | |
24152 | ||
24153 | * If the connection is not using extended SMTP (that is, HELO was used rather | |
24154 | than EHLO), the use of AUTH= is a syntax error. | |
24155 | ||
24156 | * If the value of the AUTH= parameter is "<>", it is ignored. | |
24157 | ||
24158 | * If acl_smtp_mailauth is defined, the ACL it specifies is run. While it is | |
24159 | running, the value of $authenticated_sender is set to the value obtained | |
24160 | from the AUTH= parameter. If the ACL does not yield "accept", the value of | |
24161 | $authenticated_sender is deleted. The acl_smtp_mailauth ACL may not return | |
24162 | "drop" or "discard". If it defers, a temporary error code (451) is given | |
24163 | for the MAIL command. | |
24164 | ||
24165 | * If acl_smtp_mailauth is not defined, the value of the AUTH= parameter is | |
24166 | accepted and placed in $authenticated_sender only if the client has | |
24167 | authenticated. | |
24168 | ||
24169 | * If the AUTH= value was accepted by either of the two previous rules, and | |
24170 | the client has authenticated, and the authenticator has a setting for the | |
24171 | server_mail_auth_condition, the condition is checked at this point. The | |
24172 | valued that was saved from the authenticator is expanded. If the expansion | |
24173 | fails, or yields an empty string, "0", "no", or "false", the value of | |
24174 | $authenticated_sender is deleted. If the expansion yields any other value, | |
24175 | the value of $authenticated_sender is retained and passed on with the | |
24176 | message. | |
24177 | ||
24178 | When $authenticated_sender is set for a message, it is passed on to other hosts | |
24179 | to which Exim authenticates as a client. Do not confuse this value with | |
24180 | $authenticated_id, which is a string obtained from the authentication process, | |
24181 | and which is not usually a complete email address. | |
24182 | ||
24183 | Whenever an AUTH= value is ignored, the incident is logged. The ACL for MAIL, | |
24184 | if defined, is run after AUTH= is accepted or ignored. It can therefore make | |
24185 | use of $authenticated_sender. The converse is not true: the value of | |
24186 | $sender_address is not yet set up when the acl_smtp_mailauth ACL is run. | |
24187 | ||
24188 | ||
24189 | 33.3 Authentication on an Exim server | |
24190 | ------------------------------------- | |
24191 | ||
24192 | When Exim receives an EHLO command, it advertises the public names of those | |
24193 | authenticators that are configured as servers, subject to the following | |
24194 | conditions: | |
24195 | ||
24196 | * The client host must match auth_advertise_hosts (default *). | |
24197 | ||
24198 | * It the server_advertise_condition option is set, its expansion must not | |
24199 | yield the empty string, "0", "no", or "false". | |
24200 | ||
24201 | The order in which the authenticators are defined controls the order in which | |
24202 | the mechanisms are advertised. | |
24203 | ||
24204 | Some mail clients (for example, some versions of Netscape) require the user to | |
24205 | provide a name and password for authentication whenever AUTH is advertised, | |
24206 | even though authentication may not in fact be needed (for example, Exim may be | |
24207 | set up to allow unconditional relaying from the client by an IP address check). | |
24208 | You can make such clients more friendly by not advertising AUTH to them. For | |
24209 | example, if clients on the 10.9.8.0/24 network are permitted (by the ACL that | |
24210 | runs for RCPT) to relay without authentication, you should set | |
24211 | ||
24212 | auth_advertise_hosts = ! 10.9.8.0/24 | |
24213 | ||
24214 | so that no authentication mechanisms are advertised to them. | |
24215 | ||
24216 | The server_advertise_condition controls the advertisement of individual | |
24217 | authentication mechanisms. For example, it can be used to restrict the | |
24218 | advertisement of a particular mechanism to encrypted connections, by a setting | |
24219 | such as: | |
24220 | ||
24221 | server_advertise_condition = ${if eq{$tls_in_cipher}{}{no}{yes}} | |
24222 | ||
24223 | If the session is encrypted, $tls_in_cipher is not empty, and so the expansion | |
24224 | yields "yes", which allows the advertisement to happen. | |
24225 | ||
24226 | When an Exim server receives an AUTH command from a client, it rejects it | |
24227 | immediately if AUTH was not advertised in response to an earlier EHLO command. | |
24228 | This is the case if | |
24229 | ||
24230 | * The client host does not match auth_advertise_hosts; or | |
24231 | ||
24232 | * No authenticators are configured with server options; or | |
24233 | ||
24234 | * Expansion of server_advertise_condition blocked the advertising of all the | |
24235 | server authenticators. | |
24236 | ||
24237 | Otherwise, Exim runs the ACL specified by acl_smtp_auth in order to decide | |
24238 | whether to accept the command. If acl_smtp_auth is not set, AUTH is accepted | |
24239 | from any client host. | |
24240 | ||
24241 | If AUTH is not rejected by the ACL, Exim searches its configuration for a | |
24242 | server authentication mechanism that was advertised in response to EHLO and | |
24243 | that matches the one named in the AUTH command. If it finds one, it runs the | |
24244 | appropriate authentication protocol, and authentication either succeeds or | |
24245 | fails. If there is no matching advertised mechanism, the AUTH command is | |
24246 | rejected with a 504 error. | |
24247 | ||
24248 | When a message is received from an authenticated host, the value of | |
24249 | $received_protocol is set to "esmtpa" or "esmtpsa" instead of "esmtp" or | |
24250 | "esmtps", and $sender_host_authenticated contains the name (not the public | |
24251 | name) of the authenticator driver that successfully authenticated the client | |
24252 | from which the message was received. This variable is empty if there was no | |
24253 | successful authentication. | |
24254 | ||
24255 | ||
24256 | 33.4 Testing server authentication | |
24257 | ---------------------------------- | |
24258 | ||
24259 | Exim's -bh option can be useful for testing server authentication | |
24260 | configurations. The data for the AUTH command has to be sent using base64 | |
24261 | encoding. A quick way to produce such data for testing is the following Perl | |
24262 | script: | |
24263 | ||
24264 | use MIME::Base64; | |
24265 | printf ("%s", encode_base64(eval "\"$ARGV[0]\"")); | |
24266 | ||
24267 | This interprets its argument as a Perl string, and then encodes it. The | |
24268 | interpretation as a Perl string allows binary zeros, which are required for | |
24269 | some kinds of authentication, to be included in the data. For example, a | |
24270 | command line to run this script on such data might be | |
24271 | ||
24272 | encode '\0user\0password' | |
24273 | ||
24274 | Note the use of single quotes to prevent the shell interpreting the | |
24275 | backslashes, so that they can be interpreted by Perl to specify characters | |
24276 | whose code value is zero. | |
24277 | ||
24278 | Warning 1: If either of the user or password strings starts with an octal | |
24279 | digit, you must use three zeros instead of one after the leading backslash. If | |
24280 | you do not, the octal digit that starts your string will be incorrectly | |
24281 | interpreted as part of the code for the first character. | |
24282 | ||
24283 | Warning 2: If there are characters in the strings that Perl interprets | |
24284 | specially, you must use a Perl escape to prevent them being misinterpreted. For | |
24285 | example, a command such as | |
24286 | ||
24287 | encode '\0user@domain.com\0pas$$word' | |
24288 | ||
24289 | gives an incorrect answer because of the unescaped "@" and "$" characters. | |
24290 | ||
24291 | If you have the mimencode command installed, another way to do produce | |
24292 | base64-encoded strings is to run the command | |
24293 | ||
24294 | echo -e -n `\0user\0password' | mimencode | |
24295 | ||
24296 | The -e option of echo enables the interpretation of backslash escapes in the | |
24297 | argument, and the -n option specifies no newline at the end of its output. | |
24298 | However, not all versions of echo recognize these options, so you should check | |
24299 | your version before relying on this suggestion. | |
24300 | ||
24301 | ||
24302 | 33.5 Authentication by an Exim client | |
24303 | ------------------------------------- | |
24304 | ||
24305 | The smtp transport has two options called hosts_require_auth and hosts_try_auth | |
24306 | . When the smtp transport connects to a server that announces support for | |
24307 | authentication, and the host matches an entry in either of these options, Exim | |
24308 | (as a client) tries to authenticate as follows: | |
24309 | ||
24310 | * For each authenticator that is configured as a client, in the order in | |
24311 | which they are defined in the configuration, it searches the authentication | |
24312 | mechanisms announced by the server for one whose name matches the public | |
24313 | name of the authenticator. | |
24314 | ||
24315 | * When it finds one that matches, it runs the authenticator's client code. | |
24316 | The variables $host and $host_address are available for any string | |
24317 | expansions that the client might do. They are set to the server's name and | |
24318 | IP address. If any expansion is forced to fail, the authentication attempt | |
24319 | is abandoned, and Exim moves on to the next authenticator. Otherwise an | |
24320 | expansion failure causes delivery to be deferred. | |
24321 | ||
24322 | * If the result of the authentication attempt is a temporary error or a | |
24323 | timeout, Exim abandons trying to send the message to the host for the | |
24324 | moment. It will try again later. If there are any backup hosts available, | |
24325 | they are tried in the usual way. | |
24326 | ||
24327 | * If the response to authentication is a permanent error (5xx code), Exim | |
24328 | carries on searching the list of authenticators and tries another one if | |
24329 | possible. If all authentication attempts give permanent errors, or if there | |
24330 | are no attempts because no mechanisms match (or option expansions force | |
24331 | failure), what happens depends on whether the host matches | |
24332 | hosts_require_auth or hosts_try_auth. In the first case, a temporary error | |
24333 | is generated, and delivery is deferred. The error can be detected in the | |
24334 | retry rules, and thereby turned into a permanent error if you wish. In the | |
24335 | second case, Exim tries to deliver the message unauthenticated. | |
24336 | ||
2813c06e CE |
24337 | Note that the hostlist test for whether to do authentication can be confused if |
24338 | name-IP lookups change between the time the peer is decided on and the | |
24339 | transport running. For example, with a manualroute router given a host name, | |
24340 | and DNS "round-robin" use by that name: if the local resolver cache times out | |
24341 | between the router and the transport running, the transport may get an IP for | |
24342 | the name for its authentication check which does not match the connection peer | |
24343 | IP. No authentication will then be done, despite the names being identical. | |
24344 | ||
24345 | For such cases use a separate transport which always authenticates. | |
24346 | ||
420a0d19 CE |
24347 | When Exim has authenticated itself to a remote server, it adds the AUTH |
24348 | parameter to the MAIL commands it sends, if it has an authenticated sender for | |
24349 | the message. If the message came from a remote host, the authenticated sender | |
24350 | is the one that was receiving on an incoming MAIL command, provided that the | |
24351 | incoming connection was authenticated and the server_mail_auth condition | |
24352 | allowed the authenticated sender to be retained. If a local process calls Exim | |
24353 | to send a message, the sender address that is built from the login name and | |
24354 | qualify_domain is treated as authenticated. However, if the | |
24355 | authenticated_sender option is set on the smtp transport, it overrides the | |
24356 | authenticated sender that was received with the message. | |
24357 | ||
24358 | ||
24359 | ||
24360 | =============================================================================== | |
24361 | 34. THE PLAINTEXT AUTHENTICATOR | |
24362 | ||
24363 | The plaintext authenticator can be configured to support the PLAIN and LOGIN | |
24364 | authentication mechanisms, both of which transfer authentication data as plain | |
24365 | (unencrypted) text (though base64 encoded). The use of plain text is a security | |
24366 | risk; you are strongly advised to insist on the use of SMTP encryption (see | |
2813c06e | 24367 | chapter 42) if you use the PLAIN or LOGIN mechanisms. If you do use unencrypted |
420a0d19 CE |
24368 | plain text, you should not use the same passwords for SMTP connections as you |
24369 | do for login accounts. | |
24370 | ||
24371 | ||
24372 | 34.1 Plaintext options | |
24373 | ---------------------- | |
24374 | ||
24375 | When configured as a server, plaintext uses the following options: | |
24376 | ||
2813c06e | 24377 | +-----------------------------------------------------------------+ |
420a0d19 | 24378 | |server_condition|Use: authenticators|Type: string*|Default: unset| |
2813c06e | 24379 | +-----------------------------------------------------------------+ |
420a0d19 CE |
24380 | |
24381 | This is actually a global authentication option, but it must be set in order to | |
24382 | configure the plaintext driver as a server. Its use is described below. | |
24383 | ||
2813c06e | 24384 | +----------------------------------------------------------+ |
420a0d19 | 24385 | |server_prompts|Use: plaintext|Type: string*|Default: unset| |
2813c06e | 24386 | +----------------------------------------------------------+ |
420a0d19 CE |
24387 | |
24388 | The contents of this option, after expansion, must be a colon-separated list of | |
24389 | prompt strings. If expansion fails, a temporary authentication rejection is | |
24390 | given. | |
24391 | ||
24392 | ||
24393 | 34.2 Using plaintext in a server | |
24394 | -------------------------------- | |
24395 | ||
24396 | When running as a server, plaintext performs the authentication test by | |
24397 | expanding a string. The data sent by the client with the AUTH command, or in | |
24398 | response to subsequent prompts, is base64 encoded, and so may contain any byte | |
24399 | values when decoded. If any data is supplied with the command, it is treated as | |
24400 | a list of strings, separated by NULs (binary zeros), the first three of which | |
24401 | are placed in the expansion variables $auth1, $auth2, and $auth3 (neither LOGIN | |
24402 | nor PLAIN uses more than three strings). | |
24403 | ||
24404 | For compatibility with previous releases of Exim, the values are also placed in | |
24405 | the expansion variables $1, $2, and $3. However, the use of these variables for | |
24406 | this purpose is now deprecated, as it can lead to confusion in string | |
24407 | expansions that also use them for other things. | |
24408 | ||
24409 | If there are more strings in server_prompts than the number of strings supplied | |
24410 | with the AUTH command, the remaining prompts are used to obtain more data. Each | |
24411 | response from the client may be a list of NUL-separated strings. | |
24412 | ||
24413 | Once a sufficient number of data strings have been received, server_condition | |
24414 | is expanded. If the expansion is forced to fail, authentication fails. Any | |
24415 | other expansion failure causes a temporary error code to be returned. If the | |
24416 | result of a successful expansion is an empty string, "0", "no", or "false", | |
24417 | authentication fails. If the result of the expansion is "1", "yes", or "true", | |
24418 | authentication succeeds and the generic server_set_id option is expanded and | |
24419 | saved in $authenticated_id. For any other result, a temporary error code is | |
24420 | returned, with the expanded string as the error text | |
24421 | ||
24422 | Warning: If you use a lookup in the expansion to find the user's password, be | |
24423 | sure to make the authentication fail if the user is unknown. There are good and | |
24424 | bad examples at the end of the next section. | |
24425 | ||
24426 | ||
24427 | 34.3 The PLAIN authentication mechanism | |
24428 | --------------------------------------- | |
24429 | ||
24430 | The PLAIN authentication mechanism (RFC 2595) specifies that three strings be | |
24431 | sent as one item of data (that is, one combined string containing two NUL | |
24432 | separators). The data is sent either as part of the AUTH command, or | |
24433 | subsequently in response to an empty prompt from the server. | |
24434 | ||
24435 | The second and third strings are a user name and a corresponding password. | |
24436 | Using a single fixed user name and password as an example, this could be | |
24437 | configured as follows: | |
24438 | ||
24439 | fixed_plain: | |
24440 | driver = plaintext | |
24441 | public_name = PLAIN | |
24442 | server_prompts = : | |
24443 | server_condition = \ | |
24444 | ${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}} | |
24445 | server_set_id = $auth2 | |
24446 | ||
24447 | Note that the default result strings from if ("true" or an empty string) are | |
24448 | exactly what we want here, so they need not be specified. Obviously, if the | |
24449 | password contains expansion-significant characters such as dollar, backslash, | |
24450 | or closing brace, they have to be escaped. | |
24451 | ||
24452 | The server_prompts setting specifies a single, empty prompt (empty items at the | |
24453 | end of a string list are ignored). If all the data comes as part of the AUTH | |
24454 | command, as is commonly the case, the prompt is not used. This authenticator is | |
24455 | advertised in the response to EHLO as | |
24456 | ||
24457 | 250-AUTH PLAIN | |
24458 | ||
24459 | and a client host can authenticate itself by sending the command | |
24460 | ||
24461 | AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0 | |
24462 | ||
24463 | As this contains three strings (more than the number of prompts), no further | |
24464 | data is required from the client. Alternatively, the client may just send | |
24465 | ||
24466 | AUTH PLAIN | |
24467 | ||
24468 | to initiate authentication, in which case the server replies with an empty | |
24469 | prompt. The client must respond with the combined data string. | |
24470 | ||
24471 | The data string is base64 encoded, as required by the RFC. This example, when | |
24472 | decoded, is <NUL>"username"<NUL>"mysecret", where <NUL> represents a zero byte. | |
24473 | This is split up into three strings, the first of which is empty. The | |
24474 | server_condition option in the authenticator checks that the second two are | |
24475 | "username" and "mysecret" respectively. | |
24476 | ||
24477 | Having just one fixed user name and password, as in this example, is not very | |
24478 | realistic, though for a small organization with only a handful of | |
24479 | authenticating clients it could make sense. | |
24480 | ||
24481 | A more sophisticated instance of this authenticator could use the user name in | |
24482 | $auth2 to look up a password in a file or database, and maybe do an encrypted | |
24483 | comparison (see crypteq in chapter 11). Here is a example of this approach, | |
24484 | where the passwords are looked up in a DBM file. Warning: This is an incorrect | |
24485 | example: | |
24486 | ||
24487 | server_condition = \ | |
24488 | ${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}} | |
24489 | ||
24490 | The expansion uses the user name ($auth2) as the key to look up a password, | |
24491 | which it then compares to the supplied password ($auth3). Why is this example | |
24492 | incorrect? It works fine for existing users, but consider what happens if a | |
24493 | non-existent user name is given. The lookup fails, but as no success/failure | |
24494 | strings are given for the lookup, it yields an empty string. Thus, to defeat | |
24495 | the authentication, all a client has to do is to supply a non-existent user | |
24496 | name and an empty password. The correct way of writing this test is: | |
24497 | ||
24498 | server_condition = ${lookup{$auth2}dbm{/etc/authpwd}\ | |
24499 | {${if eq{$value}{$auth3}}} {false}} | |
24500 | ||
24501 | In this case, if the lookup succeeds, the result is checked; if the lookup | |
24502 | fails, "false" is returned and authentication fails. If crypteq is being used | |
24503 | instead of eq, the first example is in fact safe, because crypteq always fails | |
24504 | if its second argument is empty. However, the second way of writing the test | |
24505 | makes the logic clearer. | |
24506 | ||
24507 | ||
24508 | 34.4 The LOGIN authentication mechanism | |
24509 | --------------------------------------- | |
24510 | ||
24511 | The LOGIN authentication mechanism is not documented in any RFC, but is in use | |
24512 | in a number of programs. No data is sent with the AUTH command. Instead, a user | |
24513 | name and password are supplied separately, in response to prompts. The | |
24514 | plaintext authenticator can be configured to support this as in this example: | |
24515 | ||
24516 | fixed_login: | |
24517 | driver = plaintext | |
24518 | public_name = LOGIN | |
24519 | server_prompts = User Name : Password | |
24520 | server_condition = \ | |
24521 | ${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}} | |
24522 | server_set_id = $auth1 | |
24523 | ||
24524 | Because of the way plaintext operates, this authenticator accepts data supplied | |
24525 | with the AUTH command (in contravention of the specification of LOGIN), but if | |
24526 | the client does not supply it (as is the case for LOGIN clients), the prompt | |
24527 | strings are used to obtain two data items. | |
24528 | ||
24529 | Some clients are very particular about the precise text of the prompts. For | |
24530 | example, Outlook Express is reported to recognize only "Username:" and | |
24531 | "Password:". Here is an example of a LOGIN authenticator that uses those | |
24532 | strings. It uses the ldapauth expansion condition to check the user name and | |
24533 | password by binding to an LDAP server: | |
24534 | ||
24535 | login: | |
24536 | driver = plaintext | |
24537 | public_name = LOGIN | |
24538 | server_prompts = Username:: : Password:: | |
24539 | server_condition = ${if and{{ \ | |
24540 | !eq{}{$auth1} }{ \ | |
24541 | ldapauth{\ | |
24542 | user="uid=${quote_ldap_dn:$auth1},ou=people,o=example.org" \ | |
24543 | pass=${quote:$auth2} \ | |
24544 | ldap://ldap.example.org/} }} } | |
24545 | server_set_id = uid=$auth1,ou=people,o=example.org | |
24546 | ||
24547 | We have to check that the username is not empty before using it, because LDAP | |
24548 | does not permit empty DN components. We must also use the quote_ldap_dn | |
24549 | operator to correctly quote the DN for authentication. However, the basic quote | |
24550 | operator, rather than any of the LDAP quoting operators, is the correct one to | |
24551 | use for the password, because quoting is needed only to make the password | |
24552 | conform to the Exim syntax. At the LDAP level, the password is an uninterpreted | |
24553 | string. | |
24554 | ||
24555 | ||
24556 | 34.5 Support for different kinds of authentication | |
24557 | -------------------------------------------------- | |
24558 | ||
24559 | A number of string expansion features are provided for the purpose of | |
24560 | interfacing to different ways of user authentication. These include checking | |
24561 | traditionally encrypted passwords from /etc/passwd (or equivalent), PAM, | |
24562 | Radius, ldapauth, pwcheck, and saslauthd. For details see section 11.7. | |
24563 | ||
24564 | ||
24565 | 34.6 Using plaintext in a client | |
24566 | -------------------------------- | |
24567 | ||
24568 | The plaintext authenticator has two client options: | |
24569 | ||
2813c06e | 24570 | +------------------------------------------------------------------------+ |
420a0d19 | 24571 | |client_ignore_invalid_base64|Use: plaintext|Type: boolean|Default: false| |
2813c06e | 24572 | +------------------------------------------------------------------------+ |
420a0d19 CE |
24573 | |
24574 | If the client receives a server prompt that is not a valid base64 string, | |
24575 | authentication is abandoned by default. However, if this option is set true, | |
24576 | the error in the challenge is ignored and the client sends the response as | |
24577 | usual. | |
24578 | ||
2813c06e | 24579 | +-------------------------------------------------------+ |
420a0d19 | 24580 | |client_send|Use: plaintext|Type: string*|Default: unset| |
2813c06e | 24581 | +-------------------------------------------------------+ |
420a0d19 CE |
24582 | |
24583 | The string is a colon-separated list of authentication data strings. Each | |
24584 | string is independently expanded before being sent to the server. The first | |
24585 | string is sent with the AUTH command; any more strings are sent in response to | |
24586 | prompts from the server. Before each string is expanded, the value of the most | |
24587 | recent prompt is placed in the next $auth<n> variable, starting with $auth1 for | |
24588 | the first prompt. Up to three prompts are stored in this way. Thus, the prompt | |
24589 | that is received in response to sending the first string (with the AUTH | |
24590 | command) can be used in the expansion of the second string, and so on. If an | |
24591 | invalid base64 string is received when client_ignore_invalid_base64 is set, an | |
24592 | empty string is put in the $auth<n> variable. | |
24593 | ||
24594 | Note: You cannot use expansion to create multiple strings, because splitting | |
24595 | takes priority and happens first. | |
24596 | ||
24597 | Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in | |
24598 | the data, further processing is applied to each string before it is sent. If | |
24599 | there are any single circumflex characters in the string, they are converted to | |
24600 | NULs. Should an actual circumflex be required as data, it must be doubled in | |
24601 | the string. | |
24602 | ||
24603 | This is an example of a client configuration that implements the PLAIN | |
24604 | authentication mechanism with a fixed user name and password: | |
24605 | ||
24606 | fixed_plain: | |
24607 | driver = plaintext | |
24608 | public_name = PLAIN | |
24609 | client_send = ^username^mysecret | |
24610 | ||
24611 | The lack of colons means that the entire text is sent with the AUTH command, | |
24612 | with the circumflex characters converted to NULs. A similar example that uses | |
24613 | the LOGIN mechanism is: | |
24614 | ||
24615 | fixed_login: | |
24616 | driver = plaintext | |
24617 | public_name = LOGIN | |
24618 | client_send = : username : mysecret | |
24619 | ||
24620 | The initial colon means that the first string is empty, so no data is sent with | |
24621 | the AUTH command itself. The remaining strings are sent in response to prompts. | |
24622 | ||
24623 | ||
24624 | ||
24625 | =============================================================================== | |
24626 | 35. THE CRAM_MD5 AUTHENTICATOR | |
24627 | ||
24628 | The CRAM-MD5 authentication mechanism is described in RFC 2195. The server | |
24629 | sends a challenge string to the client, and the response consists of a user | |
24630 | name and the CRAM-MD5 digest of the challenge string combined with a secret | |
24631 | string (password) which is known to both server and client. Thus, the secret is | |
24632 | not sent over the network as plain text, which makes this authenticator more | |
24633 | secure than plaintext. However, the downside is that the secret has to be | |
24634 | available in plain text at either end. | |
24635 | ||
24636 | ||
24637 | 35.1 Using cram_md5 as a server | |
24638 | ------------------------------- | |
24639 | ||
24640 | This authenticator has one server option, which must be set to configure the | |
24641 | authenticator as a server: | |
24642 | ||
2813c06e | 24643 | +--------------------------------------------------------+ |
420a0d19 | 24644 | |server_secret|Use: cram_md5|Type: string*|Default: unset| |
2813c06e | 24645 | +--------------------------------------------------------+ |
420a0d19 CE |
24646 | |
24647 | When the server receives the client's response, the user name is placed in the | |
24648 | expansion variable $auth1, and server_secret is expanded to obtain the password | |
24649 | for that user. The server then computes the CRAM-MD5 digest that the client | |
24650 | should have sent, and checks that it received the correct string. If the | |
24651 | expansion of server_secret is forced to fail, authentication fails. If the | |
24652 | expansion fails for some other reason, a temporary error code is returned to | |
24653 | the client. | |
24654 | ||
24655 | For compatibility with previous releases of Exim, the user name is also placed | |
24656 | in $1. However, the use of this variables for this purpose is now deprecated, | |
24657 | as it can lead to confusion in string expansions that also use numeric | |
24658 | variables for other things. | |
24659 | ||
24660 | For example, the following authenticator checks that the user name given by the | |
24661 | client is "ph10", and if so, uses "secret" as the password. For any other user | |
24662 | name, authentication fails. | |
24663 | ||
24664 | fixed_cram: | |
24665 | driver = cram_md5 | |
24666 | public_name = CRAM-MD5 | |
24667 | server_secret = ${if eq{$auth1}{ph10}{secret}fail} | |
24668 | server_set_id = $auth1 | |
24669 | ||
24670 | If authentication succeeds, the setting of server_set_id preserves the user | |
24671 | name in $authenticated_id. A more typical configuration might look up the | |
24672 | secret string in a file, using the user name as the key. For example: | |
24673 | ||
24674 | lookup_cram: | |
24675 | driver = cram_md5 | |
24676 | public_name = CRAM-MD5 | |
24677 | server_secret = ${lookup{$auth1}lsearch{/etc/authpwd}\ | |
24678 | {$value}fail} | |
24679 | server_set_id = $auth1 | |
24680 | ||
24681 | Note that this expansion explicitly forces failure if the lookup fails because | |
24682 | $auth1 contains an unknown user name. | |
24683 | ||
24684 | As another example, if you wish to re-use a Cyrus SASL sasldb2 file without | |
24685 | using the relevant libraries, you need to know the realm to specify in the | |
24686 | lookup and then ask for the "userPassword" attribute for that user in that | |
24687 | realm, with: | |
24688 | ||
24689 | cyrusless_crammd5: | |
24690 | driver = cram_md5 | |
24691 | public_name = CRAM-MD5 | |
24692 | server_secret = ${lookup{$auth1:mail.example.org:userPassword}\ | |
2813c06e | 24693 | dbmjz{/etc/sasldb2}{$value}fail} |
420a0d19 CE |
24694 | server_set_id = $auth1 |
24695 | ||
24696 | ||
24697 | 35.2 Using cram_md5 as a client | |
24698 | ------------------------------- | |
24699 | ||
24700 | When used as a client, the cram_md5 authenticator has two options: | |
24701 | ||
2813c06e | 24702 | +----------------------------------------------------------------------+ |
420a0d19 | 24703 | |client_name|Use: cram_md5|Type: string*|Default: the primary host name| |
2813c06e | 24704 | +----------------------------------------------------------------------+ |
420a0d19 CE |
24705 | |
24706 | This string is expanded, and the result used as the user name data when | |
24707 | computing the response to the server's challenge. | |
24708 | ||
2813c06e | 24709 | +--------------------------------------------------------+ |
420a0d19 | 24710 | |client_secret|Use: cram_md5|Type: string*|Default: unset| |
2813c06e | 24711 | +--------------------------------------------------------+ |
420a0d19 CE |
24712 | |
24713 | This option must be set for the authenticator to work as a client. Its value is | |
24714 | expanded and the result used as the secret string when computing the response. | |
24715 | ||
24716 | Different user names and secrets can be used for different servers by referring | |
24717 | to $host or $host_address in the options. Forced failure of either expansion | |
24718 | string is treated as an indication that this authenticator is not prepared to | |
24719 | handle this case. Exim moves on to the next configured client authenticator. | |
24720 | Any other expansion failure causes Exim to give up trying to send the message | |
24721 | to the current server. | |
24722 | ||
24723 | A simple example configuration of a cram_md5 authenticator, using fixed | |
24724 | strings, is: | |
24725 | ||
24726 | fixed_cram: | |
24727 | driver = cram_md5 | |
24728 | public_name = CRAM-MD5 | |
24729 | client_name = ph10 | |
24730 | client_secret = secret | |
24731 | ||
24732 | ||
24733 | ||
24734 | =============================================================================== | |
24735 | 36. THE CYRUS_SASL AUTHENTICATOR | |
24736 | ||
24737 | The code for this authenticator was provided by Matthew Byng-Maddick of A L | |
24738 | Digital Ltd (http://www.aldigital.co.uk). | |
24739 | ||
24740 | The cyrus_sasl authenticator provides server support for the Cyrus SASL library | |
24741 | implementation of the RFC 2222 ("Simple Authentication and Security Layer"). | |
24742 | This library supports a number of authentication mechanisms, including PLAIN | |
24743 | and LOGIN, but also several others that Exim does not support directly. In | |
24744 | particular, there is support for Kerberos authentication. | |
24745 | ||
24746 | The cyrus_sasl authenticator provides a gatewaying mechanism directly to the | |
24747 | Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5, then | |
24748 | so can the cyrus_sasl authenticator. By default it uses the public name of the | |
24749 | driver to determine which mechanism to support. | |
24750 | ||
24751 | Where access to some kind of secret file is required, for example in GSSAPI or | |
24752 | CRAM-MD5, it is worth noting that the authenticator runs as the Exim user, and | |
24753 | that the Cyrus SASL library has no way of escalating privileges by default. You | |
24754 | may also find you need to set environment variables, depending on the driver | |
24755 | you are using. | |
24756 | ||
24757 | The application name provided by Exim is "exim", so various SASL options may be | |
24758 | set in exim.conf in your SASL directory. If you are using GSSAPI for Kerberos, | |
24759 | note that because of limitations in the GSSAPI interface, changing the server | |
24760 | keytab might need to be communicated down to the Kerberos layer independently. | |
24761 | The mechanism for doing so is dependent upon the Kerberos implementation. | |
24762 | ||
24763 | For example, for older releases of Heimdal, the environment variable | |
24764 | KRB5_KTNAME may be set to point to an alternative keytab file. Exim will pass | |
24765 | this variable through from its own inherited environment when started as root | |
24766 | or the Exim user. The keytab file needs to be readable by the Exim user. With | |
24767 | newer releases of Heimdal, a setuid Exim may cause Heimdal to discard the | |
24768 | environment variable. In practice, for those releases, the Cyrus authenticator | |
24769 | is not a suitable interface for GSSAPI (Kerberos) support. Instead, consider | |
24770 | the heimdal_gssapi authenticator, described in chapter 39 | |
24771 | ||
24772 | ||
24773 | 36.1 Using cyrus_sasl as a server | |
24774 | --------------------------------- | |
24775 | ||
24776 | The cyrus_sasl authenticator has four private options. It puts the username (on | |
24777 | a successful authentication) into $auth1. For compatibility with previous | |
24778 | releases of Exim, the username is also placed in $1. However, the use of this | |
24779 | variable for this purpose is now deprecated, as it can lead to confusion in | |
24780 | string expansions that also use numeric variables for other things. | |
24781 | ||
2813c06e | 24782 | +----------------------------------------------------------------+ |
420a0d19 | 24783 | |server_hostname|Use: cyrus_sasl|Type: string*|Default: see below| |
2813c06e | 24784 | +----------------------------------------------------------------+ |
420a0d19 CE |
24785 | |
24786 | This option selects the hostname that is used when communicating with the | |
24787 | library. The default value is "$primary_hostname". It is up to the underlying | |
24788 | SASL plug-in what it does with this data. | |
24789 | ||
2813c06e | 24790 | +-----------------------------------------------------------+ |
420a0d19 | 24791 | |server_mech|Use: cyrus_sasl|Type: string|Default: see below| |
2813c06e | 24792 | +-----------------------------------------------------------+ |
420a0d19 CE |
24793 | |
24794 | This option selects the authentication mechanism this driver should use. The | |
24795 | default is the value of the generic public_name option. This option allows you | |
24796 | to use a different underlying mechanism from the advertised name. For example: | |
24797 | ||
24798 | sasl: | |
24799 | driver = cyrus_sasl | |
24800 | public_name = X-ANYTHING | |
24801 | server_mech = CRAM-MD5 | |
24802 | server_set_id = $auth1 | |
24803 | ||
2813c06e | 24804 | +---------------------------------------------------------+ |
420a0d19 | 24805 | |server_realm|Use: cyrus_sasl|Type: string*|Default: unset| |
2813c06e | 24806 | +---------------------------------------------------------+ |
420a0d19 CE |
24807 | |
24808 | This specifies the SASL realm that the server claims to be in. | |
24809 | ||
2813c06e | 24810 | +-----------------------------------------------------------+ |
420a0d19 | 24811 | |server_service|Use: cyrus_sasl|Type: string|Default: "smtp"| |
2813c06e | 24812 | +-----------------------------------------------------------+ |
420a0d19 CE |
24813 | |
24814 | This is the SASL service that the server claims to implement. | |
24815 | ||
24816 | For straightforward cases, you do not need to set any of the authenticator's | |
24817 | private options. All you need to do is to specify an appropriate mechanism as | |
24818 | the public name. Thus, if you have a SASL library that supports CRAM-MD5 and | |
24819 | PLAIN, you could have two authenticators as follows: | |
24820 | ||
24821 | sasl_cram_md5: | |
24822 | driver = cyrus_sasl | |
24823 | public_name = CRAM-MD5 | |
24824 | server_set_id = $auth1 | |
24825 | ||
24826 | sasl_plain: | |
24827 | driver = cyrus_sasl | |
24828 | public_name = PLAIN | |
24829 | server_set_id = $auth2 | |
24830 | ||
24831 | Cyrus SASL does implement the LOGIN authentication method, even though it is | |
24832 | not a standard method. It is disabled by default in the source distribution, | |
24833 | but it is present in many binary distributions. | |
24834 | ||
24835 | ||
24836 | ||
24837 | =============================================================================== | |
24838 | 37. THE DOVECOT AUTHENTICATOR | |
24839 | ||
24840 | This authenticator is an interface to the authentication facility of the | |
24841 | Dovecot POP/IMAP server, which can support a number of authentication methods. | |
2813c06e CE |
24842 | Note that Dovecot must be configured to use auth-client not auth-userdb. If you |
24843 | are using Dovecot to authenticate POP/IMAP clients, it might be helpful to use | |
24844 | the same mechanisms for SMTP authentication. This is a server authenticator | |
24845 | only. There is only one option: | |
420a0d19 | 24846 | |
2813c06e | 24847 | +------------------------------------------------------+ |
420a0d19 | 24848 | |server_socket|Use: dovecot|Type: string|Default: unset| |
2813c06e | 24849 | +------------------------------------------------------+ |
420a0d19 CE |
24850 | |
24851 | This option must specify the socket that is the interface to Dovecot | |
24852 | authentication. The public_name option must specify an authentication mechanism | |
24853 | that Dovecot is configured to support. You can have several authenticators for | |
24854 | different mechanisms. For example: | |
24855 | ||
24856 | dovecot_plain: | |
24857 | driver = dovecot | |
24858 | public_name = PLAIN | |
24859 | server_socket = /var/run/dovecot/auth-client | |
24860 | server_set_id = $auth1 | |
24861 | ||
24862 | dovecot_ntlm: | |
24863 | driver = dovecot | |
24864 | public_name = NTLM | |
24865 | server_socket = /var/run/dovecot/auth-client | |
24866 | server_set_id = $auth1 | |
24867 | ||
24868 | If the SMTP connection is encrypted, or if $sender_host_address is equal to | |
24869 | $received_ip_address (that is, the connection is local), the "secured" option | |
24870 | is passed in the Dovecot authentication command. If, for a TLS connection, a | |
24871 | client certificate has been verified, the "valid-client-cert" option is passed. | |
24872 | When authentication succeeds, the identity of the user who authenticated is | |
24873 | placed in $auth1. | |
24874 | ||
24875 | ||
24876 | ||
24877 | =============================================================================== | |
24878 | 38. THE GSASL AUTHENTICATOR | |
24879 | ||
24880 | The gsasl authenticator provides server integration for the GNU SASL library | |
24881 | and the mechanisms it provides. This is new as of the 4.80 release and there | |
24882 | are a few areas where the library does not let Exim smoothly scale to handle | |
24883 | future authentication mechanisms, so no guarantee can be made that any | |
24884 | particular new authentication mechanism will be supported without code changes | |
24885 | in Exim. | |
24886 | ||
2813c06e | 24887 | +-------------------------------------------------------------+ |
420a0d19 | 24888 | |server_channelbinding|Use: gsasl|Type: boolean|Default: false| |
2813c06e | 24889 | +-------------------------------------------------------------+ |
420a0d19 CE |
24890 | |
24891 | Some authentication mechanisms are able to use external context at both ends of | |
24892 | the session to bind the authentication to that context, and fail the | |
24893 | authentication process if that context differs. Specifically, some TLS | |
24894 | ciphersuites can provide identifying information about the cryptographic | |
24895 | context. | |
24896 | ||
24897 | This means that certificate identity and verification becomes a non-issue, as a | |
24898 | man-in-the-middle attack will cause the correct client and server to see | |
24899 | different identifiers and authentication will fail. | |
24900 | ||
24901 | This is currently only supported when using the GnuTLS library. This is only | |
24902 | usable by mechanisms which support "channel binding"; at time of writing, | |
24903 | that's the SCRAM family. | |
24904 | ||
24905 | This defaults off to ensure smooth upgrade across Exim releases, in case this | |
24906 | option causes some clients to start failing. Some future release of Exim may | |
24907 | switch the default to be true. | |
24908 | ||
2813c06e | 24909 | +-----------------------------------------------------------+ |
420a0d19 | 24910 | |server_hostname|Use: gsasl|Type: string*|Default: see below| |
2813c06e | 24911 | +-----------------------------------------------------------+ |
420a0d19 CE |
24912 | |
24913 | This option selects the hostname that is used when communicating with the | |
24914 | library. The default value is "$primary_hostname". Some mechanisms will use | |
24915 | this data. | |
24916 | ||
2813c06e | 24917 | +------------------------------------------------------+ |
420a0d19 | 24918 | |server_mech|Use: gsasl|Type: string|Default: see below| |
2813c06e | 24919 | +------------------------------------------------------+ |
420a0d19 CE |
24920 | |
24921 | This option selects the authentication mechanism this driver should use. The | |
24922 | default is the value of the generic public_name option. This option allows you | |
24923 | to use a different underlying mechanism from the advertised name. For example: | |
24924 | ||
24925 | sasl: | |
24926 | driver = gsasl | |
24927 | public_name = X-ANYTHING | |
24928 | server_mech = CRAM-MD5 | |
24929 | server_set_id = $auth1 | |
24930 | ||
2813c06e | 24931 | +-------------------------------------------------------+ |
420a0d19 | 24932 | |server_password|Use: gsasl|Type: string*|Default: unset| |
2813c06e | 24933 | +-------------------------------------------------------+ |
420a0d19 CE |
24934 | |
24935 | Various mechanisms need access to the cleartext password on the server, so that | |
24936 | proof-of-possession can be demonstrated on the wire, without sending the | |
24937 | password itself. | |
24938 | ||
24939 | The data available for lookup varies per mechanism. In all cases, $auth1 is set | |
24940 | to the authentication id. The $auth2 variable will always be the authorization | |
24941 | id (authz) if available, else the empty string. The $auth3 variable will always | |
24942 | be the realm if available, else the empty string. | |
24943 | ||
24944 | A forced failure will cause authentication to defer. | |
24945 | ||
24946 | If using this option, it may make sense to set the server_condition option to | |
24947 | be simply "true". | |
24948 | ||
2813c06e | 24949 | +----------------------------------------------------+ |
420a0d19 | 24950 | |server_realm|Use: gsasl|Type: string*|Default: unset| |
2813c06e | 24951 | +----------------------------------------------------+ |
420a0d19 CE |
24952 | |
24953 | This specifies the SASL realm that the server claims to be in. Some mechanisms | |
24954 | will use this data. | |
24955 | ||
2813c06e | 24956 | +---------------------------------------------------------+ |
420a0d19 | 24957 | |server_scram_iter|Use: gsasl|Type: string*|Default: unset| |
2813c06e | 24958 | +---------------------------------------------------------+ |
420a0d19 CE |
24959 | |
24960 | This option provides data for the SCRAM family of mechanisms. $auth1 is not | |
24961 | available at evaluation time. (This may change, as we receive feedback on use) | |
24962 | ||
2813c06e | 24963 | +---------------------------------------------------------+ |
420a0d19 | 24964 | |server_scram_salt|Use: gsasl|Type: string*|Default: unset| |
2813c06e | 24965 | +---------------------------------------------------------+ |
420a0d19 CE |
24966 | |
24967 | This option provides data for the SCRAM family of mechanisms. $auth1 is not | |
24968 | available at evaluation time. (This may change, as we receive feedback on use) | |
24969 | ||
2813c06e | 24970 | +------------------------------------------------------+ |
420a0d19 | 24971 | |server_service|Use: gsasl|Type: string|Default: "smtp"| |
2813c06e | 24972 | +------------------------------------------------------+ |
420a0d19 CE |
24973 | |
24974 | This is the SASL service that the server claims to implement. Some mechanisms | |
24975 | will use this data. | |
24976 | ||
24977 | ||
24978 | 38.1 gsasl auth variables | |
24979 | ------------------------- | |
24980 | ||
24981 | These may be set when evaluating specific options, as detailed above. They will | |
24982 | also be set when evaluating server_condition. | |
24983 | ||
24984 | Unless otherwise stated below, the gsasl integration will use the following | |
24985 | meanings for these variables: | |
24986 | ||
24987 | * $auth1: the authentication id | |
24988 | ||
24989 | * $auth2: the authorization id | |
24990 | ||
24991 | * $auth3: the realm | |
24992 | ||
24993 | On a per-mechanism basis: | |
24994 | ||
24995 | * EXTERNAL: only $auth1 is set, to the possibly empty authorization id; the | |
24996 | server_condition option must be present. | |
24997 | ||
24998 | * ANONYMOUS: only $auth1 is set, to the possibly empty anonymous token; the | |
24999 | server_condition option must be present. | |
25000 | ||
25001 | * GSSAPI: $auth1 will be set to the GSSAPI Display Name; $auth2 will be set | |
25002 | to the authorization id, the server_condition option must be present. | |
25003 | ||
25004 | An anonymous token is something passed along as an unauthenticated identifier; | |
25005 | this is analogous to FTP anonymous authentication passing an email address, or | |
25006 | software-identifier@, as the "password". | |
25007 | ||
25008 | An example showing the password having the realm specified in the callback and | |
25009 | demonstrating a Cyrus SASL to GSASL migration approach is: | |
25010 | ||
25011 | gsasl_cyrusless_crammd5: | |
25012 | driver = gsasl | |
25013 | public_name = CRAM-MD5 | |
25014 | server_realm = imap.example.org | |
25015 | server_password = ${lookup{$auth1:$auth3:userPassword}\ | |
25016 | dbmjz{/etc/sasldb2}{$value}fail} | |
25017 | server_set_id = ${quote:$auth1} | |
25018 | server_condition = yes | |
25019 | ||
25020 | ||
25021 | ||
25022 | =============================================================================== | |
25023 | 39. THE HEIMDAL_GSSAPI AUTHENTICATOR | |
25024 | ||
25025 | The heimdal_gssapi authenticator provides server integration for the Heimdal | |
25026 | GSSAPI/Kerberos library, permitting Exim to set a keytab pathname reliably. | |
25027 | ||
2813c06e | 25028 | +--------------------------------------------------------------------+ |
420a0d19 | 25029 | |server_hostname|Use: heimdal_gssapi|Type: string*|Default: see below| |
2813c06e | 25030 | +--------------------------------------------------------------------+ |
420a0d19 CE |
25031 | |
25032 | This option selects the hostname that is used, with server_service, for | |
25033 | constructing the GSS server name, as a GSS_C_NT_HOSTBASED_SERVICE identifier. | |
25034 | The default value is "$primary_hostname". | |
25035 | ||
2813c06e | 25036 | +--------------------------------------------------------------+ |
420a0d19 | 25037 | |server_keytab|Use: heimdal_gssapi|Type: string*|Default: unset| |
2813c06e | 25038 | +--------------------------------------------------------------+ |
420a0d19 CE |
25039 | |
25040 | If set, then Heimdal will not use the system default keytab (typically /etc/ | |
25041 | krb5.keytab) but instead the pathname given in this option. The value should be | |
25042 | a pathname, with no "file:" prefix. | |
25043 | ||
2813c06e | 25044 | +--------------------------------------------------------------+ |
420a0d19 | 25045 | |server_service|Use: heimdal_gssapi|Type: string*|Default: smtp| |
2813c06e | 25046 | +--------------------------------------------------------------+ |
420a0d19 CE |
25047 | |
25048 | This option specifies the service identifier used, in conjunction with | |
2813c06e | 25049 | server_hostname, for building the identifier for finding credentials from the |
420a0d19 CE |
25050 | keytab. |
25051 | ||
25052 | ||
25053 | 39.1 heimdal_gssapi auth variables | |
25054 | ---------------------------------- | |
25055 | ||
25056 | Beware that these variables will typically include a realm, thus will appear to | |
25057 | be roughly like an email address already. The authzid in $auth2 is not | |
25058 | verified, so a malicious client can set it to anything. | |
25059 | ||
25060 | The $auth1 field should be safely trustable as a value from the Key | |
25061 | Distribution Center. Note that these are not quite email addresses. Each | |
25062 | identifier is for a role, and so the left-hand-side may include a role suffix. | |
25063 | For instance, "joe/admin@EXAMPLE.ORG". | |
25064 | ||
25065 | * $auth1: the authentication id, set to the GSS Display Name. | |
25066 | ||
25067 | * $auth2: the authorization id, sent within SASL encapsulation after | |
25068 | authentication. If that was empty, this will also be set to the GSS Display | |
25069 | Name. | |
25070 | ||
25071 | ||
25072 | ||
25073 | =============================================================================== | |
25074 | 40. THE SPA AUTHENTICATOR | |
25075 | ||
25076 | The spa authenticator provides client support for Microsoft's Secure Password | |
25077 | Authentication mechanism, which is also sometimes known as NTLM (NT LanMan). | |
25078 | The code for client side of this authenticator was contributed by Marc | |
25079 | Prud'hommeaux, and much of it is taken from the Samba project (http:// | |
25080 | www.samba.org). The code for the server side was subsequently contributed by | |
25081 | Tom Kistner. The mechanism works as follows: | |
25082 | ||
25083 | * After the AUTH command has been accepted, the client sends an SPA | |
25084 | authentication request based on the user name and optional domain. | |
25085 | ||
25086 | * The server sends back a challenge. | |
25087 | ||
25088 | * The client builds a challenge response which makes use of the user's | |
25089 | password and sends it to the server, which then accepts or rejects it. | |
25090 | ||
25091 | Encryption is used to protect the password in transit. | |
25092 | ||
25093 | ||
25094 | 40.1 Using spa as a server | |
25095 | -------------------------- | |
25096 | ||
25097 | The spa authenticator has just one server option: | |
25098 | ||
2813c06e | 25099 | +-----------------------------------------------------+ |
420a0d19 | 25100 | |server_password|Use: spa|Type: string*|Default: unset| |
2813c06e | 25101 | +-----------------------------------------------------+ |
420a0d19 CE |
25102 | |
25103 | This option is expanded, and the result must be the cleartext password for the | |
25104 | authenticating user, whose name is at this point in $auth1. For compatibility | |
25105 | with previous releases of Exim, the user name is also placed in $1. However, | |
25106 | the use of this variable for this purpose is now deprecated, as it can lead to | |
25107 | confusion in string expansions that also use numeric variables for other | |
25108 | things. For example: | |
25109 | ||
25110 | spa: | |
25111 | driver = spa | |
25112 | public_name = NTLM | |
25113 | server_password = \ | |
25114 | ${lookup{$auth1}lsearch{/etc/exim/spa_clearpass}{$value}fail} | |
25115 | ||
25116 | If the expansion is forced to fail, authentication fails. Any other expansion | |
25117 | failure causes a temporary error code to be returned. | |
25118 | ||
25119 | ||
25120 | 40.2 Using spa as a client | |
25121 | -------------------------- | |
25122 | ||
25123 | The spa authenticator has the following client options: | |
25124 | ||
2813c06e | 25125 | +---------------------------------------------------+ |
420a0d19 | 25126 | |client_domain|Use: spa|Type: string*|Default: unset| |
2813c06e | 25127 | +---------------------------------------------------+ |
420a0d19 CE |
25128 | |
25129 | This option specifies an optional domain for the authentication. | |
25130 | ||
2813c06e | 25131 | +-----------------------------------------------------+ |
420a0d19 | 25132 | |client_password|Use: spa|Type: string*|Default: unset| |
2813c06e | 25133 | +-----------------------------------------------------+ |
420a0d19 CE |
25134 | |
25135 | This option specifies the user's password, and must be set. | |
25136 | ||
2813c06e | 25137 | +-----------------------------------------------------+ |
420a0d19 | 25138 | |client_username|Use: spa|Type: string*|Default: unset| |
2813c06e | 25139 | +-----------------------------------------------------+ |
420a0d19 CE |
25140 | |
25141 | This option specifies the user name, and must be set. Here is an example of a | |
25142 | configuration of this authenticator for use with the mail servers at msn.com: | |
25143 | ||
25144 | msn: | |
25145 | driver = spa | |
25146 | public_name = MSN | |
25147 | client_username = msn/msn_username | |
25148 | client_password = msn_plaintext_password | |
25149 | client_domain = DOMAIN_OR_UNSET | |
25150 | ||
25151 | ||
25152 | ||
25153 | =============================================================================== | |
2813c06e CE |
25154 | 41. THE TLS AUTHENTICATOR |
25155 | ||
25156 | The tls authenticator provides server support for authentication based on | |
25157 | client certificates. | |
25158 | ||
25159 | It is not an SMTP authentication mechanism and is not advertised by the server | |
25160 | as part of the SMTP EHLO response. It is an Exim authenticator in the sense | |
25161 | that it affects the protocol element of the log line, can be tested for by the | |
25162 | authenticated ACL condition, and can set the $authenticated_id variable. | |
25163 | ||
25164 | The client must present a verifiable certificate, for which it must have been | |
25165 | requested via the tls_verify_hosts or tls_try_verify_hosts main options (see 42 | |
25166 | ). | |
25167 | ||
25168 | If an authenticator of this type is configured it is run before any SMTP-level | |
25169 | communication is done, and can authenticate the connection. If it does, SMTP | |
25170 | authentication is not offered. | |
25171 | ||
25172 | A maximum of one authenticator of this type may be present. | |
25173 | ||
25174 | The tls authenticator has three server options: | |
25175 | ||
25176 | +---------------------------------------------------+ | |
25177 | |server_param1|Use: tls|Type: string*|Default: unset| | |
25178 | +---------------------------------------------------+ | |
25179 | ||
25180 | This option is expanded after the TLS negotiation and the result is placed in | |
25181 | $auth1. If the expansion is forced to fail, authentication fails. Any other | |
25182 | expansion failure causes a temporary error code to be returned. | |
25183 | ||
25184 | +---------------------------------------------------+ | |
25185 | |server_param2|Use: tls|Type: string*|Default: unset| | |
25186 | +---------------------------------------------------+ | |
25187 | ||
25188 | +---------------------------------------------------+ | |
25189 | |server_param3|Use: tls|Type: string*|Default: unset| | |
25190 | +---------------------------------------------------+ | |
25191 | ||
25192 | As above, for $auth2 and $auth3. | |
25193 | ||
25194 | server_param1 may also be spelled server_param. | |
25195 | ||
25196 | Example: | |
25197 | ||
25198 | tls: | |
25199 | driver = tls | |
25200 | server_param1 = ${certextract {subj_altname,mail,>:} \ | |
25201 | {$tls_in_peercert}} | |
25202 | server_condition = ${if forany {$auth1} \ | |
25203 | {!= {0} \ | |
25204 | {${lookup ldap{ldap:///\ | |
25205 | mailname=${quote_ldap_dn:${lc:$item}},\ | |
25206 | ou=users,LDAP_DC?mailid} {$value}{0} \ | |
25207 | } } } } | |
25208 | server_set_id = ${if = {1}{${listcount:$auth1}} {$auth1}{}} | |
25209 | ||
25210 | This accepts a client certificate that is verifiable against any of your | |
25211 | configured trust-anchors (which usually means the full set of public CAs) and | |
25212 | which has a SAN with a good account name. Note that the client cert is on the | |
25213 | wire in-clear, including the SAN, whereas a plaintext SMTP AUTH done inside TLS | |
25214 | is not. | |
25215 | ||
25216 | Note that because authentication is traditionally an SMTP operation, the | |
25217 | authenticated ACL condition cannot be used in a connect- or helo-ACL. | |
25218 | ||
25219 | ||
25220 | ||
25221 | =============================================================================== | |
25222 | 42. ENCRYPTED SMTP CONNECTIONS USING TLS/SSL | |
420a0d19 CE |
25223 | |
25224 | Support for TLS (Transport Layer Security), formerly known as SSL (Secure | |
25225 | Sockets Layer), is implemented by making use of the OpenSSL library or the | |
25226 | GnuTLS library (Exim requires GnuTLS release 1.0 or later). There is no | |
25227 | cryptographic code in the Exim distribution itself for implementing TLS. In | |
25228 | order to use this feature you must install OpenSSL or GnuTLS, and then build a | |
25229 | version of Exim that includes TLS support (see section 4.7). You also need to | |
25230 | understand the basic concepts of encryption at a managerial level, and in | |
25231 | particular, the way that public keys, private keys, and certificates are used. | |
25232 | ||
25233 | RFC 3207 defines how SMTP connections can make use of encryption. Once a | |
25234 | connection is established, the client issues a STARTTLS command. If the server | |
25235 | accepts this, the client and the server negotiate an encryption mechanism. If | |
25236 | the negotiation succeeds, the data that subsequently passes between them is | |
25237 | encrypted. | |
25238 | ||
25239 | Exim's ACLs can detect whether the current SMTP session is encrypted or not, | |
25240 | and if so, what cipher suite is in use, whether the client supplied a | |
25241 | certificate, and whether or not that certificate was verified. This makes it | |
25242 | possible for an Exim server to deny or accept certain commands based on the | |
25243 | encryption state. | |
25244 | ||
25245 | Warning: Certain types of firewall and certain anti-virus products can disrupt | |
25246 | TLS connections. You need to turn off SMTP scanning for these products in order | |
25247 | to get TLS to work. | |
25248 | ||
25249 | ||
2813c06e | 25250 | 42.1 Support for the legacy "ssmtp" (aka "smtps") protocol |
420a0d19 CE |
25251 | ---------------------------------------------------------- |
25252 | ||
25253 | Early implementations of encrypted SMTP used a different TCP port from normal | |
25254 | SMTP, and expected an encryption negotiation to start immediately, instead of | |
25255 | waiting for a STARTTLS command from the client using the standard SMTP port. | |
25256 | The protocol was called "ssmtp" or "smtps", and port 465 was allocated for this | |
25257 | purpose. | |
25258 | ||
25259 | This approach was abandoned when encrypted SMTP was standardized, but there are | |
25260 | still some legacy clients that use it. Exim supports these clients by means of | |
25261 | the tls_on_connect_ports global option. Its value must be a list of port | |
25262 | numbers; the most common use is expected to be: | |
25263 | ||
25264 | tls_on_connect_ports = 465 | |
25265 | ||
25266 | The port numbers specified by this option apply to all SMTP connections, both | |
25267 | via the daemon and via inetd. You still need to specify all the ports that the | |
25268 | daemon uses (by setting daemon_smtp_ports or local_interfaces or the -oX | |
25269 | command line option) because tls_on_connect_ports does not add an extra port - | |
25270 | rather, it specifies different behaviour on a port that is defined elsewhere. | |
25271 | ||
25272 | There is also a -tls-on-connect command line option. This overrides | |
25273 | tls_on_connect_ports; it forces the legacy behaviour for all ports. | |
25274 | ||
25275 | ||
2813c06e | 25276 | 42.2 OpenSSL vs GnuTLS |
420a0d19 CE |
25277 | ---------------------- |
25278 | ||
25279 | The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS | |
25280 | followed later, when the first versions of GnuTLS were released. To build Exim | |
25281 | to use GnuTLS, you need to set | |
25282 | ||
25283 | USE_GNUTLS=yes | |
25284 | ||
25285 | in Local/Makefile, in addition to | |
25286 | ||
25287 | SUPPORT_TLS=yes | |
25288 | ||
25289 | You must also set TLS_LIBS and TLS_INCLUDE appropriately, so that the include | |
25290 | files and libraries for GnuTLS can be found. | |
25291 | ||
25292 | There are some differences in usage when using GnuTLS instead of OpenSSL: | |
25293 | ||
2813c06e CE |
25294 | * The tls_verify_certificates option cannot be the path of a directory for |
25295 | GnuTLS versions before 3.3.6 (for later versions, or OpenSSL, it can be | |
25296 | either). | |
420a0d19 CE |
25297 | |
25298 | * The default value for tls_dhparam differs for historical reasons. | |
25299 | ||
25300 | * Distinguished Name (DN) strings reported by the OpenSSL library use a slash | |
25301 | for separating fields; GnuTLS uses commas, in accordance with RFC 2253. | |
25302 | This affects the value of the $tls_in_peerdn and $tls_out_peerdn variables. | |
25303 | ||
25304 | * OpenSSL identifies cipher suites using hyphens as separators, for example: | |
25305 | DES-CBC3-SHA. GnuTLS historically used underscores, for example: | |
25306 | RSA_ARCFOUR_SHA. What is more, OpenSSL complains if underscores are present | |
25307 | in a cipher list. To make life simpler, Exim changes underscores to hyphens | |
25308 | for OpenSSL and passes the string unchanged to GnuTLS (expecting the | |
25309 | library to handle its own older variants) when processing lists of cipher | |
25310 | suites in the tls_require_ciphers options (the global option and the smtp | |
25311 | transport option). | |
25312 | ||
25313 | * The tls_require_ciphers options operate differently, as described in the | |
2813c06e | 25314 | sections 42.4 and 42.5. |
420a0d19 CE |
25315 | |
25316 | * The tls_dh_min_bits SMTP transport option is only honoured by GnuTLS. When | |
25317 | using OpenSSL, this option is ignored. (If an API is found to let OpenSSL | |
25318 | be configured in this way, let the Exim Maintainers know and we'll likely | |
25319 | use it). | |
25320 | ||
25321 | * Some other recently added features may only be available in one or the | |
25322 | other. This should be documented with the feature. If the documentation | |
25323 | does not explicitly state that the feature is infeasible in the other TLS | |
25324 | implementation, then patches are welcome. | |
25325 | ||
25326 | ||
2813c06e | 25327 | 42.3 GnuTLS parameter computation |
420a0d19 CE |
25328 | --------------------------------- |
25329 | ||
25330 | This section only applies if tls_dhparam is set to "historic" or to an explicit | |
25331 | path; if the latter, then the text about generation still applies, but not the | |
25332 | chosen filename. By default, as of Exim 4.80 a hard-coded D-H prime is used. | |
25333 | See the documentation of tls_dhparam for more information. | |
25334 | ||
25335 | GnuTLS uses D-H parameters that may take a substantial amount of time to | |
25336 | compute. It is unreasonable to re-compute them for every TLS session. | |
25337 | Therefore, Exim keeps this data in a file in its spool directory, called | |
25338 | gnutls-params-NNNN for some value of NNNN, corresponding to the number of bits | |
25339 | requested. The file is owned by the Exim user and is readable only by its | |
25340 | owner. Every Exim process that start up GnuTLS reads the D-H parameters from | |
25341 | this file. If the file does not exist, the first Exim process that needs it | |
25342 | computes the data and writes it to a temporary file which is renamed once it is | |
25343 | complete. It does not matter if several Exim processes do this simultaneously | |
25344 | (apart from wasting a few resources). Once a file is in place, new Exim | |
25345 | processes immediately start using it. | |
25346 | ||
25347 | For maximum security, the parameters that are stored in this file should be | |
25348 | recalculated periodically, the frequency depending on your paranoia level. If | |
25349 | you are avoiding using the fixed D-H primes published in RFCs, then you are | |
25350 | concerned about some advanced attacks and will wish to do this; if you do not | |
25351 | regenerate then you might as well stick to the standard primes. | |
25352 | ||
25353 | Arranging this is easy in principle; just delete the file when you want new | |
25354 | values to be computed. However, there may be a problem. The calculation of new | |
25355 | parameters needs random numbers, and these are obtained from /dev/random. If | |
25356 | the system is not very active, /dev/random may delay returning data until | |
25357 | enough randomness (entropy) is available. This may cause Exim to hang for a | |
25358 | substantial amount of time, causing timeouts on incoming connections. | |
25359 | ||
25360 | The solution is to generate the parameters externally to Exim. They are stored | |
25361 | in gnutls-params-N in PEM format, which means that they can be generated | |
25362 | externally using the certtool command that is part of GnuTLS. | |
25363 | ||
25364 | To replace the parameters with new ones, instead of deleting the file and | |
25365 | letting Exim re-create it, you can generate new parameters using certtool and, | |
25366 | when this has been done, replace Exim's cache file by renaming. The relevant | |
25367 | commands are something like this: | |
25368 | ||
25369 | # ls | |
25370 | [ look for file; assume gnutls-params-2236 is the most recent ] | |
25371 | # rm -f new-params | |
25372 | # touch new-params | |
25373 | # chown exim:exim new-params | |
25374 | # chmod 0600 new-params | |
25375 | # certtool --generate-dh-params --bits 2236 >>new-params | |
25376 | # openssl dhparam -noout -text -in new-params | head | |
25377 | [ check the first line, make sure it's not more than 2236; | |
25378 | if it is, then go back to the start ("rm") and repeat | |
25379 | until the size generated is at most the size requested ] | |
25380 | # chmod 0400 new-params | |
25381 | # mv new-params gnutls-params-2236 | |
25382 | ||
25383 | If Exim never has to generate the parameters itself, the possibility of | |
25384 | stalling is removed. | |
25385 | ||
25386 | The filename changed in Exim 4.80, to gain the -bits suffix. The value which | |
25387 | Exim will choose depends upon the version of GnuTLS in use. For older GnuTLS, | |
25388 | the value remains hard-coded in Exim as 1024. As of GnuTLS 2.12.x, there is a | |
25389 | way for Exim to ask for the "normal" number of bits for D-H public-key usage, | |
25390 | and Exim does so. This attempt to remove Exim from TLS policy decisions failed, | |
25391 | as GnuTLS 2.12 returns a value higher than the current hard-coded limit of the | |
25392 | NSS library. Thus Exim gains the tls_dh_max_bits global option, which applies | |
25393 | to all D-H usage, client or server. If the value returned by GnuTLS is greater | |
25394 | than tls_dh_max_bits then the value will be clamped down to tls_dh_max_bits. | |
25395 | The default value has been set at the current NSS limit, which is still much | |
25396 | higher than Exim historically used. | |
25397 | ||
25398 | The filename and bits used will change as the GnuTLS maintainers change the | |
25399 | value for their parameter "GNUTLS_SEC_PARAM_NORMAL", as clamped by | |
25400 | tls_dh_max_bits. At the time of writing (mid 2012), GnuTLS 2.12 recommends 2432 | |
25401 | bits, while NSS is limited to 2236 bits. | |
25402 | ||
25403 | In fact, the requested value will be *lower* than tls_dh_max_bits, to increase | |
25404 | the chance of the generated prime actually being within acceptable bounds, as | |
25405 | GnuTLS has been observed to overshoot. Note the check step in the procedure | |
25406 | above. There is no sane procedure available to Exim to double-check the size of | |
25407 | the generated prime, so it might still be too large. | |
25408 | ||
25409 | ||
2813c06e | 25410 | 42.4 Requiring specific ciphers in OpenSSL |
420a0d19 CE |
25411 | ------------------------------------------ |
25412 | ||
25413 | There is a function in the OpenSSL library that can be passed a list of cipher | |
25414 | suites before the cipher negotiation takes place. This specifies which ciphers | |
25415 | are acceptable. The list is colon separated and may contain names like | |
25416 | DES-CBC3-SHA. Exim passes the expanded value of tls_require_ciphers directly to | |
25417 | this function call. Many systems will install the OpenSSL manual-pages, so you | |
25418 | may have ciphers(1) available to you. The following quotation from the OpenSSL | |
25419 | documentation specifies what forms of item are allowed in the cipher string: | |
25420 | ||
25421 | * It can consist of a single cipher suite such as RC4-SHA. | |
25422 | ||
25423 | * It can represent a list of cipher suites containing a certain algorithm, or | |
25424 | cipher suites of a certain type. For example SHA1 represents all ciphers | |
25425 | suites using the digest algorithm SHA1 and SSLv3 represents all SSL v3 | |
25426 | algorithms. | |
25427 | ||
25428 | * Lists of cipher suites can be combined in a single cipher string using the | |
25429 | + character. This is used as a logical and operation. For example SHA1+DES | |
25430 | represents all cipher suites containing the SHA1 and the DES algorithms. | |
25431 | ||
25432 | Each cipher string can be optionally preceded by one of the characters "!", "-" | |
25433 | or "+". | |
25434 | ||
25435 | * If "!" is used, the ciphers are permanently deleted from the list. The | |
25436 | ciphers deleted can never reappear in the list even if they are explicitly | |
25437 | stated. | |
25438 | ||
25439 | * If "-" is used, the ciphers are deleted from the list, but some or all of | |
25440 | the ciphers can be added again by later options. | |
25441 | ||
25442 | * If "+" is used, the ciphers are moved to the end of the list. This option | |
25443 | does not add any new ciphers; it just moves matching existing ones. | |
25444 | ||
25445 | If none of these characters is present, the string is interpreted as a list of | |
25446 | ciphers to be appended to the current preference list. If the list includes any | |
25447 | ciphers already present they will be ignored: that is, they will not be moved | |
25448 | to the end of the list. | |
25449 | ||
25450 | The OpenSSL ciphers(1) command may be used to test the results of a given | |
25451 | string: | |
25452 | ||
25453 | # note single-quotes to get ! past any shell history expansion | |
25454 | $ openssl ciphers 'HIGH:!MD5:!SHA1' | |
25455 | ||
25456 | This example will let the library defaults be permitted on the MX port, where | |
25457 | there's probably no identity verification anyway, but ups the ante on the | |
25458 | submission ports where the administrator might have some influence on the | |
25459 | choice of clients used: | |
25460 | ||
25461 | # OpenSSL variant; see man ciphers(1) | |
25462 | tls_require_ciphers = ${if =={$received_port}{25}\ | |
25463 | {DEFAULT}\ | |
25464 | {HIGH:!MD5:!SHA1}} | |
25465 | ||
25466 | ||
2813c06e | 25467 | 42.5 Requiring specific ciphers or other parameters in GnuTLS |
420a0d19 CE |
25468 | ------------------------------------------------------------- |
25469 | ||
25470 | The GnuTLS library allows the caller to provide a "priority string", documented | |
25471 | as part of the gnutls_priority_init function. This is very similar to the | |
25472 | ciphersuite specification in OpenSSL. | |
25473 | ||
2813c06e CE |
25474 | The tls_require_ciphers option is treated as the GnuTLS priority string and |
25475 | controls both protocols and ciphers. | |
420a0d19 CE |
25476 | |
25477 | The tls_require_ciphers option is available both as an global option, | |
25478 | controlling how Exim behaves as a server, and also as an option of the smtp | |
25479 | transport, controlling how Exim behaves as a client. In both cases the value is | |
25480 | string expanded. The resulting string is not an Exim list and the string is | |
25481 | given to the GnuTLS library, so that Exim does not need to be aware of future | |
25482 | feature enhancements of GnuTLS. | |
25483 | ||
25484 | Documentation of the strings accepted may be found in the GnuTLS manual, under | |
25485 | "Priority strings". This is online as http://www.gnutls.org/manual/html_node/ | |
25486 | Priority-Strings.html, but beware that this relates to GnuTLS 3, which may be | |
2813c06e CE |
25487 | newer than the version installed on your system. If you are using GnuTLS 3, |
25488 | then the example code http://www.gnutls.org/manual/gnutls.html# | |
25489 | Listing-the-ciphersuites-in-a-priority-string on that site can be used to test | |
25490 | a given string. | |
25491 | ||
25492 | For example: | |
25493 | ||
25494 | # Disable older versions of protocols | |
25495 | tls_require_ciphers = NORMAL:%LATEST_RECORD_VERSION:-VERS-SSL3.0 | |
420a0d19 CE |
25496 | |
25497 | Prior to Exim 4.80, an older API of GnuTLS was used, and Exim supported three | |
25498 | additional options, "gnutls_require_kx", "gnutls_require_mac" and " | |
25499 | gnutls_require_protocols". tls_require_ciphers was an Exim list. | |
25500 | ||
25501 | This example will let the library defaults be permitted on the MX port, where | |
25502 | there's probably no identity verification anyway, and lowers security further | |
25503 | by increasing compatibility; but this ups the ante on the submission ports | |
25504 | where the administrator might have some influence on the choice of clients | |
25505 | used: | |
25506 | ||
25507 | # GnuTLS variant | |
25508 | tls_require_ciphers = ${if =={$received_port}{25}\ | |
25509 | {NORMAL:%COMPAT}\ | |
25510 | {SECURE128}} | |
25511 | ||
25512 | ||
2813c06e | 25513 | 42.6 Configuring an Exim server to use TLS |
420a0d19 CE |
25514 | ------------------------------------------ |
25515 | ||
25516 | When Exim has been built with TLS support, it advertises the availability of | |
25517 | the STARTTLS command to client hosts that match tls_advertise_hosts, but not to | |
25518 | any others. The default value of this option is unset, which means that | |
25519 | STARTTLS is not advertised at all. This default is chosen because you need to | |
25520 | set some other options in order to make TLS available, and also it is sensible | |
25521 | for systems that want to use TLS only as a client. | |
25522 | ||
25523 | If a client issues a STARTTLS command and there is some configuration problem | |
25524 | in the server, the command is rejected with a 454 error. If the client persists | |
25525 | in trying to issue SMTP commands, all except QUIT are rejected with the error | |
25526 | ||
25527 | 554 Security failure | |
25528 | ||
25529 | If a STARTTLS command is issued within an existing TLS session, it is rejected | |
25530 | with a 554 error code. | |
25531 | ||
2813c06e CE |
25532 | To enable TLS operations on a server, the tls_advertise_hosts option must be |
25533 | set to match some hosts. The default is * which matches all hosts. | |
25534 | ||
25535 | If this is all you do, TLS encryption will be enabled but not authentication - | |
25536 | meaning that the peer has no assurance it is actually you he is talking to. You | |
25537 | gain protection from a passive sniffer listening on the wire but not from | |
25538 | someone able to intercept the communication. | |
25539 | ||
25540 | Further protection requires some further configuration at the server end. | |
420a0d19 CE |
25541 | |
25542 | It is rumoured that all existing clients that support TLS/SSL use RSA | |
25543 | encryption. To make this work you need to set, in the server, | |
25544 | ||
25545 | tls_certificate = /some/file/name | |
25546 | tls_privatekey = /some/file/name | |
25547 | ||
25548 | These options are, in fact, expanded strings, so you can make them depend on | |
25549 | the identity of the client that is connected if you wish. The first file | |
25550 | contains the server's X509 certificate, and the second contains the private key | |
2813c06e CE |
25551 | that goes with it. These files need to be PEM format and readable by the Exim |
25552 | user, and must always be given as full path names. The key must not be | |
25553 | password-protected. They can be the same file if both the certificate and the | |
25554 | key are contained within it. If tls_privatekey is not set, or if its expansion | |
25555 | is forced to fail or results in an empty string, this is assumed to be the | |
25556 | case. The certificate file may also contain intermediate certificates that need | |
25557 | to be sent to the client to enable it to authenticate the server's certificate. | |
420a0d19 CE |
25558 | |
25559 | If you do not understand about certificates and keys, please try to find a | |
25560 | source of this background information, which is not Exim-specific. (There are a | |
2813c06e | 25561 | few comments below in section 42.12.) |
420a0d19 CE |
25562 | |
25563 | Note: These options do not apply when Exim is operating as a client - they | |
25564 | apply only in the case of a server. If you need to use a certificate in an Exim | |
25565 | client, you must set the options of the same names in an smtp transport. | |
25566 | ||
25567 | With just these options, an Exim server will be able to use TLS. It does not | |
25568 | require the client to have a certificate (but see below for how to insist on | |
25569 | this). There is one other option that may be needed in other situations. If | |
25570 | ||
25571 | tls_dhparam = /some/file/name | |
25572 | ||
25573 | is set, the SSL library is initialized for the use of Diffie-Hellman ciphers | |
25574 | with the parameters contained in the file. Set this to "none" to disable use of | |
25575 | DH entirely, by making no prime available: | |
25576 | ||
25577 | tls_dhparam = none | |
25578 | ||
25579 | This may also be set to a string identifying a standard prime to be used for | |
25580 | DH; if it is set to "default" or, for OpenSSL, is unset, then the prime used is | |
25581 | "ike23". There are a few standard primes available, see the documentation for | |
25582 | tls_dhparam for the complete list. | |
25583 | ||
25584 | See the command | |
25585 | ||
25586 | openssl dhparam | |
25587 | ||
25588 | for a way of generating file data. | |
25589 | ||
25590 | The strings supplied for these three options are expanded every time a client | |
25591 | host connects. It is therefore possible to use different certificates and keys | |
25592 | for different hosts, if you so wish, by making use of the client's IP address | |
25593 | in $sender_host_address to control the expansion. If a string expansion is | |
25594 | forced to fail, Exim behaves as if the option is not set. | |
25595 | ||
25596 | The variable $tls_in_cipher is set to the cipher suite that was negotiated for | |
25597 | an incoming TLS connection. It is included in the Received: header of an | |
25598 | incoming message (by default - you can, of course, change this), and it is also | |
25599 | included in the log line that records a message's arrival, keyed by "X=", | |
25600 | unless the tls_cipher log selector is turned off. The encrypted condition can | |
25601 | be used to test for specific cipher suites in ACLs. | |
25602 | ||
25603 | Once TLS has been established, the ACLs that run for subsequent SMTP commands | |
25604 | can check the name of the cipher suite and vary their actions accordingly. The | |
25605 | cipher suite names vary, depending on which TLS library is being used. For | |
25606 | example, OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other | |
25607 | contexts is known as TLS_RSA_WITH_3DES_EDE_CBC_SHA. Check the OpenSSL or GnuTLS | |
25608 | documentation for more details. | |
25609 | ||
25610 | For outgoing SMTP deliveries, $tls_out_cipher is used and logged (again | |
25611 | depending on the tls_cipher log selector). | |
25612 | ||
25613 | ||
2813c06e | 25614 | 42.7 Requesting and verifying client certificates |
420a0d19 CE |
25615 | ------------------------------------------------- |
25616 | ||
25617 | If you want an Exim server to request a certificate when negotiating a TLS | |
25618 | session with a client, you must set either tls_verify_hosts or | |
25619 | tls_try_verify_hosts. You can, of course, set either of them to * to apply to | |
25620 | all TLS connections. For any host that matches one of these options, Exim | |
25621 | requests a certificate as part of the setup of the TLS session. The contents of | |
25622 | the certificate are verified by comparing it with a list of expected | |
2813c06e CE |
25623 | certificates. These may be the system default set (depending on library |
25624 | version), an explicit file or, depending on library version, a directory, | |
25625 | identified by tls_verify_certificates. | |
420a0d19 CE |
25626 | |
25627 | A file can contain multiple certificates, concatenated end to end. If a | |
25628 | directory is used (OpenSSL only), each certificate must be in a separate file, | |
25629 | with a name (or a symbolic link) of the form <hash>.0, where <hash> is a hash | |
25630 | value constructed from the certificate. You can compute the relevant hash by | |
25631 | running the command | |
25632 | ||
25633 | openssl x509 -hash -noout -in /cert/file | |
25634 | ||
25635 | where /cert/file contains a single certificate. | |
25636 | ||
25637 | The difference between tls_verify_hosts and tls_try_verify_hosts is what | |
25638 | happens if the client does not supply a certificate, or if the certificate does | |
25639 | not match any of the certificates in the collection named by | |
25640 | tls_verify_certificates. If the client matches tls_verify_hosts, the attempt to | |
25641 | set up a TLS session is aborted, and the incoming connection is dropped. If the | |
25642 | client matches tls_try_verify_hosts, the (encrypted) SMTP session continues. | |
25643 | ACLs that run for subsequent SMTP commands can detect the fact that no | |
25644 | certificate was verified, and vary their actions accordingly. For example, you | |
25645 | can insist on a certificate before accepting a message for relaying, but not | |
25646 | when the message is destined for local delivery. | |
25647 | ||
25648 | When a client supplies a certificate (whether it verifies or not), the value of | |
25649 | the Distinguished Name of the certificate is made available in the variable | |
25650 | $tls_in_peerdn during subsequent processing of the message. | |
25651 | ||
25652 | Because it is often a long text string, it is not included in the log line or | |
25653 | Received: header by default. You can arrange for it to be logged, keyed by "DN= | |
25654 | ", by setting the tls_peerdn log selector, and you can use received_header_text | |
25655 | to change the Received: header. When no certificate is supplied, $tls_in_peerdn | |
25656 | is empty. | |
25657 | ||
25658 | ||
2813c06e | 25659 | 42.8 Revoked certificates |
420a0d19 CE |
25660 | ------------------------- |
25661 | ||
25662 | Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when | |
25663 | certificates are revoked. If you have such a list, you can pass it to an Exim | |
25664 | server using the global option called tls_crl and to an Exim client using an | |
25665 | identically named option for the smtp transport. In each case, the value of the | |
25666 | option is expanded and must then be the name of a file that contains a CRL in | |
25667 | PEM format. The downside is that clients have to periodically re-download a | |
2813c06e | 25668 | potentially huge file from every certificate authority they know of. |
420a0d19 CE |
25669 | |
25670 | The way with most moving parts at query time is Online Certificate Status | |
25671 | Protocol (OCSP), where the client verifies the certificate against an OCSP | |
25672 | server run by the CA. This lets the CA track all usage of the certs. It | |
25673 | requires running software with access to the private key of the CA, to sign the | |
25674 | responses to the OCSP queries. OCSP is based on HTTP and can be proxied | |
25675 | accordingly. | |
25676 | ||
25677 | The only widespread OCSP server implementation (known to this writer) comes as | |
25678 | part of OpenSSL and aborts on an invalid request, such as connecting to the | |
25679 | port and then disconnecting. This requires re-entering the passphrase each time | |
25680 | some random client does this. | |
25681 | ||
25682 | The third way is OCSP Stapling; in this, the server using a certificate issued | |
25683 | by the CA periodically requests an OCSP proof of validity from the OCSP server, | |
25684 | then serves it up inline as part of the TLS negotiation. This approach adds no | |
25685 | extra round trips, does not let the CA track users, scales well with number of | |
25686 | certs issued by the CA and is resilient to temporary OCSP server failures, as | |
25687 | long as the server starts retrying to fetch an OCSP proof some time before its | |
25688 | current proof expires. The downside is that it requires server support. | |
25689 | ||
25690 | Unless Exim is built with the support disabled, or with GnuTLS earlier than | |
2813c06e | 25691 | version 3.3.16 / 3.4.8 support for OCSP stapling is included. |
420a0d19 CE |
25692 | |
25693 | There is a global option called tls_ocsp_file. The file specified therein is | |
25694 | expected to be in DER format, and contain an OCSP proof. Exim will serve it as | |
25695 | part of the TLS handshake. This option will be re-expanded for SNI, if the | |
25696 | tls_certificate option contains "tls_in_sni", as per other TLS options. | |
25697 | ||
25698 | Exim does not at this time implement any support for fetching a new OCSP proof. | |
25699 | The burden is on the administrator to handle this, outside of Exim. The file | |
25700 | specified should be replaced atomically, so that the contents are always valid. | |
25701 | Exim will expand the tls_ocsp_file option on each connection, so a new file | |
25702 | will be handled transparently on the next connection. | |
25703 | ||
25704 | When built with OpenSSL Exim will check for a valid next update timestamp in | |
25705 | the OCSP proof; if not present, or if the proof has expired, it will be | |
25706 | ignored. | |
25707 | ||
25708 | For the client to be able to verify the stapled OCSP the server must also | |
25709 | supply, in its stapled information, any intermediate certificates for the chain | |
25710 | leading to the OCSP proof from the signer of the server certificate. There may | |
25711 | be zero or one such. These intermediate certificates should be added to the | |
25712 | server OCSP stapling file named by tls_ocsp_file. | |
25713 | ||
25714 | Note that the proof only covers the terminal server certificate, not any of the | |
25715 | chain from CA to it. | |
25716 | ||
25717 | There is no current way to staple a proof for a client certificate. | |
25718 | ||
25719 | A helper script "ocsp_fetch.pl" for fetching a proof from a CA | |
25720 | OCSP server is supplied. The server URL may be included in the | |
25721 | server certificate, if the CA is helpful. | |
25722 | ||
25723 | One failure mode seen was the OCSP Signer cert expiring before the end | |
25724 | of validity of the OCSP proof. The checking done by Exim/OpenSSL | |
25725 | noted this as invalid overall, but the re-fetch script did not. | |
25726 | ||
25727 | ||
2813c06e | 25728 | 42.9 Configuring an Exim client to use TLS |
420a0d19 CE |
25729 | ------------------------------------------ |
25730 | ||
25731 | The tls_cipher and tls_peerdn log selectors apply to outgoing SMTP deliveries | |
25732 | as well as to incoming, the latter one causing logging of the server | |
25733 | certificate's DN. The remaining client configuration for TLS is all within the | |
25734 | smtp transport. | |
25735 | ||
25736 | It is not necessary to set any options to have TLS work in the smtp transport. | |
25737 | If Exim is built with TLS support, and TLS is advertised by a server, the smtp | |
25738 | transport always tries to start a TLS session. However, this can be prevented | |
25739 | by setting hosts_avoid_tls (an option of the transport) to a list of server | |
25740 | hosts for which TLS should not be used. | |
25741 | ||
25742 | If you do not want Exim to attempt to send messages unencrypted when an attempt | |
25743 | to set up an encrypted connection fails in any way, you can set | |
25744 | hosts_require_tls to a list of hosts for which encryption is mandatory. For | |
25745 | those hosts, delivery is always deferred if an encrypted connection cannot be | |
25746 | set up. If there are any other hosts for the address, they are tried in the | |
25747 | usual way. | |
25748 | ||
25749 | When the server host is not in hosts_require_tls, Exim may try to deliver the | |
25750 | message unencrypted. It always does this if the response to STARTTLS is a 5xx | |
25751 | code. For a temporary error code, or for a failure to negotiate a TLS session | |
25752 | after a success response code, what happens is controlled by the | |
25753 | tls_tempfail_tryclear option of the smtp transport. If it is false, delivery to | |
25754 | this host is deferred, and other hosts (if available) are tried. If it is true, | |
25755 | Exim attempts to deliver unencrypted after a 4xx response to STARTTLS, and if | |
25756 | STARTTLS is accepted, but the subsequent TLS negotiation fails, Exim closes the | |
25757 | current connection (because it is in an unknown state), opens a new one to the | |
25758 | same host, and then tries the delivery unencrypted. | |
25759 | ||
25760 | The tls_certificate and tls_privatekey options of the smtp transport provide | |
25761 | the client with a certificate, which is passed to the server if it requests it. | |
25762 | If the server is Exim, it will request a certificate only if tls_verify_hosts | |
25763 | or tls_try_verify_hosts matches the client. | |
25764 | ||
2813c06e CE |
25765 | If the tls_verify_certificates option is set on the smtp transport, it |
25766 | specifies a collection of expected server certificates. These may be the system | |
25767 | default set (depending on library version), a file or, depending on library | |
25768 | version, a directory, must name a file or, for OpenSSL only (not GnuTLS), a | |
25769 | directory. The client verifies the server's certificate against this | |
25770 | collection, taking into account any revoked certificates that are in the list | |
25771 | defined by tls_crl. Failure to verify fails the TLS connection unless either of | |
25772 | the tls_verify_hosts or tls_try_verify_hosts options are set. | |
420a0d19 CE |
25773 | |
25774 | The tls_verify_hosts and tls_try_verify_hosts options restrict certificate | |
25775 | verification to the listed servers. Verification either must or need not | |
25776 | succeed respectively. | |
25777 | ||
25778 | The smtp transport has two OCSP-related options: hosts_require_ocsp; a | |
25779 | host-list for which a Certificate Status is requested and required for the | |
25780 | connection to proceed. The default value is empty. hosts_request_ocsp; a | |
25781 | host-list for which (additionally) a Certificate Status is requested (but not | |
25782 | necessarily verified). The default value is "*" meaning that requests are made | |
25783 | unless configured otherwise. | |
25784 | ||
25785 | The host(s) should also be in hosts_require_tls, and tls_verify_certificates | |
25786 | configured for the transport, for OCSP to be relevant. | |
25787 | ||
25788 | If tls_require_ciphers is set on the smtp transport, it must contain a list of | |
25789 | permitted cipher suites. If either of these checks fails, delivery to the | |
25790 | current host is abandoned, and the smtp transport tries to deliver to | |
25791 | alternative hosts, if any. | |
25792 | ||
25793 | Note: These options must be set in the smtp transport for Exim to use TLS when | |
25794 | it is operating as a client. Exim does not assume that a server certificate | |
25795 | (set by the global options of the same name) should also be used when operating | |
25796 | as a client. | |
25797 | ||
25798 | All the TLS options in the smtp transport are expanded before use, with $host | |
25799 | and $host_address containing the name and address of the server to which the | |
25800 | client is connected. Forced failure of an expansion causes Exim to behave as if | |
25801 | the relevant option were unset. | |
25802 | ||
25803 | Before an SMTP connection is established, the $tls_out_bits, $tls_out_cipher, | |
25804 | $tls_out_peerdn and $tls_out_sni variables are emptied. (Until the first | |
25805 | connection, they contain the values that were set when the message was | |
25806 | received.) If STARTTLS is subsequently successfully obeyed, these variables are | |
25807 | set to the relevant values for the outgoing connection. | |
25808 | ||
25809 | ||
2813c06e | 25810 | 42.10 Use of TLS Server Name Indication |
420a0d19 CE |
25811 | --------------------------------------- |
25812 | ||
25813 | With TLS1.0 or above, there is an extension mechanism by which extra | |
25814 | information can be included at various points in the protocol. One of these | |
25815 | extensions, documented in RFC 6066 (and before that RFC 4366) is "Server Name | |
25816 | Indication", commonly "SNI". This extension is sent by the client in the | |
25817 | initial handshake, so that the server can examine the servername within and | |
25818 | possibly choose to use different certificates and keys (and more) for this | |
25819 | session. | |
25820 | ||
2813c06e | 25821 | This is analogous to HTTP's "Host:" header, and is the main mechanism by which |
420a0d19 CE |
25822 | HTTPS-enabled web-sites can be virtual-hosted, many sites to one IP address. |
25823 | ||
25824 | With SMTP to MX, there are the same problems here as in choosing the identity | |
25825 | against which to validate a certificate: you can't rely on insecure DNS to | |
25826 | provide the identity which you then cryptographically verify. So this will be | |
25827 | of limited use in that environment. | |
25828 | ||
25829 | With SMTP to Submission, there is a well-defined hostname which clients are | |
25830 | connecting to and can validate certificates against. Thus clients can choose to | |
25831 | include this information in the TLS negotiation. If this becomes wide-spread, | |
25832 | then hosters can choose to present different certificates to different clients. | |
25833 | Or even negotiate different cipher suites. | |
25834 | ||
25835 | The tls_sni option on an SMTP transport is an expanded string; the result, if | |
25836 | not empty, will be sent on a TLS session as part of the handshake. There's | |
25837 | nothing more to it. Choosing a sensible value not derived insecurely is the | |
25838 | only point of caution. The $tls_out_sni variable will be set to this string for | |
25839 | the lifetime of the client connection (including during authentication). | |
25840 | ||
25841 | Except during SMTP client sessions, if $tls_in_sni is set then it is a string | |
25842 | received from a client. It can be logged with the log_selector item "+tls_sni". | |
25843 | ||
25844 | If the string "tls_in_sni" appears in the main section's tls_certificate option | |
25845 | (prior to expansion) then the following options will be re-expanded during TLS | |
25846 | session handshake, to permit alternative values to be chosen: | |
25847 | ||
25848 | * tls_certificate | |
25849 | ||
25850 | * tls_crl | |
25851 | ||
25852 | * tls_privatekey | |
25853 | ||
25854 | * tls_verify_certificates | |
25855 | ||
2813c06e | 25856 | * tls_ocsp_file |
420a0d19 CE |
25857 | |
25858 | Great care should be taken to deal with matters of case, various injection | |
25859 | attacks in the string ("../" or SQL), and ensuring that a valid filename can | |
2813c06e CE |
25860 | always be referenced; it is important to remember that $tls_in_sni is arbitrary |
25861 | unverified data provided prior to authentication. Further, the initial | |
25862 | certificate is loaded before SNI is arrived, so an expansion for | |
25863 | tls_certificate must have a default which is used when $tls_in_sni is empty. | |
420a0d19 CE |
25864 | |
25865 | The Exim developers are proceeding cautiously and so far no other TLS options | |
25866 | are re-expanded. | |
25867 | ||
2813c06e | 25868 | When Exim is built against OpenSSL, OpenSSL must have been built with support |
420a0d19 CE |
25869 | for TLS Extensions. This holds true for OpenSSL 1.0.0+ and 0.9.8+ with |
25870 | enable-tlsext in EXTRACONFIGURE. If you invoke openssl s_client -h and see | |
25871 | "-servername" in the output, then OpenSSL has support. | |
25872 | ||
25873 | When Exim is built against GnuTLS, SNI support is available as of GnuTLS | |
25874 | 0.5.10. (Its presence predates the current API which Exim uses, so if Exim | |
25875 | built, then you have SNI support). | |
25876 | ||
25877 | ||
2813c06e | 25878 | 42.11 Multiple messages on the same encrypted TCP/IP connection |
420a0d19 CE |
25879 | --------------------------------------------------------------- |
25880 | ||
25881 | Exim sends multiple messages down the same TCP/IP connection by starting up an | |
25882 | entirely new delivery process for each message, passing the socket from one | |
25883 | process to the next. This implementation does not fit well with the use of TLS, | |
25884 | because there is quite a lot of state information associated with a TLS | |
25885 | connection, not just a socket identification. Passing all the state information | |
25886 | to a new process is not feasible. Consequently, Exim shuts down an existing TLS | |
25887 | session before passing the socket to a new process. The new process may then | |
25888 | try to start a new TLS session, and if successful, may try to re-authenticate | |
25889 | if AUTH is in use, before sending the next message. | |
25890 | ||
25891 | The RFC is not clear as to whether or not an SMTP session continues in clear | |
25892 | after TLS has been shut down, or whether TLS may be restarted again later, as | |
25893 | just described. However, if the server is Exim, this shutdown and | |
25894 | reinitialization works. It is not known which (if any) other servers operate | |
25895 | successfully if the client closes a TLS session and continues with unencrypted | |
25896 | SMTP, but there are certainly some that do not work. For such servers, Exim | |
25897 | should not pass the socket to another process, because the failure of the | |
25898 | subsequent attempt to use it would cause Exim to record a temporary host error, | |
25899 | and delay other deliveries to that host. | |
25900 | ||
25901 | To test for this case, Exim sends an EHLO command to the server after closing | |
25902 | down the TLS session. If this fails in any way, the connection is closed | |
25903 | instead of being passed to a new delivery process, but no retry information is | |
25904 | recorded. | |
25905 | ||
25906 | There is also a manual override; you can set hosts_nopass_tls on the smtp | |
25907 | transport to match those hosts for which Exim should not pass connections to | |
25908 | new processes if TLS has been used. | |
25909 | ||
25910 | ||
2813c06e | 25911 | 42.12 Certificates and all that |
420a0d19 CE |
25912 | ------------------------------- |
25913 | ||
25914 | In order to understand fully how TLS works, you need to know about | |
25915 | certificates, certificate signing, and certificate authorities. This is not the | |
25916 | place to give a tutorial, especially as I do not know very much about it | |
25917 | myself. Some helpful introduction can be found in the FAQ for the SSL addition | |
25918 | to Apache, currently at | |
25919 | ||
25920 | http://www.modssl.org/docs/2.7/ssl_faq.html#ToC24 | |
25921 | ||
25922 | Other parts of the modssl documentation are also helpful, and have links to | |
25923 | further files. Eric Rescorla's book, SSL and TLS, published by Addison-Wesley | |
25924 | (ISBN 0-201-61598-3), contains both introductory and more in-depth | |
25925 | descriptions. Some sample programs taken from the book are available from | |
25926 | ||
25927 | http://www.rtfm.com/openssl-examples/ | |
25928 | ||
25929 | ||
2813c06e | 25930 | 42.13 Certificate chains |
420a0d19 CE |
25931 | ------------------------ |
25932 | ||
25933 | The file named by tls_certificate may contain more than one certificate. This | |
25934 | is useful in the case where the certificate that is being sent is validated by | |
25935 | an intermediate certificate which the other end does not have. Multiple | |
25936 | certificates must be in the correct order in the file. First the host's | |
25937 | certificate itself, then the first intermediate certificate to validate the | |
25938 | issuer of the host certificate, then the next intermediate certificate to | |
25939 | validate the issuer of the first intermediate certificate, and so on, until | |
25940 | finally (optionally) the root certificate. The root certificate must already be | |
25941 | trusted by the recipient for validation to succeed, of course, but if it's not | |
25942 | preinstalled, sending the root certificate along with the rest makes it | |
25943 | available for the user to install if the receiving end is a client MUA that can | |
25944 | interact with a user. | |
25945 | ||
25946 | Note that certificates using MD5 are unlikely to work on today's Internet; even | |
25947 | if your libraries allow loading them for use in Exim when acting as a server, | |
25948 | increasingly clients will not accept such certificates. The error diagnostics | |
25949 | in such a case can be frustratingly vague. | |
25950 | ||
25951 | ||
2813c06e | 25952 | 42.14 Self-signed certificates |
420a0d19 CE |
25953 | ------------------------------ |
25954 | ||
25955 | You can create a self-signed certificate using the req command provided with | |
25956 | OpenSSL, like this: | |
25957 | ||
25958 | openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \ | |
25959 | -days 9999 -nodes | |
25960 | ||
25961 | file1 and file2 can be the same file; the key and the certificate are delimited | |
25962 | and so can be identified independently. The -days option specifies a period for | |
25963 | which the certificate is valid. The -nodes option is important: if you do not | |
25964 | set it, the key is encrypted with a passphrase that you are prompted for, and | |
25965 | any use that is made of the key causes more prompting for the passphrase. This | |
25966 | is not helpful if you are going to use this certificate and key in an MTA, | |
25967 | where prompting is not possible. | |
25968 | ||
25969 | NB: we are now past the point where 9999 days takes us past the 32-bit Unix | |
25970 | epoch. If your system uses unsigned time_t (most do) and is 32-bit, then the | |
25971 | above command might produce a date in the past. Think carefully about the | |
25972 | lifetime of the systems you're deploying, and either reduce the duration of the | |
25973 | certificate or reconsider your platform deployment. (At time of writing, | |
25974 | reducing the duration is the most likely choice, but the inexorable progression | |
25975 | of time takes us steadily towards an era where this will not be a sensible | |
25976 | resolution). | |
25977 | ||
25978 | A self-signed certificate made in this way is sufficient for testing, and may | |
25979 | be adequate for all your requirements if you are mainly interested in | |
25980 | encrypting transfers, and not in secure identification. | |
25981 | ||
25982 | However, many clients require that the certificate presented by the server be a | |
25983 | user (also called "leaf" or "site") certificate, and not a self-signed | |
25984 | certificate. In this situation, the self-signed certificate described above | |
25985 | must be installed on the client host as a trusted root certification authority | |
25986 | (CA), and the certificate used by Exim must be a user certificate signed with | |
25987 | that self-signed certificate. | |
25988 | ||
25989 | For information on creating self-signed CA certificates and using them to sign | |
25990 | user certificates, see the General implementation overview chapter of the | |
25991 | Open-source PKI book, available online at http://ospkibook.sourceforge.net/. | |
25992 | ||
25993 | ||
25994 | ||
25995 | =============================================================================== | |
2813c06e | 25996 | 43. ACCESS CONTROL LISTS |
420a0d19 CE |
25997 | |
25998 | Access Control Lists (ACLs) are defined in a separate section of the run time | |
25999 | configuration file, headed by "begin acl". Each ACL definition starts with a | |
26000 | name, terminated by a colon. Here is a complete ACL section that contains just | |
26001 | one very small ACL: | |
26002 | ||
26003 | begin acl | |
26004 | small_acl: | |
26005 | accept hosts = one.host.only | |
26006 | ||
26007 | You can have as many lists as you like in the ACL section, and the order in | |
26008 | which they appear does not matter. The lists are self-terminating. | |
26009 | ||
26010 | The majority of ACLs are used to control Exim's behaviour when it receives | |
26011 | certain SMTP commands. This applies both to incoming TCP/IP connections, and | |
26012 | when a local process submits a message using SMTP by specifying the -bs option. | |
26013 | The most common use is for controlling which recipients are accepted in | |
26014 | incoming messages. In addition, you can define an ACL that is used to check | |
26015 | local non-SMTP messages. The default configuration file contains an example of | |
26016 | a realistic ACL for checking RCPT commands. This is discussed in chapter 7. | |
26017 | ||
26018 | ||
2813c06e | 26019 | 43.1 Testing ACLs |
420a0d19 CE |
26020 | ----------------- |
26021 | ||
26022 | The -bh command line option provides a way of testing your ACL configuration | |
2813c06e | 26023 | locally by running a fake SMTP session with which you interact. |
420a0d19 CE |
26024 | |
26025 | ||
2813c06e | 26026 | 43.2 Specifying when ACLs are used |
420a0d19 CE |
26027 | ---------------------------------- |
26028 | ||
26029 | In order to cause an ACL to be used, you have to name it in one of the relevant | |
26030 | options in the main part of the configuration. These options are: | |
26031 | ||
26032 | acl_not_smtp ACL for non-SMTP messages | |
26033 | acl_not_smtp_mime ACL for non-SMTP MIME parts | |
26034 | acl_not_smtp_start ACL at start of non-SMTP message | |
26035 | acl_smtp_auth ACL for AUTH | |
26036 | acl_smtp_connect ACL for start of SMTP connection | |
26037 | acl_smtp_data ACL after DATA is complete | |
26038 | acl_smtp_data_prdr ACL for each recipient, after DATA is complete | |
2813c06e | 26039 | acl_smtp_dkim ACL for each DKIM signer |
420a0d19 CE |
26040 | acl_smtp_etrn ACL for ETRN |
26041 | acl_smtp_expn ACL for EXPN | |
26042 | acl_smtp_helo ACL for HELO or EHLO | |
26043 | acl_smtp_mail ACL for MAIL | |
26044 | acl_smtp_mailauth ACL for the AUTH parameter of MAIL | |
26045 | acl_smtp_mime ACL for content-scanning MIME parts | |
26046 | acl_smtp_notquit ACL for non-QUIT terminations | |
26047 | acl_smtp_predata ACL at start of DATA command | |
26048 | acl_smtp_quit ACL for QUIT | |
26049 | acl_smtp_rcpt ACL for RCPT | |
26050 | acl_smtp_starttls ACL for STARTTLS | |
26051 | acl_smtp_vrfy ACL for VRFY | |
26052 | ||
26053 | For example, if you set | |
26054 | ||
26055 | acl_smtp_rcpt = small_acl | |
26056 | ||
26057 | the little ACL defined above is used whenever Exim receives a RCPT command in | |
26058 | an SMTP dialogue. The majority of policy tests on incoming messages can be done | |
26059 | when RCPT commands arrive. A rejection of RCPT should cause the sending MTA to | |
26060 | give up on the recipient address contained in the RCPT command, whereas | |
26061 | rejection at other times may cause the client MTA to keep on trying to deliver | |
26062 | the message. It is therefore recommended that you do as much testing as | |
26063 | possible at RCPT time. | |
26064 | ||
26065 | ||
2813c06e | 26066 | 43.3 The non-SMTP ACLs |
420a0d19 CE |
26067 | ---------------------- |
26068 | ||
26069 | The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they | |
26070 | apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not | |
26071 | really SMTP.) Many of the ACL conditions (for example, host tests, and tests on | |
26072 | the state of the SMTP connection such as encryption and authentication) are not | |
26073 | relevant and are forbidden in these ACLs. However, the sender and recipients | |
26074 | are known, so the senders and sender_domains conditions and the $sender_address | |
26075 | and $recipients variables can be used. Variables such as $authenticated_sender | |
26076 | are also available. You can specify added header lines in any of these ACLs. | |
26077 | ||
26078 | The acl_not_smtp_start ACL is run right at the start of receiving a non-SMTP | |
26079 | message, before any of the message has been read. (This is the analogue of the | |
26080 | acl_smtp_predata ACL for SMTP input.) In the case of batched SMTP input, it | |
26081 | runs after the DATA command has been reached. The result of this ACL is | |
26082 | ignored; it cannot be used to reject a message. If you really need to, you | |
26083 | could set a value in an ACL variable here and reject based on that in the | |
26084 | acl_not_smtp ACL. However, this ACL can be used to set controls, and in | |
26085 | particular, it can be used to set | |
26086 | ||
26087 | control = suppress_local_fixups | |
26088 | ||
26089 | This cannot be used in the other non-SMTP ACLs because by the time they are | |
26090 | run, it is too late. | |
26091 | ||
26092 | The acl_not_smtp_mime ACL is available only when Exim is compiled with the | |
2813c06e | 26093 | content-scanning extension. For details, see chapter 44. |
420a0d19 CE |
26094 | |
26095 | The acl_not_smtp ACL is run just before the local_scan() function. Any kind of | |
26096 | rejection is treated as permanent, because there is no way of sending a | |
26097 | temporary error for these kinds of message. | |
26098 | ||
26099 | ||
2813c06e | 26100 | 43.4 The SMTP connect ACL |
420a0d19 CE |
26101 | ------------------------- |
26102 | ||
26103 | The ACL test specified by acl_smtp_connect happens at the start of an SMTP | |
26104 | session, after the test specified by host_reject_connection (which is now an | |
26105 | anomaly) and any TCP Wrappers testing (if configured). If the connection is | |
26106 | accepted by an accept verb that has a message modifier, the contents of the | |
26107 | message override the banner message that is otherwise specified by the | |
26108 | smtp_banner option. | |
26109 | ||
26110 | ||
2813c06e | 26111 | 43.5 The EHLO/HELO ACL |
420a0d19 CE |
26112 | ---------------------- |
26113 | ||
26114 | The ACL test specified by acl_smtp_helo happens when the client issues an EHLO | |
26115 | or HELO command, after the tests specified by helo_accept_junk_hosts, | |
26116 | helo_allow_chars, helo_verify_hosts, and helo_try_verify_hosts. Note that a | |
26117 | client may issue more than one EHLO or HELO command in an SMTP session, and | |
26118 | indeed is required to issue a new EHLO or HELO after successfully setting up | |
26119 | encryption following a STARTTLS command. | |
26120 | ||
2813c06e CE |
26121 | Note also that a deny neither forces the client to go away nor means that mail |
26122 | will be refused on the connection. Consider checking for $sender_helo_name | |
26123 | being defined in a MAIL or RCPT ACL to do that. | |
26124 | ||
420a0d19 CE |
26125 | If the command is accepted by an accept verb that has a message modifier, the |
26126 | message may not contain more than one line (it will be truncated at the first | |
26127 | newline and a panic logged if it does). Such a message cannot affect the EHLO | |
26128 | options that are listed on the second and subsequent lines of an EHLO response. | |
26129 | ||
26130 | ||
2813c06e | 26131 | 43.6 The DATA ACLs |
420a0d19 CE |
26132 | ------------------ |
26133 | ||
26134 | Two ACLs are associated with the DATA command, because it is two-stage command, | |
26135 | with two responses being sent to the client. When the DATA command is received, | |
26136 | the ACL defined by acl_smtp_predata is obeyed. This gives you control after all | |
26137 | the RCPT commands, but before the message itself is received. It offers the | |
26138 | opportunity to give a negative response to the DATA command before the data is | |
26139 | transmitted. Header lines added by MAIL or RCPT ACLs are not visible at this | |
26140 | time, but any that are defined here are visible when the acl_smtp_data ACL is | |
26141 | run. | |
26142 | ||
26143 | You cannot test the contents of the message, for example, to verify addresses | |
26144 | in the headers, at RCPT time or when the DATA command is received. Such tests | |
26145 | have to appear in the ACL that is run after the message itself has been | |
26146 | received, before the final response to the DATA command is sent. This is the | |
26147 | ACL specified by acl_smtp_data, which is the second ACL that is associated with | |
26148 | the DATA command. | |
26149 | ||
2813c06e CE |
26150 | If CHUNKING was advertised and a BDAT command sequence is received, the |
26151 | acl_smtp_predata ACL is not run. The acl_smtp_data is run after the last BDAT | |
26152 | command and all of the data specified is received. | |
26153 | ||
420a0d19 CE |
26154 | For both of these ACLs, it is not possible to reject individual recipients. An |
26155 | error response rejects the entire message. Unfortunately, it is known that some | |
26156 | MTAs do not treat hard (5xx) responses to the DATA command (either before or | |
26157 | after the data) correctly - they keep the message on their queues and try again | |
26158 | later, but that is their problem, though it does waste some of your resources. | |
26159 | ||
26160 | The acl_smtp_data ACL is run after the acl_smtp_data_prdr, the acl_smtp_dkim | |
26161 | and the acl_smtp_mime ACLs. | |
26162 | ||
26163 | ||
2813c06e | 26164 | 43.7 The SMTP DKIM ACL |
420a0d19 CE |
26165 | ---------------------- |
26166 | ||
26167 | The acl_smtp_dkim ACL is available only when Exim is compiled with DKIM support | |
26168 | enabled (which is the default). | |
26169 | ||
26170 | The ACL test specified by acl_smtp_dkim happens after a message has been | |
26171 | received, and is executed for each DKIM signature found in a message. If not | |
26172 | otherwise specified, the default action is to accept. | |
26173 | ||
26174 | This ACL is evaluated before acl_smtp_mime and acl_smtp_data. | |
26175 | ||
2813c06e | 26176 | For details on the operation of DKIM, see chapter 57. |
420a0d19 CE |
26177 | |
26178 | ||
2813c06e | 26179 | 43.8 The SMTP MIME ACL |
420a0d19 CE |
26180 | ---------------------- |
26181 | ||
26182 | The acl_smtp_mime option is available only when Exim is compiled with the | |
2813c06e | 26183 | content-scanning extension. For details, see chapter 44. |
420a0d19 CE |
26184 | |
26185 | This ACL is evaluated after acl_smtp_dkim but before acl_smtp_data. | |
26186 | ||
26187 | ||
2813c06e | 26188 | 43.9 The SMTP PRDR ACL |
420a0d19 CE |
26189 | ---------------------- |
26190 | ||
26191 | The acl_smtp_data_prdr ACL is available only when Exim is compiled with PRDR | |
26192 | support enabled (which is the default). It becomes active only when the PRDR | |
26193 | feature is negotiated between client and server for a message, and more than | |
26194 | one recipient has been accepted. | |
26195 | ||
2813c06e CE |
26196 | The ACL test specified by acl_smtp_data_prdr happens after a message has been |
26197 | received, and is executed once for each recipient of the message with | |
26198 | $local_part and $domain valid. The test may accept, defer or deny for | |
26199 | individual recipients. The acl_smtp_data will still be called after this ACL | |
26200 | and can reject the message overall, even if this ACL has accepted it for some | |
26201 | or all recipients. | |
420a0d19 CE |
26202 | |
26203 | PRDR may be used to support per-user content filtering. Without it one must | |
26204 | defer any recipient after the first that has a different content-filter | |
26205 | configuration. With PRDR, the RCPT-time check for this can be disabled when the | |
2813c06e CE |
26206 | variable $prdr_requested is "yes". Any required difference in behaviour of the |
26207 | main DATA-time ACL should however depend on the PRDR-time ACL having run, as | |
26208 | Exim will avoid doing so in some situations (e.g. single-recipient mails). | |
420a0d19 CE |
26209 | |
26210 | See also the prdr_enable global option and the hosts_try_prdr smtp transport | |
26211 | option. | |
26212 | ||
26213 | This ACL is evaluated after acl_smtp_dkim but before acl_smtp_data. If the ACL | |
26214 | is not defined, processing completes as if the feature was not requested by the | |
26215 | client. | |
26216 | ||
26217 | ||
2813c06e | 26218 | 43.10 The QUIT ACL |
420a0d19 CE |
26219 | ------------------ |
26220 | ||
26221 | The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL | |
26222 | does not affect the response code to QUIT, which is always 221. Thus, the ACL | |
2813c06e CE |
26223 | does not in fact control any access. For this reason, it may only accept or |
26224 | warn as its final result. | |
420a0d19 CE |
26225 | |
26226 | This ACL can be used for tasks such as custom logging at the end of an SMTP | |
26227 | session. For example, you can use ACL variables in other ACLs to count | |
26228 | messages, recipients, etc., and log the totals at QUIT time using one or more | |
26229 | logwrite modifiers on a warn verb. | |
26230 | ||
26231 | Warning: Only the $acl_cx variables can be used for this, because the $acl_mx | |
26232 | variables are reset at the end of each incoming message. | |
26233 | ||
26234 | You do not need to have a final accept, but if you do, you can use a message | |
26235 | modifier to specify custom text that is sent as part of the 221 response to | |
26236 | QUIT. | |
26237 | ||
26238 | This ACL is run only for a "normal" QUIT. For certain kinds of disastrous | |
26239 | failure (for example, failure to open a log file, or when Exim is bombing out | |
26240 | because it has detected an unrecoverable error), all SMTP commands from the | |
26241 | client are given temporary error responses until QUIT is received or the | |
26242 | connection is closed. In these special cases, the QUIT ACL does not run. | |
26243 | ||
26244 | ||
2813c06e | 26245 | 43.11 The not-QUIT ACL |
420a0d19 CE |
26246 | ---------------------- |
26247 | ||
26248 | The not-QUIT ACL, specified by acl_smtp_notquit, is run in most cases when an | |
26249 | SMTP session ends without sending QUIT. However, when Exim itself is in bad | |
26250 | trouble, such as being unable to write to its log files, this ACL is not run, | |
26251 | because it might try to do things (such as write to log files) that make the | |
26252 | situation even worse. | |
26253 | ||
26254 | Like the QUIT ACL, this ACL is provided to make it possible to do customized | |
26255 | logging or to gather statistics, and its outcome is ignored. The delay modifier | |
26256 | is forbidden in this ACL, and the only permitted verbs are accept and warn. | |
26257 | ||
26258 | When the not-QUIT ACL is running, the variable $smtp_notquit_reason is set to a | |
26259 | string that indicates the reason for the termination of the SMTP connection. | |
26260 | The possible values are: | |
26261 | ||
26262 | "acl-drop" Another ACL issued a drop command | |
26263 | "bad-commands" Too many unknown or non-mail commands | |
26264 | "command-timeout" Timeout while reading SMTP commands | |
26265 | "connection-lost" The SMTP connection has been lost | |
26266 | "data-timeout" Timeout while reading message data | |
26267 | "local-scan-error" The local_scan() function crashed | |
26268 | "local-scan-timeout" The local_scan() function timed out | |
26269 | "signal-exit" SIGTERM or SIGINT | |
26270 | "synchronization-error" SMTP synchronization error | |
26271 | "tls-failed" TLS failed to start | |
26272 | ||
26273 | In most cases when an SMTP connection is closed without having received QUIT, | |
26274 | Exim sends an SMTP response message before actually closing the connection. | |
26275 | With the exception of the "acl-drop" case, the default message can be | |
26276 | overridden by the message modifier in the not-QUIT ACL. In the case of a drop | |
26277 | verb in another ACL, it is the message from the other ACL that is used. | |
26278 | ||
26279 | ||
2813c06e | 26280 | 43.12 Finding an ACL to use |
420a0d19 CE |
26281 | --------------------------- |
26282 | ||
26283 | The value of an acl_smtp_xxx option is expanded before use, so you can use | |
26284 | different ACLs in different circumstances. For example, | |
26285 | ||
26286 | acl_smtp_rcpt = ${if ={25}{$interface_port} \ | |
26287 | {acl_check_rcpt} {acl_check_rcpt_submit} } | |
26288 | ||
26289 | In the default configuration file there are some example settings for providing | |
26290 | an RFC 4409 message submission service on port 587 and a non-standard "smtps" | |
26291 | service on port 465. You can use a string expansion like this to choose an ACL | |
26292 | for MUAs on these ports which is more appropriate for this purpose than the | |
26293 | default ACL on port 25. | |
26294 | ||
26295 | The expanded string does not have to be the name of an ACL in the configuration | |
26296 | file; there are other possibilities. Having expanded the string, Exim searches | |
26297 | for an ACL as follows: | |
26298 | ||
26299 | * If the string begins with a slash, Exim uses it as a file name, and reads | |
26300 | its contents as an ACL. The lines are processed in the same way as lines in | |
26301 | the Exim configuration file. In particular, continuation lines are | |
26302 | supported, blank lines are ignored, as are lines whose first non-whitespace | |
26303 | character is "#". If the file does not exist or cannot be read, an error | |
26304 | occurs (typically causing a temporary failure of whatever caused the ACL to | |
26305 | be run). For example: | |
26306 | ||
26307 | acl_smtp_data = /etc/acls/\ | |
26308 | ${lookup{$sender_host_address}lsearch\ | |
26309 | {/etc/acllist}{$value}{default}} | |
26310 | ||
26311 | This looks up an ACL file to use on the basis of the host's IP address, | |
26312 | falling back to a default if the lookup fails. If an ACL is successfully | |
26313 | read from a file, it is retained in memory for the duration of the Exim | |
26314 | process, so that it can be re-used without having to re-read the file. | |
26315 | ||
26316 | * If the string does not start with a slash, and does not contain any spaces, | |
26317 | Exim searches the ACL section of the configuration for an ACL whose name | |
26318 | matches the string. | |
26319 | ||
26320 | * If no named ACL is found, or if the string contains spaces, Exim parses the | |
26321 | string as an inline ACL. This can save typing in cases where you just want | |
26322 | to have something like | |
26323 | ||
26324 | acl_smtp_vrfy = accept | |
26325 | ||
26326 | in order to allow free use of the VRFY command. Such a string may contain | |
26327 | newlines; it is processed in the same way as an ACL that is read from a | |
26328 | file. | |
26329 | ||
26330 | ||
2813c06e | 26331 | 43.13 ACL return codes |
420a0d19 CE |
26332 | ---------------------- |
26333 | ||
26334 | Except for the QUIT ACL, which does not affect the SMTP return code (see | |
2813c06e | 26335 | section 43.10 above), the result of running an ACL is either "accept" or |
420a0d19 CE |
26336 | "deny", or, if some test cannot be completed (for example, if a database is |
26337 | down), "defer". These results cause 2xx, 5xx, and 4xx return codes, | |
26338 | respectively, to be used in the SMTP dialogue. A fourth return, "error", occurs | |
26339 | when there is an error such as invalid syntax in the ACL. This also causes a 4 | |
26340 | xx return code. | |
26341 | ||
26342 | For the non-SMTP ACL, "defer" and "error" are treated in the same way as | |
26343 | "deny", because there is no mechanism for passing temporary errors to the | |
26344 | submitters of non-SMTP messages. | |
26345 | ||
26346 | ACLs that are relevant to message reception may also return "discard". This has | |
26347 | the effect of "accept", but causes either the entire message or an individual | |
26348 | recipient address to be discarded. In other words, it is a blackholing | |
26349 | facility. Use it with care. | |
26350 | ||
26351 | If the ACL for MAIL returns "discard", all recipients are discarded, and no ACL | |
26352 | is run for subsequent RCPT commands. The effect of "discard" in a RCPT ACL is | |
26353 | to discard just the one recipient address. If there are no recipients left when | |
26354 | the message's data is received, the DATA ACL is not run. A "discard" return | |
26355 | from the DATA or the non-SMTP ACL discards all the remaining recipients. The | |
26356 | "discard" return is not permitted for the acl_smtp_predata ACL. | |
26357 | ||
2813c06e CE |
26358 | If the ACL for VRFY returns "accept", a recipient verify (without callout) is |
26359 | done on the address and the result determines the SMTP response. | |
26360 | ||
420a0d19 CE |
26361 | The local_scan() function is always run, even if there are no remaining |
26362 | recipients; it may create new recipients. | |
26363 | ||
26364 | ||
2813c06e | 26365 | 43.14 Unset ACL options |
420a0d19 CE |
26366 | ----------------------- |
26367 | ||
26368 | The default actions when any of the acl_xxx options are unset are not all the | |
26369 | same. Note: These defaults apply only when the relevant ACL is not defined at | |
26370 | all. For any defined ACL, the default action when control reaches the end of | |
26371 | the ACL statements is "deny". | |
26372 | ||
26373 | For acl_smtp_quit and acl_not_smtp_start there is no default because these two | |
26374 | are ACLs that are used only for their side effects. They cannot be used to | |
26375 | accept or reject anything. | |
26376 | ||
26377 | For acl_not_smtp, acl_smtp_auth, acl_smtp_connect, acl_smtp_data, acl_smtp_helo | |
26378 | , acl_smtp_mail, acl_smtp_mailauth, acl_smtp_mime, acl_smtp_predata, and | |
26379 | acl_smtp_starttls, the action when the ACL is not defined is "accept". | |
26380 | ||
26381 | For the others (acl_smtp_etrn, acl_smtp_expn, acl_smtp_rcpt, and acl_smtp_vrfy | |
26382 | ), the action when the ACL is not defined is "deny". This means that | |
26383 | acl_smtp_rcpt must be defined in order to receive any messages over an SMTP | |
26384 | connection. For an example, see the ACL in the default configuration file. | |
26385 | ||
26386 | ||
2813c06e | 26387 | 43.15 Data for message ACLs |
420a0d19 CE |
26388 | --------------------------- |
26389 | ||
26390 | When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables | |
26391 | that contain information about the host and the message's sender (for example, | |
26392 | $sender_host_address and $sender_address) are set, and can be used in ACL | |
26393 | statements. In the case of RCPT (but not MAIL or DATA), $domain and $local_part | |
26394 | are set from the argument address. The entire SMTP command is available in | |
26395 | $smtp_command. | |
26396 | ||
26397 | When an ACL for the AUTH parameter of MAIL is running, the variables that | |
26398 | contain information about the host are set, but $sender_address is not yet set. | |
26399 | Section 33.2 contains a discussion of this parameter and how it is used. | |
26400 | ||
26401 | The $message_size variable is set to the value of the SIZE parameter on the | |
26402 | MAIL command at MAIL, RCPT and pre-data time, or to -1 if that parameter is not | |
26403 | given. The value is updated to the true message size by the time the final DATA | |
26404 | ACL is run (after the message data has been received). | |
26405 | ||
26406 | The $rcpt_count variable increases by one for each RCPT command received. The | |
26407 | $recipients_count variable increases by one each time a RCPT command is | |
26408 | accepted, so while an ACL for RCPT is being processed, it contains the number | |
26409 | of previously accepted recipients. At DATA time (for both the DATA ACLs), | |
26410 | $rcpt_count contains the total number of RCPT commands, and $recipients_count | |
26411 | contains the total number of accepted recipients. | |
26412 | ||
26413 | ||
2813c06e | 26414 | 43.16 Data for non-message ACLs |
420a0d19 CE |
26415 | ------------------------------- |
26416 | ||
26417 | When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY, | |
26418 | the remainder of the SMTP command line is placed in $smtp_command_argument, and | |
26419 | the entire SMTP command is available in $smtp_command. These variables can be | |
26420 | tested using a condition condition. For example, here is an ACL for use with | |
26421 | AUTH, which insists that either the session is encrypted, or the CRAM-MD5 | |
26422 | authentication method is used. In other words, it does not permit | |
26423 | authentication methods that use cleartext passwords on unencrypted connections. | |
26424 | ||
26425 | acl_check_auth: | |
26426 | accept encrypted = * | |
26427 | accept condition = ${if eq{${uc:$smtp_command_argument}}\ | |
26428 | {CRAM-MD5}} | |
26429 | deny message = TLS encryption or CRAM-MD5 required | |
26430 | ||
26431 | (Another way of applying this restriction is to arrange for the authenticators | |
26432 | that use cleartext passwords not to be advertised when the connection is not | |
26433 | encrypted. You can use the generic server_advertise_condition authenticator | |
26434 | option to do this.) | |
26435 | ||
26436 | ||
2813c06e | 26437 | 43.17 Format of an ACL |
420a0d19 CE |
26438 | ---------------------- |
26439 | ||
26440 | An individual ACL consists of a number of statements. Each statement starts | |
26441 | with a verb, optionally followed by a number of conditions and "modifiers". | |
26442 | Modifiers can change the way the verb operates, define error and log messages, | |
26443 | set variables, insert delays, and vary the processing of accepted messages. | |
26444 | ||
26445 | If all the conditions are met, the verb is obeyed. The same condition may be | |
26446 | used (with different arguments) more than once in the same statement. This | |
26447 | provides a means of specifying an "and" conjunction between conditions. For | |
26448 | example: | |
26449 | ||
26450 | deny dnslists = list1.example | |
2813c06e | 26451 | dnslists = list2.example |
420a0d19 CE |
26452 | |
26453 | If there are no conditions, the verb is always obeyed. Exim stops evaluating | |
26454 | the conditions and modifiers when it reaches a condition that fails. What | |
26455 | happens then depends on the verb (and in one case, on a special modifier). Not | |
26456 | all the conditions make sense at every testing point. For example, you cannot | |
26457 | test a sender address in the ACL that is run for a VRFY command. | |
26458 | ||
26459 | ||
2813c06e | 26460 | 43.18 ACL verbs |
420a0d19 CE |
26461 | --------------- |
26462 | ||
26463 | The ACL verbs are as follows: | |
26464 | ||
26465 | * accept: If all the conditions are met, the ACL returns "accept". If any of | |
26466 | the conditions are not met, what happens depends on whether endpass appears | |
26467 | among the conditions (for syntax see below). If the failing condition is | |
26468 | before endpass, control is passed to the next ACL statement; if it is after | |
26469 | endpass, the ACL returns "deny". Consider this statement, used to check a | |
26470 | RCPT command: | |
26471 | ||
26472 | accept domains = +local_domains | |
2813c06e CE |
26473 | endpass |
26474 | verify = recipient | |
420a0d19 CE |
26475 | |
26476 | If the recipient domain does not match the domains condition, control | |
26477 | passes to the next statement. If it does match, the recipient is verified, | |
26478 | and the command is accepted if verification succeeds. However, if | |
26479 | verification fails, the ACL yields "deny", because the failing condition is | |
26480 | after endpass. | |
26481 | ||
26482 | The endpass feature has turned out to be confusing to many people, so its | |
26483 | use is not recommended nowadays. It is always possible to rewrite an ACL so | |
26484 | that endpass is not needed, and it is no longer used in the default | |
26485 | configuration. | |
26486 | ||
26487 | If a message modifier appears on an accept statement, its action depends on | |
26488 | whether or not endpass is present. In the absence of endpass (when an | |
26489 | accept verb either accepts or passes control to the next statement), | |
26490 | message can be used to vary the message that is sent when an SMTP command | |
26491 | is accepted. For example, in a RCPT ACL you could have: | |
26492 | ||
26493 | accept <some conditions> | |
26494 | message = OK, I will allow you through today | |
26495 | ||
26496 | You can specify an SMTP response code, optionally followed by an "extended | |
26497 | response code" at the start of the message, but the first digit must be the | |
26498 | same as would be sent by default, which is 2 for an accept verb. | |
26499 | ||
26500 | If endpass is present in an accept statement, message specifies an error | |
26501 | message that is used when access is denied. This behaviour is retained for | |
26502 | backward compatibility, but current "best practice" is to avoid the use of | |
26503 | endpass. | |
26504 | ||
26505 | * defer: If all the conditions are true, the ACL returns "defer" which, in an | |
26506 | SMTP session, causes a 4xx response to be given. For a non-SMTP ACL, defer | |
26507 | is the same as deny, because there is no way of sending a temporary error. | |
26508 | For a RCPT command, defer is much the same as using a redirect router and | |
26509 | ":defer:" while verifying, but the defer verb can be used in any ACL, and | |
26510 | even for a recipient it might be a simpler approach. | |
26511 | ||
26512 | * deny: If all the conditions are met, the ACL returns "deny". If any of the | |
26513 | conditions are not met, control is passed to the next ACL statement. For | |
26514 | example, | |
26515 | ||
26516 | deny dnslists = blackholes.mail-abuse.org | |
26517 | ||
26518 | rejects commands from hosts that are on a DNS black list. | |
26519 | ||
26520 | * discard: This verb behaves like accept, except that it returns "discard" | |
26521 | from the ACL instead of "accept". It is permitted only on ACLs that are | |
26522 | concerned with receiving messages. When all the conditions are true, the | |
26523 | sending entity receives a "success" response. However, discard causes | |
26524 | recipients to be discarded. If it is used in an ACL for RCPT, just the one | |
26525 | recipient is discarded; if used for MAIL, DATA or in the non-SMTP ACL, all | |
26526 | the message's recipients are discarded. Recipients that are discarded | |
26527 | before DATA do not appear in the log line when the received_recipients log | |
26528 | selector is set. | |
26529 | ||
26530 | If the log_message modifier is set when discard operates, its contents are | |
26531 | added to the line that is automatically written to the log. The message | |
26532 | modifier operates exactly as it does for accept. | |
26533 | ||
26534 | * drop: This verb behaves like deny, except that an SMTP connection is | |
26535 | forcibly closed after the 5xx error message has been sent. For example: | |
26536 | ||
26537 | drop message = I don't take more than 20 RCPTs | |
26538 | condition = ${if > {$rcpt_count}{20}} | |
26539 | ||
26540 | There is no difference between deny and drop for the connect-time ACL. The | |
26541 | connection is always dropped after sending a 550 response. | |
26542 | ||
26543 | * require: If all the conditions are met, control is passed to the next ACL | |
26544 | statement. If any of the conditions are not met, the ACL returns "deny". | |
26545 | For example, when checking a RCPT command, | |
26546 | ||
26547 | require message = Sender did not verify | |
26548 | verify = sender | |
26549 | ||
26550 | passes control to subsequent statements only if the message's sender can be | |
26551 | verified. Otherwise, it rejects the command. Note the positioning of the | |
26552 | message modifier, before the verify condition. The reason for this is | |
2813c06e | 26553 | discussed in section 43.20. |
420a0d19 CE |
26554 | |
26555 | * warn: If all the conditions are true, a line specified by the log_message | |
26556 | modifier is written to Exim's main log. Control always passes to the next | |
26557 | ACL statement. If any condition is false, the log line is not written. If | |
26558 | an identical log line is requested several times in the same message, only | |
26559 | one copy is actually written to the log. If you want to force duplicates to | |
26560 | be written, use the logwrite modifier instead. | |
26561 | ||
26562 | If log_message is not present, a warn verb just checks its conditions and | |
26563 | obeys any "immediate" modifiers (such as control, set, logwrite, add_header | |
26564 | , and remove_header) that appear before the first failing condition. There | |
2813c06e | 26565 | is more about adding header lines in section 43.24. |
420a0d19 CE |
26566 | |
26567 | If any condition on a warn statement cannot be completed (that is, there is | |
26568 | some sort of defer), the log line specified by log_message is not written. | |
26569 | This does not include the case of a forced failure from a lookup, which is | |
26570 | considered to be a successful completion. After a defer, no further | |
26571 | conditions or modifiers in the warn statement are processed. The incident | |
26572 | is logged, and the ACL continues to be processed, from the next statement | |
26573 | onwards. | |
26574 | ||
26575 | When one of the warn conditions is an address verification that fails, the | |
26576 | text of the verification failure message is in $acl_verify_message. If you | |
26577 | want this logged, you must set it up explicitly. For example: | |
26578 | ||
26579 | warn !verify = sender | |
26580 | log_message = sender verify failed: $acl_verify_message | |
26581 | ||
26582 | At the end of each ACL there is an implicit unconditional deny. | |
26583 | ||
26584 | As you can see from the examples above, the conditions and modifiers are | |
26585 | written one to a line, with the first one on the same line as the verb, and | |
26586 | subsequent ones on following lines. If you have a very long condition, you can | |
26587 | continue it onto several physical lines by the usual backslash continuation | |
26588 | mechanism. It is conventional to align the conditions vertically. | |
26589 | ||
26590 | ||
2813c06e | 26591 | 43.19 ACL variables |
420a0d19 CE |
26592 | ------------------- |
26593 | ||
26594 | There are some special variables that can be set during ACL processing. They | |
26595 | can be used to pass information between different ACLs, different invocations | |
26596 | of the same ACL in the same SMTP connection, and between ACLs and the routers, | |
26597 | transports, and filters that are used to deliver a message. The names of these | |
26598 | variables must begin with $acl_c or $acl_m, followed either by a digit or an | |
26599 | underscore, but the remainder of the name can be any sequence of alphanumeric | |
26600 | characters and underscores that you choose. There is no limit on the number of | |
26601 | ACL variables. The two sets act as follows: | |
26602 | ||
26603 | * The values of those variables whose names begin with $acl_c persist | |
26604 | throughout an SMTP connection. They are never reset. Thus, a value that is | |
26605 | set while receiving one message is still available when receiving the next | |
26606 | message on the same SMTP connection. | |
26607 | ||
26608 | * The values of those variables whose names begin with $acl_m persist only | |
26609 | while a message is being received. They are reset afterwards. They are also | |
26610 | reset by MAIL, RSET, EHLO, HELO, and after starting up a TLS session. | |
26611 | ||
26612 | When a message is accepted, the current values of all the ACL variables are | |
26613 | preserved with the message and are subsequently made available at delivery | |
26614 | time. The ACL variables are set by a modifier called set. For example: | |
26615 | ||
26616 | accept hosts = whatever | |
26617 | set acl_m4 = some value | |
26618 | accept authenticated = * | |
26619 | set acl_c_auth = yes | |
26620 | ||
26621 | Note: A leading dollar sign is not used when naming a variable that is to be | |
26622 | set. If you want to set a variable without taking any action, you can use a | |
26623 | warn verb without any other modifiers or conditions. | |
26624 | ||
26625 | What happens if a syntactically valid but undefined ACL variable is referenced | |
26626 | depends on the setting of the strict_acl_vars option. If it is false (the | |
26627 | default), an empty string is substituted; if it is true, an error is generated. | |
26628 | ||
26629 | Versions of Exim before 4.64 have a limited set of numbered variables, but | |
26630 | their names are compatible, so there is no problem with upgrading. | |
26631 | ||
26632 | ||
2813c06e | 26633 | 43.20 Condition and modifier processing |
420a0d19 CE |
26634 | --------------------------------------- |
26635 | ||
26636 | An exclamation mark preceding a condition negates its result. For example: | |
26637 | ||
26638 | deny domains = *.dom.example | |
26639 | !verify = recipient | |
26640 | ||
26641 | causes the ACL to return "deny" if the recipient domain ends in dom.example and | |
26642 | the recipient address cannot be verified. Sometimes negation can be used on the | |
26643 | right-hand side of a condition. For example, these two statements are | |
26644 | equivalent: | |
26645 | ||
26646 | deny hosts = !192.168.3.4 | |
26647 | deny !hosts = 192.168.3.4 | |
26648 | ||
26649 | However, for many conditions (verify being a good example), only left-hand side | |
26650 | negation of the whole condition is possible. | |
26651 | ||
26652 | The arguments of conditions and modifiers are expanded. A forced failure of an | |
26653 | expansion causes a condition to be ignored, that is, it behaves as if the | |
26654 | condition is true. Consider these two statements: | |
26655 | ||
26656 | accept senders = ${lookup{$host_name}lsearch\ | |
26657 | {/some/file}{$value}fail} | |
26658 | accept senders = ${lookup{$host_name}lsearch\ | |
26659 | {/some/file}{$value}{}} | |
26660 | ||
26661 | Each attempts to look up a list of acceptable senders. If the lookup succeeds, | |
26662 | the returned list is searched, but if the lookup fails the behaviour is | |
26663 | different in the two cases. The fail in the first statement causes the | |
26664 | condition to be ignored, leaving no further conditions. The accept verb | |
26665 | therefore succeeds. The second statement, however, generates an empty list when | |
26666 | the lookup fails. No sender can match an empty list, so the condition fails, | |
26667 | and therefore the accept also fails. | |
26668 | ||
26669 | ACL modifiers appear mixed in with conditions in ACL statements. Some of them | |
26670 | specify actions that are taken as the conditions for a statement are checked; | |
26671 | others specify text for messages that are used when access is denied or a | |
26672 | warning is generated. The control modifier affects the way an incoming message | |
26673 | is handled. | |
26674 | ||
26675 | The positioning of the modifiers in an ACL statement is important, because the | |
26676 | processing of a verb ceases as soon as its outcome is known. Only those | |
26677 | modifiers that have already been encountered will take effect. For example, | |
26678 | consider this use of the message modifier: | |
26679 | ||
26680 | require message = Can't verify sender | |
26681 | verify = sender | |
26682 | message = Can't verify recipient | |
26683 | verify = recipient | |
26684 | message = This message cannot be used | |
26685 | ||
26686 | If sender verification fails, Exim knows that the result of the statement is | |
26687 | "deny", so it goes no further. The first message modifier has been seen, so its | |
26688 | text is used as the error message. If sender verification succeeds, but | |
26689 | recipient verification fails, the second message is used. If recipient | |
26690 | verification succeeds, the third message becomes "current", but is never used | |
26691 | because there are no more conditions to cause failure. | |
26692 | ||
26693 | For the deny verb, on the other hand, it is always the last message modifier | |
26694 | that is used, because all the conditions must be true for rejection to happen. | |
26695 | Specifying more than one message modifier does not make sense, and the message | |
26696 | can even be specified after all the conditions. For example: | |
26697 | ||
26698 | deny hosts = ... | |
26699 | !senders = *@my.domain.example | |
26700 | message = Invalid sender from client host | |
26701 | ||
26702 | The "deny" result does not happen until the end of the statement is reached, by | |
26703 | which time Exim has set up the message. | |
26704 | ||
26705 | ||
2813c06e | 26706 | 43.21 ACL modifiers |
420a0d19 CE |
26707 | ------------------- |
26708 | ||
26709 | The ACL modifiers are as follows: | |
26710 | ||
26711 | add_header = <text> | |
26712 | ||
26713 | This modifier specifies one or more header lines that are to be added to an | |
26714 | incoming message, assuming, of course, that the message is ultimately | |
2813c06e | 26715 | accepted. For details, see section 43.24. |
420a0d19 CE |
26716 | |
26717 | continue = <text> | |
26718 | ||
26719 | This modifier does nothing of itself, and processing of the ACL always | |
26720 | continues with the next condition or modifier. The value of continue is in | |
26721 | the side effects of expanding its argument. Typically this could be used to | |
26722 | update a database. It is really just a syntactic tidiness, to avoid having | |
26723 | to write rather ugly lines like this: | |
26724 | ||
26725 | condition = ${if eq{0}{<some expansion>}{true}{true}} | |
26726 | ||
26727 | Instead, all you need is | |
26728 | ||
26729 | continue = <some expansion> | |
26730 | ||
26731 | control = <text> | |
26732 | ||
26733 | This modifier affects the subsequent processing of the SMTP connection or | |
26734 | of an incoming message that is accepted. The effect of the first type of | |
26735 | control lasts for the duration of the connection, whereas the effect of the | |
26736 | second type lasts only until the current message has been received. The | |
26737 | message-specific controls always apply to the whole message, not to | |
26738 | individual recipients, even if the control modifier appears in a RCPT ACL. | |
26739 | ||
26740 | As there are now quite a few controls that can be applied, they are | |
2813c06e | 26741 | described separately in section 43.22. The control modifier can be used in |
420a0d19 CE |
26742 | several different ways. For example: |
26743 | ||
2813c06e | 26744 | + It can be at the end of an accept statement: |
420a0d19 CE |
26745 | |
26746 | accept ...some conditions | |
26747 | control = queue_only | |
26748 | ||
26749 | In this case, the control is applied when this statement yields | |
26750 | "accept", in other words, when the conditions are all true. | |
26751 | ||
2813c06e | 26752 | + It can be in the middle of an accept statement: |
420a0d19 CE |
26753 | |
26754 | accept ...some conditions... | |
26755 | control = queue_only | |
26756 | ...some more conditions... | |
26757 | ||
26758 | If the first set of conditions are true, the control is applied, even | |
26759 | if the statement does not accept because one of the second set of | |
26760 | conditions is false. In this case, some subsequent statement must yield | |
26761 | "accept" for the control to be relevant. | |
26762 | ||
2813c06e | 26763 | + It can be used with warn to apply the control, leaving the decision |
420a0d19 CE |
26764 | about accepting or denying to a subsequent verb. For example: |
26765 | ||
26766 | warn ...some conditions... | |
26767 | control = freeze | |
26768 | accept ... | |
26769 | ||
26770 | This example of warn does not contain message, log_message, or logwrite | |
26771 | , so it does not add anything to the message and does not write a log | |
26772 | entry. | |
26773 | ||
2813c06e | 26774 | + If you want to apply a control unconditionally, you can use it with a |
420a0d19 CE |
26775 | require verb. For example: |
26776 | ||
26777 | require control = no_multiline_responses | |
26778 | ||
26779 | delay = <time> | |
26780 | ||
26781 | This modifier may appear in any ACL except notquit. It causes Exim to wait | |
26782 | for the time interval before proceeding. However, when testing Exim using | |
26783 | the -bh option, the delay is not actually imposed (an appropriate message | |
26784 | is output instead). The time is given in the usual Exim notation, and the | |
26785 | delay happens as soon as the modifier is processed. In an SMTP session, | |
26786 | pending output is flushed before the delay is imposed. | |
26787 | ||
26788 | Like control, delay can be used with accept or deny, for example: | |
26789 | ||
26790 | deny ...some conditions... | |
26791 | delay = 30s | |
26792 | ||
26793 | The delay happens if all the conditions are true, before the statement | |
26794 | returns "deny". Compare this with: | |
26795 | ||
26796 | deny delay = 30s | |
26797 | ...some conditions... | |
26798 | ||
26799 | which waits for 30s before processing the conditions. The delay modifier | |
26800 | can also be used with warn and together with control: | |
26801 | ||
26802 | warn ...some conditions... | |
26803 | delay = 2m | |
26804 | control = freeze | |
26805 | accept ... | |
26806 | ||
26807 | If delay is encountered when the SMTP PIPELINING extension is in use, | |
26808 | responses to several commands are no longer buffered and sent in one packet | |
26809 | (as they would normally be) because all output is flushed before imposing | |
26810 | the delay. This optimization is disabled so that a number of small delays | |
26811 | do not appear to the client as one large aggregated delay that might | |
26812 | provoke an unwanted timeout. You can, however, disable output flushing for | |
26813 | delay by using a control modifier to set no_delay_flush. | |
26814 | ||
26815 | endpass | |
26816 | ||
26817 | This modifier, which has no argument, is recognized only in accept and | |
26818 | discard statements. It marks the boundary between the conditions whose | |
26819 | failure causes control to pass to the next statement, and the conditions | |
26820 | whose failure causes the ACL to return "deny". This concept has proved to | |
26821 | be confusing to some people, so the use of endpass is no longer recommended | |
26822 | as "best practice". See the description of accept above for more details. | |
26823 | ||
26824 | log_message = <text> | |
26825 | ||
26826 | This modifier sets up a message that is used as part of the log message if | |
26827 | the ACL denies access or a warn statement's conditions are true. For | |
26828 | example: | |
26829 | ||
26830 | require log_message = wrong cipher suite $tls_in_cipher | |
26831 | encrypted = DES-CBC3-SHA | |
26832 | ||
26833 | log_message is also used when recipients are discarded by discard. For | |
26834 | example: | |
26835 | ||
26836 | discard <some conditions> | |
26837 | log_message = Discarded $local_part@$domain because... | |
26838 | ||
26839 | When access is denied, log_message adds to any underlying error message | |
26840 | that may exist because of a condition failure. For example, while verifying | |
26841 | a recipient address, a :fail: redirection might have already set up a | |
26842 | message. | |
26843 | ||
26844 | The message may be defined before the conditions to which it applies, | |
26845 | because the string expansion does not happen until Exim decides that access | |
26846 | is to be denied. This means that any variables that are set by the | |
26847 | condition are available for inclusion in the message. For example, the | |
26848 | $dnslist_<xxx> variables are set after a DNS black list lookup succeeds. If | |
26849 | the expansion of log_message fails, or if the result is an empty string, | |
26850 | the modifier is ignored. | |
26851 | ||
26852 | If you want to use a warn statement to log the result of an address | |
26853 | verification, you can use $acl_verify_message to include the verification | |
26854 | error message. | |
26855 | ||
26856 | If log_message is used with a warn statement, "Warning:" is added to the | |
26857 | start of the logged message. If the same warning log message is requested | |
26858 | more than once while receiving a single email message, only one copy is | |
26859 | actually logged. If you want to log multiple copies, use logwrite instead | |
26860 | of log_message. In the absence of log_message and logwrite, nothing is | |
26861 | logged for a successful warn statement. | |
26862 | ||
26863 | If log_message is not present and there is no underlying error message (for | |
26864 | example, from the failure of address verification), but message is present, | |
26865 | the message text is used for logging rejections. However, if any text for | |
26866 | logging contains newlines, only the first line is logged. In the absence of | |
26867 | both log_message and message, a default built-in message is used for | |
26868 | logging rejections. | |
26869 | ||
26870 | log_reject_target = <log name list> | |
26871 | ||
26872 | This modifier makes it possible to specify which logs are used for messages | |
26873 | about ACL rejections. Its argument is a colon-separated list of words that | |
26874 | can be "main", "reject", or "panic". The default is "main:reject". The list | |
26875 | may be empty, in which case a rejection is not logged at all. For example, | |
26876 | this ACL fragment writes no logging information when access is denied: | |
26877 | ||
26878 | deny <some conditions> | |
26879 | log_reject_target = | |
26880 | ||
26881 | This modifier can be used in SMTP and non-SMTP ACLs. It applies to both | |
26882 | permanent and temporary rejections. Its effect lasts for the rest of the | |
26883 | current ACL. | |
26884 | ||
26885 | logwrite = <text> | |
26886 | ||
26887 | This modifier writes a message to a log file as soon as it is encountered | |
26888 | when processing an ACL. (Compare log_message, which, except in the case of | |
26889 | warn and discard, is used only if the ACL statement denies access.) The | |
26890 | logwrite modifier can be used to log special incidents in ACLs. For | |
26891 | example: | |
26892 | ||
26893 | accept <some special conditions> | |
26894 | control = freeze | |
26895 | logwrite = froze message because ... | |
26896 | ||
26897 | By default, the message is written to the main log. However, it may begin | |
26898 | with a colon, followed by a comma-separated list of log names, and then | |
26899 | another colon, to specify exactly which logs are to be written. For | |
26900 | example: | |
26901 | ||
26902 | logwrite = :main,reject: text for main and reject logs | |
26903 | logwrite = :panic: text for panic log only | |
26904 | ||
26905 | message = <text> | |
26906 | ||
26907 | This modifier sets up a text string that is expanded and used as a response | |
26908 | message when an ACL statement terminates the ACL with an "accept", "deny", | |
26909 | or "defer" response. (In the case of the accept and discard verbs, there is | |
26910 | some complication if endpass is involved; see the description of accept for | |
26911 | details.) | |
26912 | ||
26913 | The expansion of the message happens at the time Exim decides that the ACL | |
26914 | is to end, not at the time it processes message. If the expansion fails, or | |
26915 | generates an empty string, the modifier is ignored. Here is an example | |
26916 | where message must be specified first, because the ACL ends with a | |
26917 | rejection if the hosts condition fails: | |
26918 | ||
26919 | require message = Host not recognized | |
26920 | hosts = 10.0.0.0/8 | |
26921 | ||
26922 | (Once a condition has failed, no further conditions or modifiers are | |
26923 | processed.) | |
26924 | ||
26925 | For ACLs that are triggered by SMTP commands, the message is returned as | |
26926 | part of the SMTP response. The use of message with accept (or discard) is | |
26927 | meaningful only for SMTP, as no message is returned when a non-SMTP message | |
26928 | is accepted. In the case of the connect ACL, accepting with a message | |
26929 | modifier overrides the value of smtp_banner. For the EHLO/HELO ACL, a | |
26930 | customized accept message may not contain more than one line (otherwise it | |
26931 | will be truncated at the first newline and a panic logged), and it cannot | |
26932 | affect the EHLO options. | |
26933 | ||
26934 | When SMTP is involved, the message may begin with an overriding response | |
26935 | code, consisting of three digits optionally followed by an "extended | |
26936 | response code" of the form n.n.n, each code being followed by a space. For | |
26937 | example: | |
26938 | ||
26939 | deny message = 599 1.2.3 Host not welcome | |
26940 | hosts = 192.168.34.0/24 | |
26941 | ||
26942 | The first digit of the supplied response code must be the same as would be | |
26943 | sent by default. A panic occurs if it is not. Exim uses a 550 code when it | |
26944 | denies access, but for the predata ACL, note that the default success code | |
26945 | is 354, not 2xx. | |
26946 | ||
26947 | Notwithstanding the previous paragraph, for the QUIT ACL, unlike the | |
26948 | others, the message modifier cannot override the 221 response code. | |
26949 | ||
26950 | The text in a message modifier is literal; any quotes are taken as | |
26951 | literals, but because the string is expanded, backslash escapes are | |
26952 | processed anyway. If the message contains newlines, this gives rise to a | |
26953 | multi-line SMTP response. | |
26954 | ||
2813c06e CE |
26955 | For ACLs that are called by an acl = ACL condition, the message is stored |
26956 | in $acl_verify_message, from which the calling ACL may use it. | |
26957 | ||
420a0d19 CE |
26958 | If message is used on a statement that verifies an address, the message |
26959 | specified overrides any message that is generated by the verification | |
26960 | process. However, the original message is available in the variable | |
26961 | $acl_verify_message, so you can incorporate it into your message if you | |
26962 | wish. In particular, if you want the text from :fail: items in redirect | |
26963 | routers to be passed back as part of the SMTP response, you should either | |
26964 | not use a message modifier, or make use of $acl_verify_message. | |
26965 | ||
26966 | For compatibility with previous releases of Exim, a message modifier that | |
26967 | is used with a warn verb behaves in a similar way to the add_header | |
26968 | modifier, but this usage is now deprecated. However, message acts only when | |
26969 | all the conditions are true, wherever it appears in an ACL command, whereas | |
26970 | add_header acts as soon as it is encountered. If message is used with warn | |
26971 | in an ACL that is not concerned with receiving a message, it has no effect. | |
26972 | ||
2813c06e CE |
26973 | queue = <text> |
26974 | ||
26975 | This modifier specifies the use of a named queue for spool files for the | |
26976 | message. It can only be used before the message is received (i.e. not in | |
26977 | the DATA ACL). This could be used, for example, for known high-volume burst | |
26978 | sources of traffic, or for quarantine of messages. Separate queue-runner | |
26979 | processes will be needed for named queues. If the text after expansion is | |
26980 | empty, the default queue is used. | |
26981 | ||
420a0d19 CE |
26982 | remove_header = <text> |
26983 | ||
26984 | This modifier specifies one or more header names in a colon-separated list | |
26985 | that are to be removed from an incoming message, assuming, of course, that | |
2813c06e | 26986 | the message is ultimately accepted. For details, see section 43.25. |
420a0d19 CE |
26987 | |
26988 | set <acl_name> = <value> | |
26989 | ||
2813c06e | 26990 | This modifier puts a value into one of the ACL variables (see section 43.19 |
420a0d19 CE |
26991 | ). |
26992 | ||
26993 | udpsend = <parameters> | |
26994 | ||
26995 | This modifier sends a UDP packet, for purposes such as statistics | |
26996 | collection or behaviour monitoring. The parameters are expanded, and the | |
26997 | result of the expansion must be a colon-separated list consisting of a | |
26998 | destination server, port number, and the packet contents. The server can be | |
26999 | specified as a host name or IPv4 or IPv6 address. The separator can be | |
27000 | changed with the usual angle bracket syntax. For example, you might want to | |
27001 | collect information on which hosts connect when: | |
27002 | ||
27003 | udpsend = <; 2001:dB8::dead:beef ; 1234 ;\ | |
27004 | $tod_zulu $sender_host_address | |
27005 | ||
27006 | ||
2813c06e | 27007 | 43.22 Use of the control modifier |
420a0d19 CE |
27008 | --------------------------------- |
27009 | ||
27010 | The control modifier supports the following settings: | |
27011 | ||
27012 | control = allow_auth_unadvertised | |
27013 | ||
27014 | This modifier allows a client host to use the SMTP AUTH command even when | |
27015 | it has not been advertised in response to EHLO. Furthermore, because there | |
27016 | are apparently some really broken clients that do this, Exim will accept | |
27017 | AUTH after HELO (rather than EHLO) when this control is set. It should be | |
27018 | used only if you really need it, and you should limit its use to those | |
27019 | broken clients that do not work without it. For example: | |
27020 | ||
27021 | warn hosts = 192.168.34.25 | |
27022 | control = allow_auth_unadvertised | |
27023 | ||
27024 | Normally, when an Exim server receives an AUTH command, it checks the name | |
27025 | of the authentication mechanism that is given in the command to ensure that | |
27026 | it matches an advertised mechanism. When this control is set, the check | |
27027 | that a mechanism has been advertised is bypassed. Any configured mechanism | |
27028 | can be used by the client. This control is permitted only in the connection | |
27029 | and HELO ACLs. | |
27030 | ||
27031 | control = caseful_local_part, control = caselower_local_part | |
27032 | ||
27033 | These two controls are permitted only in the ACL specified by acl_smtp_rcpt | |
27034 | (that is, during RCPT processing). By default, the contents of $local_part | |
27035 | are lower cased before ACL processing. If "caseful_local_part" is | |
27036 | specified, any uppercase letters in the original local part are restored in | |
27037 | $local_part for the rest of the ACL, or until a control that sets | |
27038 | "caselower_local_part" is encountered. | |
27039 | ||
27040 | These controls affect only the current recipient. Moreover, they apply only | |
27041 | to local part handling that takes place directly in the ACL (for example, | |
27042 | as a key in lookups). If a test to verify the recipient is obeyed, the | |
27043 | case-related handling of the local part during the verification is | |
27044 | controlled by the router configuration (see the caseful_local_part generic | |
27045 | router option). | |
27046 | ||
27047 | This facility could be used, for example, to add a spam score to local | |
27048 | parts containing upper case letters. For example, using $acl_m4 to | |
27049 | accumulate the spam score: | |
27050 | ||
27051 | warn control = caseful_local_part | |
27052 | set acl_m4 = ${eval:\ | |
27053 | $acl_m4 + \ | |
27054 | ${if match{$local_part}{[A-Z]}{1}{0}}\ | |
27055 | } | |
27056 | control = caselower_local_part | |
27057 | ||
27058 | Notice that we put back the lower cased version afterwards, assuming that | |
27059 | is what is wanted for subsequent tests. | |
27060 | ||
2813c06e | 27061 | control = cutthrough_delivery/<options> |
420a0d19 CE |
27062 | |
27063 | This option requests delivery be attempted while the item is being | |
2813c06e CE |
27064 | received. |
27065 | ||
27066 | The option is usable in the RCPT ACL. If enabled for a message received via | |
27067 | smtp and routed to an smtp transport, and only one transport, interface, | |
27068 | destination host and port combination is used for all recipients of the | |
27069 | message, then the delivery connection is made while the receiving | |
27070 | connection is open and data is copied from one to the other. | |
27071 | ||
27072 | An attempt to set this option for any recipient but the first for a mail | |
27073 | will be quietly ignored. If a recipient-verify callout (with use_sender) | |
27074 | connection is subsequently requested in the same ACL it is held open and | |
27075 | used for any subsequent recipients and the data, otherwise one is made | |
27076 | after the initial RCPT ACL completes. | |
420a0d19 CE |
27077 | |
27078 | Note that routers are used in verify mode, and cannot depend on content of | |
27079 | received headers. Note also that headers cannot be modified by any of the | |
27080 | post-data ACLs (DATA, MIME and DKIM). Headers may be modified by routers | |
27081 | (subject to the above) and transports. | |
27082 | ||
2813c06e CE |
27083 | All the usual ACLs are called; if one results in the message being |
27084 | rejected, all effort spent in delivery (including the costs on the ultimate | |
27085 | destination) will be wasted. Note that in the case of data-time ACLs this | |
27086 | includes the entire message body. | |
27087 | ||
420a0d19 CE |
27088 | Cutthrough delivery is not supported via transport-filters or when DKIM |
27089 | signing of outgoing messages is done, because it sends data to the ultimate | |
2813c06e CE |
27090 | destination before the entire message has been received from the source. It |
27091 | is not supported for messages received with the SMTP PRDR | |
27092 | ||
27093 | or CHUNKING | |
27094 | ||
27095 | options in use. | |
420a0d19 CE |
27096 | |
27097 | Should the ultimate destination system positively accept or reject the | |
27098 | mail, a corresponding indication is given to the source system and nothing | |
2813c06e CE |
27099 | is queued. If the item is successfully delivered in cutthrough mode the |
27100 | delivery log lines are tagged with ">>" rather than "=>" and appear before | |
27101 | the acceptance "<=" line. | |
27102 | ||
27103 | If there is a temporary error the item is queued for later delivery in the | |
27104 | usual fashion. This behaviour can be adjusted by appending the option defer | |
27105 | =<value> to the control; the default value is "spool" and the alternate | |
27106 | value "pass" copies an SMTP defer response from the target back to the | |
27107 | initiator and does not queue the message. Note that this is independent of | |
27108 | any recipient verify conditions in the ACL. | |
420a0d19 CE |
27109 | |
27110 | Delivery in this mode avoids the generation of a bounce mail to a (possibly | |
27111 | faked) sender when the destination system is doing content-scan based | |
27112 | rejection. | |
27113 | ||
27114 | control = debug/<options> | |
27115 | ||
27116 | This control turns on debug logging, almost as though Exim had been invoked | |
27117 | with "-d", with the output going to a new logfile, by default called | |
27118 | debuglog. The filename can be adjusted with the tag option, which may | |
27119 | access any variables already defined. The logging may be adjusted with the | |
27120 | opts option, which takes the same values as the "-d" command-line option. | |
2813c06e CE |
27121 | Logging may be stopped, and the file removed, with the kill option. Some |
27122 | examples (which depend on variables that don't exist in all contexts): | |
420a0d19 CE |
27123 | |
27124 | control = debug | |
27125 | control = debug/tag=.$sender_host_address | |
27126 | control = debug/opts=+expand+acl | |
27127 | control = debug/tag=.$message_exim_id/opts=+expand | |
2813c06e | 27128 | control = debug/kill |
420a0d19 CE |
27129 | |
27130 | control = dkim_disable_verify | |
27131 | ||
27132 | This control turns off DKIM verification processing entirely. For details | |
2813c06e | 27133 | on the operation and configuration of DKIM, see chapter 57. |
420a0d19 CE |
27134 | |
27135 | control = dscp/<value> | |
27136 | ||
27137 | This option causes the DSCP value associated with the socket for the | |
27138 | inbound connection to be adjusted to a given value, given as one of a | |
27139 | number of fixed strings or to numeric value. The -bI:dscp option may be | |
27140 | used to ask Exim which names it knows of. Common values include | |
27141 | "throughput", "mincost", and on newer systems "ef", "af41", etc. Numeric | |
27142 | values may be in the range 0 to 0x3F. | |
27143 | ||
27144 | The outbound packets from Exim will be marked with this value in the header | |
27145 | (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no | |
27146 | guarantee that these values will have any effect, not be stripped by | |
27147 | networking equipment, or do much of anything without cooperation with your | |
27148 | Network Engineer and those of all network operators between the source and | |
27149 | destination. | |
27150 | ||
27151 | control = enforce_sync, control = no_enforce_sync | |
27152 | ||
27153 | These controls make it possible to be selective about when SMTP | |
27154 | synchronization is enforced. The global option smtp_enforce_sync specifies | |
27155 | the initial state of the switch (it is true by default). See the | |
27156 | description of this option in chapter 14 for details of SMTP | |
27157 | synchronization checking. | |
27158 | ||
27159 | The effect of these two controls lasts for the remainder of the SMTP | |
27160 | connection. They can appear in any ACL except the one for the non-SMTP | |
27161 | messages. The most straightforward place to put them is in the ACL defined | |
27162 | by acl_smtp_connect, which is run at the start of an incoming SMTP | |
27163 | connection, before the first synchronization check. The expected use is to | |
27164 | turn off the synchronization checks for badly-behaved hosts that you | |
27165 | nevertheless need to work with. | |
27166 | ||
27167 | control = fakedefer/<message> | |
27168 | ||
27169 | This control works in exactly the same way as fakereject (described below) | |
27170 | except that it causes an SMTP 450 response after the message data instead | |
27171 | of a 550 response. You must take care when using fakedefer because it | |
27172 | causes the messages to be duplicated when the sender retries. Therefore, | |
27173 | you should not use fakedefer if the message is to be delivered normally. | |
27174 | ||
27175 | control = fakereject/<message> | |
27176 | ||
27177 | This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other | |
27178 | words, only when an SMTP message is being received. If Exim accepts the | |
27179 | message, instead the final 250 response, a 550 rejection message is sent. | |
27180 | However, Exim proceeds to deliver the message as normal. The control | |
27181 | applies only to the current message, not to any subsequent ones that may be | |
27182 | received in the same SMTP connection. | |
27183 | ||
27184 | The text for the 550 response is taken from the control modifier. If no | |
27185 | message is supplied, the following is used: | |
27186 | ||
27187 | 550-Your message has been rejected but is being | |
27188 | 550-kept for evaluation. | |
27189 | 550-If it was a legitimate message, it may still be | |
27190 | 550 delivered to the target recipient(s). | |
27191 | ||
27192 | This facility should be used with extreme caution. | |
27193 | ||
27194 | control = freeze | |
27195 | ||
27196 | This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, | |
27197 | in other words, only when a message is being received. If the message is | |
27198 | accepted, it is placed on Exim's queue and frozen. The control applies only | |
27199 | to the current message, not to any subsequent ones that may be received in | |
27200 | the same SMTP connection. | |
27201 | ||
27202 | This modifier can optionally be followed by "/no_tell". If the global | |
27203 | option freeze_tell is set, it is ignored for the current message (that is, | |
27204 | nobody is told about the freezing), provided all the control=freeze | |
27205 | modifiers that are obeyed for the current message have the "/no_tell" | |
27206 | option. | |
27207 | ||
27208 | control = no_delay_flush | |
27209 | ||
27210 | Exim normally flushes SMTP output before implementing a delay in an ACL, to | |
27211 | avoid unexpected timeouts in clients when the SMTP PIPELINING extension is | |
27212 | in use. This control, as long as it is encountered before the delay | |
27213 | modifier, disables such output flushing. | |
27214 | ||
27215 | control = no_callout_flush | |
27216 | ||
27217 | Exim normally flushes SMTP output before performing a callout in an ACL, to | |
27218 | avoid unexpected timeouts in clients when the SMTP PIPELINING extension is | |
27219 | in use. This control, as long as it is encountered before the verify | |
27220 | condition that causes the callout, disables such output flushing. | |
27221 | ||
27222 | control = no_mbox_unspool | |
27223 | ||
27224 | This control is available when Exim is compiled with the content scanning | |
27225 | extension. Content scanning may require a copy of the current message, or | |
27226 | parts of it, to be written in "mbox format" to a spool file, for passing to | |
27227 | a virus or spam scanner. Normally, such copies are deleted when they are no | |
27228 | longer needed. If this control is set, the copies are not deleted. The | |
27229 | control applies only to the current message, not to any subsequent ones | |
27230 | that may be received in the same SMTP connection. It is provided for | |
27231 | debugging purposes and is unlikely to be useful in production. | |
27232 | ||
27233 | control = no_multiline_responses | |
27234 | ||
27235 | This control is permitted for any ACL except the one for non-SMTP messages. | |
27236 | It seems that there are broken clients in use that cannot handle multiline | |
27237 | SMTP responses, despite the fact that RFC 821 defined them over 20 years | |
27238 | ago. | |
27239 | ||
27240 | If this control is set, multiline SMTP responses from ACL rejections are | |
27241 | suppressed. One way of doing this would have been to put out these | |
27242 | responses as one long line. However, RFC 2821 specifies a maximum of 512 | |
27243 | bytes per response ("use multiline responses for more" it says - ha!), and | |
27244 | some of the responses might get close to that. So this facility, which is | |
27245 | after all only a sop to broken clients, is implemented by doing two very | |
27246 | easy things: | |
27247 | ||
2813c06e | 27248 | + Extra information that is normally output as part of a rejection caused |
420a0d19 CE |
27249 | by sender verification failure is omitted. Only the final line |
27250 | (typically "sender verification failed") is sent. | |
27251 | ||
2813c06e | 27252 | + If a message modifier supplies a multiline response, only the first |
420a0d19 CE |
27253 | line is output. |
27254 | ||
27255 | The setting of the switch can, of course, be made conditional on the | |
27256 | calling host. Its effect lasts until the end of the SMTP connection. | |
27257 | ||
27258 | control = no_pipelining | |
27259 | ||
27260 | This control turns off the advertising of the PIPELINING extension to SMTP | |
27261 | in the current session. To be useful, it must be obeyed before Exim sends | |
27262 | its response to an EHLO command. Therefore, it should normally appear in an | |
27263 | ACL controlled by acl_smtp_connect or acl_smtp_helo. See also | |
27264 | pipelining_advertise_hosts. | |
27265 | ||
27266 | control = queue_only | |
27267 | ||
27268 | This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, | |
27269 | in other words, only when a message is being received. If the message is | |
27270 | accepted, it is placed on Exim's queue and left there for delivery by a | |
27271 | subsequent queue runner. No immediate delivery process is started. In other | |
27272 | words, it has the effect as the queue_only global option. However, the | |
27273 | control applies only to the current message, not to any subsequent ones | |
27274 | that may be received in the same SMTP connection. | |
27275 | ||
27276 | control = submission/<options> | |
27277 | ||
27278 | This control is permitted only for the MAIL, RCPT, and start of data ACLs | |
27279 | (the latter is the one defined by acl_smtp_predata). Setting it tells Exim | |
27280 | that the current message is a submission from a local MUA. In this case, | |
27281 | Exim operates in "submission mode", and applies certain fixups to the | |
27282 | message if necessary. For example, it adds a Date: header line if one is | |
27283 | not present. This control is not permitted in the acl_smtp_data ACL, | |
27284 | because that is too late (the message has already been created). | |
27285 | ||
2813c06e CE |
27286 | Chapter 47 describes the processing that Exim applies to messages. Section |
27287 | 47.1 covers the processing that happens in submission mode; the available | |
420a0d19 CE |
27288 | options for this control are described there. The control applies only to |
27289 | the current message, not to any subsequent ones that may be received in the | |
27290 | same SMTP connection. | |
27291 | ||
27292 | control = suppress_local_fixups | |
27293 | ||
27294 | This control applies to locally submitted (non TCP/IP) messages, and is the | |
27295 | complement of "control = submission". It disables the fixups that are | |
27296 | normally applied to locally-submitted messages. Specifically: | |
27297 | ||
2813c06e | 27298 | + Any Sender: header line is left alone (in this respect, it is a dynamic |
420a0d19 CE |
27299 | version of local_sender_retain). |
27300 | ||
2813c06e | 27301 | + No Message-ID:, From:, or Date: header lines are added. |
420a0d19 | 27302 | |
2813c06e | 27303 | + There is no check that From: corresponds to the actual sender. |
420a0d19 CE |
27304 | |
27305 | This control may be useful when a remotely-originated message is accepted, | |
27306 | passed to some scanning program, and then re-submitted for delivery. It can | |
27307 | be used only in the acl_smtp_mail, acl_smtp_rcpt, acl_smtp_predata, and | |
27308 | acl_not_smtp_start ACLs, because it has to be set before the message's data | |
27309 | is read. | |
27310 | ||
27311 | Note: This control applies only to the current message, not to any others | |
27312 | that are being submitted at the same time using -bs or -bS. | |
27313 | ||
2813c06e CE |
27314 | control = utf8_downconvert |
27315 | ||
27316 | This control enables conversion of UTF-8 in message addresses to a-label | |
27317 | form. For details see section 59.1. | |
27318 | ||
420a0d19 | 27319 | |
2813c06e | 27320 | 43.23 Summary of message fixup control |
420a0d19 CE |
27321 | -------------------------------------- |
27322 | ||
27323 | All four possibilities for message fixups can be specified: | |
27324 | ||
27325 | * Locally submitted, fixups applied: the default. | |
27326 | ||
27327 | * Locally submitted, no fixups applied: use "control = | |
27328 | suppress_local_fixups". | |
27329 | ||
27330 | * Remotely submitted, no fixups applied: the default. | |
27331 | ||
27332 | * Remotely submitted, fixups applied: use "control = submission". | |
27333 | ||
27334 | ||
2813c06e | 27335 | 43.24 Adding header lines in ACLs |
420a0d19 CE |
27336 | --------------------------------- |
27337 | ||
27338 | The add_header modifier can be used to add one or more extra header lines to an | |
27339 | incoming message, as in this example: | |
27340 | ||
27341 | warn dnslists = sbl.spamhaus.org : \ | |
27342 | dialup.mail-abuse.org | |
27343 | add_header = X-blacklisted-at: $dnslist_domain | |
27344 | ||
27345 | The add_header modifier is permitted in the MAIL, RCPT, PREDATA, DATA, MIME, | |
27346 | DKIM, and non-SMTP ACLs (in other words, those that are concerned with | |
27347 | receiving a message). The message must ultimately be accepted for add_header to | |
27348 | have any significant effect. You can use add_header with any ACL verb, | |
27349 | including deny (though this is potentially useful only in a RCPT ACL). | |
27350 | ||
27351 | Headers will not be added to the message if the modifier is used in DATA, MIME | |
2813c06e | 27352 | or DKIM ACLs for a message delivered by cutthrough routing. |
420a0d19 CE |
27353 | |
27354 | Leading and trailing newlines are removed from the data for the add_header | |
27355 | modifier; if it then contains one or more newlines that are not followed by a | |
27356 | space or a tab, it is assumed to contain multiple header lines. Each one is | |
27357 | checked for valid syntax; "X-ACL-Warn:" is added to the front of any line that | |
27358 | is not a valid header line. | |
27359 | ||
27360 | Added header lines are accumulated during the MAIL, RCPT, and predata ACLs. | |
27361 | They are added to the message before processing the DATA and MIME ACLs. | |
27362 | However, if an identical header line is requested more than once, only one copy | |
27363 | is actually added to the message. Further header lines may be accumulated | |
27364 | during the DATA and MIME ACLs, after which they are added to the message, again | |
27365 | with duplicates suppressed. Thus, it is possible to add two identical header | |
27366 | lines to an SMTP message, but only if one is added before DATA and one after. | |
27367 | In the case of non-SMTP messages, new headers are accumulated during the | |
27368 | non-SMTP ACLs, and are added to the message after all the ACLs have run. If a | |
27369 | message is rejected after DATA or by the non-SMTP ACL, all added header lines | |
27370 | are included in the entry that is written to the reject log. | |
27371 | ||
27372 | Header lines are not visible in string expansions of message headers until they | |
27373 | are added to the message. It follows that header lines defined in the MAIL, | |
27374 | RCPT, and predata ACLs are not visible until the DATA ACL and MIME ACLs are | |
27375 | run. Similarly, header lines that are added by the DATA or MIME ACLs are not | |
27376 | visible in those ACLs. Because of this restriction, you cannot use header lines | |
27377 | as a way of passing data between (for example) the MAIL and RCPT ACLs. If you | |
2813c06e | 27378 | want to do this, you can use ACL variables, as described in section 43.19. |
420a0d19 CE |
27379 | |
27380 | The list of headers yet to be added is given by the $headers_added variable. | |
27381 | ||
27382 | The add_header modifier acts immediately as it is encountered during the | |
27383 | processing of an ACL. Notice the difference between these two cases: | |
27384 | ||
27385 | accept add_header = ADDED: some text | |
27386 | <some condition> | |
27387 | ||
27388 | accept <some condition> | |
27389 | add_header = ADDED: some text | |
27390 | ||
27391 | In the first case, the header line is always added, whether or not the | |
27392 | condition is true. In the second case, the header line is added only if the | |
27393 | condition is true. Multiple occurrences of add_header may occur in the same ACL | |
27394 | statement. All those that are encountered before a condition fails are | |
27395 | honoured. | |
27396 | ||
27397 | For compatibility with previous versions of Exim, a message modifier for a warn | |
27398 | verb acts in the same way as add_header, except that it takes effect only if | |
27399 | all the conditions are true, even if it appears before some of them. | |
27400 | Furthermore, only the last occurrence of message is honoured. This usage of | |
27401 | message is now deprecated. If both add_header and message are present on a warn | |
27402 | verb, both are processed according to their specifications. | |
27403 | ||
27404 | By default, new header lines are added to a message at the end of the existing | |
27405 | header lines. However, you can specify that any particular header line should | |
27406 | be added right at the start (before all the Received: lines), immediately after | |
27407 | the first block of Received: lines, or immediately before any line that is not | |
27408 | a Received: or Resent-something: header. | |
27409 | ||
27410 | This is done by specifying ":at_start:", ":after_received:", or | |
27411 | ":at_start_rfc:" (or, for completeness, ":at_end:") before the text of the | |
27412 | header line, respectively. (Header text cannot start with a colon, as there has | |
27413 | to be a header name first.) For example: | |
27414 | ||
27415 | warn add_header = \ | |
27416 | :after_received:X-My-Header: something or other... | |
27417 | ||
27418 | If more than one header line is supplied in a single add_header modifier, each | |
27419 | one is treated independently and can therefore be placed differently. If you | |
27420 | add more than one line at the start, or after the Received: block, they end up | |
27421 | in reverse order. | |
27422 | ||
27423 | Warning: This facility currently applies only to header lines that are added in | |
27424 | an ACL. It does NOT work for header lines that are added in a system filter or | |
27425 | in a router or transport. | |
27426 | ||
27427 | ||
2813c06e | 27428 | 43.25 Removing header lines in ACLs |
420a0d19 CE |
27429 | ----------------------------------- |
27430 | ||
27431 | The remove_header modifier can be used to remove one or more header lines from | |
27432 | an incoming message, as in this example: | |
27433 | ||
27434 | warn message = Remove internal headers | |
27435 | remove_header = x-route-mail1 : x-route-mail2 | |
27436 | ||
27437 | The remove_header modifier is permitted in the MAIL, RCPT, PREDATA, DATA, MIME, | |
27438 | DKIM, and non-SMTP ACLs (in other words, those that are concerned with | |
27439 | receiving a message). The message must ultimately be accepted for remove_header | |
27440 | to have any significant effect. You can use remove_header with any ACL verb, | |
27441 | including deny, though this is really not useful for any verb that doesn't | |
27442 | result in a delivered message. | |
27443 | ||
2813c06e CE |
27444 | Headers will not be removed from the message if the modifier is used in DATA, |
27445 | MIME or DKIM ACLs for a message delivered by cutthrough routing. | |
420a0d19 CE |
27446 | |
27447 | More than one header can be removed at the same time by using a colon separated | |
27448 | list of header names. The header matching is case insensitive. Wildcards are | |
27449 | not permitted, nor is list expansion performed, so you cannot use hostlists to | |
27450 | create a list of headers, however both connection and message variable | |
27451 | expansion are performed ($acl_c_* and $acl_m_*), illustrated in this example: | |
27452 | ||
27453 | warn hosts = +internal_hosts | |
27454 | set acl_c_ihdrs = x-route-mail1 : x-route-mail2 | |
27455 | warn message = Remove internal headers | |
27456 | remove_header = $acl_c_ihdrs | |
27457 | ||
27458 | Removed header lines are accumulated during the MAIL, RCPT, and predata ACLs. | |
27459 | They are removed from the message before processing the DATA and MIME ACLs. | |
27460 | There is no harm in attempting to remove the same header twice nor is removing | |
27461 | a non-existent header. Further header lines to be removed may be accumulated | |
27462 | during the DATA and MIME ACLs, after which they are removed from the message, | |
27463 | if present. In the case of non-SMTP messages, headers to be removed are | |
27464 | accumulated during the non-SMTP ACLs, and are removed from the message after | |
27465 | all the ACLs have run. If a message is rejected after DATA or by the non-SMTP | |
27466 | ACL, there really is no effect because there is no logging of what headers | |
27467 | would have been removed. | |
27468 | ||
27469 | Header lines are not visible in string expansions until the DATA phase when it | |
27470 | is received. Any header lines removed in the MAIL, RCPT, and predata ACLs are | |
27471 | not visible in the DATA ACL and MIME ACLs. Similarly, header lines that are | |
27472 | removed by the DATA or MIME ACLs are still visible in those ACLs. Because of | |
27473 | this restriction, you cannot use header lines as a way of controlling data | |
27474 | passed between (for example) the MAIL and RCPT ACLs. If you want to do this, | |
2813c06e | 27475 | you should instead use ACL variables, as described in section 43.19. |
420a0d19 CE |
27476 | |
27477 | The remove_header modifier acts immediately as it is encountered during the | |
27478 | processing of an ACL. Notice the difference between these two cases: | |
27479 | ||
27480 | accept remove_header = X-Internal | |
27481 | <some condition> | |
27482 | ||
27483 | accept <some condition> | |
27484 | remove_header = X-Internal | |
27485 | ||
27486 | In the first case, the header line is always removed, whether or not the | |
27487 | condition is true. In the second case, the header line is removed only if the | |
27488 | condition is true. Multiple occurrences of remove_header may occur in the same | |
27489 | ACL statement. All those that are encountered before a condition fails are | |
27490 | honoured. | |
27491 | ||
27492 | Warning: This facility currently applies only to header lines that are present | |
27493 | during ACL processing. It does NOT remove header lines that are added in a | |
27494 | system filter or in a router or transport. | |
27495 | ||
27496 | ||
2813c06e | 27497 | 43.26 ACL conditions |
420a0d19 CE |
27498 | -------------------- |
27499 | ||
27500 | Some of the conditions listed in this section are available only when Exim is | |
27501 | compiled with the content-scanning extension. They are included here briefly | |
27502 | for completeness. More detailed descriptions can be found in the discussion on | |
2813c06e | 27503 | content scanning in chapter 44. |
420a0d19 CE |
27504 | |
27505 | Not all conditions are relevant in all circumstances. For example, testing | |
27506 | senders and recipients does not make sense in an ACL that is being run as the | |
27507 | result of the arrival of an ETRN command, and checks on message headers can be | |
27508 | done only in the ACLs specified by acl_smtp_data and acl_not_smtp. You can use | |
27509 | the same condition (with different parameters) more than once in the same ACL | |
27510 | statement. This provides a way of specifying an "and" conjunction. The | |
27511 | conditions are as follows: | |
27512 | ||
27513 | acl = <name of acl or ACL string or file name > | |
27514 | ||
27515 | The possible values of the argument are the same as for the acl_smtp_xxx | |
27516 | options. The named or inline ACL is run. If it returns "accept" the | |
27517 | condition is true; if it returns "deny" the condition is false. If it | |
27518 | returns "defer", the current ACL returns "defer" unless the condition is on | |
27519 | a warn verb. In that case, a "defer" return makes the condition false. This | |
27520 | means that further processing of the warn verb ceases, but processing of | |
27521 | the ACL continues. | |
27522 | ||
27523 | If the argument is a named ACL, up to nine space-separated optional values | |
27524 | can be appended; they appear within the called ACL in $acl_arg1 to | |
27525 | $acl_arg9, and $acl_narg is set to the count of values. Previous values of | |
27526 | these variables are restored after the call returns. The name and values | |
2813c06e CE |
27527 | are expanded separately. Note that spaces in complex expansions which are |
27528 | used as arguments will act as argument separators. | |
420a0d19 CE |
27529 | |
27530 | If the nested acl returns "drop" and the outer condition denies access, the | |
27531 | connection is dropped. If it returns "discard", the verb must be accept or | |
27532 | discard, and the action is taken immediately - no further conditions are | |
27533 | tested. | |
27534 | ||
27535 | ACLs may be nested up to 20 deep; the limit exists purely to catch runaway | |
27536 | loops. This condition allows you to use different ACLs in different | |
27537 | circumstances. For example, different ACLs can be used to handle RCPT | |
27538 | commands for different local users or different local domains. | |
27539 | ||
27540 | authenticated = <string list> | |
27541 | ||
27542 | If the SMTP connection is not authenticated, the condition is false. | |
27543 | Otherwise, the name of the authenticator is tested against the list. To | |
27544 | test for authentication by any authenticator, you can set | |
27545 | ||
27546 | authenticated = * | |
27547 | ||
27548 | condition = <string> | |
27549 | ||
27550 | This feature allows you to make up custom conditions. If the result of | |
27551 | expanding the string is an empty string, the number zero, or one of the | |
27552 | strings "no" or "false", the condition is false. If the result is any | |
27553 | non-zero number, or one of the strings "yes" or "true", the condition is | |
27554 | true. For any other value, some error is assumed to have occurred, and the | |
27555 | ACL returns "defer". However, if the expansion is forced to fail, the | |
27556 | condition is ignored. The effect is to treat it as true, whether it is | |
27557 | positive or negative. | |
27558 | ||
27559 | decode = <location> | |
27560 | ||
27561 | This condition is available only when Exim is compiled with the | |
27562 | content-scanning extension, and it is allowed only in the ACL defined by | |
27563 | acl_smtp_mime. It causes the current MIME part to be decoded into a file. | |
27564 | If all goes well, the condition is true. It is false only if there are | |
27565 | problems such as a syntax error or a memory shortage. For more details, see | |
2813c06e | 27566 | chapter 44. |
420a0d19 CE |
27567 | |
27568 | dnslists = <list of domain names and other data> | |
27569 | ||
27570 | This condition checks for entries in DNS black lists. These are also known | |
27571 | as "RBL lists", after the original Realtime Blackhole List, but note that | |
27572 | the use of the lists at mail-abuse.org now carries a charge. There are too | |
27573 | many different variants of this condition to describe briefly here. See | |
2813c06e | 27574 | sections 43.27-43.37 for details. |
420a0d19 CE |
27575 | |
27576 | domains = <domain list> | |
27577 | ||
27578 | This condition is relevant only after a RCPT command. It checks that the | |
27579 | domain of the recipient address is in the domain list. If percent-hack | |
27580 | processing is enabled, it is done before this test is done. If the check | |
27581 | succeeds with a lookup, the result of the lookup is placed in $domain_data | |
27582 | until the next domains test. | |
27583 | ||
27584 | Note carefully (because many people seem to fall foul of this): you cannot | |
27585 | use domains in a DATA ACL. | |
27586 | ||
27587 | encrypted = <string list> | |
27588 | ||
27589 | If the SMTP connection is not encrypted, the condition is false. Otherwise, | |
27590 | the name of the cipher suite in use is tested against the list. To test for | |
27591 | encryption without testing for any specific cipher suite(s), set | |
27592 | ||
27593 | encrypted = * | |
27594 | ||
27595 | hosts = <host list> | |
27596 | ||
27597 | This condition tests that the calling host matches the host list. If you | |
27598 | have name lookups or wildcarded host names and IP addresses in the same | |
27599 | host list, you should normally put the IP addresses first. For example, you | |
27600 | could have: | |
27601 | ||
27602 | accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts | |
27603 | ||
27604 | The lookup in this example uses the host name for its key. This is implied | |
27605 | by the lookup type "dbm". (For a host address lookup you would use | |
27606 | "net-dbm" and it wouldn't matter which way round you had these two items.) | |
27607 | ||
27608 | The reason for the problem with host names lies in the left-to-right way | |
27609 | that Exim processes lists. It can test IP addresses without doing any DNS | |
27610 | lookups, but when it reaches an item that requires a host name, it fails if | |
27611 | it cannot find a host name to compare with the pattern. If the above list | |
27612 | is given in the opposite order, the accept statement fails for a host whose | |
27613 | name cannot be found, even if its IP address is 10.9.8.7. | |
27614 | ||
27615 | If you really do want to do the name check first, and still recognize the | |
27616 | IP address even if the name lookup fails, you can rewrite the ACL like | |
27617 | this: | |
27618 | ||
27619 | accept hosts = dbm;/etc/friendly/hosts | |
27620 | accept hosts = 10.9.8.7 | |
27621 | ||
27622 | The default action on failing to find the host name is to assume that the | |
27623 | host is not in the list, so the first accept statement fails. The second | |
27624 | statement can then check the IP address. | |
27625 | ||
27626 | If a hosts condition is satisfied by means of a lookup, the result of the | |
27627 | lookup is made available in the $host_data variable. This allows you, for | |
27628 | example, to set up a statement like this: | |
27629 | ||
27630 | deny hosts = net-lsearch;/some/file | |
27631 | message = $host_data | |
27632 | ||
27633 | which gives a custom error message for each denied host. | |
27634 | ||
27635 | local_parts = <local part list> | |
27636 | ||
27637 | This condition is relevant only after a RCPT command. It checks that the | |
27638 | local part of the recipient address is in the list. If percent-hack | |
27639 | processing is enabled, it is done before this test. If the check succeeds | |
27640 | with a lookup, the result of the lookup is placed in $local_part_data, | |
27641 | which remains set until the next local_parts test. | |
27642 | ||
27643 | malware = <option> | |
27644 | ||
27645 | This condition is available only when Exim is compiled with the | |
27646 | content-scanning extension. It causes the incoming message to be scanned | |
2813c06e | 27647 | for viruses. For details, see chapter 44. |
420a0d19 CE |
27648 | |
27649 | mime_regex = <list of regular expressions> | |
27650 | ||
27651 | This condition is available only when Exim is compiled with the | |
27652 | content-scanning extension, and it is allowed only in the ACL defined by | |
27653 | acl_smtp_mime. It causes the current MIME part to be scanned for a match | |
2813c06e | 27654 | with any of the regular expressions. For details, see chapter 44. |
420a0d19 CE |
27655 | |
27656 | ratelimit = <parameters> | |
27657 | ||
27658 | This condition can be used to limit the rate at which a user or host | |
2813c06e | 27659 | submits messages. Details are given in section 43.38. |
420a0d19 CE |
27660 | |
27661 | recipients = <address list> | |
27662 | ||
27663 | This condition is relevant only after a RCPT command. It checks the entire | |
27664 | recipient address against a list of recipients. | |
27665 | ||
27666 | regex = <list of regular expressions> | |
27667 | ||
27668 | This condition is available only when Exim is compiled with the | |
27669 | content-scanning extension, and is available only in the DATA, MIME, and | |
27670 | non-SMTP ACLs. It causes the incoming message to be scanned for a match | |
2813c06e | 27671 | with any of the regular expressions. For details, see chapter 44. |
420a0d19 CE |
27672 | |
27673 | sender_domains = <domain list> | |
27674 | ||
27675 | This condition tests the domain of the sender of the message against the | |
27676 | given domain list. Note: The domain of the sender address is in | |
27677 | $sender_address_domain. It is not put in $domain during the testing of this | |
27678 | condition. This is an exception to the general rule for testing domain | |
27679 | lists. It is done this way so that, if this condition is used in an ACL for | |
27680 | a RCPT command, the recipient's domain (which is in $domain) can be used to | |
27681 | influence the sender checking. | |
27682 | ||
27683 | Warning: It is a bad idea to use this condition on its own as a control on | |
27684 | relaying, because sender addresses are easily, and commonly, forged. | |
27685 | ||
27686 | senders = <address list> | |
27687 | ||
27688 | This condition tests the sender of the message against the given list. To | |
27689 | test for a bounce message, which has an empty sender, set | |
27690 | ||
27691 | senders = : | |
27692 | ||
27693 | Warning: It is a bad idea to use this condition on its own as a control on | |
27694 | relaying, because sender addresses are easily, and commonly, forged. | |
27695 | ||
27696 | spam = <username> | |
27697 | ||
27698 | This condition is available only when Exim is compiled with the | |
27699 | content-scanning extension. It causes the incoming message to be scanned by | |
2813c06e | 27700 | SpamAssassin. For details, see chapter 44. |
420a0d19 CE |
27701 | |
27702 | verify = certificate | |
27703 | ||
27704 | This condition is true in an SMTP session if the session is encrypted, and | |
27705 | a certificate was received from the client, and the certificate was | |
27706 | verified. The server requests a certificate only if the client matches | |
2813c06e | 27707 | tls_verify_hosts or tls_try_verify_hosts (see chapter 42). |
420a0d19 CE |
27708 | |
27709 | verify = csa | |
27710 | ||
27711 | This condition checks whether the sending host (the client) is authorized | |
2813c06e | 27712 | to send email. Details of how this works are given in section 43.50. |
420a0d19 CE |
27713 | |
27714 | verify = header_names_ascii | |
27715 | ||
27716 | This condition is relevant only in an ACL that is run after a message has | |
27717 | been received, that is, in an ACL specified by acl_smtp_data or | |
27718 | acl_not_smtp. It checks all header names (not the content) to make sure | |
27719 | there are no non-ASCII characters, also excluding control characters. The | |
27720 | allowable characters are decimal ASCII values 33 through 126. | |
27721 | ||
27722 | Exim itself will handle headers with non-ASCII characters, but it can cause | |
27723 | problems for downstream applications, so this option will allow their | |
27724 | detection and rejection in the DATA ACL's. | |
27725 | ||
27726 | verify = header_sender/<options> | |
27727 | ||
27728 | This condition is relevant only in an ACL that is run after a message has | |
27729 | been received, that is, in an ACL specified by acl_smtp_data or | |
27730 | acl_not_smtp. It checks that there is a verifiable address in at least one | |
27731 | of the Sender:, Reply-To:, or From: header lines. Such an address is | |
27732 | loosely thought of as a "sender" address (hence the name of the test). | |
27733 | However, an address that appears in one of these headers need not be an | |
27734 | address that accepts bounce messages; only sender addresses in envelopes | |
27735 | are required to accept bounces. Therefore, if you use the callout option on | |
27736 | this check, you might want to arrange for a non-empty address in the MAIL | |
27737 | command. | |
27738 | ||
27739 | Details of address verification and the options are given later, starting | |
2813c06e | 27740 | at section 43.44 (callouts are described in section 43.45). You can combine |
420a0d19 CE |
27741 | this condition with the senders condition to restrict it to bounce messages |
27742 | only: | |
27743 | ||
27744 | deny senders = : | |
27745 | message = A valid sender header is required for bounces | |
27746 | !verify = header_sender | |
27747 | ||
27748 | verify = header_syntax | |
27749 | ||
27750 | This condition is relevant only in an ACL that is run after a message has | |
27751 | been received, that is, in an ACL specified by acl_smtp_data or | |
27752 | acl_not_smtp. It checks the syntax of all header lines that can contain | |
2813c06e CE |
27753 | lists of addresses (Sender:, From:, Reply-To:, To:, Cc:, and Bcc:), |
27754 | returning true if there are no problems. Unqualified addresses (local parts | |
27755 | without domains) are permitted only in locally generated messages and from | |
27756 | hosts that match sender_unqualified_hosts or recipient_unqualified_hosts, | |
27757 | as appropriate. | |
420a0d19 CE |
27758 | |
27759 | Note that this condition is a syntax check only. However, a common spamming | |
27760 | ploy used to be to send syntactically invalid headers such as | |
27761 | ||
27762 | To: @ | |
27763 | ||
27764 | and this condition can be used to reject such messages, though they are not | |
27765 | as common as they used to be. | |
27766 | ||
27767 | verify = helo | |
27768 | ||
27769 | This condition is true if a HELO or EHLO command has been received from the | |
27770 | client host, and its contents have been verified. If there has been no | |
27771 | previous attempt to verify the HELO/EHLO contents, it is carried out when | |
27772 | this condition is encountered. See the description of the helo_verify_hosts | |
27773 | and helo_try_verify_hosts options for details of how to request | |
27774 | verification independently of this condition. | |
27775 | ||
27776 | For SMTP input that does not come over TCP/IP (the -bs command line | |
27777 | option), this condition is always true. | |
27778 | ||
27779 | verify = not_blind | |
27780 | ||
27781 | This condition checks that there are no blind (bcc) recipients in the | |
27782 | message. Every envelope recipient must appear either in a To: header line | |
27783 | or in a Cc: header line for this condition to be true. Local parts are | |
27784 | checked case-sensitively; domains are checked case-insensitively. If | |
27785 | Resent-To: or Resent-Cc: header lines exist, they are also checked. This | |
27786 | condition can be used only in a DATA or non-SMTP ACL. | |
27787 | ||
27788 | There are, of course, many legitimate messages that make use of blind (bcc) | |
27789 | recipients. This check should not be used on its own for blocking messages. | |
27790 | ||
27791 | verify = recipient/<options> | |
27792 | ||
27793 | This condition is relevant only after a RCPT command. It verifies the | |
27794 | current recipient. Details of address verification are given later, | |
2813c06e | 27795 | starting at section 43.44. After a recipient has been verified, the value |
420a0d19 CE |
27796 | of $address_data is the last value that was set while routing the address. |
27797 | This applies even if the verification fails. When an address that is being | |
27798 | verified is redirected to a single address, verification continues with the | |
27799 | new address, and in that case, the subsequent value of $address_data is the | |
27800 | value for the child address. | |
27801 | ||
2813c06e | 27802 | verify = reverse_host_lookup/<options> |
420a0d19 CE |
27803 | |
27804 | This condition ensures that a verified host name has been looked up from | |
27805 | the IP address of the client host. (This may have happened already if the | |
27806 | host name was needed for checking a host list, or if the host matched | |
27807 | host_lookup.) Verification ensures that the host name obtained from a | |
27808 | reverse DNS lookup, or one of its aliases, does, when it is itself looked | |
27809 | up in the DNS, yield the original IP address. | |
27810 | ||
2813c06e CE |
27811 | There is one possible option, "defer_ok". If this is present and a DNS |
27812 | operation returns a temporary error, the verify condition succeeds. | |
27813 | ||
420a0d19 CE |
27814 | If this condition is used for a locally generated message (that is, when |
27815 | there is no client host involved), it always succeeds. | |
27816 | ||
27817 | verify = sender/<options> | |
27818 | ||
27819 | This condition is relevant only after a MAIL or RCPT command, or after a | |
27820 | message has been received (the acl_smtp_data or acl_not_smtp ACLs). If the | |
27821 | message's sender is empty (that is, this is a bounce message), the | |
27822 | condition is true. Otherwise, the sender address is verified. | |
27823 | ||
27824 | If there is data in the $address_data variable at the end of routing, its | |
27825 | value is placed in $sender_address_data at the end of verification. This | |
27826 | value can be used in subsequent conditions and modifiers in the same ACL | |
27827 | statement. It does not persist after the end of the current statement. If | |
27828 | you want to preserve the value for longer, you can save it in an ACL | |
27829 | variable. | |
27830 | ||
2813c06e | 27831 | Details of verification are given later, starting at section 43.44. Exim |
420a0d19 CE |
27832 | caches the result of sender verification, to avoid doing it more than once |
27833 | per message. | |
27834 | ||
27835 | verify = sender=<address>/<options> | |
27836 | ||
27837 | This is a variation of the previous option, in which a modified address is | |
27838 | verified as a sender. | |
27839 | ||
2813c06e CE |
27840 | Note that '/' is legal in local-parts; if the address may have such (eg. is |
27841 | generated from the received message) they must be protected from the | |
27842 | options parsing by doubling: | |
27843 | ||
27844 | verify = sender=${sg{${address:$h_sender:}}{/}{//}} | |
420a0d19 | 27845 | |
2813c06e CE |
27846 | |
27847 | 43.27 Using DNS lists | |
420a0d19 CE |
27848 | --------------------- |
27849 | ||
27850 | In its simplest form, the dnslists condition tests whether the calling host is | |
27851 | on at least one of a number of DNS lists by looking up the inverted IP address | |
27852 | in one or more DNS domains. (Note that DNS list domains are not mail domains, | |
27853 | so the "+" syntax for named lists doesn't work - it is used for special options | |
27854 | instead.) For example, if the calling host's IP address is 192.168.62.43, and | |
27855 | the ACL statement is | |
27856 | ||
27857 | deny dnslists = blackholes.mail-abuse.org : \ | |
27858 | dialups.mail-abuse.org | |
27859 | ||
27860 | the following records are looked up: | |
27861 | ||
27862 | 43.62.168.192.blackholes.mail-abuse.org | |
27863 | 43.62.168.192.dialups.mail-abuse.org | |
27864 | ||
27865 | As soon as Exim finds an existing DNS record, processing of the list stops. | |
27866 | Thus, multiple entries on the list provide an "or" conjunction. If you want to | |
27867 | test that a host is on more than one list (an "and" conjunction), you can use | |
27868 | two separate conditions: | |
27869 | ||
27870 | deny dnslists = blackholes.mail-abuse.org | |
27871 | dnslists = dialups.mail-abuse.org | |
27872 | ||
27873 | If a DNS lookup times out or otherwise fails to give a decisive answer, Exim | |
27874 | behaves as if the host does not match the list item, that is, as if the DNS | |
27875 | record does not exist. If there are further items in the DNS list, they are | |
27876 | processed. | |
27877 | ||
27878 | This is usually the required action when dnslists is used with deny (which is | |
27879 | the most common usage), because it prevents a DNS failure from blocking mail. | |
27880 | However, you can change this behaviour by putting one of the following special | |
27881 | items in the list: | |
27882 | ||
27883 | +include_unknown behave as if the item is on the list | |
27884 | +exclude_unknown behave as if the item is not on the list (default) | |
27885 | +defer_unknown give a temporary error | |
27886 | ||
27887 | Each of these applies to any subsequent items on the list. For example: | |
27888 | ||
27889 | deny dnslists = +defer_unknown : foo.bar.example | |
27890 | ||
27891 | Testing the list of domains stops as soon as a match is found. If you want to | |
27892 | warn for one list and block for another, you can use two different statements: | |
27893 | ||
27894 | deny dnslists = blackholes.mail-abuse.org | |
27895 | warn message = X-Warn: sending host is on dialups list | |
27896 | dnslists = dialups.mail-abuse.org | |
27897 | ||
2813c06e CE |
27898 | DNS list lookups are cached by Exim for the duration of the SMTP session (but |
27899 | limited by the DNS return TTL value), so a lookup based on the IP address is | |
27900 | done at most once for any incoming connection (assuming long-enough TTL). Exim | |
27901 | does not share information between multiple incoming connections (but your | |
27902 | local name server cache should be active). | |
420a0d19 CE |
27903 | |
27904 | ||
2813c06e | 27905 | 43.28 Specifying the IP address for a DNS list lookup |
420a0d19 CE |
27906 | ----------------------------------------------------- |
27907 | ||
27908 | By default, the IP address that is used in a DNS list lookup is the IP address | |
27909 | of the calling host. However, you can specify another IP address by listing it | |
27910 | after the domain name, introduced by a slash. For example: | |
27911 | ||
27912 | deny dnslists = black.list.tld/192.168.1.2 | |
27913 | ||
27914 | This feature is not very helpful with explicit IP addresses; it is intended for | |
27915 | use with IP addresses that are looked up, for example, the IP addresses of the | |
27916 | MX hosts or nameservers of an email sender address. For an example, see section | |
2813c06e | 27917 | 43.30 below. |
420a0d19 CE |
27918 | |
27919 | ||
2813c06e | 27920 | 43.29 DNS lists keyed on domain names |
420a0d19 CE |
27921 | ------------------------------------- |
27922 | ||
27923 | There are some lists that are keyed on domain names rather than inverted IP | |
27924 | addresses (see for example the domain based zones link at http:// | |
27925 | www.rfc-ignorant.org/). No reversing of components is used with these lists. | |
27926 | You can change the name that is looked up in a DNS list by listing it after the | |
27927 | domain name, introduced by a slash. For example, | |
27928 | ||
27929 | deny message = Sender's domain is listed at $dnslist_domain | |
27930 | dnslists = dsn.rfc-ignorant.org/$sender_address_domain | |
27931 | ||
27932 | This particular example is useful only in ACLs that are obeyed after the RCPT | |
27933 | or DATA commands, when a sender address is available. If (for example) the | |
27934 | message's sender is user@tld.example the name that is looked up by this example | |
27935 | is | |
27936 | ||
27937 | tld.example.dsn.rfc-ignorant.org | |
27938 | ||
27939 | A single dnslists condition can contain entries for both names and IP | |
27940 | addresses. For example: | |
27941 | ||
27942 | deny dnslists = sbl.spamhaus.org : \ | |
27943 | dsn.rfc-ignorant.org/$sender_address_domain | |
27944 | ||
27945 | The first item checks the sending host's IP address; the second checks a domain | |
27946 | name. The whole condition is true if either of the DNS lookups succeeds. | |
27947 | ||
27948 | ||
2813c06e | 27949 | 43.30 Multiple explicit keys for a DNS list |
420a0d19 CE |
27950 | ------------------------------------------- |
27951 | ||
27952 | The syntax described above for looking up explicitly-defined values (either | |
27953 | names or IP addresses) in a DNS blacklist is a simplification. After the domain | |
27954 | name for the DNS list, what follows the slash can in fact be a list of items. | |
27955 | As with all lists in Exim, the default separator is a colon. However, because | |
27956 | this is a sublist within the list of DNS blacklist domains, it is necessary | |
27957 | either to double the separators like this: | |
27958 | ||
27959 | dnslists = black.list.tld/name.1::name.2 | |
27960 | ||
27961 | or to change the separator character, like this: | |
27962 | ||
27963 | dnslists = black.list.tld/<;name.1;name.2 | |
27964 | ||
27965 | If an item in the list is an IP address, it is inverted before the DNS | |
27966 | blacklist domain is appended. If it is not an IP address, no inversion occurs. | |
27967 | Consider this condition: | |
27968 | ||
27969 | dnslists = black.list.tld/<;192.168.1.2;a.domain | |
27970 | ||
27971 | The DNS lookups that occur are: | |
27972 | ||
27973 | 2.1.168.192.black.list.tld | |
27974 | a.domain.black.list.tld | |
27975 | ||
27976 | Once a DNS record has been found (that matches a specific IP return address, if | |
2813c06e | 27977 | specified - see section 43.33), no further lookups are done. If there is a |
420a0d19 CE |
27978 | temporary DNS error, the rest of the sublist of domains or IP addresses is |
27979 | tried. A temporary error for the whole dnslists item occurs only if no other | |
27980 | DNS lookup in this sublist succeeds. In other words, a successful lookup for | |
27981 | any of the items in the sublist overrides a temporary error for a previous | |
27982 | item. | |
27983 | ||
27984 | The ability to supply a list of items after the slash is in some sense just a | |
27985 | syntactic convenience. These two examples have the same effect: | |
27986 | ||
27987 | dnslists = black.list.tld/a.domain : black.list.tld/b.domain | |
27988 | dnslists = black.list.tld/a.domain::b.domain | |
27989 | ||
27990 | However, when the data for the list is obtained from a lookup, the second form | |
27991 | is usually much more convenient. Consider this example: | |
27992 | ||
27993 | deny message = The mail servers for the domain \ | |
27994 | $sender_address_domain \ | |
27995 | are listed at $dnslist_domain ($dnslist_value); \ | |
27996 | see $dnslist_text. | |
27997 | dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\ | |
27998 | ${lookup dnsdb {>|mxh=\ | |
27999 | $sender_address_domain} }} } | |
28000 | ||
28001 | Note the use of ">|" in the dnsdb lookup to specify the separator for multiple | |
28002 | DNS records. The inner dnsdb lookup produces a list of MX hosts and the outer | |
28003 | dnsdb lookup finds the IP addresses for these hosts. The result of expanding | |
28004 | the condition might be something like this: | |
28005 | ||
2813c06e | 28006 | dnslists = sbl.spamhaus.org/<|192.168.2.3|192.168.5.6|... |
420a0d19 CE |
28007 | |
28008 | Thus, this example checks whether or not the IP addresses of the sender | |
28009 | domain's mail servers are on the Spamhaus black list. | |
28010 | ||
28011 | The key that was used for a successful DNS list lookup is put into the variable | |
2813c06e | 28012 | $dnslist_matched (see section 43.32). |
420a0d19 CE |
28013 | |
28014 | ||
2813c06e | 28015 | 43.31 Data returned by DNS lists |
420a0d19 CE |
28016 | -------------------------------- |
28017 | ||
28018 | DNS lists are constructed using address records in the DNS. The original RBL | |
28019 | just used the address 127.0.0.1 on the right hand side of each record, but the | |
28020 | RBL+ list and some other lists use a number of values with different meanings. | |
28021 | The values used on the RBL+ list are: | |
28022 | ||
28023 | 127.1.0.1 RBL | |
28024 | 127.1.0.2 DUL | |
28025 | 127.1.0.3 DUL and RBL | |
28026 | 127.1.0.4 RSS | |
28027 | 127.1.0.5 RSS and RBL | |
28028 | 127.1.0.6 RSS and DUL | |
28029 | 127.1.0.7 RSS and DUL and RBL | |
28030 | ||
2813c06e CE |
28031 | Section 43.33 below describes how you can distinguish between different values. |
28032 | Some DNS lists may return more than one address record; see section 43.35 for | |
420a0d19 CE |
28033 | details of how they are checked. |
28034 | ||
28035 | ||
2813c06e | 28036 | 43.32 Variables set from DNS lists |
420a0d19 CE |
28037 | ---------------------------------- |
28038 | ||
28039 | When an entry is found in a DNS list, the variable $dnslist_domain contains the | |
28040 | name of the overall domain that matched (for example, "spamhaus.example"), | |
28041 | $dnslist_matched contains the key within that domain (for example, | |
28042 | "192.168.5.3"), and $dnslist_value contains the data from the DNS record. When | |
28043 | the key is an IP address, it is not reversed in $dnslist_matched (though it is, | |
28044 | of course, in the actual lookup). In simple cases, for example: | |
28045 | ||
28046 | deny dnslists = spamhaus.example | |
28047 | ||
28048 | the key is also available in another variable (in this case, | |
28049 | $sender_host_address). In more complicated cases, however, this is not true. | |
2813c06e | 28050 | For example, using a data lookup (as described in section 43.30) might generate |
420a0d19 CE |
28051 | a dnslists lookup like this: |
28052 | ||
28053 | deny dnslists = spamhaus.example/<|192.168.1.2|192.168.6.7|... | |
28054 | ||
28055 | If this condition succeeds, the value in $dnslist_matched might be | |
28056 | "192.168.6.7" (for example). | |
28057 | ||
28058 | If more than one address record is returned by the DNS lookup, all the IP | |
28059 | addresses are included in $dnslist_value, separated by commas and spaces. The | |
28060 | variable $dnslist_text contains the contents of any associated TXT record. For | |
28061 | lists such as RBL+ the TXT record for a merged entry is often not very | |
2813c06e | 28062 | meaningful. See section 43.36 for a way of obtaining more information. |
420a0d19 CE |
28063 | |
28064 | You can use the DNS list variables in message or log_message modifiers - | |
28065 | although these appear before the condition in the ACL, they are not expanded | |
28066 | until after it has failed. For example: | |
28067 | ||
28068 | deny hosts = !+local_networks | |
28069 | message = $sender_host_address is listed \ | |
28070 | at $dnslist_domain | |
28071 | dnslists = rbl-plus.mail-abuse.example | |
28072 | ||
28073 | ||
2813c06e | 28074 | 43.33 Additional matching conditions for DNS lists |
420a0d19 CE |
28075 | -------------------------------------------------- |
28076 | ||
28077 | You can add an equals sign and an IP address after a dnslists domain name in | |
28078 | order to restrict its action to DNS records with a matching right hand side. | |
28079 | For example, | |
28080 | ||
28081 | deny dnslists = rblplus.mail-abuse.org=127.0.0.2 | |
28082 | ||
28083 | rejects only those hosts that yield 127.0.0.2. Without this additional data, | |
28084 | any address record is considered to be a match. For the moment, we assume that | |
2813c06e | 28085 | the DNS lookup returns just one record. Section 43.35 describes how multiple |
420a0d19 CE |
28086 | records are handled. |
28087 | ||
28088 | More than one IP address may be given for checking, using a comma as a | |
28089 | separator. These are alternatives - if any one of them matches, the dnslists | |
28090 | condition is true. For example: | |
28091 | ||
28092 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
28093 | ||
28094 | If you want to specify a constraining address list and also specify names or IP | |
28095 | addresses to be looked up, the constraining address list must be specified | |
28096 | first. For example: | |
28097 | ||
28098 | deny dnslists = dsn.rfc-ignorant.org\ | |
28099 | =127.0.0.2/$sender_address_domain | |
28100 | ||
28101 | If the character "&" is used instead of "=", the comparison for each listed IP | |
28102 | address is done by a bitwise "and" instead of by an equality test. In other | |
28103 | words, the listed addresses are used as bit masks. The comparison is true if | |
28104 | all the bits in the mask are present in the address that is being tested. For | |
28105 | example: | |
28106 | ||
28107 | dnslists = a.b.c&0.0.0.3 | |
28108 | ||
28109 | matches if the address is x.x.x.3, x.x.x.7, x.x.x.11, etc. If you want to test | |
28110 | whether one bit or another bit is present (as opposed to both being present), | |
28111 | you must use multiple values. For example: | |
28112 | ||
28113 | dnslists = a.b.c&0.0.0.1,0.0.0.2 | |
28114 | ||
28115 | matches if the final component of the address is an odd number or two times an | |
28116 | odd number. | |
28117 | ||
28118 | ||
2813c06e | 28119 | 43.34 Negated DNS matching conditions |
420a0d19 CE |
28120 | ------------------------------------- |
28121 | ||
28122 | You can supply a negative list of IP addresses as part of a dnslists condition. | |
28123 | Whereas | |
28124 | ||
28125 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
28126 | ||
28127 | means "deny if the host is in the black list at the domain a.b.c and the IP | |
28128 | address yielded by the list is either 127.0.0.2 or 127.0.0.3", | |
28129 | ||
28130 | deny dnslists = a.b.c!=127.0.0.2,127.0.0.3 | |
28131 | ||
28132 | means "deny if the host is in the black list at the domain a.b.c and the IP | |
28133 | address yielded by the list is not 127.0.0.2 and not 127.0.0.3". In other | |
28134 | words, the result of the test is inverted if an exclamation mark appears before | |
28135 | the "=" (or the "&") sign. | |
28136 | ||
28137 | Note: This kind of negation is not the same as negation in a domain, host, or | |
28138 | address list (which is why the syntax is different). | |
28139 | ||
28140 | If you are using just one list, the negation syntax does not gain you much. The | |
28141 | previous example is precisely equivalent to | |
28142 | ||
28143 | deny dnslists = a.b.c | |
28144 | !dnslists = a.b.c=127.0.0.2,127.0.0.3 | |
28145 | ||
28146 | However, if you are using multiple lists, the negation syntax is clearer. | |
28147 | Consider this example: | |
28148 | ||
28149 | deny dnslists = sbl.spamhaus.org : \ | |
28150 | list.dsbl.org : \ | |
28151 | dnsbl.njabl.org!=127.0.0.3 : \ | |
28152 | relays.ordb.org | |
28153 | ||
28154 | Using only positive lists, this would have to be: | |
28155 | ||
28156 | deny dnslists = sbl.spamhaus.org : \ | |
28157 | list.dsbl.org | |
28158 | deny dnslists = dnsbl.njabl.org | |
28159 | !dnslists = dnsbl.njabl.org=127.0.0.3 | |
28160 | deny dnslists = relays.ordb.org | |
28161 | ||
28162 | which is less clear, and harder to maintain. | |
28163 | ||
28164 | ||
2813c06e | 28165 | 43.35 Handling multiple DNS records from a DNS list |
420a0d19 CE |
28166 | --------------------------------------------------- |
28167 | ||
28168 | A DNS lookup for a dnslists condition may return more than one DNS record, | |
28169 | thereby providing more than one IP address. When an item in a dnslists list is | |
28170 | followed by "=" or "&" and a list of IP addresses, in order to restrict the | |
28171 | match to specific results from the DNS lookup, there are two ways in which the | |
28172 | checking can be handled. For example, consider the condition: | |
28173 | ||
28174 | dnslists = a.b.c=127.0.0.1 | |
28175 | ||
28176 | What happens if the DNS lookup for the incoming IP address yields both | |
28177 | 127.0.0.1 and 127.0.0.2 by means of two separate DNS records? Is the condition | |
28178 | true because at least one given value was found, or is it false because at | |
28179 | least one of the found values was not listed? And how does this affect negated | |
28180 | conditions? Both possibilities are provided for with the help of additional | |
28181 | separators "==" and "=&". | |
28182 | ||
28183 | * If "=" or "&" is used, the condition is true if any one of the looked up IP | |
28184 | addresses matches one of the listed addresses. For the example above, the | |
28185 | condition is true because 127.0.0.1 matches. | |
28186 | ||
28187 | * If "==" or "=&" is used, the condition is true only if every one of the | |
28188 | looked up IP addresses matches one of the listed addresses. If the | |
28189 | condition is changed to: | |
28190 | ||
28191 | dnslists = a.b.c==127.0.0.1 | |
28192 | ||
28193 | and the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is | |
28194 | false because 127.0.0.2 is not listed. You would need to have: | |
28195 | ||
28196 | dnslists = a.b.c==127.0.0.1,127.0.0.2 | |
28197 | ||
28198 | for the condition to be true. | |
28199 | ||
28200 | When "!" is used to negate IP address matching, it inverts the result, giving | |
28201 | the precise opposite of the behaviour above. Thus: | |
28202 | ||
28203 | * If "!=" or "!&" is used, the condition is true if none of the looked up IP | |
28204 | addresses matches one of the listed addresses. Consider: | |
28205 | ||
28206 | dnslists = a.b.c!&0.0.0.1 | |
28207 | ||
28208 | If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is | |
28209 | false because 127.0.0.1 matches. | |
28210 | ||
28211 | * If "!==" or "!=&" is used, the condition is true if there is at least one | |
28212 | looked up IP address that does not match. Consider: | |
28213 | ||
28214 | dnslists = a.b.c!=&0.0.0.1 | |
28215 | ||
28216 | If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is | |
28217 | true, because 127.0.0.2 does not match. You would need to have: | |
28218 | ||
28219 | dnslists = a.b.c!=&0.0.0.1,0.0.0.2 | |
28220 | ||
28221 | for the condition to be false. | |
28222 | ||
28223 | When the DNS lookup yields only a single IP address, there is no difference | |
28224 | between "=" and "==" and between "&" and "=&". | |
28225 | ||
28226 | ||
2813c06e | 28227 | 43.36 Detailed information from merged DNS lists |
420a0d19 CE |
28228 | ------------------------------------------------ |
28229 | ||
28230 | When the facility for restricting the matching IP values in a DNS list is used, | |
28231 | the text from the TXT record that is set in $dnslist_text may not reflect the | |
28232 | true reason for rejection. This happens when lists are merged and the IP | |
28233 | address in the A record is used to distinguish them; unfortunately there is | |
28234 | only one TXT record. One way round this is not to use merged lists, but that | |
28235 | can be inefficient because it requires multiple DNS lookups where one would do | |
28236 | in the vast majority of cases when the host of interest is not on any of the | |
28237 | lists. | |
28238 | ||
28239 | A less inefficient way of solving this problem is available. If two domain | |
28240 | names, comma-separated, are given, the second is used first to do an initial | |
28241 | check, making use of any IP value restrictions that are set. If there is a | |
28242 | match, the first domain is used, without any IP value restrictions, to get the | |
28243 | TXT record. As a byproduct of this, there is also a check that the IP being | |
28244 | tested is indeed on the first list. The first domain is the one that is put in | |
28245 | $dnslist_domain. For example: | |
28246 | ||
28247 | reject message = \ | |
28248 | rejected because $sender_host_address is blacklisted \ | |
28249 | at $dnslist_domain\n$dnslist_text | |
28250 | dnslists = \ | |
28251 | sbl.spamhaus.org,sbl-xbl.spamhaus.org=127.0.0.2 : \ | |
28252 | dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10 | |
28253 | ||
28254 | For the first blacklist item, this starts by doing a lookup in | |
28255 | sbl-xbl.spamhaus.org and testing for a 127.0.0.2 return. If there is a match, | |
28256 | it then looks in sbl.spamhaus.org, without checking the return value, and as | |
28257 | long as something is found, it looks for the corresponding TXT record. If there | |
28258 | is no match in sbl-xbl.spamhaus.org, nothing more is done. The second blacklist | |
28259 | item is processed similarly. | |
28260 | ||
28261 | If you are interested in more than one merged list, the same list must be given | |
28262 | several times, but because the results of the DNS lookups are cached, the DNS | |
28263 | calls themselves are not repeated. For example: | |
28264 | ||
28265 | reject dnslists = \ | |
28266 | http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \ | |
28267 | socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \ | |
28268 | misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \ | |
28269 | dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10 | |
28270 | ||
28271 | In this case there is one lookup in dnsbl.sorbs.net, and if none of the IP | |
28272 | values matches (or if no record is found), this is the only lookup that is | |
28273 | done. Only if there is a match is one of the more specific lists consulted. | |
28274 | ||
28275 | ||
2813c06e | 28276 | 43.37 DNS lists and IPv6 |
420a0d19 CE |
28277 | ------------------------ |
28278 | ||
28279 | If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it | |
28280 | nibble by nibble. For example, if the calling host's IP address is | |
28281 | 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up | |
28282 | ||
28283 | 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8. | |
28284 | f.f.f.f.e.f.f.3.blackholes.mail-abuse.org | |
28285 | ||
28286 | (split over two lines here to fit on the page). Unfortunately, some of the DNS | |
28287 | lists contain wildcard records, intended for IPv4, that interact badly with | |
28288 | IPv6. For example, the DNS entry | |
28289 | ||
28290 | *.3.some.list.example. A 127.0.0.1 | |
28291 | ||
28292 | is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list. | |
28293 | Unfortunately, it also matches the entire 3::/4 IPv6 network. | |
28294 | ||
28295 | You can exclude IPv6 addresses from DNS lookups by making use of a suitable | |
28296 | condition condition, as in this example: | |
28297 | ||
28298 | deny condition = ${if isip4{$sender_host_address}} | |
28299 | dnslists = some.list.example | |
28300 | ||
28301 | If an explicit key is being used for a DNS lookup and it may be an IPv6 address | |
28302 | you should specify alternate list separators for both the outer (DNS list name) | |
28303 | list and inner (lookup keys) list: | |
28304 | ||
28305 | dnslists = <; dnsbl.example.com/<|$acl_m_addrslist | |
28306 | ||
28307 | ||
2813c06e | 28308 | 43.38 Rate limiting incoming messages |
420a0d19 CE |
28309 | ------------------------------------- |
28310 | ||
28311 | The ratelimit ACL condition can be used to measure and control the rate at | |
28312 | which clients can send email. This is more powerful than the smtp_ratelimit_* | |
28313 | options, because those options control the rate of commands in a single SMTP | |
28314 | session only, whereas the ratelimit condition works across all connections | |
28315 | (concurrent and sequential) from the same client host. The syntax of the | |
28316 | ratelimit condition is: | |
28317 | ||
28318 | ratelimit = <m> / <p> / <options> / <key> | |
28319 | ||
28320 | If the average client sending rate is less than m messages per time period p | |
28321 | then the condition is false; otherwise it is true. | |
28322 | ||
28323 | As a side-effect, the ratelimit condition sets the expansion variable | |
28324 | $sender_rate to the client's computed rate, $sender_rate_limit to the | |
28325 | configured value of m, and $sender_rate_period to the configured value of p. | |
28326 | ||
28327 | The parameter p is the smoothing time constant, in the form of an Exim time | |
28328 | interval, for example, "8h" for eight hours. A larger time constant means that | |
28329 | it takes Exim longer to forget a client's past behaviour. The parameter m is | |
28330 | the maximum number of messages that a client is permitted to send in each time | |
28331 | interval. It also specifies the number of messages permitted in a fast burst. | |
28332 | By increasing both m and p but keeping m/p constant, you can allow a client to | |
28333 | send more messages in a burst without changing its long-term sending rate | |
28334 | limit. Conversely, if m and p are both small, messages must be sent at an even | |
28335 | rate. | |
28336 | ||
28337 | There is a script in util/ratelimit.pl which extracts sending rates from log | |
28338 | files, to assist with choosing appropriate settings for m and p when deploying | |
28339 | the ratelimit ACL condition. The script prints usage instructions when it is | |
28340 | run with no arguments. | |
28341 | ||
28342 | The key is used to look up the data for calculating the client's average | |
28343 | sending rate. This data is stored in Exim's spool directory, alongside the | |
28344 | retry and other hints databases. The default key is $sender_host_address, which | |
28345 | means Exim computes the sending rate of each client host IP address. By | |
28346 | changing the key you can change how Exim identifies clients for the purpose of | |
28347 | ratelimiting. For example, to limit the sending rate of each authenticated | |
28348 | user, independent of the computer they are sending from, set the key to | |
28349 | $authenticated_id. You must ensure that the lookup key is meaningful; for | |
28350 | example, $authenticated_id is only meaningful if the client has authenticated | |
28351 | (which you can check with the authenticated ACL condition). | |
28352 | ||
28353 | The lookup key does not have to identify clients: If you want to limit the rate | |
28354 | at which a recipient receives messages, you can use the key | |
28355 | "$local_part@$domain" with the per_rcpt option (see below) in a RCPT ACL. | |
28356 | ||
28357 | Each ratelimit condition can have up to four options. A per_* option specifies | |
28358 | what Exim measures the rate of, for example messages or recipients or bytes. | |
28359 | You can adjust the measurement using the unique= and/or count= options. You can | |
28360 | also control when Exim updates the recorded rate using a strict, leaky, or | |
28361 | readonly option. The options are separated by a slash, like the other | |
28362 | parameters. They may appear in any order. | |
28363 | ||
28364 | Internally, Exim appends the smoothing constant p onto the lookup key with any | |
28365 | options that alter the meaning of the stored data. The limit m is not stored, | |
28366 | so you can alter the configured maximum rate and Exim will still remember | |
28367 | clients' past behaviour. If you change the per_* mode or add or remove the | |
28368 | unique= option, the lookup key changes so Exim will forget past behaviour. The | |
28369 | lookup key is not affected by changes to the update mode and the count= option. | |
28370 | ||
28371 | ||
2813c06e | 28372 | 43.39 Ratelimit options for what is being measured |
420a0d19 CE |
28373 | -------------------------------------------------- |
28374 | ||
28375 | The per_conn option limits the client's connection rate. It is not normally | |
28376 | used in the acl_not_smtp, acl_not_smtp_mime, or acl_not_smtp_start ACLs. | |
28377 | ||
28378 | The per_mail option limits the client's rate of sending messages. This is the | |
28379 | default if none of the per_* options is specified. It can be used in | |
28380 | acl_smtp_mail, acl_smtp_rcpt, acl_smtp_predata, acl_smtp_mime, acl_smtp_data, | |
28381 | or acl_not_smtp. | |
28382 | ||
28383 | The per_byte option limits the sender's email bandwidth. It can be used in the | |
28384 | same ACLs as the per_mail option, though it is best to use this option in the | |
28385 | acl_smtp_mime, acl_smtp_data or acl_not_smtp ACLs; if it is used in an earlier | |
28386 | ACL, Exim relies on the SIZE parameter given by the client in its MAIL command, | |
28387 | which may be inaccurate or completely missing. You can follow the limit m in | |
28388 | the configuration with K, M, or G to specify limits in kilobytes, megabytes, or | |
28389 | gigabytes, respectively. | |
28390 | ||
28391 | The per_rcpt option causes Exim to limit the rate at which recipients are | |
28392 | accepted. It can be used in the acl_smtp_rcpt, acl_smtp_predata, acl_smtp_mime, | |
28393 | acl_smtp_data, or acl_smtp_rcpt ACLs. In acl_smtp_rcpt the rate is updated one | |
28394 | recipient at a time; in the other ACLs the rate is updated with the total | |
2813c06e CE |
28395 | (accepted) recipient count in one go. Note that in either case the rate |
28396 | limiting engine will see a message with many recipients as a large high-speed | |
28397 | burst. | |
420a0d19 CE |
28398 | |
28399 | The per_addr option is like the per_rcpt option, except it counts the number of | |
28400 | different recipients that the client has sent messages to in the last time | |
28401 | period. That is, if the client repeatedly sends messages to the same recipient, | |
28402 | its measured rate is not increased. This option can only be used in | |
28403 | acl_smtp_rcpt. | |
28404 | ||
28405 | The per_cmd option causes Exim to recompute the rate every time the condition | |
28406 | is processed. This can be used to limit the rate of any SMTP command. If it is | |
28407 | used in multiple ACLs it can limit the aggregate rate of multiple different | |
28408 | commands. | |
28409 | ||
28410 | The count= option can be used to alter how much Exim adds to the client's | |
28411 | measured rate. For example, the per_byte option is equivalent to "per_mail/ | |
28412 | count=$message_size". If there is no count= option, Exim increases the measured | |
28413 | rate by one (except for the per_rcpt option in ACLs other than acl_smtp_rcpt). | |
28414 | The count does not have to be an integer. | |
28415 | ||
2813c06e | 28416 | The unique= option is described in section 43.42 below. |
420a0d19 CE |
28417 | |
28418 | ||
2813c06e | 28419 | 43.40 Ratelimit update modes |
420a0d19 CE |
28420 | ---------------------------- |
28421 | ||
28422 | You can specify one of three options with the ratelimit condition to control | |
28423 | when its database is updated. This section describes the readonly mode, and the | |
28424 | next section describes the strict and leaky modes. | |
28425 | ||
28426 | If the ratelimit condition is used in readonly mode, Exim looks up a | |
28427 | previously-computed rate to check against the limit. | |
28428 | ||
28429 | For example, you can test the client's sending rate and deny it access (when it | |
28430 | is too fast) in the connect ACL. If the client passes this check then it can go | |
28431 | on to send a message, in which case its recorded rate will be updated in the | |
28432 | MAIL ACL. Subsequent connections from the same client will check this new rate. | |
28433 | ||
28434 | acl_check_connect: | |
28435 | deny ratelimit = 100 / 5m / readonly | |
28436 | log_message = RATE CHECK: $sender_rate/$sender_rate_period \ | |
28437 | (max $sender_rate_limit) | |
28438 | # ... | |
28439 | acl_check_mail: | |
28440 | warn ratelimit = 100 / 5m / strict | |
28441 | log_message = RATE UPDATE: $sender_rate/$sender_rate_period \ | |
28442 | (max $sender_rate_limit) | |
28443 | ||
28444 | If Exim encounters multiple ratelimit conditions with the same key when | |
28445 | processing a message then it may increase the client's measured rate more than | |
28446 | it should. For example, this will happen if you check the per_rcpt option in | |
28447 | both acl_smtp_rcpt and acl_smtp_data. However it's OK to check the same | |
28448 | ratelimit condition multiple times in the same ACL. You can avoid any multiple | |
28449 | update problems by using the readonly option on later ratelimit checks. | |
28450 | ||
28451 | The per_* options described above do not make sense in some ACLs. If you use a | |
28452 | per_* option in an ACL where it is not normally permitted then the update mode | |
28453 | defaults to readonly and you cannot specify the strict or leaky modes. In other | |
28454 | ACLs the default update mode is leaky (see the next section) so you must | |
28455 | specify the readonly option explicitly. | |
28456 | ||
28457 | ||
2813c06e | 28458 | 43.41 Ratelimit options for handling fast clients |
420a0d19 CE |
28459 | ------------------------------------------------- |
28460 | ||
28461 | If a client's average rate is greater than the maximum, the rate limiting | |
28462 | engine can react in two possible ways, depending on the presence of the strict | |
28463 | or leaky update modes. This is independent of the other counter-measures (such | |
28464 | as rejecting the message) that may be specified by the rest of the ACL. | |
28465 | ||
28466 | The leaky (default) option means that the client's recorded rate is not updated | |
28467 | if it is above the limit. The effect of this is that Exim measures the client's | |
28468 | average rate of successfully sent email, which cannot be greater than the | |
28469 | maximum allowed. If the client is over the limit it may suffer some | |
28470 | counter-measures (as specified in the ACL), but it will still be able to send | |
28471 | email at the configured maximum rate, whatever the rate of its attempts. This | |
28472 | is generally the better choice if you have clients that retry automatically. | |
28473 | For example, it does not prevent a sender with an over-aggressive retry rate | |
28474 | from getting any email through. | |
28475 | ||
28476 | The strict option means that the client's recorded rate is always updated. The | |
28477 | effect of this is that Exim measures the client's average rate of attempts to | |
28478 | send email, which can be much higher than the maximum it is actually allowed. | |
28479 | If the client is over the limit it may be subjected to counter-measures by the | |
28480 | ACL. It must slow down and allow sufficient time to pass that its computed rate | |
28481 | falls below the maximum before it can send email again. The time (the number of | |
28482 | smoothing periods) it must wait and not attempt to send mail can be calculated | |
28483 | with this formula: | |
28484 | ||
28485 | ln(peakrate/maxrate) | |
28486 | ||
28487 | ||
2813c06e | 28488 | 43.42 Limiting the rate of different events |
420a0d19 CE |
28489 | ------------------------------------------- |
28490 | ||
28491 | The ratelimit unique= option controls a mechanism for counting the rate of | |
28492 | different events. For example, the per_addr option uses this mechanism to count | |
28493 | the number of different recipients that the client has sent messages to in the | |
28494 | last time period; it is equivalent to "per_rcpt/unique=$local_part@$domain". | |
28495 | You could use this feature to measure the rate that a client uses different | |
28496 | sender addresses with the options "per_mail/unique=$sender_address". | |
28497 | ||
28498 | For each ratelimit key Exim stores the set of unique= values that it has seen | |
28499 | for that key. The whole set is thrown away when it is older than the rate | |
28500 | smoothing period p, so each different event is counted at most once per period. | |
28501 | In the leaky update mode, an event that causes the client to go over the limit | |
28502 | is not added to the set, in the same way that the client's recorded rate is not | |
28503 | updated in the same situation. | |
28504 | ||
28505 | When you combine the unique= and readonly options, the specific unique= value | |
28506 | is ignored, and Exim just retrieves the client's stored rate. | |
28507 | ||
28508 | The unique= mechanism needs more space in the ratelimit database than the other | |
28509 | ratelimit options in order to store the event set. The number of unique values | |
28510 | is potentially as large as the rate limit, so the extra space required | |
28511 | increases with larger limits. | |
28512 | ||
28513 | The uniqueification is not perfect: there is a small probability that Exim will | |
28514 | think a new event has happened before. If the sender's rate is less than the | |
28515 | limit, Exim should be more than 99.9% correct. However in strict mode the | |
28516 | measured rate can go above the limit, in which case Exim may under-count events | |
28517 | by a significant margin. Fortunately, if the rate is high enough (2.7 times the | |
28518 | limit) that the false positive rate goes above 9%, then Exim will throw away | |
28519 | the over-full event set before the measured rate falls below the limit. | |
28520 | Therefore the only harm should be that exceptionally high sending rates are | |
28521 | logged incorrectly; any countermeasures you configure will be as effective as | |
28522 | intended. | |
28523 | ||
28524 | ||
2813c06e | 28525 | 43.43 Using rate limiting |
420a0d19 CE |
28526 | ------------------------- |
28527 | ||
28528 | Exim's other ACL facilities are used to define what counter-measures are taken | |
28529 | when the rate limit is exceeded. This might be anything from logging a warning | |
28530 | (for example, while measuring existing sending rates in order to define | |
28531 | policy), through time delays to slow down fast senders, up to rejecting the | |
28532 | message. For example: | |
28533 | ||
28534 | # Log all senders' rates | |
28535 | warn ratelimit = 0 / 1h / strict | |
28536 | log_message = Sender rate $sender_rate / $sender_rate_period | |
28537 | ||
28538 | # Slow down fast senders; note the need to truncate $sender_rate | |
28539 | # at the decimal point. | |
28540 | warn ratelimit = 100 / 1h / per_rcpt / strict | |
28541 | delay = ${eval: ${sg{$sender_rate}{[.].*}{}} - \ | |
28542 | $sender_rate_limit }s | |
28543 | ||
28544 | # Keep authenticated users under control | |
28545 | deny authenticated = * | |
28546 | ratelimit = 100 / 1d / strict / $authenticated_id | |
28547 | ||
28548 | # System-wide rate limit | |
28549 | defer message = Sorry, too busy. Try again later. | |
28550 | ratelimit = 10 / 1s / $primary_hostname | |
28551 | ||
28552 | # Restrict incoming rate from each host, with a default | |
28553 | # set using a macro and special cases looked up in a table. | |
28554 | defer message = Sender rate exceeds $sender_rate_limit \ | |
28555 | messages per $sender_rate_period | |
28556 | ratelimit = ${lookup {$sender_host_address} \ | |
28557 | cdb {DB/ratelimits.cdb} \ | |
28558 | {$value} {RATELIMIT} } | |
28559 | ||
28560 | Warning: If you have a busy server with a lot of ratelimit tests, especially | |
28561 | with the per_rcpt option, you may suffer from a performance bottleneck caused | |
28562 | by locking on the ratelimit hints database. Apart from making your ACLs less | |
28563 | complicated, you can reduce the problem by using a RAM disk for Exim's hints | |
28564 | directory (usually /var/spool/exim/db/). However this means that Exim will lose | |
28565 | its hints data after a reboot (including retry hints, the callout cache, and | |
28566 | ratelimit data). | |
28567 | ||
28568 | ||
2813c06e | 28569 | 43.44 Address verification |
420a0d19 CE |
28570 | -------------------------- |
28571 | ||
2813c06e CE |
28572 | Several of the verify conditions described in section 43.26 cause addresses to |
28573 | be verified. Section 43.48 discusses the reporting of sender verification | |
420a0d19 CE |
28574 | failures. The verification conditions can be followed by options that modify |
28575 | the verification process. The options are separated from the keyword and from | |
28576 | each other by slashes, and some of them contain parameters. For example: | |
28577 | ||
28578 | verify = sender/callout | |
28579 | verify = recipient/defer_ok/callout=10s,defer_ok | |
28580 | ||
28581 | The first stage of address verification, which always happens, is to run the | |
28582 | address through the routers, in "verify mode". Routers can detect the | |
28583 | difference between verification and routing for delivery, and their actions can | |
28584 | be varied by a number of generic options such as verify and verify_only (see | |
28585 | chapter 15). If routing fails, verification fails. The available options are as | |
28586 | follows: | |
28587 | ||
28588 | * If the callout option is specified, successful routing to one or more | |
28589 | remote hosts is followed by a "callout" to those hosts as an additional | |
28590 | check. Callouts and their sub-options are discussed in the next section. | |
28591 | ||
28592 | * If there is a defer error while doing verification routing, the ACL | |
28593 | normally returns "defer". However, if you include defer_ok in the options, | |
28594 | the condition is forced to be true instead. Note that this is a main | |
28595 | verification option as well as a suboption for callouts. | |
28596 | ||
2813c06e | 28597 | * The no_details option is covered in section 43.48, which discusses the |
420a0d19 CE |
28598 | reporting of sender address verification failures. |
28599 | ||
28600 | * The success_on_redirect option causes verification always to succeed | |
28601 | immediately after a successful redirection. By default, if a redirection | |
28602 | generates just one address, that address is also verified. See further | |
2813c06e | 28603 | discussion in section 43.49. |
420a0d19 CE |
28604 | |
28605 | After an address verification failure, $acl_verify_message contains the error | |
28606 | message that is associated with the failure. It can be preserved by coding like | |
28607 | this: | |
28608 | ||
28609 | warn !verify = sender | |
28610 | set acl_m0 = $acl_verify_message | |
28611 | ||
28612 | If you are writing your own custom rejection message or log message when | |
28613 | denying access, you can use this variable to include information about the | |
28614 | verification failure. | |
28615 | ||
28616 | In addition, $sender_verify_failure or $recipient_verify_failure (as | |
28617 | appropriate) contains one of the following words: | |
28618 | ||
28619 | * qualify: The address was unqualified (no domain), and the message was | |
28620 | neither local nor came from an exempted host. | |
28621 | ||
28622 | * route: Routing failed. | |
28623 | ||
28624 | * mail: Routing succeeded, and a callout was attempted; rejection occurred at | |
28625 | or before the MAIL command (that is, on initial connection, HELO, or MAIL). | |
28626 | ||
28627 | * recipient: The RCPT command in a callout was rejected. | |
28628 | ||
28629 | * postmaster: The postmaster check in a callout was rejected. | |
28630 | ||
28631 | The main use of these variables is expected to be to distinguish between | |
28632 | rejections of MAIL and rejections of RCPT in callouts. | |
28633 | ||
28634 | ||
2813c06e | 28635 | 43.45 Callout verification |
420a0d19 CE |
28636 | -------------------------- |
28637 | ||
28638 | For non-local addresses, routing verifies the domain, but is unable to do any | |
28639 | checking of the local part. There are situations where some means of verifying | |
28640 | the local part is desirable. One way this can be done is to make an SMTP | |
28641 | callback to a delivery host for the sender address or a callforward to a | |
28642 | subsequent host for a recipient address, to see if the host accepts the | |
28643 | address. We use the term callout to cover both cases. Note that for a sender | |
28644 | address, the callback is not to the client host that is trying to deliver the | |
28645 | message, but to one of the hosts that accepts incoming mail for the sender's | |
28646 | domain. | |
28647 | ||
28648 | Exim does not do callouts by default. If you want them to happen, you must | |
28649 | request them by setting appropriate options on the verify condition, as | |
28650 | described below. This facility should be used with care, because it can add a | |
28651 | lot of resource usage to the cost of verifying an address. However, Exim does | |
28652 | cache the results of callouts, which helps to reduce the cost. Details of | |
2813c06e | 28653 | caching are in section 43.47. |
420a0d19 CE |
28654 | |
28655 | Recipient callouts are usually used only between hosts that are controlled by | |
28656 | the same administration. For example, a corporate gateway host could use | |
28657 | callouts to check for valid recipients on an internal mailserver. A successful | |
28658 | callout does not guarantee that a real delivery to the address would succeed; | |
28659 | on the other hand, a failing callout does guarantee that a delivery would fail. | |
28660 | ||
28661 | If the callout option is present on a condition that verifies an address, a | |
28662 | second stage of verification occurs if the address is successfully routed to | |
28663 | one or more remote hosts. The usual case is routing by a dnslookup or a | |
28664 | manualroute router, where the router specifies the hosts. However, if a router | |
28665 | that does not set up hosts routes to an smtp transport with a hosts setting, | |
28666 | the transport's hosts are used. If an smtp transport has hosts_override set, | |
28667 | its hosts are always used, whether or not the router supplies a host list. | |
28668 | Callouts are only supported on smtp transports. | |
28669 | ||
28670 | The port that is used is taken from the transport, if it is specified and is a | |
28671 | remote transport. (For routers that do verification only, no transport need be | |
28672 | specified.) Otherwise, the default SMTP port is used. If a remote transport | |
28673 | specifies an outgoing interface, this is used; otherwise the interface is not | |
28674 | specified. Likewise, the text that is used for the HELO command is taken from | |
28675 | the transport's helo_data option; if there is no transport, the value of | |
28676 | $smtp_active_hostname is used. | |
28677 | ||
28678 | For a sender callout check, Exim makes SMTP connections to the remote hosts, to | |
28679 | test whether a bounce message could be delivered to the sender address. The | |
28680 | following SMTP commands are sent: | |
28681 | ||
28682 | HELO <local host name> | |
28683 | MAIL FROM:<> | |
28684 | RCPT TO:<the address to be tested> | |
28685 | QUIT | |
28686 | ||
28687 | LHLO is used instead of HELO if the transport's protocol option is set to | |
28688 | "lmtp". | |
28689 | ||
28690 | The callout may use EHLO, AUTH and/or STARTTLS given appropriate option | |
28691 | settings. | |
28692 | ||
28693 | A recipient callout check is similar. By default, it also uses an empty address | |
28694 | for the sender. This default is chosen because most hosts do not make use of | |
28695 | the sender address when verifying a recipient. Using the same address means | |
28696 | that a single cache entry can be used for each recipient. Some sites, however, | |
28697 | do make use of the sender address when verifying. These are catered for by the | |
28698 | use_sender and use_postmaster options, described in the next section. | |
28699 | ||
28700 | If the response to the RCPT command is a 2xx code, the verification succeeds. | |
28701 | If it is 5xx, the verification fails. For any other condition, Exim tries the | |
28702 | next host, if any. If there is a problem with all the remote hosts, the ACL | |
28703 | yields "defer", unless the defer_ok parameter of the callout option is given, | |
28704 | in which case the condition is forced to succeed. | |
28705 | ||
28706 | A callout may take a little time. For this reason, Exim normally flushes SMTP | |
28707 | output before performing a callout in an ACL, to avoid unexpected timeouts in | |
28708 | clients when the SMTP PIPELINING extension is in use. The flushing can be | |
28709 | disabled by using a control modifier to set no_callout_flush. | |
28710 | ||
28711 | ||
2813c06e | 28712 | 43.46 Additional parameters for callouts |
420a0d19 CE |
28713 | ---------------------------------------- |
28714 | ||
28715 | The callout option can be followed by an equals sign and a number of optional | |
28716 | parameters, separated by commas. For example: | |
28717 | ||
28718 | verify = recipient/callout=10s,defer_ok | |
28719 | ||
28720 | The old syntax, which had callout_defer_ok and check_postmaster as separate | |
28721 | verify options, is retained for backwards compatibility, but is now deprecated. | |
28722 | The additional parameters for callout are as follows: | |
28723 | ||
28724 | <a time interval> | |
28725 | ||
28726 | This specifies the timeout that applies for the callout attempt to each | |
28727 | host. For example: | |
28728 | ||
28729 | verify = sender/callout=5s | |
28730 | ||
28731 | The default is 30 seconds. The timeout is used for each response from the | |
28732 | remote host. It is also used for the initial connection, unless overridden | |
28733 | by the connect parameter. | |
28734 | ||
28735 | connect = <time interval> | |
28736 | ||
28737 | This parameter makes it possible to set a different (usually smaller) | |
28738 | timeout for making the SMTP connection. For example: | |
28739 | ||
28740 | verify = sender/callout=5s,connect=1s | |
28741 | ||
28742 | If not specified, this timeout defaults to the general timeout value. | |
28743 | ||
28744 | defer_ok | |
28745 | ||
28746 | When this parameter is present, failure to contact any host, or any other | |
28747 | kind of temporary error, is treated as success by the ACL. However, the | |
28748 | cache is not updated in this circumstance. | |
28749 | ||
28750 | fullpostmaster | |
28751 | ||
28752 | This operates like the postmaster option (see below), but if the check for | |
28753 | postmaster@domain fails, it tries just postmaster, without a domain, in | |
28754 | accordance with the specification in RFC 2821. The RFC states that the | |
28755 | unqualified address postmaster should be accepted. | |
28756 | ||
28757 | mailfrom = <email address> | |
28758 | ||
28759 | When verifying addresses in header lines using the header_sender | |
28760 | verification option, Exim behaves by default as if the addresses are | |
28761 | envelope sender addresses from a message. Callout verification therefore | |
28762 | tests to see whether a bounce message could be delivered, by using an empty | |
28763 | address in the MAIL command. However, it is arguable that these addresses | |
28764 | might never be used as envelope senders, and could therefore justifiably | |
28765 | reject bounce messages (empty senders). The mailfrom callout parameter | |
28766 | allows you to specify what address to use in the MAIL command. For example: | |
28767 | ||
28768 | require verify = header_sender/callout=mailfrom=abcd@x.y.z | |
28769 | ||
28770 | This parameter is available only for the header_sender verification option. | |
28771 | ||
28772 | maxwait = <time interval> | |
28773 | ||
28774 | This parameter sets an overall timeout for performing a callout | |
28775 | verification. For example: | |
28776 | ||
28777 | verify = sender/callout=5s,maxwait=30s | |
28778 | ||
28779 | This timeout defaults to four times the callout timeout for individual SMTP | |
28780 | commands. The overall timeout applies when there is more than one host that | |
28781 | can be tried. The timeout is checked before trying the next host. This | |
28782 | prevents very long delays if there are a large number of hosts and all are | |
28783 | timing out (for example, when network connections are timing out). | |
28784 | ||
28785 | no_cache | |
28786 | ||
28787 | When this parameter is given, the callout cache is neither read nor | |
28788 | updated. | |
28789 | ||
28790 | postmaster | |
28791 | ||
28792 | When this parameter is set, a successful callout check is followed by a | |
28793 | similar check for the local part postmaster at the same domain. If this | |
28794 | address is rejected, the callout fails (but see fullpostmaster above). The | |
28795 | result of the postmaster check is recorded in a cache record; if it is a | |
28796 | failure, this is used to fail subsequent callouts for the domain without a | |
28797 | connection being made, until the cache record expires. | |
28798 | ||
28799 | postmaster_mailfrom = <email address> | |
28800 | ||
28801 | The postmaster check uses an empty sender in the MAIL command by default. | |
28802 | You can use this parameter to do a postmaster check using a different | |
28803 | address. For example: | |
28804 | ||
28805 | require verify = sender/callout=postmaster_mailfrom=abc@x.y.z | |
28806 | ||
28807 | If both postmaster and postmaster_mailfrom are present, the rightmost one | |
28808 | overrides. The postmaster parameter is equivalent to this example: | |
28809 | ||
28810 | require verify = sender/callout=postmaster_mailfrom= | |
28811 | ||
28812 | Warning: The caching arrangements for postmaster checking do not take | |
28813 | account of the sender address. It is assumed that either the empty address | |
28814 | or a fixed non-empty address will be used. All that Exim remembers is that | |
28815 | the postmaster check for the domain succeeded or failed. | |
28816 | ||
28817 | random | |
28818 | ||
28819 | When this parameter is set, before doing the normal callout check, Exim | |
28820 | does a check for a "random" local part at the same domain. The local part | |
28821 | is not really random - it is defined by the expansion of the option | |
28822 | callout_random_local_part, which defaults to | |
28823 | ||
28824 | $primary_hostname-$tod_epoch-testing | |
28825 | ||
28826 | The idea here is to try to determine whether the remote host accepts all | |
28827 | local parts without checking. If it does, there is no point in doing | |
28828 | callouts for specific local parts. If the "random" check succeeds, the | |
28829 | result is saved in a cache record, and used to force the current and | |
28830 | subsequent callout checks to succeed without a connection being made, until | |
28831 | the cache record expires. | |
28832 | ||
28833 | use_postmaster | |
28834 | ||
28835 | This parameter applies to recipient callouts only. For example: | |
28836 | ||
28837 | deny !verify = recipient/callout=use_postmaster | |
28838 | ||
28839 | It causes a non-empty postmaster address to be used in the MAIL command | |
28840 | when performing the callout for the recipient, and also for a "random" | |
28841 | check if that is configured. The local part of the address is "postmaster" | |
28842 | and the domain is the contents of $qualify_domain. | |
28843 | ||
28844 | use_sender | |
28845 | ||
28846 | This option applies to recipient callouts only. For example: | |
28847 | ||
28848 | require verify = recipient/callout=use_sender | |
28849 | ||
28850 | It causes the message's actual sender address to be used in the MAIL | |
28851 | command when performing the callout, instead of an empty address. There is | |
28852 | no need to use this option unless you know that the called hosts make use | |
28853 | of the sender when checking recipients. If used indiscriminately, it | |
28854 | reduces the usefulness of callout caching. | |
28855 | ||
28856 | If you use any of the parameters that set a non-empty sender for the MAIL | |
28857 | command (mailfrom, postmaster_mailfrom, use_postmaster, or use_sender), you | |
28858 | should think about possible loops. Recipient checking is usually done between | |
28859 | two hosts that are under the same management, and the host that receives the | |
28860 | callouts is not normally configured to do callouts itself. Therefore, it is | |
28861 | normally safe to use use_postmaster or use_sender in these circumstances. | |
28862 | ||
28863 | However, if you use a non-empty sender address for a callout to an arbitrary | |
28864 | host, there is the likelihood that the remote host will itself initiate a | |
28865 | callout check back to your host. As it is checking what appears to be a message | |
28866 | sender, it is likely to use an empty address in MAIL, thus avoiding a callout | |
28867 | loop. However, to be on the safe side it would be best to set up your own ACLs | |
28868 | so that they do not do sender verification checks when the recipient is the | |
28869 | address you use for header sender or postmaster callout checking. | |
28870 | ||
28871 | Another issue to think about when using non-empty senders for callouts is | |
28872 | caching. When you set mailfrom or use_sender, the cache record is keyed by the | |
28873 | sender/recipient combination; thus, for any given recipient, many more actual | |
28874 | callouts are performed than when an empty sender or postmaster is used. | |
28875 | ||
28876 | ||
2813c06e | 28877 | 43.47 Callout caching |
420a0d19 CE |
28878 | --------------------- |
28879 | ||
28880 | Exim caches the results of callouts in order to reduce the amount of resources | |
28881 | used, unless you specify the no_cache parameter with the callout option. A | |
28882 | hints database called "callout" is used for the cache. Two different record | |
28883 | types are used: one records the result of a callout check for a specific | |
28884 | address, and the other records information that applies to the entire domain | |
28885 | (for example, that it accepts the local part postmaster). | |
28886 | ||
28887 | When an original callout fails, a detailed SMTP error message is given about | |
28888 | the failure. However, for subsequent failures use the cache data, this message | |
28889 | is not available. | |
28890 | ||
28891 | The expiry times for negative and positive address cache records are | |
28892 | independent, and can be set by the global options callout_negative_expire | |
28893 | (default 2h) and callout_positive_expire (default 24h), respectively. | |
28894 | ||
28895 | If a host gives a negative response to an SMTP connection, or rejects any | |
28896 | commands up to and including | |
28897 | ||
28898 | MAIL FROM:<> | |
28899 | ||
28900 | (but not including the MAIL command with a non-empty address), any callout | |
28901 | attempt is bound to fail. Exim remembers such failures in a domain cache | |
28902 | record, which it uses to fail callouts for the domain without making new | |
28903 | connections, until the domain record times out. There are two separate expiry | |
28904 | times for domain cache records: callout_domain_negative_expire (default 3h) and | |
28905 | callout_domain_positive_expire (default 7d). | |
28906 | ||
28907 | Domain records expire when the negative expiry time is reached if callouts | |
28908 | cannot be made for the domain, or if the postmaster check failed. Otherwise, | |
28909 | they expire when the positive expiry time is reached. This ensures that, for | |
28910 | example, a host that stops accepting "random" local parts will eventually be | |
28911 | noticed. | |
28912 | ||
28913 | The callout caching mechanism is based on the domain of the address that is | |
28914 | being tested. If the domain routes to several hosts, it is assumed that their | |
28915 | behaviour will be the same. | |
28916 | ||
28917 | ||
2813c06e | 28918 | 43.48 Sender address verification reporting |
420a0d19 CE |
28919 | ------------------------------------------- |
28920 | ||
2813c06e | 28921 | See section 43.44 for a general discussion of verification. When sender |
420a0d19 CE |
28922 | verification fails in an ACL, the details of the failure are given as |
28923 | additional output lines before the 550 response to the relevant SMTP command | |
28924 | (RCPT or DATA). For example, if sender callout is in use, you might see: | |
28925 | ||
28926 | MAIL FROM:<xyz@abc.example> | |
28927 | 250 OK | |
28928 | RCPT TO:<pqr@def.example> | |
28929 | 550-Verification failed for <xyz@abc.example> | |
28930 | 550-Called: 192.168.34.43 | |
28931 | 550-Sent: RCPT TO:<xyz@abc.example> | |
28932 | 550-Response: 550 Unknown local part xyz in <xyz@abc.example> | |
28933 | 550 Sender verification failed | |
28934 | ||
28935 | If more than one RCPT command fails in the same way, the details are given only | |
28936 | for the first of them. However, some administrators do not want to send out | |
28937 | this much information. You can suppress the details by adding "/no_details" to | |
28938 | the ACL statement that requests sender verification. For example: | |
28939 | ||
28940 | verify = sender/no_details | |
28941 | ||
28942 | ||
2813c06e | 28943 | 43.49 Redirection while verifying |
420a0d19 CE |
28944 | --------------------------------- |
28945 | ||
28946 | A dilemma arises when a local address is redirected by aliasing or forwarding | |
28947 | during verification: should the generated addresses themselves be verified, or | |
28948 | should the successful expansion of the original address be enough to verify it? | |
28949 | By default, Exim takes the following pragmatic approach: | |
28950 | ||
28951 | * When an incoming address is redirected to just one child address, | |
28952 | verification continues with the child address, and if that fails to verify, | |
28953 | the original verification also fails. | |
28954 | ||
28955 | * When an incoming address is redirected to more than one child address, | |
28956 | verification does not continue. A success result is returned. | |
28957 | ||
28958 | This seems the most reasonable behaviour for the common use of aliasing as a | |
28959 | way of redirecting different local parts to the same mailbox. It means, for | |
28960 | example, that a pair of alias entries of the form | |
28961 | ||
28962 | A.Wol: aw123 | |
28963 | aw123: :fail: Gone away, no forwarding address | |
28964 | ||
28965 | work as expected, with both local parts causing verification failure. When a | |
28966 | redirection generates more than one address, the behaviour is more like a | |
28967 | mailing list, where the existence of the alias itself is sufficient for | |
28968 | verification to succeed. | |
28969 | ||
28970 | It is possible, however, to change the default behaviour so that all successful | |
28971 | redirections count as successful verifications, however many new addresses are | |
28972 | generated. This is specified by the success_on_redirect verification option. | |
28973 | For example: | |
28974 | ||
28975 | require verify = recipient/success_on_redirect/callout=10s | |
28976 | ||
28977 | In this example, verification succeeds if a router generates a new address, and | |
28978 | the callout does not occur, because no address was routed to a remote host. | |
28979 | ||
28980 | When verification is being tested via the -bv option, the treatment of | |
28981 | redirections is as just described, unless the -v or any debugging option is | |
28982 | also specified. In that case, full verification is done for every generated | |
28983 | address and a report is output for each of them. | |
28984 | ||
28985 | ||
2813c06e | 28986 | 43.50 Client SMTP authorization (CSA) |
420a0d19 CE |
28987 | ------------------------------------- |
28988 | ||
28989 | Client SMTP Authorization is a system that allows a site to advertise which | |
28990 | machines are and are not permitted to send email. This is done by placing | |
28991 | special SRV records in the DNS; these are looked up using the client's HELO | |
28992 | domain. At the time of writing, CSA is still an Internet Draft. Client SMTP | |
28993 | Authorization checks in Exim are performed by the ACL condition: | |
28994 | ||
28995 | verify = csa | |
28996 | ||
28997 | This fails if the client is not authorized. If there is a DNS problem, or if no | |
28998 | valid CSA SRV record is found, or if the client is authorized, the condition | |
28999 | succeeds. These three cases can be distinguished using the expansion variable | |
29000 | $csa_status, which can take one of the values "fail", "defer", "unknown", or | |
29001 | "ok". The condition does not itself defer because that would be likely to cause | |
29002 | problems for legitimate email. | |
29003 | ||
29004 | The error messages produced by the CSA code include slightly more detail. If | |
29005 | $csa_status is "defer", this may be because of problems looking up the CSA SRV | |
29006 | record, or problems looking up the CSA target address record. There are four | |
29007 | reasons for $csa_status being "fail": | |
29008 | ||
29009 | * The client's host name is explicitly not authorized. | |
29010 | ||
29011 | * The client's IP address does not match any of the CSA target IP addresses. | |
29012 | ||
29013 | * The client's host name is authorized but it has no valid target IP | |
29014 | addresses (for example, the target's addresses are IPv6 and the client is | |
29015 | using IPv4). | |
29016 | ||
29017 | * The client's host name has no CSA SRV record but a parent domain has | |
29018 | asserted that all subdomains must be explicitly authorized. | |
29019 | ||
29020 | The csa verification condition can take an argument which is the domain to use | |
29021 | for the DNS query. The default is: | |
29022 | ||
29023 | verify = csa/$sender_helo_name | |
29024 | ||
29025 | This implementation includes an extension to CSA. If the query domain is an | |
29026 | address literal such as [192.0.2.95], or if it is a bare IP address, Exim | |
29027 | searches for CSA SRV records in the reverse DNS as if the HELO domain was (for | |
29028 | example) 95.2.0.192.in-addr.arpa. Therefore it is meaningful to say: | |
29029 | ||
29030 | verify = csa/$sender_host_address | |
29031 | ||
29032 | In fact, this is the check that Exim performs if the client does not say HELO. | |
29033 | This extension can be turned off by setting the main configuration option | |
29034 | dns_csa_use_reverse to be false. | |
29035 | ||
29036 | If a CSA SRV record is not found for the domain itself, a search is performed | |
29037 | through its parent domains for a record which might be making assertions about | |
29038 | subdomains. The maximum depth of this search is limited using the main | |
29039 | configuration option dns_csa_search_limit, which is 5 by default. Exim does not | |
29040 | look for CSA SRV records in a top level domain, so the default settings handle | |
29041 | HELO domains as long as seven (hostname.five.four.three.two.one.com). This | |
29042 | encompasses the vast majority of legitimate HELO domains. | |
29043 | ||
29044 | The dnsdb lookup also has support for CSA. Although dnsdb also supports direct | |
29045 | SRV lookups, this is not sufficient because of the extra parent domain search | |
29046 | behaviour of CSA, and (as with PTR lookups) dnsdb also turns IP addresses into | |
29047 | lookups in the reverse DNS space. The result of a successful lookup such as: | |
29048 | ||
29049 | ${lookup dnsdb {csa=$sender_helo_name}} | |
29050 | ||
29051 | has two space-separated fields: an authorization code and a target host name. | |
29052 | The authorization code can be "Y" for yes, "N" for no, "X" for explicit | |
29053 | authorization required but absent, or "?" for unknown. | |
29054 | ||
29055 | ||
2813c06e | 29056 | 43.51 Bounce address tag validation |
420a0d19 CE |
29057 | ----------------------------------- |
29058 | ||
29059 | Bounce address tag validation (BATV) is a scheme whereby the envelope senders | |
29060 | of outgoing messages have a cryptographic, timestamped "tag" added to them. | |
29061 | Genuine incoming bounce messages should therefore always be addressed to | |
29062 | recipients that have a valid tag. This scheme is a way of detecting unwanted | |
29063 | bounce messages caused by sender address forgeries (often called "collateral | |
29064 | spam"), because the recipients of such messages do not include valid tags. | |
29065 | ||
29066 | There are two expansion items to help with the implementation of the BATV | |
29067 | "prvs" (private signature) scheme in an Exim configuration. This scheme signs | |
29068 | the original envelope sender address by using a simple key to add a hash of the | |
29069 | address and some time-based randomizing information. The prvs expansion item | |
29070 | creates a signed address, and the prvscheck expansion item checks one. The | |
29071 | syntax of these expansion items is described in section 11.5. | |
29072 | ||
29073 | As an example, suppose the secret per-address keys are stored in an MySQL | |
29074 | database. A query to look up the key for an address could be defined as a macro | |
29075 | like this: | |
29076 | ||
29077 | PRVSCHECK_SQL = ${lookup mysql{SELECT secret FROM batv_prvs \ | |
29078 | WHERE sender='${quote_mysql:$prvscheck_address}'\ | |
29079 | }{$value}} | |
29080 | ||
29081 | Suppose also that the senders who make use of BATV are defined by an address | |
29082 | list called batv_senders. Then, in the ACL for RCPT commands, you could use | |
29083 | this: | |
29084 | ||
29085 | # Bounces: drop unsigned addresses for BATV senders | |
29086 | deny message = This address does not send an unsigned reverse path | |
29087 | senders = : | |
29088 | recipients = +batv_senders | |
29089 | ||
29090 | # Bounces: In case of prvs-signed address, check signature. | |
29091 | deny message = Invalid reverse path signature. | |
29092 | senders = : | |
29093 | condition = ${prvscheck {$local_part@$domain}\ | |
29094 | {PRVSCHECK_SQL}{1}} | |
29095 | !condition = $prvscheck_result | |
29096 | ||
29097 | The first statement rejects recipients for bounce messages that are addressed | |
29098 | to plain BATV sender addresses, because it is known that BATV senders do not | |
29099 | send out messages with plain sender addresses. The second statement rejects | |
29100 | recipients that are prvs-signed, but with invalid signatures (either because | |
29101 | the key is wrong, or the signature has timed out). | |
29102 | ||
29103 | A non-prvs-signed address is not rejected by the second statement, because the | |
29104 | prvscheck expansion yields an empty string if its first argument is not a | |
29105 | prvs-signed address, thus causing the condition condition to be false. If the | |
29106 | first argument is a syntactically valid prvs-signed address, the yield is the | |
29107 | third string (in this case "1"), whether or not the cryptographic and timeout | |
29108 | checks succeed. The $prvscheck_result variable contains the result of the | |
29109 | checks (empty for failure, "1" for success). | |
29110 | ||
29111 | There is one more issue you must consider when implementing prvs-signing: you | |
29112 | have to ensure that the routers accept prvs-signed addresses and deliver them | |
29113 | correctly. The easiest way to handle this is to use a redirect router to remove | |
29114 | the signature with a configuration along these lines: | |
29115 | ||
29116 | batv_redirect: | |
29117 | driver = redirect | |
29118 | data = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}} | |
29119 | ||
29120 | This works because, if the third argument of prvscheck is empty, the result of | |
29121 | the expansion of a prvs-signed address is the decoded value of the original | |
29122 | address. This router should probably be the first of your routers that handles | |
29123 | local addresses. | |
29124 | ||
29125 | To create BATV-signed addresses in the first place, a transport of this form | |
29126 | can be used: | |
29127 | ||
29128 | external_smtp_batv: | |
29129 | driver = smtp | |
29130 | return_path = ${prvs {$return_path} \ | |
29131 | {${lookup mysql{SELECT \ | |
29132 | secret FROM batv_prvs WHERE \ | |
29133 | sender='${quote_mysql:$sender_address}'} \ | |
29134 | {$value}fail}}} | |
29135 | ||
29136 | If no key can be found for the existing return path, no signing takes place. | |
29137 | ||
29138 | ||
2813c06e | 29139 | 43.52 Using an ACL to control relaying |
420a0d19 CE |
29140 | -------------------------------------- |
29141 | ||
29142 | An MTA is said to relay a message if it receives it from some host and delivers | |
29143 | it directly to another host as a result of a remote address contained within | |
29144 | it. Redirecting a local address via an alias or forward file and then passing | |
29145 | the message on to another host is not relaying, but a redirection as a result | |
29146 | of the "percent hack" is. | |
29147 | ||
29148 | Two kinds of relaying exist, which are termed "incoming" and "outgoing". A host | |
29149 | which is acting as a gateway or an MX backup is concerned with incoming | |
29150 | relaying from arbitrary hosts to a specific set of domains. On the other hand, | |
29151 | a host which is acting as a smart host for a number of clients is concerned | |
29152 | with outgoing relaying from those clients to the Internet at large. Often the | |
29153 | same host is fulfilling both functions, but in principle these two kinds of | |
29154 | relaying are entirely independent. What is not wanted is the transmission of | |
29155 | mail from arbitrary remote hosts through your system to arbitrary domains. | |
29156 | ||
29157 | You can implement relay control by means of suitable statements in the ACL that | |
29158 | runs for each RCPT command. For convenience, it is often easiest to use Exim's | |
29159 | named list facility to define the domains and hosts involved. For example, | |
29160 | suppose you want to do the following: | |
29161 | ||
29162 | * Deliver a number of domains to mailboxes on the local host (or process them | |
29163 | locally in some other way). Let's say these are my.dom1.example and | |
29164 | my.dom2.example. | |
29165 | ||
29166 | * Relay mail for a number of other domains for which you are the secondary | |
29167 | MX. These might be friend1.example and friend2.example. | |
29168 | ||
29169 | * Relay mail from the hosts on your local LAN, to whatever domains are | |
29170 | involved. Suppose your LAN is 192.168.45.0/24. | |
29171 | ||
29172 | In the main part of the configuration, you put the following definitions: | |
29173 | ||
29174 | domainlist local_domains = my.dom1.example : my.dom2.example | |
29175 | domainlist relay_to_domains = friend1.example : friend2.example | |
29176 | hostlist relay_from_hosts = 192.168.45.0/24 | |
29177 | ||
29178 | Now you can use these definitions in the ACL that is run for every RCPT | |
29179 | command: | |
29180 | ||
29181 | acl_check_rcpt: | |
29182 | accept domains = +local_domains : +relay_to_domains | |
29183 | accept hosts = +relay_from_hosts | |
29184 | ||
29185 | The first statement accepts any RCPT command that contains an address in the | |
29186 | local or relay domains. For any other domain, control passes to the second | |
29187 | statement, which accepts the command only if it comes from one of the relay | |
29188 | hosts. In practice, you will probably want to make your ACL more sophisticated | |
29189 | than this, for example, by including sender and recipient verification. The | |
29190 | default configuration includes a more comprehensive example, which is described | |
29191 | in chapter 7. | |
29192 | ||
29193 | ||
2813c06e | 29194 | 43.53 Checking a relay configuration |
420a0d19 CE |
29195 | ------------------------------------ |
29196 | ||
29197 | You can check the relay characteristics of your configuration in the same way | |
29198 | that you can test any ACL behaviour for an incoming SMTP connection, by using | |
29199 | the -bh option to run a fake SMTP session with which you interact. | |
29200 | ||
420a0d19 CE |
29201 | |
29202 | ||
29203 | =============================================================================== | |
2813c06e | 29204 | 44. CONTENT SCANNING AT ACL TIME |
420a0d19 CE |
29205 | |
29206 | The extension of Exim to include content scanning at ACL time, formerly known | |
29207 | as "exiscan", was originally implemented as a patch by Tom Kistner. The code | |
29208 | was integrated into the main source for Exim release 4.50, and Tom continues to | |
29209 | maintain it. Most of the wording of this chapter is taken from Tom's | |
29210 | specification. | |
29211 | ||
29212 | It is also possible to scan the content of messages at other times. The | |
2813c06e | 29213 | local_scan() function (see chapter 45) allows for content scanning after all |
420a0d19 CE |
29214 | the ACLs have run. A transport filter can be used to scan messages at delivery |
29215 | time (see the transport_filter option, described in chapter 24). | |
29216 | ||
29217 | If you want to include the ACL-time content-scanning features when you compile | |
29218 | Exim, you need to arrange for WITH_CONTENT_SCAN to be defined in your Local/ | |
29219 | Makefile. When you do that, the Exim binary is built with: | |
29220 | ||
29221 | * Two additional ACLs (acl_smtp_mime and acl_not_smtp_mime) that are run for | |
29222 | all MIME parts for SMTP and non-SMTP messages, respectively. | |
29223 | ||
29224 | * Additional ACL conditions and modifiers: decode, malware, mime_regex, regex | |
29225 | , and spam. These can be used in the ACL that is run at the end of message | |
29226 | reception (the acl_smtp_data ACL). | |
29227 | ||
29228 | * An additional control feature ("no_mbox_unspool") that saves spooled copies | |
29229 | of messages, or parts of messages, for debugging purposes. | |
29230 | ||
29231 | * Additional expansion variables that are set in the new ACL and by the new | |
29232 | conditions. | |
29233 | ||
29234 | * Two new main configuration options: av_scanner and spamd_address. | |
29235 | ||
420a0d19 CE |
29236 | Content-scanning is continually evolving, and new features are still being |
29237 | added. While such features are still unstable and liable to incompatible | |
29238 | changes, they are made available in Exim by setting options whose names begin | |
29239 | EXPERIMENTAL_ in Local/Makefile. Such features are not documented in this | |
29240 | manual. You can find out about them by reading the file called doc/ | |
29241 | experimental.txt. | |
29242 | ||
29243 | All the content-scanning facilities work on a MBOX copy of the message that is | |
29244 | temporarily created in a file called: | |
29245 | ||
29246 | <spool_directory>/scan/<message_id>/<message_id>.eml | |
29247 | ||
29248 | The .eml extension is a friendly hint to virus scanners that they can expect an | |
29249 | MBOX-like structure inside that file. The file is created when the first | |
29250 | content scanning facility is called. Subsequent calls to content scanning | |
29251 | conditions open the same file again. The directory is recursively removed when | |
29252 | the acl_smtp_data ACL has finished running, unless | |
29253 | ||
29254 | control = no_mbox_unspool | |
29255 | ||
29256 | has been encountered. When the MIME ACL decodes files, they are put into the | |
29257 | same directory by default. | |
29258 | ||
29259 | ||
2813c06e | 29260 | 44.1 Scanning for viruses |
420a0d19 CE |
29261 | ------------------------- |
29262 | ||
29263 | The malware ACL condition lets you connect virus scanner software to Exim. It | |
29264 | supports a "generic" interface to scanners called via the shell, and | |
29265 | specialized interfaces for "daemon" type virus scanners, which are resident in | |
29266 | memory and thus are much faster. | |
29267 | ||
2813c06e CE |
29268 | A timeout of 2 minutes is applied to a scanner call (by default); if it expires |
29269 | then a defer action is taken. | |
29270 | ||
29271 | You can set the av_scanner option in the main part of the configuration to | |
29272 | specify which scanner to use, together with any additional options that are | |
420a0d19 CE |
29273 | needed. The basic syntax is as follows: |
29274 | ||
29275 | av_scanner = <scanner-type>:<option1>:<option2>:[...] | |
29276 | ||
29277 | If you do not set av_scanner, it defaults to | |
29278 | ||
29279 | av_scanner = sophie:/var/run/sophie | |
29280 | ||
29281 | If the value of av_scanner starts with a dollar character, it is expanded | |
2813c06e | 29282 | before use. The usual list-parsing of the content (see 6.20) applies. The |
420a0d19 CE |
29283 | following scanner types are supported in this release: |
29284 | ||
2813c06e CE |
29285 | avast |
29286 | ||
29287 | This is the scanner daemon of Avast. It has been tested with Avast Core | |
29288 | Security (currently at version 1.1.7). You can get a trial version at http: | |
29289 | //www.avast.com or for Linux at http://www.avast.com/linux-server-antivirus | |
29290 | . This scanner type takes one option, which can be either a full path to a | |
29291 | UNIX socket, or host and port specifiers separated by white space. The host | |
29292 | may be a name or an IP address; the port is either a single number or a | |
29293 | pair of numbers with a dash between. Any further options are given, on | |
29294 | separate lines, to the daemon as options before the main scan command. For | |
29295 | example: | |
29296 | ||
29297 | av_scanner = avast:/var/run/avast/scan.sock:FLAGS -fullfiles:SENSITIVITY -pup | |
29298 | av_scanner = avast:192.168.2.22 5036 | |
29299 | ||
29300 | If you omit the argument, the default path /var/run/avast/scan.sock is | |
29301 | used. If you use a remote host, you need to make Exim's spool directory | |
29302 | available to it, as the scanner is passed a file path, not file contents. | |
29303 | For information about available commands and their options you may use | |
29304 | ||
29305 | $ socat UNIX:/var/run/avast/scan.sock STDIO: | |
29306 | FLAGS | |
29307 | SENSITIVITY | |
29308 | PACK | |
29309 | ||
420a0d19 CE |
29310 | aveserver |
29311 | ||
29312 | This is the scanner daemon of Kaspersky Version 5. You can get a trial | |
29313 | version at http://www.kaspersky.com. This scanner type takes one option, | |
29314 | which is the path to the daemon's UNIX socket. The default is shown in this | |
29315 | example: | |
29316 | ||
29317 | av_scanner = aveserver:/var/run/aveserver | |
29318 | ||
29319 | clamd | |
29320 | ||
29321 | This daemon-type scanner is GPL and free. You can get it at http:// | |
29322 | www.clamav.net/. Some older versions of clamd do not seem to unpack MIME | |
29323 | containers, so it used to be recommended to unpack MIME attachments in the | |
2813c06e CE |
29324 | MIME ACL. This is no longer believed to be necessary. |
29325 | ||
29326 | The options are a list of server specifiers, which may be a UNIX socket | |
29327 | specification, a TCP socket specification, or a (global) option. | |
29328 | ||
29329 | A socket specification consists of a space-separated list. For a Unix | |
29330 | socket the first element is a full path for the socket, for a TCP socket | |
29331 | the first element is the IP address and the second a port number, Any | |
29332 | further elements are per-server (non-global) options. These per-server | |
29333 | options are supported: | |
29334 | ||
29335 | retry=<timespec> Retry on connect fail | |
29336 | ||
29337 | The "retry" option specifies a time after which a single retry for a failed | |
29338 | connect is made. The default is to not retry. | |
29339 | ||
29340 | If a Unix socket file is specified, only one server is supported. | |
29341 | ||
29342 | Examples: | |
420a0d19 CE |
29343 | |
29344 | av_scanner = clamd:/opt/clamd/socket | |
29345 | av_scanner = clamd:192.0.2.3 1234 | |
29346 | av_scanner = clamd:192.0.2.3 1234:local | |
2813c06e | 29347 | av_scanner = clamd:192.0.2.3 1234 retry=10s |
420a0d19 CE |
29348 | av_scanner = clamd:192.0.2.3 1234 : 192.0.2.4 1234 |
29349 | ||
29350 | If the value of av_scanner points to a UNIX socket file or contains the | |
2813c06e | 29351 | "local" option, then the ClamAV interface will pass a filename containing |
420a0d19 CE |
29352 | the data to be scanned, which will should normally result in less I/O |
29353 | happening and be more efficient. Normally in the TCP case, the data is | |
29354 | streamed to ClamAV as Exim does not assume that there is a common | |
29355 | filesystem with the remote host. There is an option WITH_OLD_CLAMAV_STREAM | |
29356 | in src/EDITME available, should you be running a version of ClamAV prior to | |
29357 | 0.95. | |
29358 | ||
29359 | The final example shows that multiple TCP targets can be specified. Exim | |
29360 | will randomly use one for each incoming email (i.e. it load balances them). | |
29361 | Note that only TCP targets may be used if specifying a list of scanners; a | |
29362 | UNIX socket cannot be mixed in with TCP targets. If one of the servers | |
29363 | becomes unavailable, Exim will try the remaining one(s) until it finds one | |
29364 | that works. When a clamd server becomes unreachable, Exim will log a | |
29365 | message. Exim does not keep track of scanner state between multiple | |
29366 | messages, and the scanner selection is random, so the message will get | |
29367 | logged in the mainlog for each email that the down scanner gets chosen | |
29368 | first (message wrapped to be readable): | |
29369 | ||
29370 | 2013-10-09 14:30:39 1VTumd-0000Y8-BQ malware acl condition: | |
29371 | clamd: connection to localhost, port 3310 failed | |
29372 | (Connection refused) | |
29373 | ||
29374 | If the option is unset, the default is /tmp/clamd. Thanks to David Saez for | |
29375 | contributing the code for this scanner. | |
29376 | ||
29377 | cmdline | |
29378 | ||
29379 | This is the keyword for the generic command line scanner interface. It can | |
29380 | be used to attach virus scanners that are invoked from the shell. This | |
29381 | scanner type takes 3 mandatory options: | |
29382 | ||
29383 | 1. The full path and name of the scanner binary, with all command line | |
29384 | options, and a placeholder ("%s") for the directory to scan. | |
29385 | ||
29386 | 2. A regular expression to match against the STDOUT and STDERR output of | |
29387 | the virus scanner. If the expression matches, a virus was found. You | |
29388 | must make absolutely sure that this expression matches on "virus | |
29389 | found". This is called the "trigger" expression. | |
29390 | ||
29391 | 3. Another regular expression, containing exactly one pair of parentheses, | |
29392 | to match the name of the virus found in the scanners output. This is | |
29393 | called the "name" expression. | |
29394 | ||
29395 | For example, Sophos Sweep reports a virus on a line like this: | |
29396 | ||
29397 | Virus 'W32/Magistr-B' found in file ./those.bat | |
29398 | ||
29399 | For the trigger expression, we can match the phrase "found in file". For | |
29400 | the name expression, we want to extract the W32/Magistr-B string, so we can | |
29401 | match for the single quotes left and right of it. Altogether, this makes | |
29402 | the configuration setting: | |
29403 | ||
29404 | av_scanner = cmdline:\ | |
29405 | /path/to/sweep -ss -all -rec -archive %s:\ | |
29406 | found in file:'(.+)' | |
29407 | ||
29408 | drweb | |
29409 | ||
2813c06e CE |
29410 | The DrWeb daemon scanner (http://www.sald.com/) interface takes one option, |
29411 | either a full path to a UNIX socket, or host and port specifiers separated | |
29412 | by white space. The host may be a name or an IP address; the port is either | |
29413 | a single number or a pair of numbers with a dash between. For example: | |
420a0d19 CE |
29414 | |
29415 | av_scanner = drweb:/var/run/drwebd.sock | |
29416 | av_scanner = drweb:192.168.2.20 31337 | |
29417 | ||
29418 | If you omit the argument, the default path /usr/local/drweb/run/drwebd.sock | |
29419 | is used. Thanks to Alex Miller for contributing the code for this scanner. | |
29420 | ||
2813c06e CE |
29421 | f-protd |
29422 | ||
29423 | The f-protd scanner is accessed via HTTP over TCP. One argument is taken, | |
29424 | being a space-separated hostname and port number (or port-range). For | |
29425 | example: | |
29426 | ||
29427 | av_scanner = f-protd:localhost 10200-10204 | |
29428 | ||
29429 | If you omit the argument, the default values show above are used. | |
29430 | ||
420a0d19 CE |
29431 | fsecure |
29432 | ||
29433 | The F-Secure daemon scanner (http://www.f-secure.com) takes one argument | |
29434 | which is the path to a UNIX socket. For example: | |
29435 | ||
29436 | av_scanner = fsecure:/path/to/.fsav | |
29437 | ||
29438 | If no argument is given, the default is /var/run/.fsav. Thanks to Johan | |
29439 | Thelmen for contributing the code for this scanner. | |
29440 | ||
29441 | kavdaemon | |
29442 | ||
29443 | This is the scanner daemon of Kaspersky Version 4. This version of the | |
29444 | Kaspersky scanner is outdated. Please upgrade (see aveserver above). This | |
29445 | scanner type takes one option, which is the path to the daemon's UNIX | |
29446 | socket. For example: | |
29447 | ||
29448 | av_scanner = kavdaemon:/opt/AVP/AvpCtl | |
29449 | ||
29450 | The default path is /var/run/AvpCtl. | |
29451 | ||
29452 | mksd | |
29453 | ||
29454 | This is a daemon type scanner that is aimed mainly at Polish users, though | |
29455 | some parts of documentation are now available in English. You can get it at | |
29456 | http://linux.mks.com.pl/. The only option for this scanner type is the | |
29457 | maximum number of processes used simultaneously to scan the attachments, | |
2813c06e CE |
29458 | provided that mksd has been run with at least the same number of child |
29459 | processes. For example: | |
420a0d19 CE |
29460 | |
29461 | av_scanner = mksd:2 | |
29462 | ||
29463 | You can safely omit this option (the default value is 1). | |
29464 | ||
29465 | sock | |
29466 | ||
29467 | This is a general-purpose way of talking to simple scanner daemons running | |
29468 | on the local machine. There are four options: an address (which may be an | |
2813c06e | 29469 | IP address and port, or the path of a Unix socket), a commandline to send |
420a0d19 CE |
29470 | (may include a single %s which will be replaced with the path to the mail |
29471 | file to be scanned), an RE to trigger on from the returned data, an RE to | |
29472 | extract malware_name from the returned data. For example: | |
29473 | ||
29474 | av_scanner = sock:127.0.0.1 6001:%s:(SPAM|VIRUS):(.*)\$ | |
29475 | ||
29476 | Default for the socket specifier is /tmp/malware.sock. Default for the | |
29477 | commandline is %s\n. Both regular-expressions are required. | |
29478 | ||
29479 | sophie | |
29480 | ||
29481 | Sophie is a daemon that uses Sophos' libsavi library to scan for viruses. | |
29482 | You can get Sophie at http://www.clanfield.info/sophie/. The only option | |
29483 | for this scanner type is the path to the UNIX socket that Sophie uses for | |
29484 | client communication. For example: | |
29485 | ||
29486 | av_scanner = sophie:/tmp/sophie | |
29487 | ||
29488 | The default path is /var/run/sophie, so if you are using this, you can omit | |
29489 | the option. | |
29490 | ||
29491 | When av_scanner is correctly set, you can use the malware condition in the DATA | |
29492 | ACL. Note: You cannot use the malware condition in the MIME ACL. | |
29493 | ||
29494 | The av_scanner option is expanded each time malware is called. This makes it | |
29495 | possible to use different scanners. See further below for an example. The | |
29496 | malware condition caches its results, so when you use it multiple times for the | |
29497 | same message, the actual scanning process is only carried out once. However, | |
29498 | using expandable items in av_scanner disables this caching, in which case each | |
29499 | use of the malware condition causes a new scan of the message. | |
29500 | ||
2813c06e CE |
29501 | The malware condition takes a right-hand argument that is expanded before use |
29502 | and taken as a list, slash-separated by default. The first element can then be | |
29503 | one of | |
420a0d19 CE |
29504 | |
29505 | * "true", "*", or "1", in which case the message is scanned for viruses. The | |
29506 | condition succeeds if a virus was found, and fail otherwise. This is the | |
29507 | recommended usage. | |
29508 | ||
29509 | * "false" or "0" or an empty string, in which case no scanning is done and | |
29510 | the condition fails immediately. | |
29511 | ||
29512 | * A regular expression, in which case the message is scanned for viruses. The | |
29513 | condition succeeds if a virus is found and its name matches the regular | |
29514 | expression. This allows you to take special actions on certain types of | |
2813c06e CE |
29515 | virus. Note that "/" characters in the RE must be doubled due to the |
29516 | list-processing, unless the separator is changed (in the usual way). | |
420a0d19 | 29517 | |
2813c06e CE |
29518 | You can append a "defer_ok" element to the malware argument list to accept |
29519 | messages even if there is a problem with the virus scanner. Otherwise, such a | |
29520 | problem causes the ACL to defer. | |
29521 | ||
29522 | You can append a "tmo=<val>" element to the malware argument list to specify a | |
29523 | non-default timeout. The default is two minutes. For example: | |
29524 | ||
29525 | malware = * / defer_ok / tmo=10s | |
29526 | ||
29527 | A timeout causes the ACL to defer. | |
29528 | ||
29529 | When a connection is made to the scanner the expansion variable | |
29530 | $callout_address is set to record the actual address used. | |
420a0d19 CE |
29531 | |
29532 | When a virus is found, the condition sets up an expansion variable called | |
29533 | $malware_name that contains the name of the virus. You can use it in a message | |
29534 | modifier that specifies the error returned to the sender, and/or in logging | |
29535 | data. | |
29536 | ||
420a0d19 CE |
29537 | Beware the interaction of Exim's message_size_limit with any size limits |
29538 | imposed by your anti-virus scanner. | |
29539 | ||
29540 | Here is a very simple scanning example: | |
29541 | ||
29542 | deny message = This message contains malware ($malware_name) | |
420a0d19 CE |
29543 | malware = * |
29544 | ||
29545 | The next example accepts messages when there is a problem with the scanner: | |
29546 | ||
29547 | deny message = This message contains malware ($malware_name) | |
420a0d19 CE |
29548 | malware = */defer_ok |
29549 | ||
29550 | The next example shows how to use an ACL variable to scan with both sophie and | |
29551 | aveserver. It assumes you have set: | |
29552 | ||
29553 | av_scanner = $acl_m0 | |
29554 | ||
29555 | in the main Exim configuration. | |
29556 | ||
29557 | deny message = This message contains malware ($malware_name) | |
29558 | set acl_m0 = sophie | |
29559 | malware = * | |
29560 | ||
29561 | deny message = This message contains malware ($malware_name) | |
29562 | set acl_m0 = aveserver | |
29563 | malware = * | |
29564 | ||
29565 | ||
2813c06e CE |
29566 | 44.2 Scanning with SpamAssassin and Rspamd |
29567 | ------------------------------------------ | |
420a0d19 CE |
29568 | |
29569 | The spam ACL condition calls SpamAssassin's spamd daemon to get a spam score | |
2813c06e CE |
29570 | and a report for the message. Support is also provided for Rspamd. |
29571 | ||
29572 | For more information about installation and configuration of SpamAssassin or | |
29573 | Rspamd refer to their respective websites at http://spamassassin.apache.org and | |
29574 | http://www.rspamd.com | |
29575 | ||
29576 | SpamAssassin can be installed with CPAN by running: | |
420a0d19 CE |
29577 | |
29578 | perl -MCPAN -e 'install Mail::SpamAssassin' | |
29579 | ||
29580 | SpamAssassin has its own set of configuration files. Please review its | |
29581 | documentation to see how you can tweak it. The default installation should work | |
29582 | nicely, however. | |
29583 | ||
2813c06e CE |
29584 | By default, SpamAssassin listens on 127.0.0.1, TCP port 783 and if you intend |
29585 | to use an instance running on the local host you do not need to set | |
29586 | spamd_address. If you intend to use another host or port for SpamAssassin, you | |
29587 | must set the spamd_address option in the global part of the Exim configuration | |
29588 | as follows (example): | |
420a0d19 CE |
29589 | |
29590 | spamd_address = 192.168.99.45 387 | |
29591 | ||
2813c06e CE |
29592 | The SpamAssassin protocol relies on a TCP half-close from the client. If your |
29593 | SpamAssassin client side is running a Linux system with an iptables firewall, | |
29594 | consider setting net.netfilter.nf_conntrack_tcp_timeout_close_wait to at least | |
29595 | the timeout, Exim uses when waiting for a response from the SpamAssassin server | |
29596 | (currently defaulting to 120s). With a lower value the Linux connection | |
29597 | tracking may consider your half-closed connection as dead too soon. | |
29598 | ||
29599 | To use Rspamd (which by default listens on all local addresses on TCP port | |
29600 | 11333) you should add variant=rspamd after the address/port pair, for example: | |
29601 | ||
29602 | spamd_address = 127.0.0.1 11333 variant=rspamd | |
29603 | ||
29604 | As of version 2.60, SpamAssassin also supports communication over UNIX sockets. | |
29605 | If you want to us these, supply spamd_address with an absolute file name | |
29606 | instead of an address/port pair: | |
420a0d19 CE |
29607 | |
29608 | spamd_address = /var/run/spamd_socket | |
29609 | ||
29610 | You can have multiple spamd servers to improve scalability. These can reside on | |
29611 | other hardware reachable over the network. To specify multiple spamd servers, | |
29612 | put multiple address/port pairs in the spamd_address option, separated with | |
2813c06e | 29613 | colons (the separator can be changed in the usual way): |
420a0d19 CE |
29614 | |
29615 | spamd_address = 192.168.2.10 783 : \ | |
29616 | 192.168.2.11 783 : \ | |
29617 | 192.168.2.12 783 | |
29618 | ||
2813c06e CE |
29619 | Up to 32 spamd servers are supported. When a server fails to respond to the |
29620 | connection attempt, all other servers are tried until one succeeds. If no | |
29621 | server responds, the spam condition defers. | |
29622 | ||
29623 | Unix and TCP socket specifications may be mixed in any order. Each element of | |
29624 | the list is a list itself, space-separated by default and changeable in the | |
29625 | usual way; take care to not double the separator. | |
29626 | ||
29627 | For TCP socket specifications a host name or IP (v4 or v6, but subject to | |
29628 | list-separator quoting rules) address can be used, and the port can be one or a | |
29629 | dash-separated pair. In the latter case, the range is tried in strict order. | |
29630 | ||
29631 | Elements after the first for Unix sockets, or second for TCP socket, are | |
29632 | options. The supported options are: | |
29633 | ||
29634 | pri=<priority> Selection priority | |
29635 | weight=<value> Selection bias | |
29636 | time=<start>-<end> Use only between these times of day | |
29637 | retry=<timespec> Retry on connect fail | |
29638 | tmo=<timespec> Connection time limit | |
29639 | variant=rspamd Use Rspamd rather than SpamAssassin protocol | |
420a0d19 | 29640 | |
2813c06e CE |
29641 | The "pri" option specifies a priority for the server within the list, higher |
29642 | values being tried first. The default priority is 1. | |
29643 | ||
29644 | The "weight" option specifies a selection bias. Within a priority set servers | |
29645 | are queried in a random fashion, weighted by this value. The default value for | |
29646 | selection bias is 1. | |
29647 | ||
29648 | Time specifications for the "time" option are <hour>.<minute>.<second> in the | |
29649 | local time zone; each element being one or more digits. Either the seconds or | |
29650 | both minutes and seconds, plus the leading "." characters, may be omitted and | |
29651 | will be taken as zero. | |
29652 | ||
29653 | Timeout specifications for the "retry" and "tmo" options are the usual Exim | |
29654 | time interval standard, e.g. "20s" or "1m". | |
29655 | ||
29656 | The "tmo" option specifies an overall timeout for communication. The default | |
29657 | value is two minutes. | |
29658 | ||
29659 | The "retry" option specifies a time after which a single retry for a failed | |
29660 | connect is made. The default is to not retry. | |
420a0d19 CE |
29661 | |
29662 | The spamd_address variable is expanded before use if it starts with a dollar | |
29663 | sign. In this case, the expansion may return a string that is used as the list | |
29664 | so that multiple spamd servers can be the result of an expansion. | |
29665 | ||
2813c06e CE |
29666 | When a connection is made to the server the expansion variable $callout_address |
29667 | is set to record the actual address used. | |
420a0d19 | 29668 | |
2813c06e CE |
29669 | |
29670 | 44.3 Calling SpamAssassin from an Exim ACL | |
420a0d19 CE |
29671 | ------------------------------------------ |
29672 | ||
29673 | Here is a simple example of the use of the spam condition in a DATA ACL: | |
29674 | ||
29675 | deny message = This message was classified as SPAM | |
29676 | spam = joe | |
29677 | ||
29678 | The right-hand side of the spam condition specifies a name. This is relevant if | |
29679 | you have set up multiple SpamAssassin profiles. If you do not want to scan | |
29680 | using a specific profile, but rather use the SpamAssassin system-wide default | |
2813c06e CE |
29681 | profile, you can scan for an unknown name, or simply use "nobody". Rspamd does |
29682 | not use this setting. However, you must put something on the right-hand side. | |
420a0d19 CE |
29683 | |
29684 | The name allows you to use per-domain or per-user antispam profiles in | |
29685 | principle, but this is not straightforward in practice, because a message may | |
29686 | have multiple recipients, not necessarily all in the same domain. Because the | |
2813c06e CE |
29687 | spam condition has to be called from a DATA-time ACL in order to be able to |
29688 | read the contents of the message, the variables $local_part and $domain are not | |
29689 | set. Careful enforcement of single-recipient messages (e.g. by responding with | |
29690 | defer in the recipient ACL for all recipients after the first), or the use of | |
29691 | PRDR, are needed to use this feature. | |
420a0d19 CE |
29692 | |
29693 | The right-hand side of the spam condition is expanded before being used, so you | |
29694 | can put lookups or conditions there. When the right-hand side evaluates to "0" | |
29695 | or "false", no scanning is done and the condition fails immediately. | |
29696 | ||
29697 | Scanning with SpamAssassin uses a lot of resources. If you scan every message, | |
29698 | large ones may cause significant performance degradation. As most spam messages | |
29699 | are quite small, it is recommended that you do not scan the big ones. For | |
29700 | example: | |
29701 | ||
29702 | deny message = This message was classified as SPAM | |
29703 | condition = ${if < {$message_size}{10K}} | |
29704 | spam = nobody | |
29705 | ||
29706 | The spam condition returns true if the threshold specified in the user's | |
29707 | SpamAssassin profile has been matched or exceeded. If you want to use the spam | |
29708 | condition for its side effects (see the variables below), you can make it | |
29709 | always return "true" by appending ":true" to the username. | |
29710 | ||
29711 | When the spam condition is run, it sets up a number of expansion variables. | |
2813c06e CE |
29712 | Except for $spam_report, these variables are saved with the received message so |
29713 | are available for use at delivery time. | |
420a0d19 CE |
29714 | |
29715 | $spam_score | |
29716 | ||
29717 | The spam score of the message, for example "3.4" or "30.5". This is useful | |
29718 | for inclusion in log or reject messages. | |
29719 | ||
29720 | $spam_score_int | |
29721 | ||
29722 | The spam score of the message, multiplied by ten, as an integer value. For | |
29723 | example "34" or "305". It may appear to disagree with $spam_score because | |
29724 | $spam_score is rounded and $spam_score_int is truncated. The integer value | |
29725 | is useful for numeric comparisons in conditions. | |
29726 | ||
29727 | $spam_bar | |
29728 | ||
29729 | A string consisting of a number of "+" or "-" characters, representing the | |
29730 | integer part of the spam score value. A spam score of 4.4 would have a | |
29731 | $spam_bar value of "++++". This is useful for inclusion in warning headers, | |
2813c06e CE |
29732 | since MUAs can match on such strings. The maximum length of the spam bar is |
29733 | 50 characters. | |
420a0d19 CE |
29734 | |
29735 | $spam_report | |
29736 | ||
29737 | A multiline text table, containing the full SpamAssassin report for the | |
2813c06e CE |
29738 | message. Useful for inclusion in headers or reject messages. This variable |
29739 | is only usable in a DATA-time ACL. Beware that SpamAssassin may return | |
29740 | non-ASCII characters, especially when running in country-specific locales, | |
29741 | which are not legal unencoded in headers. | |
29742 | ||
29743 | $spam_action | |
29744 | ||
29745 | For SpamAssassin either 'reject' or 'no action' depending on the spam score | |
29746 | versus threshold. For Rspamd, the recommended action. | |
420a0d19 CE |
29747 | |
29748 | The spam condition caches its results unless expansion in spamd_address was | |
29749 | used. If you call it again with the same user name, it does not scan again, but | |
29750 | rather returns the same values as before. | |
29751 | ||
29752 | The spam condition returns DEFER if there is any error while running the | |
29753 | message through SpamAssassin or if the expansion of spamd_address failed. If | |
29754 | you want to treat DEFER as FAIL (to pass on to the next ACL statement block), | |
29755 | append "/defer_ok" to the right-hand side of the spam condition, like this: | |
29756 | ||
29757 | deny message = This message was classified as SPAM | |
29758 | spam = joe/defer_ok | |
29759 | ||
29760 | This causes messages to be accepted even if there is a problem with spamd. | |
29761 | ||
29762 | Here is a longer, commented example of the use of the spam condition: | |
29763 | ||
29764 | # put headers in all messages (no matter if spam or not) | |
29765 | warn spam = nobody:true | |
29766 | add_header = X-Spam-Score: $spam_score ($spam_bar) | |
29767 | add_header = X-Spam-Report: $spam_report | |
29768 | ||
29769 | # add second subject line with *SPAM* marker when message | |
29770 | # is over threshold | |
29771 | warn spam = nobody | |
29772 | add_header = Subject: *SPAM* $h_Subject: | |
29773 | ||
29774 | # reject spam at high scores (> 12) | |
29775 | deny message = This message scored $spam_score spam points. | |
29776 | spam = nobody:true | |
29777 | condition = ${if >{$spam_score_int}{120}{1}{0}} | |
29778 | ||
29779 | ||
2813c06e | 29780 | 44.4 Scanning MIME parts |
420a0d19 CE |
29781 | ------------------------ |
29782 | ||
29783 | The acl_smtp_mime global option specifies an ACL that is called once for each | |
29784 | MIME part of an SMTP message, including multipart types, in the sequence of | |
29785 | their position in the message. Similarly, the acl_not_smtp_mime option | |
29786 | specifies an ACL that is used for the MIME parts of non-SMTP messages. These | |
29787 | options may both refer to the same ACL if you want the same processing in both | |
29788 | cases. | |
29789 | ||
29790 | These ACLs are called (possibly many times) just before the acl_smtp_data ACL | |
29791 | in the case of an SMTP message, or just before the acl_not_smtp ACL in the case | |
29792 | of a non-SMTP message. However, a MIME ACL is called only if the message | |
29793 | contains a Content-Type: header line. When a call to a MIME ACL does not yield | |
29794 | "accept", ACL processing is aborted and the appropriate result code is sent to | |
29795 | the client. In the case of an SMTP message, the acl_smtp_data ACL is not called | |
29796 | when this happens. | |
29797 | ||
29798 | You cannot use the malware or spam conditions in a MIME ACL; these can only be | |
29799 | used in the DATA or non-SMTP ACLs. However, you can use the regex condition to | |
29800 | match against the raw MIME part. You can also use the mime_regex condition to | |
2813c06e | 29801 | match against the decoded MIME part (see section 44.5). |
420a0d19 CE |
29802 | |
29803 | At the start of a MIME ACL, a number of variables are set from the header | |
29804 | information for the relevant MIME part. These are described below. The contents | |
29805 | of the MIME part are not by default decoded into a disk file except for MIME | |
29806 | parts whose content-type is "message/rfc822". If you want to decode a MIME part | |
29807 | into a disk file, you can use the decode condition. The general syntax is: | |
29808 | ||
29809 | decode = [/<path>/]<filename> | |
29810 | ||
29811 | The right hand side is expanded before use. After expansion, the value can be: | |
29812 | ||
29813 | 1. "0" or "false", in which case no decoding is done. | |
29814 | ||
29815 | 2. The string "default". In that case, the file is put in the temporary | |
29816 | "default" directory <spool_directory>/scan/<message_id>/ with a sequential | |
29817 | file name consisting of the message id and a sequence number. The full path | |
29818 | and name is available in $mime_decoded_filename after decoding. | |
29819 | ||
29820 | 3. A full path name starting with a slash. If the full name is an existing | |
29821 | directory, it is used as a replacement for the default directory. The | |
29822 | filename is then sequentially assigned. If the path does not exist, it is | |
29823 | used as the full path and file name. | |
29824 | ||
29825 | 4. If the string does not start with a slash, it is used as the filename, and | |
29826 | the default path is then used. | |
29827 | ||
29828 | The decode condition normally succeeds. It is only false for syntax errors or | |
29829 | unusual circumstances such as memory shortages. You can easily decode a file | |
29830 | with its original, proposed filename using | |
29831 | ||
29832 | decode = $mime_filename | |
29833 | ||
29834 | However, you should keep in mind that $mime_filename might contain anything. If | |
29835 | you place files outside of the default path, they are not automatically | |
29836 | unlinked. | |
29837 | ||
29838 | For RFC822 attachments (these are messages attached to messages, with a | |
29839 | content-type of "message/rfc822"), the ACL is called again in the same manner | |
29840 | as for the primary message, only that the $mime_is_rfc822 expansion variable is | |
29841 | set (see below). Attached messages are always decoded to disk before being | |
29842 | checked, and the files are unlinked once the check is done. | |
29843 | ||
29844 | The MIME ACL supports the regex and mime_regex conditions. These can be used to | |
29845 | match regular expressions against raw and decoded MIME parts, respectively. | |
2813c06e | 29846 | They are described in section 44.5. |
420a0d19 CE |
29847 | |
29848 | The following list describes all expansion variables that are available in the | |
29849 | MIME ACL: | |
29850 | ||
29851 | $mime_boundary | |
29852 | ||
29853 | If the current part is a multipart (see $mime_is_multipart) below, it | |
29854 | should have a boundary string, which is stored in this variable. If the | |
29855 | current part has no boundary parameter in the Content-Type: header, this | |
29856 | variable contains the empty string. | |
29857 | ||
29858 | $mime_charset | |
29859 | ||
29860 | This variable contains the character set identifier, if one was found in | |
29861 | the Content-Type: header. Examples for charset identifiers are: | |
29862 | ||
29863 | us-ascii | |
29864 | gb2312 (Chinese) | |
29865 | iso-8859-1 | |
29866 | ||
29867 | Please note that this value is not normalized, so you should do matches | |
29868 | case-insensitively. | |
29869 | ||
29870 | $mime_content_description | |
29871 | ||
29872 | This variable contains the normalized content of the Content-Description: | |
29873 | header. It can contain a human-readable description of the parts content. | |
29874 | Some implementations repeat the filename for attachments here, but they are | |
29875 | usually only used for display purposes. | |
29876 | ||
29877 | $mime_content_disposition | |
29878 | ||
29879 | This variable contains the normalized content of the Content-Disposition: | |
29880 | header. You can expect strings like "attachment" or "inline" here. | |
29881 | ||
29882 | $mime_content_id | |
29883 | ||
29884 | This variable contains the normalized content of the Content-ID: header. | |
29885 | This is a unique ID that can be used to reference a part from another part. | |
29886 | ||
29887 | $mime_content_size | |
29888 | ||
29889 | This variable is set only after the decode modifier (see above) has been | |
29890 | successfully run. It contains the size of the decoded part in kilobytes. | |
29891 | The size is always rounded up to full kilobytes, so only a completely empty | |
29892 | part has a $mime_content_size of zero. | |
29893 | ||
29894 | $mime_content_transfer_encoding | |
29895 | ||
29896 | This variable contains the normalized content of the | |
29897 | Content-transfer-encoding: header. This is a symbolic name for an encoding | |
29898 | type. Typical values are "base64" and "quoted-printable". | |
29899 | ||
29900 | $mime_content_type | |
29901 | ||
29902 | If the MIME part has a Content-Type: header, this variable contains its | |
29903 | value, lowercased, and without any options (like "name" or "charset"). Here | |
29904 | are some examples of popular MIME types, as they may appear in this | |
29905 | variable: | |
29906 | ||
29907 | text/plain | |
29908 | text/html | |
29909 | application/octet-stream | |
29910 | image/jpeg | |
29911 | audio/midi | |
29912 | ||
29913 | If the MIME part has no Content-Type: header, this variable contains the | |
29914 | empty string. | |
29915 | ||
29916 | $mime_decoded_filename | |
29917 | ||
29918 | This variable is set only after the decode modifier (see above) has been | |
29919 | successfully run. It contains the full path and file name of the file | |
29920 | containing the decoded data. | |
29921 | ||
29922 | $mime_filename | |
29923 | ||
29924 | This is perhaps the most important of the MIME variables. It contains a | |
29925 | proposed filename for an attachment, if one was found in either the | |
29926 | Content-Type: or Content-Disposition: headers. The filename will be RFC2047 | |
2813c06e CE |
29927 | or RFC2231 decoded, but no additional sanity checks are done. If no |
29928 | filename was found, this variable contains the empty string. | |
420a0d19 CE |
29929 | |
29930 | $mime_is_coverletter | |
29931 | ||
29932 | This variable attempts to differentiate the "cover letter" of an e-mail | |
29933 | from attached data. It can be used to clamp down on flashy or unnecessarily | |
29934 | encoded content in the cover letter, while not restricting attachments at | |
29935 | all. | |
29936 | ||
29937 | The variable contains 1 (true) for a MIME part believed to be part of the | |
29938 | cover letter, and 0 (false) for an attachment. At present, the algorithm is | |
29939 | as follows: | |
29940 | ||
29941 | 1. The outermost MIME part of a message is always a cover letter. | |
29942 | ||
29943 | 2. If a multipart/alternative or multipart/related MIME part is a cover | |
29944 | letter, so are all MIME subparts within that multipart. | |
29945 | ||
29946 | 3. If any other multipart is a cover letter, the first subpart is a cover | |
29947 | letter, and the rest are attachments. | |
29948 | ||
29949 | 4. All parts contained within an attachment multipart are attachments. | |
29950 | ||
29951 | As an example, the following will ban "HTML mail" (including that sent with | |
29952 | alternative plain text), while allowing HTML files to be attached. HTML | |
29953 | coverletter mail attached to non-HMTL coverletter mail will also be | |
29954 | allowed: | |
29955 | ||
29956 | deny message = HTML mail is not accepted here | |
29957 | !condition = $mime_is_rfc822 | |
29958 | condition = $mime_is_coverletter | |
29959 | condition = ${if eq{$mime_content_type}{text/html}{1}{0}} | |
29960 | ||
29961 | $mime_is_multipart | |
29962 | ||
29963 | This variable has the value 1 (true) when the current part has the main | |
29964 | type "multipart", for example "multipart/alternative" or "multipart/mixed". | |
29965 | Since multipart entities only serve as containers for other parts, you may | |
29966 | not want to carry out specific actions on them. | |
29967 | ||
29968 | $mime_is_rfc822 | |
29969 | ||
29970 | This variable has the value 1 (true) if the current part is not a part of | |
29971 | the checked message itself, but part of an attached message. Attached | |
29972 | message decoding is fully recursive. | |
29973 | ||
29974 | $mime_part_count | |
29975 | ||
29976 | This variable is a counter that is raised for each processed MIME part. It | |
29977 | starts at zero for the very first part (which is usually a multipart). The | |
29978 | counter is per-message, so it is reset when processing RFC822 attachments | |
29979 | (see $mime_is_rfc822). The counter stays set after acl_smtp_mime is | |
29980 | complete, so you can use it in the DATA ACL to determine the number of MIME | |
29981 | parts of a message. For non-MIME messages, this variable contains the value | |
29982 | -1. | |
29983 | ||
29984 | ||
2813c06e | 29985 | 44.5 Scanning with regular expressions |
420a0d19 CE |
29986 | -------------------------------------- |
29987 | ||
29988 | You can specify your own custom regular expression matches on the full body of | |
29989 | the message, or on individual MIME parts. | |
29990 | ||
29991 | The regex condition takes one or more regular expressions as arguments and | |
29992 | matches them against the full message (when called in the DATA ACL) or a raw | |
29993 | MIME part (when called in the MIME ACL). The regex condition matches linewise, | |
29994 | with a maximum line length of 32K characters. That means you cannot have | |
29995 | multiline matches with the regex condition. | |
29996 | ||
29997 | The mime_regex condition can be called only in the MIME ACL. It matches up to | |
29998 | 32K of decoded content (the whole content at once, not linewise). If the part | |
29999 | has not been decoded with the decode modifier earlier in the ACL, it is decoded | |
30000 | automatically when mime_regex is executed (using default path and filename | |
30001 | values). If the decoded data is larger than 32K, only the first 32K characters | |
30002 | are checked. | |
30003 | ||
30004 | The regular expressions are passed as a colon-separated list. To include a | |
30005 | literal colon, you must double it. Since the whole right-hand side string is | |
30006 | expanded before being used, you must also escape dollar signs and backslashes | |
30007 | with more backslashes, or use the "\N" facility to disable expansion. Here is a | |
30008 | simple example that contains two regular expressions: | |
30009 | ||
30010 | deny message = contains blacklisted regex ($regex_match_string) | |
30011 | regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL | |
30012 | ||
30013 | The conditions returns true if any one of the regular expressions matches. The | |
30014 | $regex_match_string expansion variable is then set up and contains the matching | |
2813c06e CE |
30015 | regular expression. The expansion variables $regex1 $regex2 etc are set to any |
30016 | substrings captured by the regular expression. | |
420a0d19 CE |
30017 | |
30018 | Warning: With large messages, these conditions can be fairly CPU-intensive. | |
30019 | ||
30020 | ||
420a0d19 CE |
30021 | |
30022 | =============================================================================== | |
2813c06e | 30023 | 45. ADDING A LOCAL SCAN FUNCTION TO EXIM |
420a0d19 CE |
30024 | |
30025 | In these days of email worms, viruses, and ever-increasing spam, some sites | |
30026 | want to apply a lot of checking to messages before accepting them. | |
30027 | ||
2813c06e | 30028 | The content scanning extension (chapter 44) has facilities for passing messages |
420a0d19 CE |
30029 | to external virus and spam scanning software. You can also do a certain amount |
30030 | in Exim itself through string expansions and the condition condition in the ACL | |
30031 | that runs after the SMTP DATA command or the ACL for non-SMTP messages (see | |
2813c06e | 30032 | chapter 43), but this has its limitations. |
420a0d19 CE |
30033 | |
30034 | To allow for further customization to a site's own requirements, there is the | |
30035 | possibility of linking Exim with a private message scanning function, written | |
30036 | in C. If you want to run code that is written in something other than C, you | |
30037 | can of course use a little C stub to call it. | |
30038 | ||
30039 | The local scan function is run once for every incoming message, at the point | |
30040 | when Exim is just about to accept the message. It can therefore be used to | |
30041 | control non-SMTP messages from local processes as well as messages arriving via | |
30042 | SMTP. | |
30043 | ||
30044 | Exim applies a timeout to calls of the local scan function, and there is an | |
30045 | option called local_scan_timeout for setting it. The default is 5 minutes. Zero | |
30046 | means "no timeout". Exim also sets up signal handlers for SIGSEGV, SIGILL, | |
30047 | SIGFPE, and SIGBUS before calling the local scan function, so that the most | |
30048 | common types of crash are caught. If the timeout is exceeded or one of those | |
30049 | signals is caught, the incoming message is rejected with a temporary error if | |
30050 | it is an SMTP message. For a non-SMTP message, the message is dropped and Exim | |
30051 | ends with a non-zero code. The incident is logged on the main and reject logs. | |
30052 | ||
30053 | ||
2813c06e | 30054 | 45.1 Building Exim to use a local scan function |
420a0d19 CE |
30055 | ----------------------------------------------- |
30056 | ||
30057 | To make use of the local scan function feature, you must tell Exim where your | |
30058 | function is before building Exim, by setting LOCAL_SCAN_SOURCE in your Local/ | |
30059 | Makefile. A recommended place to put it is in the Local directory, so you might | |
30060 | set | |
30061 | ||
30062 | LOCAL_SCAN_SOURCE=Local/local_scan.c | |
30063 | ||
30064 | for example. The function must be called local_scan(). It is called by Exim | |
30065 | after it has received a message, when the success return code is about to be | |
30066 | sent. This is after all the ACLs have been run. The return code from your | |
30067 | function controls whether the message is actually accepted or not. There is a | |
30068 | commented template function (that just accepts the message) in the file _src/ | |
30069 | local_scan.c_. | |
30070 | ||
30071 | If you want to make use of Exim's run time configuration file to set options | |
30072 | for your local_scan() function, you must also set | |
30073 | ||
30074 | LOCAL_SCAN_HAS_OPTIONS=yes | |
30075 | ||
2813c06e | 30076 | in Local/Makefile (see section 45.3 below). |
420a0d19 CE |
30077 | |
30078 | ||
2813c06e | 30079 | 45.2 API for local_scan() |
420a0d19 CE |
30080 | ------------------------- |
30081 | ||
30082 | You must include this line near the start of your code: | |
30083 | ||
30084 | #include "local_scan.h" | |
30085 | ||
30086 | This header file defines a number of variables and other values, and the | |
30087 | prototype for the function itself. Exim is coded to use unsigned char values | |
30088 | almost exclusively, and one of the things this header defines is a shorthand | |
30089 | for "unsigned char" called "uschar". It also contains the following macro | |
30090 | definitions, to simplify casting character strings and pointers to character | |
30091 | strings: | |
30092 | ||
30093 | #define CS (char *) | |
30094 | #define CCS (const char *) | |
30095 | #define CSS (char **) | |
30096 | #define US (unsigned char *) | |
30097 | #define CUS (const unsigned char *) | |
30098 | #define USS (unsigned char **) | |
30099 | ||
30100 | The function prototype for local_scan() is: | |
30101 | ||
30102 | extern int local_scan(int fd, uschar **return_text); | |
30103 | ||
30104 | The arguments are as follows: | |
30105 | ||
30106 | * fd is a file descriptor for the file that contains the body of the message | |
30107 | (the -D file). The file is open for reading and writing, but updating it is | |
30108 | not recommended. Warning: You must not close this file descriptor. | |
30109 | ||
30110 | The descriptor is positioned at character 19 of the file, which is the | |
30111 | first character of the body itself, because the first 19 characters are the | |
30112 | message id followed by "-D" and a newline. If you rewind the file, you | |
30113 | should use the macro SPOOL_DATA_START_OFFSET to reset to the start of the | |
30114 | data, just in case this changes in some future version. | |
30115 | ||
30116 | * return_text is an address which you can use to return a pointer to a text | |
30117 | string at the end of the function. The value it points to on entry is NULL. | |
30118 | ||
30119 | The function must return an int value which is one of the following macros: | |
30120 | ||
30121 | "LOCAL_SCAN_ACCEPT" | |
30122 | ||
30123 | The message is accepted. If you pass back a string of text, it is saved | |
30124 | with the message, and made available in the variable $local_scan_data. No | |
30125 | newlines are permitted (if there are any, they are turned into spaces) and | |
30126 | the maximum length of text is 1000 characters. | |
30127 | ||
30128 | "LOCAL_SCAN_ACCEPT_FREEZE" | |
30129 | ||
30130 | This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is | |
30131 | queued without immediate delivery, and is frozen. | |
30132 | ||
30133 | "LOCAL_SCAN_ACCEPT_QUEUE" | |
30134 | ||
30135 | This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is | |
30136 | queued without immediate delivery. | |
30137 | ||
30138 | "LOCAL_SCAN_REJECT" | |
30139 | ||
30140 | The message is rejected; the returned text is used as an error message | |
30141 | which is passed back to the sender and which is also logged. Newlines are | |
30142 | permitted - they cause a multiline response for SMTP rejections, but are | |
30143 | converted to "\n" in log lines. If no message is given, "Administrative | |
30144 | prohibition" is used. | |
30145 | ||
30146 | "LOCAL_SCAN_TEMPREJECT" | |
30147 | ||
30148 | The message is temporarily rejected; the returned text is used as an error | |
30149 | message as for LOCAL_SCAN_REJECT. If no message is given, "Temporary local | |
30150 | problem" is used. | |
30151 | ||
30152 | "LOCAL_SCAN_REJECT_NOLOGHDR" | |
30153 | ||
30154 | This behaves as LOCAL_SCAN_REJECT, except that the header of the rejected | |
30155 | message is not written to the reject log. It has the effect of unsetting | |
30156 | the rejected_header log selector for just this rejection. If | |
30157 | rejected_header is already unset (see the discussion of the log_selection | |
2813c06e | 30158 | option in section 52.15), this code is the same as LOCAL_SCAN_REJECT. |
420a0d19 CE |
30159 | |
30160 | "LOCAL_SCAN_TEMPREJECT_NOLOGHDR" | |
30161 | ||
30162 | This code is a variation of LOCAL_SCAN_TEMPREJECT in the same way that | |
30163 | LOCAL_SCAN_REJECT_NOLOGHDR is a variation of LOCAL_SCAN_REJECT. | |
30164 | ||
30165 | If the message is not being received by interactive SMTP, rejections are | |
30166 | reported by writing to stderr or by sending an email, as configured by the -oe | |
30167 | command line options. | |
30168 | ||
30169 | ||
2813c06e | 30170 | 45.3 Configuration options for local_scan() |
420a0d19 CE |
30171 | ------------------------------------------- |
30172 | ||
30173 | It is possible to have option settings in the main configuration file that set | |
30174 | values in static variables in the local_scan() module. If you want to do this, | |
30175 | you must have the line | |
30176 | ||
30177 | LOCAL_SCAN_HAS_OPTIONS=yes | |
30178 | ||
30179 | in your Local/Makefile when you build Exim. (This line is in OS/ | |
30180 | Makefile-Default, commented out). Then, in the local_scan() source file, you | |
30181 | must define static variables to hold the option values, and a table to define | |
30182 | them. | |
30183 | ||
30184 | The table must be a vector called local_scan_options, of type "optionlist". | |
30185 | Each entry is a triplet, consisting of a name, an option type, and a pointer to | |
30186 | the variable that holds the value. The entries must appear in alphabetical | |
30187 | order. Following local_scan_options you must also define a variable called | |
30188 | local_scan_options_count that contains the number of entries in the table. Here | |
30189 | is a short example, showing two kinds of option: | |
30190 | ||
30191 | static int my_integer_option = 42; | |
30192 | static uschar *my_string_option = US"a default string"; | |
30193 | ||
30194 | optionlist local_scan_options[] = { | |
30195 | { "my_integer", opt_int, &my_integer_option }, | |
30196 | { "my_string", opt_stringptr, &my_string_option } | |
30197 | }; | |
30198 | ||
30199 | int local_scan_options_count = | |
30200 | sizeof(local_scan_options)/sizeof(optionlist); | |
30201 | ||
30202 | The values of the variables can now be changed from Exim's runtime | |
30203 | configuration file by including a local scan section as in this example: | |
30204 | ||
30205 | begin local_scan | |
30206 | my_integer = 99 | |
30207 | my_string = some string of text... | |
30208 | ||
30209 | The available types of option data are as follows: | |
30210 | ||
30211 | opt_bool | |
30212 | ||
30213 | This specifies a boolean (true/false) option. The address should point to a | |
30214 | variable of type "BOOL", which will be set to TRUE or FALSE, which are | |
30215 | macros that are defined as "1" and "0", respectively. If you want to detect | |
30216 | whether such a variable has been set at all, you can initialize it to | |
30217 | TRUE_UNSET. (BOOL variables are integers underneath, so can hold more than | |
30218 | two values.) | |
30219 | ||
30220 | opt_fixed | |
30221 | ||
30222 | This specifies a fixed point number, such as is used for load averages. The | |
30223 | address should point to a variable of type "int". The value is stored | |
30224 | multiplied by 1000, so, for example, 1.4142 is truncated and stored as | |
30225 | 1414. | |
30226 | ||
30227 | opt_int | |
30228 | ||
30229 | This specifies an integer; the address should point to a variable of type | |
30230 | "int". The value may be specified in any of the integer formats accepted by | |
30231 | Exim. | |
30232 | ||
30233 | opt_mkint | |
30234 | ||
30235 | This is the same as opt_int, except that when such a value is output in a | |
30236 | -bP listing, if it is an exact number of kilobytes or megabytes, it is | |
30237 | printed with the suffix K or M. | |
30238 | ||
30239 | opt_octint | |
30240 | ||
30241 | This also specifies an integer, but the value is always interpreted as an | |
30242 | octal integer, whether or not it starts with the digit zero, and it is | |
30243 | always output in octal. | |
30244 | ||
30245 | opt_stringptr | |
30246 | ||
30247 | This specifies a string value; the address must be a pointer to a variable | |
30248 | that points to a string (for example, of type "uschar *"). | |
30249 | ||
30250 | opt_time | |
30251 | ||
30252 | This specifies a time interval value. The address must point to a variable | |
30253 | of type "int". The value that is placed there is a number of seconds. | |
30254 | ||
30255 | If the -bP command line option is followed by "local_scan", Exim prints out the | |
30256 | values of all the local_scan() options. | |
30257 | ||
30258 | ||
2813c06e | 30259 | 45.4 Available Exim variables |
420a0d19 CE |
30260 | ----------------------------- |
30261 | ||
30262 | The header local_scan.h gives you access to a number of C variables. These are | |
30263 | the only ones that are guaranteed to be maintained from release to release. | |
30264 | Note, however, that you can obtain the value of any Exim expansion variable, | |
30265 | including $recipients, by calling expand_string(). The exported C variables are | |
30266 | as follows: | |
30267 | ||
30268 | int body_linecount | |
30269 | ||
30270 | This variable contains the number of lines in the message's body. | |
30271 | ||
30272 | int body_zerocount | |
30273 | ||
30274 | This variable contains the number of binary zero bytes in the message's | |
30275 | body. | |
30276 | ||
30277 | unsigned int debug_selector | |
30278 | ||
30279 | This variable is set to zero when no debugging is taking place. Otherwise, | |
30280 | it is a bitmap of debugging selectors. Two bits are identified for use in | |
30281 | local_scan(); they are defined as macros: | |
30282 | ||
2813c06e | 30283 | + The "D_v" bit is set when -v was present on the command line. This is a |
420a0d19 CE |
30284 | testing option that is not privileged - any caller may set it. All the |
30285 | other selector bits can be set only by admin users. | |
30286 | ||
2813c06e | 30287 | + The "D_local_scan" bit is provided for use by local_scan(); it is set |
420a0d19 CE |
30288 | by the "+local_scan" debug selector. It is not included in the default |
30289 | set of debugging bits. | |
30290 | ||
30291 | Thus, to write to the debugging output only when "+local_scan" has been | |
30292 | selected, you should use code like this: | |
30293 | ||
30294 | if ((debug_selector & D_local_scan) != 0) | |
30295 | debug_printf("xxx", ...); | |
30296 | ||
30297 | uschar *expand_string_message | |
30298 | ||
30299 | After a failing call to expand_string() (returned value NULL), the variable | |
30300 | expand_string_message contains the error message, zero-terminated. | |
30301 | ||
30302 | header_line *header_list | |
30303 | ||
30304 | A pointer to a chain of header lines. The header_line structure is | |
30305 | discussed below. | |
30306 | ||
30307 | header_line *header_last | |
30308 | ||
30309 | A pointer to the last of the header lines. | |
30310 | ||
30311 | uschar *headers_charset | |
30312 | ||
30313 | The value of the headers_charset configuration option. | |
30314 | ||
30315 | BOOL host_checking | |
30316 | ||
30317 | This variable is TRUE during a host checking session that is initiated by | |
30318 | the -bh command line option. | |
30319 | ||
30320 | uschar *interface_address | |
30321 | ||
30322 | The IP address of the interface that received the message, as a string. | |
30323 | This is NULL for locally submitted messages. | |
30324 | ||
30325 | int interface_port | |
30326 | ||
30327 | The port on which this message was received. When testing with the -bh | |
30328 | command line option, the value of this variable is -1 unless a port has | |
30329 | been specified via the -oMi option. | |
30330 | ||
30331 | uschar *message_id | |
30332 | ||
30333 | This variable contains Exim's message id for the incoming message (the | |
30334 | value of $message_exim_id) as a zero-terminated string. | |
30335 | ||
30336 | uschar *received_protocol | |
30337 | ||
30338 | The name of the protocol by which the message was received. | |
30339 | ||
30340 | int recipients_count | |
30341 | ||
30342 | The number of accepted recipients. | |
30343 | ||
30344 | recipient_item *recipients_list | |
30345 | ||
30346 | The list of accepted recipients, held in a vector of length | |
30347 | recipients_count. The recipient_item structure is discussed below. You can | |
30348 | add additional recipients by calling receive_add_recipient() (see below). | |
30349 | You can delete recipients by removing them from the vector and adjusting | |
30350 | the value in recipients_count. In particular, by setting recipients_count | |
30351 | to zero you remove all recipients. If you then return the value | |
30352 | "LOCAL_SCAN_ACCEPT", the message is accepted, but immediately blackholed. | |
30353 | To replace the recipients, you can set recipients_count to zero and then | |
30354 | call receive_add_recipient() as often as needed. | |
30355 | ||
30356 | uschar *sender_address | |
30357 | ||
30358 | The envelope sender address. For bounce messages this is the empty string. | |
30359 | ||
30360 | uschar *sender_host_address | |
30361 | ||
30362 | The IP address of the sending host, as a string. This is NULL for | |
30363 | locally-submitted messages. | |
30364 | ||
30365 | uschar *sender_host_authenticated | |
30366 | ||
30367 | The name of the authentication mechanism that was used, or NULL if the | |
30368 | message was not received over an authenticated SMTP connection. | |
30369 | ||
30370 | uschar *sender_host_name | |
30371 | ||
30372 | The name of the sending host, if known. | |
30373 | ||
30374 | int sender_host_port | |
30375 | ||
30376 | The port on the sending host. | |
30377 | ||
30378 | BOOL smtp_input | |
30379 | ||
30380 | This variable is TRUE for all SMTP input, including BSMTP. | |
30381 | ||
30382 | BOOL smtp_batched_input | |
30383 | ||
30384 | This variable is TRUE for BSMTP input. | |
30385 | ||
30386 | int store_pool | |
30387 | ||
30388 | The contents of this variable control which pool of memory is used for new | |
2813c06e | 30389 | requests. See section 45.8 for details. |
420a0d19 CE |
30390 | |
30391 | ||
2813c06e | 30392 | 45.5 Structure of header lines |
420a0d19 CE |
30393 | ------------------------------ |
30394 | ||
30395 | The header_line structure contains the members listed below. You can add | |
30396 | additional header lines by calling the header_add() function (see below). You | |
30397 | can cause header lines to be ignored (deleted) by setting their type to *. | |
30398 | ||
30399 | struct header_line *next | |
30400 | ||
30401 | A pointer to the next header line, or NULL for the last line. | |
30402 | ||
30403 | int type | |
30404 | ||
30405 | A code identifying certain headers that Exim recognizes. The codes are | |
2813c06e | 30406 | printing characters, and are documented in chapter 56 of this manual. |
420a0d19 CE |
30407 | Notice in particular that any header line whose type is * is not |
30408 | transmitted with the message. This flagging is used for header lines that | |
30409 | have been rewritten, or are to be removed (for example, Envelope-sender: | |
30410 | header lines.) Effectively, * means "deleted". | |
30411 | ||
30412 | int slen | |
30413 | ||
30414 | The number of characters in the header line, including the terminating and | |
30415 | any internal newlines. | |
30416 | ||
30417 | uschar *text | |
30418 | ||
30419 | A pointer to the text of the header. It always ends with a newline, | |
30420 | followed by a zero byte. Internal newlines are preserved. | |
30421 | ||
30422 | ||
2813c06e | 30423 | 45.6 Structure of recipient items |
420a0d19 CE |
30424 | --------------------------------- |
30425 | ||
30426 | The recipient_item structure contains these members: | |
30427 | ||
30428 | uschar *address | |
30429 | ||
30430 | This is a pointer to the recipient address as it was received. | |
30431 | ||
30432 | int pno | |
30433 | ||
30434 | This is used in later Exim processing when top level addresses are created | |
30435 | by the one_time option. It is not relevant at the time local_scan() is run | |
30436 | and must always contain -1 at this stage. | |
30437 | ||
30438 | uschar *errors_to | |
30439 | ||
30440 | If this value is not NULL, bounce messages caused by failing to deliver to | |
30441 | the recipient are sent to the address it contains. In other words, it | |
30442 | overrides the envelope sender for this one recipient. (Compare the | |
30443 | errors_to generic router option.) If a local_scan() function sets an | |
30444 | errors_to field to an unqualified address, Exim qualifies it using the | |
30445 | domain from qualify_recipient. When local_scan() is called, the errors_to | |
30446 | field is NULL for all recipients. | |
30447 | ||
30448 | ||
2813c06e | 30449 | 45.7 Available Exim functions |
420a0d19 CE |
30450 | ----------------------------- |
30451 | ||
30452 | The header local_scan.h gives you access to a number of Exim functions. These | |
30453 | are the only ones that are guaranteed to be maintained from release to release: | |
30454 | ||
30455 | pid_t child_open | |
30456 | (uschar **argv, uschar **envp, int newumask, int *infdptr, int *outfdptr, | |
30457 | BOOL make_leader) | |
30458 | ||
30459 | This function creates a child process that runs the command specified by | |
30460 | argv. The environment for the process is specified by envp, which can be | |
30461 | NULL if no environment variables are to be passed. A new umask is supplied | |
30462 | for the process in newumask. | |
30463 | ||
30464 | Pipes to the standard input and output of the new process are set up and | |
30465 | returned to the caller via the infdptr and outfdptr arguments. The standard | |
30466 | error is cloned to the standard output. If there are any file descriptors | |
30467 | "in the way" in the new process, they are closed. If the final argument is | |
30468 | TRUE, the new process is made into a process group leader. | |
30469 | ||
30470 | The function returns the pid of the new process, or -1 if things go wrong. | |
30471 | ||
30472 | int child_close(pid_t pid, int timeout) | |
30473 | ||
30474 | This function waits for a child process to terminate, or for a timeout (in | |
30475 | seconds) to expire. A timeout value of zero means wait as long as it takes. | |
30476 | The return value is as follows: | |
30477 | ||
2813c06e | 30478 | + >= 0 |
420a0d19 CE |
30479 | |
30480 | The process terminated by a normal exit and the value is the process | |
30481 | ending status. | |
30482 | ||
2813c06e | 30483 | + < 0 and > -256 |
420a0d19 CE |
30484 | |
30485 | The process was terminated by a signal and the value is the negation of | |
30486 | the signal number. | |
30487 | ||
2813c06e | 30488 | + -256 |
420a0d19 CE |
30489 | |
30490 | The process timed out. | |
30491 | ||
2813c06e | 30492 | + -257 |
420a0d19 CE |
30493 | |
30494 | The was some other error in wait(); errno is still set. | |
30495 | ||
30496 | pid_t child_open_exim(int *fd) | |
30497 | ||
30498 | This function provide you with a means of submitting a new message to Exim. | |
30499 | (Of course, you can also call /usr/sbin/sendmail yourself if you want, but | |
30500 | this packages it all up for you.) The function creates a pipe, forks a | |
30501 | subprocess that is running | |
30502 | ||
30503 | exim -t -oem -oi -f <> | |
30504 | ||
30505 | and returns to you (via the "int *" argument) a file descriptor for the | |
30506 | pipe that is connected to the standard input. The yield of the function is | |
30507 | the PID of the subprocess. You can then write a message to the file | |
30508 | descriptor, with recipients in To:, Cc:, and/or Bcc: header lines. | |
30509 | ||
30510 | When you have finished, call child_close() to wait for the process to | |
30511 | finish and to collect its ending status. A timeout value of zero is usually | |
30512 | fine in this circumstance. Unless you have made a mistake with the | |
30513 | recipient addresses, you should get a return code of zero. | |
30514 | ||
30515 | pid_t child_open_exim2(int *fd, uschar *sender, uschar *sender_authentication) | |
30516 | ||
30517 | This function is a more sophisticated version of child_open(). The command | |
30518 | that it runs is: | |
30519 | ||
30520 | exim -t -oem -oi -f sender -oMas sender_authentication | |
30521 | ||
30522 | The third argument may be NULL, in which case the -oMas option is omitted. | |
30523 | ||
30524 | void debug_printf(char *, ...) | |
30525 | ||
30526 | This is Exim's debugging function, with arguments as for (printf(). The | |
30527 | output is written to the standard error stream. If no debugging is | |
30528 | selected, calls to debug_printf() have no effect. Normally, you should make | |
30529 | calls conditional on the "local_scan" debug selector by coding like this: | |
30530 | ||
30531 | if ((debug_selector & D_local_scan) != 0) | |
30532 | debug_printf("xxx", ...); | |
30533 | ||
30534 | uschar *expand_string(uschar *string) | |
30535 | ||
30536 | This is an interface to Exim's string expansion code. The return value is | |
30537 | the expanded string, or NULL if there was an expansion failure. The C | |
30538 | variable expand_string_message contains an error message after an expansion | |
30539 | failure. If expansion does not change the string, the return value is the | |
30540 | pointer to the input string. Otherwise, the return value points to a new | |
30541 | block of memory that was obtained by a call to store_get(). See section | |
2813c06e | 30542 | 45.8 below for a discussion of memory handling. |
420a0d19 CE |
30543 | |
30544 | void header_add(int type, char *format, ...) | |
30545 | ||
30546 | This function allows you to an add additional header line at the end of the | |
30547 | existing ones. The first argument is the type, and should normally be a | |
30548 | space character. The second argument is a format string and any number of | |
30549 | substitution arguments as for sprintf(). You may include internal newlines | |
30550 | if you want, and you must ensure that the string ends with a newline. | |
30551 | ||
30552 | void header_add_at_position | |
30553 | (BOOL after, uschar *name, BOOL topnot, int type, char *format, ...) | |
30554 | ||
30555 | This function adds a new header line at a specified point in the header | |
30556 | chain. The header itself is specified as for header_add(). | |
30557 | ||
30558 | If name is NULL, the new header is added at the end of the chain if after | |
30559 | is true, or at the start if after is false. If name is not NULL, the header | |
30560 | lines are searched for the first non-deleted header that matches the name. | |
30561 | If one is found, the new header is added before it if after is false. If | |
30562 | after is true, the new header is added after the found header and any | |
30563 | adjacent subsequent ones with the same name (even if marked "deleted"). If | |
30564 | no matching non-deleted header is found, the topnot option controls where | |
30565 | the header is added. If it is true, addition is at the top; otherwise at | |
30566 | the bottom. Thus, to add a header after all the Received: headers, or at | |
30567 | the top if there are no Received: headers, you could use | |
30568 | ||
30569 | header_add_at_position(TRUE, US"Received", TRUE, | |
30570 | ' ', "X-xxx: ..."); | |
30571 | ||
30572 | Normally, there is always at least one non-deleted Received: header, but | |
30573 | there may not be if received_header_text expands to an empty string. | |
30574 | ||
30575 | void header_remove(int occurrence, uschar *name) | |
30576 | ||
30577 | This function removes header lines. If occurrence is zero or negative, all | |
30578 | occurrences of the header are removed. If occurrence is greater than zero, | |
30579 | that particular instance of the header is removed. If no header(s) can be | |
30580 | found that match the specification, the function does nothing. | |
30581 | ||
30582 | BOOL header_testname(header_line *hdr, uschar *name, int length, BOOL notdel) | |
30583 | ||
30584 | This function tests whether the given header has the given name. It is not | |
30585 | just a string comparison, because white space is permitted between the name | |
30586 | and the colon. If the notdel argument is true, a false return is forced for | |
30587 | all "deleted" headers; otherwise they are not treated specially. For | |
30588 | example: | |
30589 | ||
30590 | if (header_testname(h, US"X-Spam", 6, TRUE)) ... | |
30591 | ||
30592 | uschar *lss_b64encode(uschar *cleartext, int length) | |
30593 | ||
30594 | This function base64-encodes a string, which is passed by address and | |
30595 | length. The text may contain bytes of any value, including zero. The result | |
30596 | is passed back in dynamic memory that is obtained by calling store_get(). | |
30597 | It is zero-terminated. | |
30598 | ||
30599 | int lss_b64decode(uschar *codetext, uschar **cleartext) | |
30600 | ||
30601 | This function decodes a base64-encoded string. Its arguments are a | |
30602 | zero-terminated base64-encoded string and the address of a variable that is | |
30603 | set to point to the result, which is in dynamic memory. The length of the | |
30604 | decoded string is the yield of the function. If the input is invalid base64 | |
30605 | data, the yield is -1. A zero byte is added to the end of the output string | |
30606 | to make it easy to interpret as a C string (assuming it contains no zeros | |
30607 | of its own). The added zero byte is not included in the returned count. | |
30608 | ||
30609 | int lss_match_domain(uschar *domain, uschar *list) | |
30610 | ||
30611 | This function checks for a match in a domain list. Domains are always | |
30612 | matched caselessly. The return value is one of the following: | |
30613 | ||
30614 | OK match succeeded | |
30615 | FAIL match failed | |
30616 | DEFER match deferred | |
30617 | ||
30618 | DEFER is usually caused by some kind of lookup defer, such as the inability | |
30619 | to contact a database. | |
30620 | ||
30621 | int lss_match_local_part(uschar *localpart, uschar *list, BOOL caseless) | |
30622 | ||
30623 | This function checks for a match in a local part list. The third argument | |
30624 | controls case-sensitivity. The return values are as for lss_match_domain(). | |
30625 | ||
30626 | int lss_match_address(uschar *address, uschar *list, BOOL caseless) | |
30627 | ||
30628 | This function checks for a match in an address list. The third argument | |
30629 | controls the case-sensitivity of the local part match. The domain is always | |
30630 | matched caselessly. The return values are as for lss_match_domain(). | |
30631 | ||
30632 | int lss_match_host(uschar *host_name, uschar *host_address, uschar *list) | |
30633 | ||
30634 | This function checks for a match in a host list. The most common usage is | |
30635 | expected to be | |
30636 | ||
30637 | lss_match_host(sender_host_name, sender_host_address, ...) | |
30638 | ||
30639 | An empty address field matches an empty item in the host list. If the host | |
30640 | name is NULL, the name corresponding to $sender_host_address is | |
30641 | automatically looked up if a host name is required to match an item in the | |
30642 | list. The return values are as for lss_match_domain(), but in addition, | |
30643 | lss_match_host() returns ERROR in the case when it had to look up a host | |
30644 | name, but the lookup failed. | |
30645 | ||
30646 | void log_write(unsigned int selector, int which, char *format, ...) | |
30647 | ||
30648 | This function writes to Exim's log files. The first argument should be zero | |
30649 | (it is concerned with log_selector). The second argument can be "LOG_MAIN" | |
30650 | or "LOG_REJECT" or "LOG_PANIC" or the inclusive "or" of any combination of | |
30651 | them. It specifies to which log or logs the message is written. The | |
30652 | remaining arguments are a format and relevant insertion arguments. The | |
30653 | string should not contain any newlines, not even at the end. | |
30654 | ||
30655 | void receive_add_recipient(uschar *address, int pno) | |
30656 | ||
30657 | This function adds an additional recipient to the message. The first | |
30658 | argument is the recipient address. If it is unqualified (has no domain), it | |
30659 | is qualified with the qualify_recipient domain. The second argument must | |
30660 | always be -1. | |
30661 | ||
30662 | This function does not allow you to specify a private errors_to address (as | |
30663 | described with the structure of recipient_item above), because it pre-dates | |
30664 | the addition of that field to the structure. However, it is easy to add | |
30665 | such a value afterwards. For example: | |
30666 | ||
30667 | receive_add_recipient(US"monitor@mydom.example", -1); | |
30668 | recipients_list[recipients_count-1].errors_to = | |
30669 | US"postmaster@mydom.example"; | |
30670 | ||
30671 | BOOL receive_remove_recipient(uschar *recipient) | |
30672 | ||
30673 | This is a convenience function to remove a named recipient from the list of | |
30674 | recipients. It returns true if a recipient was removed, and false if no | |
30675 | matching recipient could be found. The argument must be a complete email | |
30676 | address. | |
30677 | ||
30678 | uschar rfc2047_decode | |
30679 | (uschar *string, BOOL lencheck, uschar *target, int zeroval, int *lenptr, | |
30680 | uschar **error) | |
30681 | ||
30682 | This function decodes strings that are encoded according to RFC 2047. | |
30683 | Typically these are the contents of header lines. First, each "encoded | |
30684 | word" is decoded from the Q or B encoding into a byte-string. Then, if | |
30685 | provided with the name of a charset encoding, and if the iconv() function | |
30686 | is available, an attempt is made to translate the result to the named | |
30687 | character set. If this fails, the binary string is returned with an error | |
30688 | message. | |
30689 | ||
30690 | The first argument is the string to be decoded. If lencheck is TRUE, the | |
30691 | maximum MIME word length is enforced. The third argument is the target | |
30692 | encoding, or NULL if no translation is wanted. | |
30693 | ||
30694 | If a binary zero is encountered in the decoded string, it is replaced by | |
30695 | the contents of the zeroval argument. For use with Exim headers, the value | |
30696 | must not be 0 because header lines are handled as zero-terminated strings. | |
30697 | ||
30698 | The function returns the result of processing the string, zero-terminated; | |
30699 | if lenptr is not NULL, the length of the result is set in the variable to | |
30700 | which it points. When zeroval is 0, lenptr should not be NULL. | |
30701 | ||
30702 | If an error is encountered, the function returns NULL and uses the error | |
30703 | argument to return an error message. The variable pointed to by error is | |
30704 | set to NULL if there is no error; it may be set non-NULL even when the | |
30705 | function returns a non-NULL value if decoding was successful, but there was | |
30706 | a problem with translation. | |
30707 | ||
30708 | int smtp_fflush(void) | |
30709 | ||
30710 | This function is used in conjunction with smtp_printf(), as described | |
30711 | below. | |
30712 | ||
30713 | void smtp_printf(char *, ...) | |
30714 | ||
30715 | The arguments of this function are like printf(); it writes to the SMTP | |
30716 | output stream. You should use this function only when there is an SMTP | |
30717 | output stream, that is, when the incoming message is being received via | |
30718 | interactive SMTP. This is the case when smtp_input is TRUE and | |
30719 | smtp_batched_input is FALSE. If you want to test for an incoming message | |
30720 | from another host (as opposed to a local process that used the -bs command | |
30721 | line option), you can test the value of sender_host_address, which is | |
30722 | non-NULL when a remote host is involved. | |
30723 | ||
30724 | If an SMTP TLS connection is established, smtp_printf() uses the TLS output | |
30725 | function, so it can be used for all forms of SMTP connection. | |
30726 | ||
30727 | Strings that are written by smtp_printf() from within local_scan() must | |
30728 | start with an appropriate response code: 550 if you are going to return | |
30729 | LOCAL_SCAN_REJECT, 451 if you are going to return LOCAL_SCAN_TEMPREJECT, | |
30730 | and 250 otherwise. Because you are writing the initial lines of a | |
30731 | multi-line response, the code must be followed by a hyphen to indicate that | |
30732 | the line is not the final response line. You must also ensure that the | |
30733 | lines you write terminate with CRLF. For example: | |
30734 | ||
30735 | smtp_printf("550-this is some extra info\r\n"); | |
30736 | return LOCAL_SCAN_REJECT; | |
30737 | ||
30738 | Note that you can also create multi-line responses by including newlines in | |
30739 | the data returned via the return_text argument. The added value of using | |
30740 | smtp_printf() is that, for instance, you could introduce delays between | |
30741 | multiple output lines. | |
30742 | ||
30743 | The smtp_printf() function does not return any error indication, because it | |
30744 | does not automatically flush pending output, and therefore does not test | |
30745 | the state of the stream. (In the main code of Exim, flushing and error | |
30746 | detection is done when Exim is ready for the next SMTP input command.) If | |
30747 | you want to flush the output and check for an error (for example, the | |
30748 | dropping of a TCP/IP connection), you can call smtp_fflush(), which has no | |
30749 | arguments. It flushes the output stream, and returns a non-zero value if | |
30750 | there is an error. | |
30751 | ||
30752 | void *store_get(int) | |
30753 | ||
30754 | This function accesses Exim's internal store (memory) manager. It gets a | |
30755 | new chunk of memory whose size is given by the argument. Exim bombs out if | |
30756 | it ever runs out of memory. See the next section for a discussion of memory | |
30757 | handling. | |
30758 | ||
30759 | void *store_get_perm(int) | |
30760 | ||
30761 | This function is like store_get(), but it always gets memory from the | |
30762 | permanent pool. See the next section for a discussion of memory handling. | |
30763 | ||
30764 | uschar *string_copy(uschar *string) | |
30765 | ||
30766 | See below. | |
30767 | ||
30768 | uschar *string_copyn(uschar *string, int length) | |
30769 | ||
30770 | See below. | |
30771 | ||
30772 | uschar *string_sprintf(char *format, ...) | |
30773 | ||
30774 | These three functions create strings using Exim's dynamic memory | |
30775 | facilities. The first makes a copy of an entire string. The second copies | |
30776 | up to a maximum number of characters, indicated by the second argument. The | |
30777 | third uses a format and insertion arguments to create a new string. In each | |
30778 | case, the result is a pointer to a new string in the current memory pool. | |
30779 | See the next section for more discussion. | |
30780 | ||
30781 | ||
2813c06e | 30782 | 45.8 More about Exim's memory handling |
420a0d19 CE |
30783 | -------------------------------------- |
30784 | ||
30785 | No function is provided for freeing memory, because that is never needed. The | |
30786 | dynamic memory that Exim uses when receiving a message is automatically | |
30787 | recycled if another message is received by the same process (this applies only | |
30788 | to incoming SMTP connections - other input methods can supply only one message | |
30789 | at a time). After receiving the last message, a reception process terminates. | |
30790 | ||
30791 | Because it is recycled, the normal dynamic memory cannot be used for holding | |
30792 | data that must be preserved over a number of incoming messages on the same SMTP | |
30793 | connection. However, Exim in fact uses two pools of dynamic memory; the second | |
30794 | one is not recycled, and can be used for this purpose. | |
30795 | ||
30796 | If you want to allocate memory that remains available for subsequent messages | |
30797 | in the same SMTP connection, you should set | |
30798 | ||
30799 | store_pool = POOL_PERM | |
30800 | ||
30801 | before calling the function that does the allocation. There is no need to | |
30802 | restore the value if you do not need to; however, if you do want to revert to | |
30803 | the normal pool, you can either restore the previous value of store_pool or set | |
30804 | it explicitly to POOL_MAIN. | |
30805 | ||
30806 | The pool setting applies to all functions that get dynamic memory, including | |
30807 | expand_string(), store_get(), and the string_xxx() functions. There is also a | |
30808 | convenience function called store_get_perm() that gets a block of memory from | |
30809 | the permanent pool while preserving the value of store_pool. | |
30810 | ||
30811 | ||
30812 | ||
30813 | =============================================================================== | |
2813c06e | 30814 | 46. SYSTEM-WIDE MESSAGE FILTERING |
420a0d19 CE |
30815 | |
30816 | The previous chapters (on ACLs and the local scan function) describe checks | |
30817 | that can be applied to messages before they are accepted by a host. There is | |
30818 | also a mechanism for checking messages once they have been received, but before | |
30819 | they are delivered. This is called the system filter. | |
30820 | ||
30821 | The system filter operates in a similar manner to users' filter files, but it | |
30822 | is run just once per message (however many recipients the message has). It | |
30823 | should not normally be used as a substitute for routing, because deliver | |
30824 | commands in a system router provide new envelope recipient addresses. The | |
30825 | system filter must be an Exim filter. It cannot be a Sieve filter. | |
30826 | ||
30827 | The system filter is run at the start of a delivery attempt, before any routing | |
30828 | is done. If a message fails to be completely delivered at the first attempt, | |
30829 | the system filter is run again at the start of every retry. If you want your | |
30830 | filter to do something only once per message, you can make use of the | |
30831 | first_delivery condition in an if command in the filter to prevent it happening | |
30832 | on retries. | |
30833 | ||
30834 | Warning: Because the system filter runs just once, variables that are specific | |
30835 | to individual recipient addresses, such as $local_part and $domain, are not | |
30836 | set, and the "personal" condition is not meaningful. If you want to run a | |
30837 | centrally-specified filter for each recipient address independently, you can do | |
2813c06e | 30838 | so by setting up a suitable redirect router, as described in section 46.8 |
420a0d19 CE |
30839 | below. |
30840 | ||
30841 | ||
2813c06e | 30842 | 46.1 Specifying a system filter |
420a0d19 CE |
30843 | ------------------------------- |
30844 | ||
30845 | The name of the file that contains the system filter must be specified by | |
30846 | setting system_filter. If you want the filter to run under a uid and gid other | |
30847 | than root, you must also set system_filter_user and system_filter_group as | |
30848 | appropriate. For example: | |
30849 | ||
30850 | system_filter = /etc/mail/exim.filter | |
30851 | system_filter_user = exim | |
30852 | ||
30853 | If a system filter generates any deliveries directly to files or pipes (via the | |
30854 | save or pipe commands), transports to handle these deliveries must be specified | |
30855 | by setting system_filter_file_transport and system_filter_pipe_transport, | |
30856 | respectively. Similarly, system_filter_reply_transport must be set to handle | |
30857 | any messages generated by the reply command. | |
30858 | ||
30859 | ||
2813c06e | 30860 | 46.2 Testing a system filter |
420a0d19 CE |
30861 | ---------------------------- |
30862 | ||
30863 | You can run simple tests of a system filter in the same way as for a user | |
30864 | filter, but you should use -bF rather than -bf, so that features that are | |
30865 | permitted only in system filters are recognized. | |
30866 | ||
30867 | If you want to test the combined effect of a system filter and a user filter, | |
30868 | you can use both -bF and -bf on the same command line. | |
30869 | ||
30870 | ||
2813c06e | 30871 | 46.3 Contents of a system filter |
420a0d19 CE |
30872 | -------------------------------- |
30873 | ||
30874 | The language used to specify system filters is the same as for users' filter | |
30875 | files. It is described in the separate end-user document Exim's interface to | |
30876 | mail filtering. However, there are some additional features that are available | |
30877 | only in system filters; these are described in subsequent sections. If they are | |
30878 | encountered in a user's filter file or when testing with -bf, they cause | |
30879 | errors. | |
30880 | ||
30881 | There are two special conditions which, though available in users' filter | |
30882 | files, are designed for use in system filters. The condition first_delivery is | |
30883 | true only for the first attempt at delivering a message, and manually_thawed is | |
30884 | true only if the message has been frozen, and subsequently thawed by an admin | |
30885 | user. An explicit forced delivery counts as a manual thaw, but thawing as a | |
30886 | result of the auto_thaw setting does not. | |
30887 | ||
30888 | Warning: If a system filter uses the first_delivery condition to specify an | |
30889 | "unseen" (non-significant) delivery, and that delivery does not succeed, it | |
30890 | will not be tried again. If you want Exim to retry an unseen delivery until it | |
30891 | succeeds, you should arrange to set it up every time the filter runs. | |
30892 | ||
30893 | When a system filter finishes running, the values of the variables $n0 - $n9 | |
30894 | are copied into $sn0 - $sn9 and are thereby made available to users' filter | |
30895 | files. Thus a system filter can, for example, set up "scores" to which users' | |
30896 | filter files can refer. | |
30897 | ||
30898 | ||
2813c06e | 30899 | 46.4 Additional variable for system filters |
420a0d19 CE |
30900 | ------------------------------------------- |
30901 | ||
30902 | The expansion variable $recipients, containing a list of all the recipients of | |
30903 | the message (separated by commas and white space), is available in system | |
30904 | filters. It is not available in users' filters for privacy reasons. | |
30905 | ||
30906 | ||
2813c06e | 30907 | 46.5 Defer, freeze, and fail commands for system filters |
420a0d19 CE |
30908 | -------------------------------------------------------- |
30909 | ||
30910 | There are three extra commands (defer, freeze and fail) which are always | |
30911 | available in system filters, but are not normally enabled in users' filters. | |
30912 | (See the allow_defer, allow_freeze and allow_fail options for the redirect | |
30913 | router.) These commands can optionally be followed by the word text and a | |
30914 | string containing an error message, for example: | |
30915 | ||
30916 | fail text "this message looks like spam to me" | |
30917 | ||
30918 | The keyword text is optional if the next character is a double quote. | |
30919 | ||
30920 | The defer command defers delivery of the original recipients of the message. | |
30921 | The fail command causes all the original recipients to be failed, and a bounce | |
30922 | message to be created. The freeze command suspends all delivery attempts for | |
30923 | the original recipients. In all cases, any new deliveries that are specified by | |
30924 | the filter are attempted as normal after the filter has run. | |
30925 | ||
30926 | The freeze command is ignored if the message has been manually unfrozen and not | |
30927 | manually frozen since. This means that automatic freezing by a system filter | |
30928 | can be used as a way of checking out suspicious messages. If a message is found | |
30929 | to be all right, manually unfreezing it allows it to be delivered. | |
30930 | ||
30931 | The text given with a fail command is used as part of the bounce message as | |
30932 | well as being written to the log. If the message is quite long, this can fill | |
30933 | up a lot of log space when such failures are common. To reduce the size of the | |
30934 | log message, Exim interprets the text in a special way if it starts with the | |
30935 | two characters "<<" and contains ">>" later. The text between these two strings | |
30936 | is written to the log, and the rest of the text is used in the bounce message. | |
30937 | For example: | |
30938 | ||
30939 | fail "<<filter test 1>>Your message is rejected \ | |
30940 | because it contains attachments that we are \ | |
30941 | not prepared to receive." | |
30942 | ||
30943 | Take great care with the fail command when basing the decision to fail on the | |
30944 | contents of the message, because the bounce message will of course include the | |
30945 | contents of the original message and will therefore trigger the fail command | |
30946 | again (causing a mail loop) unless steps are taken to prevent this. Testing the | |
30947 | error_message condition is one way to prevent this. You could use, for example | |
30948 | ||
30949 | if $message_body contains "this is spam" and not error_message | |
30950 | then fail text "spam is not wanted here" endif | |
30951 | ||
30952 | though of course that might let through unwanted bounce messages. The | |
30953 | alternative is clever checking of the body and/or headers to detect bounces | |
30954 | generated by the filter. | |
30955 | ||
30956 | The interpretation of a system filter file ceases after a defer, freeze, or | |
30957 | fail command is obeyed. However, any deliveries that were set up earlier in the | |
30958 | filter file are honoured, so you can use a sequence such as | |
30959 | ||
30960 | mail ... | |
30961 | freeze | |
30962 | ||
30963 | to send a specified message when the system filter is freezing (or deferring or | |
30964 | failing) a message. The normal deliveries for the message do not, of course, | |
30965 | take place. | |
30966 | ||
30967 | ||
2813c06e | 30968 | 46.6 Adding and removing headers in a system filter |
420a0d19 CE |
30969 | --------------------------------------------------- |
30970 | ||
30971 | Two filter commands that are available only in system filters are: | |
30972 | ||
30973 | headers add <string> | |
30974 | headers remove <string> | |
30975 | ||
30976 | The argument for the headers add is a string that is expanded and then added to | |
30977 | the end of the message's headers. It is the responsibility of the filter | |
30978 | maintainer to make sure it conforms to RFC 2822 syntax. Leading white space is | |
30979 | ignored, and if the string is otherwise empty, or if the expansion is forced to | |
30980 | fail, the command has no effect. | |
30981 | ||
30982 | You can use "\n" within the string, followed by white space, to specify | |
30983 | continued header lines. More than one header may be added in one command by | |
30984 | including "\n" within the string without any following white space. For | |
30985 | example: | |
30986 | ||
30987 | headers add "X-header-1: ....\n \ | |
30988 | continuation of X-header-1 ...\n\ | |
30989 | X-header-2: ...." | |
30990 | ||
30991 | Note that the header line continuation white space after the first newline must | |
30992 | be placed before the backslash that continues the input string, because white | |
30993 | space after input continuations is ignored. | |
30994 | ||
30995 | The argument for headers remove is a colon-separated list of header names. This | |
30996 | command applies only to those headers that are stored with the message; those | |
30997 | that are added at delivery time (such as Envelope-To: and Return-Path:) cannot | |
30998 | be removed by this means. If there is more than one header with the same name, | |
30999 | they are all removed. | |
31000 | ||
31001 | The headers command in a system filter makes an immediate change to the set of | |
31002 | header lines that was received with the message (with possible additions from | |
31003 | ACL processing). Subsequent commands in the system filter operate on the | |
31004 | modified set, which also forms the basis for subsequent message delivery. | |
31005 | Unless further modified during routing or transporting, this set of headers is | |
31006 | used for all recipients of the message. | |
31007 | ||
31008 | During routing and transporting, the variables that refer to the contents of | |
31009 | header lines refer only to those lines that are in this set. Thus, header lines | |
31010 | that are added by a system filter are visible to users' filter files and to all | |
31011 | routers and transports. This contrasts with the manipulation of header lines by | |
31012 | routers and transports, which is not immediate, but which instead is saved up | |
2813c06e | 31013 | until the message is actually being written (see section 47.17). |
420a0d19 CE |
31014 | |
31015 | If the message is not delivered at the first attempt, header lines that were | |
31016 | added by the system filter are stored with the message, and so are still | |
31017 | present at the next delivery attempt. Header lines that were removed are still | |
31018 | present, but marked "deleted" so that they are not transported with the | |
31019 | message. For this reason, it is usual to make the headers command conditional | |
31020 | on first_delivery so that the set of header lines is not modified more than | |
31021 | once. | |
31022 | ||
31023 | Because header modification in a system filter acts immediately, you have to | |
31024 | use an indirect approach if you want to modify the contents of a header line. | |
31025 | For example: | |
31026 | ||
31027 | headers add "Old-Subject: $h_subject:" | |
31028 | headers remove "Subject" | |
31029 | headers add "Subject: new subject (was: $h_old-subject:)" | |
31030 | headers remove "Old-Subject" | |
31031 | ||
31032 | ||
2813c06e | 31033 | 46.7 Setting an errors address in a system filter |
420a0d19 CE |
31034 | ------------------------------------------------- |
31035 | ||
31036 | In a system filter, if a deliver command is followed by | |
31037 | ||
31038 | errors_to <some address> | |
31039 | ||
31040 | in order to change the envelope sender (and hence the error reporting) for that | |
31041 | delivery, any address may be specified. (In a user filter, only the current | |
31042 | user's address can be set.) For example, if some mail is being monitored, you | |
31043 | might use | |
31044 | ||
31045 | unseen deliver monitor@spying.example errors_to root@local.example | |
31046 | ||
31047 | to take a copy which would not be sent back to the normal error reporting | |
31048 | address if its delivery failed. | |
31049 | ||
31050 | ||
2813c06e | 31051 | 46.8 Per-address filtering |
420a0d19 CE |
31052 | -------------------------- |
31053 | ||
31054 | In contrast to the system filter, which is run just once per message for each | |
31055 | delivery attempt, it is also possible to set up a system-wide filtering | |
31056 | operation that runs once for each recipient address. In this case, variables | |
31057 | such as $local_part and $domain can be used, and indeed, the choice of filter | |
31058 | file could be made dependent on them. This is an example of a router which | |
31059 | implements such a filter: | |
31060 | ||
31061 | central_filter: | |
31062 | check_local_user | |
31063 | driver = redirect | |
31064 | domains = +local_domains | |
31065 | file = /central/filters/$local_part | |
31066 | no_verify | |
31067 | allow_filter | |
31068 | allow_freeze | |
31069 | ||
31070 | The filter is run in a separate process under its own uid. Therefore, either | |
31071 | check_local_user must be set (as above), in which case the filter is run as the | |
31072 | local user, or the user option must be used to specify which user to use. If | |
31073 | both are set, user overrides. | |
31074 | ||
31075 | Care should be taken to ensure that none of the commands in the filter file | |
31076 | specify a significant delivery if the message is to go on to be delivered to | |
31077 | its intended recipient. The router will not then claim to have dealt with the | |
31078 | address, so it will be passed on to subsequent routers to be delivered in the | |
31079 | normal way. | |
31080 | ||
31081 | ||
31082 | ||
31083 | =============================================================================== | |
2813c06e | 31084 | 47. MESSAGE PROCESSING |
420a0d19 CE |
31085 | |
31086 | Exim performs various transformations on the sender and recipient addresses of | |
31087 | all messages that it handles, and also on the messages' header lines. Some of | |
31088 | these are optional and configurable, while others always take place. All of | |
31089 | this processing, except rewriting as a result of routing, and the addition or | |
31090 | removal of header lines while delivering, happens when a message is received, | |
31091 | before it is placed on Exim's queue. | |
31092 | ||
31093 | Some of the automatic processing takes place by default only for | |
31094 | "locally-originated" messages. This adjective is used to describe messages that | |
31095 | are not received over TCP/IP, but instead are passed to an Exim process on its | |
31096 | standard input. This includes the interactive "local SMTP" case that is set up | |
31097 | by the -bs command line option. | |
31098 | ||
31099 | Note: Messages received over TCP/IP on the loopback interface (127.0.0.1 or | |
31100 | ::1) are not considered to be locally-originated. Exim does not treat the | |
31101 | loopback interface specially in any way. | |
31102 | ||
31103 | If you want the loopback interface to be treated specially, you must ensure | |
31104 | that there are appropriate entries in your ACLs. | |
31105 | ||
31106 | ||
2813c06e | 31107 | 47.1 Submission mode for non-local messages |
420a0d19 CE |
31108 | ------------------------------------------- |
31109 | ||
31110 | Processing that happens automatically for locally-originated messages (unless | |
31111 | suppress_local_fixups is set) can also be requested for messages that are | |
31112 | received over TCP/IP. The term "submission mode" is used to describe this | |
31113 | state. Submission mode is set by the modifier | |
31114 | ||
31115 | control = submission | |
31116 | ||
2813c06e CE |
31117 | in a MAIL, RCPT, or pre-data ACL for an incoming message (see sections 43.21 |
31118 | and 43.22). This makes Exim treat the message as a local submission, and is | |
420a0d19 CE |
31119 | normally used when the source of the message is known to be an MUA running on a |
31120 | client host (as opposed to an MTA). For example, to set submission mode for | |
31121 | messages originating on the IPv4 loopback interface, you could include the | |
31122 | following in the MAIL ACL: | |
31123 | ||
31124 | warn hosts = 127.0.0.1 | |
31125 | control = submission | |
31126 | ||
31127 | There are some options that can be used when setting submission mode. A slash | |
31128 | is used to separate options. For example: | |
31129 | ||
31130 | control = submission/sender_retain | |
31131 | ||
31132 | Specifying sender_retain has the effect of setting local_sender_retain true and | |
31133 | local_from_check false for the current incoming message. The first of these | |
31134 | allows an existing Sender: header in the message to remain, and the second | |
31135 | suppresses the check to ensure that From: matches the authenticated sender. | |
31136 | With this setting, Exim still fixes up messages by adding Date: and Message-ID: | |
31137 | header lines if they are missing, but makes no attempt to check sender | |
31138 | authenticity in header lines. | |
31139 | ||
31140 | When sender_retain is not set, a submission mode setting may specify a domain | |
31141 | to be used when generating a From: or Sender: header line. For example: | |
31142 | ||
31143 | control = submission/domain=some.domain | |
31144 | ||
2813c06e CE |
31145 | The domain may be empty. How this value is used is described in sections 47.11 |
31146 | and 47.16. There is also a name option that allows you to specify the user's | |
420a0d19 CE |
31147 | full name for inclusion in a created Sender: or From: header line. For example: |
31148 | ||
31149 | accept authenticated = * | |
31150 | control = submission/domain=wonderland.example/\ | |
31151 | name=${lookup {$authenticated_id} \ | |
31152 | lsearch {/etc/exim/namelist}} | |
31153 | ||
31154 | Because the name may contain any characters, including slashes, the name option | |
31155 | must be given last. The remainder of the string is used as the name. For the | |
31156 | example above, if /etc/exim/namelist contains: | |
31157 | ||
31158 | bigegg: Humpty Dumpty | |
31159 | ||
31160 | then when the sender has authenticated as bigegg, the generated Sender: line | |
31161 | would be: | |
31162 | ||
31163 | Sender: Humpty Dumpty <bigegg@wonderland.example> | |
31164 | ||
31165 | By default, submission mode forces the return path to the same address as is | |
31166 | used to create the Sender: header. However, if sender_retain is specified, the | |
31167 | return path is also left unchanged. | |
31168 | ||
31169 | Note: The changes caused by submission mode take effect after the predata ACL. | |
31170 | This means that any sender checks performed before the fix-ups use the | |
31171 | untrusted sender address specified by the user, not the trusted sender address | |
31172 | specified by submission mode. Although this might be slightly unexpected, it | |
31173 | does mean that you can configure ACL checks to spot that a user is trying to | |
31174 | spoof another's address. | |
31175 | ||
31176 | ||
2813c06e | 31177 | 47.2 Line endings |
420a0d19 CE |
31178 | ----------------- |
31179 | ||
31180 | RFC 2821 specifies that CRLF (two characters: carriage-return, followed by | |
31181 | linefeed) is the line ending for messages transmitted over the Internet using | |
31182 | SMTP over TCP/IP. However, within individual operating systems, different | |
31183 | conventions are used. For example, Unix-like systems use just LF, but others | |
31184 | use CRLF or just CR. | |
31185 | ||
31186 | Exim was designed for Unix-like systems, and internally, it stores messages | |
31187 | using the system's convention of a single LF as a line terminator. When | |
31188 | receiving a message, all line endings are translated to this standard format. | |
31189 | Originally, it was thought that programs that passed messages directly to an | |
31190 | MTA within an operating system would use that system's convention. Experience | |
31191 | has shown that this is not the case; for example, there are Unix applications | |
31192 | that use CRLF in this circumstance. For this reason, and for compatibility with | |
31193 | other MTAs, the way Exim handles line endings for all messages is now as | |
31194 | follows: | |
31195 | ||
31196 | * LF not preceded by CR is treated as a line ending. | |
31197 | ||
31198 | * CR is treated as a line ending; if it is immediately followed by LF, the LF | |
31199 | is ignored. | |
31200 | ||
31201 | * The sequence "CR, dot, CR" does not terminate an incoming SMTP message, nor | |
31202 | a local message in the state where a line containing only a dot is a | |
31203 | terminator. | |
31204 | ||
31205 | * If a bare CR is encountered within a header line, an extra space is added | |
31206 | after the line terminator so as not to end the header line. The reasoning | |
31207 | behind this is that bare CRs in header lines are most likely either to be | |
31208 | mistakes, or people trying to play silly games. | |
31209 | ||
31210 | * If the first header line received in a message ends with CRLF, a subsequent | |
31211 | bare LF in a header line is treated in the same way as a bare CR in a | |
31212 | header line. | |
31213 | ||
31214 | ||
2813c06e | 31215 | 47.3 Unqualified addresses |
420a0d19 CE |
31216 | -------------------------- |
31217 | ||
31218 | By default, Exim expects every envelope address it receives from an external | |
31219 | host to be fully qualified. Unqualified addresses cause negative responses to | |
31220 | SMTP commands. However, because SMTP is used as a means of transporting | |
31221 | messages from MUAs running on personal workstations, there is sometimes a | |
31222 | requirement to accept unqualified addresses from specific hosts or IP networks. | |
31223 | ||
31224 | Exim has two options that separately control which hosts may send unqualified | |
31225 | sender or recipient addresses in SMTP commands, namely sender_unqualified_hosts | |
31226 | and recipient_unqualified_hosts. In both cases, if an unqualified address is | |
31227 | accepted, it is qualified by adding the value of qualify_domain or | |
31228 | qualify_recipient, as appropriate. | |
31229 | ||
31230 | Unqualified addresses in header lines are automatically qualified for messages | |
31231 | that are locally originated, unless the -bnq option is given on the command | |
31232 | line. For messages received over SMTP, unqualified addresses in header lines | |
31233 | are qualified only if unqualified addresses are permitted in SMTP commands. In | |
31234 | other words, such qualification is also controlled by sender_unqualified_hosts | |
31235 | and recipient_unqualified_hosts, | |
31236 | ||
31237 | ||
2813c06e | 31238 | 47.4 The UUCP From line |
420a0d19 CE |
31239 | ----------------------- |
31240 | ||
31241 | Messages that have come from UUCP (and some other applications) often begin | |
31242 | with a line containing the envelope sender and a timestamp, following the word | |
31243 | "From". Examples of two common formats are: | |
31244 | ||
31245 | From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996 | |
31246 | From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT | |
31247 | ||
31248 | This line precedes the RFC 2822 header lines. For compatibility with Sendmail, | |
31249 | Exim recognizes such lines at the start of messages that are submitted to it | |
31250 | via the command line (that is, on the standard input). It does not recognize | |
31251 | such lines in incoming SMTP messages, unless the sending host matches | |
31252 | ignore_fromline_hosts or the -bs option was used for a local message and | |
31253 | ignore_fromline_local is set. The recognition is controlled by a regular | |
31254 | expression that is defined by the uucp_from_pattern option, whose default value | |
31255 | matches the two common cases shown above and puts the address that follows | |
31256 | "From" into $1. | |
31257 | ||
31258 | When the caller of Exim for a non-SMTP message that contains a "From" line is a | |
31259 | trusted user, the message's sender address is constructed by expanding the | |
31260 | contents of uucp_sender_address, whose default value is "$1". This is then | |
31261 | parsed as an RFC 2822 address. If there is no domain, the local part is | |
31262 | qualified with qualify_domain unless it is the empty string. However, if the | |
31263 | command line -f option is used, it overrides the "From" line. | |
31264 | ||
31265 | If the caller of Exim is not trusted, the "From" line is recognized, but the | |
31266 | sender address is not changed. This is also the case for incoming SMTP messages | |
31267 | that are permitted to contain "From" lines. | |
31268 | ||
31269 | Only one "From" line is recognized. If there is more than one, the second is | |
31270 | treated as a data line that starts the body of the message, as it is not valid | |
31271 | as a header line. This also happens if a "From" line is present in an incoming | |
31272 | SMTP message from a source that is not permitted to send them. | |
31273 | ||
31274 | ||
2813c06e | 31275 | 47.5 Resent- header lines |
420a0d19 CE |
31276 | ------------------------- |
31277 | ||
31278 | RFC 2822 makes provision for sets of header lines starting with the string | |
31279 | "Resent-" to be added to a message when it is resent by the original recipient | |
31280 | to somebody else. These headers are Resent-Date:, Resent-From:, Resent-Sender:, | |
31281 | Resent-To:, Resent-Cc:, Resent-Bcc: and Resent-Message-ID:. The RFC says: | |
31282 | ||
31283 | Resent fields are strictly informational. They MUST NOT be used in the | |
31284 | normal processing of replies or other such automatic actions on messages. | |
31285 | ||
31286 | This leaves things a bit vague as far as other processing actions such as | |
31287 | address rewriting are concerned. Exim treats Resent- header lines as follows: | |
31288 | ||
31289 | * A Resent-From: line that just contains the login id of the submitting user | |
31290 | is automatically rewritten in the same way as From: (see below). | |
31291 | ||
31292 | * If there's a rewriting rule for a particular header line, it is also | |
31293 | applied to Resent- header lines of the same type. For example, a rule that | |
31294 | rewrites From: also rewrites Resent-From:. | |
31295 | ||
31296 | * For local messages, if Sender: is removed on input, Resent-Sender: is also | |
31297 | removed. | |
31298 | ||
31299 | * For a locally-submitted message, if there are any Resent- header lines but | |
31300 | no Resent-Date:, Resent-From:, or Resent-Message-Id:, they are added as | |
31301 | necessary. It is the contents of Resent-Message-Id: (rather than | |
31302 | Message-Id:) which are included in log lines in this case. | |
31303 | ||
31304 | * The logic for adding Sender: is duplicated for Resent-Sender: when any | |
31305 | Resent- header lines are present. | |
31306 | ||
31307 | ||
2813c06e | 31308 | 47.6 The Auto-Submitted: header line |
420a0d19 CE |
31309 | ------------------------------------ |
31310 | ||
31311 | Whenever Exim generates an autoreply, a bounce, or a delay warning message, it | |
31312 | includes the header line: | |
31313 | ||
31314 | Auto-Submitted: auto-replied | |
31315 | ||
31316 | ||
2813c06e | 31317 | 47.7 The Bcc: header line |
420a0d19 CE |
31318 | ------------------------- |
31319 | ||
31320 | If Exim is called with the -t option, to take recipient addresses from a | |
31321 | message's header, it removes any Bcc: header line that may exist (after | |
31322 | extracting its addresses). If -t is not present on the command line, any | |
31323 | existing Bcc: is not removed. | |
31324 | ||
31325 | ||
2813c06e | 31326 | 47.8 The Date: header line |
420a0d19 CE |
31327 | -------------------------- |
31328 | ||
31329 | If a locally-generated or submission-mode message has no Date: header line, | |
31330 | Exim adds one, using the current date and time, unless the | |
31331 | suppress_local_fixups control has been specified. | |
31332 | ||
31333 | ||
2813c06e | 31334 | 47.9 The Delivery-date: header line |
420a0d19 CE |
31335 | ----------------------------------- |
31336 | ||
31337 | Delivery-date: header lines are not part of the standard RFC 2822 header set. | |
31338 | Exim can be configured to add them to the final delivery of messages. (See the | |
31339 | generic delivery_date_add transport option.) They should not be present in | |
31340 | messages in transit. If the delivery_date_remove configuration option is set | |
31341 | (the default), Exim removes Delivery-date: header lines from incoming messages. | |
31342 | ||
31343 | ||
2813c06e | 31344 | 47.10 The Envelope-to: header line |
420a0d19 CE |
31345 | ---------------------------------- |
31346 | ||
31347 | Envelope-to: header lines are not part of the standard RFC 2822 header set. | |
31348 | Exim can be configured to add them to the final delivery of messages. (See the | |
31349 | generic envelope_to_add transport option.) They should not be present in | |
31350 | messages in transit. If the envelope_to_remove configuration option is set (the | |
31351 | default), Exim removes Envelope-to: header lines from incoming messages. | |
31352 | ||
31353 | ||
2813c06e | 31354 | 47.11 The From: header line |
420a0d19 CE |
31355 | --------------------------- |
31356 | ||
31357 | If a submission-mode message does not contain a From: header line, Exim adds | |
31358 | one if either of the following conditions is true: | |
31359 | ||
31360 | * The envelope sender address is not empty (that is, this is not a bounce | |
31361 | message). The added header line copies the envelope sender address. | |
31362 | ||
31363 | * The SMTP session is authenticated and $authenticated_id is not empty. | |
31364 | ||
31365 | 1. If no domain is specified by the submission control, the local part is | |
31366 | $authenticated_id and the domain is $qualify_domain. | |
31367 | ||
31368 | 2. If a non-empty domain is specified by the submission control, the local | |
31369 | part is $authenticated_id, and the domain is the specified domain. | |
31370 | ||
31371 | 3. If an empty domain is specified by the submission control, | |
31372 | $authenticated_id is assumed to be the complete address. | |
31373 | ||
31374 | A non-empty envelope sender takes precedence. | |
31375 | ||
31376 | If a locally-generated incoming message does not contain a From: header line, | |
31377 | and the suppress_local_fixups control is not set, Exim adds one containing the | |
31378 | sender's address. The calling user's login name and full name are used to | |
2813c06e | 31379 | construct the address, as described in section 47.18. They are obtained from |
420a0d19 CE |
31380 | the password data by calling getpwuid() (but see the unknown_login |
31381 | configuration option). The address is qualified with qualify_domain. | |
31382 | ||
31383 | For compatibility with Sendmail, if an incoming, non-SMTP message has a From: | |
31384 | header line containing just the unqualified login name of the calling user, | |
31385 | this is replaced by an address containing the user's login name and full name | |
2813c06e | 31386 | as described in section 47.18. |
420a0d19 CE |
31387 | |
31388 | ||
2813c06e | 31389 | 47.12 The Message-ID: header line |
420a0d19 CE |
31390 | --------------------------------- |
31391 | ||
31392 | If a locally-generated or submission-mode incoming message does not contain a | |
31393 | Message-ID: or Resent-Message-ID: header line, and the suppress_local_fixups | |
31394 | control is not set, Exim adds a suitable header line to the message. If there | |
31395 | are any Resent-: headers in the message, it creates Resent-Message-ID:. The id | |
31396 | is constructed from Exim's internal message id, preceded by the letter E to | |
31397 | ensure it starts with a letter, and followed by @ and the primary host name. | |
31398 | Additional information can be included in this header line by setting the | |
31399 | message_id_header_text and/or message_id_header_domain options. | |
31400 | ||
31401 | ||
2813c06e | 31402 | 47.13 The Received: header line |
420a0d19 CE |
31403 | ------------------------------- |
31404 | ||
31405 | A Received: header line is added at the start of every message. The contents | |
31406 | are defined by the received_header_text configuration option, and Exim | |
31407 | automatically adds a semicolon and a timestamp to the configured string. | |
31408 | ||
31409 | The Received: header is generated as soon as the message's header lines have | |
31410 | been received. At this stage, the timestamp in the Received: header line is the | |
31411 | time that the message started to be received. This is the value that is seen by | |
31412 | the DATA ACL and by the local_scan() function. | |
31413 | ||
31414 | Once a message is accepted, the timestamp in the Received: header line is | |
31415 | changed to the time of acceptance, which is (apart from a small delay while the | |
31416 | -H spool file is written) the earliest time at which delivery could start. | |
31417 | ||
31418 | ||
2813c06e | 31419 | 47.14 The References: header line |
420a0d19 CE |
31420 | --------------------------------- |
31421 | ||
31422 | Messages created by the autoreply transport include a References: header line. | |
31423 | This is constructed according to the rules that are described in section 3.64 | |
31424 | of RFC 2822 (which states that replies should contain such a header line), and | |
31425 | section 3.14 of RFC 3834 (which states that automatic responses are not | |
31426 | different in this respect). However, because some mail processing software does | |
31427 | not cope well with very long header lines, no more than 12 message IDs are | |
31428 | copied from the References: header line in the incoming message. If there are | |
31429 | more than 12, the first one and then the final 11 are copied, before adding the | |
31430 | message ID of the incoming message. | |
31431 | ||
31432 | ||
2813c06e | 31433 | 47.15 The Return-path: header line |
420a0d19 CE |
31434 | ---------------------------------- |
31435 | ||
31436 | Return-path: header lines are defined as something an MTA may insert when it | |
31437 | does the final delivery of messages. (See the generic return_path_add transport | |
31438 | option.) Therefore, they should not be present in messages in transit. If the | |
31439 | return_path_remove configuration option is set (the default), Exim removes | |
31440 | Return-path: header lines from incoming messages. | |
31441 | ||
31442 | ||
2813c06e | 31443 | 47.16 The Sender: header line |
420a0d19 CE |
31444 | ----------------------------- |
31445 | ||
31446 | For a locally-originated message from an untrusted user, Exim may remove an | |
31447 | existing Sender: header line, and it may add a new one. You can modify these | |
31448 | actions by setting the local_sender_retain option true, the local_from_check | |
31449 | option false, or by using the suppress_local_fixups control setting. | |
31450 | ||
31451 | When a local message is received from an untrusted user and local_from_check is | |
31452 | true (the default), and the suppress_local_fixups control has not been set, a | |
31453 | check is made to see if the address given in the From: header line is the | |
31454 | correct (local) sender of the message. The address that is expected has the | |
31455 | login name as the local part and the value of qualify_domain as the domain. | |
31456 | Prefixes and suffixes for the local part can be permitted by setting | |
31457 | local_from_prefix and local_from_suffix appropriately. If From: does not | |
31458 | contain the correct sender, a Sender: line is added to the message. | |
31459 | ||
31460 | If you set local_from_check false, this checking does not occur. However, the | |
31461 | removal of an existing Sender: line still happens, unless you also set | |
31462 | local_sender_retain to be true. It is not possible to set both of these options | |
31463 | true at the same time. | |
31464 | ||
31465 | By default, no processing of Sender: header lines is done for messages received | |
31466 | over TCP/IP or for messages submitted by trusted users. However, when a message | |
31467 | is received over TCP/IP in submission mode, and sender_retain is not specified | |
31468 | on the submission control, the following processing takes place: | |
31469 | ||
31470 | First, any existing Sender: lines are removed. Then, if the SMTP session is | |
31471 | authenticated, and $authenticated_id is not empty, a sender address is created | |
31472 | as follows: | |
31473 | ||
31474 | * If no domain is specified by the submission control, the local part is | |
31475 | $authenticated_id and the domain is $qualify_domain. | |
31476 | ||
31477 | * If a non-empty domain is specified by the submission control, the local | |
31478 | part is $authenticated_id, and the domain is the specified domain. | |
31479 | ||
31480 | * If an empty domain is specified by the submission control, | |
31481 | $authenticated_id is assumed to be the complete address. | |
31482 | ||
31483 | This address is compared with the address in the From: header line. If they are | |
31484 | different, a Sender: header line containing the created address is added. | |
31485 | Prefixes and suffixes for the local part in From: can be permitted by setting | |
31486 | local_from_prefix and local_from_suffix appropriately. | |
31487 | ||
31488 | Note: Whenever a Sender: header line is created, the return path for the | |
31489 | message (the envelope sender address) is changed to be the same address, except | |
31490 | in the case of submission mode when sender_retain is specified. | |
31491 | ||
31492 | ||
2813c06e | 31493 | 47.17 Adding and removing header lines in routers and transports |
420a0d19 CE |
31494 | ---------------------------------------------------------------- |
31495 | ||
31496 | When a message is delivered, the addition and removal of header lines can be | |
31497 | specified in a system filter, or on any of the routers and transports that | |
2813c06e | 31498 | process the message. Section 46.6 contains details about modifying headers in a |
420a0d19 | 31499 | system filter. Header lines can also be added in an ACL as a message is |
2813c06e | 31500 | received (see section 43.24). |
420a0d19 CE |
31501 | |
31502 | In contrast to what happens in a system filter, header modifications that are | |
31503 | specified on routers and transports apply only to the particular recipient | |
31504 | addresses that are being processed by those routers and transports. These | |
31505 | changes do not actually take place until a copy of the message is being | |
31506 | transported. Therefore, they do not affect the basic set of header lines, and | |
31507 | they do not affect the values of the variables that refer to header lines. | |
31508 | ||
31509 | Note: In particular, this means that any expansions in the configuration of the | |
31510 | transport cannot refer to the modified header lines, because such expansions | |
31511 | all occur before the message is actually transported. | |
31512 | ||
31513 | For both routers and transports, the argument of a headers_add option must be | |
31514 | in the form of one or more RFC 2822 header lines, separated by newlines (coded | |
31515 | as "\n"). For example: | |
31516 | ||
31517 | headers_add = X-added-header: added by $primary_hostname\n\ | |
31518 | X-added-second: another added header line | |
31519 | ||
31520 | Exim does not check the syntax of these added header lines. | |
31521 | ||
31522 | Multiple headers_add options for a single router or transport can be specified; | |
31523 | the values will append to a single list of header lines. Each header-line is | |
31524 | separately expanded. | |
31525 | ||
31526 | The argument of a headers_remove option must consist of a colon-separated list | |
31527 | of header names. This is confusing, because header names themselves are often | |
31528 | terminated by colons. In this case, the colons are the list separators, not | |
31529 | part of the names. For example: | |
31530 | ||
31531 | headers_remove = return-receipt-to:acknowledge-to | |
31532 | ||
31533 | Multiple headers_remove options for a single router or transport can be | |
31534 | specified; the arguments will append to a single header-names list. Each item | |
2813c06e CE |
31535 | is separately expanded. Note that colons in complex expansions which are used |
31536 | to form all or part of a headers_remove list will act as list separators. | |
420a0d19 CE |
31537 | |
31538 | When headers_add or headers_remove is specified on a router, items are expanded | |
31539 | at routing time, and then associated with all addresses that are accepted by | |
31540 | that router, and also with any new addresses that it generates. If an address | |
31541 | passes through several routers as a result of aliasing or forwarding, the | |
31542 | changes are cumulative. | |
31543 | ||
31544 | However, this does not apply to multiple routers that result from the use of | |
31545 | the unseen option. Any header modifications that were specified by the "unseen" | |
31546 | router or its predecessors apply only to the "unseen" delivery. | |
31547 | ||
31548 | Addresses that end up with different headers_add or headers_remove settings | |
31549 | cannot be delivered together in a batch, so a transport is always dealing with | |
31550 | a set of addresses that have the same header-processing requirements. | |
31551 | ||
31552 | The transport starts by writing the original set of header lines that arrived | |
31553 | with the message, possibly modified by the system filter. As it writes out | |
31554 | these lines, it consults the list of header names that were attached to the | |
31555 | recipient address(es) by headers_remove options in routers, and it also | |
31556 | consults the transport's own headers_remove option. Header lines whose names | |
31557 | are on either of these lists are not written out. If there are multiple | |
31558 | instances of any listed header, they are all skipped. | |
31559 | ||
31560 | After the remaining original header lines have been written, new header lines | |
31561 | that were specified by routers' headers_add options are written, in the order | |
31562 | in which they were attached to the address. These are followed by any header | |
31563 | lines specified by the transport's headers_add option. | |
31564 | ||
31565 | This way of handling header line modifications in routers and transports has | |
31566 | the following consequences: | |
31567 | ||
31568 | * The original set of header lines, possibly modified by the system filter, | |
31569 | remains "visible", in the sense that the $header_xxx variables refer to it, | |
31570 | at all times. | |
31571 | ||
31572 | * Header lines that are added by a router's headers_add option are not | |
31573 | accessible by means of the $header_xxx expansion syntax in subsequent | |
31574 | routers or the transport. | |
31575 | ||
31576 | * Conversely, header lines that are specified for removal by headers_remove | |
31577 | in a router remain visible to subsequent routers and the transport. | |
31578 | ||
31579 | * Headers added to an address by headers_add in a router cannot be removed by | |
31580 | a later router or by a transport. | |
31581 | ||
31582 | * An added header can refer to the contents of an original header that is to | |
31583 | be removed, even it has the same name as the added header. For example: | |
31584 | ||
31585 | headers_remove = subject | |
31586 | headers_add = Subject: new subject (was: $h_subject:) | |
31587 | ||
31588 | Warning: The headers_add and headers_remove options cannot be used for a | |
31589 | redirect router that has the one_time option set. | |
31590 | ||
31591 | ||
2813c06e | 31592 | 47.18 Constructed addresses |
420a0d19 CE |
31593 | --------------------------- |
31594 | ||
31595 | When Exim constructs a sender address for a locally-generated message, it uses | |
31596 | the form | |
31597 | ||
31598 | <user name> <login@qualify_domain> | |
31599 | ||
31600 | For example: | |
31601 | ||
31602 | Zaphod Beeblebrox <zaphod@end.univ.example> | |
31603 | ||
31604 | The user name is obtained from the -F command line option if set, or otherwise | |
31605 | by looking up the calling user by getpwuid() and extracting the "gecos" field | |
31606 | from the password entry. If the "gecos" field contains an ampersand character, | |
31607 | this is replaced by the login name with the first letter upper cased, as is | |
31608 | conventional in a number of operating systems. See the gecos_name option for a | |
31609 | way to tailor the handling of the "gecos" field. The unknown_username option | |
31610 | can be used to specify user names in cases when there is no password file | |
31611 | entry. | |
31612 | ||
31613 | In all cases, the user name is made to conform to RFC 2822 by quoting all or | |
31614 | parts of it if necessary. In addition, if it contains any non-printing | |
31615 | characters, it is encoded as described in RFC 2047, which defines a way of | |
31616 | including non-ASCII characters in header lines. The value of the | |
31617 | headers_charset option specifies the name of the encoding that is used (the | |
31618 | characters are assumed to be in this encoding). The setting of | |
31619 | print_topbitchars controls whether characters with the top bit set (that is, | |
31620 | with codes greater than 127) count as printing characters or not. | |
31621 | ||
31622 | ||
2813c06e | 31623 | 47.19 Case of local parts |
420a0d19 CE |
31624 | ------------------------- |
31625 | ||
31626 | RFC 2822 states that the case of letters in the local parts of addresses cannot | |
31627 | be assumed to be non-significant. Exim preserves the case of local parts of | |
31628 | addresses, but by default it uses a lower-cased form when it is routing, | |
31629 | because on most Unix systems, usernames are in lower case and case-insensitive | |
31630 | routing is required. However, any particular router can be made to use the | |
31631 | original case for local parts by setting the caseful_local_part generic router | |
31632 | option. | |
31633 | ||
31634 | If you must have mixed-case user names on your system, the best way to proceed, | |
31635 | assuming you want case-independent handling of incoming email, is to set up | |
31636 | your first router to convert incoming local parts in your domains to the | |
31637 | correct case by means of a file lookup. For example: | |
31638 | ||
31639 | correct_case: | |
31640 | driver = redirect | |
31641 | domains = +local_domains | |
31642 | data = ${lookup{$local_part}cdb\ | |
31643 | {/etc/usercased.cdb}{$value}fail}\ | |
31644 | @$domain | |
31645 | ||
31646 | For this router, the local part is forced to lower case by the default action ( | |
31647 | caseful_local_part is not set). The lower-cased local part is used to look up a | |
31648 | new local part in the correct case. If you then set caseful_local_part on any | |
31649 | subsequent routers which process your domains, they will operate on local parts | |
31650 | with the correct case in a case-sensitive manner. | |
31651 | ||
31652 | ||
2813c06e | 31653 | 47.20 Dots in local parts |
420a0d19 CE |
31654 | ------------------------- |
31655 | ||
31656 | RFC 2822 forbids empty components in local parts. That is, an unquoted local | |
31657 | part may not begin or end with a dot, nor have two consecutive dots in the | |
31658 | middle. However, it seems that many MTAs do not enforce this, so Exim permits | |
31659 | empty components for compatibility. | |
31660 | ||
31661 | ||
2813c06e | 31662 | 47.21 Rewriting addresses |
420a0d19 CE |
31663 | ------------------------- |
31664 | ||
31665 | Rewriting of sender and recipient addresses, and addresses in headers, can | |
31666 | happen automatically, or as the result of configuration options, as described | |
31667 | in chapter 31. The headers that may be affected by this are Bcc:, Cc:, From:, | |
31668 | Reply-To:, Sender:, and To:. | |
31669 | ||
31670 | Automatic rewriting includes qualification, as mentioned above. The other case | |
31671 | in which it can happen is when an incomplete non-local domain is given. The | |
31672 | routing process may cause this to be expanded into the full domain name. For | |
31673 | example, a header such as | |
31674 | ||
31675 | To: hare@teaparty | |
31676 | ||
31677 | might get rewritten as | |
31678 | ||
31679 | To: hare@teaparty.wonderland.fict.example | |
31680 | ||
31681 | Rewriting as a result of routing is the one kind of message processing that | |
31682 | does not happen at input time, as it cannot be done until the address has been | |
31683 | routed. | |
31684 | ||
31685 | Strictly, one should not do any deliveries of a message until all its addresses | |
31686 | have been routed, in case any of the headers get changed as a result of | |
31687 | routing. However, doing this in practice would hold up many deliveries for | |
31688 | unreasonable amounts of time, just because one address could not immediately be | |
31689 | routed. Exim therefore does not delay other deliveries when routing of one or | |
31690 | more addresses is deferred. | |
31691 | ||
31692 | ||
31693 | ||
31694 | =============================================================================== | |
2813c06e | 31695 | 48. SMTP PROCESSING |
420a0d19 CE |
31696 | |
31697 | Exim supports a number of different ways of using the SMTP protocol, and its | |
31698 | LMTP variant, which is an interactive protocol for transferring messages into a | |
31699 | closed mail store application. This chapter contains details of how SMTP is | |
31700 | processed. For incoming mail, the following are available: | |
31701 | ||
31702 | * SMTP over TCP/IP (Exim daemon or inetd); | |
31703 | ||
31704 | * SMTP over the standard input and output (the -bs option); | |
31705 | ||
31706 | * Batched SMTP on the standard input (the -bS option). | |
31707 | ||
31708 | For mail delivery, the following are available: | |
31709 | ||
31710 | * SMTP over TCP/IP (the smtp transport); | |
31711 | ||
31712 | * LMTP over TCP/IP (the smtp transport with the protocol option set to | |
31713 | "lmtp"); | |
31714 | ||
31715 | * LMTP over a pipe to a process running in the local host (the lmtp | |
31716 | transport); | |
31717 | ||
31718 | * Batched SMTP to a file or pipe (the appendfile and pipe transports with the | |
31719 | use_bsmtp option set). | |
31720 | ||
31721 | Batched SMTP is the name for a process in which batches of messages are stored | |
31722 | in or read from files (or pipes), in a format in which SMTP commands are used | |
31723 | to contain the envelope information. | |
31724 | ||
31725 | ||
2813c06e | 31726 | 48.1 Outgoing SMTP and LMTP over TCP/IP |
420a0d19 CE |
31727 | --------------------------------------- |
31728 | ||
31729 | Outgoing SMTP and LMTP over TCP/IP is implemented by the smtp transport. The | |
31730 | protocol option selects which protocol is to be used, but the actual processing | |
31731 | is the same in both cases. | |
31732 | ||
31733 | If, in response to its EHLO command, Exim is told that the SIZE parameter is | |
31734 | supported, it adds SIZE=<n> to each subsequent MAIL command. The value of <n> | |
31735 | is the message size plus the value of the size_addition option (default 1024) | |
31736 | to allow for additions to the message such as per-transport header lines, or | |
31737 | changes made in a transport filter. If size_addition is set negative, the use | |
31738 | of SIZE is suppressed. | |
31739 | ||
31740 | If the remote server advertises support for PIPELINING, Exim uses the | |
31741 | pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets | |
31742 | required for the transaction. | |
31743 | ||
31744 | If the remote server advertises support for the STARTTLS command, and Exim was | |
31745 | built to support TLS encryption, it tries to start a TLS session unless the | |
2813c06e | 31746 | server matches hosts_avoid_tls. See chapter 42 for more details. Either a match |
420a0d19 CE |
31747 | in that or hosts_verify_avoid_tls apply when the transport is called for |
31748 | verification. | |
31749 | ||
31750 | If the remote server advertises support for the AUTH command, Exim scans the | |
31751 | authenticators configuration for any suitable client settings, as described in | |
31752 | chapter 33. | |
31753 | ||
31754 | Responses from the remote host are supposed to be terminated by CR followed by | |
31755 | LF. However, there are known to be hosts that do not send CR characters, so in | |
31756 | order to be able to interwork with such hosts, Exim treats LF on its own as a | |
31757 | line terminator. | |
31758 | ||
31759 | If a message contains a number of different addresses, all those with the same | |
31760 | characteristics (for example, the same envelope sender) that resolve to the | |
31761 | same set of hosts, in the same order, are sent in a single SMTP transaction, | |
31762 | even if they are for different domains, unless there are more than the setting | |
31763 | of the max_rcpts option in the smtp transport allows, in which case they are | |
31764 | split into groups containing no more than max_rcpts addresses each. If | |
31765 | remote_max_parallel is greater than one, such groups may be sent in parallel | |
31766 | sessions. The order of hosts with identical MX values is not significant when | |
31767 | checking whether addresses can be batched in this way. | |
31768 | ||
31769 | When the smtp transport suffers a temporary failure that is not | |
31770 | message-related, Exim updates its transport-specific database, which contains | |
31771 | records indexed by host name that remember which messages are waiting for each | |
31772 | particular host. It also updates the retry database with new retry times. | |
31773 | ||
31774 | Exim's retry hints are based on host name plus IP address, so if one address of | |
31775 | a multi-homed host is broken, it will soon be skipped most of the time. See the | |
31776 | next section for more detail about error handling. | |
31777 | ||
31778 | When a message is successfully delivered over a TCP/IP SMTP connection, Exim | |
31779 | looks in the hints database for the transport to see if there are any queued | |
31780 | messages waiting for the host to which it is connected. If it finds one, it | |
31781 | creates a new Exim process using the -MC option (which can only be used by a | |
31782 | process running as root or the Exim user) and passes the TCP/IP socket to it so | |
31783 | that it can deliver another message using the same socket. The new process does | |
31784 | only those deliveries that are routed to the connected host, and may in turn | |
31785 | pass the socket on to a third process, and so on. | |
31786 | ||
31787 | The connection_max_messages option of the smtp transport can be used to limit | |
31788 | the number of messages sent down a single TCP/IP connection. | |
31789 | ||
31790 | The second and subsequent messages delivered down an existing connection are | |
31791 | identified in the main log by the addition of an asterisk after the closing | |
31792 | square bracket of the IP address. | |
31793 | ||
31794 | ||
2813c06e | 31795 | 48.2 Errors in outgoing SMTP |
420a0d19 CE |
31796 | ---------------------------- |
31797 | ||
31798 | Three different kinds of error are recognized for outgoing SMTP: host errors, | |
31799 | message errors, and recipient errors. | |
31800 | ||
31801 | Host errors | |
31802 | ||
31803 | A host error is not associated with a particular message or with a | |
31804 | particular recipient of a message. The host errors are: | |
31805 | ||
2813c06e | 31806 | + Connection refused or timed out, |
420a0d19 | 31807 | |
2813c06e | 31808 | + Any error response code on connection, |
420a0d19 | 31809 | |
2813c06e | 31810 | + Any error response code to EHLO or HELO, |
420a0d19 | 31811 | |
2813c06e | 31812 | + Loss of connection at any time, except after ".", |
420a0d19 | 31813 | |
2813c06e | 31814 | + I/O errors at any time, |
420a0d19 | 31815 | |
2813c06e | 31816 | + Timeouts during the session, other than in response to MAIL, RCPT or |
420a0d19 CE |
31817 | the "." at the end of the data. |
31818 | ||
31819 | For a host error, a permanent error response on connection, or in response | |
31820 | to EHLO, causes all addresses routed to the host to be failed. Any other | |
31821 | host error causes all addresses to be deferred, and retry data to be | |
31822 | created for the host. It is not tried again, for any message, until its | |
31823 | retry time arrives. If the current set of addresses are not all delivered | |
31824 | in this run (to some alternative host), the message is added to the list of | |
31825 | those waiting for this host, so if it is still undelivered when a | |
31826 | subsequent successful delivery is made to the host, it will be sent down | |
31827 | the same SMTP connection. | |
31828 | ||
31829 | Message errors | |
31830 | ||
31831 | A message error is associated with a particular message when sent to a | |
31832 | particular host, but not with a particular recipient of the message. The | |
31833 | message errors are: | |
31834 | ||
2813c06e | 31835 | + Any error response code to MAIL, DATA, or the "." that terminates the |
420a0d19 CE |
31836 | data, |
31837 | ||
2813c06e | 31838 | + Timeout after MAIL, |
420a0d19 | 31839 | |
2813c06e | 31840 | + Timeout or loss of connection after the "." that terminates the data. A |
420a0d19 CE |
31841 | timeout after the DATA command itself is treated as a host error, as is |
31842 | loss of connection at any other time. | |
31843 | ||
31844 | For a message error, a permanent error response (5xx) causes all addresses | |
31845 | to be failed, and a delivery error report to be returned to the sender. A | |
31846 | temporary error response (4xx), or one of the timeouts, causes all | |
31847 | addresses to be deferred. Retry data is not created for the host, but | |
31848 | instead, a retry record for the combination of host plus message id is | |
31849 | created. The message is not added to the list of those waiting for this | |
31850 | host. This ensures that the failing message will not be sent to this host | |
31851 | again until the retry time arrives. However, other messages that are routed | |
31852 | to the host are not affected, so if it is some property of the message that | |
31853 | is causing the error, it will not stop the delivery of other mail. | |
31854 | ||
31855 | If the remote host specified support for the SIZE parameter in its response | |
31856 | to EHLO, Exim adds SIZE=nnn to the MAIL command, so an over-large message | |
31857 | will cause a message error because the error arrives as a response to MAIL. | |
31858 | ||
31859 | Recipient errors | |
31860 | ||
31861 | A recipient error is associated with a particular recipient of a message. | |
31862 | The recipient errors are: | |
31863 | ||
2813c06e | 31864 | + Any error response to RCPT, |
420a0d19 | 31865 | |
2813c06e | 31866 | + Timeout after RCPT. |
420a0d19 CE |
31867 | |
31868 | For a recipient error, a permanent error response (5xx) causes the | |
31869 | recipient address to be failed, and a bounce message to be returned to the | |
31870 | sender. A temporary error response (4xx) or a timeout causes the failing | |
31871 | address to be deferred, and routing retry data to be created for it. This | |
31872 | is used to delay processing of the address in subsequent queue runs, until | |
31873 | its routing retry time arrives. This applies to all messages, but because | |
31874 | it operates only in queue runs, one attempt will be made to deliver a new | |
31875 | message to the failing address before the delay starts to operate. This | |
31876 | ensures that, if the failure is really related to the message rather than | |
31877 | the recipient ("message too big for this recipient" is a possible example), | |
31878 | other messages have a chance of getting delivered. If a delivery to the | |
31879 | address does succeed, the retry information gets cleared, so all stuck | |
31880 | messages get tried again, and the retry clock is reset. | |
31881 | ||
31882 | The message is not added to the list of those waiting for this host. Use of | |
31883 | the host for other messages is unaffected, and except in the case of a | |
31884 | timeout, other recipients are processed independently, and may be | |
31885 | successfully delivered in the current SMTP session. After a timeout it is | |
31886 | of course impossible to proceed with the session, so all addresses get | |
31887 | deferred. However, those other than the one that failed do not suffer any | |
31888 | subsequent retry delays. Therefore, if one recipient is causing trouble, | |
31889 | the others have a chance of getting through when a subsequent delivery | |
31890 | attempt occurs before the failing recipient's retry time. | |
31891 | ||
31892 | In all cases, if there are other hosts (or IP addresses) available for the | |
31893 | current set of addresses (for example, from multiple MX records), they are | |
31894 | tried in this run for any undelivered addresses, subject of course to their own | |
31895 | retry data. In other words, recipient error retry data does not take effect | |
31896 | until the next delivery attempt. | |
31897 | ||
31898 | Some hosts have been observed to give temporary error responses to every MAIL | |
31899 | command at certain times ("insufficient space" has been seen). It would be nice | |
31900 | if such circumstances could be recognized, and defer data for the host itself | |
31901 | created, but this is not possible within the current Exim design. What actually | |
31902 | happens is that retry data for every (host, message) combination is created. | |
31903 | ||
31904 | The reason that timeouts after MAIL and RCPT are treated specially is that | |
31905 | these can sometimes arise as a result of the remote host's verification | |
31906 | procedures. Exim makes this assumption, and treats them as if a temporary error | |
31907 | response had been received. A timeout after "." is treated specially because it | |
31908 | is known that some broken implementations fail to recognize the end of the | |
31909 | message if the last character of the last line is a binary zero. Thus, it is | |
31910 | helpful to treat this case as a message error. | |
31911 | ||
31912 | Timeouts at other times are treated as host errors, assuming a problem with the | |
31913 | host, or the connection to it. If a timeout after MAIL, RCPT, or "." is really | |
31914 | a connection problem, the assumption is that at the next try the timeout is | |
31915 | likely to occur at some other point in the dialogue, causing it then to be | |
31916 | treated as a host error. | |
31917 | ||
31918 | There is experimental evidence that some MTAs drop the connection after the | |
31919 | terminating "." if they do not like the contents of the message for some | |
31920 | reason, in contravention of the RFC, which indicates that a 5xx response should | |
31921 | be given. That is why Exim treats this case as a message rather than a host | |
31922 | error, in order not to delay other messages to the same host. | |
31923 | ||
31924 | ||
2813c06e | 31925 | 48.3 Incoming SMTP messages over TCP/IP |
420a0d19 CE |
31926 | --------------------------------------- |
31927 | ||
31928 | Incoming SMTP messages can be accepted in one of two ways: by running a | |
31929 | listening daemon, or by using inetd. In the latter case, the entry in /etc/ | |
31930 | inetd.conf should be like this: | |
31931 | ||
31932 | smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs | |
31933 | ||
31934 | Exim distinguishes between this case and the case of a locally running user | |
31935 | agent using the -bs option by checking whether or not the standard input is a | |
31936 | socket. When it is, either the port must be privileged (less than 1024), or the | |
31937 | caller must be root or the Exim user. If any other user passes a socket with an | |
31938 | unprivileged port number, Exim prints a message on the standard error stream | |
31939 | and exits with an error code. | |
31940 | ||
31941 | By default, Exim does not make a log entry when a remote host connects or | |
31942 | disconnects (either via the daemon or inetd), unless the disconnection is | |
31943 | unexpected. It can be made to write such log entries by setting the | |
31944 | smtp_connection log selector. | |
31945 | ||
31946 | Commands from the remote host are supposed to be terminated by CR followed by | |
31947 | LF. However, there are known to be hosts that do not send CR characters. In | |
31948 | order to be able to interwork with such hosts, Exim treats LF on its own as a | |
31949 | line terminator. Furthermore, because common code is used for receiving | |
31950 | messages from all sources, a CR on its own is also interpreted as a line | |
31951 | terminator. However, the sequence "CR, dot, CR" does not terminate incoming | |
31952 | SMTP data. | |
31953 | ||
31954 | One area that sometimes gives rise to problems concerns the EHLO or HELO | |
31955 | commands. Some clients send syntactically invalid versions of these commands, | |
31956 | which Exim rejects by default. (This is nothing to do with verifying the data | |
31957 | that is sent, so helo_verify_hosts is not relevant.) You can tell Exim not to | |
31958 | apply a syntax check by setting helo_accept_junk_hosts to match the broken | |
31959 | hosts that send invalid commands. | |
31960 | ||
31961 | The amount of disk space available is checked whenever SIZE is received on a | |
31962 | MAIL command, independently of whether message_size_limit or check_spool_space | |
31963 | is configured, unless smtp_check_spool_space is set false. A temporary error is | |
31964 | given if there is not enough space. If check_spool_space is set, the check is | |
31965 | for that amount of space plus the value given with SIZE, that is, it checks | |
31966 | that the addition of the incoming message will not reduce the space below the | |
31967 | threshold. | |
31968 | ||
31969 | When a message is successfully received, Exim includes the local message id in | |
31970 | its response to the final "." that terminates the data. If the remote host logs | |
31971 | this text it can help with tracing what has happened to a message. | |
31972 | ||
31973 | The Exim daemon can limit the number of simultaneous incoming connections it is | |
31974 | prepared to handle (see the smtp_accept_max option). It can also limit the | |
31975 | number of simultaneous incoming connections from a single remote host (see the | |
31976 | smtp_accept_max_per_host option). Additional connection attempts are rejected | |
31977 | using the SMTP temporary error code 421. | |
31978 | ||
31979 | The Exim daemon does not rely on the SIGCHLD signal to detect when a subprocess | |
31980 | has finished, as this can get lost at busy times. Instead, it looks for | |
31981 | completed subprocesses every time it wakes up. Provided there are other things | |
31982 | happening (new incoming calls, starts of queue runs), completed processes will | |
31983 | be noticed and tidied away. On very quiet systems you may sometimes see a | |
31984 | "defunct" Exim process hanging about. This is not a problem; it will be noticed | |
31985 | when the daemon next wakes up. | |
31986 | ||
31987 | When running as a daemon, Exim can reserve some SMTP slots for specific hosts, | |
31988 | and can also be set up to reject SMTP calls from non-reserved hosts at times of | |
31989 | high system load - for details see the smtp_accept_reserve, smtp_load_reserve, | |
31990 | and smtp_reserve_hosts options. The load check applies in both the daemon and | |
31991 | inetd cases. | |
31992 | ||
31993 | Exim normally starts a delivery process for each message received, though this | |
31994 | can be varied by means of the -odq command line option and the queue_only, | |
31995 | queue_only_file, and queue_only_load options. The number of simultaneously | |
31996 | running delivery processes started in this way from SMTP input can be limited | |
31997 | by the smtp_accept_queue and smtp_accept_queue_per_connection options. When | |
31998 | either limit is reached, subsequently received messages are just put on the | |
31999 | input queue without starting a delivery process. | |
32000 | ||
32001 | The controls that involve counts of incoming SMTP calls (smtp_accept_max, | |
32002 | smtp_accept_queue, smtp_accept_reserve) are not available when Exim is started | |
32003 | up from the inetd daemon, because in that case each connection is handled by an | |
32004 | entirely independent Exim process. Control by load average is, however, | |
32005 | available with inetd. | |
32006 | ||
32007 | Exim can be configured to verify addresses in incoming SMTP commands as they | |
2813c06e | 32008 | are received. See chapter 43 for details. It can also be configured to rewrite |
420a0d19 CE |
32009 | addresses at this time - before any syntax checking is done. See section 31.9. |
32010 | ||
32011 | Exim can also be configured to limit the rate at which a client host submits | |
32012 | MAIL and RCPT commands in a single SMTP session. See the smtp_ratelimit_hosts | |
32013 | option. | |
32014 | ||
32015 | ||
2813c06e | 32016 | 48.4 Unrecognized SMTP commands |
420a0d19 CE |
32017 | ------------------------------- |
32018 | ||
32019 | If Exim receives more than smtp_max_unknown_commands unrecognized SMTP commands | |
32020 | during a single SMTP connection, it drops the connection after sending the | |
32021 | error response to the last command. The default value for | |
32022 | smtp_max_unknown_commands is 3. This is a defence against some kinds of abuse | |
32023 | that subvert web servers into making connections to SMTP ports; in these | |
32024 | circumstances, a number of non-SMTP lines are sent first. | |
32025 | ||
32026 | ||
2813c06e | 32027 | 48.5 Syntax and protocol errors in SMTP commands |
420a0d19 CE |
32028 | ------------------------------------------------ |
32029 | ||
32030 | A syntax error is detected if an SMTP command is recognized, but there is | |
32031 | something syntactically wrong with its data, for example, a malformed email | |
32032 | address in a RCPT command. Protocol errors include invalid command sequencing | |
32033 | such as RCPT before MAIL. If Exim receives more than smtp_max_synprot_errors | |
32034 | such commands during a single SMTP connection, it drops the connection after | |
32035 | sending the error response to the last command. The default value for | |
32036 | smtp_max_synprot_errors is 3. This is a defence against broken clients that | |
32037 | loop sending bad commands (yes, it has been seen). | |
32038 | ||
32039 | ||
2813c06e | 32040 | 48.6 Use of non-mail SMTP commands |
420a0d19 CE |
32041 | ---------------------------------- |
32042 | ||
32043 | The "non-mail" SMTP commands are those other than MAIL, RCPT, and DATA. Exim | |
32044 | counts such commands, and drops the connection if there are too many of them in | |
32045 | a single SMTP session. This action catches some denial-of-service attempts and | |
32046 | things like repeated failing AUTHs, or a mad client looping sending EHLO. The | |
32047 | global option smtp_accept_max_nonmail defines what "too many" means. Its | |
32048 | default value is 10. | |
32049 | ||
32050 | When a new message is expected, one occurrence of RSET is not counted. This | |
32051 | allows a client to send one RSET between messages (this is not necessary, but | |
32052 | some clients do it). Exim also allows one uncounted occurrence of HELO or EHLO, | |
32053 | and one occurrence of STARTTLS between messages. After starting up a TLS | |
32054 | session, another EHLO is expected, and so it too is not counted. | |
32055 | ||
32056 | The first occurrence of AUTH in a connection, or immediately following STARTTLS | |
32057 | is also not counted. Otherwise, all commands other than MAIL, RCPT, DATA, and | |
32058 | QUIT are counted. | |
32059 | ||
32060 | You can control which hosts are subject to the limit set by | |
32061 | smtp_accept_max_nonmail by setting smtp_accept_max_nonmail_hosts. The default | |
32062 | value is "*", which makes the limit apply to all hosts. This option means that | |
32063 | you can exclude any specific badly-behaved hosts that you have to live with. | |
32064 | ||
32065 | ||
2813c06e | 32066 | 48.7 The VRFY and EXPN commands |
420a0d19 CE |
32067 | ------------------------------- |
32068 | ||
32069 | When Exim receives a VRFY or EXPN command on a TCP/IP connection, it runs the | |
32070 | ACL specified by acl_smtp_vrfy or acl_smtp_expn (as appropriate) in order to | |
2813c06e | 32071 | decide whether the command should be accepted or not. |
420a0d19 | 32072 | |
2813c06e CE |
32073 | When no ACL is defined for VRFY, or if it rejects without setting an explicit |
32074 | response code, the command is accepted (with a 252 SMTP response code) in order | |
32075 | to support awkward clients that do a VRFY before every RCPT. When VRFY is | |
32076 | accepted, it runs exactly the same code as when Exim is called with the -bv | |
32077 | option, and returns 250/451/550 SMTP response codes. | |
420a0d19 | 32078 | |
2813c06e CE |
32079 | If no ACL for EXPN is defined, the command is rejected. When EXPN is accepted, |
32080 | a single-level expansion of the address is done. EXPN is treated as an "address | |
32081 | test" (similar to the -bt option) rather than a verification (the -bv option). | |
32082 | If an unqualified local part is given as the argument to EXPN, it is qualified | |
32083 | with qualify_domain. Rejections of VRFY and EXPN commands are logged on the | |
32084 | main and reject logs, and VRFY verification failures are logged on the main log | |
32085 | for consistency with RCPT failures. | |
420a0d19 CE |
32086 | |
32087 | ||
2813c06e | 32088 | 48.8 The ETRN command |
420a0d19 CE |
32089 | --------------------- |
32090 | ||
32091 | RFC 1985 describes an SMTP command called ETRN that is designed to overcome the | |
32092 | security problems of the TURN command (which has fallen into disuse). When Exim | |
32093 | receives an ETRN command on a TCP/IP connection, it runs the ACL specified by | |
32094 | acl_smtp_etrn in order to decide whether the command should be accepted or not. | |
32095 | If no ACL is defined, the command is rejected. | |
32096 | ||
32097 | The ETRN command is concerned with "releasing" messages that are awaiting | |
32098 | delivery to certain hosts. As Exim does not organize its message queue by host, | |
32099 | the only form of ETRN that is supported by default is the one where the text | |
32100 | starts with the "#" prefix, in which case the remainder of the text is specific | |
32101 | to the SMTP server. A valid ETRN command causes a run of Exim with the -R | |
32102 | option to happen, with the remainder of the ETRN text as its argument. For | |
32103 | example, | |
32104 | ||
32105 | ETRN #brigadoon | |
32106 | ||
32107 | runs the command | |
32108 | ||
32109 | exim -R brigadoon | |
32110 | ||
32111 | which causes a delivery attempt on all messages with undelivered addresses | |
32112 | containing the text "brigadoon". When smtp_etrn_serialize is set (the default), | |
32113 | Exim prevents the simultaneous execution of more than one queue run for the | |
32114 | same argument string as a result of an ETRN command. This stops a misbehaving | |
32115 | client from starting more than one queue runner at once. | |
32116 | ||
32117 | Exim implements the serialization by means of a hints database in which a | |
32118 | record is written whenever a process is started by ETRN, and deleted when the | |
32119 | process completes. However, Exim does not keep the SMTP session waiting for the | |
32120 | ETRN process to complete. Once ETRN is accepted, the client is sent a "success" | |
32121 | return code. Obviously there is scope for hints records to get left lying | |
32122 | around if there is a system or program crash. To guard against this, Exim | |
32123 | ignores any records that are more than six hours old. | |
32124 | ||
32125 | For more control over what ETRN does, the smtp_etrn_command option can used. | |
32126 | This specifies a command that is run whenever ETRN is received, whatever the | |
32127 | form of its argument. For example: | |
32128 | ||
32129 | smtp_etrn_command = /etc/etrn_command $domain \ | |
32130 | $sender_host_address | |
32131 | ||
32132 | The string is split up into arguments which are independently expanded. The | |
32133 | expansion variable $domain is set to the argument of the ETRN command, and no | |
32134 | syntax checking is done on the contents of this argument. Exim does not wait | |
32135 | for the command to complete, so its status code is not checked. Exim runs under | |
32136 | its own uid and gid when receiving incoming SMTP, so it is not possible for it | |
32137 | to change them before running the command. | |
32138 | ||
32139 | ||
2813c06e | 32140 | 48.9 Incoming local SMTP |
420a0d19 CE |
32141 | ------------------------ |
32142 | ||
32143 | Some user agents use SMTP to pass messages to their local MTA using the | |
32144 | standard input and output, as opposed to passing the envelope on the command | |
32145 | line and writing the message to the standard input. This is supported by the | |
32146 | -bs option. This form of SMTP is handled in the same way as incoming messages | |
32147 | over TCP/IP (including the use of ACLs), except that the envelope sender given | |
32148 | in a MAIL command is ignored unless the caller is trusted. In an ACL you can | |
32149 | detect this form of SMTP input by testing for an empty host identification. It | |
32150 | is common to have this as the first line in the ACL that runs for RCPT | |
32151 | commands: | |
32152 | ||
32153 | accept hosts = : | |
32154 | ||
32155 | This accepts SMTP messages from local processes without doing any other tests. | |
32156 | ||
32157 | ||
2813c06e | 32158 | 48.10 Outgoing batched SMTP |
420a0d19 CE |
32159 | --------------------------- |
32160 | ||
32161 | Both the appendfile and pipe transports can be used for handling batched SMTP. | |
32162 | Each has an option called use_bsmtp which causes messages to be output in BSMTP | |
32163 | format. No SMTP responses are possible for this form of delivery. All it is | |
32164 | doing is using SMTP commands as a way of transmitting the envelope along with | |
32165 | the message. | |
32166 | ||
32167 | The message is written to the file or pipe preceded by the SMTP commands MAIL | |
32168 | and RCPT, and followed by a line containing a single dot. Lines in the message | |
32169 | that start with a dot have an extra dot added. The SMTP command HELO is not | |
32170 | normally used. If it is required, the message_prefix option can be used to | |
32171 | specify it. | |
32172 | ||
32173 | Because appendfile and pipe are both local transports, they accept only one | |
32174 | recipient address at a time by default. However, you can arrange for them to | |
32175 | handle several addresses at once by setting the batch_max option. When this is | |
32176 | done for BSMTP, messages may contain multiple RCPT commands. See chapter 25 for | |
32177 | more details. | |
32178 | ||
32179 | When one or more addresses are routed to a BSMTP transport by a router that | |
32180 | sets up a host list, the name of the first host on the list is available to the | |
32181 | transport in the variable $host. Here is an example of such a transport and | |
32182 | router: | |
32183 | ||
32184 | begin routers | |
32185 | route_append: | |
32186 | driver = manualroute | |
32187 | transport = smtp_appendfile | |
32188 | route_list = domain.example batch.host.example | |
32189 | ||
32190 | begin transports | |
32191 | smtp_appendfile: | |
32192 | driver = appendfile | |
32193 | directory = /var/bsmtp/$host | |
32194 | batch_max = 1000 | |
32195 | use_bsmtp | |
32196 | user = exim | |
32197 | ||
32198 | This causes messages addressed to domain.example to be written in BSMTP format | |
32199 | to /var/bsmtp/batch.host.example, with only a single copy of each message | |
32200 | (unless there are more than 1000 recipients). | |
32201 | ||
32202 | ||
2813c06e | 32203 | 48.11 Incoming batched SMTP |
420a0d19 CE |
32204 | --------------------------- |
32205 | ||
32206 | The -bS command line option causes Exim to accept one or more messages by | |
32207 | reading SMTP on the standard input, but to generate no responses. If the caller | |
32208 | is trusted, the senders in the MAIL commands are believed; otherwise the sender | |
32209 | is always the caller of Exim. Unqualified senders and receivers are not | |
32210 | rejected (there seems little point) but instead just get qualified. HELO and | |
32211 | EHLO act as RSET; VRFY, EXPN, ETRN and HELP, act as NOOP; QUIT quits. | |
32212 | ||
32213 | Minimal policy checking is done for BSMTP input. Only the non-SMTP ACL is run | |
32214 | in the same way as for non-SMTP local input. | |
32215 | ||
32216 | If an error is detected while reading a message, including a missing "." at the | |
32217 | end, Exim gives up immediately. It writes details of the error to the standard | |
32218 | output in a stylized way that the calling program should be able to make some | |
32219 | use of automatically, for example: | |
32220 | ||
32221 | 554 Unexpected end of file | |
32222 | Transaction started in line 10 | |
32223 | Error detected in line 14 | |
32224 | ||
32225 | It writes a more verbose version, for human consumption, to the standard error | |
32226 | file, for example: | |
32227 | ||
32228 | An error was detected while processing a file of BSMTP input. | |
32229 | The error message was: | |
32230 | ||
32231 | 501 '>' missing at end of address | |
32232 | ||
32233 | The SMTP transaction started in line 10. | |
32234 | The error was detected in line 12. | |
32235 | The SMTP command at fault was: | |
32236 | ||
32237 | rcpt to:<malformed@in.com.plete | |
32238 | ||
32239 | 1 previous message was successfully processed. | |
32240 | The rest of the batch was abandoned. | |
32241 | ||
32242 | The return code from Exim is zero only if there were no errors. It is 1 if some | |
32243 | messages were accepted before an error was detected, and 2 if no messages were | |
32244 | accepted. | |
32245 | ||
32246 | ||
32247 | ||
32248 | =============================================================================== | |
2813c06e | 32249 | 49. CUSTOMIZING BOUNCE AND WARNING MESSAGES |
420a0d19 CE |
32250 | |
32251 | When a message fails to be delivered, or remains on the queue for more than a | |
32252 | configured amount of time, Exim sends a message to the original sender, or to | |
32253 | an alternative configured address. The text of these messages is built into the | |
32254 | code of Exim, but it is possible to change it, either by adding a single | |
32255 | string, or by replacing each of the paragraphs by text supplied in a file. | |
32256 | ||
32257 | The From: and To: header lines are automatically generated; you can cause a | |
32258 | Reply-To: line to be added by setting the errors_reply_to option. Exim also | |
32259 | adds the line | |
32260 | ||
32261 | Auto-Submitted: auto-generated | |
32262 | ||
32263 | to all warning and bounce messages, | |
32264 | ||
32265 | ||
2813c06e | 32266 | 49.1 Customizing bounce messages |
420a0d19 CE |
32267 | -------------------------------- |
32268 | ||
32269 | If bounce_message_text is set, its contents are included in the default message | |
32270 | immediately after "This message was created automatically by mail delivery | |
32271 | software." The string is not expanded. It is not used if bounce_message_file is | |
32272 | set. | |
32273 | ||
32274 | When bounce_message_file is set, it must point to a template file for | |
32275 | constructing error messages. The file consists of a series of text items, | |
32276 | separated by lines consisting of exactly four asterisks. If the file cannot be | |
32277 | opened, default text is used and a message is written to the main and panic | |
32278 | logs. If any text item in the file is empty, default text is used for that | |
32279 | item. | |
32280 | ||
32281 | Each item of text that is read from the file is expanded, and there are two | |
32282 | expansion variables which can be of use here: $bounce_recipient is set to the | |
32283 | recipient of an error message while it is being created, and | |
32284 | $bounce_return_size_limit contains the value of the return_size_limit option, | |
32285 | rounded to a whole number. | |
32286 | ||
32287 | The items must appear in the file in the following order: | |
32288 | ||
32289 | * The first item is included in the headers, and should include at least a | |
32290 | Subject: header. Exim does not check the syntax of these headers. | |
32291 | ||
32292 | * The second item forms the start of the error message. After it, Exim lists | |
32293 | the failing addresses with their error messages. | |
32294 | ||
32295 | * The third item is used to introduce any text from pipe transports that is | |
32296 | to be returned to the sender. It is omitted if there is no such text. | |
32297 | ||
2813c06e CE |
32298 | * The fourth, fifth and sixth items will be ignored and may be empty. The |
32299 | fields exist for back-compatibility | |
420a0d19 CE |
32300 | |
32301 | The default state (bounce_message_file unset) is equivalent to the following | |
32302 | file, in which the sixth item is empty. The Subject: and some other lines have | |
32303 | been split in order to fit them on the page: | |
32304 | ||
32305 | Subject: Mail delivery failed | |
32306 | ${if eq{$sender_address}{$bounce_recipient} | |
32307 | {: returning message to sender}} | |
32308 | **** | |
32309 | This message was created automatically by mail delivery software. | |
32310 | ||
32311 | A message ${if eq{$sender_address}{$bounce_recipient} | |
32312 | {that you sent }{sent by | |
32313 | ||
32314 | <$sender_address> | |
32315 | ||
32316 | }}could not be delivered to all of its recipients. | |
32317 | This is a permanent error. The following address(es) failed: | |
32318 | **** | |
32319 | The following text was generated during the delivery attempt(s): | |
32320 | **** | |
32321 | ------ This is a copy of the message, including all the headers. | |
32322 | ------ | |
32323 | **** | |
32324 | ------ The body of the message is $message_size characters long; | |
32325 | only the first | |
32326 | ------ $bounce_return_size_limit or so are included here. | |
32327 | **** | |
32328 | ||
32329 | ||
2813c06e | 32330 | 49.2 Customizing warning messages |
420a0d19 CE |
32331 | --------------------------------- |
32332 | ||
32333 | The option warn_message_file can be pointed at a template file for use when | |
32334 | warnings about message delays are created. In this case there are only three | |
32335 | text sections: | |
32336 | ||
32337 | * The first item is included in the headers, and should include at least a | |
32338 | Subject: header. Exim does not check the syntax of these headers. | |
32339 | ||
32340 | * The second item forms the start of the warning message. After it, Exim | |
32341 | lists the delayed addresses. | |
32342 | ||
32343 | * The third item then ends the message. | |
32344 | ||
32345 | The default state is equivalent to the following file, except that some lines | |
32346 | have been split here, in order to fit them on the page: | |
32347 | ||
32348 | Subject: Warning: message $message_exim_id delayed | |
32349 | $warn_message_delay | |
32350 | **** | |
32351 | This message was created automatically by mail delivery software. | |
32352 | ||
32353 | A message ${if eq{$sender_address}{$warn_message_recipients} | |
32354 | {that you sent }{sent by | |
32355 | ||
32356 | <$sender_address> | |
32357 | ||
32358 | }}has not been delivered to all of its recipients after | |
32359 | more than $warn_message_delay on the queue on $primary_hostname. | |
32360 | ||
32361 | The message identifier is: $message_exim_id | |
32362 | The subject of the message is: $h_subject | |
32363 | The date of the message is: $h_date | |
32364 | ||
32365 | The following address(es) have not yet been delivered: | |
32366 | **** | |
32367 | No action is required on your part. Delivery attempts will | |
32368 | continue for some time, and this warning may be repeated at | |
32369 | intervals if the message remains undelivered. Eventually the | |
32370 | mail delivery software will give up, and when that happens, | |
32371 | the message will be returned to you. | |
32372 | ||
32373 | However, in the default state the subject and date lines are omitted if no | |
32374 | appropriate headers exist. During the expansion of this file, | |
32375 | $warn_message_delay is set to the delay time in one of the forms "<n> minutes" | |
32376 | or "<n> hours", and $warn_message_recipients contains a list of recipients for | |
32377 | the warning message. There may be more than one if there are multiple addresses | |
32378 | with different errors_to settings on the routers that handled them. | |
32379 | ||
32380 | ||
32381 | ||
32382 | =============================================================================== | |
2813c06e | 32383 | 50. SOME COMMON CONFIGURATION SETTINGS |
420a0d19 CE |
32384 | |
32385 | This chapter discusses some configuration settings that seem to be fairly | |
32386 | common. More examples and discussion can be found in the Exim book. | |
32387 | ||
32388 | ||
2813c06e | 32389 | 50.1 Sending mail to a smart host |
420a0d19 CE |
32390 | --------------------------------- |
32391 | ||
32392 | If you want to send all mail for non-local domains to a "smart host", you | |
32393 | should replace the default dnslookup router with a router which does the | |
32394 | routing explicitly: | |
32395 | ||
32396 | send_to_smart_host: | |
32397 | driver = manualroute | |
32398 | route_list = !+local_domains smart.host.name | |
32399 | transport = remote_smtp | |
32400 | ||
32401 | You can use the smart host's IP address instead of the name if you wish. If you | |
32402 | are using Exim only to submit messages to a smart host, and not for receiving | |
32403 | incoming messages, you can arrange for it to do the submission synchronously by | |
2813c06e | 32404 | setting the mua_wrapper option (see chapter 51). |
420a0d19 CE |
32405 | |
32406 | ||
2813c06e | 32407 | 50.2 Using Exim to handle mailing lists |
420a0d19 CE |
32408 | --------------------------------------- |
32409 | ||
32410 | Exim can be used to run simple mailing lists, but for large and/or complicated | |
32411 | requirements, the use of additional specialized mailing list software such as | |
32412 | Majordomo or Mailman is recommended. | |
32413 | ||
32414 | The redirect router can be used to handle mailing lists where each list is | |
32415 | maintained in a separate file, which can therefore be managed by an independent | |
32416 | manager. The domains router option can be used to run these lists in a separate | |
32417 | domain from normal mail. For example: | |
32418 | ||
32419 | lists: | |
32420 | driver = redirect | |
32421 | domains = lists.example | |
32422 | file = /usr/lists/$local_part | |
32423 | forbid_pipe | |
32424 | forbid_file | |
32425 | errors_to = $local_part-request@lists.example | |
32426 | no_more | |
32427 | ||
32428 | This router is skipped for domains other than lists.example. For addresses in | |
32429 | that domain, it looks for a file that matches the local part. If there is no | |
32430 | such file, the router declines, but because no_more is set, no subsequent | |
32431 | routers are tried, and so the whole delivery fails. | |
32432 | ||
32433 | The forbid_pipe and forbid_file options prevent a local part from being | |
32434 | expanded into a file name or a pipe delivery, which is usually inappropriate in | |
32435 | a mailing list. | |
32436 | ||
32437 | The errors_to option specifies that any delivery errors caused by addresses | |
32438 | taken from a mailing list are to be sent to the given address rather than the | |
32439 | original sender of the message. However, before acting on this, Exim verifies | |
32440 | the error address, and ignores it if verification fails. | |
32441 | ||
32442 | For example, using the configuration above, mail sent to dicts@lists.example is | |
32443 | passed on to those addresses contained in /usr/lists/dicts, with error reports | |
32444 | directed to dicts-request@lists.example, provided that this address can be | |
32445 | verified. There could be a file called /usr/lists/dicts-request containing the | |
32446 | address(es) of this particular list's manager(s), but other approaches, such as | |
32447 | setting up an earlier router (possibly using the local_part_prefix or | |
32448 | local_part_suffix options) to handle addresses of the form owner-xxx or xxx- | |
32449 | request, are also possible. | |
32450 | ||
32451 | ||
2813c06e | 32452 | 50.3 Syntax errors in mailing lists |
420a0d19 CE |
32453 | ----------------------------------- |
32454 | ||
32455 | If an entry in redirection data contains a syntax error, Exim normally defers | |
32456 | delivery of the original address. That means that a syntax error in a mailing | |
32457 | list holds up all deliveries to the list. This may not be appropriate when a | |
32458 | list is being maintained automatically from data supplied by users, and the | |
32459 | addresses are not rigorously checked. | |
32460 | ||
32461 | If the skip_syntax_errors option is set, the redirect router just skips entries | |
32462 | that fail to parse, noting the incident in the log. If in addition | |
32463 | syntax_errors_to is set to a verifiable address, a message is sent to it | |
32464 | whenever a broken address is skipped. It is usually appropriate to set | |
32465 | syntax_errors_to to the same address as errors_to. | |
32466 | ||
32467 | ||
2813c06e | 32468 | 50.4 Re-expansion of mailing lists |
420a0d19 CE |
32469 | ---------------------------------- |
32470 | ||
32471 | Exim remembers every individual address to which a message has been delivered, | |
32472 | in order to avoid duplication, but it normally stores only the original | |
32473 | recipient addresses with a message. If all the deliveries to a mailing list | |
32474 | cannot be done at the first attempt, the mailing list is re-expanded when the | |
32475 | delivery is next tried. This means that alterations to the list are taken into | |
32476 | account at each delivery attempt, so addresses that have been added to the list | |
32477 | since the message arrived will therefore receive a copy of the message, even | |
32478 | though it pre-dates their subscription. | |
32479 | ||
32480 | If this behaviour is felt to be undesirable, the one_time option can be set on | |
32481 | the redirect router. If this is done, any addresses generated by the router | |
32482 | that fail to deliver at the first attempt are added to the message as "top | |
32483 | level" addresses, and the parent address that generated them is marked | |
32484 | "delivered". Thus, expansion of the mailing list does not happen again at the | |
32485 | subsequent delivery attempts. The disadvantage of this is that if any of the | |
32486 | failing addresses are incorrect, correcting them in the file has no effect on | |
32487 | pre-existing messages. | |
32488 | ||
32489 | The original top-level address is remembered with each of the generated | |
32490 | addresses, and is output in any log messages. However, any intermediate parent | |
32491 | addresses are not recorded. This makes a difference to the log only if the | |
32492 | all_parents selector is set, but for mailing lists there is normally only one | |
32493 | level of expansion anyway. | |
32494 | ||
32495 | ||
2813c06e | 32496 | 50.5 Closed mailing lists |
420a0d19 CE |
32497 | ------------------------- |
32498 | ||
32499 | The examples so far have assumed open mailing lists, to which anybody may send | |
32500 | mail. It is also possible to set up closed lists, where mail is accepted from | |
32501 | specified senders only. This is done by making use of the generic senders | |
32502 | option to restrict the router that handles the list. | |
32503 | ||
32504 | The following example uses the same file as a list of recipients and as a list | |
32505 | of permitted senders. It requires three routers: | |
32506 | ||
32507 | lists_request: | |
32508 | driver = redirect | |
32509 | domains = lists.example | |
32510 | local_part_suffix = -request | |
32511 | file = /usr/lists/$local_part$local_part_suffix | |
32512 | no_more | |
32513 | ||
32514 | lists_post: | |
32515 | driver = redirect | |
32516 | domains = lists.example | |
32517 | senders = ${if exists {/usr/lists/$local_part}\ | |
32518 | {lsearch;/usr/lists/$local_part}{*}} | |
32519 | file = /usr/lists/$local_part | |
32520 | forbid_pipe | |
32521 | forbid_file | |
32522 | errors_to = $local_part-request@lists.example | |
32523 | no_more | |
32524 | ||
32525 | lists_closed: | |
32526 | driver = redirect | |
32527 | domains = lists.example | |
32528 | allow_fail | |
32529 | data = :fail: $local_part@lists.example is a closed mailing list | |
32530 | ||
32531 | All three routers have the same domains setting, so for any other domains, they | |
32532 | are all skipped. The first router runs only if the local part ends in -request. | |
32533 | It handles messages to the list manager(s) by means of an open mailing list. | |
32534 | ||
32535 | The second router runs only if the senders precondition is satisfied. It checks | |
32536 | for the existence of a list that corresponds to the local part, and then checks | |
32537 | that the sender is on the list by means of a linear search. It is necessary to | |
32538 | check for the existence of the file before trying to search it, because | |
32539 | otherwise Exim thinks there is a configuration error. If the file does not | |
32540 | exist, the expansion of senders is *, which matches all senders. This means | |
32541 | that the router runs, but because there is no list, declines, and no_more | |
32542 | ensures that no further routers are run. The address fails with an "unrouteable | |
32543 | address" error. | |
32544 | ||
32545 | The third router runs only if the second router is skipped, which happens when | |
32546 | a mailing list exists, but the sender is not on it. This router forcibly fails | |
32547 | the address, giving a suitable error message. | |
32548 | ||
32549 | ||
2813c06e | 32550 | 50.6 Variable Envelope Return Paths (VERP) |
420a0d19 CE |
32551 | ------------------------------------------ |
32552 | ||
32553 | Variable Envelope Return Paths - see http://cr.yp.to/proto/verp.txt - are a way | |
32554 | of helping mailing list administrators discover which subscription address is | |
32555 | the cause of a particular delivery failure. The idea is to encode the original | |
32556 | recipient address in the outgoing envelope sender address, so that if the | |
32557 | message is forwarded by another host and then subsequently bounces, the | |
32558 | original recipient can be extracted from the recipient address of the bounce. | |
32559 | ||
32560 | Envelope sender addresses can be modified by Exim using two different | |
32561 | facilities: the errors_to option on a router (as shown in previous mailing list | |
32562 | examples), or the return_path option on a transport. The second of these is | |
32563 | effective only if the message is successfully delivered to another host; it is | |
32564 | not used for errors detected on the local host (see the description of | |
32565 | return_path in chapter 24). Here is an example of the use of return_path to | |
32566 | implement VERP on an smtp transport: | |
32567 | ||
32568 | verp_smtp: | |
32569 | driver = smtp | |
32570 | max_rcpt = 1 | |
32571 | return_path = \ | |
32572 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ | |
32573 | {$1-request+$local_part=$domain@your.dom.example}fail} | |
32574 | ||
32575 | This has the effect of rewriting the return path (envelope sender) on outgoing | |
32576 | SMTP messages, if the local part of the original return path ends in | |
32577 | "-request", and the domain is your.dom.example. The rewriting inserts the local | |
32578 | part and domain of the recipient into the return path. Suppose, for example, | |
32579 | that a message whose return path has been set to | |
32580 | somelist-request@your.dom.example is sent to subscriber@other.dom.example. In | |
32581 | the transport, the return path is rewritten as | |
32582 | ||
32583 | somelist-request+subscriber=other.dom.example@your.dom.example | |
32584 | ||
32585 | For this to work, you must tell Exim to send multiple copies of messages that | |
32586 | have more than one recipient, so that each copy has just one recipient. This is | |
32587 | achieved by setting max_rcpt to 1. Without this, a single copy of a message | |
32588 | might be sent to several different recipients in the same domain, in which case | |
32589 | $local_part is not available in the transport, because it is not unique. | |
32590 | ||
32591 | Unless your host is doing nothing but mailing list deliveries, you should | |
32592 | probably use a separate transport for the VERP deliveries, so as not to use | |
32593 | extra resources in making one-per-recipient copies for other deliveries. This | |
32594 | can easily be done by expanding the transport option in the router: | |
32595 | ||
32596 | dnslookup: | |
32597 | driver = dnslookup | |
32598 | domains = ! +local_domains | |
32599 | transport = \ | |
32600 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ | |
32601 | {verp_smtp}{remote_smtp}} | |
32602 | no_more | |
32603 | ||
32604 | If you want to change the return path using errors_to in a router instead of | |
32605 | using return_path in the transport, you need to set errors_to on all routers | |
32606 | that handle mailing list addresses. This will ensure that all delivery errors, | |
32607 | including those detected on the local host, are sent to the VERP address. | |
32608 | ||
32609 | On a host that does no local deliveries and has no manual routing, only the | |
32610 | dnslookup router needs to be changed. A special transport is not needed for | |
32611 | SMTP deliveries. Every mailing list recipient has its own return path value, | |
32612 | and so Exim must hand them to the transport one at a time. Here is an example | |
32613 | of a dnslookup router that implements VERP: | |
32614 | ||
32615 | verp_dnslookup: | |
32616 | driver = dnslookup | |
32617 | domains = ! +local_domains | |
32618 | transport = remote_smtp | |
32619 | errors_to = \ | |
32620 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}} | |
32621 | {$1-request+$local_part=$domain@your.dom.example}fail} | |
32622 | no_more | |
32623 | ||
32624 | Before you start sending out messages with VERPed return paths, you must also | |
32625 | configure Exim to accept the bounce messages that come back to those paths. | |
32626 | Typically this is done by setting a local_part_suffix option for a router, and | |
32627 | using this to route the messages to wherever you want to handle them. | |
32628 | ||
32629 | The overhead incurred in using VERP depends very much on the size of the | |
32630 | message, the number of recipient addresses that resolve to the same remote | |
32631 | host, and the speed of the connection over which the message is being sent. If | |
32632 | a lot of addresses resolve to the same host and the connection is slow, sending | |
32633 | a separate copy of the message for each address may take substantially longer | |
32634 | than sending a single copy with many recipients (for which VERP cannot be | |
32635 | used). | |
32636 | ||
32637 | ||
2813c06e | 32638 | 50.7 Virtual domains |
420a0d19 CE |
32639 | -------------------- |
32640 | ||
32641 | The phrase virtual domain is unfortunately used with two rather different | |
32642 | meanings: | |
32643 | ||
32644 | * A domain for which there are no real mailboxes; all valid local parts are | |
32645 | aliases for other email addresses. Common examples are organizational | |
32646 | top-level domains and "vanity" domains. | |
32647 | ||
32648 | * One of a number of independent domains that are all handled by the same | |
32649 | host, with mailboxes on that host, but where the mailbox owners do not | |
32650 | necessarily have login accounts on that host. | |
32651 | ||
32652 | The first usage is probably more common, and does seem more "virtual" than the | |
32653 | second. This kind of domain can be handled in Exim with a straightforward | |
32654 | aliasing router. One approach is to create a separate alias file for each | |
32655 | virtual domain. Exim can test for the existence of the alias file to determine | |
32656 | whether the domain exists. The dsearch lookup type is useful here, leading to a | |
32657 | router of this form: | |
32658 | ||
32659 | virtual: | |
32660 | driver = redirect | |
32661 | domains = dsearch;/etc/mail/virtual | |
32662 | data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}} | |
32663 | no_more | |
32664 | ||
32665 | The domains option specifies that the router is to be skipped, unless there is | |
32666 | a file in the /etc/mail/virtual directory whose name is the same as the domain | |
32667 | that is being processed. When the router runs, it looks up the local part in | |
32668 | the file to find a new address (or list of addresses). The no_more setting | |
32669 | ensures that if the lookup fails (leading to data being an empty string), Exim | |
32670 | gives up on the address without trying any subsequent routers. | |
32671 | ||
32672 | This one router can handle all the virtual domains because the alias file names | |
32673 | follow a fixed pattern. Permissions can be arranged so that appropriate people | |
32674 | can edit the different alias files. A successful aliasing operation results in | |
32675 | a new envelope recipient address, which is then routed from scratch. | |
32676 | ||
32677 | The other kind of "virtual" domain can also be handled in a straightforward | |
32678 | way. One approach is to create a file for each domain containing a list of | |
32679 | valid local parts, and use it in a router like this: | |
32680 | ||
32681 | my_domains: | |
32682 | driver = accept | |
32683 | domains = dsearch;/etc/mail/domains | |
32684 | local_parts = lsearch;/etc/mail/domains/$domain | |
32685 | transport = my_mailboxes | |
32686 | ||
32687 | The address is accepted if there is a file for the domain, and the local part | |
32688 | can be found in the file. The domains option is used to check for the file's | |
32689 | existence because domains is tested before the local_parts option (see section | |
32690 | 3.12). You cannot use require_files, because that option is tested after | |
32691 | local_parts. The transport is as follows: | |
32692 | ||
32693 | my_mailboxes: | |
32694 | driver = appendfile | |
32695 | file = /var/mail/$domain/$local_part | |
32696 | user = mail | |
32697 | ||
32698 | This uses a directory of mailboxes for each domain. The user setting is | |
32699 | required, to specify which uid is to be used for writing to the mailboxes. | |
32700 | ||
32701 | The configuration shown here is just one example of how you might support this | |
32702 | requirement. There are many other ways this kind of configuration can be set | |
32703 | up, for example, by using a database instead of separate files to hold all the | |
32704 | information about the domains. | |
32705 | ||
32706 | ||
2813c06e | 32707 | 50.8 Multiple user mailboxes |
420a0d19 CE |
32708 | ---------------------------- |
32709 | ||
32710 | Heavy email users often want to operate with multiple mailboxes, into which | |
32711 | incoming mail is automatically sorted. A popular way of handling this is to | |
32712 | allow users to use multiple sender addresses, so that replies can easily be | |
32713 | identified. Users are permitted to add prefixes or suffixes to their local | |
32714 | parts for this purpose. The wildcard facility of the generic router options | |
32715 | local_part_prefix and local_part_suffix can be used for this. For example, | |
32716 | consider this router: | |
32717 | ||
32718 | userforward: | |
32719 | driver = redirect | |
32720 | check_local_user | |
32721 | file = $home/.forward | |
32722 | local_part_suffix = -* | |
32723 | local_part_suffix_optional | |
32724 | allow_filter | |
32725 | ||
32726 | It runs a user's .forward file for all local parts of the form username-*. | |
32727 | Within the filter file the user can distinguish different cases by testing the | |
32728 | variable $local_part_suffix. For example: | |
32729 | ||
32730 | if $local_part_suffix contains -special then | |
32731 | save /home/$local_part/Mail/special | |
32732 | endif | |
32733 | ||
32734 | If the filter file does not exist, or does not deal with such addresses, they | |
32735 | fall through to subsequent routers, and, assuming no subsequent use of the | |
32736 | local_part_suffix option is made, they presumably fail. Thus, users have | |
32737 | control over which suffixes are valid. | |
32738 | ||
32739 | Alternatively, a suffix can be used to trigger the use of a different .forward | |
32740 | file - which is the way a similar facility is implemented in another MTA: | |
32741 | ||
32742 | userforward: | |
32743 | driver = redirect | |
32744 | check_local_user | |
32745 | file = $home/.forward$local_part_suffix | |
32746 | local_part_suffix = -* | |
32747 | local_part_suffix_optional | |
32748 | allow_filter | |
32749 | ||
32750 | If there is no suffix, .forward is used; if the suffix is -special, for | |
32751 | example, .forward-special is used. Once again, if the appropriate file does not | |
32752 | exist, or does not deal with the address, it is passed on to subsequent | |
32753 | routers, which could, if required, look for an unqualified .forward file to use | |
32754 | as a default. | |
32755 | ||
32756 | ||
2813c06e | 32757 | 50.9 Simplified vacation processing |
420a0d19 CE |
32758 | ----------------------------------- |
32759 | ||
32760 | The traditional way of running the vacation program is for a user to set up a | |
32761 | pipe command in a .forward file (see section 22.6 for syntax details). This is | |
32762 | prone to error by inexperienced users. There are two features of Exim that can | |
32763 | be used to make this process simpler for users: | |
32764 | ||
32765 | * A local part prefix such as "vacation-" can be specified on a router which | |
32766 | can cause the message to be delivered directly to the vacation program, or | |
32767 | alternatively can use Exim's autoreply transport. The contents of a user's | |
32768 | .forward file are then much simpler. For example: | |
32769 | ||
32770 | spqr, vacation-spqr | |
32771 | ||
32772 | * The require_files generic router option can be used to trigger a vacation | |
32773 | delivery by checking for the existence of a certain file in the user's home | |
32774 | directory. The unseen generic option should also be used, to ensure that | |
32775 | the original delivery also proceeds. In this case, all the user has to do | |
32776 | is to create a file called, say, .vacation, containing a vacation message. | |
32777 | ||
32778 | Another advantage of both these methods is that they both work even when the | |
32779 | use of arbitrary pipes by users is locked out. | |
32780 | ||
32781 | ||
2813c06e | 32782 | 50.10 Taking copies of mail |
420a0d19 CE |
32783 | --------------------------- |
32784 | ||
32785 | Some installations have policies that require archive copies of all messages to | |
32786 | be made. A single copy of each message can easily be taken by an appropriate | |
32787 | command in a system filter, which could, for example, use a different file for | |
32788 | each day's messages. | |
32789 | ||
32790 | There is also a shadow transport mechanism that can be used to take copies of | |
32791 | messages that are successfully delivered by local transports, one copy per | |
32792 | delivery. This could be used, inter alia, to implement automatic notification | |
32793 | of delivery by sites that insist on doing such things. | |
32794 | ||
32795 | ||
2813c06e | 32796 | 50.11 Intermittently connected hosts |
420a0d19 CE |
32797 | ------------------------------------ |
32798 | ||
32799 | It has become quite common (because it is cheaper) for hosts to connect to the | |
32800 | Internet periodically rather than remain connected all the time. The normal | |
32801 | arrangement is that mail for such hosts accumulates on a system that is | |
32802 | permanently connected. | |
32803 | ||
32804 | Exim was designed for use on permanently connected hosts, and so it is not | |
32805 | particularly well-suited to use in an intermittently connected environment. | |
32806 | Nevertheless there are some features that can be used. | |
32807 | ||
32808 | ||
2813c06e | 32809 | 50.12 Exim on the upstream server host |
420a0d19 CE |
32810 | -------------------------------------- |
32811 | ||
32812 | It is tempting to arrange for incoming mail for the intermittently connected | |
32813 | host to remain on Exim's queue until the client connects. However, this | |
32814 | approach does not scale very well. Two different kinds of waiting message are | |
32815 | being mixed up in the same queue - those that cannot be delivered because of | |
32816 | some temporary problem, and those that are waiting for their destination host | |
32817 | to connect. This makes it hard to manage the queue, as well as wasting | |
32818 | resources, because each queue runner scans the entire queue. | |
32819 | ||
32820 | A better approach is to separate off those messages that are waiting for an | |
32821 | intermittently connected host. This can be done by delivering these messages | |
32822 | into local files in batch SMTP, "mailstore", or other envelope-preserving | |
32823 | format, from where they are transmitted by other software when their | |
32824 | destination connects. This makes it easy to collect all the mail for one host | |
32825 | in a single directory, and to apply local timeout rules on a per-message basis | |
32826 | if required. | |
32827 | ||
32828 | On a very small scale, leaving the mail on Exim's queue can be made to work. If | |
32829 | you are doing this, you should configure Exim with a long retry period for the | |
32830 | intermittent host. For example: | |
32831 | ||
32832 | cheshire.wonderland.fict.example * F,5d,24h | |
32833 | ||
32834 | This stops a lot of failed delivery attempts from occurring, but Exim remembers | |
32835 | which messages it has queued up for that host. Once the intermittent host comes | |
32836 | online, forcing delivery of one message (either by using the -M or -R options, | |
2813c06e | 32837 | or by using the ETRN SMTP command (see section 48.8) causes all the queued up |
420a0d19 CE |
32838 | messages to be delivered, often down a single SMTP connection. While the host |
32839 | remains connected, any new messages get delivered immediately. | |
32840 | ||
32841 | If the connecting hosts do not have fixed IP addresses, that is, if a host is | |
32842 | issued with a different IP address each time it connects, Exim's retry | |
32843 | mechanisms on the holding host get confused, because the IP address is normally | |
32844 | used as part of the key string for holding retry information. This can be | |
32845 | avoided by unsetting retry_include_ip_address on the smtp transport. Since this | |
32846 | has disadvantages for permanently connected hosts, it is best to arrange a | |
32847 | separate transport for the intermittently connected ones. | |
32848 | ||
32849 | ||
2813c06e | 32850 | 50.13 Exim on the intermittently connected client host |
420a0d19 CE |
32851 | ------------------------------------------------------ |
32852 | ||
32853 | The value of smtp_accept_queue_per_connection should probably be increased, or | |
32854 | even set to zero (that is, disabled) on the intermittently connected host, so | |
32855 | that all incoming messages down a single connection get delivered immediately. | |
32856 | ||
32857 | Mail waiting to be sent from an intermittently connected host will probably not | |
32858 | have been routed, because without a connection DNS lookups are not possible. | |
32859 | This means that if a normal queue run is done at connection time, each message | |
32860 | is likely to be sent in a separate SMTP session. This can be avoided by | |
32861 | starting the queue run with a command line option beginning with -qq instead of | |
32862 | -q. In this case, the queue is scanned twice. In the first pass, routing is | |
32863 | done but no deliveries take place. The second pass is a normal queue run; since | |
32864 | all the messages have been previously routed, those destined for the same host | |
32865 | are likely to get sent as multiple deliveries in a single SMTP connection. | |
32866 | ||
32867 | ||
32868 | ||
32869 | =============================================================================== | |
2813c06e | 32870 | 51. USING EXIM AS A NON-QUEUEING CLIENT |
420a0d19 CE |
32871 | |
32872 | On a personal computer, it is a common requirement for all email to be sent to | |
32873 | a "smart host". There are plenty of MUAs that can be configured to operate that | |
32874 | way, for all the popular operating systems. However, there are some MUAs for | |
32875 | Unix-like systems that cannot be so configured: they submit messages using the | |
32876 | command line interface of /usr/sbin/sendmail. Furthermore, utility programs | |
32877 | such as cron submit messages this way. | |
32878 | ||
32879 | If the personal computer runs continuously, there is no problem, because it can | |
32880 | run a conventional MTA that handles delivery to the smart host, and deal with | |
32881 | any delays via its queueing mechanism. However, if the computer does not run | |
32882 | continuously or runs different operating systems at different times, queueing | |
32883 | email is not desirable. | |
32884 | ||
32885 | There is therefore a requirement for something that can provide the /usr/sbin/ | |
32886 | sendmail interface but deliver messages to a smart host without any queueing or | |
32887 | retrying facilities. Furthermore, the delivery to the smart host should be | |
32888 | synchronous, so that if it fails, the sending MUA is immediately informed. In | |
32889 | other words, we want something that extends an MUA that submits to a local MTA | |
32890 | via the command line so that it behaves like one that submits to a remote smart | |
32891 | host using TCP/SMTP. | |
32892 | ||
32893 | There are a number of applications (for example, there is one called ssmtp) | |
32894 | that do this job. However, people have found them to be lacking in various | |
32895 | ways. For instance, you might want to allow aliasing and forwarding to be done | |
32896 | before sending a message to the smart host. | |
32897 | ||
32898 | Exim already had the necessary infrastructure for doing this job. Just a few | |
32899 | tweaks were needed to make it behave as required, though it is somewhat of an | |
32900 | overkill to use a fully-featured MTA for this purpose. | |
32901 | ||
32902 | There is a Boolean global option called mua_wrapper, defaulting false. Setting | |
32903 | mua_wrapper true causes Exim to run in a special mode where it assumes that it | |
32904 | is being used to "wrap" a command-line MUA in the manner just described. As | |
32905 | well as setting mua_wrapper, you also need to provide a compatible router and | |
32906 | transport configuration. Typically there will be just one router and one | |
32907 | transport, sending everything to a smart host. | |
32908 | ||
32909 | When run in MUA wrapping mode, the behaviour of Exim changes in the following | |
32910 | ways: | |
32911 | ||
32912 | * A daemon cannot be run, nor will Exim accept incoming messages from inetd. | |
32913 | In other words, the only way to submit messages is via the command line. | |
32914 | ||
32915 | * Each message is synchronously delivered as soon as it is received (-odi is | |
32916 | assumed). All queueing options (queue_only, queue_smtp_domains, control in | |
32917 | an ACL, etc.) are quietly ignored. The Exim reception process does not | |
32918 | finish until the delivery attempt is complete. If the delivery is | |
32919 | successful, a zero return code is given. | |
32920 | ||
32921 | * Address redirection is permitted, but the final routing for all addresses | |
32922 | must be to the same remote transport, and to the same list of hosts. | |
32923 | Furthermore, the return address (envelope sender) must be the same for all | |
32924 | recipients, as must any added or deleted header lines. In other words, it | |
32925 | must be possible to deliver the message in a single SMTP transaction, | |
32926 | however many recipients there are. | |
32927 | ||
32928 | * If these conditions are not met, or if routing any address results in a | |
32929 | failure or defer status, or if Exim is unable to deliver all the recipients | |
32930 | successfully to one of the smart hosts, delivery of the entire message | |
32931 | fails. | |
32932 | ||
32933 | * Because no queueing is allowed, all failures are treated as permanent; | |
32934 | there is no distinction between 4xx and 5xx SMTP response codes from the | |
32935 | smart host. Furthermore, because only a single yes/no response can be given | |
32936 | to the caller, it is not possible to deliver to some recipients and not | |
32937 | others. If there is an error (temporary or permanent) for any recipient, | |
32938 | all are failed. | |
32939 | ||
32940 | * If more than one smart host is listed, Exim will try another host after a | |
32941 | connection failure or a timeout, in the normal way. However, if this kind | |
32942 | of failure happens for all the hosts, the delivery fails. | |
32943 | ||
32944 | * When delivery fails, an error message is written to the standard error | |
32945 | stream (as well as to Exim's log), and Exim exits to the caller with a | |
32946 | return code value 1. The message is expunged from Exim's spool files. No | |
32947 | bounce messages are ever generated. | |
32948 | ||
32949 | * No retry data is maintained, and any retry rules are ignored. | |
32950 | ||
32951 | * A number of Exim options are overridden: deliver_drop_privilege is forced | |
32952 | true, max_rcpt in the smtp transport is forced to "unlimited", | |
32953 | remote_max_parallel is forced to one, and fallback hosts are ignored. | |
32954 | ||
32955 | The overall effect is that Exim makes a single synchronous attempt to deliver | |
32956 | the message, failing if there is any kind of problem. Because no local | |
32957 | deliveries are done and no daemon can be run, Exim does not need root | |
32958 | privilege. It should be possible to run it setuid to exim instead of setuid to | |
2813c06e | 32959 | root. See section 55.3 for a general discussion about the advantages and |
420a0d19 CE |
32960 | disadvantages of running without root privilege. |
32961 | ||
32962 | ||
32963 | ||
32964 | =============================================================================== | |
2813c06e | 32965 | 52. LOG FILES |
420a0d19 CE |
32966 | |
32967 | Exim writes three different logs, referred to as the main log, the reject log, | |
32968 | and the panic log: | |
32969 | ||
32970 | * The main log records the arrival of each message and each delivery in a | |
32971 | single line in each case. The format is as compact as possible, in an | |
32972 | attempt to keep down the size of log files. Two-character flag sequences | |
32973 | make it easy to pick out these lines. A number of other events are recorded | |
32974 | in the main log. Some of them are optional, in which case the log_selector | |
32975 | option controls whether they are included or not. A Perl script called | |
32976 | eximstats, which does simple analysis of main log files, is provided in the | |
2813c06e | 32977 | Exim distribution (see section 53.7). |
420a0d19 CE |
32978 | |
32979 | * The reject log records information from messages that are rejected as a | |
32980 | result of a configuration option (that is, for policy reasons). The first | |
32981 | line of each rejection is a copy of the line that is also written to the | |
32982 | main log. Then, if the message's header has been read at the time the log | |
32983 | is written, its contents are written to this log. Only the original header | |
32984 | lines are available; header lines added by ACLs are not logged. You can use | |
32985 | the reject log to check that your policy controls are working correctly; on | |
32986 | a busy host this may be easier than scanning the main log for rejection | |
32987 | messages. You can suppress the writing of the reject log by setting | |
32988 | write_rejectlog false. | |
32989 | ||
32990 | * When certain serious errors occur, Exim writes entries to its panic log. If | |
32991 | the error is sufficiently disastrous, Exim bombs out afterwards. Panic log | |
32992 | entries are usually written to the main log as well, but can get lost amid | |
32993 | the mass of other entries. The panic log should be empty under normal | |
32994 | circumstances. It is therefore a good idea to check it (or to have a cron | |
32995 | script check it) regularly, in order to become aware of any problems. When | |
32996 | Exim cannot open its panic log, it tries as a last resort to write to the | |
32997 | system log (syslog). This is opened with LOG_PID+LOG_CONS and the facility | |
32998 | code of LOG_MAIL. The message itself is written at priority LOG_CRIT. | |
32999 | ||
33000 | Every log line starts with a timestamp, in the format shown in the following | |
33001 | example. Note that many of the examples shown in this chapter are line-wrapped. | |
33002 | In the log file, this would be all on one line: | |
33003 | ||
33004 | 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed | |
33005 | by QUIT | |
33006 | ||
33007 | By default, the timestamps are in the local timezone. There are two ways of | |
33008 | changing this: | |
33009 | ||
33010 | * You can set the timezone option to a different time zone; in particular, if | |
33011 | you set | |
33012 | ||
33013 | timezone = UTC | |
33014 | ||
33015 | the timestamps will be in UTC (aka GMT). | |
33016 | ||
33017 | * If you set log_timezone true, the time zone is added to the timestamp, for | |
33018 | example: | |
33019 | ||
33020 | 2003-04-25 11:17:07 +0100 Start queue run: pid=12762 | |
33021 | ||
33022 | Exim does not include its process id in log lines by default, but you can | |
2813c06e | 33023 | request that it does so by specifying the "pid" log selector (see section 52.15 |
420a0d19 CE |
33024 | ). When this is set, the process id is output, in square brackets, immediately |
33025 | after the time and date. | |
33026 | ||
33027 | ||
2813c06e | 33028 | 52.1 Where the logs are written |
420a0d19 CE |
33029 | ------------------------------- |
33030 | ||
33031 | The logs may be written to local files, or to syslog, or both. However, it | |
33032 | should be noted that many syslog implementations use UDP as a transport, and | |
33033 | are therefore unreliable in the sense that messages are not guaranteed to | |
33034 | arrive at the loghost, nor is the ordering of messages necessarily maintained. | |
33035 | It has also been reported that on large log files (tens of megabytes) you may | |
33036 | need to tweak syslog to prevent it syncing the file with each write - on Linux | |
33037 | this has been seen to make syslog take 90% plus of CPU time. | |
33038 | ||
33039 | The destination for Exim's logs is configured by setting LOG_FILE_PATH in Local | |
33040 | /Makefile or by setting log_file_path in the run time configuration. This | |
33041 | latter string is expanded, so it can contain, for example, references to the | |
33042 | host name: | |
33043 | ||
33044 | log_file_path = /var/log/$primary_hostname/exim_%slog | |
33045 | ||
33046 | It is generally advisable, however, to set the string in Local/Makefile rather | |
33047 | than at run time, because then the setting is available right from the start of | |
33048 | Exim's execution. Otherwise, if there's something it wants to log before it has | |
33049 | read the configuration file (for example, an error in the configuration file) | |
33050 | it will not use the path you want, and may not be able to log at all. | |
33051 | ||
33052 | The value of LOG_FILE_PATH or log_file_path is a colon-separated list, | |
33053 | currently limited to at most two items. This is one option where the facility | |
33054 | for changing a list separator may not be used. The list must always be | |
33055 | colon-separated. If an item in the list is "syslog" then syslog is used; | |
33056 | otherwise the item must either be an absolute path, containing "%s" at the | |
33057 | point where "main", "reject", or "panic" is to be inserted, or be empty, | |
33058 | implying the use of a default path. | |
33059 | ||
33060 | When Exim encounters an empty item in the list, it searches the list defined by | |
33061 | LOG_FILE_PATH, and uses the first item it finds that is neither empty nor | |
33062 | "syslog". This means that an empty item in log_file_path can be used to mean | |
33063 | "use the path specified at build time". It no such item exists, log files are | |
33064 | written in the log subdirectory of the spool directory. This is equivalent to | |
33065 | the setting: | |
33066 | ||
33067 | log_file_path = $spool_directory/log/%slog | |
33068 | ||
2813c06e CE |
33069 | If you do not specify anything at build time or run time, or if you unset the |
33070 | option at run time (i.e. "log_file_path = "), that is where the logs are | |
33071 | written. | |
420a0d19 CE |
33072 | |
33073 | A log file path may also contain "%D" or "%M" if datestamped log file names are | |
2813c06e | 33074 | in use - see section 52.3 below. |
420a0d19 CE |
33075 | |
33076 | Here are some examples of possible settings: | |
33077 | ||
33078 | LOG_FILE_PATH=syslog syslog only | |
33079 | LOG_FILE_PATH=:syslog syslog and default path | |
33080 | LOG_FILE_PATH=syslog : /usr/log/exim_%s syslog and specified path | |
33081 | LOG_FILE_PATH=/usr/log/exim_%s specified path only | |
33082 | ||
33083 | If there are more than two paths in the list, the first is used and a panic | |
33084 | error is logged. | |
33085 | ||
33086 | ||
2813c06e | 33087 | 52.2 Logging to local files that are periodically "cycled" |
420a0d19 CE |
33088 | ---------------------------------------------------------- |
33089 | ||
33090 | Some operating systems provide centralized and standardized methods for cycling | |
33091 | log files. For those that do not, a utility script called exicyclog is provided | |
2813c06e | 33092 | (see section 53.6). This renames and compresses the main and reject logs each |
420a0d19 CE |
33093 | time it is called. The maximum number of old logs to keep can be set. It is |
33094 | suggested this script is run as a daily cron job. | |
33095 | ||
33096 | An Exim delivery process opens the main log when it first needs to write to it, | |
33097 | and it keeps the file open in case subsequent entries are required - for | |
33098 | example, if a number of different deliveries are being done for the same | |
33099 | message. However, remote SMTP deliveries can take a long time, and this means | |
33100 | that the file may be kept open long after it is renamed if exicyclog or | |
33101 | something similar is being used to rename log files on a regular basis. To | |
33102 | ensure that a switch of log files is noticed as soon as possible, Exim calls | |
33103 | stat() on the main log's name before reusing an open file, and if the file does | |
33104 | not exist, or its inode has changed, the old file is closed and Exim tries to | |
33105 | open the main log from scratch. Thus, an old log file may remain open for quite | |
33106 | some time, but no Exim processes should write to it once it has been renamed. | |
33107 | ||
33108 | ||
2813c06e | 33109 | 52.3 Datestamped log files |
420a0d19 CE |
33110 | -------------------------- |
33111 | ||
33112 | Instead of cycling the main and reject log files by renaming them periodically, | |
33113 | some sites like to use files whose names contain a datestamp, for example, | |
33114 | mainlog-20031225. The datestamp is in the form yyyymmdd or yyyymm. Exim has | |
33115 | support for this way of working. It is enabled by setting the log_file_path | |
33116 | option to a path that includes "%D" or "%M" at the point where the datestamp is | |
33117 | required. For example: | |
33118 | ||
33119 | log_file_path = /var/spool/exim/log/%slog-%D | |
33120 | log_file_path = /var/log/exim-%s-%D.log | |
33121 | log_file_path = /var/spool/exim/log/%D-%slog | |
33122 | log_file_path = /var/log/exim/%s.%M | |
33123 | ||
33124 | As before, "%s" is replaced by "main" or "reject"; the following are examples | |
33125 | of names generated by the above examples: | |
33126 | ||
33127 | /var/spool/exim/log/mainlog-20021225 | |
33128 | /var/log/exim-reject-20021225.log | |
33129 | /var/spool/exim/log/20021225-mainlog | |
33130 | /var/log/exim/main.200212 | |
33131 | ||
33132 | When this form of log file is specified, Exim automatically switches to new | |
33133 | files at midnight. It does not make any attempt to compress old logs; you will | |
33134 | need to write your own script if you require this. You should not run exicyclog | |
33135 | with this form of logging. | |
33136 | ||
33137 | The location of the panic log is also determined by log_file_path, but it is | |
33138 | not datestamped, because rotation of the panic log does not make sense. When | |
33139 | generating the name of the panic log, "%D" or "%M" are removed from the string. | |
33140 | In addition, if it immediately follows a slash, a following non-alphanumeric | |
33141 | character is removed; otherwise a preceding non-alphanumeric character is | |
33142 | removed. Thus, the four examples above would give these panic log names: | |
33143 | ||
33144 | /var/spool/exim/log/paniclog | |
33145 | /var/log/exim-panic.log | |
33146 | /var/spool/exim/log/paniclog | |
33147 | /var/log/exim/panic | |
33148 | ||
33149 | ||
2813c06e | 33150 | 52.4 Logging to syslog |
420a0d19 CE |
33151 | ---------------------- |
33152 | ||
33153 | The use of syslog does not change what Exim logs or the format of its messages, | |
33154 | except in one respect. If syslog_timestamp is set false, the timestamps on | |
33155 | Exim's log lines are omitted when these lines are sent to syslog. Apart from | |
33156 | that, the same strings are written to syslog as to log files. The syslog | |
33157 | "facility" is set to LOG_MAIL, and the program name to "exim" by default, but | |
33158 | you can change these by setting the syslog_facility and syslog_processname | |
33159 | options, respectively. If Exim was compiled with SYSLOG_LOG_PID set in Local/ | |
33160 | Makefile (this is the default in src/EDITME), then, on systems that permit it | |
33161 | (all except ULTRIX), the LOG_PID flag is set so that the syslog() call adds the | |
33162 | pid as well as the time and host name to each line. The three log streams are | |
33163 | mapped onto syslog priorities as follows: | |
33164 | ||
33165 | * mainlog is mapped to LOG_INFO | |
33166 | ||
33167 | * rejectlog is mapped to LOG_NOTICE | |
33168 | ||
33169 | * paniclog is mapped to LOG_ALERT | |
33170 | ||
33171 | Many log lines are written to both mainlog and rejectlog, and some are written | |
33172 | to both mainlog and paniclog, so there will be duplicates if these are routed | |
33173 | by syslog to the same place. You can suppress this duplication by setting | |
33174 | syslog_duplication false. | |
33175 | ||
33176 | Exim's log lines can sometimes be very long, and some of its rejectlog entries | |
33177 | contain multiple lines when headers are included. To cope with both these | |
33178 | cases, entries written to syslog are split into separate syslog() calls at each | |
33179 | internal newline, and also after a maximum of 870 data characters. (This allows | |
33180 | for a total syslog line length of 1024, when additions such as timestamps are | |
33181 | added.) If you are running a syslog replacement that can handle lines longer | |
33182 | than the 1024 characters allowed by RFC 3164, you should set | |
33183 | ||
33184 | SYSLOG_LONG_LINES=yes | |
33185 | ||
33186 | in Local/Makefile before building Exim. That stops Exim from splitting long | |
33187 | lines, but it still splits at internal newlines in reject log entries. | |
33188 | ||
33189 | To make it easy to re-assemble split lines later, each component of a split | |
33190 | entry starts with a string of the form [<n>/<m>] or [<n>\<m>] where <n> is the | |
33191 | component number and <m> is the total number of components in the entry. The / | |
33192 | delimiter is used when the line was split because it was too long; if it was | |
33193 | split because of an internal newline, the \ delimiter is used. For example, | |
33194 | supposing the length limit to be 50 instead of 870, the following would be the | |
33195 | result of a typical rejection message to mainlog (LOG_INFO), each line in | |
33196 | addition being preceded by the time, host name, and pid as added by syslog: | |
33197 | ||
33198 | [1/5] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from | |
33199 | [2/5] [127.0.0.1] (ph10): syntax error in 'From' header | |
33200 | [3/5] when scanning for sender: missing or malformed lo | |
33201 | [4/5] cal part in "<>" (envelope sender is <ph10@cam.exa | |
33202 | [5/5] mple>) | |
33203 | ||
33204 | The same error might cause the following lines to be written to "rejectlog" | |
33205 | (LOG_NOTICE): | |
33206 | ||
33207 | [1/18] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected fro | |
33208 | [2/18] m [127.0.0.1] (ph10): syntax error in 'From' head | |
33209 | [3/18] er when scanning for sender: missing or malformed | |
33210 | [4/18] local part in "<>" (envelope sender is <ph10@cam | |
33211 | [5\18] .example>) | |
33212 | [6\18] Recipients: ph10@some.domain.cam.example | |
33213 | [7\18] P Received: from [127.0.0.1] (ident=ph10) | |
33214 | [8\18] by xxxxx.cam.example with smtp (Exim 4.00) | |
33215 | [9\18] id 16RdAL-0006pc-00 | |
33216 | [10/18] for ph10@cam.example; Mon, 16 Sep 2002 16: | |
33217 | [11\18] 09:43 +0100 | |
33218 | [12\18] F From: <> | |
33219 | [13\18] Subject: this is a test header | |
33220 | [18\18] X-something: this is another header | |
33221 | [15/18] I Message-Id: <E16RdAL-0006pc-00@xxxxx.cam.examp | |
33222 | [16\18] le> | |
33223 | [17\18] B Bcc: | |
33224 | [18/18] Date: Mon, 16 Sep 2002 16:09:43 +0100 | |
33225 | ||
33226 | Log lines that are neither too long nor contain newlines are written to syslog | |
33227 | without modification. | |
33228 | ||
33229 | If only syslog is being used, the Exim monitor is unable to provide a log tail | |
33230 | display, unless syslog is routing mainlog to a file on the local host and the | |
33231 | environment variable EXIMON_LOG_FILE_PATH is set to tell the monitor where it | |
33232 | is. | |
33233 | ||
33234 | ||
2813c06e | 33235 | 52.5 Log line flags |
420a0d19 CE |
33236 | ------------------- |
33237 | ||
33238 | One line is written to the main log for each message received, and for each | |
33239 | successful, unsuccessful, and delayed delivery. These lines can readily be | |
33240 | picked out by the distinctive two-character flags that immediately follow the | |
33241 | timestamp. The flags are: | |
33242 | ||
33243 | <= message arrival | |
2813c06e | 33244 | (= message fakereject |
420a0d19 CE |
33245 | => normal message delivery |
33246 | -> additional address in same delivery | |
33247 | >> cutthrough message delivery | |
33248 | *> delivery suppressed by -N | |
33249 | ** delivery failed; address bounced | |
33250 | == delivery deferred; temporary problem | |
33251 | ||
33252 | ||
2813c06e | 33253 | 52.6 Logging message reception |
420a0d19 CE |
33254 | ------------------------------ |
33255 | ||
33256 | The format of the single-line entry in the main log that is written for every | |
33257 | message received is shown in the basic example below, which is split over | |
33258 | several lines in order to fit it on the page: | |
33259 | ||
33260 | 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@dwarf.fict.example | |
33261 | H=mailer.fict.example [192.168.123.123] U=exim | |
33262 | P=smtp S=5678 id=<incoming message id> | |
33263 | ||
33264 | The address immediately following "<=" is the envelope sender address. A bounce | |
33265 | message is shown with the sender address "<>", and if it is locally generated, | |
33266 | this is followed by an item of the form | |
33267 | ||
33268 | R=<message id> | |
33269 | ||
33270 | which is a reference to the message that caused the bounce to be sent. | |
33271 | ||
33272 | For messages from other hosts, the H and U fields identify the remote host and | |
33273 | record the RFC 1413 identity of the user that sent the message, if one was | |
33274 | received. The number given in square brackets is the IP address of the sending | |
33275 | host. If there is a single, unparenthesized host name in the H field, as above, | |
33276 | it has been verified to correspond to the IP address (see the host_lookup | |
33277 | option). If the name is in parentheses, it was the name quoted by the remote | |
33278 | host in the SMTP HELO or EHLO command, and has not been verified. If | |
33279 | verification yields a different name to that given for HELO or EHLO, the | |
33280 | verified name appears first, followed by the HELO or EHLO name in parentheses. | |
33281 | ||
33282 | Misconfigured hosts (and mail forgers) sometimes put an IP address, with or | |
33283 | without brackets, in the HELO or EHLO command, leading to entries in the log | |
33284 | containing text like these examples: | |
33285 | ||
33286 | H=(10.21.32.43) [192.168.8.34] | |
33287 | H=([10.21.32.43]) [192.168.8.34] | |
33288 | ||
33289 | This can be confusing. Only the final address in square brackets can be relied | |
33290 | on. | |
33291 | ||
33292 | For locally generated messages (that is, messages not received over TCP/IP), | |
33293 | the H field is omitted, and the U field contains the login name of the caller | |
33294 | of Exim. | |
33295 | ||
33296 | For all messages, the P field specifies the protocol used to receive the | |
33297 | message. This is the value that is stored in $received_protocol. In the case of | |
33298 | incoming SMTP messages, the value indicates whether or not any SMTP extensions | |
33299 | (ESMTP), encryption, or authentication were used. If the SMTP session was | |
33300 | encrypted, there is an additional X field that records the cipher suite that | |
33301 | was used. | |
33302 | ||
33303 | The protocol is set to "esmtpsa" or "esmtpa" for messages received from hosts | |
33304 | that have authenticated themselves using the SMTP AUTH command. The first value | |
33305 | is used when the SMTP connection was encrypted ("secure"). In this case there | |
33306 | is an additional item A= followed by the name of the authenticator that was | |
33307 | used. If an authenticated identification was set up by the authenticator's | |
33308 | server_set_id option, this is logged too, separated by a colon from the | |
33309 | authenticator name. | |
33310 | ||
33311 | The id field records the existing message id, if present. The size of the | |
33312 | received message is given by the S field. When the message is delivered, | |
33313 | headers may be removed or added, so that the size of delivered copies of the | |
33314 | message may not correspond with this value (and indeed may be different to each | |
33315 | other). | |
33316 | ||
33317 | The log_selector option can be used to request the logging of additional data | |
2813c06e | 33318 | when a message is received. See section 52.15 below. |
420a0d19 CE |
33319 | |
33320 | ||
2813c06e | 33321 | 52.7 Logging deliveries |
420a0d19 CE |
33322 | ----------------------- |
33323 | ||
33324 | The format of the single-line entry in the main log that is written for every | |
33325 | delivery is shown in one of the examples below, for local and remote | |
2813c06e CE |
33326 | deliveries, respectively. Each example has been split into multiple lines in |
33327 | order to fit it on the page: | |
420a0d19 CE |
33328 | |
33329 | 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv | |
33330 | <marv@hitch.fict.example> R=localuser T=local_delivery | |
33331 | 2002-10-31 09:00:10 16ZCW1-0005MB-00 => | |
33332 | monk@holistic.fict.example R=dnslookup T=remote_smtp | |
33333 | H=holistic.fict.example [192.168.234.234] | |
33334 | ||
33335 | For ordinary local deliveries, the original address is given in angle brackets | |
33336 | after the final delivery address, which might be a pipe or a file. If | |
33337 | intermediate address(es) exist between the original and the final address, the | |
33338 | last of these is given in parentheses after the final address. The R and T | |
33339 | fields record the router and transport that were used to process the address. | |
33340 | ||
33341 | If SMTP AUTH was used for the delivery there is an additional item A= followed | |
33342 | by the name of the authenticator that was used. If an authenticated | |
33343 | identification was set up by the authenticator's client_set_id option, this is | |
33344 | logged too, separated by a colon from the authenticator name. | |
33345 | ||
33346 | If a shadow transport was run after a successful local delivery, the log line | |
33347 | for the successful delivery has an item added on the end, of the form | |
33348 | ||
33349 | ST=<shadow transport name> | |
33350 | ||
33351 | If the shadow transport did not succeed, the error message is put in | |
33352 | parentheses afterwards. | |
33353 | ||
33354 | When more than one address is included in a single delivery (for example, two | |
33355 | SMTP RCPT commands in one transaction) the second and subsequent addresses are | |
33356 | flagged with "->" instead of "=>". When two or more messages are delivered down | |
33357 | a single SMTP connection, an asterisk follows the IP address in the log lines | |
33358 | for the second and subsequent messages. | |
33359 | ||
33360 | When delivery is done in cutthrough mode it is flagged with ">>" and the log | |
33361 | line precedes the reception line, since cutthrough waits for a possible | |
33362 | rejection from the destination in case it can reject the sourced item. | |
33363 | ||
33364 | The generation of a reply message by a filter file gets logged as a "delivery" | |
33365 | to the addressee, preceded by ">". | |
33366 | ||
33367 | The log_selector option can be used to request the logging of additional data | |
2813c06e | 33368 | when a message is delivered. See section 52.15 below. |
420a0d19 CE |
33369 | |
33370 | ||
2813c06e | 33371 | 52.8 Discarded deliveries |
420a0d19 CE |
33372 | ------------------------- |
33373 | ||
33374 | When a message is discarded as a result of the command "seen finish" being | |
33375 | obeyed in a filter file which generates no deliveries, a log entry of the form | |
33376 | ||
33377 | 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded | |
33378 | <low.club@bridge.example> R=userforward | |
33379 | ||
33380 | is written, to record why no deliveries are logged. When a message is discarded | |
33381 | because it is aliased to ":blackhole:" the log line is like this: | |
33382 | ||
33383 | 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole: | |
33384 | <hole@nowhere.example> R=blackhole_router | |
33385 | ||
33386 | ||
2813c06e | 33387 | 52.9 Deferred deliveries |
420a0d19 CE |
33388 | ------------------------ |
33389 | ||
33390 | When a delivery is deferred, a line of the following form is logged: | |
33391 | ||
33392 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@endrest.example | |
33393 | R=dnslookup T=smtp defer (146): Connection refused | |
33394 | ||
33395 | In the case of remote deliveries, the error is the one that was given for the | |
33396 | last IP address that was tried. Details of individual SMTP failures are also | |
33397 | written to the log, so the above line would be preceded by something like | |
33398 | ||
33399 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to | |
33400 | mail1.endrest.example [192.168.239.239]: Connection refused | |
33401 | ||
33402 | When a deferred address is skipped because its retry time has not been reached, | |
33403 | a message is written to the log, but this can be suppressed by setting an | |
33404 | appropriate value in log_selector. | |
33405 | ||
33406 | ||
2813c06e | 33407 | 52.10 Delivery failures |
420a0d19 CE |
33408 | ----------------------- |
33409 | ||
33410 | If a delivery fails because an address cannot be routed, a line of the | |
33411 | following form is logged: | |
33412 | ||
33413 | 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example | |
33414 | <jim@trek99.example>: unknown mail domain | |
33415 | ||
33416 | If a delivery fails at transport time, the router and transport are shown, and | |
33417 | the response from the remote host is included, as in this example: | |
33418 | ||
33419 | 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example | |
33420 | R=dnslookup T=remote_smtp: SMTP error from remote mailer | |
33421 | after pipelined RCPT TO:<ace400@pb.example>: host | |
33422 | pbmail3.py.example [192.168.63.111]: 553 5.3.0 | |
33423 | <ace400@pb.example>...Addressee unknown | |
33424 | ||
33425 | The word "pipelined" indicates that the SMTP PIPELINING extension was being | |
33426 | used. See hosts_avoid_esmtp in the smtp transport for a way of disabling | |
33427 | PIPELINING. The log lines for all forms of delivery failure are flagged with | |
33428 | "**". | |
33429 | ||
33430 | ||
2813c06e | 33431 | 52.11 Fake deliveries |
420a0d19 CE |
33432 | --------------------- |
33433 | ||
33434 | If a delivery does not actually take place because the -N option has been used | |
33435 | to suppress it, a normal delivery line is written to the log, except that "=>" | |
33436 | is replaced by "*>". | |
33437 | ||
33438 | ||
2813c06e | 33439 | 52.12 Completion |
420a0d19 CE |
33440 | ---------------- |
33441 | ||
33442 | A line of the form | |
33443 | ||
33444 | 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed | |
33445 | ||
33446 | is written to the main log when a message is about to be removed from the spool | |
33447 | at the end of its processing. | |
33448 | ||
33449 | ||
2813c06e | 33450 | 52.13 Summary of Fields in Log Lines |
420a0d19 CE |
33451 | ------------------------------------ |
33452 | ||
33453 | A summary of the field identifiers that are used in log lines is shown in the | |
33454 | following table: | |
33455 | ||
33456 | A authenticator name (and optional id and sender) | |
33457 | C SMTP confirmation on delivery | |
33458 | command list for "no mail in SMTP session" | |
33459 | CV certificate verification status | |
33460 | D duration of "no mail in SMTP session" | |
33461 | DN distinguished name from peer certificate | |
2813c06e | 33462 | DS DNSSEC secured lookups |
420a0d19 CE |
33463 | DT on => lines: time taken for a delivery |
33464 | F sender address (on delivery lines) | |
33465 | H host name and IP address | |
33466 | I local interface used | |
2813c06e | 33467 | K CHUNKING extension used |
420a0d19 CE |
33468 | id message id for incoming message |
33469 | P on <= lines: protocol used | |
33470 | on => and ** lines: return path | |
2813c06e CE |
33471 | PRDR PRDR extension used |
33472 | PRX on <= and => lines: proxy address | |
33473 | Q alternate queue name | |
420a0d19 CE |
33474 | QT on => lines: time spent on queue so far |
33475 | on "Completed" lines: time spent on queue | |
33476 | R on <= lines: reference for local bounce | |
2813c06e CE |
33477 | on => >> ** and == lines: router name |
33478 | S size of message in bytes | |
420a0d19 CE |
33479 | SNI server name indication from TLS client hello |
33480 | ST shadow transport name | |
33481 | T on <= lines: message subject (topic) | |
33482 | on => ** and == lines: transport name | |
33483 | U local user or RFC 1413 identity | |
33484 | X TLS cipher suite | |
33485 | ||
33486 | ||
2813c06e | 33487 | 52.14 Other log entries |
420a0d19 CE |
33488 | ----------------------- |
33489 | ||
33490 | Various other types of log entry are written from time to time. Most should be | |
33491 | self-explanatory. Among the more common are: | |
33492 | ||
33493 | * retry time not reached An address previously suffered a temporary error | |
33494 | during routing or local delivery, and the time to retry has not yet | |
33495 | arrived. This message is not written to an individual message log file | |
33496 | unless it happens during the first delivery attempt. | |
33497 | ||
33498 | * retry time not reached for any host An address previously suffered | |
33499 | temporary errors during remote delivery, and the retry time has not yet | |
33500 | arrived for any of the hosts to which it is routed. | |
33501 | ||
33502 | * spool file locked An attempt to deliver a message cannot proceed because | |
33503 | some other Exim process is already working on the message. This can be | |
33504 | quite common if queue running processes are started at frequent intervals. | |
33505 | The exiwhat utility script can be used to find out what Exim processes are | |
33506 | doing. | |
33507 | ||
33508 | * error ignored There are several circumstances that give rise to this | |
33509 | message: | |
33510 | ||
33511 | 1. Exim failed to deliver a bounce message whose age was greater than | |
33512 | ignore_bounce_errors_after. The bounce was discarded. | |
33513 | ||
33514 | 2. A filter file set up a delivery using the "noerror" option, and the | |
33515 | delivery failed. The delivery was discarded. | |
33516 | ||
33517 | 3. A delivery set up by a router configured with | |
33518 | ||
33519 | errors_to = <> | |
33520 | ||
33521 | failed. The delivery was discarded. | |
33522 | ||
33523 | ||
2813c06e | 33524 | 52.15 Reducing or increasing what is logged |
420a0d19 CE |
33525 | ------------------------------------------- |
33526 | ||
33527 | By setting the log_selector global option, you can disable some of Exim's | |
33528 | default logging, or you can request additional logging. The value of | |
33529 | log_selector is made up of names preceded by plus or minus characters. For | |
33530 | example: | |
33531 | ||
33532 | log_selector = +arguments -retry_defer | |
33533 | ||
33534 | The list of optional log items is in the following table, with the default | |
33535 | selection marked by asterisks: | |
33536 | ||
33537 | 8bitmime received 8BITMIME status | |
33538 | *acl_warn_skipped skipped warn statement in ACL | |
33539 | address_rewrite address rewriting | |
33540 | all_parents all parents in => lines | |
33541 | arguments command line arguments | |
33542 | *connection_reject connection rejections | |
33543 | *delay_delivery immediate delivery delayed | |
33544 | deliver_time time taken to perform delivery | |
33545 | delivery_size add S=nnn to => lines | |
33546 | *dnslist_defer defers of DNS list (aka RBL) lookups | |
2813c06e | 33547 | dnssec DNSSEC secured lookups |
420a0d19 CE |
33548 | *etrn ETRN commands |
33549 | *host_lookup_failed as it says | |
33550 | ident_timeout timeout for ident connection | |
2813c06e CE |
33551 | incoming_interface local interface on <= and => lines |
33552 | incoming_port remote port on <= lines | |
420a0d19 | 33553 | *lost_incoming_connection as it says (includes timeouts) |
2813c06e | 33554 | outgoing_interface local interface on => lines |
420a0d19 CE |
33555 | outgoing_port add remote port to => lines |
33556 | *queue_run start and end queue runs | |
33557 | queue_time time on queue for one recipient | |
33558 | queue_time_overall time on queue for whole message | |
33559 | pid Exim process id | |
2813c06e | 33560 | proxy proxy address on <= and => lines |
420a0d19 CE |
33561 | received_recipients recipients on <= lines |
33562 | received_sender sender on <= lines | |
33563 | *rejected_header header contents on reject log | |
33564 | *retry_defer "retry time not reached" | |
33565 | return_path_on_delivery put return path on => and ** lines | |
33566 | sender_on_delivery add sender to => lines | |
33567 | *sender_verify_fail sender verification failures | |
33568 | *size_reject rejection because too big | |
33569 | *skip_delivery delivery skipped in a queue run | |
33570 | *smtp_confirmation SMTP confirmation on => lines | |
2813c06e | 33571 | smtp_connection incoming SMTP connections |
420a0d19 CE |
33572 | smtp_incomplete_transaction incomplete SMTP transactions |
33573 | smtp_mailauth AUTH argument to MAIL commands | |
33574 | smtp_no_mail session with no MAIL commands | |
33575 | smtp_protocol_error SMTP protocol errors | |
33576 | smtp_syntax_error SMTP syntax errors | |
33577 | subject contents of Subject: on <= lines | |
2813c06e | 33578 | *tls_certificate_verified certificate verification status |
420a0d19 CE |
33579 | *tls_cipher TLS cipher suite on <= and => lines |
33580 | tls_peerdn TLS peer DN on <= and => lines | |
33581 | tls_sni TLS SNI on <= lines | |
33582 | unknown_in_list DNS lookup failed in list match | |
33583 | ||
33584 | all all of the above | |
33585 | ||
2813c06e CE |
33586 | See also the slow_lookup_log main configuration option, section 14.4 |
33587 | ||
420a0d19 CE |
33588 | More details on each of these items follows: |
33589 | ||
33590 | * 8bitmime: This causes Exim to log any 8BITMIME status of received messages, | |
33591 | which may help in tracking down interoperability issues with ancient MTAs | |
33592 | that are not 8bit clean. This is added to the "<=" line, tagged with "M8S=" | |
33593 | and a value of "0", "7" or "8", corresponding to "not given", "7BIT" and | |
33594 | "8BITMIME" respectively. | |
33595 | ||
33596 | * acl_warn_skipped: When an ACL warn statement is skipped because one of its | |
33597 | conditions cannot be evaluated, a log line to this effect is written if | |
33598 | this log selector is set. | |
33599 | ||
33600 | * address_rewrite: This applies both to global rewrites and per-transport | |
33601 | rewrites, but not to rewrites in filters run as an unprivileged user | |
33602 | (because such users cannot access the log). | |
33603 | ||
33604 | * all_parents: Normally only the original and final addresses are logged on | |
33605 | delivery lines; with this selector, intermediate parents are given in | |
33606 | parentheses between them. | |
33607 | ||
33608 | * arguments: This causes Exim to write the arguments with which it was called | |
33609 | to the main log, preceded by the current working directory. This is a | |
33610 | debugging feature, added to make it easier to find out how certain MUAs | |
33611 | call /usr/sbin/sendmail. The logging does not happen if Exim has given up | |
33612 | root privilege because it was called with the -C or -D options. Arguments | |
33613 | that are empty or that contain white space are quoted. Non-printing | |
33614 | characters are shown as escape sequences. This facility cannot log | |
33615 | unrecognized arguments, because the arguments are checked before the | |
33616 | configuration file is read. The only way to log such cases is to interpose | |
33617 | a script such as util/logargs.sh between the caller and Exim. | |
33618 | ||
33619 | * connection_reject: A log entry is written whenever an incoming SMTP | |
33620 | connection is rejected, for whatever reason. | |
33621 | ||
33622 | * delay_delivery: A log entry is written whenever a delivery process is not | |
33623 | started for an incoming message because the load is too high or too many | |
33624 | messages were received on one connection. Logging does not occur if no | |
33625 | delivery process is started because queue_only is set or -odq was used. | |
33626 | ||
33627 | * deliver_time: For each delivery, the amount of real time it has taken to | |
33628 | perform the actual delivery is logged as DT=<time>, for example, "DT=1s". | |
33629 | ||
33630 | * delivery_size: For each delivery, the size of message delivered is added to | |
33631 | the "=>" line, tagged with S=. | |
33632 | ||
33633 | * dnslist_defer: A log entry is written if an attempt to look up a host in a | |
33634 | DNS black list suffers a temporary error. | |
33635 | ||
2813c06e CE |
33636 | * dnssec: For message acceptance and (attempted) delivery log lines, when dns |
33637 | lookups gave secure results a tag of DS is added. For acceptance this | |
33638 | covers the reverse and forward lookups for host name verification. It does | |
33639 | not cover helo-name verification. For delivery this covers the SRV, MX, A | |
33640 | and/or AAAA lookups. | |
33641 | ||
420a0d19 CE |
33642 | * etrn: Every valid ETRN command that is received is logged, before the ACL |
33643 | is run to determine whether or not it is actually accepted. An invalid ETRN | |
33644 | command, or one received within a message transaction is not logged by this | |
33645 | selector (see smtp_syntax_error and smtp_protocol_error). | |
33646 | ||
33647 | * host_lookup_failed: When a lookup of a host's IP addresses fails to find | |
33648 | any addresses, or when a lookup of an IP address fails to find a host name, | |
33649 | a log line is written. This logging does not apply to direct DNS lookups | |
33650 | when routing email addresses, but it does apply to "byname" lookups. | |
33651 | ||
33652 | * ident_timeout: A log line is written whenever an attempt to connect to a | |
33653 | client's ident port times out. | |
33654 | ||
33655 | * incoming_interface: The interface on which a message was received is added | |
33656 | to the "<=" line as an IP address in square brackets, tagged by I= and | |
33657 | followed by a colon and the port number. The local interface and port are | |
2813c06e CE |
33658 | also added to other SMTP log lines, for example "SMTP connection from", to |
33659 | rejection lines, and (despite the name) to outgoing "=>" and "->" lines. | |
33660 | The latter can be disabled by turning off the outgoing_interface option. | |
33661 | ||
33662 | * proxy: The internal (closest to the system running Exim) IP address of the | |
33663 | proxy, tagged by PRX=, on the "<=" line for a message accepted on a proxied | |
33664 | connection or the "=>" line for a message delivered on a proxied | |
33665 | connection. See 58.1 for more information. | |
420a0d19 CE |
33666 | |
33667 | * incoming_port: The remote port number from which a message was received is | |
33668 | added to log entries and Received: header lines, following the IP address | |
33669 | in square brackets, and separated from it by a colon. This is implemented | |
33670 | by changing the value that is put in the $sender_fullhost and | |
33671 | $sender_rcvhost variables. Recording the remote port number has become more | |
33672 | important with the widening use of NAT (see RFC 2505). | |
33673 | ||
33674 | * lost_incoming_connection: A log line is written when an incoming SMTP | |
33675 | connection is unexpectedly dropped. | |
33676 | ||
2813c06e CE |
33677 | * outgoing_interface: If incoming_interface is turned on, then the interface |
33678 | on which a message was sent is added to delivery lines as an I= tag | |
33679 | followed by IP address in square brackets. You can disable this by turning | |
33680 | off the outgoing_interface option. | |
33681 | ||
420a0d19 | 33682 | * outgoing_port: The remote port number is added to delivery log lines (those |
2813c06e CE |
33683 | containing => tags) following the IP address. The local port is also added |
33684 | if incoming_interface and outgoing_interface are both enabled. This option | |
33685 | is not included in the default setting, because for most ordinary | |
33686 | configurations, the remote port number is always 25 (the SMTP port), and | |
33687 | the local port is a random ephemeral port. | |
420a0d19 CE |
33688 | |
33689 | * pid: The current process id is added to every log line, in square brackets, | |
33690 | immediately after the time and date. | |
33691 | ||
33692 | * queue_run: The start and end of every queue run are logged. | |
33693 | ||
33694 | * queue_time: The amount of time the message has been in the queue on the | |
33695 | local host is logged as QT=<time> on delivery ("=>") lines, for example, | |
33696 | "QT=3m45s". The clock starts when Exim starts to receive the message, so it | |
33697 | includes reception time as well as the delivery time for the current | |
33698 | address. This means that it may be longer than the difference between the | |
33699 | arrival and delivery log line times, because the arrival log line is not | |
33700 | written until the message has been successfully received. | |
33701 | ||
33702 | * queue_time_overall: The amount of time the message has been in the queue on | |
33703 | the local host is logged as QT=<time> on "Completed" lines, for example, | |
33704 | "QT=3m45s". The clock starts when Exim starts to receive the message, so it | |
33705 | includes reception time as well as the total delivery time. | |
33706 | ||
33707 | * received_recipients: The recipients of a message are listed in the main log | |
33708 | as soon as the message is received. The list appears at the end of the log | |
33709 | line that is written when a message is received, preceded by the word | |
33710 | "for". The addresses are listed after they have been qualified, but before | |
33711 | any rewriting has taken place. Recipients that were discarded by an ACL for | |
33712 | MAIL or RCPT do not appear in the list. | |
33713 | ||
33714 | * received_sender: The unrewritten original sender of a message is added to | |
33715 | the end of the log line that records the message's arrival, after the word | |
33716 | "from" (before the recipients if received_recipients is also set). | |
33717 | ||
33718 | * rejected_header: If a message's header has been received at the time a | |
33719 | rejection is written to the reject log, the complete header is added to the | |
33720 | log. Header logging can be turned off individually for messages that are | |
2813c06e | 33721 | rejected by the local_scan() function (see section 45.2). |
420a0d19 CE |
33722 | |
33723 | * retry_defer: A log line is written if a delivery is deferred because a | |
33724 | retry time has not yet been reached. However, this "retry time not reached" | |
33725 | message is always omitted from individual message logs after the first | |
33726 | delivery attempt. | |
33727 | ||
33728 | * return_path_on_delivery: The return path that is being transmitted with the | |
33729 | message is included in delivery and bounce lines, using the tag P=. This is | |
33730 | omitted if no delivery actually happens, for example, if routing fails, or | |
33731 | if delivery is to /dev/null or to ":blackhole:". | |
33732 | ||
33733 | * sender_on_delivery: The message's sender address is added to every delivery | |
33734 | and bounce line, tagged by F= (for "from"). This is the original sender | |
33735 | that was received with the message; it is not necessarily the same as the | |
33736 | outgoing return path. | |
33737 | ||
33738 | * sender_verify_fail: If this selector is unset, the separate log line that | |
33739 | gives details of a sender verification failure is not written. Log lines | |
33740 | for the rejection of SMTP commands contain just "sender verify failed", so | |
33741 | some detail is lost. | |
33742 | ||
33743 | * size_reject: A log line is written whenever a message is rejected because | |
33744 | it is too big. | |
33745 | ||
33746 | * skip_delivery: A log line is written whenever a message is skipped during a | |
33747 | queue run because it is frozen or because another process is already | |
33748 | delivering it. The message that is written is "spool file is locked". | |
33749 | ||
33750 | * smtp_confirmation: The response to the final "." in the SMTP or LMTP | |
33751 | dialogue for outgoing messages is added to delivery log lines in the form | |
33752 | "C="<text>. A number of MTAs (including Exim) return an identifying string | |
33753 | in this response. | |
33754 | ||
2813c06e CE |
33755 | * smtp_connection: A log line is written whenever an incoming SMTP connection |
33756 | is established or closed, unless the connection is from a host that matches | |
420a0d19 CE |
33757 | hosts_connection_nolog. (In contrast, lost_incoming_connection applies only |
33758 | when the closure is unexpected.) This applies to connections from local | |
33759 | processes that use -bs as well as to TCP/IP connections. If a connection is | |
33760 | dropped in the middle of a message, a log line is always written, whether | |
33761 | or not this selector is set, but otherwise nothing is written at the start | |
33762 | and end of connections unless this selector is enabled. | |
33763 | ||
33764 | For TCP/IP connections to an Exim daemon, the current number of connections | |
33765 | is included in the log message for each new connection, but note that the | |
33766 | count is reset if the daemon is restarted. Also, because connections are | |
33767 | closed (and the closure is logged) in subprocesses, the count may not | |
33768 | include connections that have been closed but whose termination the daemon | |
33769 | has not yet noticed. Thus, while it is possible to match up the opening and | |
33770 | closing of connections in the log, the value of the logged counts may not | |
33771 | be entirely accurate. | |
33772 | ||
33773 | * smtp_incomplete_transaction: When a mail transaction is aborted by RSET, | |
33774 | QUIT, loss of connection, or otherwise, the incident is logged, and the | |
33775 | message sender plus any accepted recipients are included in the log line. | |
33776 | This can provide evidence of dictionary attacks. | |
33777 | ||
33778 | * smtp_no_mail: A line is written to the main log whenever an accepted SMTP | |
33779 | connection terminates without having issued a MAIL command. This includes | |
33780 | both the case when the connection is dropped, and the case when QUIT is | |
33781 | used. It does not include cases where the connection is rejected right at | |
33782 | the start (by an ACL, or because there are too many connections, or | |
33783 | whatever). These cases already have their own log lines. | |
33784 | ||
33785 | The log line that is written contains the identity of the client in the | |
33786 | usual way, followed by D= and a time, which records the duration of the | |
33787 | connection. If the connection was authenticated, this fact is logged | |
33788 | exactly as it is for an incoming message, with an A= item. If the | |
33789 | connection was encrypted, CV=, DN=, and X= items may appear as they do for | |
33790 | an incoming message, controlled by the same logging options. | |
33791 | ||
33792 | Finally, if any SMTP commands were issued during the connection, a C= item | |
33793 | is added to the line, listing the commands that were used. For example, | |
33794 | ||
33795 | C=EHLO,QUIT | |
33796 | ||
33797 | shows that the client issued QUIT straight after EHLO. If there were fewer | |
33798 | than 20 commands, they are all listed. If there were more than 20 commands, | |
33799 | the last 20 are listed, preceded by "...". However, with the default | |
2813c06e | 33800 | setting of 10 for smtp_accept_max_nonmail, the connection will in any case |
420a0d19 CE |
33801 | have been aborted before 20 non-mail commands are processed. |
33802 | ||
33803 | * smtp_mailauth: A third subfield with the authenticated sender, | |
33804 | colon-separated, is appended to the A= item for a message arrival or | |
33805 | delivery log line, if an AUTH argument to the SMTP MAIL command (see 33.2) | |
33806 | was accepted or used. | |
33807 | ||
33808 | * smtp_protocol_error: A log line is written for every SMTP protocol error | |
33809 | encountered. Exim does not have perfect detection of all protocol errors | |
33810 | because of transmission delays and the use of pipelining. If PIPELINING has | |
33811 | been advertised to a client, an Exim server assumes that the client will | |
33812 | use it, and therefore it does not count "expected" errors (for example, | |
33813 | RCPT received after rejecting MAIL) as protocol errors. | |
33814 | ||
33815 | * smtp_syntax_error: A log line is written for every SMTP syntax error | |
33816 | encountered. An unrecognized command is treated as a syntax error. For an | |
33817 | external connection, the host identity is given; for an internal connection | |
33818 | using -bs the sender identification (normally the calling user) is given. | |
33819 | ||
33820 | * subject: The subject of the message is added to the arrival log line, | |
33821 | preceded by "T=" (T for "topic", since S is already used for "size"). Any | |
33822 | MIME "words" in the subject are decoded. The print_topbitchars option | |
33823 | specifies whether characters with values greater than 127 should be logged | |
33824 | unchanged, or whether they should be rendered as escape sequences. | |
33825 | ||
33826 | * tls_certificate_verified: An extra item is added to <= and => log lines | |
33827 | when TLS is in use. The item is "CV=yes" if the peer's certificate was | |
33828 | verified, and "CV=no" if not. | |
33829 | ||
33830 | * tls_cipher: When a message is sent or received over an encrypted | |
33831 | connection, the cipher suite used is added to the log line, preceded by X=. | |
33832 | ||
33833 | * tls_peerdn: When a message is sent or received over an encrypted | |
33834 | connection, and a certificate is supplied by the remote host, the peer DN | |
33835 | is added to the log line, preceded by DN=. | |
33836 | ||
33837 | * tls_sni: When a message is received over an encrypted connection, and the | |
33838 | remote host provided the Server Name Indication extension, the SNI is added | |
33839 | to the log line, preceded by SNI=. | |
33840 | ||
33841 | * unknown_in_list: This setting causes a log entry to be written when the | |
33842 | result of a list match is failure because a DNS lookup failed. | |
33843 | ||
33844 | ||
2813c06e | 33845 | 52.16 Message log |
420a0d19 CE |
33846 | ----------------- |
33847 | ||
33848 | In addition to the general log files, Exim writes a log file for each message | |
33849 | that it handles. The names of these per-message logs are the message ids, and | |
33850 | they are kept in the msglog sub-directory of the spool directory. Each message | |
33851 | log contains copies of the log lines that apply to the message. This makes it | |
33852 | easier to inspect the status of an individual message without having to search | |
33853 | the main log. A message log is deleted when processing of the message is | |
33854 | complete, unless preserve_message_logs is set, but this should be used only | |
33855 | with great care because they can fill up your disk very quickly. | |
33856 | ||
33857 | On a heavily loaded system, it may be desirable to disable the use of | |
33858 | per-message logs, in order to reduce disk I/O. This can be done by setting the | |
33859 | message_logs option false. | |
33860 | ||
33861 | ||
33862 | ||
33863 | =============================================================================== | |
2813c06e | 33864 | 53. EXIM UTILITIES |
420a0d19 CE |
33865 | |
33866 | A number of utility scripts and programs are supplied with Exim and are | |
33867 | described in this chapter. There is also the Exim Monitor, which is covered in | |
33868 | the next chapter. The utilities described here are: | |
33869 | ||
2813c06e CE |
33870 | 53.1 exiwhat list what Exim processes are doing |
33871 | 53.2 exiqgrep grep the queue | |
33872 | 53.3 exiqsumm summarize the queue | |
33873 | 53.4 exigrep search the main log | |
33874 | 53.5 exipick select messages on various criteria | |
33875 | 53.6 exicyclog cycle (rotate) log files | |
33876 | 53.7 eximstats extract statistics from the log | |
33877 | 53.8 exim_checkaccess check address acceptance from given IP | |
33878 | 53.9 exim_dbmbuild build a DBM file | |
33879 | 53.10 exinext extract retry information | |
33880 | 53.11 exim_dumpdb dump a hints database | |
33881 | 53.11 exim_tidydb clean up a hints database | |
33882 | 53.11 exim_fixdb patch a hints database | |
33883 | 53.15 exim_lock lock a mailbox file | |
420a0d19 CE |
33884 | |
33885 | Another utility that might be of use to sites with many MTAs is Tom Kistner's | |
33886 | exilog. It provides log visualizations across multiple Exim servers. See http:/ | |
33887 | /duncanthrax.net/exilog/ for details. | |
33888 | ||
33889 | ||
2813c06e | 33890 | 53.1 Finding out what Exim processes are doing (exiwhat) |
420a0d19 CE |
33891 | -------------------------------------------------------- |
33892 | ||
33893 | On operating systems that can restart a system call after receiving a signal | |
33894 | (most modern OS), an Exim process responds to the SIGUSR1 signal by writing a | |
33895 | line describing what it is doing to the file exim-process.info in the Exim | |
33896 | spool directory. The exiwhat script sends the signal to all Exim processes it | |
33897 | can find, having first emptied the file. It then waits for one second to allow | |
33898 | the Exim processes to react before displaying the results. In order to run | |
33899 | exiwhat successfully you have to have sufficient privilege to send the signal | |
33900 | to the Exim processes, so it is normally run as root. | |
33901 | ||
33902 | Warning: This is not an efficient process. It is intended for occasional use by | |
33903 | system administrators. It is not sensible, for example, to set up a script that | |
33904 | sends SIGUSR1 signals to Exim processes at short intervals. | |
33905 | ||
33906 | Unfortunately, the ps command that exiwhat uses to find Exim processes varies | |
33907 | in different operating systems. Not only are different options used, but the | |
33908 | format of the output is different. For this reason, there are some system | |
33909 | configuration options that configure exactly how exiwhat works. If it doesn't | |
33910 | seem to be working for you, check the following compile-time options: | |
33911 | ||
33912 | EXIWHAT_PS_CMD the command for running ps | |
33913 | EXIWHAT_PS_ARG the argument for ps | |
33914 | EXIWHAT_EGREP_ARG the argument for egrep to select from ps output | |
33915 | EXIWHAT_KILL_ARG the argument for the kill command | |
33916 | ||
33917 | An example of typical output from exiwhat is | |
33918 | ||
33919 | 164 daemon: -q1h, listening on port 25 | |
33920 | 10483 running queue: waiting for 0tAycK-0002ij-00 (10492) | |
33921 | 10492 delivering 0tAycK-0002ij-00 to mail.ref.example | |
33922 | [10.19.42.42] (editor@ref.example) | |
33923 | 10592 handling incoming call from [192.168.243.242] | |
33924 | 10628 accepting a local non-SMTP message | |
33925 | ||
33926 | The first number in the output line is the process number. The third line has | |
33927 | been split here, in order to fit it on the page. | |
33928 | ||
33929 | ||
2813c06e | 33930 | 53.2 Selective queue listing (exiqgrep) |
420a0d19 CE |
33931 | --------------------------------------- |
33932 | ||
33933 | This utility is a Perl script contributed by Matt Hubbard. It runs | |
33934 | ||
33935 | exim -bpu | |
33936 | ||
33937 | or (in case -a switch is specified) | |
33938 | ||
33939 | exim -bp | |
33940 | ||
33941 | The -C option is used to specify an alternate exim.conf which might contain | |
33942 | alternate exim configuration the queue management might be using. | |
33943 | ||
33944 | to obtain a queue listing, and then greps the output to select messages that | |
33945 | match given criteria. The following selection options are available: | |
33946 | ||
33947 | -f <regex> | |
33948 | ||
33949 | Match the sender address using a case-insensitive search. The field that is | |
33950 | tested is enclosed in angle brackets, so you can test for bounce messages | |
33951 | with | |
33952 | ||
33953 | exiqgrep -f '^<>$' | |
33954 | ||
33955 | -r <regex> | |
33956 | ||
2813c06e CE |
33957 | Match a recipient address using a case-insensitive search. The field that |
33958 | is tested is not enclosed in angle brackets. | |
420a0d19 CE |
33959 | |
33960 | -s <regex> | |
33961 | ||
33962 | Match against the size field. | |
33963 | ||
33964 | -y <seconds> | |
33965 | ||
33966 | Match messages that are younger than the given time. | |
33967 | ||
33968 | -o <seconds> | |
33969 | ||
33970 | Match messages that are older than the given time. | |
33971 | ||
33972 | -z | |
33973 | ||
33974 | Match only frozen messages. | |
33975 | ||
33976 | -x | |
33977 | ||
33978 | Match only non-frozen messages. | |
33979 | ||
33980 | The following options control the format of the output: | |
33981 | ||
33982 | -c | |
33983 | ||
33984 | Display only the count of matching messages. | |
33985 | ||
33986 | -l | |
33987 | ||
33988 | Long format - display the full message information as output by Exim. This | |
33989 | is the default. | |
33990 | ||
33991 | -i | |
33992 | ||
33993 | Display message ids only. | |
33994 | ||
33995 | -b | |
33996 | ||
33997 | Brief format - one line per message. | |
33998 | ||
33999 | -R | |
34000 | ||
34001 | Display messages in reverse order. | |
34002 | ||
34003 | -a | |
34004 | ||
34005 | Include delivered recipients in queue listing. | |
34006 | ||
34007 | There is one more option, -h, which outputs a list of options. | |
34008 | ||
34009 | ||
2813c06e | 34010 | 53.3 Summarizing the queue (exiqsumm) |
420a0d19 CE |
34011 | ------------------------------------- |
34012 | ||
34013 | The exiqsumm utility is a Perl script which reads the output of "exim -bp" and | |
34014 | produces a summary of the messages on the queue. Thus, you use it by running a | |
34015 | command such as | |
34016 | ||
34017 | exim -bp | exiqsumm | |
34018 | ||
34019 | The output consists of one line for each domain that has messages waiting for | |
34020 | it, as in the following example: | |
34021 | ||
34022 | 3 2322 74m 66m msn.com.example | |
34023 | ||
34024 | Each line lists the number of pending deliveries for a domain, their total | |
34025 | volume, and the length of time that the oldest and the newest messages have | |
34026 | been waiting. Note that the number of pending deliveries is greater than the | |
34027 | number of messages when messages have more than one recipient. | |
34028 | ||
34029 | A summary line is output at the end. By default the output is sorted on the | |
34030 | domain name, but exiqsumm has the options -a and -c, which cause the output to | |
34031 | be sorted by oldest message and by count of messages, respectively. There are | |
34032 | also three options that split the messages for each domain into two or more | |
34033 | subcounts: -b separates bounce messages, -f separates frozen messages, and -s | |
34034 | separates messages according to their sender. | |
34035 | ||
34036 | The output of exim -bp contains the original addresses in the message, so this | |
34037 | also applies to the output from exiqsumm. No domains from addresses generated | |
34038 | by aliasing or forwarding are included (unless the one_time option of the | |
34039 | redirect router has been used to convert them into "top level" addresses). | |
34040 | ||
34041 | ||
2813c06e | 34042 | 53.4 Extracting specific information from the log (exigrep) |
420a0d19 CE |
34043 | ----------------------------------------------------------- |
34044 | ||
34045 | The exigrep utility is a Perl script that searches one or more main log files | |
34046 | for entries that match a given pattern. When it finds a match, it extracts all | |
34047 | the log entries for the relevant message, not just those that match the | |
34048 | pattern. Thus, exigrep can extract complete log entries for a given message, or | |
34049 | all mail for a given user, or for a given host, for example. The input files | |
34050 | can be in Exim log format or syslog format. If a matching log line is not | |
34051 | associated with a specific message, it is included in exigrep's output without | |
34052 | any additional lines. The usage is: | |
34053 | ||
2813c06e | 34054 | exigrep [-t<n>] [-I] [-l] [-M] [-v] <pattern> [<log file>] ... |
420a0d19 CE |
34055 | |
34056 | If no log file names are given on the command line, the standard input is read. | |
34057 | ||
34058 | The -t argument specifies a number of seconds. It adds an additional condition | |
34059 | for message selection. Messages that are complete are shown only if they spent | |
34060 | more than <n> seconds on the queue. | |
34061 | ||
34062 | By default, exigrep does case-insensitive matching. The -I option makes it | |
34063 | case-sensitive. This may give a performance improvement when searching large | |
34064 | log files. Without -I, the Perl pattern matches use Perl's "/i" option; with -I | |
34065 | they do not. In both cases it is possible to change the case sensitivity within | |
34066 | the pattern by using "(?i)" or "(?-i)". | |
34067 | ||
34068 | The -l option means "literal", that is, treat all characters in the pattern as | |
34069 | standing for themselves. Otherwise the pattern must be a Perl regular | |
34070 | expression. | |
34071 | ||
34072 | The -v option inverts the matching condition. That is, a line is selected if it | |
34073 | does not match the pattern. | |
34074 | ||
2813c06e CE |
34075 | The -M options means "related messages". exigrep will show messages that are |
34076 | generated as a result/response to a message that exigrep matched normally. | |
34077 | ||
34078 | Example of -M: user_a sends a message to user_b, which generates a bounce back | |
34079 | to user_b. If exigrep is used to search for "user_a", only the first message | |
34080 | will be displayed. But if exigrep is used to search for "user_b", the first and | |
34081 | the second (bounce) message will be displayed. Using -M with exigrep when | |
34082 | searching for "user_a" will show both messages since the bounce is "related" to | |
34083 | or a "result" of the first message that was found by the search term. | |
34084 | ||
420a0d19 CE |
34085 | If the location of a zcat command is known from the definition of ZCAT_COMMAND |
34086 | in Local/Makefile, exigrep automatically passes any file whose name ends in | |
2813c06e CE |
34087 | COMPRESS_SUFFIX through zcat as it searches it. If the ZCAT_COMMAND is not |
34088 | executable, exigrep tries to use autodetection of some well known compression | |
34089 | extensions. | |
420a0d19 CE |
34090 | |
34091 | ||
2813c06e | 34092 | 53.5 Selecting messages by various criteria (exipick) |
420a0d19 CE |
34093 | ----------------------------------------------------- |
34094 | ||
34095 | John Jetmore's exipick utility is included in the Exim distribution. It lists | |
34096 | messages from the queue according to a variety of criteria. For details of | |
34097 | exipick's facilities, visit the web page at http://www.exim.org/eximwiki/ | |
34098 | ToolExipickManPage or run exipick with the --help option. | |
34099 | ||
34100 | ||
2813c06e | 34101 | 53.6 Cycling log files (exicyclog) |
420a0d19 CE |
34102 | ---------------------------------- |
34103 | ||
34104 | The exicyclog script can be used to cycle (rotate) mainlog and rejectlog files. | |
34105 | This is not necessary if only syslog is being used, or if you are using log | |
2813c06e | 34106 | files with datestamps in their names (see section 52.3). Some operating systems |
420a0d19 CE |
34107 | have their own standard mechanisms for log cycling, and these can be used |
34108 | instead of exicyclog if preferred. There are two command line options for | |
34109 | exicyclog: | |
34110 | ||
34111 | * -k <count> specifies the number of log files to keep, overriding the | |
34112 | default that is set when Exim is built. The default default is 10. | |
34113 | ||
34114 | * -l <path> specifies the log file path, in the same format as Exim's | |
34115 | log_file_path option (for example, "/var/log/exim_%slog"), again overriding | |
34116 | the script's default, which is to find the setting from Exim's | |
34117 | configuration. | |
34118 | ||
34119 | Each time exicyclog is run the file names get "shuffled down" by one. If the | |
34120 | main log file name is mainlog (the default) then when exicyclog is run mainlog | |
34121 | becomes mainlog.01, the previous mainlog.01 becomes mainlog.02 and so on, up to | |
34122 | the limit that is set in the script or by the -k option. Log files whose | |
34123 | numbers exceed the limit are discarded. Reject logs are handled similarly. | |
34124 | ||
34125 | If the limit is greater than 99, the script uses 3-digit numbers such as | |
34126 | mainlog.001, mainlog.002, etc. If you change from a number less than 99 to one | |
34127 | that is greater, or vice versa, you will have to fix the names of any existing | |
34128 | log files. | |
34129 | ||
34130 | If no mainlog file exists, the script does nothing. Files that "drop off" the | |
34131 | end are deleted. All files with numbers greater than 01 are compressed, using a | |
34132 | compression command which is configured by the COMPRESS_COMMAND setting in | |
34133 | Local/Makefile. It is usual to run exicyclog daily from a root crontab entry of | |
34134 | the form | |
34135 | ||
34136 | 1 0 * * * su exim -c /usr/exim/bin/exicyclog | |
34137 | ||
34138 | assuming you have used the name "exim" for the Exim user. You can run exicyclog | |
34139 | as root if you wish, but there is no need. | |
34140 | ||
34141 | ||
2813c06e | 34142 | 53.7 Mail statistics (eximstats) |
420a0d19 CE |
34143 | -------------------------------- |
34144 | ||
34145 | A Perl script called eximstats is provided for extracting statistical | |
34146 | information from log files. The output is either plain text, or HTML. Exim log | |
34147 | files are also supported by the Lire system produced by the LogReport | |
34148 | Foundation http://www.logreport.org. | |
34149 | ||
34150 | The eximstats script has been hacked about quite a bit over time. The latest | |
34151 | version is the result of some extensive revision by Steve Campbell. A lot of | |
34152 | information is given by default, but there are options for suppressing various | |
34153 | parts of it. Following any options, the arguments to the script are a list of | |
34154 | files, which should be main log files. For example: | |
34155 | ||
34156 | eximstats -nr /var/spool/exim/log/mainlog.01 | |
34157 | ||
34158 | By default, eximstats extracts information about the number and volume of | |
34159 | messages received from or delivered to various hosts. The information is sorted | |
34160 | both by message count and by volume, and the top fifty hosts in each category | |
34161 | are listed on the standard output. Similar information, based on email | |
34162 | addresses or domains instead of hosts can be requested by means of various | |
34163 | options. For messages delivered and received locally, similar statistics are | |
34164 | also produced per user. | |
34165 | ||
34166 | The output also includes total counts and statistics about delivery errors, and | |
34167 | histograms showing the number of messages received and deliveries made in each | |
34168 | hour of the day. A delivery with more than one address in its envelope (for | |
34169 | example, an SMTP transaction with more than one RCPT command) is counted as a | |
34170 | single delivery by eximstats. | |
34171 | ||
34172 | Though normally more deliveries than receipts are reported (as messages may | |
34173 | have multiple recipients), it is possible for eximstats to report more messages | |
34174 | received than delivered, even though the queue is empty at the start and end of | |
34175 | the period in question. If an incoming message contains no valid recipients, no | |
34176 | deliveries are recorded for it. A bounce message is handled as an entirely | |
34177 | separate message. | |
34178 | ||
34179 | eximstats always outputs a grand total summary giving the volume and number of | |
34180 | messages received and deliveries made, and the number of hosts involved in each | |
34181 | case. It also outputs the number of messages that were delayed (that is, not | |
34182 | completely delivered at the first attempt), and the number that had at least | |
34183 | one address that failed. | |
34184 | ||
34185 | The remainder of the output is in sections that can be independently disabled | |
34186 | or modified by various options. It consists of a summary of deliveries by | |
34187 | transport, histograms of messages received and delivered per time interval | |
34188 | (default per hour), information about the time messages spent on the queue, a | |
34189 | list of relayed messages, lists of the top fifty sending hosts, local senders, | |
34190 | destination hosts, and destination local users by count and by volume, and a | |
34191 | list of delivery errors that occurred. | |
34192 | ||
34193 | The relay information lists messages that were actually relayed, that is, they | |
34194 | came from a remote host and were directly delivered to some other remote host, | |
34195 | without being processed (for example, for aliasing or forwarding) locally. | |
34196 | ||
34197 | There are quite a few options for eximstats to control exactly what it outputs. | |
34198 | These are documented in the Perl script itself, and can be extracted by running | |
34199 | the command perldoc on the script. For example: | |
34200 | ||
34201 | perldoc /usr/exim/bin/eximstats | |
34202 | ||
34203 | ||
2813c06e | 34204 | 53.8 Checking access policy (exim_checkaccess) |
420a0d19 CE |
34205 | ---------------------------------------------- |
34206 | ||
34207 | The -bh command line argument allows you to run a fake SMTP session with | |
34208 | debugging output, in order to check what Exim is doing when it is applying | |
34209 | policy controls to incoming SMTP mail. However, not everybody is sufficiently | |
34210 | familiar with the SMTP protocol to be able to make full use of -bh, and | |
34211 | sometimes you just want to answer the question "Does this address have access?" | |
34212 | without bothering with any further details. | |
34213 | ||
34214 | The exim_checkaccess utility is a "packaged" version of -bh. It takes two | |
34215 | arguments, an IP address and an email address: | |
34216 | ||
34217 | exim_checkaccess 10.9.8.7 A.User@a.domain.example | |
34218 | ||
34219 | The utility runs a call to Exim with the -bh option, to test whether the given | |
34220 | email address would be accepted in a RCPT command in a TCP/IP connection from | |
34221 | the host with the given IP address. The output of the utility is either the | |
34222 | word "accepted", or the SMTP error response, for example: | |
34223 | ||
34224 | Rejected: | |
34225 | 550 Relay not permitted | |
34226 | ||
34227 | When running this test, the utility uses "<>" as the envelope sender address | |
34228 | for the MAIL command, but you can change this by providing additional options. | |
34229 | These are passed directly to the Exim command. For example, to specify that the | |
34230 | test is to be run with the sender address himself@there.example you can use: | |
34231 | ||
34232 | exim_checkaccess 10.9.8.7 A.User@a.domain.example \ | |
34233 | -f himself@there.example | |
34234 | ||
34235 | Note that these additional Exim command line items must be given after the two | |
34236 | mandatory arguments. | |
34237 | ||
34238 | Because the exim_checkaccess uses -bh, it does not perform callouts while | |
34239 | running its checks. You can run checks that include callouts by using -bhc, but | |
34240 | this is not yet available in a "packaged" form. | |
34241 | ||
34242 | ||
2813c06e | 34243 | 53.9 Making DBM files (exim_dbmbuild) |
420a0d19 CE |
34244 | ------------------------------------- |
34245 | ||
34246 | The exim_dbmbuild program reads an input file containing keys and data in the | |
34247 | format used by the lsearch lookup (see section 9.3). It writes a DBM file using | |
34248 | the lower-cased alias names as keys and the remainder of the information as | |
34249 | data. The lower-casing can be prevented by calling the program with the -nolc | |
34250 | option. | |
34251 | ||
34252 | A terminating zero is included as part of the key string. This is expected by | |
34253 | the dbm lookup type. However, if the option -nozero is given, exim_dbmbuild | |
34254 | creates files without terminating zeroes in either the key strings or the data | |
34255 | strings. The dbmnz lookup type can be used with such files. | |
34256 | ||
34257 | The program requires two arguments: the name of the input file (which can be a | |
34258 | single hyphen to indicate the standard input), and the name of the output file. | |
34259 | It creates the output under a temporary name, and then renames it if all went | |
34260 | well. | |
34261 | ||
34262 | If the native DB interface is in use (USE_DB is set in a compile-time | |
34263 | configuration file - this is common in free versions of Unix) the two file | |
34264 | names must be different, because in this mode the Berkeley DB functions create | |
34265 | a single output file using exactly the name given. For example, | |
34266 | ||
34267 | exim_dbmbuild /etc/aliases /etc/aliases.db | |
34268 | ||
34269 | reads the system alias file and creates a DBM version of it in /etc/aliases.db. | |
34270 | ||
34271 | In systems that use the ndbm routines (mostly proprietary versions of Unix), | |
34272 | two files are used, with the suffixes .dir and .pag. In this environment, the | |
34273 | suffixes are added to the second argument of exim_dbmbuild, so it can be the | |
34274 | same as the first. This is also the case when the Berkeley functions are used | |
34275 | in compatibility mode (though this is not recommended), because in that case it | |
34276 | adds a .db suffix to the file name. | |
34277 | ||
34278 | If a duplicate key is encountered, the program outputs a warning, and when it | |
34279 | finishes, its return code is 1 rather than zero, unless the -noduperr option is | |
34280 | used. By default, only the first of a set of duplicates is used - this makes it | |
34281 | compatible with lsearch lookups. There is an option -lastdup which causes it to | |
34282 | use the data for the last duplicate instead. There is also an option -nowarn, | |
34283 | which stops it listing duplicate keys to stderr. For other errors, where it | |
34284 | doesn't actually make a new file, the return code is 2. | |
34285 | ||
34286 | ||
2813c06e | 34287 | 53.10 Finding individual retry times (exinext) |
420a0d19 CE |
34288 | ---------------------------------------------- |
34289 | ||
34290 | A utility called exinext (mostly a Perl script) provides the ability to fish | |
34291 | specific information out of the retry database. Given a mail domain (or a | |
34292 | complete address), it looks up the hosts for that domain, and outputs any retry | |
34293 | information for the hosts or for the domain. At present, the retry information | |
34294 | is obtained by running exim_dumpdb (see below) and post-processing the output. | |
34295 | For example: | |
34296 | ||
34297 | $ exinext piglet@milne.fict.example | |
34298 | kanga.milne.example:192.168.8.1 error 146: Connection refused | |
34299 | first failed: 21-Feb-1996 14:57:34 | |
34300 | last tried: 21-Feb-1996 14:57:34 | |
34301 | next try at: 21-Feb-1996 15:02:34 | |
34302 | roo.milne.example:192.168.8.3 error 146: Connection refused | |
34303 | first failed: 20-Jan-1996 13:12:08 | |
34304 | last tried: 21-Feb-1996 11:42:03 | |
34305 | next try at: 21-Feb-1996 19:42:03 | |
34306 | past final cutoff time | |
34307 | ||
34308 | You can also give exinext a local part, without a domain, and it will give any | |
34309 | retry information for that local part in your default domain. A message id can | |
34310 | be used to obtain retry information pertaining to a specific message. This | |
34311 | exists only when an attempt to deliver a message to a remote host suffers a | |
2813c06e | 34312 | message-specific error (see section 48.2). exinext is not particularly |
420a0d19 CE |
34313 | efficient, but then it is not expected to be run very often. |
34314 | ||
34315 | The exinext utility calls Exim to find out information such as the location of | |
34316 | the spool directory. The utility has -C and -D options, which are passed on to | |
34317 | the exim commands. The first specifies an alternate Exim configuration file, | |
34318 | and the second sets macros for use within the configuration file. These | |
34319 | features are mainly to help in testing, but might also be useful in | |
34320 | environments where more than one configuration file is in use. | |
34321 | ||
34322 | ||
2813c06e | 34323 | 53.11 Hints database maintenance |
420a0d19 CE |
34324 | -------------------------------- |
34325 | ||
34326 | Three utility programs are provided for maintaining the DBM files that Exim | |
34327 | uses to contain its delivery hint information. Each program requires two | |
34328 | arguments. The first specifies the name of Exim's spool directory, and the | |
34329 | second is the name of the database it is to operate on. These are as follows: | |
34330 | ||
34331 | * retry: the database of retry information | |
34332 | ||
34333 | * wait-<transport name>: databases of information about messages waiting for | |
34334 | remote hosts | |
34335 | ||
34336 | * callout: the callout cache | |
34337 | ||
34338 | * ratelimit: the data for implementing the ratelimit ACL condition | |
34339 | ||
34340 | * misc: other hints data | |
34341 | ||
34342 | The misc database is used for | |
34343 | ||
34344 | * Serializing ETRN runs (when smtp_etrn_serialize is set) | |
34345 | ||
34346 | * Serializing delivery to a specific host (when serialize_hosts is set in an | |
34347 | smtp transport) | |
34348 | ||
2813c06e CE |
34349 | * Limiting the concurrency of specific transports (when max_parallel is set |
34350 | in a transport) | |
34351 | ||
420a0d19 | 34352 | |
2813c06e | 34353 | 53.12 exim_dumpdb |
420a0d19 CE |
34354 | ----------------- |
34355 | ||
34356 | The entire contents of a database are written to the standard output by the | |
34357 | exim_dumpdb program, which has no options or arguments other than the spool and | |
34358 | database names. For example, to dump the retry database: | |
34359 | ||
34360 | exim_dumpdb /var/spool/exim retry | |
34361 | ||
34362 | Two lines of output are produced for each entry: | |
34363 | ||
34364 | T:mail.ref.example:192.168.242.242 146 77 Connection refused | |
34365 | 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 * | |
34366 | ||
34367 | The first item on the first line is the key of the record. It starts with one | |
34368 | of the letters R, or T, depending on whether it refers to a routing or | |
34369 | transport retry. For a local delivery, the next part is the local address; for | |
34370 | a remote delivery it is the name of the remote host, followed by its failing IP | |
34371 | address (unless retry_include_ip_address is set false on the smtp transport). | |
34372 | If the remote port is not the standard one (port 25), it is added to the IP | |
34373 | address. Then there follows an error code, an additional error code, and a | |
34374 | textual description of the error. | |
34375 | ||
34376 | The three times on the second line are the time of first failure, the time of | |
34377 | the last delivery attempt, and the computed time for the next attempt. The line | |
34378 | ends with an asterisk if the cutoff time for the last retry rule has been | |
34379 | exceeded. | |
34380 | ||
34381 | Each output line from exim_dumpdb for the wait-xxx databases consists of a host | |
34382 | name followed by a list of ids for messages that are or were waiting to be | |
34383 | delivered to that host. If there are a very large number for any one host, | |
34384 | continuation records, with a sequence number added to the host name, may be | |
34385 | seen. The data in these records is often out of date, because a message may be | |
34386 | routed to several alternative hosts, and Exim makes no effort to keep | |
34387 | cross-references. | |
34388 | ||
34389 | ||
2813c06e | 34390 | 53.13 exim_tidydb |
420a0d19 CE |
34391 | ----------------- |
34392 | ||
34393 | The exim_tidydb utility program is used to tidy up the contents of a hints | |
34394 | database. If run with no options, it removes all records that are more than 30 | |
34395 | days old. The age is calculated from the date and time that the record was last | |
34396 | updated. Note that, in the case of the retry database, it is not the time since | |
34397 | the first delivery failure. Information about a host that has been down for | |
34398 | more than 30 days will remain in the database, provided that the record is | |
34399 | updated sufficiently often. | |
34400 | ||
34401 | The cutoff date can be altered by means of the -t option, which must be | |
34402 | followed by a time. For example, to remove all records older than a week from | |
34403 | the retry database: | |
34404 | ||
34405 | exim_tidydb -t 7d /var/spool/exim retry | |
34406 | ||
34407 | Both the wait-xxx and retry databases contain items that involve message ids. | |
34408 | In the former these appear as data in records keyed by host - they were | |
34409 | messages that were waiting for that host - and in the latter they are the keys | |
34410 | for retry information for messages that have suffered certain types of error. | |
34411 | When exim_tidydb is run, a check is made to ensure that message ids in database | |
34412 | records are those of messages that are still on the queue. Message ids for | |
34413 | messages that no longer exist are removed from wait-xxx records, and if this | |
34414 | leaves any records empty, they are deleted. For the retry database, records | |
34415 | whose keys are non-existent message ids are removed. The exim_tidydb utility | |
34416 | outputs comments on the standard output whenever it removes information from | |
34417 | the database. | |
34418 | ||
34419 | Certain records are automatically removed by Exim when they are no longer | |
34420 | needed, but others are not. For example, if all the MX hosts for a domain are | |
34421 | down, a retry record is created for each one. If the primary MX host comes back | |
34422 | first, its record is removed when Exim successfully delivers to it, but the | |
34423 | records for the others remain because Exim has not tried to use those hosts. | |
34424 | ||
34425 | It is important, therefore, to run exim_tidydb periodically on all the hints | |
34426 | databases. You should do this at a quiet time of day, because it requires a | |
34427 | database to be locked (and therefore inaccessible to Exim) while it does its | |
34428 | work. Removing records from a DBM file does not normally make the file smaller, | |
34429 | but all the common DBM libraries are able to re-use the space that is released. | |
34430 | After an initial phase of increasing in size, the databases normally reach a | |
34431 | point at which they no longer get any bigger, as long as they are regularly | |
34432 | tidied. | |
34433 | ||
34434 | Warning: If you never run exim_tidydb, the space used by the hints databases is | |
34435 | likely to keep on increasing. | |
34436 | ||
34437 | ||
2813c06e | 34438 | 53.14 exim_fixdb |
420a0d19 CE |
34439 | ---------------- |
34440 | ||
34441 | The exim_fixdb program is a utility for interactively modifying databases. Its | |
34442 | main use is for testing Exim, but it might also be occasionally useful for | |
34443 | getting round problems in a live system. It has no options, and its interface | |
34444 | is somewhat crude. On entry, it prompts for input with a right angle-bracket. A | |
34445 | key of a database record can then be entered, and the data for that record is | |
34446 | displayed. | |
34447 | ||
34448 | If "d" is typed at the next prompt, the entire record is deleted. For all | |
34449 | except the retry database, that is the only operation that can be carried out. | |
34450 | For the retry database, each field is output preceded by a number, and data for | |
34451 | individual fields can be changed by typing the field number followed by new | |
34452 | data, for example: | |
34453 | ||
34454 | > 4 951102:1000 | |
34455 | ||
34456 | resets the time of the next delivery attempt. Time values are given as a | |
34457 | sequence of digit pairs for year, month, day, hour, and minute. Colons can be | |
34458 | used as optional separators. | |
34459 | ||
34460 | ||
2813c06e | 34461 | 53.15 Mailbox maintenance (exim_lock) |
420a0d19 CE |
34462 | ------------------------------------- |
34463 | ||
34464 | The exim_lock utility locks a mailbox file using the same algorithm as Exim. | |
34465 | For a discussion of locking issues, see section 26.3. Exim_lock can be used to | |
34466 | prevent any modification of a mailbox by Exim or a user agent while | |
34467 | investigating a problem. The utility requires the name of the file as its first | |
34468 | argument. If the locking is successful, the second argument is run as a command | |
34469 | (using C's system() function); if there is no second argument, the value of the | |
34470 | SHELL environment variable is used; if this is unset or empty, /bin/sh is run. | |
34471 | When the command finishes, the mailbox is unlocked and the utility ends. The | |
34472 | following options are available: | |
34473 | ||
34474 | -fcntl | |
34475 | ||
34476 | Use fcntl() locking on the open mailbox. | |
34477 | ||
34478 | -flock | |
34479 | ||
34480 | Use flock() locking on the open mailbox, provided the operating system | |
34481 | supports it. | |
34482 | ||
34483 | -interval | |
34484 | ||
34485 | This must be followed by a number, which is a number of seconds; it sets | |
34486 | the interval to sleep between retries (default 3). | |
34487 | ||
34488 | -lockfile | |
34489 | ||
34490 | Create a lock file before opening the mailbox. | |
34491 | ||
34492 | -mbx | |
34493 | ||
34494 | Lock the mailbox using MBX rules. | |
34495 | ||
34496 | -q | |
34497 | ||
34498 | Suppress verification output. | |
34499 | ||
34500 | -retries | |
34501 | ||
34502 | This must be followed by a number; it sets the number of times to try to | |
34503 | get the lock (default 10). | |
34504 | ||
34505 | -restore_time | |
34506 | ||
34507 | This option causes exim_lock to restore the modified and read times to the | |
34508 | locked file before exiting. This allows you to access a locked mailbox (for | |
34509 | example, to take a backup copy) without disturbing the times that the user | |
34510 | subsequently sees. | |
34511 | ||
34512 | -timeout | |
34513 | ||
34514 | This must be followed by a number, which is a number of seconds; it sets a | |
34515 | timeout to be used with a blocking fcntl() lock. If it is not set (the | |
34516 | default), a non-blocking call is used. | |
34517 | ||
34518 | -v | |
34519 | ||
34520 | Generate verbose output. | |
34521 | ||
34522 | If none of -fcntl, -flock, -lockfile or -mbx are given, the default is to | |
34523 | create a lock file and also to use fcntl() locking on the mailbox, which is the | |
34524 | same as Exim's default. The use of -flock or -fcntl requires that the file be | |
34525 | writeable; the use of -lockfile requires that the directory containing the file | |
34526 | be writeable. Locking by lock file does not last for ever; Exim assumes that a | |
34527 | lock file is expired if it is more than 30 minutes old. | |
34528 | ||
34529 | The -mbx option can be used with either or both of -fcntl or -flock. It assumes | |
34530 | -fcntl by default. MBX locking causes a shared lock to be taken out on the open | |
34531 | mailbox, and an exclusive lock on the file /tmp/.n.m where n and m are the | |
34532 | device number and inode number of the mailbox file. When the locking is | |
34533 | released, if an exclusive lock can be obtained for the mailbox, the file in / | |
34534 | tmp is deleted. | |
34535 | ||
34536 | The default output contains verification of the locking that takes place. The | |
34537 | -v option causes some additional information to be given. The -q option | |
34538 | suppresses all output except error messages. | |
34539 | ||
34540 | A command such as | |
34541 | ||
34542 | exim_lock /var/spool/mail/spqr | |
34543 | ||
34544 | runs an interactive shell while the file is locked, whereas | |
34545 | ||
34546 | exim_lock -q /var/spool/mail/spqr <<End | |
34547 | <some commands> | |
34548 | End | |
34549 | ||
34550 | runs a specific non-interactive sequence of commands while the file is locked, | |
34551 | suppressing all verification output. A single command can be run by a command | |
34552 | such as | |
34553 | ||
34554 | exim_lock -q /var/spool/mail/spqr \ | |
34555 | "cp /var/spool/mail/spqr /some/where" | |
34556 | ||
34557 | Note that if a command is supplied, it must be entirely contained within the | |
34558 | second argument - hence the quotes. | |
34559 | ||
34560 | ||
34561 | ||
34562 | =============================================================================== | |
2813c06e | 34563 | 54. THE EXIM MONITOR |
420a0d19 CE |
34564 | |
34565 | The Exim monitor is an application which displays in an X window information | |
34566 | about the state of Exim's queue and what Exim is doing. An admin user can | |
34567 | perform certain operations on messages from this GUI interface; however all | |
34568 | such facilities are also available from the command line, and indeed, the | |
34569 | monitor itself makes use of the command line to perform any actions requested. | |
34570 | ||
34571 | ||
2813c06e | 34572 | 54.1 Running the monitor |
420a0d19 CE |
34573 | ------------------------ |
34574 | ||
34575 | The monitor is started by running the script called eximon. This is a shell | |
34576 | script that sets up a number of environment variables, and then runs the binary | |
34577 | called eximon.bin. The default appearance of the monitor window can be changed | |
34578 | by editing the Local/eximon.conf file created by editing exim_monitor/EDITME. | |
34579 | Comments in that file describe what the various parameters are for. | |
34580 | ||
34581 | The parameters that get built into the eximon script can be overridden for a | |
34582 | particular invocation by setting up environment variables of the same names, | |
34583 | preceded by "EXIMON_". For example, a shell command such as | |
34584 | ||
34585 | EXIMON_LOG_DEPTH=400 eximon | |
34586 | ||
34587 | (in a Bourne-compatible shell) runs eximon with an overriding setting of the | |
34588 | LOG_DEPTH parameter. If EXIMON_LOG_FILE_PATH is set in the environment, it | |
34589 | overrides the Exim log file configuration. This makes it possible to have | |
34590 | eximon tailing log data that is written to syslog, provided that MAIL.INFO | |
34591 | syslog messages are routed to a file on the local host. | |
34592 | ||
34593 | X resources can be used to change the appearance of the window in the normal | |
34594 | way. For example, a resource setting of the form | |
34595 | ||
34596 | Eximon*background: gray94 | |
34597 | ||
34598 | changes the colour of the background to light grey rather than white. The | |
34599 | stripcharts are drawn with both the data lines and the reference lines in | |
34600 | black. This means that the reference lines are not visible when on top of the | |
34601 | data. However, their colour can be changed by setting a resource called | |
34602 | "highlight" (an odd name, but that's what the Athena stripchart widget uses). | |
34603 | For example, if your X server is running Unix, you could set up lighter | |
34604 | reference lines in the stripcharts by obeying | |
34605 | ||
34606 | xrdb -merge <<End | |
34607 | Eximon*highlight: gray | |
34608 | End | |
34609 | ||
34610 | In order to see the contents of messages on the queue, and to operate on them, | |
34611 | eximon must either be run as root or by an admin user. | |
34612 | ||
34613 | The command-line parameters of eximon are passed to eximon.bin and may contain | |
34614 | X11 resource parameters interpreted by the X11 library. In addition, if the | |
34615 | first parameter starts with the string "gdb" then it is removed and the binary | |
34616 | is invoked under gdb (the parameter is used as the gdb command-name, so | |
34617 | versioned variants of gdb can be invoked). | |
34618 | ||
34619 | The monitor's window is divided into three parts. The first contains one or | |
34620 | more stripcharts and two action buttons, the second contains a "tail" of the | |
34621 | main log file, and the third is a display of the queue of messages awaiting | |
34622 | delivery, with two more action buttons. The following sections describe these | |
34623 | different parts of the display. | |
34624 | ||
34625 | ||
2813c06e | 34626 | 54.2 The stripcharts |
420a0d19 CE |
34627 | -------------------- |
34628 | ||
34629 | The first stripchart is always a count of messages on the queue. Its name can | |
34630 | be configured by setting QUEUE_STRIPCHART_NAME in the Local/eximon.conf file. | |
34631 | The remaining stripcharts are defined in the configuration script by regular | |
34632 | expression matches on log file entries, making it possible to display, for | |
34633 | example, counts of messages delivered to certain hosts or using certain | |
34634 | transports. The supplied defaults display counts of received and delivered | |
34635 | messages, and of local and SMTP deliveries. The default period between | |
34636 | stripchart updates is one minute; this can be adjusted by a parameter in the | |
34637 | Local/eximon.conf file. | |
34638 | ||
34639 | The stripchart displays rescale themselves automatically as the value they are | |
34640 | displaying changes. There are always 10 horizontal lines in each chart; the | |
34641 | title string indicates the value of each division when it is greater than one. | |
34642 | For example, "x2" means that each division represents a value of 2. | |
34643 | ||
34644 | It is also possible to have a stripchart which shows the percentage fullness of | |
34645 | a particular disk partition, which is useful when local deliveries are confined | |
34646 | to a single partition. | |
34647 | ||
34648 | This relies on the availability of the statvfs() function or equivalent in the | |
34649 | operating system. Most, but not all versions of Unix that support Exim have | |
34650 | this. For this particular stripchart, the top of the chart always represents | |
34651 | 100%, and the scale is given as "x10%". This chart is configured by setting | |
34652 | SIZE_STRIPCHART and (optionally) SIZE_STRIPCHART_NAME in the Local/eximon.conf | |
34653 | file. | |
34654 | ||
34655 | ||
2813c06e | 34656 | 54.3 Main action buttons |
420a0d19 CE |
34657 | ------------------------ |
34658 | ||
34659 | Below the stripcharts there is an action button for quitting the monitor. Next | |
34660 | to this is another button marked "Size". They are placed here so that shrinking | |
34661 | the window to its default minimum size leaves just the queue count stripchart | |
34662 | and these two buttons visible. Pressing the "Size" button causes the window to | |
34663 | expand to its maximum size, unless it is already at the maximum, in which case | |
34664 | it is reduced to its minimum. | |
34665 | ||
34666 | When expanding to the maximum, if the window cannot be fully seen where it | |
34667 | currently is, it is moved back to where it was the last time it was at full | |
34668 | size. When it is expanding from its minimum size, the old position is | |
34669 | remembered, and next time it is reduced to the minimum it is moved back there. | |
34670 | ||
34671 | The idea is that you can keep a reduced window just showing one or two | |
34672 | stripcharts at a convenient place on your screen, easily expand it to show the | |
34673 | full window when required, and just as easily put it back to what it was. The | |
34674 | idea is copied from what the twm window manager does for its f.fullzoom action. | |
34675 | The minimum size of the window can be changed by setting the MIN_HEIGHT and | |
34676 | MIN_WIDTH values in Local/eximon.conf. | |
34677 | ||
34678 | Normally, the monitor starts up with the window at its full size, but it can be | |
34679 | built so that it starts up with the window at its smallest size, by setting | |
34680 | START_SMALL=yes in Local/eximon.conf. | |
34681 | ||
34682 | ||
2813c06e | 34683 | 54.4 The log display |
420a0d19 CE |
34684 | -------------------- |
34685 | ||
34686 | The second section of the window is an area in which a display of the tail of | |
34687 | the main log is maintained. To save space on the screen, the timestamp on each | |
34688 | log line is shortened by removing the date and, if log_timezone is set, the | |
34689 | timezone. The log tail is not available when the only destination for logging | |
34690 | data is syslog, unless the syslog lines are routed to a local file whose name | |
34691 | is passed to eximon via the EXIMON_LOG_FILE_PATH environment variable. | |
34692 | ||
34693 | The log sub-window has a scroll bar at its lefthand side which can be used to | |
34694 | move back to look at earlier text, and the up and down arrow keys also have a | |
34695 | scrolling effect. The amount of log that is kept depends on the setting of | |
34696 | LOG_BUFFER in Local/eximon.conf, which specifies the amount of memory to use. | |
34697 | When this is full, the earlier 50% of data is discarded - this is much more | |
34698 | efficient than throwing it away line by line. The sub-window also has a | |
34699 | horizontal scroll bar for accessing the ends of long log lines. This is the | |
34700 | only means of horizontal scrolling; the right and left arrow keys are not | |
34701 | available. Text can be cut from this part of the window using the mouse in the | |
34702 | normal way. The size of this subwindow is controlled by parameters in the | |
34703 | configuration file Local/eximon.conf. | |
34704 | ||
34705 | Searches of the text in the log window can be carried out by means of the ^R | |
34706 | and ^S keystrokes, which default to a reverse and a forward search, | |
34707 | respectively. The search covers only the text that is displayed in the window. | |
34708 | It cannot go further back up the log. | |
34709 | ||
34710 | The point from which the search starts is indicated by a caret marker. This is | |
34711 | normally at the end of the text in the window, but can be positioned explicitly | |
34712 | by pointing and clicking with the left mouse button, and is moved automatically | |
34713 | by a successful search. If new text arrives in the window when it is scrolled | |
34714 | back, the caret remains where it is, but if the window is not scrolled back, | |
34715 | the caret is moved to the end of the new text. | |
34716 | ||
34717 | Pressing ^R or ^S pops up a window into which the search text can be typed. | |
34718 | There are buttons for selecting forward or reverse searching, for carrying out | |
34719 | the search, and for cancelling. If the "Search" button is pressed, the search | |
34720 | happens and the window remains so that further searches can be done. If the | |
34721 | "Return" key is pressed, a single search is done and the window is closed. If ^ | |
34722 | C is typed the search is cancelled. | |
34723 | ||
34724 | The searching facility is implemented using the facilities of the Athena text | |
34725 | widget. By default this pops up a window containing both "search" and "replace" | |
34726 | options. In order to suppress the unwanted "replace" portion for eximon, a | |
34727 | modified version of the TextPop widget is distributed with Exim. However, the | |
34728 | linkers in BSDI and HP-UX seem unable to handle an externally provided version | |
34729 | of TextPop when the remaining parts of the text widget come from the standard | |
34730 | libraries. The compile-time option EXIMON_TEXTPOP can be unset to cut out the | |
34731 | modified TextPop, making it possible to build Eximon on these systems, at the | |
34732 | expense of having unwanted items in the search popup window. | |
34733 | ||
34734 | ||
2813c06e | 34735 | 54.5 The queue display |
420a0d19 CE |
34736 | ---------------------- |
34737 | ||
34738 | The bottom section of the monitor window contains a list of all messages that | |
34739 | are on the queue, which includes those currently being received or delivered, | |
34740 | as well as those awaiting delivery. The size of this subwindow is controlled by | |
34741 | parameters in the configuration file Local/eximon.conf, and the frequency at | |
34742 | which it is updated is controlled by another parameter in the same file - the | |
34743 | default is 5 minutes, since queue scans can be quite expensive. However, there | |
34744 | is an "Update" action button just above the display which can be used to force | |
34745 | an update of the queue display at any time. | |
34746 | ||
34747 | When a host is down for some time, a lot of pending mail can build up for it, | |
34748 | and this can make it hard to deal with other messages on the queue. To help | |
34749 | with this situation there is a button next to "Update" called "Hide". If | |
34750 | pressed, a dialogue box called "Hide addresses ending with" is put up. If you | |
34751 | type anything in here and press "Return", the text is added to a chain of such | |
34752 | texts, and if every undelivered address in a message matches at least one of | |
34753 | the texts, the message is not displayed. | |
34754 | ||
34755 | If there is an address that does not match any of the texts, all the addresses | |
34756 | are displayed as normal. The matching happens on the ends of addresses so, for | |
34757 | example, cam.ac.uk specifies all addresses in Cambridge, while | |
34758 | xxx@foo.com.example specifies just one specific address. When any hiding has | |
34759 | been set up, a button called "Unhide" is displayed. If pressed, it cancels all | |
34760 | hiding. Also, to ensure that hidden messages do not get forgotten, a hide | |
34761 | request is automatically cancelled after one hour. | |
34762 | ||
34763 | While the dialogue box is displayed, you can't press any buttons or do anything | |
34764 | else to the monitor window. For this reason, if you want to cut text from the | |
34765 | queue display to use in the dialogue box, you have to do the cutting before | |
34766 | pressing the "Hide" button. | |
34767 | ||
34768 | The queue display contains, for each unhidden queued message, the length of | |
34769 | time it has been on the queue, the size of the message, the message id, the | |
34770 | message sender, and the first undelivered recipient, all on one line. If it is | |
34771 | a bounce message, the sender is shown as "<>". If there is more than one | |
34772 | recipient to which the message has not yet been delivered, subsequent ones are | |
34773 | listed on additional lines, up to a maximum configured number, following which | |
34774 | an ellipsis is displayed. Recipients that have already received the message are | |
34775 | not shown. | |
34776 | ||
34777 | If a message is frozen, an asterisk is displayed at the left-hand side. | |
34778 | ||
34779 | The queue display has a vertical scroll bar, and can also be scrolled by means | |
34780 | of the arrow keys. Text can be cut from it using the mouse in the normal way. | |
34781 | The text searching facilities, as described above for the log window, are also | |
34782 | available, but the caret is always moved to the end of the text when the queue | |
34783 | display is updated. | |
34784 | ||
34785 | ||
2813c06e | 34786 | 54.6 The queue menu |
420a0d19 CE |
34787 | ------------------- |
34788 | ||
34789 | If the shift key is held down and the left button is clicked when the mouse | |
34790 | pointer is over the text for any message, an action menu pops up, and the first | |
34791 | line of the queue display for the message is highlighted. This does not affect | |
34792 | any selected text. | |
34793 | ||
34794 | If you want to use some other event for popping up the menu, you can set the | |
34795 | MENU_EVENT parameter in Local/eximon.conf to change the default, or set | |
34796 | EXIMON_MENU_EVENT in the environment before starting the monitor. The value set | |
34797 | in this parameter is a standard X event description. For example, to run eximon | |
34798 | using ctrl rather than shift you could use | |
34799 | ||
34800 | EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon | |
34801 | ||
34802 | The title of the menu is the message id, and it contains entries which act as | |
34803 | follows: | |
34804 | ||
34805 | * message log: The contents of the message log for the message are displayed | |
34806 | in a new text window. | |
34807 | ||
34808 | * headers: Information from the spool file that contains the envelope | |
2813c06e | 34809 | information and headers is displayed in a new text window. See chapter 56 |
420a0d19 CE |
34810 | for a description of the format of spool files. |
34811 | ||
34812 | * body: The contents of the spool file containing the body of the message are | |
34813 | displayed in a new text window. There is a default limit of 20,000 bytes to | |
34814 | the amount of data displayed. This can be changed by setting the BODY_MAX | |
34815 | option at compile time, or the EXIMON_BODY_MAX option at run time. | |
34816 | ||
34817 | * deliver message: A call to Exim is made using the -M option to request | |
34818 | delivery of the message. This causes an automatic thaw if the message is | |
34819 | frozen. The -v option is also set, and the output from Exim is displayed in | |
34820 | a new text window. The delivery is run in a separate process, to avoid | |
34821 | holding up the monitor while the delivery proceeds. | |
34822 | ||
34823 | * freeze message: A call to Exim is made using the -Mf option to request that | |
34824 | the message be frozen. | |
34825 | ||
34826 | * thaw message: A call to Exim is made using the -Mt option to request that | |
34827 | the message be thawed. | |
34828 | ||
34829 | * give up on msg: A call to Exim is made using the -Mg option to request that | |
34830 | Exim gives up trying to deliver the message. A bounce message is generated | |
34831 | for any remaining undelivered addresses. | |
34832 | ||
34833 | * remove message: A call to Exim is made using the -Mrm option to request | |
34834 | that the message be deleted from the system without generating a bounce | |
34835 | message. | |
34836 | ||
34837 | * add recipient: A dialog box is displayed into which a recipient address can | |
34838 | be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter | |
34839 | is set in Local/eximon.conf, the address is qualified with that domain. | |
34840 | Otherwise it must be entered as a fully qualified address. Pressing RETURN | |
34841 | causes a call to Exim to be made using the -Mar option to request that an | |
34842 | additional recipient be added to the message, unless the entry box is | |
34843 | empty, in which case no action is taken. | |
34844 | ||
34845 | * mark delivered: A dialog box is displayed into which a recipient address | |
34846 | can be typed. If the address is not qualified and the QUALIFY_DOMAIN | |
34847 | parameter is set in Local/eximon.conf, the address is qualified with that | |
34848 | domain. Otherwise it must be entered as a fully qualified address. Pressing | |
34849 | RETURN causes a call to Exim to be made using the -Mmd option to mark the | |
34850 | given recipient address as already delivered, unless the entry box is | |
34851 | empty, in which case no action is taken. | |
34852 | ||
34853 | * mark all delivered: A call to Exim is made using the -Mmad option to mark | |
34854 | all recipient addresses as already delivered. | |
34855 | ||
34856 | * edit sender: A dialog box is displayed initialized with the current | |
34857 | sender's address. Pressing RETURN causes a call to Exim to be made using | |
34858 | the -Mes option to replace the sender address, unless the entry box is | |
34859 | empty, in which case no action is taken. If you want to set an empty sender | |
34860 | (as in bounce messages), you must specify it as "<>". Otherwise, if the | |
34861 | address is not qualified and the QUALIFY_DOMAIN parameter is set in Local/ | |
34862 | eximon.conf, the address is qualified with that domain. | |
34863 | ||
34864 | When a delivery is forced, a window showing the -v output is displayed. In | |
34865 | other cases when a call to Exim is made, if there is any output from Exim (in | |
34866 | particular, if the command fails) a window containing the command and the | |
34867 | output is displayed. Otherwise, the results of the action are normally apparent | |
34868 | from the log and queue displays. However, if you set ACTION_OUTPUT=yes in Local | |
34869 | /eximon.conf, a window showing the Exim command is always opened, even if no | |
34870 | output is generated. | |
34871 | ||
34872 | The queue display is automatically updated for actions such as freezing and | |
34873 | thawing, unless ACTION_QUEUE_UPDATE=no has been set in Local/eximon.conf. In | |
34874 | this case the "Update" button has to be used to force an update of the display | |
34875 | after one of these actions. | |
34876 | ||
34877 | In any text window that is displayed as result of a menu action, the normal | |
34878 | cut-and-paste facility is available, and searching can be carried out using ^R | |
34879 | and ^S, as described above for the log tail window. | |
34880 | ||
34881 | ||
34882 | ||
34883 | =============================================================================== | |
2813c06e | 34884 | 55. SECURITY CONSIDERATIONS |
420a0d19 CE |
34885 | |
34886 | This chapter discusses a number of issues concerned with security, some of | |
34887 | which are also covered in other parts of this manual. | |
34888 | ||
34889 | For reasons that this author does not understand, some people have promoted | |
34890 | Exim as a "particularly secure" mailer. Perhaps it is because of the existence | |
34891 | of this chapter in the documentation. However, the intent of the chapter is | |
34892 | simply to describe the way Exim works in relation to certain security concerns, | |
34893 | not to make any specific claims about the effectiveness of its security as | |
34894 | compared with other MTAs. | |
34895 | ||
34896 | What follows is a description of the way Exim is supposed to be. Best efforts | |
34897 | have been made to try to ensure that the code agrees with the theory, but an | |
34898 | absence of bugs can never be guaranteed. Any that are reported will get fixed | |
34899 | as soon as possible. | |
34900 | ||
34901 | ||
2813c06e | 34902 | 55.1 Building a more "hardened" Exim |
420a0d19 CE |
34903 | ------------------------------------ |
34904 | ||
34905 | There are a number of build-time options that can be set in Local/Makefile to | |
34906 | create Exim binaries that are "harder" to attack, in particular by a rogue Exim | |
34907 | administrator who does not have the root password, or by someone who has | |
34908 | penetrated the Exim (but not the root) account. These options are as follows: | |
34909 | ||
34910 | * ALT_CONFIG_PREFIX can be set to a string that is required to match the | |
34911 | start of any file names used with the -C option. When it is set, these file | |
34912 | names are also not allowed to contain the sequence "/../". (However, if the | |
34913 | value of the -C option is identical to the value of CONFIGURE_FILE in Local | |
34914 | /Makefile, Exim ignores -C and proceeds as usual.) There is no default | |
34915 | setting for ALT_CONFIG_PREFIX. | |
34916 | ||
34917 | If the permitted configuration files are confined to a directory to which | |
34918 | only root has access, this guards against someone who has broken into the | |
34919 | Exim account from running a privileged Exim with an arbitrary configuration | |
34920 | file, and using it to break into other accounts. | |
34921 | ||
34922 | * If a non-trusted configuration file (i.e. not the default configuration | |
34923 | file or one which is trusted by virtue of being listed in the | |
34924 | TRUSTED_CONFIG_LIST file) is specified with -C, or if macros are given with | |
34925 | -D (but see the next item), then root privilege is retained only if the | |
34926 | caller of Exim is root. This locks out the possibility of testing a | |
34927 | configuration using -C right through message reception and delivery, even | |
34928 | if the caller is root. The reception works, but by that time, Exim is | |
34929 | running as the Exim user, so when it re-execs to regain privilege for the | |
34930 | delivery, the use of -C causes privilege to be lost. However, root can test | |
34931 | reception and delivery using two separate commands. | |
34932 | ||
34933 | * The WHITELIST_D_MACROS build option declares some macros to be safe to | |
34934 | override with -D if the real uid is one of root, the Exim run-time user or | |
34935 | the CONFIGURE_OWNER, if defined. The potential impact of this option is | |
34936 | limited by requiring the run-time value supplied to -D to match a regex | |
34937 | that errs on the restrictive side. Requiring build-time selection of safe | |
34938 | macros is onerous but this option is intended solely as a transition | |
34939 | mechanism to permit previously-working configurations to continue to work | |
34940 | after release 4.73. | |
34941 | ||
34942 | * If DISABLE_D_OPTION is defined, the use of the -D command line option is | |
34943 | disabled. | |
34944 | ||
34945 | * FIXED_NEVER_USERS can be set to a colon-separated list of users that are | |
34946 | never to be used for any deliveries. This is like the never_users runtime | |
34947 | option, but it cannot be overridden; the runtime option adds additional | |
34948 | users to the list. The default setting is "root"; this prevents a non-root | |
34949 | user who is permitted to modify the runtime file from using Exim as a way | |
34950 | to get root. | |
34951 | ||
34952 | ||
2813c06e | 34953 | 55.2 Root privilege |
420a0d19 CE |
34954 | ------------------- |
34955 | ||
34956 | The Exim binary is normally setuid to root, which means that it gains root | |
34957 | privilege (runs as root) when it starts execution. In some special cases (for | |
34958 | example, when the daemon is not in use and there are no local deliveries), it | |
34959 | may be possible to run Exim setuid to some user other than root. This is | |
34960 | discussed in the next section. However, in most installations, root privilege | |
34961 | is required for two things: | |
34962 | ||
34963 | * To set up a socket connected to the standard SMTP port (25) when | |
34964 | initialising the listening daemon. If Exim is run from inetd, this | |
34965 | privileged action is not required. | |
34966 | ||
34967 | * To be able to change uid and gid in order to read users' .forward files and | |
34968 | perform local deliveries as the receiving user or as specified in the | |
34969 | configuration. | |
34970 | ||
34971 | It is not necessary to be root to do any of the other things Exim does, such as | |
34972 | receiving messages and delivering them externally over SMTP, and it is | |
34973 | obviously more secure if Exim does not run as root except when necessary. For | |
34974 | this reason, a user and group for Exim to use must be defined in Local/Makefile | |
34975 | . These are known as "the Exim user" and "the Exim group". Their values can be | |
34976 | changed by the run time configuration, though this is not recommended. Often a | |
34977 | user called exim is used, but some sites use mail or another user name | |
34978 | altogether. | |
34979 | ||
34980 | Exim uses setuid() whenever it gives up root privilege. This is a permanent | |
34981 | abdication; the process cannot regain root afterwards. Prior to release 4.00, | |
34982 | seteuid() was used in some circumstances, but this is no longer the case. | |
34983 | ||
34984 | After a new Exim process has interpreted its command line options, it changes | |
34985 | uid and gid in the following cases: | |
34986 | ||
34987 | * If the -C option is used to specify an alternate configuration file, or if | |
34988 | the -D option is used to define macro values for the configuration, and the | |
34989 | calling process is not running as root, the uid and gid are changed to | |
34990 | those of the calling process. However, if DISABLE_D_OPTION is defined in | |
34991 | Local/Makefile, the -D option may not be used at all. If WHITELIST_D_MACROS | |
34992 | is defined in Local/Makefile, then some macro values can be supplied if the | |
34993 | calling process is running as root, the Exim run-time user or | |
34994 | CONFIGURE_OWNER, if defined. | |
34995 | ||
34996 | * If the expansion test option (-be) or one of the filter testing options ( | |
34997 | -bf or -bF) are used, the uid and gid are changed to those of the calling | |
34998 | process. | |
34999 | ||
35000 | * If the process is not a daemon process or a queue runner process or a | |
35001 | delivery process or a process for testing address routing (started with -bt | |
35002 | ), the uid and gid are changed to the Exim user and group. This means that | |
35003 | Exim always runs under its own uid and gid when receiving messages. This | |
35004 | also applies when testing address verification (the -bv option) and testing | |
35005 | incoming message policy controls (the -bh option). | |
35006 | ||
35007 | * For a daemon, queue runner, delivery, or address testing process, the uid | |
35008 | remains as root at this stage, but the gid is changed to the Exim group. | |
35009 | ||
35010 | The processes that initially retain root privilege behave as follows: | |
35011 | ||
35012 | * A daemon process changes the gid to the Exim group and the uid to the Exim | |
35013 | user after setting up one or more listening sockets. The initgroups() | |
35014 | function is called, so that if the Exim user is in any additional groups, | |
35015 | they will be used during message reception. | |
35016 | ||
35017 | * A queue runner process retains root privilege throughout its execution. Its | |
35018 | job is to fork a controlled sequence of delivery processes. | |
35019 | ||
35020 | * A delivery process retains root privilege throughout most of its execution, | |
35021 | but any actual deliveries (that is, the transports themselves) are run in | |
35022 | subprocesses which always change to a non-root uid and gid. For local | |
35023 | deliveries this is typically the uid and gid of the owner of the mailbox; | |
35024 | for remote deliveries, the Exim uid and gid are used. Once all the delivery | |
35025 | subprocesses have been run, a delivery process changes to the Exim uid and | |
35026 | gid while doing post-delivery tidying up such as updating the retry | |
35027 | database and generating bounce and warning messages. | |
35028 | ||
35029 | While the recipient addresses in a message are being routed, the delivery | |
35030 | process runs as root. However, if a user's filter file has to be processed, | |
35031 | this is done in a subprocess that runs under the individual user's uid and | |
35032 | gid. A system filter is run as root unless system_filter_user is set. | |
35033 | ||
35034 | * A process that is testing addresses (the -bt option) runs as root so that | |
35035 | the routing is done in the same environment as a message delivery. | |
35036 | ||
35037 | ||
2813c06e | 35038 | 55.3 Running Exim without privilege |
420a0d19 CE |
35039 | ----------------------------------- |
35040 | ||
35041 | Some installations like to run Exim in an unprivileged state for more of its | |
35042 | operation, for added security. Support for this mode of operation is provided | |
35043 | by the global option deliver_drop_privilege. When this is set, the uid and gid | |
35044 | are changed to the Exim user and group at the start of a delivery process (and | |
35045 | also queue runner and address testing processes). This means that address | |
35046 | routing is no longer run as root, and the deliveries themselves cannot change | |
35047 | to any other uid. | |
35048 | ||
35049 | Leaving the binary setuid to root, but setting deliver_drop_privilege means | |
35050 | that the daemon can still be started in the usual way, and it can respond | |
35051 | correctly to SIGHUP because the re-invocation regains root privilege. | |
35052 | ||
35053 | An alternative approach is to make Exim setuid to the Exim user and also setgid | |
35054 | to the Exim group. If you do this, the daemon must be started from a root | |
35055 | process. (Calling Exim from a root process makes it behave in the way it does | |
35056 | when it is setuid root.) However, the daemon cannot restart itself after a | |
35057 | SIGHUP signal because it cannot regain privilege. | |
35058 | ||
35059 | It is still useful to set deliver_drop_privilege in this case, because it stops | |
35060 | Exim from trying to re-invoke itself to do a delivery after a message has been | |
35061 | received. Such a re-invocation is a waste of resources because it has no | |
35062 | effect. | |
35063 | ||
35064 | If restarting the daemon is not an issue (for example, if mua_wrapper is set, | |
35065 | or inetd is being used instead of a daemon), having the binary setuid to the | |
35066 | Exim user seems a clean approach, but there is one complication: | |
35067 | ||
35068 | In this style of operation, Exim is running with the real uid and gid set to | |
35069 | those of the calling process, and the effective uid/gid set to Exim's values. | |
35070 | Ideally, any association with the calling process' uid/gid should be dropped, | |
35071 | that is, the real uid/gid should be reset to the effective values so as to | |
35072 | discard any privileges that the caller may have. While some operating systems | |
35073 | have a function that permits this action for a non-root effective uid, quite a | |
35074 | number of them do not. Because of this lack of standardization, Exim does not | |
35075 | address this problem at this time. | |
35076 | ||
35077 | For this reason, the recommended approach for "mostly unprivileged" running is | |
35078 | to keep the Exim binary setuid to root, and to set deliver_drop_privilege. This | |
35079 | also has the advantage of allowing a daemon to be used in the most | |
35080 | straightforward way. | |
35081 | ||
35082 | If you configure Exim not to run delivery processes as root, there are a number | |
35083 | of restrictions on what you can do: | |
35084 | ||
35085 | * You can deliver only as the Exim user/group. You should explicitly use the | |
35086 | user and group options to override routers or local transports that | |
35087 | normally deliver as the recipient. This makes sure that configurations that | |
35088 | work in this mode function the same way in normal mode. Any implicit or | |
35089 | explicit specification of another user causes an error. | |
35090 | ||
35091 | * Use of .forward files is severely restricted, such that it is usually not | |
35092 | worthwhile to include them in the configuration. | |
35093 | ||
35094 | * Users who wish to use .forward would have to make their home directory and | |
35095 | the file itself accessible to the Exim user. Pipe and append-to-file | |
35096 | entries, and their equivalents in Exim filters, cannot be used. While they | |
35097 | could be enabled in the Exim user's name, that would be insecure and not | |
35098 | very useful. | |
35099 | ||
35100 | * Unless the local user mailboxes are all owned by the Exim user (possible in | |
35101 | some POP3 or IMAP-only environments): | |
35102 | ||
35103 | 1. They must be owned by the Exim group and be writeable by that group. | |
35104 | This implies you must set mode in the appendfile configuration, as well | |
35105 | as the mode of the mailbox files themselves. | |
35106 | ||
35107 | 2. You must set no_check_owner, since most or all of the files will not be | |
35108 | owned by the Exim user. | |
35109 | ||
35110 | 3. You must set file_must_exist, because Exim cannot set the owner | |
35111 | correctly on a newly created mailbox when unprivileged. This also | |
35112 | implies that new mailboxes need to be created manually. | |
35113 | ||
35114 | These restrictions severely restrict what can be done in local deliveries. | |
35115 | However, there are no restrictions on remote deliveries. If you are running a | |
35116 | gateway host that does no local deliveries, setting deliver_drop_privilege | |
35117 | gives more security at essentially no cost. | |
35118 | ||
2813c06e | 35119 | If you are using the mua_wrapper facility (see chapter 51), |
420a0d19 CE |
35120 | deliver_drop_privilege is forced to be true. |
35121 | ||
35122 | ||
2813c06e | 35123 | 55.4 Delivering to local files |
420a0d19 CE |
35124 | ------------------------------ |
35125 | ||
35126 | Full details of the checks applied by appendfile before it writes to a file are | |
35127 | given in chapter 26. | |
35128 | ||
35129 | ||
2813c06e | 35130 | 55.5 Running local commands |
420a0d19 CE |
35131 | --------------------------- |
35132 | ||
35133 | There are a number of ways in which an administrator can configure Exim to run | |
35134 | commands based upon received, untrustworthy, data. Further, in some | |
35135 | configurations a user who can control a .forward file can also arrange to run | |
35136 | commands. Configuration to check includes, but is not limited to: | |
35137 | ||
35138 | * Use of use_shell in the pipe transport: various forms of shell command | |
35139 | injection may be possible with this option present. It is dangerous and | |
35140 | should be used only with considerable caution. Consider constraints which | |
35141 | whitelist allowed characters in a variable which is to be used in a pipe | |
35142 | transport that has use_shell enabled. | |
35143 | ||
35144 | * A number of options such as forbid_filter_run, forbid_filter_perl, | |
35145 | forbid_filter_dlfunc and so forth which restrict facilities available to | |
35146 | .forward files in a redirect router. If Exim is running on a central mail | |
35147 | hub to which ordinary users do not have shell access, but home directories | |
35148 | are NFS mounted (for instance) then administrators should review the list | |
35149 | of these forbid options available, and should bear in mind that the options | |
35150 | that may need forbidding can change as new features are added between | |
35151 | releases. | |
35152 | ||
35153 | * The ${run...} expansion item does not use a shell by default, but | |
35154 | administrators can configure use of /bin/sh as part of the command. Such | |
35155 | invocations should be viewed with prejudicial suspicion. | |
35156 | ||
35157 | * Administrators who use embedded Perl are advised to explore how Perl's | |
35158 | taint checking might apply to their usage. | |
35159 | ||
2813c06e | 35160 | * Use of ${expand...} is somewhat analogous to shell's eval builtin and |
420a0d19 CE |
35161 | administrators are well advised to view its use with suspicion, in case |
35162 | (for instance) it allows a local-part to contain embedded Exim directives. | |
35163 | ||
35164 | * Use of ${match_local_part...} and friends becomes more dangerous if Exim | |
35165 | was built with EXPAND_LISTMATCH_RHS defined: the second string in each can | |
35166 | reference arbitrary lists and files, rather than just being a list of | |
35167 | opaque strings. The EXPAND_LISTMATCH_RHS option was added and set false by | |
35168 | default because of real-world security vulnerabilities caused by its use | |
35169 | with untrustworthy data injected in, for SQL injection attacks. Consider | |
35170 | the use of the inlisti expansion condition instead. | |
35171 | ||
35172 | ||
2813c06e | 35173 | 55.6 Trust in configuration data |
420a0d19 CE |
35174 | -------------------------------- |
35175 | ||
35176 | If configuration data for Exim can come from untrustworthy sources, there are | |
35177 | some issues to be aware of: | |
35178 | ||
35179 | * Use of ${expand...} may provide a path for shell injection attacks. | |
35180 | ||
35181 | * Letting untrusted data provide a regular expression is unwise. | |
35182 | ||
35183 | * Using ${match...} to apply a fixed regular expression against untrusted | |
35184 | data may result in pathological behaviour within PCRE. Be aware of what | |
35185 | "backtracking" means and consider options for being more strict with a | |
35186 | regular expression. Avenues to explore include limiting what can match | |
35187 | (avoiding "." when "[a-z0-9]" or other character class will do), use of | |
35188 | atomic grouping and possessive quantifiers or just not using regular | |
35189 | expressions against untrusted data. | |
35190 | ||
35191 | * It can be important to correctly use ${quote:...}, ${quote_local_part:...} | |
35192 | and ${quote_<lookup-type>:...} expansion items to ensure that data is | |
35193 | correctly constructed. | |
35194 | ||
35195 | * Some lookups might return multiple results, even though normal usage is | |
35196 | only expected to yield one result. | |
35197 | ||
35198 | ||
2813c06e | 35199 | 55.7 IPv4 source routing |
420a0d19 CE |
35200 | ------------------------ |
35201 | ||
35202 | Many operating systems suppress IP source-routed packets in the kernel, but | |
35203 | some cannot be made to do this, so Exim does its own check. It logs incoming | |
35204 | IPv4 source-routed TCP calls, and then drops them. Things are all different in | |
35205 | IPv6. No special checking is currently done. | |
35206 | ||
35207 | ||
2813c06e | 35208 | 55.8 The VRFY, EXPN, and ETRN commands in SMTP |
420a0d19 CE |
35209 | ---------------------------------------------- |
35210 | ||
35211 | Support for these SMTP commands is disabled by default. If required, they can | |
35212 | be enabled by defining suitable ACLs. | |
35213 | ||
35214 | ||
2813c06e | 35215 | 55.9 Privileged users |
420a0d19 CE |
35216 | --------------------- |
35217 | ||
35218 | Exim recognizes two sets of users with special privileges. Trusted users are | |
35219 | able to submit new messages to Exim locally, but supply their own sender | |
35220 | addresses and information about a sending host. For other users submitting | |
35221 | local messages, Exim sets up the sender address from the uid, and doesn't | |
35222 | permit a remote host to be specified. | |
35223 | ||
35224 | However, an untrusted user is permitted to use the -f command line option in | |
35225 | the special form -f <> to indicate that a delivery failure for the message | |
35226 | should not cause an error report. This affects the message's envelope, but it | |
35227 | does not affect the Sender: header. Untrusted users may also be permitted to | |
35228 | use specific forms of address with the -f option by setting the | |
35229 | untrusted_set_sender option. | |
35230 | ||
35231 | Trusted users are used to run processes that receive mail messages from some | |
35232 | other mail domain and pass them on to Exim for delivery either locally, or over | |
35233 | the Internet. Exim trusts a caller that is running as root, as the Exim user, | |
35234 | as any user listed in the trusted_users configuration option, or under any | |
35235 | group listed in the trusted_groups option. | |
35236 | ||
35237 | Admin users are permitted to do things to the messages on Exim's queue. They | |
35238 | can freeze or thaw messages, cause them to be returned to their senders, remove | |
35239 | them entirely, or modify them in various ways. In addition, admin users can run | |
35240 | the Exim monitor and see all the information it is capable of providing, which | |
35241 | includes the contents of files on the spool. | |
35242 | ||
35243 | By default, the use of the -M and -q options to cause Exim to attempt delivery | |
35244 | of messages on its queue is restricted to admin users. This restriction can be | |
35245 | relaxed by setting the no_prod_requires_admin option. Similarly, the use of -bp | |
35246 | (and its variants) to list the contents of the queue is also restricted to | |
35247 | admin users. This restriction can be relaxed by setting | |
35248 | no_queue_list_requires_admin. | |
35249 | ||
35250 | Exim recognizes an admin user if the calling process is running as root or as | |
35251 | the Exim user or if any of the groups associated with the calling process is | |
35252 | the Exim group. It is not necessary actually to be running under the Exim | |
35253 | group. However, if admin users who are not root or the Exim user are to access | |
35254 | the contents of files on the spool via the Exim monitor (which runs | |
35255 | unprivileged), Exim must be built to allow group read access to its spool | |
35256 | files. | |
35257 | ||
35258 | ||
2813c06e | 35259 | 55.10 Spool files |
420a0d19 CE |
35260 | ----------------- |
35261 | ||
35262 | Exim's spool directory and everything it contains is owned by the Exim user and | |
35263 | set to the Exim group. The mode for spool files is defined in the Local/ | |
35264 | Makefile configuration file, and defaults to 0640. This means that any user who | |
35265 | is a member of the Exim group can access these files. | |
35266 | ||
35267 | ||
2813c06e | 35268 | 55.11 Use of argv[0] |
420a0d19 CE |
35269 | -------------------- |
35270 | ||
35271 | Exim examines the last component of argv[0], and if it matches one of a set of | |
35272 | specific strings, Exim assumes certain options. For example, calling Exim with | |
35273 | the last component of argv[0] set to "rsmtp" is exactly equivalent to calling | |
35274 | it with the option -bS. There are no security implications in this. | |
35275 | ||
35276 | ||
2813c06e | 35277 | 55.12 Use of %f formatting |
420a0d19 CE |
35278 | -------------------------- |
35279 | ||
35280 | The only use made of "%f" by Exim is in formatting load average values. These | |
35281 | are actually stored in integer variables as 1000 times the load average. | |
35282 | Consequently, their range is limited and so therefore is the length of the | |
35283 | converted output. | |
35284 | ||
35285 | ||
2813c06e | 35286 | 55.13 Embedded Exim path |
420a0d19 CE |
35287 | ------------------------ |
35288 | ||
35289 | Exim uses its own path name, which is embedded in the code, only when it needs | |
35290 | to re-exec in order to regain root privilege. Therefore, it is not root when it | |
35291 | does so. If some bug allowed the path to get overwritten, it would lead to an | |
35292 | arbitrary program's being run as exim, not as root. | |
35293 | ||
35294 | ||
2813c06e | 35295 | 55.14 Dynamic module directory |
420a0d19 CE |
35296 | ------------------------------ |
35297 | ||
35298 | Any dynamically loadable modules must be installed into the directory defined | |
35299 | in "LOOKUP_MODULE_DIR" in Local/Makefile for Exim to permit loading it. | |
35300 | ||
35301 | ||
2813c06e | 35302 | 55.15 Use of sprintf() |
420a0d19 CE |
35303 | ---------------------- |
35304 | ||
35305 | A large number of occurrences of "sprintf" in the code are actually calls to | |
35306 | string_sprintf(), a function that returns the result in malloc'd store. The | |
35307 | intermediate formatting is done into a large fixed buffer by a function that | |
35308 | runs through the format string itself, and checks the length of each conversion | |
35309 | before performing it, thus preventing buffer overruns. | |
35310 | ||
35311 | The remaining uses of sprintf() happen in controlled circumstances where the | |
35312 | output buffer is known to be sufficiently long to contain the converted string. | |
35313 | ||
35314 | ||
2813c06e | 35315 | 55.16 Use of debug_printf() and log_write() |
420a0d19 CE |
35316 | ------------------------------------------- |
35317 | ||
35318 | Arbitrary strings are passed to both these functions, but they do their | |
35319 | formatting by calling the function string_vformat(), which runs through the | |
35320 | format string itself, and checks the length of each conversion. | |
35321 | ||
35322 | ||
2813c06e | 35323 | 55.17 Use of strcat() and strcpy() |
420a0d19 CE |
35324 | ---------------------------------- |
35325 | ||
35326 | These are used only in cases where the output buffer is known to be large | |
35327 | enough to hold the result. | |
35328 | ||
35329 | ||
35330 | ||
35331 | =============================================================================== | |
2813c06e | 35332 | 56. FORMAT OF SPOOL FILES |
420a0d19 CE |
35333 | |
35334 | A message on Exim's queue consists of two files, whose names are the message id | |
35335 | followed by -D and -H, respectively. The data portion of the message is kept in | |
35336 | the -D file on its own. The message's envelope, status, and headers are all | |
35337 | kept in the -H file, whose format is described in this chapter. Each of these | |
35338 | two files contains the final component of its own name as its first line. This | |
35339 | is insurance against disk crashes where the directory is lost but the files | |
35340 | themselves are recoverable. | |
35341 | ||
35342 | Some people are tempted into editing -D files in order to modify messages. You | |
35343 | need to be extremely careful if you do this; it is not recommended and you are | |
35344 | on your own if you do it. Here are some of the pitfalls: | |
35345 | ||
35346 | * You must ensure that Exim does not try to deliver the message while you are | |
35347 | fiddling with it. The safest way is to take out a write lock on the -D | |
35348 | file, which is what Exim itself does, using fcntl(). If you update the file | |
35349 | in place, the lock will be retained. If you write a new file and rename it, | |
35350 | the lock will be lost at the instant of rename. | |
35351 | ||
35352 | * If you change the number of lines in the file, the value of $body_linecount | |
2813c06e CE |
35353 | , which is stored in the -H file, will be incorrect and can cause |
35354 | incomplete transmission of messages or undeliverable messages. | |
420a0d19 CE |
35355 | |
35356 | * If the message is in MIME format, you must take care not to break it. | |
35357 | ||
35358 | * If the message is cryptographically signed, any change will invalidate the | |
35359 | signature. | |
35360 | ||
35361 | All in all, modifying -D files is fraught with danger. | |
35362 | ||
35363 | Files whose names end with -J may also be seen in the input directory (or its | |
35364 | subdirectories when split_spool_directory is set). These are journal files, | |
35365 | used to record addresses to which the message has been delivered during the | |
35366 | course of a delivery attempt. If there are still undelivered recipients at the | |
35367 | end, the -H file is updated, and the -J file is deleted. If, however, there is | |
35368 | some kind of crash (for example, a power outage) before this happens, the -J | |
35369 | file remains in existence. When Exim next processes the message, it notices the | |
35370 | -J file and uses it to update the -H file before starting the next delivery | |
35371 | attempt. | |
35372 | ||
35373 | ||
2813c06e | 35374 | 56.1 Format of the -H file |
420a0d19 CE |
35375 | -------------------------- |
35376 | ||
35377 | The second line of the -H file contains the login name for the uid of the | |
35378 | process that called Exim to read the message, followed by the numerical uid and | |
35379 | gid. For a locally generated message, this is normally the user who sent the | |
35380 | message. For a message received over TCP/IP via the daemon, it is normally the | |
35381 | Exim user. | |
35382 | ||
35383 | The third line of the file contains the address of the message's sender as | |
35384 | transmitted in the envelope, contained in angle brackets. The sender address is | |
35385 | empty for bounce messages. For incoming SMTP mail, the sender address is given | |
35386 | in the MAIL command. For locally generated mail, the sender address is created | |
35387 | by Exim from the login name of the current user and the configured | |
35388 | qualify_domain. However, this can be overridden by the -f option or a leading | |
35389 | "From " line if the caller is trusted, or if the supplied address is "<>" or an | |
35390 | address that matches untrusted_set_senders. | |
35391 | ||
35392 | The fourth line contains two numbers. The first is the time that the message | |
35393 | was received, in the conventional Unix form - the number of seconds since the | |
35394 | start of the epoch. The second number is a count of the number of messages | |
35395 | warning of delayed delivery that have been sent to the sender. | |
35396 | ||
35397 | There follow a number of lines starting with a hyphen. These can appear in any | |
35398 | order, and are omitted when not relevant: | |
35399 | ||
35400 | -acl <number> <length> | |
35401 | ||
35402 | This item is obsolete, and is not generated from Exim release 4.61 onwards; | |
35403 | -aclc and -aclm are used instead. However, -acl is still recognized, to | |
35404 | provide backward compatibility. In the old format, a line of this form is | |
35405 | present for every ACL variable that is not empty. The number identifies the | |
35406 | variable; the acl_cx variables are numbered 0-9 and the acl_mx variables | |
35407 | are numbered 10-19. The length is the length of the data string for the | |
35408 | variable. The string itself starts at the beginning of the next line, and | |
35409 | is followed by a newline character. It may contain internal newlines. | |
35410 | ||
35411 | -aclc <rest-of-name> <length> | |
35412 | ||
35413 | A line of this form is present for every ACL connection variable that is | |
35414 | defined. Note that there is a space between -aclc and the rest of the name. | |
35415 | The length is the length of the data string for the variable. The string | |
35416 | itself starts at the beginning of the next line, and is followed by a | |
35417 | newline character. It may contain internal newlines. | |
35418 | ||
35419 | -aclm <rest-of-name> <length> | |
35420 | ||
35421 | A line of this form is present for every ACL message variable that is | |
35422 | defined. Note that there is a space between -aclm and the rest of the name. | |
35423 | The length is the length of the data string for the variable. The string | |
35424 | itself starts at the beginning of the next line, and is followed by a | |
35425 | newline character. It may contain internal newlines. | |
35426 | ||
35427 | -active_hostname <hostname> | |
35428 | ||
35429 | This is present if, when the message was received over SMTP, the value of | |
35430 | $smtp_active_hostname was different to the value of $primary_hostname. | |
35431 | ||
35432 | -allow_unqualified_recipient | |
35433 | ||
35434 | This is present if unqualified recipient addresses are permitted in header | |
35435 | lines (to stop such addresses from being qualified if rewriting occurs at | |
35436 | transport time). Local messages that were input using -bnq and remote | |
35437 | messages from hosts that match recipient_unqualified_hosts set this flag. | |
35438 | ||
35439 | -allow_unqualified_sender | |
35440 | ||
35441 | This is present if unqualified sender addresses are permitted in header | |
35442 | lines (to stop such addresses from being qualified if rewriting occurs at | |
35443 | transport time). Local messages that were input using -bnq and remote | |
35444 | messages from hosts that match sender_unqualified_hosts set this flag. | |
35445 | ||
35446 | -auth_id <text> | |
35447 | ||
35448 | The id information for a message received on an authenticated SMTP | |
35449 | connection - the value of the $authenticated_id variable. | |
35450 | ||
35451 | -auth_sender <address> | |
35452 | ||
35453 | The address of an authenticated sender - the value of the | |
35454 | $authenticated_sender variable. | |
35455 | ||
35456 | -body_linecount <number> | |
35457 | ||
35458 | This records the number of lines in the body of the message, and is always | |
35459 | present. | |
35460 | ||
35461 | -body_zerocount <number> | |
35462 | ||
35463 | This records the number of binary zero bytes in the body of the message, | |
35464 | and is present if the number is greater than zero. | |
35465 | ||
35466 | -deliver_firsttime | |
35467 | ||
35468 | This is written when a new message is first added to the spool. When the | |
35469 | spool file is updated after a deferral, it is omitted. | |
35470 | ||
35471 | -frozen <time> | |
35472 | ||
35473 | The message is frozen, and the freezing happened at <time>. | |
35474 | ||
35475 | -helo_name <text> | |
35476 | ||
35477 | This records the host name as specified by a remote host in a HELO or EHLO | |
35478 | command. | |
35479 | ||
35480 | -host_address <address>.<port> | |
35481 | ||
35482 | This records the IP address of the host from which the message was received | |
35483 | and the remote port number that was used. It is omitted for locally | |
35484 | generated messages. | |
35485 | ||
35486 | -host_auth <text> | |
35487 | ||
35488 | If the message was received on an authenticated SMTP connection, this | |
35489 | records the name of the authenticator - the value of the | |
35490 | $sender_host_authenticated variable. | |
35491 | ||
35492 | -host_lookup_failed | |
35493 | ||
35494 | This is present if an attempt to look up the sending host's name from its | |
35495 | IP address failed. It corresponds to the $host_lookup_failed variable. | |
35496 | ||
35497 | -host_name <text> | |
35498 | ||
35499 | This records the name of the remote host from which the message was | |
35500 | received, if the host name was looked up from the IP address when the | |
35501 | message was being received. It is not present if no reverse lookup was | |
35502 | done. | |
35503 | ||
35504 | -ident <text> | |
35505 | ||
35506 | For locally submitted messages, this records the login of the originating | |
35507 | user, unless it was a trusted user and the -oMt option was used to specify | |
35508 | an ident value. For messages received over TCP/IP, this records the ident | |
35509 | string supplied by the remote host, if any. | |
35510 | ||
35511 | -interface_address <address>.<port> | |
35512 | ||
35513 | This records the IP address of the local interface and the port number | |
35514 | through which a message was received from a remote host. It is omitted for | |
35515 | locally generated messages. | |
35516 | ||
35517 | -local | |
35518 | ||
35519 | The message is from a local sender. | |
35520 | ||
35521 | -localerror | |
35522 | ||
35523 | The message is a locally-generated bounce message. | |
35524 | ||
35525 | -local_scan <string> | |
35526 | ||
35527 | This records the data string that was returned by the local_scan() function | |
35528 | when the message was received - the value of the $local_scan_data variable. | |
35529 | It is omitted if no data was returned. | |
35530 | ||
35531 | -manual_thaw | |
35532 | ||
35533 | The message was frozen but has been thawed manually, that is, by an | |
35534 | explicit Exim command rather than via the auto-thaw process. | |
35535 | ||
35536 | -N | |
35537 | ||
35538 | A testing delivery process was started using the -N option to suppress any | |
35539 | actual deliveries, but delivery was deferred. At any further delivery | |
35540 | attempts, -N is assumed. | |
35541 | ||
35542 | -received_protocol | |
35543 | ||
35544 | This records the value of the $received_protocol variable, which contains | |
35545 | the name of the protocol by which the message was received. | |
35546 | ||
35547 | -sender_set_untrusted | |
35548 | ||
35549 | The envelope sender of this message was set by an untrusted local caller | |
35550 | (used to ensure that the caller is displayed in queue listings). | |
35551 | ||
35552 | -spam_score_int <number> | |
35553 | ||
35554 | If a message was scanned by SpamAssassin, this is present. It records the | |
35555 | value of $spam_score_int. | |
35556 | ||
35557 | -tls_certificate_verified | |
35558 | ||
35559 | A TLS certificate was received from the client that sent this message, and | |
35560 | the certificate was verified by the server. | |
35561 | ||
35562 | -tls_cipher <cipher name> | |
35563 | ||
35564 | When the message was received over an encrypted connection, this records | |
35565 | the name of the cipher suite that was used. | |
35566 | ||
35567 | -tls_peerdn <peer DN> | |
35568 | ||
35569 | When the message was received over an encrypted connection, and a | |
35570 | certificate was received from the client, this records the Distinguished | |
35571 | Name from that certificate. | |
35572 | ||
35573 | Following the options there is a list of those addresses to which the message | |
35574 | is not to be delivered. This set of addresses is initialized from the command | |
35575 | line when the -t option is used and extract_addresses_remove_arguments is set; | |
35576 | otherwise it starts out empty. Whenever a successful delivery is made, the | |
35577 | address is added to this set. The addresses are kept internally as a balanced | |
35578 | binary tree, and it is a representation of that tree which is written to the | |
35579 | spool file. If an address is expanded via an alias or forward file, the | |
35580 | original address is added to the tree when deliveries to all its child | |
35581 | addresses are complete. | |
35582 | ||
35583 | If the tree is empty, there is a single line in the spool file containing just | |
35584 | the text "XX". Otherwise, each line consists of two letters, which are either Y | |
35585 | or N, followed by an address. The address is the value for the node of the | |
35586 | tree, and the letters indicate whether the node has a left branch and/or a | |
35587 | right branch attached to it, respectively. If branches exist, they immediately | |
35588 | follow. Here is an example of a three-node tree: | |
35589 | ||
35590 | YY darcy@austen.fict.example | |
35591 | NN alice@wonderland.fict.example | |
35592 | NN editor@thesaurus.ref.example | |
35593 | ||
35594 | After the non-recipients tree, there is a list of the message's recipients. | |
35595 | This is a simple list, preceded by a count. It includes all the original | |
35596 | recipients of the message, including those to whom the message has already been | |
35597 | delivered. In the simplest case, the list contains one address per line. For | |
35598 | example: | |
35599 | ||
35600 | 4 | |
35601 | editor@thesaurus.ref.example | |
35602 | darcy@austen.fict.example | |
35603 | rdo@foundation | |
35604 | alice@wonderland.fict.example | |
35605 | ||
35606 | However, when a child address has been added to the top-level addresses as a | |
35607 | result of the use of the one_time option on a redirect router, each line is of | |
35608 | the following form: | |
35609 | ||
35610 | <top-level address> <errors_to address> <length>,<parent number>#<flag bits> | |
35611 | ||
35612 | The 01 flag bit indicates the presence of the three other fields that follow | |
35613 | the top-level address. Other bits may be used in future to support additional | |
35614 | fields. The <parent number> is the offset in the recipients list of the | |
35615 | original parent of the "one time" address. The first two fields are the | |
35616 | envelope sender that is associated with this address and its length. If the | |
35617 | length is zero, there is no special envelope sender (there are then two space | |
35618 | characters in the line). A non-empty field can arise from a redirect router | |
35619 | that has an errors_to setting. | |
35620 | ||
35621 | A blank line separates the envelope and status information from the headers | |
35622 | which follow. A header may occupy several lines of the file, and to save effort | |
35623 | when reading it in, each header is preceded by a number and an identifying | |
35624 | character. The number is the number of characters in the header, including any | |
35625 | embedded newlines and the terminating newline. The character is one of the | |
35626 | following: | |
35627 | ||
35628 | <blank> header in which Exim has no special interest | |
35629 | "B" Bcc: header | |
35630 | "C" Cc: header | |
35631 | "F" From: header | |
35632 | "I" Message-id: header | |
35633 | "P" Received: header - P for "postmark" | |
35634 | "R" Reply-To: header | |
35635 | "S" Sender: header | |
35636 | "T" To: header | |
35637 | "*" replaced or deleted header | |
35638 | ||
35639 | Deleted or replaced (rewritten) headers remain in the spool file for debugging | |
35640 | purposes. They are not transmitted when the message is delivered. Here is a | |
35641 | typical set of headers: | |
35642 | ||
35643 | 111P Received: by hobbit.fict.example with local (Exim 4.00) | |
35644 | id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100 | |
35645 | 049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example> | |
35646 | 038* X-rewrote-sender: bb@hobbit.fict.example | |
35647 | 042* From: Bilbo Baggins <bb@hobbit.fict.example> | |
35648 | 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example> | |
35649 | 099* To: alice@wonderland.fict.example, rdo@foundation, | |
35650 | darcy@austen.fict.example, editor@thesaurus.ref.example | |
35651 | 104T To: alice@wonderland.fict.example, rdo@foundation.example, | |
35652 | darcy@austen.fict.example, editor@thesaurus.ref.example | |
35653 | 038 Date: Fri, 11 May 2001 10:28:59 +0100 | |
35654 | ||
35655 | The asterisked headers indicate that the envelope sender, From: header, and To: | |
35656 | header have been rewritten, the last one because routing expanded the | |
35657 | unqualified domain foundation. | |
35658 | ||
35659 | ||
35660 | ||
35661 | =============================================================================== | |
2813c06e | 35662 | 57. SUPPORT FOR DKIM (DOMAINKEYS IDENTIFIED MAIL) |
420a0d19 CE |
35663 | |
35664 | DKIM is a mechanism by which messages sent by some entity can be provably | |
35665 | linked to a domain which that entity controls. It permits reputation to be | |
35666 | tracked on a per-domain basis, rather than merely upon source IP address. DKIM | |
35667 | is documented in RFC 4871. | |
35668 | ||
2813c06e CE |
35669 | DKIM support is compiled into Exim by default if TLS support is present. It can |
35670 | be disabled by setting DISABLE_DKIM=yes in Local/Makefile. | |
420a0d19 | 35671 | |
2813c06e | 35672 | Exim's DKIM implementation allows for |
420a0d19 | 35673 | |
2813c06e CE |
35674 | 1. Signing outgoing messages: This function is implemented in the SMTP |
35675 | transport. It can co-exist with all other Exim features (including | |
35676 | transport filters) except cutthrough delivery. | |
420a0d19 | 35677 | |
2813c06e | 35678 | 2. Verifying signatures in incoming messages: This is implemented by an |
420a0d19 CE |
35679 | additional ACL (acl_smtp_dkim), which can be called several times per |
35680 | message, with different signature contexts. | |
35681 | ||
35682 | In typical Exim style, the verification implementation does not include any | |
35683 | default "policy". Instead it enables you to build your own policy using Exim's | |
35684 | standard controls. | |
35685 | ||
35686 | Please note that verification of DKIM signatures in incoming mail is turned on | |
35687 | by default for logging purposes. For each signature in incoming email, exim | |
35688 | will log a line displaying the most important signature details, and the | |
35689 | signature status. Here is an example (with line-breaks added for clarity): | |
35690 | ||
35691 | 2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM: | |
35692 | d=facebookmail.com s=q1-2009b | |
35693 | c=relaxed/relaxed a=rsa-sha1 | |
35694 | i=@facebookmail.com t=1252484542 [verification succeeded] | |
35695 | ||
35696 | You might want to turn off DKIM verification processing entirely for internal | |
35697 | or relay mail sources. To do that, set the dkim_disable_verify ACL control | |
35698 | modifier. This should typically be done in the RCPT ACL, at points where you | |
35699 | accept mail from relay sources (internal hosts or authenticated senders). | |
35700 | ||
35701 | ||
2813c06e | 35702 | 57.1 Signing outgoing messages |
420a0d19 CE |
35703 | ------------------------------ |
35704 | ||
2813c06e | 35705 | Signing is enabled by setting private options on the SMTP transport. These |
420a0d19 CE |
35706 | options take (expandable) strings as arguments. |
35707 | ||
2813c06e | 35708 | +--------------------------------------------------+ |
420a0d19 | 35709 | |dkim_domain|Use: smtp|Type: string*|Default: unset| |
2813c06e | 35710 | +--------------------------------------------------+ |
420a0d19 CE |
35711 | |
35712 | MANDATORY: The domain you want to sign with. The result of this expanded option | |
2813c06e CE |
35713 | is put into the $dkim_domain expansion variable. If it is empty after |
35714 | expansion, DKIM signing is not done. | |
420a0d19 | 35715 | |
2813c06e | 35716 | +----------------------------------------------------+ |
420a0d19 | 35717 | |dkim_selector|Use: smtp|Type: string*|Default: unset| |
2813c06e | 35718 | +----------------------------------------------------+ |
420a0d19 CE |
35719 | |
35720 | MANDATORY: This sets the key selector string. You can use the $dkim_domain | |
35721 | expansion variable to look up a matching selector. The result is put in the | |
2813c06e | 35722 | expansion variable $dkim_selector which may be used in the dkim_private_key |
420a0d19 CE |
35723 | option along with $dkim_domain. |
35724 | ||
2813c06e | 35725 | +-------------------------------------------------------+ |
420a0d19 | 35726 | |dkim_private_key|Use: smtp|Type: string*|Default: unset| |
2813c06e | 35727 | +-------------------------------------------------------+ |
420a0d19 CE |
35728 | |
35729 | MANDATORY: This sets the private key to use. You can use the $dkim_domain and | |
35730 | $dkim_selector expansion variables to determine the private key to use. The | |
35731 | result can either | |
35732 | ||
35733 | * be a valid RSA private key in ASCII armor, including line breaks. | |
35734 | ||
35735 | * start with a slash, in which case it is treated as a file that contains the | |
35736 | private key. | |
35737 | ||
35738 | * be "0", "false" or the empty string, in which case the message will not be | |
35739 | signed. This case will not result in an error, even if dkim_strict is set. | |
35740 | ||
2813c06e | 35741 | +-------------------------------------------------+ |
420a0d19 | 35742 | |dkim_canon|Use: smtp|Type: string*|Default: unset| |
2813c06e | 35743 | +-------------------------------------------------+ |
420a0d19 CE |
35744 | |
35745 | OPTIONAL: This option sets the canonicalization method used when signing a | |
35746 | message. The DKIM RFC currently supports two methods: "simple" and "relaxed". | |
35747 | The option defaults to "relaxed" when unset. Note: the current implementation | |
35748 | only supports using the same canonicalization method for both headers and body. | |
35749 | ||
2813c06e | 35750 | +--------------------------------------------------+ |
420a0d19 | 35751 | |dkim_strict|Use: smtp|Type: string*|Default: unset| |
2813c06e | 35752 | +--------------------------------------------------+ |
420a0d19 CE |
35753 | |
35754 | OPTIONAL: This option defines how Exim behaves when signing a message that | |
35755 | should be signed fails for some reason. When the expansion evaluates to either | |
35756 | "1" or "true", Exim will defer. Otherwise Exim will send the message unsigned. | |
35757 | You can use the $dkim_domain and $dkim_selector expansion variables here. | |
35758 | ||
2813c06e | 35759 | +--------------------------------------------------------+ |
420a0d19 | 35760 | |dkim_sign_headers|Use: smtp|Type: string*|Default: unset| |
2813c06e | 35761 | +--------------------------------------------------------+ |
420a0d19 CE |
35762 | |
35763 | OPTIONAL: When set, this option must expand to (or be specified as) a | |
35764 | colon-separated list of header names. Headers with these names will be included | |
35765 | in the message signature. When unspecified, the header names recommended in | |
35766 | RFC4871 will be used. | |
35767 | ||
35768 | ||
2813c06e | 35769 | 57.2 Verifying DKIM signatures in incoming mail |
420a0d19 CE |
35770 | ----------------------------------------------- |
35771 | ||
2813c06e | 35772 | Verification of DKIM signatures in SMTP incoming email is implemented via the |
420a0d19 CE |
35773 | acl_smtp_dkim ACL. By default, this ACL is called once for each syntactically |
35774 | (!) correct signature in the incoming message. A missing ACL definition | |
2813c06e | 35775 | defaults to accept. If any ACL call does not accept, the message is not |
420a0d19 CE |
35776 | accepted. If a cutthrough delivery was in progress for the message it is |
35777 | summarily dropped (having wasted the transmission effort). | |
35778 | ||
35779 | To evaluate the signature in the ACL a large number of expansion variables | |
35780 | containing the signature status and its details are set up during the runtime | |
35781 | of the ACL. | |
35782 | ||
35783 | Calling the ACL only for existing signatures is not sufficient to build more | |
35784 | advanced policies. For that reason, the global option dkim_verify_signers, and | |
35785 | a global expansion variable $dkim_signers exist. | |
35786 | ||
35787 | The global option dkim_verify_signers can be set to a colon-separated list of | |
35788 | DKIM domains or identities for which the ACL acl_smtp_dkim is called. It is | |
35789 | expanded when the message has been received. At this point, the expansion | |
35790 | variable $dkim_signers already contains a colon-separated list of signer | |
35791 | domains and identities for the message. When dkim_verify_signers is not | |
35792 | specified in the main configuration, it defaults as: | |
35793 | ||
35794 | dkim_verify_signers = $dkim_signers | |
35795 | ||
35796 | This leads to the default behaviour of calling acl_smtp_dkim for each DKIM | |
35797 | signature in the message. Current DKIM verifiers may want to explicitly call | |
35798 | the ACL for known domains or identities. This would be achieved as follows: | |
35799 | ||
35800 | dkim_verify_signers = paypal.com:ebay.com:$dkim_signers | |
35801 | ||
35802 | This would result in acl_smtp_dkim always being called for "paypal.com" and | |
35803 | "ebay.com", plus all domains and identities that have signatures in the | |
35804 | message. You can also be more creative in constructing your policy. For | |
35805 | example: | |
35806 | ||
35807 | dkim_verify_signers = $sender_address_domain:$dkim_signers | |
35808 | ||
35809 | If a domain or identity is listed several times in the (expanded) value of | |
35810 | dkim_verify_signers, the ACL is only called once for that domain or identity. | |
35811 | ||
35812 | Inside the acl_smtp_dkim, the following expansion variables are available (from | |
35813 | most to least important): | |
35814 | ||
35815 | $dkim_cur_signer | |
35816 | ||
35817 | The signer that is being evaluated in this ACL run. This can be a domain or | |
35818 | an identity. This is one of the list items from the expanded main option | |
35819 | dkim_verify_signers (see above). | |
35820 | ||
35821 | $dkim_verify_status | |
35822 | ||
35823 | A string describing the general status of the signature. One of | |
35824 | ||
2813c06e | 35825 | + none: There is no signature in the message for the current domain or |
420a0d19 CE |
35826 | identity (as reflected by $dkim_cur_signer). |
35827 | ||
2813c06e | 35828 | + invalid: The signature could not be verified due to a processing error. |
420a0d19 CE |
35829 | More detail is available in $dkim_verify_reason. |
35830 | ||
2813c06e | 35831 | + fail: Verification of the signature failed. More detail is available in |
420a0d19 CE |
35832 | $dkim_verify_reason. |
35833 | ||
2813c06e | 35834 | + pass: The signature passed verification. It is valid. |
420a0d19 CE |
35835 | |
35836 | $dkim_verify_reason | |
35837 | ||
2813c06e | 35838 | A string giving a little bit more detail when $dkim_verify_status is either |
420a0d19 CE |
35839 | "fail" or "invalid". One of |
35840 | ||
2813c06e | 35841 | + pubkey_unavailable (when $dkim_verify_status="invalid"): The public key |
420a0d19 CE |
35842 | for the domain could not be retrieved. This may be a temporary problem. |
35843 | ||
2813c06e | 35844 | + pubkey_syntax (when $dkim_verify_status="invalid"): The public key |
420a0d19 CE |
35845 | record for the domain is syntactically invalid. |
35846 | ||
2813c06e | 35847 | + bodyhash_mismatch (when $dkim_verify_status="fail"): The calculated |
420a0d19 CE |
35848 | body hash does not match the one specified in the signature header. |
35849 | This means that the message body was modified in transit. | |
35850 | ||
2813c06e | 35851 | + signature_incorrect (when $dkim_verify_status="fail"): The signature |
420a0d19 CE |
35852 | could not be verified. This may mean that headers were modified, |
35853 | re-written or otherwise changed in a way which is incompatible with | |
35854 | DKIM verification. It may of course also mean that the signature is | |
35855 | forged. | |
35856 | ||
35857 | $dkim_domain | |
35858 | ||
35859 | The signing domain. IMPORTANT: This variable is only populated if there is | |
35860 | an actual signature in the message for the current domain or identity (as | |
35861 | reflected by $dkim_cur_signer). | |
35862 | ||
35863 | $dkim_identity | |
35864 | ||
35865 | The signing identity, if present. IMPORTANT: This variable is only | |
35866 | populated if there is an actual signature in the message for the current | |
35867 | domain or identity (as reflected by $dkim_cur_signer). | |
35868 | ||
35869 | $dkim_selector | |
35870 | ||
35871 | The key record selector string. | |
35872 | ||
35873 | $dkim_algo | |
35874 | ||
35875 | The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'. | |
35876 | ||
35877 | $dkim_canon_body | |
35878 | ||
35879 | The body canonicalization method. One of 'relaxed' or 'simple'. | |
35880 | ||
35881 | dkim_canon_headers | |
35882 | ||
35883 | The header canonicalization method. One of 'relaxed' or 'simple'. | |
35884 | ||
35885 | $dkim_copiedheaders | |
35886 | ||
35887 | A transcript of headers and their values which are included in the | |
2813c06e CE |
35888 | signature (copied from the 'z=' tag of the signature). Note that RFC6376 |
35889 | requires that verification fail if the From: header is not included in the | |
35890 | signature. Exim does not enforce this; sites wishing strict enforcement | |
35891 | should code the check explicitly. | |
420a0d19 CE |
35892 | |
35893 | $dkim_bodylength | |
35894 | ||
35895 | The number of signed body bytes. If zero ("0"), the body is unsigned. If no | |
35896 | limit was set by the signer, "9999999999999" is returned. This makes sure | |
35897 | that this variable always expands to an integer value. | |
35898 | ||
35899 | $dkim_created | |
35900 | ||
35901 | UNIX timestamp reflecting the date and time when the signature was created. | |
35902 | When this was not specified by the signer, "0" is returned. | |
35903 | ||
35904 | $dkim_expires | |
35905 | ||
35906 | UNIX timestamp reflecting the date and time when the signer wants the | |
35907 | signature to be treated as "expired". When this was not specified by the | |
35908 | signer, "9999999999999" is returned. This makes it possible to do useful | |
35909 | integer size comparisons against this value. | |
35910 | ||
35911 | $dkim_headernames | |
35912 | ||
35913 | A colon-separated list of names of headers included in the signature. | |
35914 | ||
35915 | $dkim_key_testing | |
35916 | ||
35917 | "1" if the key record has the "testing" flag set, "0" if not. | |
35918 | ||
35919 | $dkim_key_nosubdomains | |
35920 | ||
35921 | "1" if the key record forbids subdomaining, "0" otherwise. | |
35922 | ||
35923 | $dkim_key_srvtype | |
35924 | ||
35925 | Service type (tag s=) from the key record. Defaults to "*" if not specified | |
35926 | in the key record. | |
35927 | ||
35928 | $dkim_key_granularity | |
35929 | ||
35930 | Key granularity (tag g=) from the key record. Defaults to "*" if not | |
35931 | specified in the key record. | |
35932 | ||
35933 | $dkim_key_notes | |
35934 | ||
35935 | Notes from the key record (tag n=). | |
35936 | ||
2813c06e CE |
35937 | $dkim_key_length |
35938 | ||
35939 | Number of bits in the key. | |
35940 | ||
420a0d19 CE |
35941 | In addition, two ACL conditions are provided: |
35942 | ||
35943 | dkim_signers | |
35944 | ||
35945 | ACL condition that checks a colon-separated list of domains or identities | |
35946 | for a match against the domain or identity that the ACL is currently | |
35947 | verifying (reflected by $dkim_cur_signer). This is typically used to | |
35948 | restrict an ACL verb to a group of domains or identities. For example: | |
35949 | ||
2813c06e CE |
35950 | # Warn when Mail purportedly from GMail has no gmail signature |
35951 | warn log_message = GMail sender without gmail.com DKIM signature | |
420a0d19 CE |
35952 | sender_domains = gmail.com |
35953 | dkim_signers = gmail.com | |
35954 | dkim_status = none | |
35955 | ||
2813c06e CE |
35956 | Note that the above does not check for a total lack of DKIM signing; for |
35957 | that check for empty $h_DKIM-Signature: in the data ACL. | |
35958 | ||
420a0d19 CE |
35959 | dkim_status |
35960 | ||
35961 | ACL condition that checks a colon-separated list of possible DKIM | |
35962 | verification results against the actual result of verification. This is | |
35963 | typically used to restrict an ACL verb to a list of verification outcomes, | |
35964 | for example: | |
35965 | ||
35966 | deny message = Mail from Paypal with invalid/missing signature | |
35967 | sender_domains = paypal.com:paypal.de | |
35968 | dkim_signers = paypal.com:paypal.de | |
35969 | dkim_status = none:invalid:fail | |
35970 | ||
35971 | The possible status keywords are: 'none','invalid','fail' and 'pass'. | |
35972 | Please see the documentation of the $dkim_verify_status expansion variable | |
35973 | above for more information of what they mean. | |
35974 | ||
35975 | ||
35976 | ||
35977 | =============================================================================== | |
2813c06e CE |
35978 | 58. PROXIES |
35979 | ||
35980 | A proxy is an intermediate system through which communication is passed. | |
35981 | Proxies may provide a security, availability or load-distribution function. | |
35982 | ||
35983 | ||
35984 | 58.1 Inbound proxies | |
35985 | -------------------- | |
35986 | ||
35987 | Exim has support for receiving inbound SMTP connections via a proxy that uses | |
35988 | "Proxy Protocol" to speak to it. To include this support, include | |
35989 | "SUPPORT_PROXY=yes" in Local/Makefile. | |
35990 | ||
35991 | It was built on specifications from: (http://haproxy.1wt.eu/download/1.5/doc/ | |
35992 | proxy-protocol.txt). That URL was revised in May 2014 to version 2 spec: (http: | |
35993 | //git.1wt.eu/web?p=haproxy.git;a=commitdiff;h=afb768340c9d7e50d8e). | |
35994 | ||
35995 | The purpose of this facility is so that an application load balancer, such as | |
35996 | HAProxy, can sit in front of several Exim servers to distribute load. Exim uses | |
35997 | the local protocol communication with the proxy to obtain the remote SMTP | |
35998 | system IP address and port information. There is no logging if a host passes or | |
35999 | fails Proxy Protocol negotiation, but it can easily be determined and recorded | |
36000 | in an ACL (example is below). | |
36001 | ||
36002 | Use of a proxy is enabled by setting the hosts_proxy main configuration option | |
36003 | to a hostlist; connections from these hosts will use Proxy Protocol. Exim | |
36004 | supports both version 1 and version 2 of the Proxy Protocol and automatically | |
36005 | determines which version is in use. | |
36006 | ||
36007 | The Proxy Protocol header is the first data received on a TCP connection and is | |
36008 | inserted before any TLS-on-connect handshake from the client; Exim negotiates | |
36009 | TLS between Exim-as-server and the remote client, not between Exim and the | |
36010 | proxy server. | |
36011 | ||
36012 | The following expansion variables are usable ("internal" and "external" here | |
36013 | refer to the interfaces of the proxy): | |
36014 | ||
36015 | proxy_external_address | |
36016 | IP of host being proxied or IP of remote interface of proxy | |
36017 | proxy_external_port | |
36018 | Port of host being proxied or Port on remote interface of proxy | |
36019 | proxy_local_address | |
36020 | IP of proxy server inbound or IP of local interface of proxy | |
36021 | proxy_local_port | |
36022 | Port of proxy server inbound or Port on local interface of proxy | |
36023 | proxy_session boolean: SMTP connection via proxy | |
36024 | ||
36025 | If $proxy_session is set but $proxy_external_address is empty there was a | |
36026 | protocol error. | |
36027 | ||
36028 | Since the real connections are all coming from the proxy, and the per host | |
36029 | connection tracking is done before Proxy Protocol is evaluated, | |
36030 | smtp_accept_max_per_host must be set high enough to handle all of the parallel | |
36031 | volume you expect per inbound proxy. With the option set so high, you lose the | |
36032 | ability to protect your server from many connections from one IP. In order to | |
36033 | prevent your server from overload, you need to add a per connection ratelimit | |
36034 | to your connect ACL. A possible solution is: | |
36035 | ||
36036 | # Set max number of connections per host | |
36037 | LIMIT = 5 | |
36038 | # Or do some kind of IP lookup in a flat file or database | |
36039 | # LIMIT = ${lookup{$sender_host_address}iplsearch{/etc/exim/proxy_limits}} | |
36040 | ||
36041 | defer message = Too many connections from this IP right now | |
36042 | ratelimit = LIMIT / 5s / per_conn / strict | |
36043 | ||
36044 | ||
36045 | 58.2 Outbound proxies | |
36046 | --------------------- | |
36047 | ||
36048 | Exim has support for sending outbound SMTP via a proxy using a protocol called | |
36049 | SOCKS5 (defined by RFC1928). The support can be optionally included by defining | |
36050 | SUPPORT_SOCKS=yes in Local/Makefile. | |
36051 | ||
36052 | Use of a proxy is enabled by setting the socks_proxy option on an smtp | |
36053 | transport. The option value is expanded and should then be a list | |
36054 | (colon-separated by default) of proxy specifiers. Each proxy specifier is a | |
36055 | list (space-separated by default) where the initial element is an IP address | |
36056 | and any subsequent elements are options. | |
36057 | ||
36058 | Options are a string <name>=<value>. The list of options is in the following | |
36059 | table: | |
36060 | ||
36061 | auth authentication method | |
36062 | name authentication username | |
36063 | pass authentication password | |
36064 | port tcp port | |
36065 | tmo connection timeout | |
36066 | pri priority | |
36067 | weight selection bias | |
36068 | ||
36069 | More details on each of these options follows: | |
36070 | ||
36071 | * auth: Either "none" (default) or "name". Using "name" selects username/ | |
36072 | password authentication per RFC 1929 for access to the proxy. Default is | |
36073 | "none". | |
36074 | ||
36075 | * name: sets the username for the "name" authentication method. Default is | |
36076 | empty. | |
36077 | ||
36078 | * pass: sets the password for the "name" authentication method. Default is | |
36079 | empty. | |
36080 | ||
36081 | * port: the TCP port number to use for the connection to the proxy. Default | |
36082 | is 1080. | |
36083 | ||
36084 | * tmo: sets a connection timeout in seconds for this proxy. Default is 5. | |
36085 | ||
36086 | * pri: specifies a priority for the proxy within the list, higher values | |
36087 | being tried first. The default priority is 1. | |
36088 | ||
36089 | * weight: specifies a selection bias. Within a priority set servers are | |
36090 | queried in a random fashion, weighted by this value. The default value for | |
36091 | selection bias is 1. | |
36092 | ||
36093 | Proxies from the list are tried according to their priority and weight settings | |
36094 | until one responds. The timeout for the overall connection applies to the set | |
36095 | of proxied attempts. | |
36096 | ||
36097 | ||
36098 | 58.3 Logging | |
36099 | ------------ | |
36100 | ||
36101 | To log the (local) IP of a proxy in the incoming or delivery logline, add | |
36102 | "+proxy" to the log_selector option. This will add a component tagged with "PRX | |
36103 | =" to the line. | |
36104 | ||
36105 | ||
36106 | ||
36107 | =============================================================================== | |
36108 | 59. INTERNATIONALISATION | |
36109 | ||
36110 | Exim has support for Internationalised mail names. To include this it must be | |
36111 | built with SUPPORT_I18N and the libidn library. Standards supported are RFCs | |
36112 | 2060, 5890, 6530 and 6533. | |
36113 | ||
36114 | If Exim is built with SUPPORT_I18N_2008 (in addition to SUPPORT_I18N, not | |
36115 | instead of it) then IDNA2008 is supported; this adds an extra library | |
36116 | requirement, upon libidn2. | |
36117 | ||
36118 | ||
36119 | 59.1 MTA operations | |
36120 | ------------------- | |
36121 | ||
36122 | The main configuration option smtputf8_advertise_hosts specifies a host list. | |
36123 | If this matches the sending host and accept_8bitmime is true (the default) then | |
36124 | the ESMTP option SMTPUTF8 will be advertised. | |
36125 | ||
36126 | If the sender specifies the SMTPUTF8 option on a MAIL command international | |
36127 | handling for the message is enabled and the expansion variable | |
36128 | $message_smtputf8 will have value TRUE. | |
36129 | ||
36130 | The option allow_utf8_domains is set to true for this message. All DNS lookups | |
36131 | are converted to a-label form whatever the setting of allow_utf8_domains when | |
36132 | Exim is built with SUPPORT_I18N. | |
36133 | ||
36134 | Both localparts and domain are maintained as the original UTF-8 form | |
36135 | internally; any comparison or regular-expression use will require appropriate | |
36136 | care. Filenames created, eg. by the appendfile transport, will have UTF-8 | |
36137 | names. | |
36138 | ||
36139 | HELO names sent by the smtp transport will have any UTF-8 components expanded | |
36140 | to a-label form, and any certificate name checks will be done using the a-label | |
36141 | form of the name. | |
36142 | ||
36143 | Log lines and Received-by: header lines will acquire a "utf8" prefix on the | |
36144 | protocol element, eg. utf8esmtp. | |
36145 | ||
36146 | The following expansion operators can be used: | |
36147 | ||
36148 | ${utf8_domain_to_alabel:str} | |
36149 | ${utf8_domain_from_alabel:str} | |
36150 | ${utf8_localpart_to_alabel:str} | |
36151 | ${utf8_localpart_from_alabel:str} | |
36152 | ||
36153 | ACLs may use the following modifier: | |
36154 | ||
36155 | control = utf8_downconvert | |
36156 | control = utf8_downconvert/<value> | |
36157 | ||
36158 | This sets a flag requiring that addresses are converted to a-label form before | |
36159 | smtp delivery, for use in a Message Submission Agent context. If a value is | |
36160 | appended it may be: | |
36161 | ||
36162 | 1 (default) mandatory downconversion | |
36163 | 0 no downconversion | |
36164 | -1 if SMTPUTF8 not supported by destination host | |
36165 | ||
36166 | If mua_wrapper is set, the utf8_downconvert control is initially set to -1. | |
36167 | ||
36168 | There is no explicit support for VRFY and EXPN. Configurations supporting these | |
36169 | should inspect $smtp_command_argument for an SMTPUTF8 argument. | |
36170 | ||
36171 | There is no support for LMTP on Unix sockets. Using the "lmtp" protocol option | |
36172 | on an smtp transport, for LMTP over TCP, should work as expected. | |
36173 | ||
36174 | There is no support for DSN unitext handling, and no provision for converting | |
36175 | logging from or to UTF-8. | |
36176 | ||
36177 | ||
36178 | 59.2 MDA operations | |
36179 | ------------------- | |
36180 | ||
36181 | To aid in constructing names suitable for IMAP folders the following expansion | |
36182 | operator can be used: | |
36183 | ||
36184 | ${imapfolder {<string>} {<sep>} {<specials>}} | |
36185 | ||
36186 | The string is converted from the charset specified by the "headers charset" | |
36187 | command (in a filter file) or headers_charset main configuration option | |
36188 | (otherwise), to the modified UTF-7 encoding specified by RFC 2060, with the | |
36189 | following exception: All occurences of <sep> (which has to be a single | |
36190 | character) are replaced with periods ("."), and all periods and slashes that | |
36191 | are not <sep> and are not in the <specials> string are BASE64 encoded. | |
36192 | ||
36193 | The third argument can be omitted, defaulting to an empty string. The second | |
36194 | argument can be omitted, defaulting to "/". | |
36195 | ||
36196 | This is the encoding used by Courier for Maildir names on disk, and followed by | |
36197 | many other IMAP servers. | |
36198 | ||
36199 | Examples: | |
36200 | ||
36201 | ${imapfolder {Foo/Bar}} yields Foo.Bar | |
36202 | ${imapfolder {Foo/Bar}{.}{/}} yields Foo&AC8-Bar | |
36203 | ${imapfolder {R?ksm?rg?s}} yields R&AOQ-ksm&APY-rg&AOU-s | |
36204 | ||
36205 | Note that the source charset setting is vital, and also that characters must be | |
36206 | representable in UTF-16. | |
36207 | ||
36208 | ||
36209 | ||
36210 | =============================================================================== | |
36211 | 60. EVENTS | |
36212 | ||
36213 | The events mechanism in Exim can be used to intercept processing at a number of | |
36214 | points. It was originally invented to give a way to do customised logging | |
36215 | actions (for example, to a database) but can also be used to modify some | |
36216 | processing actions. | |
36217 | ||
36218 | Most installations will never need to use Events. The support can be left out | |
36219 | of a build by defining DISABLE_EVENT=yes in Local/Makefile. | |
36220 | ||
36221 | There are two major classes of events: main and transport. The main | |
36222 | configuration option event_action controls reception events; a transport option | |
36223 | event_action controls delivery events. | |
36224 | ||
36225 | Both options are a string which is expanded when the event fires. An example | |
36226 | might look like: | |
36227 | ||
36228 | event_action = ${if eq {msg:delivery}{$event_name} \ | |
36229 | {${lookup pgsql {SELECT * FROM record_Delivery( \ | |
36230 | '${quote_pgsql:$sender_address_domain}',\ | |
36231 | '${quote_pgsql:${lc:$sender_address_local_part}}', \ | |
36232 | '${quote_pgsql:$domain}', \ | |
36233 | '${quote_pgsql:${lc:$local_part}}', \ | |
36234 | '${quote_pgsql:$host_address}', \ | |
36235 | '${quote_pgsql:${lc:$host}}', \ | |
36236 | '${quote_pgsql:$message_exim_id}')}} \ | |
36237 | } {}} | |
36238 | ||
36239 | Events have names which correspond to the point in process at which they fire. | |
36240 | The name is placed in the variable $event_name and the event action expansion | |
36241 | must check this, as it will be called for every possible event type. | |
36242 | ||
36243 | The current list of events is: | |
36244 | ||
36245 | msg:complete after main per message | |
36246 | msg:delivery after transport per recipient | |
36247 | msg:rcpt:host:defer after transport per recipient per host | |
36248 | msg:rcpt:defer after transport per recipient | |
36249 | msg:host:defer after transport per attempt | |
36250 | msg:fail:delivery after main per recipient | |
36251 | msg:fail:internal after main per recipient | |
36252 | tcp:connect before transport per connection | |
36253 | tcp:close after transport per connection | |
36254 | tls:cert before both per certificate in verification chain | |
36255 | smtp:connect after transport per connection | |
36256 | ||
36257 | New event types may be added in future. | |
36258 | ||
36259 | The event name is a colon-separated list, defining the type of event in a tree | |
36260 | of possibilities. It may be used as a list or just matched on as a whole. There | |
36261 | will be no spaces in the name. | |
36262 | ||
36263 | The second column in the table above describes whether the event fires before | |
36264 | or after the action is associates with. Those which fire before can be used to | |
36265 | affect that action (more on this below). | |
36266 | ||
36267 | An additional variable, $event_data, is filled with information varying with | |
36268 | the event type: | |
36269 | ||
36270 | msg:delivery smtp confirmation message | |
36271 | msg:rcpt:host:defer error string | |
36272 | msg:rcpt:defer error string | |
36273 | msg:host:defer error string | |
36274 | tls:cert verification chain depth | |
36275 | smtp:connect smtp banner | |
36276 | ||
36277 | The :defer events populate one extra variable: $event_defer_errno. | |
36278 | ||
36279 | For complex operations an ACL expansion can be used in event_action however due | |
36280 | to the multiple contexts that Exim operates in during the course of its | |
36281 | processing: | |
36282 | ||
36283 | * variables set in transport events will not be visible outside that | |
36284 | transport call | |
36285 | ||
36286 | * acl_m variables in a server context are lost on a new connection, and after | |
36287 | smtp helo/ehlo/mail/starttls/rset commands | |
36288 | ||
36289 | Using an ACL expansion with the logwrite modifier can be a useful way of | |
36290 | writing to the main log. | |
36291 | ||
36292 | The expansion of the event_action option should normally return an empty | |
36293 | string. Should it return anything else the following will be forced: | |
36294 | ||
36295 | msg:delivery (ignored) | |
36296 | msg:host:defer (ignored) | |
36297 | msg:fail:delivery (ignored) | |
36298 | tcp:connect do not connect | |
36299 | tcp:close (ignored) | |
36300 | tls:cert refuse verification | |
36301 | smtp:connect close connection | |
36302 | ||
36303 | No other use is made of the result string. | |
36304 | ||
36305 | For a tcp:connect event, if the connection is being made to a proxy then the | |
36306 | address and port variables will be that of the proxy and not the target system. | |
36307 | ||
36308 | For tls:cert events, if GnuTLS is in use this will trigger only per chain | |
36309 | element received on the connection. For OpenSSL it will trigger for every chain | |
36310 | element including those loaded locally. | |
36311 | ||
36312 | ||
36313 | ||
36314 | =============================================================================== | |
36315 | 61. ADDING NEW DRIVERS OR LOOKUP TYPES | |
420a0d19 CE |
36316 | |
36317 | The following actions have to be taken in order to add a new router, transport, | |
36318 | authenticator, or lookup type to Exim: | |
36319 | ||
36320 | 1. Choose a name for the driver or lookup type that does not conflict with any | |
36321 | existing name; I will use "newdriver" in what follows. | |
36322 | ||
36323 | 2. Add to src/EDITME the line: | |
36324 | ||
36325 | <type>_NEWDRIVER=yes | |
36326 | ||
36327 | where <type> is ROUTER, TRANSPORT, AUTH, or LOOKUP. If the code is not to | |
36328 | be included in the binary by default, comment this line out. You should | |
36329 | also add any relevant comments about the driver or lookup type. | |
36330 | ||
36331 | 3. Add to src/config.h.defaults the line: | |
36332 | ||
36333 | #define <type>_NEWDRIVER | |
36334 | ||
36335 | 4. Edit src/drtables.c, adding conditional code to pull in the private header | |
36336 | and create a table entry as is done for all the other drivers and lookup | |
36337 | types. | |
36338 | ||
36339 | 5. Edit scripts/lookups-Makefile if this is a new lookup; there is a for-loop | |
36340 | near the bottom, ranging the "name_mod" variable over a list of all | |
36341 | lookups. Add your "NEWDRIVER" to that list. As long as the dynamic module | |
36342 | would be named newdriver.so, you can use the simple form that most lookups | |
36343 | have. | |
36344 | ||
36345 | 6. Edit Makefile in the appropriate sub-directory (src/routers, src/transports | |
36346 | , src/auths, or src/lookups); add a line for the new driver or lookup type | |
36347 | and add it to the definition of OBJ. | |
36348 | ||
36349 | 7. Create newdriver.h and newdriver.c in the appropriate sub-directory of src. | |
36350 | ||
36351 | 8. Edit scripts/MakeLinks and add commands to link the .h and .c files as for | |
36352 | other drivers and lookups. | |
36353 | ||
36354 | Then all you need to do is write the code! A good way to start is to make a | |
36355 | proforma by copying an existing module of the same type, globally changing all | |
36356 | occurrences of the name, and cutting out most of the code. Note that any | |
36357 | options you create must be listed in alphabetical order, because the tables are | |
36358 | searched using a binary chop procedure. | |
36359 | ||
36360 | There is a README file in each of the sub-directories of src describing the | |
36361 | interface that is expected. | |
36362 |